SDK Guide

Drop-in SDKs for TypeScript, Python, and Java with OpenAI-compatible APIs.

Design Philosophy

Cortyxia SDKs follow an OpenAI-compatible interface pattern, enabling drop-in replacement with minimal code changes. The SDKs maintain identical method signatures, parameter structures, and response formats while automatically handling memory injection, context management, and provider routing behind the scenes.

Each SDK organizes functionality into logical namespaces: chat for AI completion requests, memory for direct memory operations, and observability for telemetry and analytics access.

TypeScript / Node.js

Installation

npm install @iso/sdk

Basic Usage

import { IsoSDK } from '@iso/sdk';

const iso = new IsoSDK({
  isoUrl: 'http://localhost:3000',
  isoToken: 'iso-a1b2c3d4sxxxxxxxxxxxxxxxx'
});

// Drop-in replacement for openai.chat.completions.create
const response = await iso.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: 'What did we discuss last week?' }
  ]
});

console.log(response.choices[0].message.content);
// ISO automatically retrieves relevant context from memory

Memory Operations

// Add memory
await iso.memory.add(
  "User's name is Alice Johnson",
  ['user', 'identity'],
  'manual'
);

// Query memory
const results = await iso.memory.query(
  "What's the user's name?",
  10
);

console.log(results.hits);

Observability

// Dashboard metrics
const dashboard = await iso.observability.dashboard('project-id');
console.log(dashboard.tokens_saved);
console.log(dashboard.memory_efficiency_pct);

// Knowledge debt analysis
const debt = await iso.observability.knowledgeDebt('project-id');
console.log(debt.debt_score);

Python

Installation

pip install iso-sdk

Basic Usage

from iso_client import IsoSDK

iso = IsoSDK(
    iso_url="http://localhost:3000",
    iso_token="iso-a1b2c3d4sxxxxxxxxxxxxxxxx"
)

response = iso.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What did we discuss last week?"}]
)

print(response["choices"][0]["message"]["content"])

Memory Operations

# Add memory
iso.memory.add(
    "User's name is Alice Johnson",
    tags=["user", "identity"],
    source="manual"
)

# Query memory
results = iso.memory.query("What's the user's name?", limit=10)
print(results["hits"])

Java

Installation (Maven)

<dependency>
    <groupId>ai.iso</groupId>
    <artifactId>iso-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Basic Usage

import ai.iso.IsoSDK;

IsoSDK iso = new IsoSDK(
    "http://localhost:3000",
    "iso-a1b2c3d4sxxxxxxxxxxxxxxxx"
);

Chat.CompletionResponse response = iso.chat()
    .completions()
    .create(
        "gpt-4o-mini",
        List.of(
            new Chat.Message("user", "What did we discuss last week?")
        )
    );

System.out.println(response.choices().get(0).message().content());

Memory Operations

// Add memory
Memory.MemoryNode node = iso.memory().add(
    "User's name is Alice Johnson",
    List.of("user", "identity"),
    "manual"
);

// Query memory
Memory.MmuQueryResponse results = iso.memory().query(
    "What's the user's name?",
    10
);

for (Memory.Hit hit : results.hits()) {
    System.out.println(hit.content() + " (score: " + hit.score() + ")");
}

Migration from OpenAI SDK

TypeScript Migration

// Before
import OpenAI from 'openai';
const openai = new OpenAI({ apiKey: 'sk-...' });
const response = await openai.chat.completions.create({ model, messages });

// After
import { IsoSDK } from '@iso/sdk';
const iso = new IsoSDK({ isoUrl, isoToken });
const response = await iso.chat.completions.create({ model, messages });

Python Migration

# Before
from openai import OpenAI
openai = OpenAI(api_key="sk-...")
response = openai.chat.completions.create(model=model, messages=messages)

# After
from iso_client import IsoSDK
iso = IsoSDK(iso_url="...", iso_token="iso-...")
response = iso.chat.completions.create(model=model, messages=messages)

Configuration

Environment Variables

# Required
ISO_URL=http://localhost:3000
ISO_TOKEN=iso-a1b2c3d4sxxxxxxxxxxxxxxxx

# Optional
TELEMETRY_URL=http://localhost:4100
ISO_TIMEOUT=120
← Token OptimizationDeployment Guide