@sogni-ai/sogni-intelligence-client 3.0.0-alpha.0 → 3.0.0-alpha.11

package/README.md

@@ -1,28 +1,19 @@
-# Sogni Client Wrapper
+# @sogni-ai/sogni-intelligence-client
 
 [![NPM version](https://img.shields.io/npm/v/@sogni-ai/sogni-intelligence-client.svg)](https://www.npmjs.com/package/@sogni-ai/sogni-intelligence-client) [![License](https://img.shields.io/npm/l/@sogni-ai/sogni-intelligence-client.svg)](https://www.npmjs.com/package/@sogni-ai/sogni-intelligence-client)
 
-An enhanced Node.js wrapper for the [`@sogni-ai/sogni-client`](https://sdk-docs.sogni.ai/) library, designed for robustness, ease of use, and seamless integration with platforms like [n8n](https://n8n.io/).
+The public, mid‑tier Node.js client for the [Sogni Supernet](https://sogni.ai/) — Sogni's OpenAI‑compatible LLM and agent API for image, video, music, and chat generation. Bundles a hardened wrapper over the [`@sogni-ai/sogni-client`](https://sdk-docs.sogni.ai/) SDK with the public‑safe subset of Sogni's creative‑agent platform: hosted tool definitions, the contract registry, asset manifests, `RunRecord` types with redaction, skill‑runtime helpers, and JSON Schema artifacts for cross‑language codegen.
 
-This library simplifies interaction with the Sogni AI Supernet by providing a promise-based API, automatic connection management, enhanced error handling, and a more developer-friendly interface.
+For most agent builders this is the recommended starting point. Designed for third‑party integrations, downstream SDKs, and orchestration frameworks (n8n, LangChain, Anthropic skills, custom runtimes). Drives the same contracts and tool surface that the hosted `POST https://api.sogni.ai/v1/chat/completions`, `/v1/chat/runs`, and `/v1/creative-agent/workflows` endpoints use, so a client‑side agent loop stays shape‑locked with the server.
 
-## Features
+## Which package should I install?
 
-- **Promise-Based API**: Modern `async/await` support for all core operations.
-- **Connection Management**: Automatic connection and reconnection handling.
-- **Video Rendering Support**: Generate videos using WAN and LTX-2 models (t2v, i2v, s2v, ia2v, a2v, v2v, animate workflows).
-- **Audio Generation Support**: Generate music/audio tracks with audio models and estimate audio costs.
-- **Image Editing Support**: Edit images using Qwen models with context images for multi-reference editing.
-- **LLM Chat + Tool Calling Support**: Use chat completions through Sogni's LLM worker network, including streaming and function/tool calling.
-- **Vision Chat + Thinking Controls**: Send OpenAI-style multimodal `image_url` messages and toggle reasoning with `think`.
-- **Chat Tool Execution Helpers**: Execute Sogni platform tool calls manually from the wrapper, including streaming follow-up loops.
-- **Flexible Authentication**: Token, cookies, or API key authentication.
-- **Wallet + Tracking Utilities**: Query Base/Etherlink wallet balances and inspect SDK-tracked projects/current account state.
-- **Simplified Configuration**: Sensible defaults and clear configuration options.
-- **Enhanced Error Handling**: Custom error classes for better error diagnosis.
-- **Type-Safe**: Written entirely in TypeScript with full type definitions.
-- **n8n-Ready**: Built with n8n integration in mind, managing connection lifecycles effectively.
-- **Utility Helpers**: Includes helpers for validation, retries, and formatting.
+| 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://www.npmjs.com/package/@sogni-ai/sogni-client) (raw SDK) |
+| n8n workflow node | **`@sogni-ai/sogni-intelligence-client`** (n8n compat helpers preserved) |
+| Anthropic‑style Claude Skill, OpenClaw plugin, Hermes / Manus agent | [`@sogni-ai/sogni-creative-agent-skill`](https://github.com/Sogni-AI/sogni-creative-agent-skill) (consumes intelligence‑client under the hood) |
 
 ## Installation
 
@@ -30,794 +21,239 @@ This library simplifies interaction with the Sogni AI Supernet by providing a pr
 npm install @sogni-ai/sogni-intelligence-client
 ```
 
-Or with Yarn:
+Requires Node.js ≥ 18.
 
-```bash
-yarn add @sogni-ai/sogni-intelligence-client
-```
-
-## Quick Start
-
-### 1. Setup Environment Variables
-
-First, create a `.env` file in your project root to securely store your credentials:
-
-```bash
-# Copy the example file
-cp node_modules/@sogni-ai/sogni-intelligence-client/.env.example .env
-```
-
-### 2. Install Dependencies
-
-```bash
-npm install dotenv
-```
-
-### 3. Create Your Script
-
-```typescript
-import { config } from 'dotenv';
-import { SogniClientWrapper } from '@sogni-ai/sogni-intelligence-client';
-
-// Load environment variables from .env file
-config();
-
-async function main() {
-  // 1. Create and connect the client with credentials from .env
-  const client = new SogniClientWrapper({
-    username: process.env.SOGNI_USERNAME!,
-    password: process.env.SOGNI_PASSWORD!,
-  });
-
-  try {
-    // The client connects automatically on the first operation
-    console.log('Client connected!');
-
-    // 2. Find the most popular model
-    const model = await client.getMostPopularModel();
-    console.log(`Using model: ${model.id} (${model.workerCount} workers)`);
-
-    // 3. Generate an image
-    console.log('Generating image...');
-    const result = await client.createProject({
-      type: 'image',
-      modelId: model.id,
-      positivePrompt: 'A photorealistic portrait of a majestic lion in the savanna at sunset',
-      negativePrompt: 'blurry, cartoon, low quality',
-      stylePrompt: 'cinematic',
-      numberOfMedia: 1,
-      steps: 30,
-      guidance: 8,
-    });
-
-    if (result.completed && result.imageUrls) {
-      console.log('Image generation successful!');
-      console.log('Image URLs:', result.imageUrls);
-    } else {
-      console.error('Image generation did not complete.');
-    }
-
-  } catch (error) {
-    console.error('An error occurred:', error);
-  } finally {
-    // 4. Disconnect the client
-    await client.disconnect();
-    console.log('Client disconnected.');
-  }
-}
+## Package structure
 
-main();
-```
-
-### 4. Run the Script
+The package exposes the following subpath entry points so consumers import only what they need:
 
-```bash
-# If using TypeScript
-npx tsx your-script.ts
-
-# If using compiled JavaScript
-node your-script.js
-```
+| Subpath | Purpose |
+|---|---|
+| `@sogni-ai/sogni-intelligence-client` | `SogniClientWrapper` connection class + helpers + re‑exports from the underlying SDK |
+| `…/contracts` | Public contracts, default policies, repair recipes, prompt contracts, schema registry |
+| `…/tools` | Sogni‑hosted tool definitions and argument validators (image, video, audio, editing, analysis) |
+| `…/replay` | `RunRecord` types + redaction utilities (signed URLs, JWTs, bearer tokens scrubbed) |
+| `…/runtime` | Contract runtime — apply policies, recipes, and prompt contracts at call sites |
+| `…/public-skill-runtime` | Skill‑side helpers: classify turns, compile tool surface, dispatch tool calls |
+| `…/skills/asset_reference_management` | Asset‑reference resolution helpers for hosted media |
+| `…/workflows` | Creative‑workflow type definitions, bindings with embedded‑interpolation support, and a `primitives` namespace of pure helpers for `wf:*` stage tools (LLM judge + `__PASS__`/`__FAIL__` parser, bounded retry‑until‑predicate, storyboard script expander, dialogue duration fitter, SSRF allow‑list for fetched artifact URLs) |
+| `…/media` | Media reference helpers (upload / download URL flows) |
+| `…/chatRun` | Durable hosted `ChatRun` contracts — state machine, events, cost‑approval types |
+| `…/context` | Context‑window primitives — token accounting, message protection, summarization budgeting |
+| `…/openai-tools` | OpenAI‑shaped tool manifests (`app-tools.json`, `composition-tools.json`, `generation-tools.json`) baked into TS so consumers can compile a tool surface without filesystem reads |
+| `…/skill-runtime-source` | Cross‑surface parity helpers (workflow status, Seedance audio windows) shared with the private skill runtime |
+| `…/schemas/*` | Raw JSON Schema artifacts for cross‑language codegen (Swift, Kotlin, Python, etc.) |
 
-## Video Rendering Support
-
-The wrapper supports video generation with Sogni WAN and LTX-2 models. Generate videos from text prompts, images, audio, or other videos.
-
-### Video Generation Example
-
-```typescript
-// Text-to-Video (t2v) using speed variant for reliability
-const videoResult = await client.createVideoProject({
-  modelId: 'wan_v2.2-14b-fp8_t2v_lightx2v', // Speed variant (4 steps)
-  positivePrompt: 'A serene waterfall flowing through a lush green forest',
-  numberOfMedia: 1,
-  frames: 81,        // Generate 81 frames (5 seconds at 16fps)
-  fps: 16,          // 16 frames per second
-  width: 640,       // 640x640 resolution
-  height: 640,
-  steps: 4,         // Optimized for speed variant
-  outputFormat: 'mp4',
-  waitForCompletion: true,
-  timeout: 300000,  // 5 minute timeout for video generation
-});
+Each subpath ships dual CJS + ESM with TypeScript declarations.
 
-console.log('Video URLs:', videoResult.videoUrls);
-```
+## Quick start
 
-### Video Cost Estimate
+### 1. Configure credentials
 
-```typescript
-const estimate = await client.estimateVideoCost({
-  modelId: 'wan_v2.2-14b-fp8_i2v_lightx2v',
-  width: 512,
-  height: 512,
-  frames: 81,
-  fps: 16,
-  steps: 4,
-  tokenType: 'spark',
-});
+Create a `.env` in your project root:
 
-console.log('Estimated USD cost:', estimate.usd);
+```env
+SOGNI_USERNAME=your-username
+SOGNI_PASSWORD=your-password
+SOGNI_APP_ID=your-app-id        # optional; auto‑generated if omitted
+SOGNI_NETWORK=fast              # or "relaxed"
 ```
 
-### Video Workflows
-
-The wrapper supports multiple video generation workflows:
-
-1. **Text-to-Video (t2v)**: Generate videos from text prompts
-2. **Image-to-Video (i2v)**: Animate static images or interpolate between two images
-3. **Sound-to-Video (s2v / ia2v / a2v)**: Drive generation with audio references
-4. **Video-to-Video (v2v)**: Control motion/style from a reference video
-5. **Animate Workflows**: Create character animations or motion transfers
-
-### Advanced Video Examples
+### 2. Image generation
 
 ```typescript
-// Image-to-Video with interpolation
-const i2vResult = await client.createVideoProject({
-  modelId: 'wan_v2.2-14b-fp8_i2v_lightx2v',
-  positivePrompt: 'Smooth camera movement',
-  referenceImage: startImageBuffer,     // Starting image
-  referenceImageEnd: endImageBuffer,    // Optional: end image for interpolation
-  width: 512,
-  height: 512,
-  frames: 81,
-  fps: 16,
-  steps: 4,
-  autoResizeVideoAssets: true,          // Auto-resize reference images (default: true)
-});
-
-// Animate with motion transfer
-const animateResult = await client.createVideoProject({
-  modelId: 'wan_v2.2-14b-fp8_animate',
-  positivePrompt: 'Character animation',
-  referenceImage: characterImage,     // Character to animate
-  referenceVideo: motionVideo,        // Video with motion to transfer
-  frames: 90,
-  fps: 30,
-});
-
-// LTX image+audio-to-video (ia2v)
-const ia2vResult = await client.createVideoProject({
-  modelId: 'ltx2-13b-fp8_ia2v_distilled',
-  positivePrompt: 'A cinematic portrait delivering the spoken line naturally',
-  referenceImage: portraitBuffer,
-  referenceAudio: speechBuffer,
-  audioStart: 0,
-  audioDuration: 5,
-  fps: 24,
-  duration: 5,
-  numberOfMedia: 1,
-});
-
-// LTX audio-to-video (a2v)
-const a2vResult = await client.createVideoProject({
-  modelId: 'ltx23-22b-fp8_a2v_distilled',
-  positivePrompt: 'Abstract visuals that pulse with the soundtrack',
-  referenceAudio: soundtrackBuffer,
-  audioStart: 2,
-  audioDuration: 6,
-  fps: 24,
-  duration: 6,
-  numberOfMedia: 1,
-});
-```
-
-### Convenience Methods
-
-For cleaner code, use the dedicated convenience methods:
+import 'dotenv/config';
+import { SogniClientWrapper } from '@sogni-ai/sogni-intelligence-client';
 
-```typescript
-// For images
-const imageResult = await client.createImageProject({
-  modelId: 'flux1-schnell-fp8',
-  positivePrompt: 'A beautiful sunset',
-  numberOfMedia: 1,
+const client = new SogniClientWrapper({
+  username: process.env.SOGNI_USERNAME!,
+  password: process.env.SOGNI_PASSWORD!,
 });
 
-// For videos
-const videoResult = await client.createVideoProject({
-  modelId: 'wan_v2.2-14b-fp8_t2v',
-  positivePrompt: 'Ocean waves crashing on a beach',
-  numberOfMedia: 1,
-  frames: 60,
-  fps: 30,
-});
+const model = await client.getMostPopularModel();
 
-// For audio
-const audioResult = await client.createAudioProject({
-  modelId: 'ace-step-v1',
-  positivePrompt: 'An uplifting cinematic ambient track',
+const result = await client.createProject({
+  type: 'image',
+  modelId: model.id,
+  positivePrompt: 'A photorealistic portrait of a majestic lion at sunset',
+  negativePrompt: 'blurry, cartoon, low quality',
+  stylePrompt: 'cinematic',
   numberOfMedia: 1,
-  duration: 30,
-  steps: 20,
-  outputFormat: 'mp3',
+  steps: 30,
+  guidance: 8,
 });
-```
 
-## Audio Generation
+console.log(result.images.map((i) => i.url));
 
-```typescript
-const audioEstimate = await client.estimateAudioCost({
-  modelId: 'ace-step-v1',
-  duration: 30,
-  steps: 20,
-  numberOfMedia: 1,
-  tokenType: 'spark',
-});
-
-console.log('Estimated audio cost (USD):', audioEstimate.usd);
+await client.disconnect();
 ```
 
-## Chat Completions
+### 3. Tool calling against Sogni's hosted catalog
 
 ```typescript
-// Non-streaming
-const completion = await client.createChatCompletion({
-  model: 'qwen3-30b-a3b-gptq-int4',
-  messages: [{ role: 'user', content: 'Write a haiku about sunsets.' }],
-});
-console.log(completion.content);
-
-// Streaming
-const stream = await client.createChatCompletion({
-  model: 'qwen3-30b-a3b-gptq-int4',
-  messages: [{ role: 'user', content: 'Explain diffusion models simply.' }],
-  stream: true,
+import {
+  SogniClientWrapper,
+  SogniTools,
+  isSogniToolCall,
+} from '@sogni-ai/sogni-intelligence-client';
+
+const client = new SogniClientWrapper({ /* … */ });
+
+const chat = await client.chat.completions.create({
+  model: 'openai/gpt-oss-120b',
+  messages: [{ role: 'user', content: 'Generate a 3‑second clip of a koi pond.' }],
+  tools: SogniTools.all,           // the full Sogni-hosted tool catalog
 });
-for await (const chunk of stream) {
-  process.stdout.write(chunk.content);
-}
-```
-
-### Tool Calling (Function Calling)
-
-`createChatCompletion()` accepts OpenAI-style `tools` and `tool_choice` parameters.
 
-```typescript
-import type { ChatMessage, ToolCall, ToolDefinition } from '@sogni-ai/sogni-intelligence-client';
-
-const tools: ToolDefinition[] = [
-  {
-    type: 'function',
-    function: {
-      name: 'add_numbers',
-      description: 'Add two numbers',
-      parameters: {
-        type: 'object',
-        properties: {
-          a: { type: 'number' },
-          b: { type: 'number' },
-        },
-        required: ['a', 'b'],
-      },
-    },
-  },
-];
-
-const messages: ChatMessage[] = [
-  { role: 'user', content: 'Please add 17 and 25.' },
-];
-
-for (let turn = 0; turn < 4; turn++) {
-  const result = await client.createChatCompletion({
-    model: 'qwen3-30b-a3b-gptq-int4',
-    messages,
-    tools,
-    tool_choice: 'auto',
-    tokenType: 'spark',
-  });
-
-  const toolCalls = result.tool_calls || [];
-  if (toolCalls.length === 0) {
-    console.log('Final answer:', result.content);
-    break;
-  }
-
-  messages.push({
-    role: 'assistant',
-    content: result.content || null,
-    tool_calls: toolCalls,
-  });
-
-  for (const toolCall of toolCalls) {
-    const args = JSON.parse(toolCall.function.arguments || '{}');
-    let output = { error: `Unknown tool: ${toolCall.function.name}` };
-
-    if (toolCall.function.name === 'add_numbers') {
-      const a = Number(args.a || 0);
-      const b = Number(args.b || 0);
-      output = { a, b, sum: a + b };
-    }
-
-    messages.push({
-      role: 'tool',
-      tool_call_id: toolCall.id,
-      name: toolCall.function.name,
-      content: JSON.stringify(output),
-    });
-  }
+const call = chat.choices[0].message.tool_calls?.[0];
+if (call && isSogniToolCall(call.function.name)) {
+  // Hand the tool call off to Sogni's hosted execution surface, or
+  // dispatch it locally via /public-skill-runtime.
 }
 ```
 
-### Sogni Platform Tools (Image/Video/Audio via Chat)
-
-The wrapper re-exports the SDK helpers for Sogni platform tool calling:
-
-- `SogniTools` — the canonical 24-tool surface (use `SogniTools.all` for the full list)
-- `isSogniToolCall()`
-- `parseToolCallArguments()`
-
-```typescript
-import { SogniTools } from '@sogni-ai/sogni-intelligence-client';
-
-const result = await client.createChatCompletion({
-  model: 'qwen3-30b-a3b-gptq-int4',
-  messages: [{ role: 'user', content: 'Create a dramatic sunset image' }],
-  tools: SogniTools.all,
-  tool_choice: 'auto',
-  tokenType: 'spark',
-});
-```
-
-### Vision Chat and Thinking Mode
+### 4. Replay a previous run with redaction
 
 ```typescript
-const result = await client.createChatCompletion({
-  model: 'qwen3.5-35b-a3b-gguf-q4km',
-  messages: [
-    {
-      role: 'user',
-      content: [
-        { type: 'text', text: 'Describe the scene and read any visible text.' },
-        {
-          type: 'image_url',
-          image_url: {
-            url: 'https://example.com/photo.jpg',
-            detail: 'high',
-          },
-        },
-      ],
-    },
-  ],
-  think: false,
-  max_tokens: 300,
-  tokenType: 'spark',
-});
-
-console.log(result.content);
+import {
+  type RunRecord,
+  redactRunRecord,
+  redactPayload,
+} from '@sogni-ai/sogni-intelligence-client/replay';
+
+const safeRecord: RunRecord = redactRunRecord(originalRecord);
+// Signed URLs, bearer tokens, JWTs, and inline secrets are scrubbed.
 ```
 
-### Manual Chat Tool Execution
-
-Useful for streaming or custom multi-round tool loops where you want the wrapper to execute returned Sogni tool calls directly.
+### 5. Validate a hosted‑tool argument blob
 
 ```typescript
-const result = await client.createChatCompletion({
-  model: 'qwen3-30b-a3b-gptq-int4',
-  messages: [{ role: 'user', content: 'Generate a neon cyberpunk city image.' }],
-  tools: SogniTools.all,
-  tool_choice: 'auto',
-  tokenType: 'spark',
-});
-
-if (result.tool_calls?.length) {
-  const toolResults = await client.executeChatTools(result.tool_calls, {
-    tokenType: 'spark',
-    onToolProgress: (toolCall, progress) => {
-      console.log(toolCall.function.name, progress.status, progress.percent);
-    },
-  });
-
-  console.log(toolResults);
-}
+import {
+  validateAndNormalizeHostedToolArguments,
+} from '@sogni-ai/sogni-intelligence-client/contracts';
+
+const { ok, value, error } = validateAndNormalizeHostedToolArguments(
+  'generate_image',
+  { prompt: 'a serene koi pond', steps: 30 },
+);
+if (!ok) throw error;
+// `value` is the normalized argument object ready to dispatch.
 ```
 
-### Full LLM Examples
-
-Run these scripts with `npx tsx`:
-
-- `examples/llm-chat-basic.ts`
-- `examples/llm-chat-streaming.ts`
-- `examples/llm-chat-vision.ts --image ./photo.jpg`
-- `examples/llm-tool-calling-custom.ts`
-- `examples/llm-tool-calling-sogni-tools.ts` (supports `--dry-run`)
-
-## Image Editing with Context Images
+## Authentication
 
-The wrapper supports image editing using Qwen models that accept context images for multi-reference editing. This allows you to transform, combine, or edit images based on reference inputs.
-
-### Supported Models
-
-| Model ID | Type | Recommended Steps | Max Context Images |
-|----------|------|-------------------|-------------------|
-| `qwen_image_edit_2511_fp8` | Standard | 20 | 3 |
-| `qwen_image_edit_2511_fp8_lightning` | Fast | 4 | 3 |
-
-### Image Edit Example
+The wrapper accepts three authentication strategies through the `SogniClientConfig`:
 
 ```typescript
-import { readFileSync } from 'fs';
-
-// Load your reference image(s)
-const referenceImage = readFileSync('./my-image.png');
+// Username/password
+new SogniClientWrapper({ username, password });
 
-// Create an image edit project
-const result = await client.createImageEditProject({
-  modelId: 'qwen_image_edit_2511_fp8',
-  positivePrompt: 'Transform the cat into a majestic lion',
-  contextImages: [referenceImage],
-  numberOfMedia: 1,
-  steps: 20,
-  guidance: 4.0,
-});
+// API key
+new SogniClientWrapper({ apiKey });
 
-console.log('Edited image URLs:', result.imageUrls);
+// Token + cookies (typical for browser/edge contexts)
+new SogniClientWrapper({ token, cookies });
 ```
 
-### Using Multiple Context Images
+Connection management, reconnection, and credit/balance polling are handled automatically. Call `client.disconnect()` when finished.
 
-Qwen models support up to 3 context images for complex editing operations:
+## Generation surfaces
 
-```typescript
-const image1 = readFileSync('./subject.png');
-const image2 = readFileSync('./style-reference.png');
-const image3 = readFileSync('./background.png');
-
-const result = await client.createImageEditProject({
-  modelId: 'qwen_image_edit_2511_fp8_lightning', // Fast variant
-  positivePrompt: 'Combine the subject with the style and background',
-  contextImages: [image1, image2, image3],
-  numberOfMedia: 1,
-  steps: 4,  // Optimized for lightning variant
-  guidance: 1.0,
-});
-```
-
-### Multiple Angles LoRA (Qwen Image Edit)
-
-```typescript
-import { readFileSync } from 'fs';
+The root wrapper exposes type‑safe project creation across every modality Sogni supports:
 
-const referenceImage = readFileSync('./subject.png');
+- **Image generation** — Stable Diffusion XL, Flux, full model marketplace.
+- **Video generation** — WAN 2.2, LTX‑2.3, Seedance v2; workflows `t2v`, `i2v`, `s2v`, `ia2v`, `a2v`, `v2v`, `animate_move`, `animate_replace`.
+- **Audio generation** — music and SFX models with cost estimation.
+- **Image editing** — Qwen vision‑aware editors with multi‑reference context images.
+- **Chat completions** — OpenAI‑shaped chat API against Sogni's LLM worker network. Streaming, vision (`image_url`), reasoning (`think`), and function/tool calling are first‑class.
 
-const result = await client.createImageEditProject({
-  modelId: 'qwen_image_edit_2511_fp8_lightning',
-  positivePrompt: '<sks> front view eye-level shot medium shot',
-  contextImages: [referenceImage],
-  numberOfMedia: 1,
-  steps: 4,
-  guidance: 1.0,
-  sampler: 'euler',
-  scheduler: 'simple',
-  outputFormat: 'jpg',
-  loras: ['multiple_angles'],
-  loraStrengths: [0.9],
-});
+See the [SDK docs](https://sdk-docs.sogni.ai/) for full parameter references on each surface.
 
-console.log('Generated images:', result.imageUrls);
-```
+## Contracts, tools, and skills
 
-### Context Image Types
+Sogni's hosted tool surface — `generate_image`, `generate_video`, `analyze_video`, `replace_video_segment`, and 20+ others — is described declaratively. Consumers can:
 
-The `contextImages` parameter accepts an array of `InputMedia` types:
+- Enumerate the catalog: `import { SogniTools } from '@sogni-ai/sogni-intelligence-client'`.
+- Validate / normalize arguments before dispatch: `validateAndNormalizeHostedToolArguments` from `/contracts`.
+- Apply gating policies, repair recipes, and prompt contracts at runtime: `createPublicSkillDefaultContractRuntime` from `/public-skill-runtime`.
+- Generate JSON Schema clients for other languages from `/schemas/*`.
 
-- `Buffer` - Node.js Buffer containing image data
-- `Blob` - Browser Blob object
-- `File` - Browser File object
-- `true` - Boolean indicating a pre-uploaded image
+For an end‑to‑end agent example, see the [Sogni Creative Agent Skill](https://github.com/Sogni-AI/sogni-creative-agent-skill) — the `sogni-agent` CLI plus a `SKILL.md` behavior file for Claude Code, OpenClaw, Hermes Agent, and Manus. It consumes only this package's public surface.
 
-### Helper Functions
+## RunRecord replay & redaction
 
-The wrapper provides helper functions for working with context images:
+`RunRecord` is the canonical JSON representation of a Sogni run: tool calls, results, costs, audit trail, and timing. Useful for replay, post‑hoc audits, and offline analysis.
 
 ```typescript
-import { getMaxContextImages, supportsContextImages } from '@sogni-ai/sogni-intelligence-client';
-
-// Check if a model supports context images
-if (supportsContextImages('qwen_image_edit_2511_fp8')) {
-  console.log('Model supports context images!');
-}
-
-// Get the maximum number of context images for a model
-const maxImages = getMaxContextImages('qwen_image_edit_2511_fp8'); // Returns 3
-
-// Other models have different limits:
-getMaxContextImages('flux-1-schnell');  // Returns 6
-getMaxContextImages('kontext-model');   // Returns 2
-getMaxContextImages('sd-xl-base');      // Returns 0 (not supported)
+import {
+  type RunRecord,
+  type RunRecordRound,
+  type RunRecordToolCall,
+  type RunRecordToolResult,
+  emptyRunRecord,
+  redactRunRecord,
+  RUN_RECORD_SCHEMA_VERSION,
+} from '@sogni-ai/sogni-intelligence-client/replay';
 ```
 
-## API Reference
-
-### `new SogniClientWrapper(config)`
-
-Creates a new client instance.
+`redactRunRecord` / `redactPayload` scrub signed URLs, bearer tokens, JWTs, and inline secrets — call them before persisting or logging records.
 
-**Configuration (`SogniClientConfig`)**
+## Error handling
 
-| Parameter | Type | Default | Description |
-|---|---|---|---|
-| `authType` | `'token' \| 'cookies' \| 'apiKey'` | `'token'` | Authentication mode. |
-| `username` | `string` | Conditionally required | Required for `token` auth; optional for `cookies`/`apiKey`. |
-| `password` | `string` | Conditionally required | Required for `token` auth; optional for `cookies`/`apiKey`. |
-| `apiKey` | `string` | Conditionally required | Required for `apiKey` auth. |
-| `appId` | `string` | Auto-generated UUID | Unique ID for your application. |
-| `network` | `'fast' \| 'relaxed'` | `'fast'` | The Sogni network to use. |
-| `testnet` | `boolean` | `false` | Connect to the testnet network. |
-| `socketEndpoint` | `string` | `undefined` | Override the default WebSocket API endpoint. |
-| `restEndpoint` | `string` | `undefined` | Override the default REST API endpoint. |
-| `disableSocket` | `boolean` | `false` | Disable WebSocket connection (advanced/testing). |
-| `allowInsecureTLS` | `boolean` | `false` | Allow insecure TLS (useful for testnet with self-signed certs). |
-| `autoConnect` | `boolean` | `true` | Connect automatically on the first operation. |
-| `reconnect` | `boolean` | `true` | Attempt to reconnect if the connection is lost. |
-| `reconnectInterval` | `number` | `5000` | Time in ms between reconnect attempts. |
-| `timeout` | `number` | `300000` | Default timeout in ms for operations. |
-| `debug` | `boolean` | `false` | Enable detailed console logging. |
-
-#### API Key Authentication Example
+Errors are typed for precise dispatch:
 
 ```typescript
-const client = new SogniClientWrapper({
-  authType: 'apiKey',
-  apiKey: process.env.SOGNI_API_KEY!,
-  network: 'fast',
-});
+import {
+  SogniError,
+  SogniConnectionError,
+  SogniAuthenticationError,
+  SogniProjectError,
+  SogniTimeoutError,
+  SogniBalanceError,
+  SogniValidationError,
+  SogniConfigurationError,
+  SogniModelNotFoundError,
+  SogniNetworkError,
+} from '@sogni-ai/sogni-intelligence-client';
 ```
 
-### Core Methods
-
-- `connect(): Promise<void>`: Manually initiates the connection to Sogni.
-- `disconnect(): Promise<void>`: Disconnects the client.
-- `isConnected(): boolean`: Checks if the client is currently connected.
-- `getConnectionState(): ConnectionState`: Returns the current connection status.
-
-### Main Operations
-
-- `createProject(config: ProjectConfig): Promise<ProjectResult>`: Creates a new image, video, or audio generation project.
-  - `waitForCompletion` (default: `true`): If true, the promise resolves only when the media is ready.
-  - For images: returns `imageUrls` in result
-  - For videos: returns `videoUrls` in result
-  - For audio: returns `audioUrls` in result
-- `createImageProject(config)`: Convenience method for image generation (automatically sets `type: 'image'`).
-- `createVideoProject(config)`: Convenience method for video generation (automatically sets `type: 'video'`).
-- `createAudioProject(config)`: Convenience method for audio generation (automatically sets `type: 'audio'`).
-- `createImageEditProject(config: QwenImageEditConfig)`: Convenience method for image editing with context images (validates model-specific limits).
-- `getAvailableModels(options?: GetModelsOptions): Promise<ModelInfo[]>`: Retrieves a list of available models.
-- `getModel(modelId: string): Promise<ModelInfo>`: Retrieves details for a specific model.
-- `getMostPopularModel(): Promise<ModelInfo>`: A helper to get the model with the most active workers.
-- `getBalance(): Promise<BalanceInfo>`: Fetches your current SOGNI and Spark token balances using the `account.refreshBalance()` method.
-- `getWalletBalance(walletAddress?, provider?): Promise<WalletBalanceInfo>`: Fetches Base or Etherlink wallet balances. When `walletAddress` is omitted, the wrapper uses the connected account wallet.
-- `getCurrentAccount(): CurrentAccount | null`: Returns the SDK's current account snapshot if the client has connected.
-- `getTrackedProjects(): Project[]`: Returns the projects currently tracked by the underlying SDK instance.
-- `getSizePresets(network: 'fast' \| 'relaxed', modelId: string): Promise<SizePreset[]>`: Gets available output size presets for a model.
-- `estimateVideoCost(params: VideoCostEstimateParams): Promise<CostEstimate>`: Estimates video generation costs (frames/duration, fps, steps, size).
-- `estimateAudioCost(params: AudioCostEstimateParams): Promise<CostEstimate>`: Estimates audio generation costs (duration, steps, count).
-- `createChatCompletion(params)`: Creates chat completions (streaming or non-streaming, including `tools` / `tool_choice` function calling).
-- `executeChatTool(toolCall, options?)`: Executes a single Sogni platform tool call returned by chat.
-- `executeChatTools(toolCalls, options?)`: Executes multiple tool calls, including mixed Sogni/custom tool flows.
-- `estimateChatCost(params)`: Estimates chat completion cost.
-- `getAvailableChatModels()`: Returns available chat/LLM models.
-- `waitForChatModels(timeout?)`: Waits until chat/LLM models are available.
-- SDK helper exports: `ChatStream`, `ChatToolsApi`, `CurrentAccount`, `SogniTools`, `isSogniToolCall`, `parseToolCallArguments`.
-
-### Event Handling
-
-The wrapper is an `EventEmitter` and provides type-safe events.
-
-```typescript
-import { ClientEvent } from '@sogni-ai/sogni-intelligence-client';
-
-client.on(ClientEvent.CONNECTED, () => {
-  console.log('Client is connected!');
-});
-
-client.on(ClientEvent.PROJECT_PROGRESS, (progress) => {
-  console.log(`Project ${progress.projectId} is ${progress.percentage}% complete.`);
-  if (progress.estimatedTimeRemaining) {
-    console.log(`ETA: ${Math.round(progress.estimatedTimeRemaining / 1000)}s`);
-  }
-});
-
-client.on(ClientEvent.ERROR, (error) => {
-  console.error('A client error occurred:', error.message);
-});
+Each error carries `cause` and a typed `data` field where applicable.
 
-// Per-media events - Display outputs as soon as they're ready!
-client.on(ClientEvent.JOB_COMPLETED, (data) => {
-  console.log(`Job ${data.jobIndex + 1}/${data.totalJobs} completed!`);
-  console.log(`URL: ${data.imageUrl || data.videoUrl || data.audioUrl}`);
-  // You can now handle this individual output without waiting for the entire batch
-});
+## TypeScript & module formats
 
-client.on(ClientEvent.JOB_FAILED, (data) => {
-  console.log(`Job ${data.jobIndex + 1}/${data.totalJobs} failed:`, data.error);
-});
-```
-
-#### Available Events
-
-| Event | Payload | Description |
-|---|---|---|
-| `connected` | `void` | Fired when the client successfully connects. |
-| `disconnected` | `void` | Fired when the client disconnects. |
-| `reconnecting` | `number` | Fired when a reconnection attempt starts. Payload is the attempt number. |
-| `error` | `ErrorData` | Fired when a client or connection error occurs. |
-| `projectProgress` | `ProjectProgress` | Fired with real-time progress updates for a project. |
-| `projectCompleted` | `ProjectResult` | Fired when a project successfully completes. |
-| `projectFailed` | `ErrorData` | Fired when a project fails. |
-| **`jobCompleted`** | **`JobCompletedData`** | **Fired when an individual job finishes (image/video/audio).** |
-| **`jobFailed`** | **`JobFailedData`** | **Fired when an individual job fails.** |
-| `projectEvent` | `ProjectEvent` | Raw project events from the SDK (`queued`, `completed`, `error`). |
-| `jobEvent` | `JobEvent` | Raw job events from the SDK (includes `jobETA`, `started`, `progress`, etc). |
-| `chatToken` | `ChatCompletionChunk` | Fired for each streaming chat token chunk. |
-| `chatCompleted` | `ChatCompletionResult` | Fired when a chat completion finishes. |
-| `chatError` | `ChatErrorData` | Fired when a chat completion fails. |
-| `chatJobState` | `ChatJobStateEvent` | Fired on chat job state transitions. |
-| `chatModelsUpdated` | `Record<string, LLMModelInfo>` | Fired when available chat models are updated. |
-
-#### Per-Job Event Example
-
-Perfect for displaying batch outputs immediately as they complete:
-
-```typescript
-const client = new SogniClientWrapper({
-  username: process.env.SOGNI_USERNAME!,
-  password: process.env.SOGNI_PASSWORD!,
-});
+- Written in TypeScript; full `.d.ts` declarations ship for every subpath.
+- Dual CJS + ESM builds (`require()` and `import` both work).
+- `moduleResolution: 'node'` and `'bundler'` both supported; `'node16'` / `'nodenext'` consumers should prefer the `import` condition.
 
-// Listen for individual image completions
-client.on(ClientEvent.JOB_COMPLETED, (data) => {
-  console.log(`✓ Image ${data.jobIndex + 1} of ${data.totalJobs} ready!`);
-  console.log(`  URL: ${data.imageUrl}`);
-  // Display the image in your UI immediately
-  displayImage(data.imageUrl);
-});
+## Migrating from `@sogni-ai/sogni-client-wrapper`
 
-// Generate a batch of images
-const result = await client.createProject({
-  type: 'image',
-  modelId: 'flux1-schnell-fp8',
-  positivePrompt: 'A beautiful landscape',
-  numberOfMedia: 4, // Generate 4 images
-  steps: 4,
-  guidance: 3.5,
-});
+If you previously installed `@sogni-ai/sogni-client-wrapper`, the import path is the only thing that changes:
 
-// All 4 images will be displayed as they complete, not all at once!
+```diff
+- import { SogniClientWrapper } from '@sogni-ai/sogni-client-wrapper';
++ import { SogniClientWrapper } from '@sogni-ai/sogni-intelligence-client';
 ```
 
-## Error Handling
+All wrapper APIs are preserved at the root export. The intelligence client adds the new subpaths above; adopt them incrementally. The old `@sogni-ai/sogni-client-wrapper` npm name is deprecated.
 
-The library throws custom errors that extend `SogniError`. This allows you to catch specific types of errors.
+## Related packages and docs
 
-- `SogniConnectionError`: Issues with connecting to the WebSocket server.
-- `SogniAuthenticationError`: Invalid credentials (username/password, cookie session, or API key).
-- `SogniProjectError`: The image generation project failed.
-- `SogniTimeoutError`: An operation took longer than the configured timeout.
-- `SogniValidationError`: Invalid configuration or parameters.
-- `SogniBalanceError`: Insufficient token balance.
-
-```typescript
-import { SogniAuthenticationError, SogniProjectError } from '@sogni-ai/sogni-intelligence-client';
-
-try {
-  // ... your code
-} catch (error) {
-  if (error instanceof SogniAuthenticationError) {
-    console.error('Please check your credentials.');
-  } else if (error instanceof SogniProjectError) {
-    console.error('The image generation failed. Please try a different prompt or model.');
-  } else {
-    console.error('An unknown error occurred:', error);
-  }
-}
-```
+| | Where |
+|---|---|
+| **Intelligence Client docs** | https://sdk-docs.sogni.ai/our-superapps/sogni-sdk/intelligence-client/ |
+| **Sogni Intelligence API** | https://sdk-docs.sogni.ai/sogni-intelligence/introduction/ |
+| **`@sogni-ai/sogni-client`** (raw SDK) | [npm](https://www.npmjs.com/package/@sogni-ai/sogni-client) · [docs](https://sdk-docs.sogni.ai/) |
+| **`@sogni-ai/sogni-creative-agent-skill`** (CLI + Anthropic skill) | [GitHub](https://github.com/Sogni-AI/sogni-creative-agent-skill) · [npm](https://www.npmjs.com/package/@sogni-ai/sogni-creative-agent-skill) |
+| **SogniKit** (Swift, regenerated from `/schemas/*.json`) | https://github.com/Sogni-AI/SogniKit |
+| `@sogni/creative-agent` (private) | Server‑side orchestration, billing enforcement, persona management. Not on npm. |
 
 ## Testing
 
-The library includes basic unit tests, example type-checking, and end-to-end tests.
-
-### Running Tests
-
 ```bash
-# Run basic unit tests (no credentials required)
-npm test
-
-# Type-check all example scripts (including LLM/tool-calling examples)
-npm run test:examples
-
-# Run end-to-end tests (requires Sogni API credentials)
-npm run test:e2e
-
-# Run only LLM/tool-calling e2e tests
-npm run test:e2e:llm
-
-# Run all tests
-npm run test:all
+npm test            # unit + type checks; no credentials required
+npm run test:e2e    # full end-to-end, requires SOGNI_USERNAME/SOGNI_PASSWORD in .env
 ```
 
-### Setting Up End-to-End Tests
-
-To run the end-to-end tests, you need to provide your Sogni API credentials via environment variables:
-
-1. Copy the example environment file:
-   ```bash
-   cp .env.example .env
-   ```
-
-2. Edit `.env` and add your Sogni credentials:
-   ```env
-   SOGNI_USERNAME=your_sogni_username
-   SOGNI_PASSWORD=your_sogni_password
-   # Optional: force a specific chat/LLM model for e2e tests
-   # SOGNI_LLM_MODEL=qwen3-30b-a3b-gptq-int4
-   # Optional: fail suite if LLM tests cannot run (default: skip LLM tests if unavailable)
-   # SOGNI_REQUIRE_LLM_E2E=true
-   # Optional: fail suite if tool-calling tests cannot get tool_calls
-   # SOGNI_REQUIRE_TOOL_CALL_E2E=true
-   # Optional: run only LLM/tool-calling e2e tests
-   # SOGNI_E2E_SCOPE=llm
-   ```
-
-3. Run the e2e tests:
-   ```bash
-   npm run test:e2e
-   ```
-
-**Note:** The e2e tests make real API calls and may consume tokens from your Sogni account. They include image/video generation and live LLM chat calls.
-
-## TypeScript
-
-This library is written in TypeScript and exports all necessary types for a fully-typed experience.
-
-- `SogniClientConfig`: Configuration for the client constructor.
-- `ProjectConfig`: Parameters for creating a project (union of `ImageProjectConfig`, `VideoProjectConfig`, and `AudioProjectConfig`).
-- `ImageProjectConfig`: Parameters specific to image generation.
-- `VideoProjectConfig`: Parameters specific to video generation.
-- `AudioProjectConfig`: Parameters specific to audio generation.
-- `QwenImageEditConfig`: Parameters for image editing with context images.
-- `InputMedia`: Type for media inputs (`File | Buffer | Blob | boolean`).
-- `ProjectResult`: The return type for a completed project.
-- `VideoCostEstimateParams`: Parameters for estimating video cost.
-- `AudioCostEstimateParams`: Parameters for estimating audio cost.
-- `CostEstimate`: Cost estimate response shape.
-- `ModelInfo`: Detailed information about an available model.
-- `BalanceInfo`: Your token balance.
-- `ErrorData`: The structure of error objects.
-- `VideoWorkflowType`: Video generation workflow types (`t2v`, `i2v`, `s2v`, `ia2v`, `a2v`, `v2v`, `animate-move`, `animate-replace`).
-- `JobCompletedData`: Data emitted when an individual job completes.
-- `JobFailedData`: Data emitted when an individual job fails.
-- `ChatCompletionParams` / `ChatCompletionResult` / `ChatCompletionChunk`: Types for chat completions.
-- `ContentPart` / `ImageUrlContentPart`: Types for multimodal chat content.
-- `ToolDefinition` / `ToolChoice` / `ToolCall` / `ToolCallDelta`: Types for LLM tool/function calling.
-- `ToolExecutionOptions` / `ToolExecutionProgress` / `ToolExecutionResult` / `ToolHistoryEntry`: Types for manual or automatic chat tool execution.
-- `LLMModelInfo` / `LLMCostEstimation`: Types for chat model metadata and cost estimates.
-- `WalletBalanceInfo`: Wallet balance response shape for Base/Etherlink lookups.
-- `SogniTools` / `isSogniToolCall` / `parseToolCallArguments`: Helper exports for platform tool calling workflows.
-- `ProjectEvent`: Raw project events from the SDK.
-- `JobEvent`: Raw job events from the SDK (includes ETA updates).
-
 ## License
 
-[MIT](LICENSE)
+MIT — see [LICENSE](./LICENSE).