diff --git a/README.md b/README.md index a9e18bb..e8a1a2f 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,12 @@ plexus is the discovery layer that sits *above* an executor, not another executo

Eight stages from manifest to verify, ending in still holds or drifted.

+## See it work, step by step + +The [animated explainer](https://harperz9.github.io/repo-explainers/plexus.html) +walks through two small manifests wired into one edge, the unmet input and terminal output plexus names, a plan with its receipt, verify passing and then failing after a manifest changes, and the built-in ten-tool mesh. Every value on it is output from this repository. Its +source is [docs/explainer/index.html](docs/explainer/index.html). + ## The problem You wire up a set of tools. Each one produces artifacts and accepts inputs, but diff --git a/docs/explainer/README.md b/docs/explainer/README.md new file mode 100644 index 0000000..a8e5ad4 --- /dev/null +++ b/docs/explainer/README.md @@ -0,0 +1,13 @@ +# plexus explainer + +`index.html` is a single self-contained page that walks through how this +repository works. It is published at +. + +Open `index.html` in a browser to read it from a checkout. It loads two +typefaces from harperz9.github.io and falls back to system fonts offline. + +The commands, values and verdicts on the page came from running this repository +at commit d889be9, and each step cites the file it describes. When the behaviour +it shows changes, rerun the commands in the page's "Try it" section and update +the values in the same pull request. diff --git a/docs/explainer/index.html b/docs/explainer/index.html new file mode 100644 index 0000000..4e62e31 --- /dev/null +++ b/docs/explainer/index.html @@ -0,0 +1,513 @@ + + + + + +How plexus works + + + + + + +
+
HarperZ9/plexusExplainer, built from commit d889be9All repository explainers
+

plexus

+

Find what each tool emits and consumes, and wire them together.

+
+
+
+

What it does for you

+
+

MCP tells an agent which tools exist. plexus tells it how their outputs plug into each other's inputs. Each tool ships a small manifest; plexus builds the wiring graph, plans the pipeline that feeds the tool you want, and reports what does not connect. A plan carries a receipt tied to the exact manifests it came from, so a changed tool shows up as drift.

+
+
    +
  • Wiring from declarationsAn edge A to B forms when B consumes a capability A emits. Each edge cites the producer's own source pointer.
    • +
  • Honest gapsInputs nothing emits, outputs nothing consumes, feedback loops and duplicate tool ids are all named.
    • +
  • Plans for a goalplexus plan --goal orders the tools that feed one target and names its sources.
    • +
  • Plans you can re-checkplexus verify re-derives a plan's receipt from the current manifests and exits 1 on drift.
    • +
+

Source: README.md at d889be9 (release 0.4.0)

+
+ +
+

How it works, one step at a time

+

Scroll, or use the step buttons. The first steps use two small manifests written for this page, notes and review. The last uses the ten built-in manifests that ship with plexus. Every line is output from plexus at commit d889be9.

+
+
+
+ + + + + + +
+
+ + + + +
+
+
    +
  1. + 01

    Two tools declare their ports

    +

    notes emits notes.summary/1. review consumes notes.summary/1 and a style.guide/1, and emits review.verdict/1. Each port names the module behind it, such as src/notes/summary.py:build.

    +

    A manifest is plain JSON. A tool ships one and it joins the mesh.

    +

    Source: README.md, "How a tool plugs in"; src/plexus/manifest.py

    +
    2. +
  2. + 02

    Discover the edge

    +

    plexus discover matches capability strings. review consumes what notes emits, so one edge forms: notes to review via notes.summary/1.

    +

    The edge is tagged evidence: declared. plexus copies the producer's module pointer into via but never imports or runs it. The citation is a claim for you to check.

    +

    Source: src/plexus/mesh.py; README.md, "Declared, not probed"

    +
    3. +
  3. + 03

    Name what does not connect

    +

    Nothing in the set emits style.guide/1, so it is an unmet input: an external or human input, or a tool that is not here. Nothing consumes review.verdict/1, so it is a terminal output.

    +

    Both come from the same comparison. An unmet input means only that no manifest in this set produces it.

    +

    Source: src/plexus/mesh.py, orphans

    +
    4. +
  4. + 04

    Plan the pipeline, with a receipt

    +

    plexus plan --goal review orders the tools that feed review: notes, then review. Its receipt records the SHA-256 of each manifest and a hash over the derived plan, under a method version.

    +

    Source: src/plexus/plan.py, src/plexus/receipt.py

    +
    5. +
  5. + 05

    Verify against the manifests you have now

    +

    plexus verify re-derives the plan from the current manifests and rebuilds its receipt. Unchanged, it matches and exits 0.

    +

    Now change notes to emit notes.summary/2. The manifest hash changes, the wiring changes, and verify exits 1. Pick each case in the panel.

    +

    Source: src/plexus/receipt.py, verify_plan

    +
    6. +
  6. + 06

    The built-in mesh

    +

    plexus ships manifests for ten tools. Its tour wires them: gather feeds crucible through gather.digest/1, mneme and crucible feed each other replay packs, and the plan for crucible reports its feedback loop as a loop.

    +

    Source: examples/tour.py; src/plexus/registry.py

    +
    7. +
+
+
+ +
+

Try it

+

Install from PyPI (Python 3.11 or newer). Discovery reads manifests and runs no tool.

+
$ python -m pip install plexus-mesh
+$ plexus route --from gather --to crucible --builtin
+  "connected": true,
+  "hops": 1,
+$ plexus plan --goal crucible --builtin > plan.json
+$ plexus verify --plan plan.json --builtin
+

Output from plexus at d889be9 run from source; plexus-mesh 0.4.0 is the current PyPI release.

+
+ +
+

What it does not do

+
    +
  • Edges come from declarations. Discovery never runs a tool, so an edge says two manifests agree. Whether the tools work together is a separate test. probe_lane checks that a lane's server is live.
    • +
  • An unmet input means no manifest in the set you gave produces it. plexus reasons about nothing outside that set.
    • +
  • verify checks a saved plan's receipt against one re-derived from the current manifests. Act on the re-derived plan it reports, not on a saved file you have not re-derived.
    • +
  • The built-in manifests are kept in plexus. Their presence does not show that each tool publishes its own manifest.
    • +
+

Source: README.md at d889be9, "Declared, not probed" and "How a tool plugs in"; src/plexus/receipt.py

+
+ +
+

Check what stuck

+

Answer each one in your head before you open it.

+
When does an edge from A to B form?

When B consumes a capability that A emits, directly or through A's consumable_as list.

+
What does evidence: declared mean on an edge?

The edge comes from what the manifests say. plexus copied the producer's module pointer but did not follow or run it.

+
style.guide/1 shows up as an unmet input. Does that mean no such tool exists?

No. It means no manifest in the set plexus was given emits it.

+
A tool's manifest changes after you saved a plan. What does verify do?

It re-derives the receipt from the current manifests, the hashes no longer agree, and it exits 1.

+
+
+ + + + + +