plexus-mesh 0.2.2__py3-none-any.whl

plexus/__init__.py

@@ -0,0 +1,27 @@
+"""plexus: capability discovery + auto-wiring for agent toolchains.
+
+Point it at a set of tools that ship interop manifests and declarative discovery
+wires producer to consumer into a pipeline, every edge tagged `declared` and
+carrying the module its producer names. Discovery does not import or run cited
+tools. Optional probe helpers in `plexus.registry` launch owned MCP servers only
+when explicitly called. Zero runtime dependencies.
+"""
+from .graph import to_dot, to_mermaid
+from .manifest import Manifest, Port, validate
+from .mesh import Edge, Mesh, discover
+from .plan import plan_to, route
+from .receipt import build_plan_receipt, verify_plan
+from .registry import builtin_manifests, load_dir
+from .run import pipeline_script
+
+__version__ = "0.2.2"
+
+__all__ = [
+    "Manifest", "Port", "validate",
+    "Mesh", "Edge", "discover",
+    "plan_to", "route",
+    "build_plan_receipt", "verify_plan",
+    "to_mermaid", "to_dot", "pipeline_script",
+    "builtin_manifests", "load_dir",
+    "__version__",
+]

plexus/__main__.py

@@ -0,0 +1,4 @@
+from plexus.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plexus/cli.py

