@sogni-ai/sogni-client 4.2.0-alpha.9 → 5.0.0-alpha.2

package/{CLAUDE.md → AGENTS.md}

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding assistants (Claude Code, Codex, etc.) when working with code in this repository.
 
 ## LLM Documentation Resources
 
@@ -13,9 +13,49 @@ For AI coding assistants working with this SDK, the following resources are avai
 
 When helping users with Sogni SDK tasks, consult `llms-full.txt` for complete parameter references, especially for video generation where WAN 2.2 and LTX-2.3 models have different behaviors.
 
+These are public agent-facing docs shipped with the npm package. They are kept aligned with:
+
+- `package.json` for package version, runtime engines, npm scripts, exports, and published files.
+- `src/index.ts` for public SDK namespaces and root exports.
+- `src/Projects/types/index.ts`, `src/Projects/utils/index.ts`, and `src/Projects/createJobRequestMessage.ts` for media-generation parameters and video frame behavior.
+- `src/Chat/types.ts`, `src/Chat/index.ts`, `src/Chat/tools.ts`, and `src/Chat/hostedToolValidation.generated.ts` for chat, hosted tools, structured outputs, and durable runs.
+- `src/CreativeWorkflows/` and `src/Replay/` for durable workflow and RunRecord APIs.
+
+Current public API anchors:
+
+- The SDK runtime requirement is **Node.js >=22** (`package.json#engines`).
+- Socket-native LLM chat uses `sogni.chat.completions.create()`.
+- Durable creative workflows use `sogni.workflows`.
+- Project cost helpers are `sogni.projects.estimateCost()`, `estimateVideoCost()`, and `estimateAudioCost()`.
+- `checkAuth()` is only for cookie-auth browser flows. API-key auth auto-authenticates during `createInstance()`, and token auth uses `login()` or `setTokens()`.
+- `ChatCompletionResult` is SDK-shaped (`content`, `role`, `finishReason`, `tool_calls`, `usage`, `cost`). Streaming chunks expose `chunk.content` and optional `chunk.tool_calls`.
+
+## Sogni Intelligence APIs
+
+The SDK wraps the public Sogni Intelligence endpoints used for text chat, hosted creative tools, durable chat turns, and deterministic multi-step workflows.
+
+- `sogni.chat.completions.create()` maps to socket-native chat completions and supports text, streaming, vision input, custom function tools, Sogni tool injection, structured outputs, and `think` / `taskProfile` controls.
+- `sogni.chat.hosted.create()` maps to `POST /v1/chat/completions`, the OpenAI-compatible REST chat endpoint. It can execute Sogni media-generation and composition tools server-side.
+- `sogni.chat.runs` maps to `/v1/chat/runs`, a durable hosted-chat turn with persisted state, event replay, cancellation, and recovery across client disconnects.
+- `sogni.workflows` maps to `/v1/creative-agent/workflows`, where callers submit exact multi-step creative plans and observe durable execution through snapshots, event logs, or SSE.
+- `sogni.workflows.templates` maps to `/v1/creative-agent/workflows/templates`, the CRUD and fork API for saved, parameterized workflow recipes.
+- `sogni.replay` maps to `/v1/replay/records`, the RunRecord write/list/get surface for replay viewers and audit tooling.
+
+Public chat and workflow media rules:
+
+- Vision chat accepts inline PNG or JPEG `data:` URIs through OpenAI-style `image_url` content parts.
+- Durable chat runs and creative workflows use retrievable HTTP(S) media references, often produced by Sogni upload/download URL helpers.
+- Request media references are addressable by media index in hosted tool and workflow calls, so later steps can reuse uploaded or generated images, videos, and audio without copying URLs into prompts.
+
 ## Overview
 
-This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, etc.), video generation (WAN 2.2 and LTX-2.3 models), audio generation (ACE-Step 1.5), LLM chat with tool calling, and multimodal vision chat (Qwen3.5 VLM) via WebSocket communication.
+This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, Z-Image, Qwen image-edit models, GPT Image 2), video generation (WAN 2.2, LTX-2.3, Seedance 2.0), audio generation (ACE-Step 1.5), LLM chat with tool calling, hosted creative tools, durable creative workflows, replay records, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`).
+
+Runtime and packaging:
+
+- Node.js `>=22` is required by `package.json`.
+- CommonJS build: `dist/index.js`; ESM build: `dist-esm/index.js`; type declarations: `dist/index.d.ts`.
+- Published package files include `README.md`, `AGENTS.md`, `llms.txt`, `llms-full.txt`, `dist/`, `dist-esm/`, and `src/`.
 
 ## Build & Development Commands
 
@@ -32,10 +72,26 @@ npm run prettier:fix
 # Check formatting
 npm run prettier
 
+# Validate generated hosted-tool validation file is in sync
+npm run check:hosted-tool-validation
+
+# Validate generated hosted-tool manifest is in sync
+npm run check:hosted-tools-manifest
+
+# Build and run chat model-routing checks
+npm run test:chat-routing
+
 # Generate API documentation
 npm run docs
 ```
 
