Sogni Protocol

@sogni-ai/sogni-protocol is the language-neutral Sogni package — pure JSON artifacts (schemas, OpenAI tool manifests, prompt contracts, enums, catalogs) with zero runtime dependencies, no build step, and no native binaries. Every Sogni SDK reads from this package so contracts stay in lockstep across languages.

Status: alpha. Current npm version is 1.0.0-alpha.2; current protocolVersion is 1.1.0. Pin a specific version while the surface stabilizes.

#When to use this package

The protocol package is what the SDKs themselves consume internally. If you only need one schema or one manifest, importing this package directly is cheaper than pulling the full intelligence client.

#Installation

npm install @sogni-ai/sogni-protocol@alpha

The package ships only JSON files plus a version.json. There is nothing to import as a JS module — every consumer reads files via subpath exports.

#What's inside

#Importing artifacts

#TypeScript (Node 20+)

import manifest from '@sogni-ai/sogni-protocol/manifests/openai-tools.json' with { type: 'json' };
import statuses from '@sogni-ai/sogni-protocol/enums/chat-run-status.json' with { type: 'json' };
import generateImageSchema from '@sogni-ai/sogni-protocol/schemas/tools/generate_image.schema.json' with { type: 'json' };

type ChatRunStatus = (typeof statuses.values)[number];

For older Node or bundlers without JSON import assertions, read the files directly:

import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';

const manifestPath = fileURLToPath(
  new URL(import.meta.resolve('@sogni-ai/sogni-protocol/manifests/openai-tools.json'))
);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));

#Python

Most Python ecosystems will fetch the npm artifact at build time or vendor it once. Direct read:

import json, pathlib

manifest = json.loads(
    pathlib.Path("node_modules/@sogni-ai/sogni-protocol/manifests/openai-tools.json").read_text()
)

#Swift (build-time codegen via quicktype)

quicktype --src-lang schema --lang swift \
  --src node_modules/@sogni-ai/sogni-protocol/schemas/tools/*.schema.json \
  --out Sources/SogniKit/Models/Generated/ToolSchemas.swift

This is the same pattern SogniKit uses internally to keep its Swift types shape-locked with the JS SDK.

#Any language

The package is plain JSON. Vendor the files into your repo, fetch them at build time, or read them from node_modules/@sogni-ai/sogni-protocol/ — whatever fits your toolchain.

#Versioning policy

version.json#protocolVersion is independent of the npm package version. It follows semver against the wire spec:

• Major — removing or renaming any schema, enum, or manifest field. Breaks consumers.
• Minor — adding new optional fields, new tools, new manifests. Backwards-compatible.
• Patch — description / prose changes only (prompt text, schema descriptions). No shape change.

SDKs may check protocolVersion at startup and refuse to operate against an incompatible major.

The npm version (currently 1.0.0-alpha.2) covers packaging and repo-level changes; the protocolVersion covers wire-spec changes that SDKs validate against. The two are tracked separately on purpose.

import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { protocolVersion } = JSON.parse(
  readFileSync(require.resolve('@sogni-ai/sogni-protocol/version.json'), 'utf8')
);

if (!protocolVersion.startsWith('1.')) {
  throw new Error(`This SDK requires protocolVersion 1.x but found ${protocolVersion}`);
}

#Relationship to the other SDKs

                      @sogni-ai/sogni-protocol          (this package — JSON only)
                                 │
                                 ▼
            ┌────────────────────┴────────────────────┐
            ▼                                         ▼
   @sogni-ai/sogni-client            @sogni-ai/sogni-intelligence-client
   (raw SDK — low-level)             (contracts + wrapper, depends on sogni-client)
                                                       │
                                                       ▼
                              @sogni-ai/sogni-creative-agent-skill
                              (CLI + SKILL.md for Claude Code, OpenClaw, etc.)

• @sogni-ai/sogni-protocol — pure JSON artifacts; the source of truth.
• @sogni-ai/sogni-client — raw TypeScript SDK; consumes the protocol package for shape contracts.
• @sogni-ai/sogni-intelligence-client — public mid-tier package: ContractRegistry, AssetManifest, RunRecord, hosted-tool validators, n8n-friendly wrappers. Migrating to consume protocol artifacts directly.
• @sogni-ai/sogni-creative-agent-skill — agent runtime CLI; depends on intelligence-client.
• SogniKit (Swift) — regenerates its types from schemas/ at build time.

#Source

• GitHub repository
• npm: @sogni-ai/sogni-protocol

Issues and schema-shape feedback are welcome on the GitHub repo. Because protocolVersion bumps fan out to every SDK, treat any change request as a coordinated release across all consumers.