Skip to content

v1.0.0

Choose a tag to compare

@github-actions github-actions released this 02 May 14:53
· 146 commits to main since this release

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 backend
  • search_web — Nova OS extended; supports include_domains / exclude_domains
  • research_query — high-accuracy variant; always Tavily
  • fetch_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 version

Available 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 version

Multi-arch manifest covers linux/amd64 + linux/arm64.

From source:

go install github.com/MeganovaAI/nova-os-sdk/cli@v1.0.0

Verify (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 OK

No 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 smoke

Profile 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/acme

Override 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 classes
  • WebhookRouter HMAC 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.knowledge resource (depends on a future server-side endpoint)
  • c.settings resource (admin-only; depends on a future surface)
  • nova-os-cli logs subcommand (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[].model round-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.0

What 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_TOKEN is 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.yaml info.version
  • Python changelog: python/CHANGELOG.md
  • CLI changelog: GitHub Releases
  • Examples + integration patterns: python/examples/

License

MIT.