+Generated artifacts:
+
+- `src/Chat/sogniHostedTools.generated.json` is regenerated with `npm run sync:hosted-tools-manifest`.
+- `src/Chat/hostedToolValidation.generated.ts` is regenerated with `npm run sync:hosted-tool-validation`.
+- `docs/` is generated by TypeDoc via `npm run docs`.
+- `dist/` and `dist-esm/` are generated by `npm run build`.
+
 ## Architecture
 
 ### Entry Point & Main Classes
@@ -44,6 +100,15 @@ npm run docs
 - `account: AccountApi` - Authentication, balance, rewards
 - `projects: ProjectsApi` - Create/track AI generation jobs
 - `stats: StatsApi` - Leaderboard data
+- `chat: ChatApi` - Unified chat namespace:
+  - `chat.completions.create` - Socket-native synchronous chat
+  - `chat.hosted.create` - Hosted synchronous chat via `/v1/chat/completions`
+  - `chat.runs.{create, get, cancel, streamEvents}` - Durable hosted chat runs via `/v1/chat/runs` with SSE replay
+  - `chat.tools` - Tool helpers (build, parse, validate)
+- `workflows: CreativeWorkflowsApi` - Durable explicit creative workflows via `/v1/creative-agent/workflows`
+  - `workflows.{start, list, get, events, streamEvents, resume, reseed, cancel}`
+  - `workflows.templates.{list, get, create, update, delete, fork}`
+- `replay: ReplayApi` - RunRecord write/list/get via `/v1/replay/records`
 - `apiClient: ApiClient` - Internal REST + WebSocket communication
 
 ### Core Entity Hierarchy
@@ -71,6 +136,9 @@ src/
 │   └── utils/            # Samplers, schedulers
 ├── Account/              # User auth & balance (CurrentAccount entity)
 ├── Stats/                # Leaderboard API
+├── Chat/                 # Socket chat, hosted REST chat, durable runs, hosted tools
+├── CreativeWorkflows/    # Durable explicit workflow API + template CRUD
+├── Replay/               # RunRecord ingest/list/get API
 ├── lib/                  # Shared utilities
 │   ├── AuthManager/      # Token/Cookie auth strategies
 │   ├── DataEntity.ts     # Base reactive entity
@@ -92,6 +160,19 @@ src/
 2. Server sends `jobState`, `jobProgress`, `jobResult` events → Updates Project/Job entities
 3. Entities emit events → User code receives 'progress', 'completed', 'failed'
 
+LLM chat flow:
+
+1. User calls `sogni.chat.completions.create()` → SDK sends `llmJobRequest` via WebSocket.
+2. Server streams `jobTokens` and terminal `llmJobResult` / `llmJobError` events.
+3. Streaming callers iterate `ChatStream`; non-streaming callers receive `ChatCompletionResult`.
+4. Hosted REST chat uses `sogni.chat.hosted.create()`; durable chat runs use `sogni.chat.runs`.
+
+Durable workflow flow:
+
+1. User calls `sogni.workflows.start()` with either an inline `input` plan or `workflowId` + `inputs`.
+2. REST API persists the workflow and returns a `CreativeWorkflowRecord`.
+3. Callers inspect `get()` / `events()` or consume `streamEvents()` with SSE resume support.
+
 ### Network Types
 
 - `fast` - High-end GPUs, faster but more expensive. Required for video generation.
@@ -110,9 +191,9 @@ The SDK supports two families of video models with **fundamentally different FPS
 - **Frame step constraint**: Frame count must follow pattern `1 + n*8` (i.e., 1, 9, 17, 25, 33, ...)
 - Example: 5 seconds at 24fps = 121 frames (snapped to 1 + 15*8 = 121)
 
-### Legacy Behavior (WAN 2.2 only)
+### WAN 2.2 Behavior
 
-**WAN 2.2 Models (`wan_v2.2-*`)** are the outlier with legacy behavior:
+**WAN 2.2 Models (`wan_v2.2-*`)** use a fixed internal generation rate:
 - **Always generate at 16fps internally**, regardless of the user's fps setting
 - The `fps` parameter (16 or 32) controls **post-render frame interpolation only**
 - `fps=16`: No interpolation, output matches generation (16fps)
