Repository navigation
v1.0.0
Nova OS SDK — v1.0.0
Public API stable. This release locks the partner-facing surfaces (OpenAPI spec, Python SDK, CLI) for the v1.x line. Code written against v1.0.0 is forward-compatible with every 1.x.y release.
v0.9.0rc1 was the API freeze candidate. There are no breaking changes from rc1 → 1.0.0; partners on rc1 can upgrade with pip install --upgrade nova-os-sdk and a single tag bump on their CLI install.
At a glance
| Surface | Status | Install |
|---|---|---|
| OpenAPI spec (source of truth) | stable, locked | openapi/nova-os-partner.v1.yaml in this repo |
Python SDK (nova_os) |
stable | pip install nova-os-sdk |
CLI (nova-os-cli) |
stable | binary download (linux/darwin/windows × amd64/arm64) or docker pull ghcr.io/meganovaai/nova-os-cli:v1.0.0 |
| Anthropic SDK drop-in compatibility | stable | pip install anthropic (use as Anthropic(base_url=...)) |
Two-tier client model
The SDK ships two coherent client surfaces:
1. Anthropic-compat (1:1 mirror)
Partners with existing code targeting anthropic.Anthropic(base_url=...) swap the URL and ship — no code changes required for the compat surface.
from anthropic import Anthropic
c = Anthropic(
base_url="https://nova.partner.com", # bare server URL — SDK appends /v1/messages itself
api_key="...",
)
msg = c.messages.create(
model="anthropic/claude-opus-4-7",
max_tokens=1024,
messages=[{"role": "user", "content": "hello"}],
metadata={"agent_id": "invoice-bot"}, # routes to your registered agent
)Per-call routing to a Nova OS persona uses the standard Anthropic metadata field. Nova OS reads metadata.agent_id from the request body and dispatches to the named agent — Brain orchestration fires automatically when the resolved agent has brain: true in its frontmatter.
The convenience factory nova_os.AnthropicCompatClient(...) is a thin pass-through:
from nova_os import AnthropicCompatClient
c = AnthropicCompatClient(base_url="https://nova.partner.com", api_key="...")
# Returns anthropic.Anthropic(base_url="https://nova.partner.com", api_key=...) — base_url passed through unchanged.
# The factory exists for symmetry with the rest of the nova_os surface; it's
# functionally equivalent to anthropic.Anthropic(base_url=..., api_key=...).A recorded fixture test in the SDK locks this contract — every release verifies that an Anthropic SDK call round-trips cleanly against a Nova-OS-shaped response.
2. Nova OS extended (nova_os.Client)
The full Nova OS surface — multi-model cascade at agent + employee level, web-search backend selection, custom-tool webhooks, async jobs, portable employee bundles.
from nova_os import Client
async with Client(base_url="https://nova.partner.com", api_key="...") as c:
# Auto-paginating async iterator
agents = [a async for a in c.agents.list()]
# CRUD
emp = await c.employees.create(
id="frontdesk",
display_name="Front Desk",
model_config={"answer": {"primary": "anthropic/claude-opus-4-7"}},
)
# Send a message
resp = await c.messages.create(
agent_id="marketing-assistant",
messages=[{"role": "user", "content": "Hello"}],
)
# Streaming with Mode A custom-tool inline
async with c.messages.stream(agent_id="invoice-bot", messages=[...]) as s:
async for event in s:
if event["event"] == "custom_tool_use":
result = await my_handler(event["data"]["input"])
await s.submit_tool_result(event["data"]["id"], result)
# Async long-running job
job = await c.jobs.create("research-bot", messages=[...])
while job["status"] not in ("completed", "failed"):
await asyncio.sleep(2)
job = await c.jobs.get(job["job_id"])Sync mirror via c.sync for scripts and notebooks.
Resources
| Resource | Methods |
|---|---|
c.agents |
create, get, update, delete, list (auto-paginating) |
c.employees |
create, get, update, delete, list |
c.messages |
create, stream |
c.jobs |
create, get, cancel, list |
All methods are async-first; c.sync.<resource>.<method>(...) mirrors them synchronously.
Mode B custom-tool webhooks (WebhookRouter)
Partners declare custom tools on their Nova OS agents. When the LLM invokes one, Nova OS POSTs an HMAC-signed payload to the partner's URL. The WebhookRouter is the partner-side primitive that verifies the signature, dedupes by idempotency key, and dispatches to registered handlers.
from nova_os import WebhookRouter
router = WebhookRouter(secret="your-shared-hmac-secret")
@router.tool("fetch_invoice")
async def fetch_invoice(input: dict, ctx: dict) -> str:
return f"Invoice {input['invoice_id']}: $42"Mount on any framework — lazy-imported, no runtime deps:
# FastAPI
from fastapi import FastAPI
app = FastAPI()
app.include_router(router.fastapi_router(), prefix="/nova/cb")
# Flask
from flask import Flask
app = Flask(__name__)
app.register_blueprint(router.flask_blueprint(), url_prefix="/nova/cb")
# AWS Lambda
handler = router.aws_lambda_handler()Wire format
The HMAC scheme binds the idempotency key into the signature, defeating idempotency-key tampering attacks:
X-Nova-Signature: t=<unix_ts>,v1=<hex(hmac_sha256(secret, ts + "." + tool_use_id + "." + body))>
X-Nova-Idempotency-Key: <tool_use_id>
Replay window: 5 minutes default. Idempotency dedup is in-memory per process (production multi-replica deployments should add a shared store; v1 single-process is supported out-of-the-box).
Server-side tool observability — known v1.0.0 limitation
Anthropic-provided server-side tools (web_search_20250305, code_execution_20250522, etc.) execute on Anthropic's infrastructure and do NOT emit discrete content_block_start / content_block_stop events on the SSE stream. The model's response references the tool ran; the discrete event-stream signal is missing.
Visible: the model's text response describes the tool result; MessageResponse.content[] (non-streaming) contains server_tool_use blocks.
Not visible: discrete tool-invocation events on the streaming path.
This is a pre-existing constraint of the underlying Anthropic API; Nova OS forwards what it receives. Partner-defined custom tools (Mode B via WebhookRouter) emit custom_tool_use events normally — the limitation is specific to Anthropic-provided server-side tools.
Workaround: inspect MessageResponse.content after the stream completes; or use the non-streaming messages.create path when discrete tool observability matters.
Tracking MeganovaAI/nova-os-sdk#10 for v1.1: gateway-side synthetic event emission so audit hooks Just Work for server-side tools.
Multi-model cascade
Per-call → per-skill → per-agent → per-employee → server default. Three slots: answer, planner, skill. Per-tier whole-config resolution (no field-level merging across tiers — preserves audit boundaries).
# Set at the employee level — cascades to all owned agents
await c.employees.update(
"frontdesk",
model_config={
"answer": {"primary": "anthropic/claude-opus-4-7", "fallback": ["openai/gpt-5"]},
"planner": {"primary": "gemini/gemini-3-pro-preview"},
"skill": {"primary": "gemini/gemini-2.5-flash"},
},
)Server-side fallback is automatic: if the primary model errors (rate limit, 5xx, vendor outage, Vertex 400 schema-bug), the next entry in fallback runs. The response carries X-Nova-Model-Used and X-Nova-Model-Fallback-Triggered headers so partners can observe what actually ran.
Model names — vendor prefix required
When Nova OS routes through the MegaNova gateway, every model name must carry a <vendor>/ prefix. Bare names (the Anthropic SDK's natural default) return model_not_found:
| Right | Wrong |
|---|---|
anthropic/claude-opus-4-7 |
claude-opus-4-7 |
gemini/gemini-3-pro-preview |
gemini-3-pro-preview |
openai/gpt-5 |
gpt-5 |
For partners using vanilla anthropic.Anthropic(...): pin your ANTHROPIC_HIGH_MODEL to a prefixed value, OR translate bare → prefixed at your edge before calling Nova OS. The CLI's validate subcommand catches bare names in your YAML at PR time. List the live catalog via GET /v1/models.
The agent_inference_model and ollama_embed_model settings route to a local Ollama and use <tag>:<version> shape (e.g. gemma4:e4b) — they're exempt.
Web search
Per-agent backend selection. Configure once on the employee or agent; the search_web tool honors it transparently.
agent:
web_search_config:
backend: ceramic # or tavily, brave, exa, searxng, meganova, auto
fallback: [tavily] # chain of fallback backends
reformulator: true # LLM query rewriter (boosts keyword backends)
recency_terms: # custom recency markers (defaults cover EN + ZH)
- "现状"
- "latest"Tools available:
web_search_20250305— Anthropic-compat name; routes to configured backendsearch_web— Nova OS extended; supportsinclude_domains/exclude_domainsresearch_query— high-accuracy variant; always Tavilyfetch_url— URL → markdown via PDF/HTML-aware routing
Portable employee bundles
.nova-bundle.zip = manifest.json + employee.md + agents/<agent_id>.md. The format for tenant onboarding and cross-instance migration.
# Export
data: bytes = await c._http.get(f"/v1/managed/employees/{id}/bundle/export")
# Import
await c._http.post(
"/v1/managed/employees/bundle/import?on_conflict=overwrite",
content=data,
headers={"Content-Type": "application/zip"},
)nova-os-cli employees export and import provide higher-level wrappers (CLI section below).
Typed errors
Every error response is parsed into a typed exception with structured fields:
from nova_os import (
NovaOSError,
NotFoundError,
RateLimitedError,
BillingError,
VertexSchemaError,
ModelNotFoundError,
AuthenticationError,
PermissionError,
UpstreamError,
InternalError,
)
try:
await c.messages.create(agent_id="...", messages=[...])
except VertexSchemaError as e:
# Deterministic schema bug — do NOT retry. Fix the offending tool schema.
print(f"Tool {e.tool_name} param {e.parameter_path}: {e.fix_hint}")
except RateLimitedError as e:
await asyncio.sleep(e.retry_after or 60)
except BillingError as e:
notify_ops(f"billing issue: {e.code}")VertexSchemaError deserves special note: it surfaces the deterministic class of 400 responses caused by Vertex AI strictly enforcing JSON Schema spec on tool declarations (every type: array MUST have an items schema). Partners get the actionable diagnostic instead of the misleading "Connection error" message.
CLI (nova-os-cli)
Single static Go binary. Subcommands cover the full agent + employee + sync + validate + webhook-test workflow.
Install
Pre-built binary:
TAG=v1.0.0
curl -L "https://github.com/MeganovaAI/nova-os-sdk/releases/download/$TAG/nova-os-cli_linux_amd64.tar.gz" \
| tar -xz -C /usr/local/bin nova-os-cli
nova-os-cli versionAvailable archives: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, windows_amd64.zip. Each ships with a SHA256 checksum and a cosign signature.
Docker:
docker pull ghcr.io/meganovaai/nova-os-cli:v1.0.0
docker run --rm -v ~/.nova-os:/home/nonroot/.nova-os ghcr.io/meganovaai/nova-os-cli:v1.0.0 versionMulti-arch manifest covers linux/amd64 + linux/arm64.
From source:
go install github.com/MeganovaAI/nova-os-sdk/cli@v1.0.0Verify (cosign keyless)
Every CLI archive ships with <file>.sig + <file>.pem. Verify with cosign:
TAG=v1.0.0
ARCHIVE=nova-os-cli_linux_amd64.tar.gz
cosign verify-blob \
--certificate-identity-regexp 'https://github.com/MeganovaAI/nova-os-sdk/.+' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
--signature "$ARCHIVE.sig" \
--certificate "$ARCHIVE.pem" \
"$ARCHIVE"
# Verified OKNo long-lived signing key — signatures are produced via Sigstore Fulcio + GitHub Actions OIDC.
Subcommands
nova-os-cli employees create / list / get / update / delete
nova-os-cli agents create / list / get / update / delete
nova-os-cli jobs create / list / get / cancel
nova-os-cli messages (use SDK for streaming; REST handled via resources above)
nova-os-cli sync one-shot or --watch (folder → server live sync)
nova-os-cli validate offline frontmatter + Vertex schema-bug guard
nova-os-cli test-callback Mode B webhook smoke (forge signed POST to your URL)
nova-os-cli config list / get / set / default / delete (profile management)
nova-os-cli version CLI + spec version + build metadata
Killer commands
# CI gate — exit 0 if your folder is clean, 1 if any rule fails
# (catches the deterministic Vertex 400 class before it reaches prod)
nova-os-cli validate ./data/
# Dev loop — folder changes auto-sync to server (300ms debounce)
nova-os-cli sync --watch ./data/ --target https://dev.nova.partner.com
# Pre-flight your Mode B webhook handler
export NOVA_CB_SECRET=your-shared-secret
nova-os-cli test-callback \
--target https://partner.example.com/nova/cb \
--tool fetch_invoice \
--input '{"invoice_id":"INV-9912"}' \
--repeat 3 # idempotency dedup smokeProfile config
~/.nova-os/config.yaml:
default: partner-prod
profiles:
partner-prod:
url: https://nova.partner.com
api_key_env: NOVA_PROD_KEY
customer-acme:
url: https://nova.acme.example.com
api_key_env: NOVA_ACME_KEY
callback_url: https://partner.example.com/nova/acmeOverride per-command: nova-os-cli --profile customer-acme employees list.
Examples
8 worked examples in python/examples/ (skip 03 — knowledge resource is deferred):
| File | Surface |
|---|---|
01_basic_chat.py |
Anthropic-compat hello world |
02_create_employee_and_agent.py |
Full lifecycle |
04_custom_tool_inline.py |
Mode A SSE inline |
05_custom_tool_webhook.py |
Mode B webhook (FastAPI) |
06_multi_model_fallback.py |
Cascade + observe X-Nova-Model-Used |
07_bundle_export_import.py |
Tenant onboarding |
08_async_job_long_running.py |
20-min async job |
OpenAPI spec
Source of truth at openapi/nova-os-partner.v1.yaml. 19 endpoints across:
/v1/managed/agents(CRUD)/v1/managed/agents/{id}/messages(SSE)/v1/managed/agents/messages/{message_id}/custom_tool_results(Mode A submit)/v1/managed/employees(CRUD)/v1/managed/employees/{id}/bundle/export+/v1/managed/employees/bundle/import/v1/managed/agents/jobs(CRUD)/v1/managed/agents/jobs/{id}/stream(SSE replay)
Both the Python SDK (openapi-python-client output at python/nova_os/_generated/) and the Go CLI client (oapi-codegen output at cli/internal/client/client.gen.go) are generated from this file. Codegen drift is enforced by CI on every PR.
If you need a TS, Rust, or Go-direct client, codegen one yourself from this spec — the contract is stable for the v1.x line.
What's stable, what's deferred
Stable in v1.0.0
- All endpoints in the OpenAPI spec — request + response shapes locked
nova_os.Client+ all 4 resource classesWebhookRouterHMAC scheme, idempotency, replay window- Streaming context manager + Mode A submit
- All typed exceptions in
nova_os.errors - CLI subcommands listed above
- Multi-model cascade resolution rules
Deferred to v1.1+
c.knowledgeresource (depends on a future server-side endpoint)c.settingsresource (admin-only; depends on a future surface)nova-os-cli logssubcommand (depends on a streaming logs endpoint)nova-os-cli sync --prune(destructive forward-and-back sync)- Per-skill model override at the SDK surface (
agent.skills[].modelround-trips, but isn't yet a first-class resource method) - TypeScript / Rust / Go-direct client SDKs — codegen from the OpenAPI spec yourself if you need them in the meantime
NOT planned for v1.x
- WebSocket transport (SSE only)
- gRPC / protobuf surface
- Marketplace / bundle registry
- LoRA / finetune SDK surface
Migration from v0.9.0rc1
No breaking changes. Every public surface in rc1 is preserved 1:1. Upgrade is a one-liner:
pip install --upgrade nova-os-sdk
# and bump your CLI install tag from v0.9.0rc1 to v1.0.0What changed under the hood (non-breaking):
- CLI binaries now ship with cosign signatures + Docker images at ghcr.io
- Python wheels publish to PyPI (when
PYPI_API_TOKENis configured) - Internal release pipeline now uses goreleaser (no partner-visible change)
Acknowledgments
Special thanks to EqualDocs as our v1.0.0 launch partner. Their concrete partner-validation feedback on cascade resolution, per-tool callback override, bundle format, and fail-loud-on-error semantics shaped a number of the API decisions, and their parallel integration work was the canonical reference for the Mode B webhook end-to-end test.
Support
- Issues + feature requests: GitHub Issues
- OpenAPI changelog: see
openapi/nova-os-partner.v1.yamlinfo.version - Python changelog:
python/CHANGELOG.md - CLI changelog: GitHub Releases
- Examples + integration patterns:
python/examples/
License
MIT.