UltraContext

https://ultracontext.ai/docs
Admin
UltraContext is a context API for AI agents that simplifies managing, versioning, and manipulating...
Tokens:36,520
Snippets:175
Trust Score:4.4
Update:8 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Create, Append, and Get Context (cURL)

Source: https://ultracontext.ai/docs/api-reference/introduction

A quick example demonstrating how to create a new context, append a user message to it, and then retrieve the context using cURL commands. Requires an API key and manual construction of requests.

```bash
# create a context
curl -X POST https://api.ultracontext.ai/contexts \
  -H "Authorization: Bearer $ULTRACONTEXT_API_KEY" \
  -H "Content-Type: application/json"

# append a message
curl -X POST https://api.ultracontext.ai/contexts/ctx_abc123 \
  -H "Authorization: Bearer $ULTRACONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "Hello!"}'

# retrieve the context
curl https://api.ultracontext.ai/contexts/ctx_abc123 \
  -H "Authorization: Bearer $ULTRACONTEXT_API_KEY"
```

--------------------------------

### Environment Variable Setup for API Key (.env)

Source: https://ultracontext.ai/docs/api-reference/authentication

Provides examples for setting up environment variables to store API keys. It shows both a production `.env` file and a template `.env.example` file that should be committed to version control.

```bash
# .env
ULTRACONTEXT_API_KEY=uc_live_xxxxx

# .env.example (commit this)
ULTRACONTEXT_API_KEY=uc_live_your_key_here
```

--------------------------------

### Quick Start: Create, Append, and Get Context (Python)

Source: https://ultracontext.ai/docs/api-reference/introduction

A quick example demonstrating how to create a new context, append a user message to it, and then retrieve the context using the UltraContext Python SDK. Requires the 'ultracontext' package and an API key.

```python
from ultracontext import UltraContext
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])

# create a context
ctx = uc.create()

# append a message
uc.append(ctx["id"], {"role": "user", "content": "Hello!"})

# retrieve the context
result = uc.get(ctx["id"])
```

--------------------------------

### Start Fresh with Summary

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This API allows you to start a new context by summarizing the previous one. It involves fetching the latest context, generating a summary, creating a new context, and appending the summary to it.

```APIDOC
## Start Fresh with Summary

### Description
This process allows you to create a new context that begins with a summary of the preceding conversation or data.

### Method
This is a multi-step process involving several API calls.

### Steps

1.  **Get latest context**
    *   **Description**: Retrieve the most recent context to access its messages.
    *   **Code Example (TypeScript)**:
        ```typescript
        // list all contexts (newest first)
        const { data: contexts } = await uc.get();

        // get messages from the latest
        const { data: messages } = await uc.get(contexts[0].id);
        ```
    *   **Code Example (Python)**:
        ```python
        # list all contexts (newest first)
        contexts = uc.get()["data"]

        # get messages from the latest
        messages = uc.get(contexts[0]["id"])["data"]
        ```

2.  **Summarize context**
    *   **Description**: Generate a concise summary from the retrieved messages.
    *   **Code Example (TypeScript)**:
        ```typescript
        const summary = await generateSummary(messages);
        ```
    *   **Code Example (Python)**:
        ```python
        summary = generate_summary(messages)
        ```

3.  **Create new context**
    *   **Description**: Initiate a new, empty context.
    *   **Code Example (TypeScript)**:
        ```typescript
        const ctx = await uc.create();
        ```
    *   **Code Example (Python)**:
        ```python
        ctx = uc.create()
        ```

4.  **Append summary**
    *   **Description**: Add the generated summary as a system message to the newly created context.
    *   **Code Example (TypeScript)**:
        ```typescript
        await uc.append(ctx.id, {
            role: 'system',
            content: `Previous context summary:\n${summary}`,
        });
        ```
    *   **Code Example (Python)**:
        ```python
        uc.append(ctx["id"], {
            "role": "system",
            "content": f"Previous context summary:\n{summary}",
        })
        ```

### Parameters
*   **`uc`**: Ultracontext client instance.
*   **`contexts`**: List of context objects.
*   **`messages`**: List of message objects from the latest context.
*   **`summary`**: String containing the generated summary.
*   **`ctx`**: New context object.

### Request Example
*(This section illustrates the conceptual flow rather than a single request body, as it involves multiple steps.)*

### Response
*   **Success Response**: The process completes successfully when all steps are executed without errors.
*   **Response Example**: *(No direct response example for the entire flow, but individual calls return context and message data.)*
```

--------------------------------

### Quick Start: Create, Append, and Get Context (TypeScript)

