cls-knowledge 0.1.0__tar.gz

cls_knowledge-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+node_modules/
+.agent/
+dist/
+.next/
+.output/
+.swc/
+.vercel/
+target/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+!.env.example
+.DS_Store
+* 2.ts
+* 2.tsx
+* 2.js
+* 2.jsx
+*.tsbuildinfo
+.cumulus-db-data/
+apps/cumulus-db/.cumulus-db-data/
+.cumulus/
+coverage/
+tmp/

cls_knowledge-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: cls-knowledge
+Version: 0.1.0
+Summary: Python SDK and MCP server for Cumulus Knowledge
+Project-URL: Homepage, https://cumulush.com
+Project-URL: Repository, https://github.com/Cumulus-s/cumulus-create
+Author: Cumulus Knowledge contributors
+License-Expression: AGPL-3.0-only
+Keywords: agents,cli,knowledge-graph,mcp,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.0; extra == 'test'
+Provides-Extra: tui
+Requires-Dist: textual>=6.0.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# cls-knowledge
+
+Python SDK, operations ingestion helpers, graph QA helpers, MCP server, and ops-review TUI mode for Cumulus Knowledge.
+
+The SDK uses the `cls-knowledge` binary by default. Set `CUMULUS_BIN` to point at another binary.
+
+```python
+from cumulus_knowledge import CumulusKnowledge
+
+knowledge = CumulusKnowledge(root="Documents/rune")
+knowledge.index(profile="all")
+hits = knowledge.query("auth flow", budget=800)
+graph = knowledge.get_graph_view("risk")
+```
+
+Operations helpers:
+
+```python
+from cumulus_knowledge import (
+    extract_operations_entities,
+    build_relationship_candidates,
+    score_graph_readability,
+    detect_missing_citations,
+)
+
+entities = extract_operations_entities("demo-project")
+relationships = build_relationship_candidates(entities)
+quality = score_graph_readability(graph.data)
+missing = detect_missing_citations(graph.data)
+```
+
+Ops review TUI mode:
+
+```bash
+python3 -m cumulus_knowledge.tui --ops-review ./demo-project
+```
+
+Python owns heavier document and operations workflows: invoices, vendors, bank draws, shipments, schedule risks, missing citations, and batch graph quality checks.
+
+Hosted-style API mode:
+
+```python
+from cumulus_knowledge import CumulusKnowledge
+
+client = CumulusKnowledge(api_base_url="http://127.0.0.1:8787")
+client.create_project({"name": "Demo Operations Project"})
+client.upload_folder([{"path": "invoices/demo.md", "content": "Invoice DEMO-INV-001"}])
+client.index_project()
+graph = client.get_graph_view("finance")
+html = client.export_html()
+```

cls_knowledge-0.1.0/README.md

@@ -0,0 +1,51 @@
+# cls-knowledge
+
+Python SDK, operations ingestion helpers, graph QA helpers, MCP server, and ops-review TUI mode for Cumulus Knowledge.
+
+The SDK uses the `cls-knowledge` binary by default. Set `CUMULUS_BIN` to point at another binary.
+
+```python
+from cumulus_knowledge import CumulusKnowledge
+
+knowledge = CumulusKnowledge(root="Documents/rune")
+knowledge.index(profile="all")
+hits = knowledge.query("auth flow", budget=800)
+graph = knowledge.get_graph_view("risk")
+```
+
+Operations helpers:
+
+```python
+from cumulus_knowledge import (
+    extract_operations_entities,
+    build_relationship_candidates,
+    score_graph_readability,
+    detect_missing_citations,
+)
+
+entities = extract_operations_entities("demo-project")
+relationships = build_relationship_candidates(entities)
+quality = score_graph_readability(graph.data)
+missing = detect_missing_citations(graph.data)
+```
+
+Ops review TUI mode:
+
+```bash
+python3 -m cumulus_knowledge.tui --ops-review ./demo-project
+```
+
+Python owns heavier document and operations workflows: invoices, vendors, bank draws, shipments, schedule risks, missing citations, and batch graph quality checks.
+
+Hosted-style API mode:
+
+```python
+from cumulus_knowledge import CumulusKnowledge
+
+client = CumulusKnowledge(api_base_url="http://127.0.0.1:8787")
+client.create_project({"name": "Demo Operations Project"})
+client.upload_folder([{"path": "invoices/demo.md", "content": "Invoice DEMO-INV-001"}])
+client.index_project()
+graph = client.get_graph_view("finance")
+html = client.export_html()
+```

