toolgraph 0.0.1__py3-none-any.whl

toolgraph/models.py

@@ -0,0 +1,192 @@
+"""Pydantic models: crawl inputs/outputs and authored-governance records.
+
+Two families:
+- Crawler config + factual crawl results.
+- Authored governance (policies, ACL grants, data access) — used by manifest
+  ingest, defined here so the schema lives in one place.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+Transport = Literal["stdio", "streamable-http", "sse"]
+
+
+def _no_key_delimiter(kind: str, value: str) -> str:
+    # "::" is the Tool-key delimiter ("<server>::<tool>"). A component that
+    # contains it collapses distinct identities onto one key — e.g.
+    # (server="a", tool="b::c") and (server="a::b", tool="c") MERGE the same
+    # node — and the ecosystem bundle schema requires exactly one delimiter.
+    if "::" in value:
+        raise ValueError(f"{kind} must not contain '::' (the tool-key delimiter)")
+    return value
+
+
+class StrictInputModel(BaseModel):
+    """Base for operator-authored input: unknown fields are always errors."""
+
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+
+# --- crawler config (servers.yaml) ---------------------------------------
+
+
+class ServerSpec(StrictInputModel):
+    """One MCP server to crawl."""
+
+    name: str | None = None  # override; else taken from serverInfo.name
+    transport: Transport = "stdio"
+
+    @field_validator("name")
+    @classmethod
+    def _name_is_key_safe(cls, value: str | None) -> str | None:
+        return value if value is None else _no_key_delimiter("server name", value)
+    # stdio
+    command: str | None = None
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] = Field(default_factory=dict)
+    # http / sse
+    url: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+
+class ServersConfig(StrictInputModel):
+    servers: list[ServerSpec] = Field(default_factory=list)
+
+
+# --- factual crawl results (EXPOSES / PROVIDES) --------------------------
+
+
+class ToolRecord(BaseModel):
+    name: str
+    description: str | None = None
+
+    @field_validator("name")
+    @classmethod
+    def _name_is_key_safe(cls, value: str) -> str:
+        return _no_key_delimiter("tool name", value)
+    input_schema: dict | None = None
+    # MCP tool annotations (ADR-0006): the server's self-claims about its own
+    # behavior. Crawlable, but unverified by anyone — they surface with
+    # ``confidence: medium``, never ``high`` like EXPOSES/PROVIDES.
+    read_only_hint: bool | None = None
+    destructive_hint: bool | None = None
+    idempotent_hint: bool | None = None
+    open_world_hint: bool | None = None
+
+
+class ResourceRecord(BaseModel):
+    uri: str
+    name: str | None = None
+    mime_type: str | None = None
+    description: str | None = None
+
+
+class CrawlResult(BaseModel):
+    server_name: str
+    server_version: str | None = None
+
+    @field_validator("server_name")
+    @classmethod
+    def _server_name_is_key_safe(cls, value: str) -> str:
+        return _no_key_delimiter("server name", value)
+    transport: Transport = "stdio"
+    endpoint: str | None = None  # command line or url, for provenance
+    tools: list[ToolRecord] = Field(default_factory=list)
+    resources: list[ResourceRecord] = Field(default_factory=list)
+
+
+# --- authored governance (governance.yaml) -------------------------------
+
+
+# Provenance — per-edge metadata so a reader can tell crawled facts from
+# operator assertions, and find the supporting evidence for each assertion.
+# Default for authored edges is operator_asserted/high with no evidence link;
+# the loader sets crawled/high/<endpoint> on EXPOSES/PROVIDES.
+ProvenanceSource = Literal["crawled", "operator_asserted", "inferred"]
+ProvenanceConfidence = Literal["high", "medium", "low"]
+
+
+class Provenance(StrictInputModel):
+    """Where an edge came from and how strong the claim is."""
+
+    source: ProvenanceSource = "operator_asserted"
+    confidence: ProvenanceConfidence = "high"
+    # free-text pointer: file:line, URL, commit SHA, ticket id, runtime trace.
+    evidence: str | None = None
+
+
+class Policy(StrictInputModel):
+    # ``extra='forbid'`` catches old manifests that still carry a node-level
+    # ``provenance:`` block (the pre-completion-round shape) with a clear
+    # Pydantic error pointing at the field, instead of silently ignoring it.
+    # The replacement lives on GovernedByBinding (per-edge provenance).
+    id: str
+    effect: Literal["ALLOW", "DENY"]
+    scope: str | None = None
+    description: str | None = None
+
+
+class AccessGrant(StrictInputModel):
+    """Agent -[:CAN_CALL]-> Tool. Tool referenced as '<server>::<tool>' or '<tool>'."""
+
+    agent: str
+    tool: str
+    granted_by: str | None = None
+    provenance: Provenance | None = None
+
+
+class DataAccess(StrictInputModel):
+    """Tool -[:READS|WRITES]-> Resource."""
+
+    tool: str
+    resource: str  # resource uri
+    mode: Literal["READS", "WRITES"]
+    provenance: Provenance | None = None
+
+
+class ExpectedException(StrictInputModel):
+    """Operator-declared exception: this (agent, tool, resource?, policy) reach
+    is intentional — surface it as ``authorized_but_governed`` rather than
+    ``violation`` so reviewers don't drown in noise on by-design grants."""
+
+    agent: str
+    tool: str  # '<server>::<tool>' or bare name (same resolution rules as grants)
+    policy: str
+    resource: str | None = None  # narrow to a specific resource; None = any
+    reason: str | None = None
+
+
+class GovernedByBinding(StrictInputModel):
+    """One (node, policy) binding with optional evidence.
+
+    Lets authors cite WHY this resource (or tool) is bound to this policy —
+    e.g. a config file, a runbook, a compliance ticket. Bare strings in
+    ``governed_by`` lists are still accepted and lift to this shape with
+    ``provenance=None``.
+    """
+
+    policy: str
+    provenance: Provenance | None = None
+
+
+class Governance(StrictInputModel):
+    agents: list[str] = Field(default_factory=list)
+    policies: list[Policy] = Field(default_factory=list)
+    grants: list[AccessGrant] = Field(default_factory=list)
+    data_access: list[DataAccess] = Field(default_factory=list)
+    # node id -> list of bindings. Each item is either a bare policy_id string
+    # (backward-compatible, no provenance) or a GovernedByBinding object with
+    # per-binding source citation. node id is a resource uri or '<server>::<tool>'.
+    governed_by: dict[str, list[str | GovernedByBinding]] = Field(default_factory=dict)
+    expected_exceptions: list[ExpectedException] = Field(default_factory=list)
+
+
+def edge_provenance_props(p: Provenance | None) -> dict:
+    """Default to operator_asserted/high when authoring code omits provenance."""
+    if p is None:
+        return {"source": "operator_asserted", "confidence": "high", "evidence": None}
+    return p.model_dump()

