Problem
The code promises language-neutral provider kits that don't exist: the wire module chose NDJSON specifically because it is "trivially reimplementable in the TS/Python provider kits" (contextgraph-host/src/wire.rs:9) — there are no such kits. Today the any-language story is "here's a JSON Schema and some example transcripts, good luck," which filters out exactly the audience (TS/Python agent builders) most likely to adopt.
Proposal
Two thin official SDKs, provider-side first (hosts are rarer than providers):
@contextgraph/provider (npm) and contextgraph-provider (PyPI), each containing:
- Envelope/frame/query types (generated or hand-ported from
schema/contextgraph-envelope.schema.json, with the schema as the CI-enforced source of truth)
- A stdio provider loop: NDJSON framing, handshake with version-family check, malformed-line tolerance (reply
error, don't die — the R1 rule), clean shutdown
- The canonical token-counting helper (whatever the token-cost issue decides) and a
respects_budget self-check, so budget honesty is a one-liner
- A
create-contextgraph-provider / cookiecutter scaffold whose generated project runs contextgraph-inspect in its own CI from day one
- An HTTP adapter (single-endpoint POST handler) for hosting a provider behind any web framework
Keep the SDKs pinned to the spec, not to contextgraph-host internals: they should be written from SPEC.md + schema + examples/ alone — which doubles as a live audit that the spec self-containment issue actually succeeded.
Note on the freeze: GOVERNANCE.md requires two independent implementations, and first-party SDKs don't fully count as "independent" — but they radically lower the barrier for the genuine third-party one, and the conformance suite is what keeps everyone honest either way.
Acceptance criteria
Problem
The code promises language-neutral provider kits that don't exist: the wire module chose NDJSON specifically because it is "trivially reimplementable in the TS/Python provider kits" (
contextgraph-host/src/wire.rs:9) — there are no such kits. Today the any-language story is "here's a JSON Schema and some example transcripts, good luck," which filters out exactly the audience (TS/Python agent builders) most likely to adopt.Proposal
Two thin official SDKs, provider-side first (hosts are rarer than providers):
@contextgraph/provider(npm) andcontextgraph-provider(PyPI), each containing:schema/contextgraph-envelope.schema.json, with the schema as the CI-enforced source of truth)error, don't die — the R1 rule), cleanshutdownrespects_budgetself-check, so budget honesty is a one-linercreate-contextgraph-provider/cookiecutterscaffold whose generated project runscontextgraph-inspectin its own CI from day oneKeep the SDKs pinned to the spec, not to
contextgraph-hostinternals: they should be written fromSPEC.md+ schema +examples/alone — which doubles as a live audit that the spec self-containment issue actually succeeded.Note on the freeze:
GOVERNANCE.mdrequires two independent implementations, and first-party SDKs don't fully count as "independent" — but they radically lower the barrier for the genuine third-party one, and the conformance suite is what keeps everyone honest either way.Acceptance criteria
contextgraph-inspectgreen in their generated CIschema/contextgraph-envelope.schema.jsonon every commitdocs/implementing-a-provider.mdgains TS and Python quick-starts