Skip to content

plugin-spec.md

Latest commit

 

History

History
42 lines (34 loc) · 2.88 KB

plugin-spec.md

File metadata and controls

42 lines (34 loc) · 2.88 KB
Raw

Plugin spec (CONTRACT)

A plugin is a folder: plugin.json + data files, in a project's plugins/ or installed from URL/git. The studio validates on install, shows measured cost, and lets the user opt it into any workflow. Changes only with a written, measured change note.

plugin.json

{
  "name": "uk-brands",             // kebab-case, unique per project
  "version": "1.0.0",              // semver
  "license": "MIT",                // SPDX id or "proprietary"
  "kind": "wordlist",              // one of the kinds below
  "description": "one line",
  "provides": ["tags.brand"],      // catalogue feature ids this plugin produces
  "requires": [],                  // features that must be in the pack for provides to work
  "data": { }                      // kind-specific, below
}

Kinds and data files

kind files data fields becomes
wordlist words.tsv — word<TAB>value? per line, UTF-8, LF target: "overlay" | "tags:<name>" | "flags:<class>"; value_type: `"none" "u32"`
relations relations.tsv — src<TAB>rel<TAB>dst node_space: "word" | "synset" relations.custom.<name>
rules rules.json — array of rule objects (spec §3 mutate schema) set: name rules.<set>
grammar grammar.json name grammar.<name>
tlds tlds.tsv — tld<TAB>category — replaces domain.tlds
embeddings vectors.f32 + vocab.txt dim; mode: "hdc-base" | "tags-cluster"; clusters? quantised HDC base vectors or a tags.<name> cluster id; studio shows size trade-off before accepting
corpus examples.tsv — text<TAB>label labels: [] Train/Evaluate data
engine Rust crate in crate/ cargo_feature; segments: [names]; catalogue: {does, cost, absent, alternatives} first-class feature; must ship a catalogue entry and cost line

Validation (studio, on install)

  1. plugin.json parses and matches the schema for its kind; name, version, license present.
  2. Data files exist, parse, are UTF-8/LF; row errors reported with line numbers; > 0 rows.
  3. Every provides id is well-formed (tags.x, relations.custom.x, rules.x, grammar.x); no collision with another installed plugin's provides.
  4. requires ⊆ available catalogue features.
  5. Cost estimate shown before enable: wordlist ≈ 4 B × rows (+ value bytes); relations ≈ 8 B × rows; embeddings shows both modes' costs.
  6. Words in wordlist/relations not in the target lexicon: reported as a count with samples; kept for overlay, dropped (with log) for tags/flags/relations.

engine plugins additionally: crate builds with the workspace toolchain, exposes exactly the declared cargo feature, segments follow docs/pack-format.md §5 conventions, and a T0 entry exists before the feature can ship in a preset.