Navin Platform SDKs

This section documents the four SDKs and the command line that call the Control Plane of the Navin Platform and the Navin Manager. Every SDK calls only the documented routes of API v1, returns typed errors with messages in English and French, retries the transient failures with an idempotency key, and validates documents against the same contracts v1.

Version française : README.fr.md

SDKs and CLI

SDK	Package	Install	Runtime	Guide	Reference
Python	enterprise-ai (import enterprise_ai)	Harbor sdk/python, then pip install of the wheel	Python 3.10+	Python SDK	reference
TypeScript	@enterprise-ai/sdk	Harbor sdk/typescript, then npm install of the tarball	Node.js 18+, browsers, Deno, Bun	TypeScript SDK	reference
Go	module of sdks/go (package eai)	Harbor sdk/go, then a replace directive in go.mod	Go 1.26+	Go SDK	reference
Java	io.enterpriseai:enterprise-ai-java (Spring Boot starter enterprise-ai-spring)	Harbor sdk/java, then a Maven or Gradle dependency	Java 17+	Java SDK	reference
CLI	enterprise-ai command (in the Python package)	Harbor sdk/python, then pipx install of the wheel	Python 3.10+	CLI guide	CLI reference

Where the SDKs are hosted

The SDK packages are hosted in the Harbor registry of the organization, in the sdk project, as OCI artifacts: sdk/python, sdk/typescript, sdk/go and sdk/java. The tag of an artifact is the SDK version (for example 1.0.2). Nothing is downloaded from a public registry or from a source repository.

The Navinspire registry is registry.navinspire.ai. The platform team gives a robot account that has pull rights on the sdk project. If your organization mirrors the sdk project in its own Harbor, replace the address with that of the mirror.

oras login registry.navinspire.ai
oras pull registry.navinspire.ai/sdk/python:1.0.2 -o sdk-python

Related guides:

Guide	Content
Navin Manager SDK and CLI	The manager client of each SDK and enterprise-ai manager: hosts, clusters, services, HA, backups, restores, DR.
Realtime voice	@enterprise-ai/realtime and the voice live clients of Python and Go.
Contracts v1	The JSON Schema contracts and their validation, online and offline.

The generated references list every public class, method, parameter, model and field of each SDK, in English and in French; python3 tools/docs/gen_sdk_reference.py writes them and --check reports a stale page.

Shared behaviour

Topic	Rule in every SDK
Base URL	https required, http only for localhost, 127.0.0.1 and ::1; redirects never followed
Authentication	API key (X-API-Key) or OIDC token (Authorization: Bearer); the tenant comes from the credential
Errors	envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}} mapped to typed errors
Retries	backoff with jitter, Retry-After honored; POST calls carry an Idempotency-Key
Pagination	limit and cursor, answer {items, next_cursor}, with an iterator over every page
Tracing	W3C traceparent on every call, X-Request-Id exposed on errors
Secrets	API keys and tokens masked in logs and string forms; secret looking details keys replaced by ***

Choice matrix

Use	Recommended	Why
Agents, RAG, evaluation, data science, notebooks	Python	Full module tree (agent loop, subagents, evaluation, finops), async client
Web apps, portals, Node backends, edge	TypeScript	Typed camelCase client, browser safe OIDC mode
Voice agents in the browser or a Node bridge	TypeScript + @enterprise-ai/realtime	LiveKit and WebRTC with a WebSocket fallback
Enterprise backends, Spring Boot, banking and insurance systems	Java	Builder client, Spring Boot starter, try-with-resources reservations
Gateways, proxies, media workers, infrastructure agents	Go	gatewaymw quota middleware, worker, usage, realtime packages
CI/CD, GitOps, operations, quick checks	CLI	validate, test, deploy, finops, audit verify with json and yaml output
Any language without SDK	HTTP + contracts	OpenAPI at /openapi.json, JSON Schemas in contracts/v1

Adoption by a client of a client

Whole platform. The end client gets a tenant (POST /v1/tenants by the platform operator), projects and environments, OIDC federation or API keys, then uses the Python or TypeScript SDK for agents and the CLI for GitOps manifests. Quotas, FinOps, audit and quality gates apply automatically to everything going through the gateway.

Single brick. Each brick is reachable alone with an API key restricted to its scopes:

• FinOps only: emit Usage Events (POST /v1/finops/usage, Go usage package) from any existing AI stack and read /v1/finops/summary.
• Quotas only: wrap an existing LLM proxy with Go gatewaymw (POST /v1/quotas/reserve, commit, release).
• STT or vision only: POST /v1/media then POST /v1/multimodal/stt or POST /v1/multimodal/vision.
• Audit only: read and export the evidence chain (/v1/audit/events, /v1/audit/verify, /v1/audit/export).
• Evaluation only: register a provider endpoint and call /v1/evaluations/runs and /v1/evaluations/gates/check from CI.