SDK Guide

Drop-in SDKs for TypeScript and Python with standard chat-completion APIs.

Design Philosophy

Cortyxia SDKs follow a familiar chat-completion interface pattern, enabling drop-in replacement with minimal code changes. Install the package, set ISO_URL and ISO_TOKEN, and instantiate the client. The SDKs maintain standard 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.

TypeScript / Node.js

Installation

bash
npm install cortyxia

One-Shot Setup

Create a .env file in your project root. No dotenv package is required — the SDK reads it with the Node.js built-in fs module.

bash
1# .env
2ISO_URL=https://app.cortyxia.com
3ISO_TOKEN=<ISO_TOKEN>

Basic Usage

typescript
1import { Cortyxia } from "cortyxia";
2 
3const client = new Cortyxia({
4  isoUrl: process.env.ISO_URL || "https://app.cortyxia.com",
5  isoToken: process.env.ISO_TOKEN
6});
7 
8// Standard chat-completion call with automatic memory injection
9const response = await client.chat.completions.create({
10  model: "<MODEL_NAME>",
11  messages: [{ role: "user", content: "What did we discuss last week?" }]
12});
13 
14console.log(response.choices[0].message.content);
15// Cortyxia automatically retrieves relevant context from memory

Chat Completions

typescript
1// Non-streaming
2const response = await client.chat.completions.create({
3  model: "<MODEL_NAME>",
4  messages: [{ role: "user", content: "Hello!" }],
5  temperature: 0.7,
6  max_tokens: 1000
7});
8 
9// Streaming
10const stream = await client.chat.completions.stream({
11  model: "<MODEL_NAME>",
12  messages: [{ role: "user", content: "Tell me a story" }]
13});
14 
15for await (const chunk of stream) {
16  console.log(chunk);
17}

Memory Operations

typescript
1// Add memory
2const node = await client.memory.add(
3  "User's name is Alice Johnson",
4  ["user", "identity"]
5);
6 
7// Query memory
8const results = await client.memory.query(
9  "What's the user's name?",
10  10
11);
12 
13console.log(results.hits);

Observability

typescript
1const dashboard = await client.observability.dashboard("<PROJECT_ID>");
2console.log(dashboard);
3 
4const debt = await client.observability.knowledgeDebt("<PROJECT_ID>");
5console.log(debt);

Helper Functions

typescript
1import { answer } from "cortyxia";
2 
3const resp = await client.chat.completions.create({ messages: [...] });
4console.log(answer(resp)); // Clean assistant text, no JSON digging

Python

Installation

bash
pip install cortyxia

One-Shot Setup

Create a .env file in your project root. No python-dotenv dependency is required — the SDK reads it with the standard library pathlib module.

bash
1# .env
2ISO_URL=https://app.cortyxia.com
3ISO_TOKEN=<ISO_TOKEN>

Basic Usage

python
1from cortyxia import Cortyxia
2 
3client = Cortyxia(
4    iso_url="https://app.cortyxia.com",
5    iso_token="<ISO_TOKEN>"
6)
7 
8response = client.chat.completions.create(
9    model="<MODEL_NAME>",
10    messages=[{"role": "user", "content": "What did we discuss last week?"}]
11)
12 
13print(response["choices"][0]["message"]["content"])

Chat Completions

python
1# Non-streaming
2response = client.chat.completions.create(
3    model="<MODEL_NAME>",
4    messages=[{"role": "user", "content": "Hello!"}],
5    temperature=0.7,
6    max_tokens=1000
7)
8 
9# Streaming
10for chunk in client.chat.completions.stream(
11    model="<MODEL_NAME>",
12    messages=[{"role": "user", "content": "Tell me a story"}]
13):
14    print(chunk)

Memory Operations

python
1# Add memory
2client.memory.add(
3    "User's name is Alice Johnson",
4    ["user", "identity"]
5)
6 
7# Query memory
8results = client.memory.query("What's the user's name?", limit=10)
9print(results["hits"])

Observability

python
1dashboard = client.observability.dashboard("<PROJECT_ID>")
2print(dashboard)
3 
4debt = client.observability.knowledge_debt("<PROJECT_ID>")
5print(debt)

Helper Functions

python
1from cortyxia import answer
2 
3resp = client.chat.completions.create(messages=[...])
4print(answer(resp))  # Clean assistant text, no JSON digging

Migration from Other SDKs

The migration is two lines: change the import and swap the constructor. Your prompts, message format, and response parsing stay the same.

TypeScript

typescript
1// Before — OpenAI SDK
2import OpenAI from "openai";
3const client = new OpenAI({ apiKey: "sk-..." });
4const response = await client.chat.completions.create({ model, messages });
5 
6// After — Cortyxia
7import { Cortyxia } from "cortyxia";
8const client = new Cortyxia({
9  isoUrl: "https://app.cortyxia.com",
10  isoToken: "<ISO_TOKEN>"
11});
12const response = await client.chat.completions.create({ model, messages });

Python

python
1# Before — OpenAI SDK
2from openai import OpenAI
3client = OpenAI(api_key="sk-...")
4response = client.chat.completions.create(model=model, messages=messages)
5 
6# After — Cortyxia
7from cortyxia import Cortyxia
8client = Cortyxia(iso_url="https://app.cortyxia.com", iso_token="<ISO_TOKEN>")
9response = client.chat.completions.create(model=model, messages=messages)

Configuration

Environment Variables

bash
1# Required
2ISO_URL=https://app.cortyxia.com
3ISO_TOKEN=<ISO_TOKEN>

Credentials are stored locally with 0o600 permissions. Keep ISO_TOKEN out of source control and load it from a secret manager or environment file in production.

Error Handling

TypeScript

typescript
1import { Cortyxia, CortyxiaError } from "cortyxia";
2 
3try {
4  const client = new Cortyxia({
5    isoUrl: "https://app.cortyxia.com",
6    isoToken: "<ISO_TOKEN>"
7  });
8  const response = await client.chat.completions.create({ messages: [...] });
9} catch (err) {
10  if (err instanceof CortyxiaError) {
11    console.error("Request failed:", err.message);
12  }
13}

Python

python
1from cortyxia import Cortyxia, CortyxiaError
2 
3try:
4    client = Cortyxia(iso_url="https://app.cortyxia.com", iso_token="<ISO_TOKEN>")
5    response = client.chat.completions.create(messages=[...])
6except CortyxiaError as e:
7    print(f"Request failed: {e}")
← Token OptimizationCLI Guide