Source: https://docs.sogni.ai/sogni-sdk/intelligence-client/

# Sogni Intelligence Client

`@sogni-ai/sogni-intelligence-client` is the public **mid-tier** Sogni package — a single import that combines:

1.  **Convenience wrappers** over the raw [Sogni SDK](https://docs.sogni.ai/sogni-sdk/) — promise-based methods, connection management, n8n-friendly helpers (preserved from the previously-named `@sogni-ai/sogni-client-wrapper`).
2.  **Portable creative-agent contracts** — `ContractRegistry`, `AssetManifest`, `RunRecord`, hosted tool argument validation, public skill runtime manifests, tool envelope helpers, and the structured contract data (gating policies, repair recipes, prompt contracts) that the Sogni platform itself uses internally.

It's the recommended starting point for most agent builders. The lower-level `@sogni-ai/sogni-client` (raw SDK) is installed as a regular dependency, so anything you can do with the raw SDK alone you can also do here without managing a separate peer install.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#which-package-should-i-install)Which package should I install?

| You're building... | Install |
| --- | --- |
| Custom AI agent that calls Sogni tools, validates LLM tool arguments, manages asset references | **`@sogni-ai/sogni-intelligence-client`** (recommended) |
| Thin wrapper that only generates an image/video/audio from a single direct call | [`@sogni-ai/sogni-client`](https://docs.sogni.ai/sogni-sdk/) (raw SDK) |
| n8n workflow node | **`@sogni-ai/sogni-intelligence-client`** (n8n compat helpers preserved) |
| Anthropic-style Claude Skill | [`@sogni-ai/sogni-creative-agent-skill`](https://docs.sogni.ai/sogni-intelligence/creative-agent-skill/) (consumes intelligence-client under the hood) |

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#installation)Installation

```
npm install @sogni-ai/sogni-intelligence-client
```

The raw SDK comes in as a transitive dependency — no need to install it separately unless you want to pin a different version.

> **Current version:** `3.0.13` — the `3.x` line is `latest`. The 3.x release moved the bundled JSON artifacts out into the standalone [`@sogni-ai/sogni-protocol`](https://docs.sogni.ai/sogni-sdk/sogni-protocol/) package, which this package now consumes as a dependency; it also added dual CJS+ESM builds, re-exports `SogniClient` from `@sogni-ai/sogni-client`, and added several new public subpaths (`/artifacts`, `/agent`, `/billing`). `npm install @sogni-ai/sogni-intelligence-client` gives you the current stable surface.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#quick-start)Quick start

```
import { SogniClientWrapper } from '@sogni-ai/sogni-intelligence-client';
import {
  ContractRegistry,
  populateContractsDefaults
} from '@sogni-ai/sogni-intelligence-client/contracts';
import {
  createAssetManifest,
  addAsset
} from '@sogni-ai/sogni-intelligence-client/skills/asset_reference_management';

const sogni = new SogniClientWrapper({
  appId: 'your-app-id',
  network: 'fast',
  apiKey: 'your-api-key'
});

// Seed the standard Sogni gating/repair/prompt-contract data
const registry = new ContractRegistry();
populateContractsDefaults(registry);

// Build an asset manifest your agent can reference by id
const manifest = createAssetManifest();
addAsset(manifest, { kind: 'image', userLabel: 'Hero', sourceUrl: 'https://...' });

// Use the wrapper for generation — promise-based, n8n-friendly
const result = await sogni.generateImage({
  modelId: 'flux1-schnell-fp8',
  positivePrompt: 'A serene mountain landscape at dawn',
  numberOfImages: 4
});

console.log(result.imageUrls);
```

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#subpath-exports)Subpath exports

The package exposes its surface via npm subpath exports — only import what you need to keep your bundle small:

| Subpath | Provides |
| --- | --- |
| `@sogni-ai/sogni-intelligence-client` | The wrapper client, error types, n8n-friendly helpers |
| `/contracts` | `ContractRegistry`, `ToolGatingPolicy`, `RepairRecipe`, `PromptContract`, `classifyTurn`, `compileToolsForTurn`, `dispatchToolCall`, `populateContractsDefaults` |
| `/tools` | `ToolResult`, `ToolErrorCode`, `toolOk`, `toolErr`, `isToolResultOk`, `isToolResultErr` |
| `/replay` | `RunRecord` schema, `redactRunRecord`, `emptyRunRecord` |
| `/skills/asset_reference_management` | `createAssetManifest`, `addAsset`, `mapAssetsForModel`, `validateAssetReferences`, `formatModelRef` |
| `/workflows` | Workflow plan types and templates |
| `/media` | Asset and generation-job spec types |
| `/runtime` | Chat envelope types and durable-run client types |
| `/public-skill-runtime` | Bundled skill runtime artifact (rarely imported directly; mostly internal to `@sogni-ai/sogni-creative-agent-skill`) |
| `/chatRun` | Durable chat-run protocol types, event helpers, cost-approval helpers, and artifact reference helpers |
| `/context` | Conversation trimming and context-budget helpers |
| `/openai-tools` | OpenAI tool manifests for hosted creative tools |
| `/artifacts` | Artifact-graph node and schema helpers (artifact schemas via `@sogni-ai/sogni-protocol`) |
| `/agent` | Agent tool-metadata and intent-input types |
| `/billing` | Spend-gate and workflow-authorization billing types |
| `/skill-runtime-source` | Source bundle used when regenerating the public skill runtime artifact |
| `/schemas/*` | JSON Schema artifacts (for cross-language code generation — see [SogniKit](https://github.com/Sogni-AI/SogniKit)) |

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#working-with-the-contract-registry)Working with the Contract Registry

The `ContractRegistry` is how Sogni Intelligence's hosted chat-completions endpoint decides which tools to expose for a given turn, how to repair tool errors, and which prompt contracts to enforce. You can use the same registry to drive your own agent loop:

```
import {
  ContractRegistry,
  classifyTurn,
  compileToolsForTurn,
  dispatchToolCall,
  populateContractsDefaults
} from '@sogni-ai/sogni-intelligence-client/contracts';

const registry = new ContractRegistry();
populateContractsDefaults(registry);

// At each turn, ask the registry which tools to expose
const turn = await classifyTurn(registry, { messages, intent });
const tools = compileToolsForTurn(registry, turn);

// After the LLM picks a tool, dispatch through the registry's dispatch logic
const result = await dispatchToolCall(registry, toolCall, { /* context */ });
```

The same contracts data is what powers the synchronous `POST /v1/chat/completions` endpoint and the durable `POST /v1/chat/runs` endpoint — so your client-side agent loop produces the same tool selection and repair decisions as the hosted Sogni Intelligence chat.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#asset-references-across-model-token-formats)Asset References Across Model Token Formats

Different image/video models expect different placeholder tokens in their prompts: GPT-Image-2 uses `Image 1`, Seedance uses `@Image1`, LTX-2.3 uses `context_image_0`. The asset manifest abstracts this:

```
import {
  createAssetManifest,
  addAsset,
  mapAssetsForModel,
  formatModelRef
} from '@sogni-ai/sogni-intelligence-client/skills/asset_reference_management';

const manifest = createAssetManifest();
const heroId = addAsset(manifest, {
  kind: 'image',
  userLabel: 'Hero',
  sourceUrl: 'https://example.com/hero.png'
});

// Map the asset for a specific model's token format. mapAssetsForModel returns
// an array of { asset_id, user_label, type, model_ref } records, not a label map.
const seedanceTokens = mapAssetsForModel(manifest, 'seedance2-pro');
// → [{ asset_id: '…', user_label: 'Hero', type: 'image', model_ref: '@Image1' }]

const gptImage2Tokens = mapAssetsForModel(manifest, 'gpt-image-2');
// → [{ asset_id: '…', user_label: 'Hero', type: 'image', model_ref: 'Image 1' }]
```

This is the same logic Sogni Intelligence's storyboard adapters use internally to drive multi-image generations.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#runrecord-replay)RunRecord Replay

Long agentic turns can be persisted as `RunRecord` entries — a structured, redact-safe log of every LLM round, tool call, and tool result. Use them for debugging, audit, or as input to a replay tool:

```
import { redactRunRecord } from '@sogni-ai/sogni-intelligence-client/replay';

const safe = redactRunRecord(runRecord);
// Strips API keys, raw credentials, and other sensitive fields.

await fetch('https://api.sogni.ai/v1/replay/records', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify(safe)
});
```

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#migrating-from-sogni-aisogni-client-wrapper)Migrating from `@sogni-ai/sogni-client-wrapper`

If you previously installed `@sogni-ai/sogni-client-wrapper`, the import path is the only thing that changes:

```
- import { SogniClientWrapper } from '@sogni-ai/sogni-client-wrapper';
+ import { SogniClientWrapper } from '@sogni-ai/sogni-intelligence-client';
```

All existing wrapper APIs are preserved at the root export. The intelligence client adds the new subpaths above; you can adopt them incrementally.

The old `@sogni-ai/sogni-client-wrapper` npm name is deprecated and points at the new one via the `npm deprecate` warning on install.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#cross-language-consumers)Cross-language consumers

JSON Schema artifacts for the public types ship at `@sogni-ai/sogni-intelligence-client/schemas/*.json` today. The [SogniKit](https://github.com/Sogni-AI/SogniKit) Swift package regenerates its Swift types from these schemas, so iOS/macOS apps that consume Sogni Intelligence stay shape-locked with the JS SDK.

For non-TypeScript SDKs or codegen pipelines that only need the JSON artifacts (schemas, OpenAI tool manifests, enums, catalogs) without the contracts runtime, install [`@sogni-ai/sogni-protocol`](https://docs.sogni.ai/sogni-sdk/sogni-protocol/) directly — it's the language-neutral source of truth that this package's `schemas/` subpath ultimately points at.

* * *

## [#](https://docs.sogni.ai/sogni-sdk/intelligence-client/#source-of-truth)Source of truth

The intelligence client carves out the public-safe subset of `@sogni/creative-agent` (private). Server-side orchestration — full workflow planning, prompt composition, ffmpeg-backed video editing, billing enforcement, socket session management — stays in the private repo behind the [Sogni Intelligence API](https://docs.sogni.ai/sogni-intelligence/introduction/). When you call `POST /v1/chat/completions` or `POST /v1/chat/runs`, the API uses the same contracts you import here, which is how the cross-surface parity story works.