Source: https://ultracontext.ai/docs/api-reference/introduction

A quick example demonstrating how to create a new context, append a user message to it, and then retrieve the context using the UltraContext Node.js SDK. Requires the 'ultracontext' package and an API key.

```typescript
import { UltraContext } from 'ultracontext';
const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });

// create a context
const ctx = await uc.create();

// append a message
await uc.append(ctx.id, { role: 'user', content: 'Hello!' });

// retrieve the context
const { data } = await uc.get(ctx.id);
```

--------------------------------

### Switch LLM Frameworks: CrewAI (Python)

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This Python example shows how to integrate UltraContext with CrewAI. After retrieving context and parsing it with `parse_for_crewai`, the `crew.kickoff` method is called with the prepared inputs. The output is the result from the CrewAI execution.

```python
from ultracontext import UltraContext
from crewai import Agent, Task, Crew
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])
crew = Crew(agents=[...], tasks=[...])

# retrieve context
messages = uc.get(context_id)["data"]

# prepare messages for CrewAI
parsed = parse_for_crewai(messages)

result = crew.kickoff(inputs=parsed)
```

--------------------------------

### Install UltraContext Package (Node.js)

Source: https://ultracontext.ai/docs/quickstart/nodejs

Installs the ultracontext package for Node.js using various package managers like npm, yarn, pnpm, and bun. Ensure you have Node.js and a compatible package manager installed.

```bash
npm install ultracontext
```

```bash
yarn add ultracontext
```

```bash
pnpm add ultracontext
```

```bash
bun add ultracontext
```

--------------------------------

### Environment Setup

Source: https://ultracontext.ai/docs/api-reference/authentication

Configure your environment variables to securely manage your Ultracontext AI API keys. It is recommended to use a `.env` file for local development and a secure secret management system for production.

```APIDOC
## Environment Setup

### Description
Securely manage your API keys by using environment variables. This example demonstrates setting up the `ULTRACONTEXT_API_KEY` in a `.env` file.

### Environment Variable
- **ULTRACONTEXT_API_KEY**: Your Ultracontext AI API key.

### Example `.env` file
```
# .env
ULTRACONTEXT_API_KEY=uc_live_xxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Example `.env.example` file (for version control)
```
# .env.example
ULTRACONTEXT_API_KEY=uc_live_your_key_here
```

### Usage with SDK (TypeScript)
```typescript
import { UltraContext } from 'ultracontext';

const uc = new UltraContext({
  apiKey: process.env.ULTRACONTEXT_API_KEY! 
});
```
```

--------------------------------

### Forking by Version

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Gets the exact state of a context after a specific update or delete, identified by its version number.

```APIDOC
## Forking by Version

### Description
Gets the exact state of a context after a specific update or delete, identified by its version number.

### Method
POST

### Endpoint
`/contexts/fork`

### Parameters
#### Request Body
- **from** (string) - Required - The ID of the context to fork from.
- **version** (integer) - Required - The specific version number to fork.

### Request Example (TypeScript)
```typescript
const fork = await uc.create({ from: 'ctx_abc123', version: 1 });
```

### Request Example (Python)
```python
fork = uc.create(from_='ctx_abc123', version=1)
```
```

--------------------------------

### GET /contexts

Source: https://ultracontext.ai/docs/api-reference/list-contexts

Retrieves a list of all root contexts for your project, ordered by creation date in descending order.

```APIDOC
## GET /contexts

### Description
List all root contexts for your project. Sorted by `created_at` descending (newest first).

### Method
GET

### Endpoint
/contexts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of contexts to return. Defaults to 20.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of Context objects.
  - **id** (string) - Unique identifier (ctx_...). Example: ctx_a1b2c3d4e5f6
  - **metadata** (object) - User-defined metadata.
  - **created_at** (string) - ISO 8601 timestamp.

#### Response Example
```json
{
  "data": [
    {
      "id": "ctx_a1b2c3d4e5f6",
      "metadata": {},
      "created_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Forking by Index

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Gets the state of a context by including the first N messages, up to and including the message at the specified index.

```APIDOC
## Forking by Index

### Description
Gets the state of a context by including the first N messages, up to and including the message at the specified index.

### Method
POST

### Endpoint
`/contexts/fork`

### Parameters
#### Request Body
- **from** (string) - Required - The ID of the context to fork from.
- **at** (integer) - Required - The index of the last message to include (0-based).

### Request Example (TypeScript)
```typescript
const fork = await uc.create({ from: 'ctx_abc123', at: 5 });
```