cls_knowledge-0.1.0/cumulus_knowledge/__init__.py

@@ -0,0 +1,25 @@
+from .client import CumulusKnowledge
+from .models import AxiEnvelope
+from .operations import (
+    build_relationship_candidates,
+    detect_missing_citations,
+    detect_schedule_shipping_risk,
+    compare_invoice_to_bank_draw,
+    extract_operations_entities,
+    run_agent_eval,
+    score_graph_readability,
+    upload_project,
+)
+
+__all__ = [
+    "AxiEnvelope",
+    "CumulusKnowledge",
+    "build_relationship_candidates",
+    "compare_invoice_to_bank_draw",
+    "detect_missing_citations",
+    "detect_schedule_shipping_risk",
+    "extract_operations_entities",
+    "run_agent_eval",
+    "score_graph_readability",
+    "upload_project",
+]

cls_knowledge-0.1.0/cumulus_knowledge/client.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+from urllib import parse, request
+
+from .models import AxiEnvelope
+
+
+class CumulusKnowledge:
+    def __init__(
+        self,
+        root: str | os.PathLike[str] = ".",
+        bin: str | None = None,
+        api_base_url: str | None = None,
+        project_id: str = "local",
+    ) -> None:
+        self.root = str(root)
+        self.bin = bin or os.environ.get("CUMULUS_BIN", "cls-knowledge")
+        self.api_base_url = api_base_url or os.environ.get("CUMULUS_API_URL")
+        self.project_id = project_id or os.environ.get("CUMULUS_PROJECT_ID", "local")
+
+    def init(self, root: str | os.PathLike[str] | None = None) -> AxiEnvelope[Any]:
+        return self._run(["knowledge", "init", str(root or self.root)])
+
+    def index(
+        self,
+        profile: str = "all",
+        root: str | os.PathLike[str] | None = None,
+        watch: bool = False,
+    ) -> AxiEnvelope[Any]:
+        args = ["knowledge", "index", str(root or self.root), "--profile", profile]
+        if watch:
+            args.append("--watch")
+        return self._run(args)
+
+    def query(self, text: str, budget: int = 1200, limit: int = 10) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            return self._api_json(
+                "POST",
+                self._project_path("/query"),
+                {"query": text, "budget": budget, "limit": limit},
+            )
+        return self._run(
+            [
+                "knowledge",
+                "query",
+                text,
+                "--path",
+                self.root,
+                "--budget",
+                str(budget),
+                "--limit",
+                str(limit),
+            ]
+        )
+
+    def get_node(self, node_id: str) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            return self.fetch_node(node_id)
+        return self._run(["knowledge", "node", "get", node_id, "--path", self.root])
+
+    def expand_neighbors(self, node_id: str, depth: int = 1) -> AxiEnvelope[Any]:
+        return self._run(["knowledge", "graph", "expand", node_id, "--path", self.root, "--depth", str(depth)])
+
+    def find_paths(self, from_id: str, to_id: str, max_depth: int = 6) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            return self.explain_path(from_id, to_id)
+        return self._run(
+            [
+                "knowledge",
+                "path",
+                "explain",
+                from_id,
+                to_id,
+                "--path",
+                self.root,
+                "--max-depth",
+                str(max_depth),
+            ]
+        )
+
+    def index_status(self) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            return self.get_job()
+        return self._run(["knowledge", "doctor", "--path", self.root])
+
+    def get_graph_view(self, preset: str = "full") -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            query = parse.urlencode({"preset": preset})
+            return self._api_json("GET", f"{self._project_path('/graph-view')}?{query}")
+        return self._run(["knowledge", "graph", "view", "--path", self.root, "--preset", preset])
+
+    def create_project(self, data: dict[str, Any] | None = None) -> AxiEnvelope[Any]:
+        return self._api_json("POST", "/v1/projects", data or {})
+
+    def upload_folder(self, files: list[dict[str, str]]) -> AxiEnvelope[Any]:
+        return self._api_json("POST", self._project_path("/uploads"), {"files": files})
+
+    def index_project(self) -> AxiEnvelope[Any]:
+        return self._api_json("POST", self._project_path("/index"), {})
+
+    def get_job(self, job_id: str = "local") -> AxiEnvelope[Any]:
+        return self._api_json("GET", f"/v1/jobs/{parse.quote(job_id)}")
+
+    def upload_project(self, path_or_zip: str | os.PathLike[str]) -> AxiEnvelope[Any]:
+        return self.init(path_or_zip)
+
+    def fetch_node(self, node_id: str) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            return self._api_json("GET", self._project_path(f"/nodes/{parse.quote(node_id)}"))
+        return self.get_node(node_id)
+
+    def explain_path(self, from_id: str, to_id: str, max_depth: int = 6) -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            query = parse.urlencode({"from": from_id, "to": to_id, "max_depth": max_depth})
+            return self._api_json("GET", f"{self._project_path('/paths/explain')}?{query}")
+        return self.find_paths(from_id, to_id, max_depth=max_depth)
+
+    def source_trace(self, node_id: str, preset: str = "full") -> AxiEnvelope[Any]:
+        if self.api_base_url:
+            query = parse.urlencode({"preset": preset})
+            return self._api_json("GET", f"{self._project_path(f'/nodes/{parse.quote(node_id)}/source-trace')}?{query}")
+        view = self.get_graph_view(preset).data
+        return AxiEnvelope.from_dict({
+            "ok": True,
+            "data": {
+                "node_id": node_id,
+                "evidence": [item for item in view.get("evidence", []) if item.get("node_id") == node_id],
+            },
+            "meta": {"command": "knowledge.source_trace"},
+            "links": [],
+        })
+
+    def export_html(self) -> str:
+        return self._api_text("GET", self._project_path("/exports/html"))
+
+    def export_graph(self, output: str | os.PathLike[str], format: str = "json") -> Path:
+        out = Path(output)
+        self._run_raw(["knowledge", "viz", "export", "--path", self.root, "--format", format, "--output", str(out)])
+        return out
+
+    def _run(self, args: list[str]) -> AxiEnvelope[Any]:
+        completed = self._run_raw([*args, "--format", "json"])
+        return AxiEnvelope.from_dict(json.loads(completed.stdout))
+
+    def _run_raw(self, args: list[str]) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [self.bin, *args],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+        )
+
+    def _api_json(self, method: str, path: str, body: dict[str, Any] | None = None) -> AxiEnvelope[Any]:
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        req = request.Request(
+            self._api_url(path),
+            data=payload,
+            method=method,
+            headers={"content-type": "application/json"},
+        )
+        with request.urlopen(req) as response:
+            return AxiEnvelope.from_dict(json.loads(response.read().decode("utf-8")))
+
+    def _api_text(self, method: str, path: str) -> str:
+        req = request.Request(self._api_url(path), method=method)
+        with request.urlopen(req) as response:
+            return response.read().decode("utf-8")
+
+    def _api_url(self, path: str) -> str:
+        if not self.api_base_url:
+            raise RuntimeError("api_base_url is required for API calls")
+        return parse.urljoin(self.api_base_url.rstrip("/") + "/", path.lstrip("/"))
+
+    def _project_path(self, suffix: str) -> str:
+        return f"/v1/projects/{parse.quote(self.project_id)}{suffix}"