toolgraph/policy_bundle.py

@@ -0,0 +1,212 @@
+"""Portable, product-neutral policy bundle compiler.
+
+The bundle is a control-plane artifact.  It contains deterministic policy
+decisions and crawl contract fingerprints, but no proxy/runtime behavior.
+memtomem-stm is the first reference consumer; independent gateways can consume
+the same schema without importing Toolgraph Python code.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import datetime, timezone
+from typing import Any
+
+from toolgraph.artifacts import (
+    canonical_json_bytes,
+    rfc3339_offset_error,
+    sha256_bytes,
+)
+from toolgraph.graph import queries, selector
+from toolgraph.graph.store import GraphReader, RuntimeGraphStore
+from toolgraph.artifact_safety import safe_artifact, validate_identity
+
+SCHEMA_VERSION = 1
+KIND = "toolgraph.policy-bundle"
+
+
+class PolicyBundleError(RuntimeError):
+    """The graph cannot produce a trustworthy policy bundle."""
+
+
+def tool_contract_digest(contract: dict[str, Any]) -> str:
+    fields = {
+        key: contract.get(key)
+        for key in (
+            "server",
+            "name",
+            "description",
+            "input_schema",
+            "read_only_hint",
+            "destructive_hint",
+            "idempotent_hint",
+            "open_world_hint",
+        )
+    }
+    return sha256_bytes(canonical_json_bytes(fields))
+
+
+def _catalog_digest(contracts: list[dict[str, Any]]) -> str:
+    rows = [
+        {
+            "tool_key": row["tool_key"],
+            "tool_contract_digest": tool_contract_digest(row),
+        }
+        for row in contracts
+    ]
+    return sha256_bytes(canonical_json_bytes(rows))
+
+
+def build_policy_bundle(
+    *,
+    agent: str,
+    profile: str = selector.DEFAULT_PROFILE,
+    created_at: datetime | None = None,
+    store: GraphReader | None = None,
+) -> dict[str, Any]:
+    """Compile every currently exposed qualified tool under one policy profile."""
+    validate_identity(agent)
+    if not agent.strip():
+        raise PolicyBundleError("agent must not be empty")
+    if profile not in selector.PROFILES:
+        raise PolicyBundleError(
+            f"unknown profile {profile!r} — expected one of {sorted(selector.PROFILES)}"
+        )
+    if created_at is not None:
+        problem = rfc3339_offset_error(created_at)
+        if problem:
+            raise PolicyBundleError(problem)
+
+    reader = store if store is not None else RuntimeGraphStore()
+
+    def fetch() -> dict[str, Any]:
+        state = reader.state()
+        contracts = sorted(reader.exposed_tool_contracts(), key=lambda row: row["tool_key"])
+        for contract in contracts:
+            validate_identity(contract["tool_key"])
+        # Consumers key decisions by tool_key and may reject the whole bundle
+        # on a duplicate (the schema's tools description makes this normative),
+        # so failing compilation here is strictly better than shipping one.
+        duplicates = sorted(
+            key
+            for key, count in Counter(row["tool_key"] for row in contracts).items()
+            if count > 1
+        )
+        if duplicates:
+            raise PolicyBundleError(
+                f"duplicate tool_key rows in exposed catalog: {', '.join(duplicates)}"
+                " — repair the graph (e.g. multiple EXPOSES edges per tool) before"
+                " compiling"
+            )
+        candidates = [row["tool_key"] for row in contracts]
+        # One graph evaluation per bounded chunk when the adapter supports
+        # it: the hard filter is a pure function over the ranked features
+        # (ADR-0005), so compiling must not run the full selector pass twice
+        # per bracket attempt. Adapters without ``evaluate`` keep the original
+        # two-call contract — their rank rows never promised selector-internal
+        # fields, so we must not filter them ourselves.
+        evaluate = getattr(reader, "evaluate", None)
+        filtered = {"eligible": [], "rejected": []}
+        features = []
+        # The empty catalog still evaluates identity once. Every chunk is
+        # inside the same bracket; a state change retries the entire catalog.
+        chunks = [
+            candidates[i:i + selector.MAX_CANDIDATES]
+            for i in range(0, len(candidates), selector.MAX_CANDIDATES)
+        ] or [[]]
+        for chunk in chunks:
+            if evaluate is not None:
+                evaluated = evaluate(agent, chunk, profile)
+                if not evaluated["agent_found"]:
+                    raise PolicyBundleError(f"agent {agent!r} not found in the graph")
+                decisions = evaluated["filtered"]
+                rows = evaluated["features"]
+            else:
+                decisions = reader.eligible_tools(agent, chunk, profile)
+                ranked = reader.rank_features(agent, chunk)
+                if not decisions["agent_found"] or not ranked["agent_found"]:
+                    raise PolicyBundleError(f"agent {agent!r} not found in the graph")
+                rows = ranked["features"]
+            expected = Counter(chunk)
+            feature_keys = Counter(row.get("tool_key") or row["candidate"] for row in rows)
+            if feature_keys != expected:
+                raise PolicyBundleError(
+                    "selector returned no feature row or duplicate/unexpected "
+                    "feature rows for catalog"
+                )
+            decision_keys = Counter(decisions["eligible"])
+            decision_keys.update(
+                row.get("tool_key") or row["candidate"]
+                for row in decisions["rejected"]
+            )
+            if decision_keys != expected:
+                raise PolicyBundleError("selector returned missing, duplicate, or conflicting decisions")
+            filtered["eligible"].extend(decisions["eligible"])
+            filtered["rejected"].extend(decisions["rejected"])
+            features.extend(rows)
+        return {
+            "governance_digest": state.governance_digest,
+            "contracts": contracts,
+            "filtered": filtered,
+            "features": features,
+        }
+
+    compiled = queries.with_graph_state(fetch, strict=True, state_reader=reader.state)
+    graph_state = compiled["graph_state"]
+    if not isinstance(graph_state.get("instance_id"), str) or not graph_state["instance_id"]:
+        raise PolicyBundleError(
+            "graph has no instance id — run init-schema before compiling"
+        )
+    governance_digest = compiled["governance_digest"]
+    if not governance_digest:
+        raise PolicyBundleError(
+            "graph has no governance digest — re-run ingest-manifest before compiling"
+        )
+
+    rejected = {
+        row.get("tool_key") or row["candidate"]: row
+        for row in compiled["filtered"]["rejected"]
+    }
+    features = {
+        row.get("tool_key") or row["candidate"]: row
+        for row in compiled["features"]
+    }
+    tools: list[dict[str, Any]] = []
+    for contract in compiled["contracts"]:
+        key = contract["tool_key"]
+        rejection = rejected.get(key)
+        feature = features.get(key)
+        if feature is None:
+            # Both passes ran inside one graph-state bracket, so every catalog
+            # key must have a feature row; a miss means the selector contract
+            # broke — fail as a typed compile error, not a KeyError traceback.
+            raise PolicyBundleError(
+                f"selector returned no feature row for catalog tool {key!r}"
+            )
+        item: dict[str, Any] = {
+            "tool_key": key,
+            "tool_contract_digest": tool_contract_digest(contract),
+            "decision": "rejected" if rejection else "eligible",
+            "risk_score": feature["risk_score"],
+        }
+        if rejection:
+            item["reason"] = rejection["reason"]
+            if rejection.get("paths"):
+                item["paths"] = rejection["paths"]
+        tools.append(item)
+
+    timestamp = created_at or datetime.now(timezone.utc)
+    return safe_artifact(
+        {
+            "schema_version": SCHEMA_VERSION,
+            "kind": KIND,
+            "created_at": timestamp.isoformat(),
+            "graph_state": compiled["graph_state"],
+            "agent": agent,
+            "agent_found": True,
+            "profile": profile,
+            "governance_digest": governance_digest,
+            "catalog_digest": _catalog_digest(compiled["contracts"]),
+            "tools": tools,
+        }
+    )

toolgraph/policy_review.py

@@ -0,0 +1,97 @@
+"""Non-mutating bridge from accepted Tracegraph evidence to policy work.
+
+Trace failures are observations, not authorization facts.  This compiler makes
+the hand-off explicit: it binds accepted human review dispositions to the
+current graph decision and produces a private work-plan artifact.  Applying a
+change still requires editing and ingesting an authored governance manifest.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from toolgraph.artifacts import rfc3339_offset_error
+from toolgraph.artifact_safety import safe_artifact, validate_identity
+from toolgraph.graph import queries, selector
+from toolgraph.review_candidates import ReviewCandidateError, list_candidates
+
+SCHEMA_VERSION = 1
+KIND = "toolgraph.policy-review-plan"
+
+
+class PolicyReviewPlanError(RuntimeError):
+    """Accepted evidence cannot be projected onto a trustworthy graph state."""
+
+
+def build_policy_review_plan(
+    *,
+    report: Path,
+    agent: str,
+    profile: str = selector.DEFAULT_PROFILE,
+    annotations: Path | None = None,
+    created_at: datetime | None = None,
+) -> dict[str, Any]:
+    """Bind accepted Tracegraph candidates to current Toolgraph decisions."""
+    validate_identity(agent)
+    if created_at is not None and (problem := rfc3339_offset_error(created_at)):
+        raise PolicyReviewPlanError(problem)
+    if not agent.strip():
+        raise PolicyReviewPlanError("agent must not be empty")
+    if profile not in selector.PROFILES:
+        raise PolicyReviewPlanError(f"unknown profile {profile!r}")
+    try:
+        reviewed = list_candidates(
+            report, annotations_path=annotations, status="accepted"
+        )
+    except ReviewCandidateError as exc:
+        raise PolicyReviewPlanError(str(exc)) from exc
+    accepted = reviewed["candidates"]
+    if not accepted:
+        raise PolicyReviewPlanError("the review report has no accepted candidates")
+
+    tool_keys = sorted({row["tool_key"] for row in accepted})
+
+    def fetch() -> dict[str, Any]:
+        verdict = selector.eligible_tools(agent, tool_keys, profile)
+        if not verdict["agent_found"]:
+            raise PolicyReviewPlanError(f"agent {agent!r} not found in the graph")
+        return verdict
+
+    compiled = queries.with_graph_state(fetch, strict=True)
+    rejected = {
+        row.get("tool_key") or row["candidate"]: row
+        for row in compiled["rejected"]
+    }
+    candidates = []
+    for row in accepted:
+        rejection = rejected.get(row["tool_key"])
+        candidates.append(
+            {
+                "candidate_id": row["candidate_id"],
+                "run_id": row["run_id"],
+                "pattern_id": row["pattern_id"],
+                "pattern_version": row["pattern_version"],
+                "tool_key": row["tool_key"],
+                "artifact_digest": row["artifact_digest"],
+                "current_decision": "rejected" if rejection else "eligible",
+                "current_reason": rejection.get("reason") if rejection else None,
+                "current_paths": rejection.get("paths", []) if rejection else [],
+                "recommended_action": "review_governance_manifest",
+                "automatic_change": False,
+            }
+        )
+
+    timestamp = created_at or datetime.now(timezone.utc)
+    return safe_artifact({
+        "schema_version": SCHEMA_VERSION,
+        "kind": KIND,
+        "created_at": timestamp.isoformat(),
+        "source_report_digest": reviewed["source_report_digest"],
+        "graph_state": compiled["graph_state"],
+        "agent": agent,
+        "profile": profile,
+        "decision_mode": "human_required",
+        "candidates": candidates,
+    })