### Request Example (Python)
```python
fork = uc.create(from_='ctx_abc123', at=5)
```
```

--------------------------------

### Switch LLM Frameworks: Anthropic SDK (TypeScript)

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This example illustrates retrieving context via UltraContext and formatting it for the Anthropic SDK. It relies on a `parseForAnthropic` function for message transformation. The output is the response from Anthropic's messages API, with parameters like model and max_tokens specified.

```typescript
import { UltraContext } from 'ultracontext';
import Anthropic from '@anthropic-ai/sdk';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const anthropic = new Anthropic();

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for Anthropic
const parsed = parseForAnthropic(messages);

const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    ...parsed,
});
```

--------------------------------

### Resume Chats

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This section details how to resume existing chat conversations by retrieving and utilizing stored context. It provides examples in TypeScript and Python for creating new contexts, appending messages, and retrieving existing chat histories.

```APIDOC
## Resume Chats

### Description
Resuming chats is simple. Just retrieve the associated context and continue the conversation from there.

### Method
POST (for create), POST (for append), GET (for retrieve)

### Endpoint
- `/create` (implicit)
- `/append` (implicit)
- `/get` (implicit)

### Parameters
#### Path Parameters
None

#### Query Parameters
- `contextId` (string) - Required - The ID of the context to retrieve.
- `at` (integer) - Optional - The index of the checkpoint to retrieve messages up to.

#### Request Body
For `append`:
- `role` (string) - Required - The role of the message sender ('user' or 'assistant').
- `content` (string) - Required - The message content.
- `metadata` (object) - Optional - Additional metadata for the message.

### Request Example
**TypeScript:**
```typescript
import { UltraContext } from 'ultracontext';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });

// on first visit: create context, store ID in your session/database
const ctx = await uc.create();

// on each message exchange: append both sides
await uc.append(ctx.id, { role: 'user', content: userMessage });
await uc.append(ctx.id, { role: 'assistant', content: assistantResponse });

// on return visit: retrieve existing context
const { data: messages } = await uc.get(ctx.id);
// → ready to send to LLM or display in UI
```

**Python:**
```python
from ultracontext import UltraContext
import os

nc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])

# on first visit: create context, store ID in your session/database
ctx = uc.create()

# on each message exchange: append both sides
nc.append(ctx["id"], {"role": "user", "content": user_message})
nc.append(ctx["id"], {"role": "assistant", "content": assistant_response})

# on return visit: retrieve existing context
result = uc.get(ctx["id"])
# → ready to send to LLM or display in UI
```

### Response
#### Success Response (200)
- `data` (array) - An array of message objects, each containing `role`, `content`, and optional `metadata`.

#### Response Example
```json
{
  "data": [
    {
      "role": "user",
      "content": "Hello!"
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help you today?"
    }
  ]
}
```
```

--------------------------------

### Retrieve to Checkpoint

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This section explains how to retrieve chat context up to a specific point, marked by metadata. It includes steps for marking checkpoints, finding their index, and retrieving messages, with examples in TypeScript and Python.

```APIDOC
## Retrieve to Checkpoint

### Description
Retrieve the context up to a specific checkpoint.

### Method
POST (for append), GET (for retrieve)

### Endpoint
- `/append` (implicit)
- `/get` (implicit)
- `/create` (for forking, implicit)

### Parameters
#### Path Parameters
None

#### Query Parameters
- `contextId` (string) - Required - The ID of the context to retrieve.
- `at` (integer) - Optional - The index of the checkpoint to retrieve messages up to.
- `from_` (string) - Optional (for create) - The context ID to fork from.

#### Request Body
For `append`:
- `role` (string) - Required - The role of the message sender ('user' or 'assistant').
- `content` (string) - Required - The message content.
- `metadata` (object) - Required - Additional metadata for the message, including a `checkpoint` key.

### Request Example
**1. Mark your checkpoint with metadata as you go:**

**TypeScript:**
```typescript
await uc.append(contextId, {
    role: 'assistant',
    content: 'I now have full context of your codebase.',
    metadata: { checkpoint: 'codebase_indexed' },
});
```

**Python:**
```python
nc.append(context_id, {
    "role": "assistant",
    "content": "I now have full context of your codebase.",
    "metadata": {"checkpoint": "codebase_indexed"},
})
```

**2. Find checkpoint index:**

**TypeScript:**
```typescript
const { data: history } = await uc.get(contextId);
const checkpointIndex = history.findIndex((m) => m.metadata?.checkpoint === 'codebase_indexed');
```