cls_knowledge-0.1.0/cumulus_knowledge/mcp_server.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from .client import CumulusKnowledge
+from .operations import (
+    build_relationship_candidates,
+    compare_invoice_to_bank_draw,
+    detect_missing_citations,
+    detect_schedule_shipping_risk,
+    extract_operations_entities,
+    run_agent_eval,
+    score_graph_readability,
+)
+
+
+TOOLS = [
+    {"name": "graph_view", "description": "Return a semantic graph view with readable labels, legend, layout, filters, and evidence.", "inputSchema": {"type": "object", "properties": {"preset": {"type": "string"}}}},
+    {"name": "search", "description": "Search indexed nodes and chunks.", "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["query"]}},
+    {"name": "fetch", "description": "Fetch a node by ID.", "inputSchema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}},
+    {"name": "expand_neighbors", "description": "Expand graph neighbors.", "inputSchema": {"type": "object", "properties": {"id": {"type": "string"}, "depth": {"type": "integer"}}, "required": ["id"]}},
+    {"name": "find_paths", "description": "Find a graph path.", "inputSchema": {"type": "object", "properties": {"from_id": {"type": "string"}, "to_id": {"type": "string"}}, "required": ["from_id", "to_id"]}},
+    {"name": "index_status", "description": "Return local index status.", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "ingest", "description": "Index the configured root.", "inputSchema": {"type": "object", "properties": {"profile": {"type": "string"}}}},
+    {"name": "source_trace", "description": "Return evidence links for a semantic node.", "inputSchema": {"type": "object", "properties": {"id": {"type": "string"}, "preset": {"type": "string"}}, "required": ["id"]}},
+    {"name": "extract_entities", "description": "Extract operations entities from the configured root.", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "audit_graph_quality", "description": "Score graph readability and citation health.", "inputSchema": {"type": "object", "properties": {"preset": {"type": "string"}}}},
+    {"name": "detect_missing_citations", "description": "Find semantic nodes without evidence.", "inputSchema": {"type": "object", "properties": {"preset": {"type": "string"}}}},
+    {"name": "compare_invoice_to_bank_draw", "description": "Detect invoice and bank draw mismatches from extracted entities.", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "detect_schedule_shipping_risk", "description": "Detect shipment and schedule risk language.", "inputSchema": {"type": "object", "properties": {}}},
+]
+
+
+def main() -> None:
+    client = CumulusKnowledge(root=os.environ.get("CUMULUS_ROOT", os.getcwd()))
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            request = json.loads(line)
+            if "id" not in request:
+                continue
+            result = handle(client, request.get("method", ""), request.get("params") or {})
+            write({"jsonrpc": "2.0", "id": request["id"], "result": result})
+        except Exception as exc:
+            write({"jsonrpc": "2.0", "id": request.get("id") if "request" in locals() else None, "error": {"code": -32603, "message": str(exc)}})
+
+
+def handle(client: CumulusKnowledge, method: str, params: dict[str, Any]) -> Any:
+    if method == "initialize":
+        return {
+            "protocolVersion": "2025-06-18",
+            "serverInfo": {"name": "cls-knowledge", "version": "0.1.0"},
+            "capabilities": {"tools": {}, "resources": {}, "prompts": {}},
+        }
+    if method == "tools/list":
+        return {"tools": TOOLS}
+    if method == "resources/list":
+        return {"resources": [{"uri": "cumulus://snapshot/current", "name": "Current Graph Snapshot", "mimeType": "application/json"}]}
+    if method != "tools/call":
+        return {}
+
+    name = params.get("name")
+    args = params.get("arguments") or {}
+    if name == "search":
+        return tool_result(client.query(args["query"], limit=args.get("limit", 10)).data)
+    if name == "graph_view":
+        return tool_result(client.get_graph_view(args.get("preset", "full")).data)
+    if name == "fetch":
+        return tool_result(client.get_node(args["id"]).data)
+    if name == "expand_neighbors":
+        return tool_result(client.expand_neighbors(args["id"], args.get("depth", 1)).data)
+    if name == "find_paths":
+        return tool_result(client.find_paths(args["from_id"], args["to_id"], args.get("max_depth", 6)).data)
+    if name == "index_status":
+        return tool_result(client.index_status().data)
+    if name == "ingest":
+        return tool_result(client.index(profile=args.get("profile", "all")).data)
+    if name == "source_trace":
+        view = client.get_graph_view(args.get("preset", "full")).data
+        return tool_result({"node_id": args["id"], "evidence": [item for item in view.get("evidence", []) if item.get("node_id") == args["id"]]})
+    if name == "extract_entities":
+        entities = extract_operations_entities(client.root)
+        return tool_result({"entities": entities, "relationships": build_relationship_candidates(entities)})
+    if name == "audit_graph_quality":
+        view = client.get_graph_view(args.get("preset", "full")).data
+        return tool_result({"readability": score_graph_readability(view), "eval": run_agent_eval("local", view)})
+    if name == "detect_missing_citations":
+        return tool_result(detect_missing_citations(client.get_graph_view(args.get("preset", "full")).data))
+    if name == "compare_invoice_to_bank_draw":
+        return tool_result(compare_invoice_to_bank_draw(extract_operations_entities(client.root)))
+    if name == "detect_schedule_shipping_risk":
+        return tool_result(detect_schedule_shipping_risk(extract_operations_entities(client.root)))
+    raise ValueError(f"unknown tool: {name}")
+
+
+def tool_result(data: Any) -> dict[str, Any]:
+    return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}], "structuredContent": data}
+
+
+def write(value: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(value) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

cls_knowledge-0.1.0/cumulus_knowledge/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class AxiEnvelope(Generic[T]):
+    ok: bool
+    data: T
+    meta: dict[str, Any]
+    links: list[dict[str, Any]]
+    error: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "AxiEnvelope[Any]":
+        return cls(
+            ok=bool(value.get("ok")),
+            data=value.get("data"),
+            meta=dict(value.get("meta") or {}),
+            links=list(value.get("links") or []),
+            error=value.get("error"),
+        )

cls_knowledge-0.1.0/cumulus_knowledge/operations.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from .client import CumulusKnowledge
+
+
+ENTITY_PATTERNS: dict[str, re.Pattern[str]] = {
+    "invoice": re.compile(r"\b(?:invoice|inv)[:#\s-]+([A-Z0-9-]{3,})", re.I),
+    "bank_draw": re.compile(r"\b(?:draw request|bank draw|draw)[:#\s-]+(.+)", re.I),
+    "vendor": re.compile(r"\b(?:vendor|contractor)[:\s-]+(.+)", re.I),
+    "supplier": re.compile(r"\bsupplier[:\s-]+(.+)", re.I),
+    "client": re.compile(r"\b(?:client|owner)[:\s-]+(.+)", re.I),
+    "bank": re.compile(r"\b(?:bank|lender)\s*:\s*(.+)", re.I),
+}
+
+
+def upload_project(path_or_zip: str | Path, root: str | Path | None = None) -> dict[str, Any]:
+    target = Path(root or path_or_zip)
+    client = CumulusKnowledge(root=target)
+    init = client.init()
+    return {"root": str(target), "init": init.data}
+
+
+def extract_operations_entities(path: str | Path) -> list[dict[str, Any]]:
+    root = Path(path)
+    entities: list[dict[str, Any]] = []
+    for file in root.rglob("*"):
+        if not file.is_file() or ".cumulus" in file.parts:
+            continue
+        try:
+            text = file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            compact = line.strip().strip("-*# ")
+            if not compact:
+                continue
+            for kind, pattern in ENTITY_PATTERNS.items():
+                match = pattern.search(compact)
+                if match:
+                    entities.append(entity(kind, match.group(1), file, line_no, compact))
+            lower = compact.lower()
+            if any(term in lower for term in ("shipment", "shipping", "delivery")):
+                entities.append(entity("shipment", compact, file, line_no, compact))
+            if any(term in lower for term in ("milestone", "inspection", "phase ")):
+                entities.append(entity("milestone", compact, file, line_no, compact))
+            if any(term in lower for term in ("risk", "delay", "overdue", "blocked")):
+                entities.append(entity("risk", compact, file, line_no, compact))
+            if any(term in lower for term in ("conflict", "mismatch", "does not match")):
+                entities.append(entity("conflict", compact, file, line_no, compact))
+    return entities
+
+
+def build_relationship_candidates(docs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    by_path: dict[str, list[dict[str, Any]]] = {}
+    for item in docs:
+        by_path.setdefault(str(item.get("path")), []).append(item)
+    relationships: list[dict[str, Any]] = []
+    for path, items in by_path.items():
+        for left in items:
+            for right in items:
+                if left is right or left["kind"] == right["kind"]:
+                    continue
+                relationships.append({
+                    "from": left["id"],
+                    "to": right["id"],
+                    "kind": relation_kind(left["kind"], right["kind"]),
+                    "path": path,
+                    "confidence": 0.54,
+                })
+    return relationships
+
+
+def score_graph_readability(graph_view: dict[str, Any]) -> dict[str, Any]:
+    nodes = graph_view.get("nodes", [])
+    labels = [node.get("display_label", "") for node in nodes]
+    chunk_labels = [label for label in labels if str(label).startswith("chunk_")]
+    long_labels = [label for label in labels if len(str(label)) > 96]
+    legend_count = len(graph_view.get("legend", {}).get("node_kinds", []))
+    score = 1.0
+    score -= min(0.4, len(chunk_labels) * 0.08)
+    score -= min(0.25, len(long_labels) * 0.04)
+    if legend_count == 0:
+        score -= 0.2
+    return {
+        "score": round(max(0.0, score), 3),
+        "node_count": len(nodes),
+        "chunk_label_count": len(chunk_labels),
+        "long_label_count": len(long_labels),
+        "legend_count": legend_count,
+        "passed": score >= 0.8 and not chunk_labels,
+    }
+
+
+def run_agent_eval(project_id: str, graph_view: dict[str, Any] | None = None) -> dict[str, Any]:
+    readability = score_graph_readability(graph_view or {"nodes": [], "legend": {"node_kinds": []}})
+    return {
+        "project_id": project_id,
+        "passed": readability["passed"],
+        "score": readability["score"],
+        "checks": {
+            "readability": readability,
+            "citations_present": bool((graph_view or {}).get("evidence")),
+        },
+    }
+
+
+def detect_missing_citations(graph_view: dict[str, Any]) -> list[dict[str, Any]]:
+    evidence_by_node = {item.get("node_id") for item in graph_view.get("evidence", [])}
+    return [
+        {"node_id": node.get("id"), "label": node.get("display_label"), "issue": "missing citation"}
+        for node in graph_view.get("nodes", [])
+        if node.get("id") not in evidence_by_node and node.get("domain_kind") not in {"project", "folder"}
+    ]
+
+
+def compare_invoice_to_bank_draw(entities: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    invoices = [item for item in entities if item["kind"] == "invoice"]
+    draws = [item for item in entities if item["kind"] == "bank_draw"]
+    if invoices and not draws:
+        return [{"severity": "high", "issue": "invoice without bank draw evidence", "invoice_count": len(invoices)}]
+    return []
+
+
+def detect_schedule_shipping_risk(entities: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    shipments = [item for item in entities if item["kind"] == "shipment"]
+    risks = [item for item in entities if item["kind"] == "risk"]
+    return [
+        {"severity": "medium", "issue": "shipping item has risk language", "shipment": item["label"]}
+        for item in shipments
+        if any(term in item["line"].lower() for term in ("delay", "blocked", "overdue"))
+    ] + [{"severity": "medium", "issue": "schedule risk found", "risk": item["label"]} for item in risks]
+
+
+def entity(kind: str, label: str, file: Path, line_no: int, line: str) -> dict[str, Any]:
+    clean = label.strip().strip(":#- ")
+    return {
+        "id": f"{kind}:{slug(clean)}:{line_no}",
+        "kind": kind,
+        "label": clean[:120],
+        "path": str(file),
+        "line_no": line_no,
+        "line": line,
+    }
+
+
+def relation_kind(left: str, right: str) -> str:
+    pair = {left, right}
+    if "invoice" in pair and "vendor" in pair:
+        return "billed_by"
+    if "bank_draw" in pair and "bank" in pair:
+        return "paid_by"
+    if "shipment" in pair and "supplier" in pair:
+        return "ships"
+    if "risk" in pair:
+        return "risks"
+    return "mentions"
+
+
+def slug(value: str) -> str:
+    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", value.lower())).strip("-")
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("path")
+    args = parser.parse_args()
+    entities = extract_operations_entities(args.path)
+    print(json.dumps({"entities": entities, "relationships": build_relationship_candidates(entities)}, indent=2))

cls_knowledge-0.1.0/cumulus_knowledge/tui.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from .operations import (
+    compare_invoice_to_bank_draw,
+    detect_schedule_shipping_risk,
+    extract_operations_entities,
+)
+
+
+def main() -> None:
+    if "--ops-review" in sys.argv:
+        path = sys.argv[sys.argv.index("--ops-review") + 1] if sys.argv[-1] != "--ops-review" else "."
+        entities = extract_operations_entities(path)
+        invoice_issues = compare_invoice_to_bank_draw(entities)
+        shipping_risks = detect_schedule_shipping_risk(entities)
+        print("Cumulus Operations Review")
+        print(f"entities: {len(entities)}")
+        print(f"invoice/payment issues: {len(invoice_issues)}")
+        print(f"shipping/schedule risks: {len(shipping_risks)}")
+        for item in [*invoice_issues, *shipping_risks][:12]:
+            print(f"- {item}")
+        return
+    try:
+        subprocess.run(["cumulus", "knowledge", *sys.argv[1:]], check=True)
+    except FileNotFoundError:
+        print("cls-knowledge binary was not found. Build it with `cargo build --release`.", file=sys.stderr)
+        raise SystemExit(1)
+    except subprocess.CalledProcessError as exc:
+        print({"ok": False, "error": str(exc)}, file=sys.stderr)
+        raise SystemExit(exc.returncode)

cls_knowledge-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "cls-knowledge"
+version = "0.1.0"
+description = "Python SDK and MCP server for Cumulus Knowledge"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "AGPL-3.0-only"
+authors = [{ name = "Cumulus Knowledge contributors" }]
+dependencies = []
+keywords = ["knowledge-graph", "mcp", "cli", "agents", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Text Processing :: Indexing",
+]
+
+[project.urls]
+Homepage = "https://cumulush.com"
+Repository = "https://github.com/Cumulus-s/cumulus-create"
+
+[project.optional-dependencies]
+tui = ["textual>=6.0.0"]
+test = ["pytest>=9.0.0"]
+
+[project.scripts]
+cls-knowledge-mcp = "cumulus_knowledge.mcp_server:main"
+cls-knowledge-tui = "cumulus_knowledge.tui:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cumulus_knowledge"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"

cls_knowledge-0.1.0/tests/test_models.py

@@ -0,0 +1,52 @@
+import unittest
+
+from cumulus_knowledge.models import AxiEnvelope
+from cumulus_knowledge.operations import (
+    build_relationship_candidates,
+    detect_schedule_shipping_risk,
+    extract_operations_entities,
+    score_graph_readability,
+)
+
+
+class EnvelopeTests(unittest.TestCase):
+    def test_envelope_from_dict(self) -> None:
+        envelope = AxiEnvelope.from_dict({"ok": True, "data": {"id": "node_1"}, "meta": {"command": "x"}, "links": []})
+        self.assertTrue(envelope.ok)
+        self.assertEqual(envelope.data["id"], "node_1")
+        self.assertEqual(envelope.meta["command"], "x")
+
+
+class OperationsTests(unittest.TestCase):
+    def test_extracts_operations_entities_and_scores_graph(self) -> None:
+        with self.subTest("entities"):
+            import tempfile
+            from pathlib import Path
+
+            with tempfile.TemporaryDirectory() as tmp:
+                root = Path(tmp)
+                (root / "finance.md").write_text(
+                    "Invoice DEMO-INV-001\nBank: Atlas Demo Bank\nDraw Request: Bank Draw Request #2\nVendor: BrightSteel Demo Supply\nSteel delivery delayed\n",
+                    encoding="utf-8",
+                )
+                entities = extract_operations_entities(root)
+                kinds = {item["kind"] for item in entities}
+                self.assertIn("invoice", kinds)
+                self.assertIn("bank", kinds)
+                self.assertIn("bank_draw", kinds)
+                self.assertIn("vendor", kinds)
+                self.assertTrue(any(item["label"] == "Bank Draw Request #2" for item in entities))
+                self.assertFalse(any(item["kind"] == "bank" and "Draw Request" in item["label"] for item in entities))
+                self.assertTrue(build_relationship_candidates(entities))
+                self.assertTrue(detect_schedule_shipping_risk(entities))
+        with self.subTest("readability"):
+            score = score_graph_readability({
+                "nodes": [{"display_label": "Invoice DEMO-INV-001"}],
+                "legend": {"node_kinds": [{"kind": "invoice"}]},
+                "evidence": [{"node_id": "n1"}],
+            })
+            self.assertTrue(score["passed"])
+
+
+if __name__ == "__main__":
+    unittest.main()