@@ -222,9 +303,9 @@ const urls = await project.waitForCompletion();
 
 The SDK receives `LLMModelInfo` per model including `maxContextLength`, `maxOutputTokens` (min/max/default), and parameter constraints. Use these to configure `max_tokens` and display limits to users.
 
-**Caution**: `maxContextLength` from the server may not reflect the actual per-request limit on the worker (see sogni-socket and sogni-llm-nvidia CLAUDE.md for the llama-server `--parallel` slot division issue).
+Use the returned model constraints as request guidance, and prefer each model's advertised `maxOutputTokens.default` when a caller has not chosen `max_tokens`.
 
-### Thinking Models (Qwen3/3.5) — `chat_template_kwargs`
+### Thinking Models (Qwen3.x) — `chat_template_kwargs`
 
 Thinking mode is controlled via llama.cpp's `chat_template_kwargs: { enable_thinking }` per-request parameter. The SDK's `think` param maps to this:
 - `think: false` → `chat_template_kwargs: { enable_thinking: false }` (no thinking)
@@ -233,7 +314,7 @@ Thinking mode is controlled via llama.cpp's `chat_template_kwargs: { enable_thin
 
 The llama-server should run with default `--reasoning-budget -1` (unrestricted) so per-request control works.
 
-Qwen3/3.5 models generate thinking output in a separate `reasoning_content` field (OpenAI-compatible). The LLM worker wraps this in `<think>` tags inside `content` for the SDK. The SDK's `ChatCompletionChunk` type has NO `reasoning_content` field — only `content` and `tool_calls`.
+`ChatCompletionChunk` exposes generated text through `content` and tool invocations through optional `tool_calls`.
 
 **The solution for structured output**: Use **tool calling** (`tools` + `tool_choice: 'required'`). Tool call arguments are always forwarded by the worker regardless of thinking mode. The `workflow_text_chat_sogni_tools.mjs` example uses this pattern for all composition pipelines (video/image/audio prompt engineering).
 

package/CHANGELOG.md

