Python SDK
What sdk/python contains today (generated Protobuf and gRPC stubs at version 0.0.0), its real requirements, and how to generate the stubs yourself.
Generated stubs only, at version 0.0.0. There is no handwritten Python API and no verified package-index publication.
The Python SDK is the Protobuf and gRPC output for the public definitions, checked in under numinance_sdk/gen/. It lets Python code build and parse Numinance messages and call the services. It adds no behavior on top.
What is in the tree
sdk/python/
pyproject.toml
uv.lock
.python-version
numinance_sdk/gen/numinance/... generated *_pb2.py and *_pb2_grpc.py
tests/test_import_smoke.pyGenerated modules cover annotations, events, evidence, kinds, plugin, ports (authorexecutor, ciexecutor, evidencestore, knowledge, sandboxprovider, scm, ticketing, transparencylog, verifier) and types. Each .proto has a <name>_pb2 module and a <name>_pb2_grpc module.
Package metadata
From pyproject.toml at the revision this site documents:
| Field | Value |
|---|---|
name | numinance-sdk |
version | 0.0.0 |
description | Numinance Python plugin SDK |
license | Apache-2.0 |
requires-python | >=3.14 |
dependencies | none declared |
dependency-groups.dev | grpcio-tools==1.84.0 |
[tool.uv] package | false |
package = false means uv treats the directory as a project, not as an installable distribution. A comment in the file states that the generated stubs need grpcio>=1.84.0 and protobuf>=7.35.1 at runtime, but the file declares no runtime dependencies, so you install those yourself. The .python-version file pins 3.14.4 for the repository's own tooling.
Not a published package
No install command is documented here because none is verified. Do not assume a package-index release of numinance-sdk exists. Use the generated source from a checkout.
Use the generated stubs
The generated modules import each other as top-level numinance.*, so the gen directory itself must be on sys.path. The repository's smoke test does exactly that, then imports every generated module and checks that PluginService resolves:
def setUpModule() -> None:
# The generated modules import each other as top-level numinance.*.
sys.path.insert(0, str(_GEN))
...
pb2 = importlib.import_module("numinance.plugin.v1.plugin_pb2")
grpc_pb2 = importlib.import_module("numinance.plugin.v1.plugin_pb2_grpc")
req = pb2.HandshakeRequest()The smoke test is plain unittest; the repository runs it from its own just gen-check task. This site did not run it.
Generate the stubs yourself
The checked-in buf.gen.yaml is a maintainer file: it runs local generators pinned in files that are not part of the public checkout, so it is not a recipe to copy. A minimal template that uses buf's built-in Python generator works against the public proto/ module:
version: v2
plugins:
- protoc_builtin: python
out: gen-py44That output is plain *_pb2.py message modules. To get gRPC service stubs as well, use the gRPC Python generator (the repository runs the protoc bundled in grpcio-tools). See Generating clients for what is and is not tested.
What is tested
- The repository's smoke test checks that every
.protohas an importable_pb2and_pb2_grpcmodule and that no generated module lacks a.proto. - Nothing in the tree tests a Python plugin end to end, and there are no Python conformance kits. The conformance kits are Go.
Failure modes
| Symptom | Cause |
|---|---|
ModuleNotFoundError: numinance | numinance_sdk/gen is not on sys.path |
Import error for grpc or google.protobuf | Runtime dependencies are not declared in pyproject.toml; install them |
| Interpreter older than 3.14 | requires-python is >=3.14 for the repository's tooling |
Next steps
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.
TypeScript SDK
What sdk/typescript contains today (generated protobuf-es code in a private package at 0.0.0), its Node requirement, and how to generate it yourself.