**Python:**
```python
result = uc.get(context_id)
history = result["data"]
checkpoint_index = next(i for i, m in enumerate(history) if m.get("metadata", {}).get("checkpoint") == "codebase_indexed")
```

**3. Retrieve messages up to checkpoint:**

**TypeScript:**
```typescript
const { data: messages } = await uc.get(contextId, { at: checkpointIndex });
```

**Python:**
```python
result = uc.get(context_id, at=checkpoint_index)
messages = result["data"]
```

**4. (Optional) Fork context from checkpoint:**

**TypeScript:**
```typescript
const fork = await uc.create({ from: contextId, at: checkpointIndex });
```

**Python:**
```python
fork = uc.create(from_=context_id, at=checkpoint_index)
```

### Response
#### Success Response (200)
- `data` (array) - An array of message objects up to the specified checkpoint.

#### Response Example
```json
{
  "data": [
    {
      "role": "user",
      "content": "Initial query."
    },
    {
      "role": "assistant",
      "content": "Response to initial query.",
      "metadata": {}
    },
    {
      "role": "assistant",
      "content": "I now have full context of your codebase.",
      "metadata": {"checkpoint": "codebase_indexed"}
    }
  ]
}
```
```

--------------------------------

### Fetch Contexts: Current State, Version, Timestamp, or Index

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

Demonstrates fetching context data using different parameters like current state, specific version, a point in time (ISO 8601 timestamp), or by message index. It also shows how to retrieve the full mutation history.

```typescript
// current state
const { data, version } = await uc.get(contextId);

// by index — first N messages (0 to at)
const { data } = await uc.get(contextId, { at: 5 });

// by timestamp — state at that moment. Uses ISO 8601 format
const { data } = await uc.get(contextId, { before: '2024-01-10T10:30:00Z' });

// by version — exact state after that mutation
const { data } = await uc.get(contextId, { version: 1 });

// with history — see all mutations
const { data, version, versions } = await uc.get(contextId, { history: true });
```

```python
# current state
result = uc.get(context_id)

# by index — first N messages (0 to at)
result = uc.get(context_id, at=5)

# by timestamp — state at that moment. Uses ISO 8601 format
result = uc.get(context_id, before="2024-01-10T10:30:00Z")

# by version — exact state after that mutation
result = uc.get(context_id, version=1)

# with history — see all mutations
result = uc.get(context_id, history=True)
```

--------------------------------

### Create and Manage Contexts (Node.js)

Source: https://ultracontext.ai/docs/index

Shows how to create new contexts, optionally with metadata, and how to list, retrieve, and fork existing contexts using the UltraContext library in Node.js. It covers retrieving contexts by ID, message index, timestamp, version, or with full history.

```javascript
import { UltraContext } from 'ultracontext';
const uc = new UltraContext({ apiKey: 'uc_live_...' });

// create new contexts
const ctx = await uc.create();
const ctx2 = await uc.create({ metadata: { user_id: '123' } });

// list all contexts
const { data } = await uc.get();

// retrieve a context (by id, message index, timestamp or version)
const { data } = await uc.get('ctx_abc123');
const { data } = await uc.get('ctx_abc123', { at: 5 });
const { data } = await uc.get('ctx_abc123', { before: '2024-01-01T00:00:00Z' });
const { data } = await uc.get('ctx_abc123', { version: 2 });

// retrieve a context with history
const { data, versions } = await uc.get('ctx_abc123', { history: true });

// fork a context from an existing one
const fork = await uc.create({ from: 'ctx_abc123' });

```

--------------------------------

### Time Travel by Timestamp (TypeScript, Python)

Source: https://ultracontext.ai/docs/guides/view-context-history

Get the state of a context at a specific moment in time, even between appends, by using the `before` parameter with an ISO timestamp in the `get` method. This is useful for historical analysis.

```typescript
const { data } = await uc.get(contextId, { before: '2024-01-10T10:30:00Z' });
```

```python
result = uc.get(context_id, before="2024-01-10T10:30:00Z")
```

--------------------------------

### Get Context Version History (TypeScript, Python)

Source: https://ultracontext.ai/docs/guides/view-context-history

Retrieve the version history of a context by passing `history: true` to the `get` method. This returns the current state, version number, and the complete version history. Dependencies include the Ultracontext library.

```typescript
const { data, version, versions } = await uc.get(contextId, { history: true });
```

```python
result = uc.get(context_id, history=True)
data, version, versions = result["data"], result["version"], result["versions"]
```

--------------------------------

### POST /contexts

Source: https://ultracontext.ai/docs/api-reference/create-context

Create a new context. Optionally copy from an existing context using the `from` parameter, and specify a `version` to fork from a specific version.

```APIDOC
## POST /contexts

