SDKs
Which language SDKs exist under numinance-spec today, what each one contains, and how to build against the contract in a language that has no SDK yet.
Go ships handwritten packages plus generated stubs. Python and TypeScript are generated stubs only. Rust and Java are not available yet.
Build once against the contract. Bring your own capabilities. The SDKs are conveniences over the public Protobuf definitions; none of them is required, and none of them is the authority.
Language matrix
Go
Handwritten packages (plugin, ports, kindyaml, schema, cli, evidenceverify) plus generated stubs. Module path github.com/numinance/numinance-spec.
Python
Generated Protobuf and gRPC stubs, version 0.0.0. Generate from source; no package-index publication is claimed.
TypeScript
Generated protobuf-es code. The package is marked private at 0.0.0, so it is not installable from a registry.
Rust
Coming soon. Not available; no distribution exists yet.
Java
Coming soon. Not available; no distribution exists yet.
Any other language
Generate Protobuf clients from the public .proto files. This is interoperability, not an official SDK.
What an SDK is and is not
The contract is the set of .proto files under proto/numinance/ plus the JSON Schemas generated from the configuration kinds. An SDK in this repository is one of three things:
- Generated stubs. Messages and service clients produced from the
.protofiles by a pinned generator. Python and TypeScript are only this. - Handwritten helpers. Code that applies rules a Protobuf schema cannot express: stream-shape checks, a strict YAML loader, an offline evidence verifier. Only Go has these.
- Command logic. The Go package behind the
numicommand line, which the private engine build also runs.
None of the SDKs is the Numinance engine. Importing one does not give you an autonomous engineer, and it cannot widen a grant, approve a change or bypass policy. Authority stays with the runtime and your policy.
Capability matrix
The matrix below is generated from the same source as the rest of the site, so every row on every page agrees.
Capability matrix
What exists today, per language and surface?
SDK language coverage
- GoPre-alpha
- PythonPre-alpha
- TypeScriptPre-alpha
- RustComing soon
- JavaComing soon
Open CLI
numi version
Available in public specOpen build of numi
numi init
Available in public specScaffolds .numinance/ for a Python repository
numi validate --files
Available in public specStrict schema + loader check of kind documents
numi validate (repository)
Available in public specSchema pass, then exit 7: profile resolution needs the engine build
numi run / connect / plan / approve / doctor
Under developmentDesigned command surface of the unified CLI
numi evidence export
Under developmentEngine-side export of an evidence bundle
Protocol
Protobuf contracts
Pre-alphaPluginService, HostService, ports, annotations, kinds
JSON Schemas and kind examples
Available in public specGenerated kind schemas and schemas/examples/
SDKs
Go SDK
Pre-alphaHandwritten plugin, kindyaml, schema, cli, evidenceverify + generated stubs
Python SDK
Pre-alphaGenerated Protobuf/gRPC stubs (version 0.0.0)
TypeScript SDK
Pre-alphaGenerated protobuf-es code, private package at 0.0.0
Rust SDK
Coming soonNo source distribution yet
Java SDK
Coming soonNo source distribution yet
Evidence
numi evidence verify
Available in public specOffline verifier over an evidence/v1 export
evidence/v1 specification + conformance vectors
Available in public specdocs/evidence/, schemas/evidence/v1/, conformance/evidence/v1/
Integrations
Sample knowledge plugin
Available in public specA host-launched Go provider of numinance.ports.knowledge.v1
Official providers (GitHub SCM, GitHub Actions, verifiers)
Pre-alphaSource and tests under plugins/official/
Runtime
Numinance engine (autonomous runtime)
Under developmentPrivate, proprietary; not generally available
Managed and sovereign deployment
Under developmentCustomer data plane + thin vendor control plane
Air-gapped deployment
Coming soonLater design milestone
Distribution
GitHub source build of the open CLI
Available in public specgit clone + go run / go build
GitHub Releases binaries
Planned distributionSigned binaries with checksums
Homebrew
Planned distributionTap/formula
Showing 23 of 23 capabilities.
Text description
Capabilities of the public numinance-spec repository and the proprietary runtime, by group, with a status from the shared status vocabulary. Rust and Java SDKs are coming soon: no source distribution, package name, version or date exists. Python and TypeScript are generated stubs at pre-alpha, not verified published packages. Go has handwritten packages plus generated stubs.
Open CLI
- numi version: Available in public spec. Open build of numi. Try: go run ./cli/numi version. Next: Tagged releases.
- numi init: Available in public spec. Scaffolds .numinance/ for a Python repository. Try: go run ./cli/numi init --ci github-actions <repo>. Next: More languages and SCM providers.
- numi validate --files: Available in public spec. Strict schema + loader check of kind documents. Try: go run ./cli/numi validate --files schemas/examples. Next: None: profile resolution lives in the engine build.
- numi validate (repository): Available in public spec. Schema pass, then exit 7: profile resolution needs the engine build. Try: go run ./cli/numi validate <repo>. Next: Full resolution ships only in the private engine build.
- numi run / connect / plan / approve / doctor: Under development. Designed command surface of the unified CLI. Try: Not in the open build. Next: Engine build; interface subject to change.
- numi evidence export: Under development. Engine-side export of an evidence bundle. Try: Unknown subcommand in the open build (exit 2). Next: Engine build.
Protocol
- Protobuf contracts: Pre-alpha. PluginService, HostService, ports, annotations, kinds. Try: Read proto/numinance/. Next: First tagged release (see VERSIONING.md).
- JSON Schemas and kind examples: Available in public spec. Generated kind schemas and schemas/examples/. Try: numi validate --files schemas/examples. Next: Additional kinds as they are accepted.
SDKs
- Go SDK: Pre-alpha. Handwritten plugin, kindyaml, schema, cli, evidenceverify + generated stubs. Try: go test ./sdk/go/.... Next: Tagged module release.
- Python SDK: Pre-alpha. Generated Protobuf/gRPC stubs (version 0.0.0). Try: Generate from source; not a verified PyPI package. Next: Ergonomic plugin SDK; publication when verified.
- TypeScript SDK: Pre-alpha. Generated protobuf-es code, private package at 0.0.0. Try: Build from source; not a verified npm package. Next: Ergonomic plugin SDK; publication when verified.
- Rust SDK: Coming soon. No source distribution yet. Try: Generate clients from the .proto files with your own toolchain. Next: Roadmap; no date, crate name or version promised.
- Java SDK: Coming soon. No source distribution yet. Try: Generate clients from the .proto files with your own toolchain. Next: Roadmap; no date, coordinates or version promised.
Evidence
- numi evidence verify: Available in public spec. Offline verifier over an evidence/v1 export. Try: go run ./cli/numi evidence verify --runner-key … --log-key … --log-origin … DIR. Next: Engine build delegates to the same package.
- evidence/v1 specification + conformance vectors: Available in public spec. docs/evidence/, schemas/evidence/v1/, conformance/evidence/v1/. Try: Verify a golden export offline. Next: Independent third-party implementations.
Integrations
- Sample knowledge plugin: Available in public spec. A host-launched Go provider of numinance.ports.knowledge.v1. Try: go build ./plugins/examples/sample-knowledge. Next: Conformance replay wiring.
- Official providers (GitHub SCM, GitHub Actions, verifiers): Pre-alpha. Source and tests under plugins/official/. Try: go test ./plugins/official/.... Next: Live-run verification; presence is not a readiness claim.
Runtime
- Numinance engine (autonomous runtime): Under development. Private, proprietary; not generally available. Try: Not installable. Next: Not scheduled publicly.
- Managed and sovereign deployment: Under development. Customer data plane + thin vendor control plane. Try: Not installable. Next: Design partners (pre-alpha).
- Air-gapped deployment: Coming soon. Later design milestone. Try: Not available. Next: After managed and sovereign.
Distribution
- GitHub source build of the open CLI: Available in public spec. git clone + go run / go build. Try: See Install. Next: Tagged releases.
- GitHub Releases binaries: Planned distribution. Signed binaries with checksums. Try: Not published; no command given. Next: Verify release artifacts first.
- Homebrew: Planned distribution. Tap/formula. Try: Not published; no command given. Next: Verify formula first.
Readiness of each SDK
| Capability | State | Public surface | How to try | Next milestone |
|---|---|---|---|---|
| Go SDK SDKs | Pre-alpha | Handwritten plugin, kindyaml, schema, cli, evidenceverify + generated stubs | go test ./sdk/go/... | Tagged module release |
| Python SDK SDKs | Pre-alpha | Generated Protobuf/gRPC stubs (version 0.0.0) | Generate from source; not a verified PyPI package | Ergonomic plugin SDK; publication when verified |
| TypeScript SDK SDKs | Pre-alpha | Generated protobuf-es code, private package at 0.0.0 | Build from source; not a verified npm package | Ergonomic plugin SDK; publication when verified |
| Rust SDK SDKs | Coming soon | No source distribution yet | Generate clients from the .proto files with your own toolchain | Roadmap; no date, crate name or version promised |
| Java SDK SDKs | Coming soon | No source distribution yet | Generate clients from the .proto files with your own toolchain | Roadmap; no date, coordinates or version promised |
Choosing a path
| You want to | Use |
|---|---|
| Load and validate kind YAML in a Go program | sdk/go/kindyaml (see Go SDK) |
| Verify an evidence export offline from code | sdk/go/evidenceverify or numi evidence verify (CLI) |
| Write a provider plugin | Go, against sdk/go/plugin and the generated stubs (Custom plugin in Go) |
| Read or write Numinance messages from Python or TypeScript | Generated stubs, built from source (Python, TypeScript) |
| Work in Rust, Java or any other language | Generate Protobuf clients yourself (Generating clients) |
No tagged release yet
The repository declares Go 1.27 and the module is not tagged. Treat every SDK surface as pre-alpha: it can change before a tag, and the versioning policy for untagged packages is in the versioning page.
Next steps
Threat model and limits
What a verified evidence/v1 export proves and what it cannot, which attacks the format detects, which need a witness outside the runner, and why conformance is not an audit.
Go SDK
The Go packages under sdk/go, their real import paths, a compile-checked example that loads a kind document, and how to run the tests.