toolgraph/preflight.py

@@ -0,0 +1,77 @@
+"""Deterministic advisory preflight artifact production."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from toolgraph.artifacts import rfc3339_offset_error
+from toolgraph.artifact_safety import safe_artifact, validate_identity
+from toolgraph.artifact_safety import redact as redact
+
+from toolgraph.graph import queries, selector
+
+SCHEMA_VERSION = 1
+KIND = "toolgraph.preflight"
+
+def build_preflight(
+    *,
+    agent: str,
+    candidates: list[str],
+    profile: str,
+    run_id: str,
+    include_features: bool = False,
+    created_at: datetime | None = None,
+) -> dict:
+    """Build one schema-v1 advisory verdict over a bracketed graph state."""
+    for identity in [agent, run_id, *candidates]:
+        validate_identity(identity)
+    if created_at is not None and (problem := rfc3339_offset_error(created_at)):
+        raise ValueError(problem)
+    if not run_id:
+        raise ValueError("run_id must not be empty")
+    if profile not in selector.PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r} — expected one of {sorted(selector.PROFILES)}"
+        )
+
+    def fetch() -> dict:
+        # One graph evaluation: the filter is a pure function over the ranked
+        # features, so --features must not pay a second full pass.
+        ranked = selector.rank_features(agent, candidates)
+        filtered = selector.filter_features(ranked, profile)
+        result = {
+            "agent": agent,
+            "agent_found": filtered["agent_found"],
+            "profile": profile,
+            "eligible": filtered["eligible"],
+            "rejected": filtered["rejected"],
+        }
+        if include_features:
+            result["features"] = ranked["features"]
+        return result
+
+    verdict = queries.with_graph_state(fetch, strict=True)
+    if not verdict["agent_found"]:
+        decision = "unresolved_identity"
+    elif verdict["rejected"]:
+        decision = "advisory_warn"
+    else:
+        decision = "advisory_allow"
+    timestamp = created_at or datetime.now(timezone.utc)
+    artifact = {
+        "schema_version": SCHEMA_VERSION,
+        "kind": KIND,
+        "run_id": run_id,
+        "created_at": timestamp.isoformat(),
+        "graph_generation": verdict["graph_generation"],
+        "graph_instance_id": verdict["graph_instance_id"],
+        "graph_state": verdict["graph_state"],
+        "agent": agent,
+        "agent_found": verdict["agent_found"],
+        "profile": profile,
+        "mode": "advisory",  # v1 emits advisory artifacts only
+        "eligible": verdict["eligible"],
+        "rejected": verdict["rejected"],
+        "features": verdict.get("features", []),
+    }
+    artifact["decision"] = decision
+    return safe_artifact(artifact)

toolgraph/quickstart/governance.yaml

@@ -0,0 +1,28 @@
+agents:
+  - vibe-coder
+
+policies:
+  - id: draft-publish-deny
+    effect: DENY
+    scope: demo-drafts
+    description: Publishing demo drafts requires an explicit policy review.
+
+grants:
+  - agent: vibe-coder
+    tool: "policy-gateway::read_note"
+    granted_by: quickstart
+  - agent: vibe-coder
+    tool: "policy-gateway::publish_note"
+    granted_by: quickstart
+
+data_access:
+  - tool: "policy-gateway::read_note"
+    resource: "file:///demo/notes"
+    mode: READS
+  - tool: "policy-gateway::publish_note"
+    resource: "file:///demo/drafts"
+    mode: WRITES
+
+governed_by:
+  "file:///demo/drafts":
+    - draft-publish-deny

toolgraph/quickstart/policy_gateway_server.py

@@ -0,0 +1,31 @@
+"""Deterministic, local-only MCP server for the Toolgraph quickstart."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+
+def build() -> FastMCP:
+    server = FastMCP("policy-gateway")
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True))
+    def read_note(note_id: str) -> str:
+        """Read a deterministic demo note."""
+        return f"note:{note_id}"
+
+    @server.tool(annotations=ToolAnnotations(destructiveHint=True))
+    def publish_note(note_id: str, content: str) -> str:
+        """Publish a demo note to the governed draft area."""
+        return f"published:{note_id}:{len(content)}"
+
+    @server.resource("file:///demo/notes")
+    def notes() -> str:
+        """Describe the deterministic demo note collection."""
+        return "policy-gateway quickstart notes"
+
+    return server
+
+
+if __name__ == "__main__":
+    build().run()

toolgraph/quickstart/servers.yaml

@@ -0,0 +1,5 @@
+servers:
+  - name: policy-gateway
+    transport: stdio
+    command: __TOOLGRAPH_PYTHON__
+    args: ["policy_gateway_server.py"]