SDK

The Nimi SDK is the app-facing boundary for Runtime, Realm, AI, agent, feature, and shared-type consumption. The active implementation lives under sdks/typescript and is the public @nimiplatform/sdk package.

Apps should start from the root package:

import { createNimiClient } from '@nimiplatform/sdk';

The root client composes admitted Runtime and Realm surfaces with app identity. Dedicated subpaths remain available for lower-level or domain-specific use.

Surfaces

• DelegationHand tasks between agents and people, with typed context handoff and an audit trail.
• Local EnvironmentProject the shared environment into a local session — files, tools, and runtime state.
• AI ConfigOne config surface for model selection, capability routing, and provider preference.
• WEE ProjectionStream world execution events as typed events for any consumer.
• WEE ConsumerSubscribe to world execution events with backpressure-safe consumption.
• Transport & ErrorTyped transport contracts + structured error semantics consistent across the SDK.

NimiOpen-source AI runtime for apps.

In build-outDelegationHand tasks between agents and people, with typed context handoff and an audit trail.

View SDK reference →

What This Section Contains

• Boundaries — the import and call rules apps must follow.
• First AI Call — the shortest Runtime-backed text generation path through createNimiClient.
• Runtime Client — the public app path into Runtime.
• Realm And Composition — Realm truth and admitted world-facing composition without restoring @nimiplatform/sdk/world.
• Adapters — external framework adapters such as @nimiplatform/sdk-adapter-vercel-ai.
• Shared Types — portable public types and errors.

Public Surface Set

The TypeScript SDK has one base package. External framework adapters are independent packages, not base SDK subpaths.

Public entry	Role
@nimiplatform/sdk	Recommended app-level composition surface
@nimiplatform/sdk/runtime	Runtime facade and typed Runtime projection
@nimiplatform/sdk/realm	Realm facade and generated Realm client boundary
@nimiplatform/sdk/app	App identity and app-facing helpers
@nimiplatform/sdk/types	Shared public types and SDK errors
@nimiplatform/sdk/contracts	Public contract descriptors
@nimiplatform/sdk/ai	Native AI model generation surface
@nimiplatform/sdk/ai-runner	Framework-neutral AI runner facade
@nimiplatform/sdk/testing	Test helpers for SDK consumers
@nimiplatform/sdk/features/*	Demand-driven feature modules backed by a concrete consumer contract

The removed subpaths must fail closed: @nimiplatform/sdk/world, @nimiplatform/sdk/scope, @nimiplatform/sdk/ai-provider, @nimiplatform/sdk/ai-app, and old runtime compatibility subpaths are not forwarded.

Why The SDK Exists

Nimi has multiple owner domains. Runtime owns execution, LocalAgent Conversation, Memory, and Knowledge. Realm owns Character, World, social, and semantic truth. Desktop owns native shell behavior. Application code needs a stable way to use those domains without importing their private implementation.

The SDK is that boundary. It projects admitted owner-domain behavior into developer-facing TypeScript APIs. It does not invent Runtime, Realm, or Desktop truth.

Reader Scenario: A First Integration

An app that needs Realm data and Runtime-backed generation should:

1. Create a root client with explicit app identity.
2. Read Realm data through client.realm or @nimiplatform/sdk/realm.
3. Run Runtime work through client.runtime, @nimiplatform/sdk/runtime, or native @nimiplatform/sdk/ai helpers. For a first text generation, start with First AI Call.
4. Use @nimiplatform/sdk/features/* only when an admitted feature contract matches the concrete product need.
5. Keep portable ids, reason codes, and public errors in @nimiplatform/sdk/types.

That app does not import Runtime internals, Realm REST routes, or removed SDK compatibility paths.

Source Basis

• .nimi/spec/sdks/client-core.authority.yaml
• .nimi/spec/sdks/feature-clients.authority.yaml