@@ -0,0 +1,139 @@
+"""cli.py — plexus command line.
+
+  plexus discover [--builtin] [--dir DIR]   # the mesh: organs, edges, orphans
+  plexus wiring   [...]                      # capability -> (producer, consumer) pairs
+  plexus plan --goal ORGAN [...]             # upstream pipeline that feeds ORGAN
+  plexus route --from A --to B [...]         # capability path from A to B
+  plexus validate [...]                      # manifest problems (exit 1 if any)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+
+from . import __version__
+from .graph import to_dot, to_mermaid
+from .manifest import content_hash, duplicate_organs, validate
+from .mesh import discover
+from .plan import plan_to, route
+from .registry import builtin_manifests, export_all, load_dir
+from .run import pipeline_script
+
+
+def _load(args) -> list:
+    mans = list(builtin_manifests()) if (args.builtin or not args.dir) else []
+    if args.dir:
+        mans += load_dir(args.dir)
+    return mans
+
+
+def _receipt(mesh) -> dict:
+    """A re-runnable provenance receipt for the mesh: which manifests were read,
+    from where, and a content hash a stranger can recompute from the same bytes."""
+    return {
+        "plexus_version": __version__,
+        "generated_utc": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "manifests": [{"organ": m.organ, "source": m.source,
+                       "sha256": content_hash(m)}
+                      for m in sorted(mesh.manifests.values(), key=lambda m: m.organ)],
+    }
+
+
+def _mesh_json(mesh) -> dict:
+    return {
+        "organs": mesh.organs,
+        "edges": [{"producer": e.producer, "consumer": e.consumer,
+                   "capability": e.capability, "self_loop": e.self_loop,
+                   "via": e.producer_module, "evidence": e.evidence}
+                  for e in mesh.edges],
+        "orphans": mesh.orphans(),
+        "collisions": mesh.collisions,
+        "receipt": _receipt(mesh),
+    }
+
+
+def _add_source_flags(p):
+    p.add_argument("--builtin", action="store_true", help="include the built-in flagship manifests")
+    p.add_argument("--dir", default="", help="load *.interop.json manifests from this directory")
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    ap = argparse.ArgumentParser(prog="plexus", description=__doc__)
+    ap.add_argument("--version", action="version", version=f"plexus {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    for name in ("discover", "wiring", "validate"):
+        sp = sub.add_parser(name)
+        _add_source_flags(sp)
+    pp = sub.add_parser("plan"); _add_source_flags(pp)
+    pp.add_argument("--goal", required=True, help="organ you want to feed")
+    rp = sub.add_parser("route"); _add_source_flags(rp)
+    rp.add_argument("--from", dest="src", required=True)
+    rp.add_argument("--to", dest="dst", required=True)
+    vp = sub.add_parser("verify"); _add_source_flags(vp)
+    vp.add_argument("--plan", required=True,
+                    help="a plan/route JSON file (from `plexus plan`/`route`) to re-derive "
+                         "and re-verify against the current mesh")
+    gp = sub.add_parser("graph"); _add_source_flags(gp)
+    gp.add_argument("--format", default="mermaid", choices=["mermaid", "dot"])
+    up = sub.add_parser("run"); _add_source_flags(up)
+    up.add_argument("--goal", required=True, help="organ you want to feed")
+    ep = sub.add_parser("export")
+    ep.add_argument("--dir", default="manifests", help="write <organ>.interop.json files here")
+    sub.add_parser("mcp")   # stdio MCP server: discover/wiring/plan/route as tools
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "mcp":
+        from .mcp import serve
+        return serve()
+    if args.cmd == "export":
+        print("\n".join(export_all(args.dir)))
+        return 0
+
+    mans = _load(args)
+
+    if args.cmd == "discover":
+        print(json.dumps(_mesh_json(discover(mans)), indent=2))
+        return 0
+    if args.cmd == "wiring":
+        print(json.dumps(discover(mans).wiring(), indent=2))
+        return 0
+    if args.cmd == "plan":
+        print(json.dumps(plan_to(discover(mans), args.goal), indent=2))
+        return 0
+    if args.cmd == "route":
+        print(json.dumps(route(discover(mans), args.src, args.dst), indent=2))
+        return 0
+    if args.cmd == "verify":
+        from .receipt import verify_plan
+        with open(args.plan, encoding="utf-8") as f:
+            plan = json.load(f)
+        ok = verify_plan(plan, discover(mans))
+        print(json.dumps({"verified": ok, "target": plan.get("target"),
+                          "source": plan.get("source")}, indent=2))
+        return 0 if ok else 1
+    if args.cmd == "graph":
+        mesh = discover(mans)
+        print(to_mermaid(mesh) if args.format == "mermaid" else to_dot(mesh))
+        return 0
+    if args.cmd == "run":
+        print(pipeline_script(discover(mans), args.goal))
+        return 0
+    if args.cmd == "validate":
+        problems = {m.organ: validate(m) for m in mans}
+        report = {k: v for k, v in problems.items() if v}
+        dups = duplicate_organs(mans)
+        if dups:
+            # A set-level clash the per-organ dict above cannot show (its own key
+            # collapses the duplicates); name it so a collision can never launder
+            # to {"ok": true}.
+            report["duplicate_organs"] = dups
+        print(json.dumps(report or {"ok": True}, indent=2))
+        return 1 if report else 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plexus/graph.py

@@ -0,0 +1,38 @@
+"""graph.py — render the mesh as a diagram (Mermaid / Graphviz DOT).
+
+Discovery is only useful if you can see it. This turns the mesh into a picture:
+organs as nodes, capability-labeled edges as producer -> consumer arrows, with
+self-loops and the cross-tool wiring visible at a glance. Mermaid renders in any
+Markdown viewer; DOT feeds Graphviz. Pure string output, zero deps.
+"""
+from __future__ import annotations
+
+from .mesh import Mesh
+
+
+def _san(node: str) -> str:
+    """A Mermaid/DOT-safe node id (organs are simple slugs already, but be safe)."""
+    return "".join(c if c.isalnum() else "_" for c in node)
+
+
+def to_mermaid(mesh: Mesh, *, direction: str = "LR") -> str:
+    """A Mermaid flowchart. Cross-tool edges are solid; self-loops dotted."""
+    lines = [f"flowchart {direction}"]
+    for organ in mesh.organs:
+        lines.append(f'  {_san(organ)}["{organ}"]')
+    for e in mesh.edges:
+        arrow = "-.->" if e.self_loop else "-->"
+        lines.append(f'  {_san(e.producer)} {arrow}|"{e.capability}"| {_san(e.consumer)}')
+    return "\n".join(lines)
+
+
+def to_dot(mesh: Mesh) -> str:
+    """A Graphviz DOT digraph."""
+    lines = ["digraph plexus {", '  rankdir=LR;', '  node [shape=box];']
+    for organ in mesh.organs:
+        lines.append(f'  "{organ}";')
+    for e in mesh.edges:
+        attrs = f'label="{e.capability}"' + (", style=dotted" if e.self_loop else "")
+        lines.append(f'  "{e.producer}" -> "{e.consumer}" [{attrs}];')
+    lines.append("}")
+    return "\n".join(lines)

plexus/manifest.py

@@ -0,0 +1,117 @@
+"""manifest.py — what a tool declares about how it plugs into others.
+
+A manifest is a tool's interop contract: the capabilities it EMITS (re-checkable
+artifacts another tool could consume) and the capabilities it CONSUMES (inputs it
+accepts). A capability is a stable string: a schema id like
+"mneme.crucible-export/2" or a shared-spine kind like
+"project-telos.flagship-action/v1". Matching is by capability string, so an edge
+forms when a producer DECLARES a capability the consumer DECLARES it accepts.
+
+Every port carries `module` (a file:function pointer) the producer names as the
+source. plexus does not import, resolve, or run that pointer, so the mesh is
+DECLARED, not probed: the module is a self-reported citation to follow, not a
+verified receipt. A manifest is a plain dict/JSON, so any tool in any language
+can ship one; nothing here imports the tools it describes.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Port:
+    """One capability a tool emits or consumes."""
+    capability: str                 # the match key (schema id or shared kind)
+    title: str = ""                 # human label
+    module: str = ""                # evidence: repo-relative file:function
+    summary: str = ""
+    consumable_as: tuple = ()       # extra capabilities an EMIT also satisfies
+                                    # (e.g. mneme.crucible-export/2 -> crucible.thesis)
+
+    def satisfies(self, capability: str) -> bool:
+        return capability == self.capability or capability in self.consumable_as
+
+
+@dataclass
+class Manifest:
+    organ: str
+    invoke: dict = field(default_factory=dict)   # {cli, mcp_server, python_import}
+    emits: list = field(default_factory=list)    # list[Port]
+    consumes: list = field(default_factory=list)  # list[Port]
+    evidence: list = field(default_factory=list)  # file paths the manifest was grounded on
+    source: str = ""                              # provenance: "builtin:registry" or the file path read
+
+    @staticmethod
+    def from_dict(d: dict) -> "Manifest":
+        def ports(key):
+            out = []
+            for p in d.get(key, []):
+                if isinstance(p, str):
+                    out.append(Port(capability=p))
+                elif isinstance(p, dict):
+                    out.append(Port(
+                        capability=p.get("capability", ""), title=p.get("title", ""),
+                        module=p.get("module", ""), summary=p.get("summary", ""),
+                        consumable_as=tuple(p.get("consumable_as", ()))))
+            return out
+        # Tolerant by contract: a missing organ or capability becomes an empty
+        # string that validate() reports; from_dict never raises on malformed input.
+        return Manifest(organ=d.get("organ", ""), invoke=d.get("invoke", {}),
+                        emits=ports("emits"), consumes=ports("consumes"),
+                        evidence=list(d.get("evidence", [])))
+
+    def to_dict(self) -> dict:
+        def dump(ports):
+            return [{"capability": p.capability, "title": p.title, "module": p.module,
+                     "summary": p.summary, "consumable_as": list(p.consumable_as)}
+                    for p in ports]
+        return {"organ": self.organ, "invoke": self.invoke,
+                "emits": dump(self.emits), "consumes": dump(self.consumes),
+                "evidence": self.evidence}
+
+
+def content_hash(m) -> str:
+    """sha256 over the manifest's canonical content (its to_dict, sorted keys).
+    Source is deliberately excluded, so the hash binds WHAT was declared, not
+    where it was read; a stranger can recompute it from the same bytes."""
+    canonical = json.dumps(m.to_dict(), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def duplicate_organs(manifests: list) -> list:
+    """Organ ids declared by more than one manifest in the set, sorted unique.
+    A set-level check: identity is self-declared, so a collision must be NAMED,
+    never silently resolved last-writer-wins."""
+    seen, dups = set(), set()
+    for m in manifests:
+        if m.organ in seen:
+            dups.add(m.organ)
+        seen.add(m.organ)
+    return sorted(dups)
+
+
+def validate(m) -> list:
+    """Problems with a manifest (empty list == valid). A validator reports
+    malformed input; it never raises on it."""
+    issues = []
+    if not isinstance(m, Manifest):
+        return ["not a Manifest"]
+    if not m.organ or not isinstance(m.organ, str):
+        issues.append("organ id missing or not a string")
+    seen = set()
+    for side in ("emits", "consumes"):
+        for i, p in enumerate(getattr(m, side)):
+            if not isinstance(p, Port) or not p.capability:
+                issues.append(f"{side}[{i}] has no capability")
+                continue
+            if side == "emits" and not p.module:
+                # The producing module is the evidence the "cites its module"
+                # claim rests on; an emit without it is a receipt-less claim.
+                issues.append(f"emits[{i}] {p.capability!r} has no module evidence")
+            key = (side, p.capability)
+            if key in seen:
+                issues.append(f"{side} declares {p.capability!r} twice")
+            seen.add(key)
+    return issues

plexus/mcp.py

@@ -0,0 +1,156 @@
+"""mcp.py — a zero-dep MCP server so any agent can query the mesh live.
+
+A CLI mesh is useful to a human; an agent needs it mid-task. This exposes
+discover / wiring / plan / route as MCP tools over stdio JSON-RPC 2.0 (the same
+shape every flagship speaks), so a harness can ask "what feeds crucible?" or
+"how do gather and crucible connect?" while it works. No SDK, stdlib only.
+
+The transport (`serve`) is a thin loop; all logic is in `handle`, which maps a
+request dict to a response dict and is fully testable without any pipes.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from . import __version__
+from .mesh import discover
+from .plan import plan_to, route
+from .registry import builtin_manifests, load_dir
+
+PROTOCOL = "2025-06-18"
+
+_DIR = {"dir": {"type": "string", "description": "load extra *.interop.json manifests from here"}}
+
+TOOLS = [
+    {"name": "plexus_discover",
+     "description": "Discover the interop mesh: organs, producer->consumer edges (each with the module that produces it), and orphans (unmet inputs / unconsumed outputs).",
+     "inputSchema": {"type": "object", "properties": dict(_DIR)}},
+    {"name": "plexus_wiring",
+     "description": "The wiring map: capability -> list of (producer, consumer) pairs.",
+     "inputSchema": {"type": "object", "properties": dict(_DIR)}},
+    {"name": "plexus_plan",
+     "description": "The upstream pipeline that feeds a target organ, in dependency order, with any feedback loops reported.",
+     "inputSchema": {"type": "object", "required": ["goal"],
+                     "properties": {"goal": {"type": "string", "description": "organ to feed"}, **_DIR}}},
+    {"name": "plexus_route",
+     "description": "The shortest capability path from one organ to another.",
+     "inputSchema": {"type": "object", "required": ["source", "target"],
+                     "properties": {"source": {"type": "string"}, "target": {"type": "string"}, **_DIR}}},
+    {"name": "plexus.status",
+     "description": "Liveness and identity of the plexus MCP server (name, version, protocol). Network-free health probe.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "plexus.doctor",
+     "description": "Readiness diagnostic: identity plus the count of builtin interop manifests and the tools exposed.",
+     "inputSchema": {"type": "object", "properties": {}}},
+]
+
+
+def _mesh(args: dict):
+    mans = list(builtin_manifests())
+    if args.get("dir"):
+        mans += load_dir(args["dir"])
+    return discover(mans)
+
+
+def _mesh_json(mesh) -> dict:
+    return {"organs": mesh.organs,
+            "edges": [{"producer": e.producer, "consumer": e.consumer,
+                       "capability": e.capability, "self_loop": e.self_loop,
+                       "via": e.producer_module} for e in mesh.edges],
+            "orphans": mesh.orphans()}
+
+
+def _call(params: dict) -> dict:
+    name, args = params.get("name"), params.get("arguments", {}) or {}
+    if name in ("plexus.status", "plexus.doctor"):
+        info = {"ok": True, "server": "plexus", "version": __version__, "protocol": PROTOCOL}
+        if name == "plexus.doctor":
+            info["builtin_manifests"] = len(list(builtin_manifests()))
+            info["tools"] = [t["name"] for t in TOOLS]
+        return {"content": [{"type": "text", "text": json.dumps(info, indent=2)}]}
+    try:
+        mesh = _mesh(args)
+        if name == "plexus_discover":
+            result = _mesh_json(mesh)
+        elif name == "plexus_wiring":
+            result = mesh.wiring()
+        elif name == "plexus_plan":
+            result = plan_to(mesh, args.get("goal", ""))
+        elif name == "plexus_route":
+            result = route(mesh, args.get("source", ""), args.get("target", ""))
+        else:
+            return {"content": [{"type": "text", "text": f"unknown tool {name!r}"}], "isError": True}
+    except Exception as e:                       # a tool error is a result, not a crash
+        return {"content": [{"type": "text", "text": f"[error] {type(e).__name__}: {e}"}],
+                "isError": True}
+    return {"content": [{"type": "text", "text": json.dumps(result, indent=2)}]}
+
+
+def _ok(rid, result):
+    return {"jsonrpc": "2.0", "id": rid, "result": result}
+
+
+def _err(rid, code, message):
+    return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": message}}
+
+
+def _valid_request_id(value) -> bool:
+    return type(value) is str or type(value) is int
+
+
+def _safe_request_id(req: dict):
+    if "id" not in req:
+        return None
+    rid = req["id"]
+    return rid if _valid_request_id(rid) else None
+
+
+def handle(req: dict):
+    """Map one JSON-RPC request to a response dict (or None for notifications)."""
+    if not isinstance(req, dict):
+        return _err(None, -32600, "invalid request")
+    rid = _safe_request_id(req)
+    if "id" in req and not _valid_request_id(req["id"]):
+        return _err(None, -32600, "invalid request")
+    if req.get("jsonrpc") != "2.0":
+        return _err(rid, -32600, "invalid request")
+    method = req.get("method")
+    if not isinstance(method, str):
+        return _err(rid, -32600, "invalid request: method must be a string")
+    if "id" not in req:
+        return None
+    if method == "initialize":
+        return _ok(rid, {"protocolVersion": PROTOCOL, "capabilities": {"tools": {}},
+                         "serverInfo": {"name": "plexus", "version": __version__}})
+    if method == "tools/list":
+        return _ok(rid, {"tools": TOOLS})
+    if method == "tools/call":
+        params = req["params"] if "params" in req else {}
+        if not isinstance(params, dict):
+            return _err(rid, -32602, "invalid params")
+        return _ok(rid, _call(params))
+    return _err(rid, -32601, f"method not found: {method}")
+
+
+def serve(stdin=None, stdout=None) -> int:
+    stdin, stdout = stdin or sys.stdin, stdout or sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            stdout.write(json.dumps(_err(None, -32700, "parse error")) + "\n")
+            stdout.flush()
+            continue
+        resp = handle(req)
+        if resp is not None:
+            stdout.write(json.dumps(resp) + "\n")
+            stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(serve())

plexus/mesh.py

@@ -0,0 +1,88 @@
+"""mesh.py — discover the wiring: whose output plugs into whose input.
+
+Given a set of manifests, the mesh computes producer -> consumer EDGES: for every
+capability a tool consumes, it finds the tools that emit something satisfying it.
+This is the layer MCP tool lists lack: MCP tells an agent that tools exist; the
+mesh tells it how their OUTPUTS chain into each other's INPUTS.
+
+An edge is DECLARED, not probed. It forms by matching capability strings the
+manifests self-report; plexus never imports, resolves, or runs the tools, so it
+cannot confirm the cited module exists or that the outputs truly compose. Every
+edge is tagged `evidence="declared"` and carries the module its producer names,
+a self-reported citation to follow, not a verified receipt.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .manifest import duplicate_organs
+
+
+@dataclass(frozen=True)
+class Edge:
+    producer: str          # organ id
+    consumer: str          # organ id
+    capability: str        # the consumer's input capability that the producer satisfies
+    producer_module: str
+    consumer_module: str
+    self_loop: bool = False
+    evidence: str = "declared"   # "declared": self-reported, never probed by plexus
+
+
+@dataclass
+class Mesh:
+    organs: list           # organ ids, sorted
+    edges: list            # list[Edge]
+    manifests: dict        # organ -> Manifest (deduped, last-writer-wins)
+    collisions: list = field(default_factory=list)  # organ ids declared more than once
+
+    def wiring(self) -> dict:
+        """capability -> sorted list of (producer, consumer) pairs."""
+        out: dict = {}
+        for e in self.edges:
+            out.setdefault(e.capability, []).append((e.producer, e.consumer))
+        return {k: sorted(v) for k, v in sorted(out.items())}
+
+    def producers_of(self, organ: str) -> list:
+        """Organs whose output feeds `organ` (its upstream), sorted unique."""
+        return sorted({e.producer for e in self.edges
+                       if e.consumer == organ and not e.self_loop})
+
+    def consumers_of(self, organ: str) -> list:
+        """Organs that consume `organ`'s output (its downstream), sorted unique."""
+        return sorted({e.consumer for e in self.edges
+                       if e.producer == organ and not e.self_loop})
+
+    def orphans(self) -> dict:
+        """Honesty surface: capabilities consumed by someone but emitted by no
+        organ in the set (an unmet input), and emitted but never consumed."""
+        emitted, consumed = set(), set()
+        for m in self.manifests.values():
+            for p in m.emits:
+                emitted.add(p.capability)
+                emitted.update(p.consumable_as)
+            for p in m.consumes:
+                consumed.add(p.capability)
+        return {"unmet_inputs": sorted(consumed - emitted),
+                "unconsumed_outputs": sorted(emitted - consumed)}
+
+
+def discover(manifests: list) -> Mesh:
+    """Build the mesh. An edge (A -> B, cap) exists when B consumes capability
+    `cap` and A emits a port that satisfies `cap`."""
+    mans = {m.organ: m for m in manifests}
+    edges = []
+    for consumer in manifests:
+        for want in consumer.consumes:
+            for producer in manifests:
+                for emit in producer.emits:
+                    if emit.satisfies(want.capability):
+                        edges.append(Edge(
+                            producer=producer.organ, consumer=consumer.organ,
+                            capability=want.capability,
+                            producer_module=emit.module, consumer_module=want.module,
+                            self_loop=(producer.organ == consumer.organ),
+                            evidence="declared"))
+    edges.sort(key=lambda e: (e.capability, e.producer, e.consumer))
+    return Mesh(organs=sorted(mans), edges=edges, manifests=mans,
+                collisions=duplicate_organs(manifests))