@@ -1,3 +1,151 @@
+# [5.0.0-alpha.2](https://github.com/Sogni-AI/sogni-client/compare/v5.0.0-alpha.1...v5.0.0-alpha.2) (2026-05-16)
+
+
+### Features
+
+* forward runtimeConfig to chat runs for cloud executor parity ([c8002df](https://github.com/Sogni-AI/sogni-client/commit/c8002df94bc4cd1e163956803a9d237b64dc9f61))
+
+# [5.0.0-alpha.1](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.26...v5.0.0-alpha.1) (2026-05-15)
+
+
+* feat!: align SogniTools surface to canonical 24 tools, remove buildSogniTools ([2f04de9](https://github.com/Sogni-AI/sogni-client/commit/2f04de9fdb4d4423f3c46426488d6c520522c62f))
+
+
+### BREAKING CHANGES
+
+* buildSogniTools is no longer exported. Replace
+buildSogniTools(availableModels) with SogniTools.all, or set
+sogni_tools: 'creative-tools' on chat.hosted.create() / chat.runs.create()
+for server-side injection.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+
+# [4.2.0-alpha.26](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.25...v4.2.0-alpha.26) (2026-05-15)
+
+
+### Features
+
+* add replay records API ([ef98975](https://github.com/Sogni-AI/sogni-client/commit/ef98975a618523e23799aa28ab292609cbe32de6))
+
+# [4.2.0-alpha.25](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.24...v4.2.0-alpha.25) (2026-05-15)
+
+
+### Features
+
+* **workflows:** add templates CRUD, resume, reseed, and template-id runs ([fbec2b7](https://github.com/Sogni-AI/sogni-client/commit/fbec2b756df10cac3455626cd314a0fdbbde5982))
+
+# [4.2.0-alpha.24](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.23...v4.2.0-alpha.24) (2026-05-15)
+
+
+### Bug Fixes
+
+* **websocket:** preserve primary tab on new-tab open, fix promoted-primary rebind ([b74382a](https://github.com/Sogni-AI/sogni-client/commit/b74382a1b3bc02d61257bc3158ecbd96c10dee57))
+
+# [4.2.0-alpha.23](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.22...v4.2.0-alpha.23) (2026-05-15)
+
+
+### Bug Fixes
+
+* **chat:** validate remote media inputs ([daa078d](https://github.com/Sogni-AI/sogni-client/commit/daa078de22919698d87d1669298658a268565653))
+
+# [4.2.0-alpha.22](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.21...v4.2.0-alpha.22) (2026-05-15)
+
+
+### Features
+
+* **sdk:** add durable chat runs, flatten creative workflows, dual ESM build ([03d37d7](https://github.com/Sogni-AI/sogni-client/commit/03d37d7e873e3e6ac8718b407fd612bab757907b))
+
+# [4.2.0-alpha.21](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.20...v4.2.0-alpha.21) (2026-05-14)
+
+
+### Bug Fixes
+
+* **chat:** align hosted creative tool surfaces ([6e9e094](https://github.com/Sogni-AI/sogni-client/commit/6e9e094803bad7fdda994103f12bd40f726ae08e))
+
+
+### Features
+
+* **chat:** expose hosted completions wrapper ([da3799d](https://github.com/Sogni-AI/sogni-client/commit/da3799d2e99877d4bdd1990741611bac6243cdad))
+
+# [4.2.0-alpha.20](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.19...v4.2.0-alpha.20) (2026-05-12)
+
+
+### Features
+
+* **sdk:** add socket event subscription controls ([a450acd](https://github.com/Sogni-AI/sogni-client/commit/a450acd22087a690657c82de8e20cda96cd81512))
+
+# [4.2.0-alpha.19](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.18...v4.2.0-alpha.19) (2026-05-11)
+
+
+### Features
+
+* **sdk:** re-export ChatResponseFormat type from package root ([b48849c](https://github.com/Sogni-AI/sogni-client/commit/b48849c517375d7879d55653398a65f0d93f161c))
+
+# [4.2.0-alpha.18](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.17...v4.2.0-alpha.18) (2026-05-09)
+
+
+### Bug Fixes
+
+* **examples:** prepare sound-to-video audio uploads ([52e6cc2](https://github.com/Sogni-AI/sogni-client/commit/52e6cc210e67da49742229a9d1ff2d0edd5e14fa))
+
+# [4.2.0-alpha.17](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.16...v4.2.0-alpha.17) (2026-05-09)
+
+
+### Features
+
+* **alpha:** merge agentic harness refactor ([e4e1ddc](https://github.com/Sogni-AI/sogni-client/commit/e4e1ddcc4b1cd1272ed7ccc8c4b68ee5a9f7df8c))
+* **chat:** plumb response_format through createCompletion ([b711a68](https://github.com/Sogni-AI/sogni-client/commit/b711a68e4dc7fc27d8d781f8cab40f74b23393eb))
+
+# [4.2.0-alpha.16](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.15...v4.2.0-alpha.16) (2026-05-06)
+
+
+### Bug Fixes
+
+* **client:** preserve external job progress ([6390c16](https://github.com/Sogni-AI/sogni-client/commit/6390c165b9c492b8fa0df07b331cb6193c8b3916))
+
+# [4.2.0-alpha.15](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.14...v4.2.0-alpha.15) (2026-05-04)
+
+
+### Bug Fixes
+
+* update gpt-image-2 hosted tool guidance ([e346969](https://github.com/Sogni-AI/sogni-client/commit/e346969d8898d5a78ffd026bb0f2839a68366428))
+
+# [4.2.0-alpha.14](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.13...v4.2.0-alpha.14) (2026-05-04)
+
+
+### Features
+
+* **chat:** update creative workflow client metadata ([bda4a28](https://github.com/Sogni-AI/sogni-client/commit/bda4a28a78dcce41c4bf0fd796767019f8d69ce8))
+
+# [4.2.0-alpha.13](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.12...v4.2.0-alpha.13) (2026-05-04)
+
+
+### Features
+
+* **client:** expose GPT Image 2 project options ([5f8ff31](https://github.com/Sogni-AI/sogni-client/commit/5f8ff31d147c6869b9d7a238a45b117fee80fea1))
+* **client:** route GPT Image 2 aliases ([a946fe2](https://github.com/Sogni-AI/sogni-client/commit/a946fe2ae556a1d9d788d3bc0c3c7c0e223996f1))
+
+# [4.2.0-alpha.12](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.11...v4.2.0-alpha.12) (2026-05-03)
+
+
+### Bug Fixes
+
+* align Seedance routing and estimates ([93c3315](https://github.com/Sogni-AI/sogni-client/commit/93c3315352b014ce04583bbf7342691f4b88b63f))
+
+# [4.2.0-alpha.11](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.10...v4.2.0-alpha.11) (2026-05-01)
+
+
+### Bug Fixes
+
+* document monthly free Spark credits ([9a89533](https://github.com/Sogni-AI/sogni-client/commit/9a89533d3c12d05eec8b2ddf61b654879fcef243))
+
+# [4.2.0-alpha.10](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.9...v4.2.0-alpha.10) (2026-05-01)
+
+
+### Features
+
+* **seedance:** add guided partner video workflow ([36b8880](https://github.com/Sogni-AI/sogni-client/commit/36b8880f6fd33e3cfc7eeb0a828a2f3663c57996))
+
 # [4.2.0-alpha.9](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.8...v4.2.0-alpha.9) (2026-04-30)