### Description
Create a new context. Optionally copy from an existing context using the `from` parameter, and specify a `version` to fork from a specific version.

### Method
POST

### Endpoint
/contexts

### Parameters
#### Request Body
- **from** (string) - Optional - Source context ID to copy from
- **version** (integer) - Optional - When forking with `from`, copy from this specific version (0-indexed)
- **at** (integer) - Optional - When forking with `from`, copy only messages 0 through this index
- **before** (string) - Optional - When forking with `from`, copy point-in-time state before this ISO timestamp
- **metadata** (object) - Optional - User-defined metadata for this context

### Request Example
```json
{
  "from": "ctx_existing_context_id",
  "version": 5,
  "metadata": {
    "user_id": "user123",
    "project_name": "Project Alpha"
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - Unique identifier (ctx_...)
- **metadata** (object) - User-defined metadata
- **created_at** (string) - ISO 8601 timestamp

#### Response Example
```json
{
  "id": "ctx_new_context_id",
  "metadata": {
    "user_id": "user123",
    "project_name": "Project Alpha"
  },
  "created_at": "2023-10-27T10:00:00Z"
}
```

#### Error Responses
- **400** - Invalid index (when using `at` with `from`)
- **404** - Version not found (when using `version` with `from`)
- **500** - Server error
```

--------------------------------

### Get Context Endpoint Definition (OpenAPI)

Source: https://ultracontext.ai/docs/api-reference/get-context

Defines the GET /contexts/{id} endpoint for retrieving conversation contexts. It supports various query parameters for versioning, point-in-time retrieval, and history inclusion. The response includes context messages and optionally version history.

```yaml
openapi: 3.1.0
info:
  title: UltraContext
  description: >-
    Manage conversation contexts with automatic versioning. Every mutation
    creates a new branch, preserving full history.
  version: 1.1.0
servers:
  - url: https://api.ultracontext.ai
security:
  - bearerAuth: []
paths:
  /contexts/{id}:
    get:
      summary: Get context
      description: Get context with all messages. Returns latest version by default.
      operationId: getContext
      parameters:
        - name: id
          in: path
          required: true
          description: Context ID (ctx_...)
          schema:
            type: string
        - name: version
          in: query
          description: Version number to retrieve (0-indexed). Defaults to latest.
          schema:
            type: integer
        - name: at
          in: query
          description: Return messages 0 through this index (point-in-time retrieval)
          schema:
            type: integer
        - name: before
          in: query
          description: >-
            ISO timestamp. Returns point-in-time state: finds version created
            before timestamp, then filters messages by created_at.
          schema:
            type: string
            format: date-time
        - name: history
          in: query
          description: Include version history in response
          schema:
            type: boolean
      responses:
        '200':
          description: Context messages with version info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetContextResponse'
        '400':
          description: Invalid index (when using ?at=)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Context not found, version not found, or index out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GetContextResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        version:
          type: integer
          description: Current version number being viewed
        versions:
          type: array
          items:
            $ref: '#/components/schemas/Version'
          description: Version history (only present when ?history=true)
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
    Message:
      type: object
      description: Message with unwrapped content. Your fields are merged at the top level.
      properties:
        id:
          type: string
          description: Unique identifier (msg_...)
          example: msg_x1y2z3
        index:
          type: integer
          description: 0-based position in context
          example: 0
        metadata:
          type: object
          additionalProperties: true
      additionalProperties: true
    Version:
      type: object
      description: Version history entry with audit trail
      properties:
        version:
          type: integer
          description: 0-indexed version number
          example: 0
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        operation:
          type: string
          enum:
            - create
            - update
            - delete
          description: Operation that created this version
        affected:
          type: array
          items:
            type: string
          nullable: true
          description: Message IDs affected by update/delete operations. Null for create.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            User-provided audit metadata (e.g., reason, performed_by). Only
            present when provided.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from your UltraContext dashboard

```

--------------------------------

### Compare Prompts in Ultracontext AI (TypeScript & Python)

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

This code demonstrates how to compare different prompts within the Ultracontext AI framework. It sets up a baseline context, forks it to create variations with different prompts (formal and casual tones), and then runs these variations in parallel to generate responses. The comparison allows for evaluating the impact of prompt changes on the output.

