contextgraph-sdk 0.1.0__tar.gz

contextgraph_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: contextgraph-sdk
+Version: 0.1.0
+Summary: Zero-dependency Python SDK for building conformant Context Graph Protocol providers.
+License: MIT OR Apache-2.0
+Project-URL: Homepage, https://github.com/macanderson/context-graph-protocol
+Keywords: context-graph-protocol,cgp,context,provider,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# contextgraph-sdk — Python
+
+A zero-dependency (stdlib-only) Python SDK for building **conformant** Context
+Graph Protocol providers. Implement one small interface, hand it to the runtime,
+and you have a provider that speaks the line-oriented JSON wire over stdio and
+passes the same conformance suite that judges the Rust reference provider.
+
+> Third independent implementation (after Rust and TypeScript); passes the full
+> conformance suite. See [`sdk/README.md`](../README.md) for the whole picture.
+
+## Install
+
+> **Not yet published to PyPI.** The command below does not resolve yet — see
+> [`sdk/PUBLISHING.md`](../PUBLISHING.md) for the publish checklist and
+> current status. Until then, install from a checkout: `pip install -e
+> sdk/python` from the repository root.
+
+```sh
+pip install contextgraph-sdk
+```
+
+## Write a provider
+
+```python
+from contextgraph_sdk import run_stdio_provider, budget_tokens
+
+
+class MyDocsProvider:
+    def info(self):
+        # Nothing leaves the machine -> declare the honest local-only egress scope.
+        return {
+            "name": "my-docs-provider",
+            "version": "0.1.0",
+            "data_flow": {"reads": True, "writes": False, "egress": False,
+                          "egress_scopes": ["local-only"]},
+        }
+
+    def capabilities(self):
+        return {"query": {"kinds": ["doc"]}, "correlation": True, "verify": True}
+
+    def query(self, query):
+        content = "Install the binding, then implement the required methods."
+        return {
+            "frames": [{
+                "id": "doc:1", "kind": "doc", "title": "Getting started",
+                "content": content,
+                "content_digest": "sha256:" + ("11" * 32),
+                "score": 0.9,
+                # token_cost MUST equal ceil(utf8_len(content)/4).
+                "token_cost": budget_tokens(content),
+                "valid_from": "2026-01-01T00:00:00Z",
+                "provenance": [{"type": "file", "uri": "file:///docs/start.md",
+                                "range": "L1-10", "digest": "sha256:" + ("11" * 32)}],
+                "citation_label": "start.md L1-10", "relations": [],
+            }],
+            "truncated": False,
+        }
+
+
+run_stdio_provider(MyDocsProvider())
+```
+
+`verify` is optional. The runtime handles the whole lifecycle — handshake, query
+(echoing the correlation `id`), verify, shutdown — and stays alive with a typed
+error on a malformed line rather than crashing.
+
+## Host it over HTTP
+
+The same provider runs behind a single POST endpoint (the streamable-HTTP
+transport, SPEC.md §3) via a WSGI app — runnable on the stdlib server or any WSGI
+host (gunicorn, Flask):
+
+```python
+from wsgiref.simple_server import make_server
+from contextgraph_sdk import make_wsgi_app
+
+make_server("127.0.0.1", 8788, make_wsgi_app(MyDocsProvider())).serve_forever()
+# Flask:           app.wsgi_app = make_wsgi_app(provider)
+# FastAPI (ASGI):  reply with respond_to_body(provider, await request.body()) in your route
+```
+
+`handle_envelope(provider, envelope)` is the transport-free state machine if you
+want to wire it into a framework yourself. A runnable HTTP example lives at
+`examples/example_docs_http.py`; confirm it green with
+`contextgraph-inspect http http://127.0.0.1:8788` (the `malformed-input-tolerance`,
+`embedding-fingerprint`, and `correlation` probes report *skipped* over HTTP —
+they inspect raw framing this transport doesn't expose).
+
+## Prove it conformant
+
+From the repository root, with the Rust bins built:
+
+```sh
+cargo build --workspace --bins
+./.github/scripts/conformance-external.sh -- python3 sdk/python/examples/example_docs.py
+```
+
+A green run is the machine-checkable claim that your provider honors the protocol.
+
+## License
+
+MIT OR Apache-2.0, matching the Context Graph Protocol crates.

contextgraph_sdk-0.1.0/README.md

@@ -0,0 +1,102 @@
+# contextgraph-sdk — Python
+
+A zero-dependency (stdlib-only) Python SDK for building **conformant** Context
+Graph Protocol providers. Implement one small interface, hand it to the runtime,
+and you have a provider that speaks the line-oriented JSON wire over stdio and
+passes the same conformance suite that judges the Rust reference provider.
+
+> Third independent implementation (after Rust and TypeScript); passes the full
+> conformance suite. See [`sdk/README.md`](../README.md) for the whole picture.
+
+## Install
+
+> **Not yet published to PyPI.** The command below does not resolve yet — see
+> [`sdk/PUBLISHING.md`](../PUBLISHING.md) for the publish checklist and
+> current status. Until then, install from a checkout: `pip install -e
+> sdk/python` from the repository root.
+
+```sh
+pip install contextgraph-sdk
+```
+
+## Write a provider
+
+```python
+from contextgraph_sdk import run_stdio_provider, budget_tokens
+
+
+class MyDocsProvider:
+    def info(self):
+        # Nothing leaves the machine -> declare the honest local-only egress scope.
+        return {
+            "name": "my-docs-provider",
+            "version": "0.1.0",
+            "data_flow": {"reads": True, "writes": False, "egress": False,
+                          "egress_scopes": ["local-only"]},
+        }
+
+    def capabilities(self):
+        return {"query": {"kinds": ["doc"]}, "correlation": True, "verify": True}
+
+    def query(self, query):
+        content = "Install the binding, then implement the required methods."
+        return {
+            "frames": [{
+                "id": "doc:1", "kind": "doc", "title": "Getting started",
+                "content": content,
+                "content_digest": "sha256:" + ("11" * 32),
+                "score": 0.9,
+                # token_cost MUST equal ceil(utf8_len(content)/4).
+                "token_cost": budget_tokens(content),
+                "valid_from": "2026-01-01T00:00:00Z",
+                "provenance": [{"type": "file", "uri": "file:///docs/start.md",
+                                "range": "L1-10", "digest": "sha256:" + ("11" * 32)}],
+                "citation_label": "start.md L1-10", "relations": [],
+            }],
+            "truncated": False,
+        }
+
+
+run_stdio_provider(MyDocsProvider())
+```
+
+`verify` is optional. The runtime handles the whole lifecycle — handshake, query
+(echoing the correlation `id`), verify, shutdown — and stays alive with a typed
+error on a malformed line rather than crashing.
+
+## Host it over HTTP
+
+The same provider runs behind a single POST endpoint (the streamable-HTTP
+transport, SPEC.md §3) via a WSGI app — runnable on the stdlib server or any WSGI
+host (gunicorn, Flask):
+
+```python
+from wsgiref.simple_server import make_server
+from contextgraph_sdk import make_wsgi_app
+
+make_server("127.0.0.1", 8788, make_wsgi_app(MyDocsProvider())).serve_forever()
+# Flask:           app.wsgi_app = make_wsgi_app(provider)
+# FastAPI (ASGI):  reply with respond_to_body(provider, await request.body()) in your route
+```
+
+`handle_envelope(provider, envelope)` is the transport-free state machine if you
+want to wire it into a framework yourself. A runnable HTTP example lives at
+`examples/example_docs_http.py`; confirm it green with
+`contextgraph-inspect http http://127.0.0.1:8788` (the `malformed-input-tolerance`,
+`embedding-fingerprint`, and `correlation` probes report *skipped* over HTTP —
+they inspect raw framing this transport doesn't expose).
+
+## Prove it conformant
+
+From the repository root, with the Rust bins built:
+
+```sh
+cargo build --workspace --bins
+./.github/scripts/conformance-external.sh -- python3 sdk/python/examples/example_docs.py
+```
+
+A green run is the machine-checkable claim that your provider honors the protocol.
+
+## License
+
+MIT OR Apache-2.0, matching the Context Graph Protocol crates.

contextgraph_sdk-0.1.0/contextgraph_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""``contextgraph-sdk`` — a zero-dependency Python SDK for building conformant
+Context Graph Protocol providers.
+
+    from contextgraph_sdk import run_stdio_provider, budget_tokens
+
+    class MyProvider:
+        def info(self):
+            return {"name": "my-provider", "version": "0.1.0",
+                    "data_flow": {"reads": True, "writes": False, "egress": False,
+                                  "egress_scopes": ["local-only"]}}
+        def capabilities(self):
+            return {"query": {"kinds": ["doc"]}, "correlation": True}
+        def query(self, query):
+            return {"frames": [], "truncated": False}
+
+    run_stdio_provider(MyProvider())
+"""
+
+from .budget import BYTES_PER_BUDGET_TOKEN, budget_tokens
+from .http import handle_envelope, make_wsgi_app, respond_to_body
+from .provider import Provider, ProviderError, run_stdio_provider
+from .types import PROTOCOL_VERSION
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "BYTES_PER_BUDGET_TOKEN",
+    "budget_tokens",
+    "Provider",
+    "ProviderError",
+    "run_stdio_provider",
+    "handle_envelope",
+    "respond_to_body",
+    "make_wsgi_app",
+]

contextgraph_sdk-0.1.0/contextgraph_sdk/budget.py

@@ -0,0 +1,20 @@
+"""Canonical token accounting (SPEC.md B3).
+
+A budget token is an accounting unit, not a real tokenizer:
+``budget_tokens(content) = ceil(utf8_byte_length(content) / 4)``. A conforming
+provider's ``ContextFrame.token_cost`` MUST equal this for the frame's inline
+content (a ``reference`` frame carries no content, so its required cost is 0).
+"""
+
+from __future__ import annotations
+
+import math
+
+BYTES_PER_BUDGET_TOKEN = 4
+
+
+def budget_tokens(content: str | None) -> int:
+    """The canonical budget-token cost of a piece of frame content."""
+    if not content:
+        return 0
+    return math.ceil(len(content.encode("utf-8")) / BYTES_PER_BUDGET_TOKEN)

contextgraph_sdk-0.1.0/contextgraph_sdk/http.py

@@ -0,0 +1,162 @@
+"""The HTTP adapter: host a provider behind a single POST endpoint, speaking the
+same Context Graph Protocol wire as :func:`run_stdio_provider` -- the "streamable
+HTTP" transport (``SPEC.md`` §3). The host POSTs one envelope as the request body
+and expects one envelope back as the response body; :func:`handle_envelope` is
+that request/response state machine, framework-agnostic so it drops under Flask,
+FastAPI, or any WSGI server.
+
+The one deliberate difference from stdio: an HTTP provider is a long-lived server
+reached by many independent hosts, so a ``shutdown`` envelope ends *that
+exchange* -- it never calls :func:`sys.exit`. (``contextgraph-inspect http`` in
+fact handshakes and shuts down twice per run: once to probe, once to run the
+conformance suite. A server that exited on the first shutdown could not answer
+the second handshake.)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Iterable
+
+from .provider import Provider, ProviderError
+from .types import PROTOCOL_VERSION
+
+
+def handle_envelope(provider: Provider, envelope: dict[str, Any]) -> dict[str, Any] | None:
+    """Drive one request ``envelope`` through ``provider`` and return the one
+    response envelope -- or ``None`` for a ``shutdown`` (and for any
+    host->provider envelope a provider must ignore), which has no reply body.
+
+    This is the whole protocol state machine, transport-free: hand it a decoded
+    envelope from whatever web framework you use and serialize what it returns.
+    It mirrors :func:`run_stdio_provider`'s per-line handling exactly --
+    including echoing a ``query``'s correlation ``id`` (H4) and catching a
+    :class:`ProviderError` into a coded ``error`` envelope (§E1) -- minus the
+    process lifecycle.
+    """
+    kind = envelope.get("type")
+
+    if kind == "handshake":
+        return {
+            "type": "handshake_ack",
+            "protocol_version": PROTOCOL_VERSION,
+            "provider": provider.info(),
+            "capabilities": provider.capabilities(),
+        }
+
+    if kind == "query":
+        echoed = envelope.get("id")
+        try:
+            result = provider.query(envelope["query"])
+        except ProviderError as error:
+            # A deliberate, coded refusal of a request the provider can't
+            # honestly serve (§E1): an error envelope, not frames.
+            reply: dict[str, Any] = {"type": "error", "message": error.message}
+            if error.code is not None:
+                reply["code"] = error.code
+        else:
+            reply = {"type": "frames", "result": result}
+        # Echo the correlation id so the host can match reply to request (H4).
+        if echoed is not None:
+            reply["id"] = echoed
+        return reply
+
+    if kind == "verify":
+        verify = getattr(provider, "verify", None)
+        if callable(verify):
+            response = verify(envelope["request"])
+        else:
+            # No verify support: vouch for nothing; the host re-queries.
+            response = {
+                "verdicts": [
+                    {"frame": frame, "status": "unknown"}
+                    for frame in envelope["request"]["frames"]
+                ]
+            }
+        return {"type": "verified", "response": response}
+
+    # `shutdown` ends the exchange but keeps the server alive for the next host;
+    # handshake_ack / frames / verified / error are host->provider-invalid. Both
+    # have no reply body.
+    return None
+
+
+def respond_to_body(provider: Provider, raw_body: str | bytes) -> tuple[int, str]:
+    """Decode one raw request body, drive it through :func:`handle_envelope`, and
+    return ``(status, body)`` to send back. Use this when your framework hands
+    you the raw body (a FastAPI/Flask route): respond with the status and the
+    JSON string.
+
+    A body that is not a valid CGP envelope is answered ``400`` with a coded
+    ``error`` envelope rather than crashing -- the HTTP mirror of the stdio
+    ``malformed-input-tolerance`` guarantee.
+    """
+    if isinstance(raw_body, (bytes, bytearray)):
+        raw_body = raw_body.decode("utf-8", "replace")
+    try:
+        envelope = json.loads(raw_body)
+    except (json.JSONDecodeError, ValueError):
+        return 400, json.dumps(
+            {
+                "type": "error",
+                "code": "bad_request",
+                "message": "request body was not a valid CGP envelope",
+            },
+            separators=(",", ":"),
+        )
+    if not isinstance(envelope, dict):
+        return 400, json.dumps(
+            {
+                "type": "error",
+                "code": "bad_request",
+                "message": "request body was not a CGP envelope object",
+            },
+            separators=(",", ":"),
+        )
+    reply = handle_envelope(provider, envelope)
+    # `shutdown` (and ignored inputs) has no reply body: 204 No Content.
+    if reply is None:
+        return 204, ""
+    return 200, json.dumps(reply, separators=(",", ":"))
+
+
+def make_wsgi_app(
+    provider: Provider,
+) -> Callable[[dict[str, Any], Callable[..., Any]], Iterable[bytes]]:
+    """Build a WSGI application that answers the CGP protocol on one endpoint --
+    the zero-config path, dependency-free and runnable under the stdlib's
+    ``wsgiref.simple_server`` or any production WSGI server (gunicorn, uWSGI):
+
+    ::
+
+        from wsgiref.simple_server import make_server
+        make_server("127.0.0.1", 8788, make_wsgi_app(provider)).serve_forever()
+
+    It also mounts under Flask (``app.wsgi_app = make_wsgi_app(provider)``) and,
+    since it reads the raw ``wsgi.input`` itself, needs no body parser. Under an
+    ASGI framework like FastAPI, call :func:`respond_to_body` with the request
+    body inside your route instead.
+    """
+
+    def app(
+        environ: dict[str, Any],
+        start_response: Callable[..., Any],
+    ) -> Iterable[bytes]:
+        try:
+            length = int(environ.get("CONTENT_LENGTH") or 0)
+        except (TypeError, ValueError):
+            length = 0
+        raw_body = environ["wsgi.input"].read(length) if length > 0 else b""
+        status_code, body = respond_to_body(provider, raw_body)
+        payload = body.encode("utf-8")
+        reason = {200: "OK", 204: "No Content", 400: "Bad Request"}.get(status_code, "OK")
+        start_response(
+            f"{status_code} {reason}",
+            [
+                ("Content-Type", "application/json"),
+                ("Content-Length", str(len(payload))),
+            ],
+        )
+        return [payload]
+
+    return app

contextgraph_sdk-0.1.0/contextgraph_sdk/provider.py

@@ -0,0 +1,131 @@
+"""The provider runtime.
+
+Implement :class:`Provider` (info / capabilities / query, and optionally verify),
+hand it to :func:`run_stdio_provider`, and you have a conformant Context Graph
+Protocol provider speaking the line-oriented JSON wire over stdio. The runtime
+drives the full lifecycle — handshake, query (echoing the correlation ``id``),
+verify, shutdown — and stays alive with a typed error on a malformed line rather
+than crashing (the ``malformed-input-tolerance`` guarantee).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Protocol, runtime_checkable
+
+from .types import PROTOCOL_VERSION
+
+
+@runtime_checkable
+class Provider(Protocol):
+    """A Context Graph Protocol provider.
+
+    ``query`` is mandatory. ``verify`` is optional — a provider that omits it is
+    treated as unable to vouch for its frames, and the host re-queries.
+    """
+
+    def info(self) -> dict[str, Any]:
+        """Identity and data-flow posture, reported at handshake."""
+        ...
+
+    def capabilities(self) -> dict[str, Any]:
+        """What this provider can do, negotiated at handshake."""
+        ...
+
+    def query(self, query: dict[str, Any]) -> dict[str, Any]:
+        """Answer a retrieval request with budgeted, provenance-carrying frames."""
+        ...
+
+    # def verify(self, request: dict[str, Any]) -> dict[str, Any]: ...  # optional
+
+
+class ProviderError(Exception):
+    """A protocol-level error a provider raises from ``query`` to reply with an
+    ``error`` envelope carrying a machine-readable ``code`` instead of frames.
+
+    This is how a provider refuses a request it cannot honestly serve — e.g.
+    rejecting a query embedding whose length contradicts its declared
+    ``embeddings_fingerprint`` dimension with ``bad_request`` (``SPEC.md`` §E1).
+    The runtime catches it, echoes the request's correlation ``id``, and writes
+    ``{"type": "error", "code": code, "message": message}``.
+    """
+
+    def __init__(self, message: str, code: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+
+
+def _write(envelope: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(envelope, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def run_stdio_provider(provider: Provider) -> None:
+    """Run ``provider`` as a stdio child process — the shape the reference host
+    and the conformance suite drive. One envelope per line in and out, until a
+    ``shutdown`` (or EOF)."""
+    while True:
+        line = sys.stdin.readline()
+        if not line:  # EOF / broken pipe: the host is gone.
+            break
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        try:
+            envelope = json.loads(stripped)
+        except json.JSONDecodeError:
+            # Malformed line: stay alive and say so with a code, don't crash.
+            _write(
+                {
+                    "type": "error",
+                    "code": "bad_request",
+                    "message": "line was not a valid CGP envelope",
+                }
+            )
+            continue
+
+        kind = envelope.get("type")
+        if kind == "handshake":
+            _write(
+                {
+                    "type": "handshake_ack",
+                    "protocol_version": PROTOCOL_VERSION,
+                    "provider": provider.info(),
+                    "capabilities": provider.capabilities(),
+                }
+            )
+        elif kind == "query":
+            # Echo the correlation id so the host can match reply to request (H4).
+            echoed = envelope.get("id")
+            try:
+                result = provider.query(envelope["query"])
+            except ProviderError as error:
+                # The provider refused a request it can't honestly serve (§E1):
+                # reply with a coded error envelope, not frames.
+                reply: dict[str, Any] = {"type": "error", "message": error.message}
+                if error.code is not None:
+                    reply["code"] = error.code
+            else:
+                reply = {"type": "frames", "result": result}
+            if echoed is not None:
+                reply["id"] = echoed
+            _write(reply)
+        elif kind == "verify":
+            verify = getattr(provider, "verify", None)
+            if callable(verify):
+                response = verify(envelope["request"])
+            else:
+                # No verify support: vouch for nothing; the host re-queries.
+                response = {
+                    "verdicts": [
+                        {"frame": frame, "status": "unknown"}
+                        for frame in envelope["request"]["frames"]
+                    ]
+                }
+            _write({"type": "verified", "response": response})
+        elif kind == "shutdown":
+            sys.exit(0)
+        # handshake_ack / frames / verified / error are host->provider-invalid; ignore.

contextgraph_sdk-0.1.0/contextgraph_sdk/types.py

@@ -0,0 +1,127 @@
+"""Context Graph Protocol wire types, mirrored from the JSON Schema.
+
+These are ``TypedDict``s: at runtime a frame or envelope is a plain ``dict`` (the
+wire is JSON), and these give editors and type-checkers the exact shape. Keys
+typed ``Optional``/absent are simply omitted when you have no value — the SDK
+never emits explicit ``null`` for them.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+PROTOCOL_VERSION = "contextgraph/1.0-draft"
+
+FrameKind = Literal["snippet", "symbol", "fact", "doc", "memory", "episode", "graph"]
+Representation = Literal["full", "compact", "reference"]
+ContentFidelity = Literal["exact", "normalized", "summarized", "omitted"]
+VerdictStatus = Literal["valid", "stale", "gone", "unknown"]
+
+
+class Provenance(TypedDict, total=False):
+    type: str  # required; the wire name for "kind"
+    uri: str
+    range: str
+    digest: str
+    method: str
+    by: str
+
+
+class Relation(TypedDict, total=False):
+    rel: str  # required
+    target_uri: str  # required
+    display_name: str
+
+
+class ContentRef(TypedDict, total=False):
+    provider_id: str  # required
+    uri: str  # required
+    expires_at: str
+
+
+class ContextFrame(TypedDict, total=False):
+    id: str  # required
+    kind: FrameKind  # required
+    title: str  # required
+    content: str  # absent for reference frames
+    content_digest: str
+    uri: str
+    representation: Representation
+    content_fidelity: ContentFidelity
+    canonical_content_hash: str
+    content_ref: ContentRef
+    transform: dict[str, str]
+    minimum_content_fidelity: ContentFidelity
+    inline_content_requirement: Literal["required", "resolvable_reference_allowed"]
+    score: float  # required
+    token_cost: int  # required; ceil(utf8_len(content)/4)
+    canonical_token_cost: int
+    tokenizer_ref: str
+    valid_from: str
+    valid_to: str
+    recorded_at: str
+    provenance: list[Provenance]
+    citation_label: str
+    embedding: dict[str, Any]
+    relations: list[Relation]
+
+
+class ContextQuery(TypedDict, total=False):
+    goal: str  # required
+    query_text: str
+    embedding: list[float]
+    kinds: list[FrameKind]
+    anchors: list[str]
+    max_frames: int  # required
+    max_tokens: int  # required
+    as_of: str
+    representation_preferences: list[Representation]
+
+
+class ContextQueryResult(TypedDict, total=False):
+    frames: list[ContextFrame]  # required
+    truncated: bool  # required
+    dropped_estimate: int
+
+
+class DataFlow(TypedDict, total=False):
+    reads: bool  # required
+    writes: bool  # required
+    egress: bool  # required
+    egress_scopes: list[str]
+
+
+class ProviderInfo(TypedDict, total=False):
+    name: str  # required
+    version: str  # required
+    data_flow: DataFlow  # required
+
+
+class Capabilities(TypedDict, total=False):
+    query: dict[str, Any]  # required, e.g. {"kinds": ["doc"]}
+    correlation: bool
+    graph: bool
+    embeddings_fingerprint: str | None
+    verify: bool
+    representations: list[Representation]
+    resolve: bool
+
+
+class FrameId(TypedDict, total=False):
+    provider_id: str  # required
+    frame_id: str  # required
+    content_digest: str
+
+
+class FrameVerdict(TypedDict, total=False):
+    frame: FrameId  # required
+    status: VerdictStatus  # required
+    replacement_digest: str
+
+
+class VerifyRequest(TypedDict, total=False):
+    frames: list[FrameId]  # required
+
+
+class VerifyResponse(TypedDict, total=False):
+    verdicts: list[FrameVerdict]  # required

contextgraph_sdk-0.1.0/contextgraph_sdk.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: contextgraph-sdk
+Version: 0.1.0
+Summary: Zero-dependency Python SDK for building conformant Context Graph Protocol providers.
+License: MIT OR Apache-2.0
+Project-URL: Homepage, https://github.com/macanderson/context-graph-protocol
+Keywords: context-graph-protocol,cgp,context,provider,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# contextgraph-sdk — Python
+
+A zero-dependency (stdlib-only) Python SDK for building **conformant** Context
+Graph Protocol providers. Implement one small interface, hand it to the runtime,
+and you have a provider that speaks the line-oriented JSON wire over stdio and
+passes the same conformance suite that judges the Rust reference provider.
+
+> Third independent implementation (after Rust and TypeScript); passes the full
+> conformance suite. See [`sdk/README.md`](../README.md) for the whole picture.
+
+## Install
+
+> **Not yet published to PyPI.** The command below does not resolve yet — see
+> [`sdk/PUBLISHING.md`](../PUBLISHING.md) for the publish checklist and
+> current status. Until then, install from a checkout: `pip install -e
+> sdk/python` from the repository root.
+
+```sh
+pip install contextgraph-sdk
+```
+
+## Write a provider
+
+```python
+from contextgraph_sdk import run_stdio_provider, budget_tokens
+
+
+class MyDocsProvider:
+    def info(self):
+        # Nothing leaves the machine -> declare the honest local-only egress scope.
+        return {
+            "name": "my-docs-provider",
+            "version": "0.1.0",
+            "data_flow": {"reads": True, "writes": False, "egress": False,
+                          "egress_scopes": ["local-only"]},
+        }
+
+    def capabilities(self):
+        return {"query": {"kinds": ["doc"]}, "correlation": True, "verify": True}
+
+    def query(self, query):
+        content = "Install the binding, then implement the required methods."
+        return {
+            "frames": [{
+                "id": "doc:1", "kind": "doc", "title": "Getting started",
+                "content": content,
+                "content_digest": "sha256:" + ("11" * 32),
+                "score": 0.9,
+                # token_cost MUST equal ceil(utf8_len(content)/4).
+                "token_cost": budget_tokens(content),
+                "valid_from": "2026-01-01T00:00:00Z",
+                "provenance": [{"type": "file", "uri": "file:///docs/start.md",
+                                "range": "L1-10", "digest": "sha256:" + ("11" * 32)}],
+                "citation_label": "start.md L1-10", "relations": [],
+            }],
+            "truncated": False,
+        }
+
+
+run_stdio_provider(MyDocsProvider())
+```
+
+`verify` is optional. The runtime handles the whole lifecycle — handshake, query
+(echoing the correlation `id`), verify, shutdown — and stays alive with a typed
+error on a malformed line rather than crashing.
+
+## Host it over HTTP
+
+The same provider runs behind a single POST endpoint (the streamable-HTTP
+transport, SPEC.md §3) via a WSGI app — runnable on the stdlib server or any WSGI
+host (gunicorn, Flask):
+
+```python
+from wsgiref.simple_server import make_server
+from contextgraph_sdk import make_wsgi_app
+
+make_server("127.0.0.1", 8788, make_wsgi_app(MyDocsProvider())).serve_forever()
+# Flask:           app.wsgi_app = make_wsgi_app(provider)
+# FastAPI (ASGI):  reply with respond_to_body(provider, await request.body()) in your route
+```
+
+`handle_envelope(provider, envelope)` is the transport-free state machine if you
+want to wire it into a framework yourself. A runnable HTTP example lives at
+`examples/example_docs_http.py`; confirm it green with
+`contextgraph-inspect http http://127.0.0.1:8788` (the `malformed-input-tolerance`,
+`embedding-fingerprint`, and `correlation` probes report *skipped* over HTTP —
+they inspect raw framing this transport doesn't expose).
+
+## Prove it conformant
+
+From the repository root, with the Rust bins built:
+
+```sh
+cargo build --workspace --bins
+./.github/scripts/conformance-external.sh -- python3 sdk/python/examples/example_docs.py
+```
+
+A green run is the machine-checkable claim that your provider honors the protocol.
+
+## License
+
+MIT OR Apache-2.0, matching the Context Graph Protocol crates.

contextgraph_sdk-0.1.0/contextgraph_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+contextgraph_sdk/__init__.py
+contextgraph_sdk/budget.py
+contextgraph_sdk/http.py
+contextgraph_sdk/provider.py
+contextgraph_sdk/py.typed
+contextgraph_sdk/types.py
+contextgraph_sdk.egg-info/PKG-INFO
+contextgraph_sdk.egg-info/SOURCES.txt
+contextgraph_sdk.egg-info/dependency_links.txt
+contextgraph_sdk.egg-info/top_level.txt

contextgraph_sdk-0.1.0/contextgraph_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

contextgraph_sdk-0.1.0/contextgraph_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+contextgraph_sdk

contextgraph_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contextgraph-sdk"
+version = "0.1.0"
+description = "Zero-dependency Python SDK for building conformant Context Graph Protocol providers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT OR Apache-2.0" }
+keywords = ["context-graph-protocol", "cgp", "context", "provider", "sdk"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/macanderson/context-graph-protocol"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["contextgraph_sdk*"]
+
+[tool.setuptools.package-data]
+contextgraph_sdk = ["py.typed"]

contextgraph_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+