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 — 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.

#Which package should I install?

#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.

Release tracks: the current latest is 2.2.6. A 3.x-alpha train is also published — install it with npm install @sogni-ai/sogni-intelligence-client@alpha to track the upcoming surface (which migrates the bundled JSON artifacts out into the standalone @sogni-ai/sogni-protocol package). APIs may shift before the alpha graduates to latest.

#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);

#Subpath exports

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

#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.

#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
const seedanceTokens = mapAssetsForModel(manifest, 'seedance2-pro');
// → { 'Hero': '@Image1' }

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

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

#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)
});

#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.

#Cross-language consumers

JSON Schema artifacts for the public types ship at @sogni-ai/sogni-intelligence-client/schemas/*.json today. The 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 directly — it's the language-neutral source of truth that this package's schemas/ subpath ultimately points at.

#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. 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.