```typescript
// 1. set up baseline
const baseline = await uc.create()
await uc.append(baseline.id, [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Help me write a marketing email.' }
])

// 2. fork for experiments
const formal = await uc.create({
  from: baseline.id,
  metadata: { experiment: 'formal_tone' }
})
await uc.append(formal.id, {
  role: 'system',
  content: 'Write in a formal, professional tone.'
})

const casual = await uc.create({
  from: baseline.id,
  metadata: { experiment: 'casual_tone' }
})
await uc.append(casual.id, {
  role: 'system',
  content: 'Write in a friendly, casual tone.'
})

// 3. run in parallel
const [responseA, responseB] = await Promise.all([
  generate(formal.id),
  generate(casual.id)
])
```

```python
# 1. set up baseline
baseline = uc.create()
uc.append(baseline["id"], [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Help me write a marketing email."}
])

# 2. fork for experiments
formal = uc.create(from_=baseline["id"], metadata={"experiment": "formal_tone"})
uc.append(formal["id"], {"role": "system", "content": "Write in a formal, professional tone."})

casual = uc.create(from_=baseline["id"], metadata={"experiment": "casual_tone"})
uc.append(casual["id"], {"role": "system", "content": "Write in a friendly, casual tone."})

# 3. run both
response_a = generate(formal["id"])
response_b = generate(casual["id"])
```

--------------------------------

### Get Current Context State

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

Retrieves the most recent state of a given context. This is the default behavior when no specific parameters are provided.

```typescript
const { data, version } = await uc.get(contextId);
```

```python
result = uc.get(context_id)
data, version = result["data"], result["version"]
```

--------------------------------

### List All Contexts

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

Retrieves a list of all contexts within the project, typically sorted by creation date in descending order. Supports limiting the number of results returned.

```typescript
const { data } = await uc.get();
// → {
//     data: [
//       { id: 'ctx_xyz789', created_at: '2024-01-15T10:00:00Z', metadata: {} },
//       { id: 'ctx_abc123', created_at: '2024-01-10T10:00:00Z', metadata: { user_id: '123' } },
//     ]
//   }

// with limit
const { data } = await uc.get({ limit: 10 });
```

```python
result = uc.get()
# → {
#     "data": [
#       { "id": "ctx_xyz789", "created_at": "2024-01-15T10:00:00Z", "metadata": {} },
#       { "id": "ctx_abc123", "created_at": "2024-01-10T10:00:00Z", "metadata": { "user_id": "123" } },
#     ]
#   }

# with limit
result = uc.get(limit=10)
```

--------------------------------

### Forking by Timestamp

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Gets the state of a context at a specific moment in time. This filters messages within a version based on the provided timestamp.

```APIDOC
## Forking by Timestamp

### Description
Gets the state of a context at a specific moment in time. This filters messages within a version based on the provided timestamp.

### Method
POST

### Endpoint
`/contexts/fork`

### Parameters
#### Request Body
- **from** (string) - Required - The ID of the context to fork from.
- **before** (string) - Required - The timestamp to fork before. Format: ISO 8601.

### Request Example (TypeScript)
```typescript
const fork = await uc.create({ from: 'ctx_abc123', before: '2024-01-10T10:30:00Z' });
```

### Request Example (Python)
```python
fork = uc.create(from_='ctx_abc123', before='2024-01-10T10:30:00Z')
```
```

--------------------------------

### Forking using Metadata to find Index

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Demonstrates how to find a specific checkpoint within a context's history using metadata, and then fork the context up to that checkpoint.

```APIDOC
## Forking using Metadata to find Index

### Description
Demonstrates how to find a specific checkpoint within a context's history using metadata, and then fork the context up to that checkpoint.

### Method
POST

### Endpoint
`/contexts/fork`

### Parameters
#### Request Body
- **from** (string) - Required - The ID of the context to fork from.
- **at** (integer) - Required - The index of the checkpoint message to fork up to.

### Request Example (TypeScript)
```typescript
// Assume contextId is the ID of the context you want to fork from
// First, get the history to find the checkpoint index
const { data: history } = await uc.get(contextId);
const checkpointIndex = history.findIndex((m) => m.metadata?.checkpoint === 'codebase_indexed');

// Fork up to the checkpoint
const fork = await uc.create({ from: contextId, at: checkpointIndex });

// You can then continue interacting with the forked context
await uc.append(fork.id, { role: 'user', content: 'Let\'s continue from here.' });
```

### Request Example (Python)
```python
# Assume context_id is the ID of the context you want to fork from
# First, get the history to find the checkpoint index
history = uc.get(context_id)['data']
checkpoint_index = next(i for i, m in enumerate(history) if m.get("metadata", {}).get("checkpoint") == "codebase_indexed")

# Fork up to the checkpoint
fork = uc.create(from_=context_id, at=checkpoint_index)

# You can then continue interacting with the forked context
uc.append(fork["id"], {"role": "user", "content": "Let's continue from here."})
```
```

--------------------------------

### Handling Specific Errors

Source: https://ultracontext.ai/docs/api-reference/errors

Example of how to implement custom logic for specific error statuses returned by the API.

```APIDOC
## Handling Specific Errors

### Description
This example shows how to use a `switch` statement within a `try-catch` block to handle different HTTP error statuses returned by the Ultracontext AI API.

### Method
N/A (Code Example)

### Endpoint
N/A

### Parameters
None

### Request Example
```typescript
import { UltraContext, UltraContextHttpError } from 'ultracontext'

const uc = new UltraContext({
  apiKey: 'YOUR_API_KEY'
});

async function safeGet(contextId: string) {
  try {
    return await uc.get(contextId);
  } catch (error) {
    if (error instanceof UltraContextHttpError) {
      switch (error.status) {
        case 404:
          // Context doesn't exist - create it
          console.log('Context not found, creating a new one...');
          const ctx = await uc.create();
          return uc.get(ctx.id);
        case 401:
          throw new Error('Invalid API key provided.');
        default:
          // Re-throw other errors
          throw error;
      }
    }
    throw error; // Re-throw non-UltraContextHttpError errors
  }
}
```
```

--------------------------------

### Initialize Ultracontext SDK with API Key (TypeScript)

Source: https://ultracontext.ai/docs/api-reference/authentication

Demonstrates how to initialize the Ultracontext SDK using an API key, typically loaded from environment variables. This ensures secure handling of credentials by not hardcoding them directly in the code.

```typescript
import { UltraContext } from 'ultracontext'

const uc = new UltraContext({
  apiKey: process.env.ULTRACONTEXT_API_KEY
})
```

```typescript
// Load from environment
const uc = new UltraContext({
  apiKey: process.env.ULTRACONTEXT_API_KEY!
})
```

--------------------------------

### Switch LLM Frameworks: OpenAI SDK (TypeScript)

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This snippet shows how to retrieve context using UltraContext and then prepare it for use with the OpenAI SDK. It assumes the existence of a `parseForOpenAI` function to format messages correctly for the OpenAI API. The primary output is the response from the OpenAI chat completion.

```typescript
import { UltraContext } from 'ultracontext';
import OpenAI from 'openai';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const openai = new OpenAI();

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for OpenAI
const parsed = parseForOpenAI(messages);

const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: parsed,
});
```

--------------------------------

### Fork Context by Version: TypeScript and Python

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Get the exact state of a context after a specific update or deletion by providing the version number. This is useful for rolling back to a known good state.

```typescript
const fork = await uc.create({ from: 'ctx_abc123', version: 1 });
```

```python
fork = uc.create(from_="ctx_abc123", version=1)
```

--------------------------------

### Switch LLM Frameworks: Google Generative AI (TypeScript)

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This snippet demonstrates fetching context using UltraContext and preparing it for Google's Generative AI. It requires a `parseForGoogle` function for message adaptation. The code then calls the `generateContent` method, returning the AI's response.

```typescript
import { UltraContext } from 'ultracontext';
import { GoogleGenerativeAI } from '@google/generative-ai';

const uc = new UltraContext({ apiKey: process.env.ULTRACONTEXT_API_KEY });
const model = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY).getGenerativeModel({ model: 'gemini-1.5-flash' });

// retrieve context
const { data: messages } = await uc.get(contextId);

// prepare messages for Google
const parsed = parseForGoogle(messages);

const response = await model.generateContent({
    contents: parsed,
});
```

--------------------------------

### Get Latest Context - TypeScript and Python

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

Fetches the most recent conversation context and its messages. It first lists all available contexts and then retrieves messages from the newest one. This is a prerequisite for summarizing previous interactions.

```typescript
// list all contexts (newest first)
const { data: contexts } = await uc.get();

// get messages from the latest
const { data: messages } = await uc.get(contexts[0].id);
```

```python
# list all contexts (newest first)
contexts = uc.get()["data"]

# get messages from the latest
messages = uc.get(contexts[0]["id"])["data"]
```

--------------------------------

### Switch LLM Frameworks: LangChain (Python)

Source: https://ultracontext.ai/docs/guides/store-retrieve-contexts

This Python snippet demonstrates using UltraContext with LangChain. It retrieves context, parses it for LangChain compatibility using `parse_for_langchain`, and then invokes a LangChain model. The result is the output from the LangChain model invocation.

```python
from ultracontext import UltraContext
from langchain_openai import ChatOpenAI
import os

uc = UltraContext(api_key=os.environ["ULTRACONTEXT_API_KEY"])
model = ChatOpenAI(model="gpt-4o")

# retrieve context
messages = uc.get(context_id)["data"]

# prepare messages for LangChain
parsed = parse_for_langchain(messages)

response = model.invoke(parsed)
```

--------------------------------

### POST /contexts/fork

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Creates a copy of an existing context. You can fork by specifying a version, a timestamp (before), or an index (at). These parameters can be combined to create a more specific fork.

```APIDOC
## POST /contexts/fork

### Description
Creates a copy of an existing context. You can fork by specifying a version, a timestamp (before), or an index (at). These parameters can be combined to create a more specific fork.

### Method
POST

### Endpoint
`/contexts/fork`

### Parameters
#### Request Body
- **from** (string) - Required - The ID of the context to fork from.
- **version** (integer) - Optional - Forks the context to an exact state after a specific update or delete.
- **before** (string) - Optional - Forks the context to the state at a specific timestamp. Format: ISO 8601.
- **at** (integer) - Optional - Forks the context to include the first N messages (indices 0 to `at`).
- **metadata** (object) - Optional - Key-value pairs to track why the context was forked.

### Request Example (TypeScript)
```typescript
// basic fork — full copy
const fork = await uc.create({ from: 'ctx_abc123' });

// by version — exact state after update/delete
const fork = await uc.create({ from: 'ctx_abc123', version: 1 });

// by timestamp — state at that moment
const fork = await uc.create({ from: 'ctx_abc123', before: '2024-01-10T10:30:00Z' });

// by index — first N messages (0 to at)
const fork = await uc.create({ from: 'ctx_abc123', at: 5 });

// combine all — order: version → time → index
const fork = await uc.create({
    from: 'ctx_abc123',
    version: 1,
    before: '2024-01-10T11:15:00Z',
    at: 5,
});

// add metadata
const fork = await uc.create({
    from: 'ctx_abc123',
    version: 1,
    metadata: {
        forked_from: 'ctx_abc123',
        reason: 'rollback',
        ticket: 'JIRA-123',
    },
});
```

### Request Example (Python)
```python
# basic fork — full copy
fork = uc.create(from_='ctx_abc123')

# by version — exact state after update/delete
fork = uc.create(from_='ctx_abc123', version=1)

# by timestamp — state at that moment
fork = uc.create(from_='ctx_abc123', before='2024-01-10T10:30:00Z')

# by index — first N messages (0 to at)
fork = uc.create(from_='ctx_abc123', at=5)

# combine all — order: version → time → index
fork = uc.create(
    from_='ctx_abc123',
    version=1,
    before='2024-01-10T11:15:00Z',
    at=5,
)

# add metadata
fork = uc.create(
    from_='ctx_abc123',
    version=1,
    metadata={
        "forked_from": "ctx_abc123",
        "reason": "rollback",
        "ticket": "JIRA-123",
    },
)
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created forked context.
- **from** (string) - The ID of the original context that was forked.
- **version** (integer) - The version of the forked context.
- **metadata** (object) - Metadata associated with the fork.

#### Response Example
```json
{
  "id": "ctx_new_fork_id",
  "from": "ctx_abc123",
  "version": 2,
  "metadata": {
    "forked_from": "ctx_abc123",
    "reason": "rollback"
  }
}
```
```

--------------------------------

### Fork Context Up to Metadata Checkpoint: TypeScript and Python

Source: https://ultracontext.ai/docs/guides/fork-clone-contexts

Find a specific message in the context history marked with metadata (e.g., 'codebase_indexed') and fork the context up to that point. This allows for creating a fresh start from a significant event.

```typescript
// find checkpoint index
const { data: history } = await uc.get(contextId);
const checkpointIndex = history.findIndex((m) => m.metadata?.checkpoint === 'codebase_indexed');

// fork up to checkpoint — fresh start on great context
const fork = await uc.create({ from: contextId, at: checkpointIndex });

// continue from there
await uc.append(fork.id, { role: 'user', content: 'Let's continue from here.' });
```

```python
# find checkpoint index
history = uc.get(context_id)("data")
checkpoint_index = next(i for i, m in enumerate(history) if m.get("metadata", {}).get("checkpoint") == "codebase_indexed")

# fork up to checkpoint — fresh start on great context
fork = uc.create(from_=context_id, at=checkpoint_index)

# continue from there
uc.append(fork["id"], {"role": "user", "content": "Let's continue from here."})
```
Tokens:
Raw