@chaoslabs/ai-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,41 @@
+Copyright (c) 2025 Chaos Labs. All rights reserved.
+
+This software and associated documentation files (the "Software") are
+proprietary and confidential. Unauthorized copying, distribution, or use
+of this Software is strictly prohibited.
+
+The Software is provided under license to authorized customers only.
+Contact support@chaoslabs.xyz for licensing information.
+
+TERMS OF USE
+
+1. LICENSE GRANT
+   Subject to the terms of this license, Chaos Labs grants you a limited,
+   non-exclusive, non-transferable license to use the Software solely in
+   connection with Chaos Labs services.
+
+2. RESTRICTIONS
+   You may not:
+   - Copy, modify, or distribute the Software
+   - Reverse engineer, decompile, or disassemble the Software
+   - Sublicense, rent, or lease the Software
+   - Use the Software for any purpose other than interfacing with Chaos Labs services
+
+3. OWNERSHIP
+   Chaos Labs retains all right, title, and interest in the Software,
+   including all intellectual property rights.
+
+4. TERMINATION
+   This license terminates automatically if you fail to comply with its terms
+   or upon termination of your agreement with Chaos Labs.
+
+5. DISCLAIMER
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. CHAOS LABS
+   DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL CHAOS LABS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE.
+
+For questions about licensing, contact: support@chaoslabs.xyz

package/README.md

@@ -0,0 +1,241 @@
+# Chaos AI SDK
+
+Official TypeScript SDK for the Chaos AI API. Build DeFi-aware applications with portfolio analysis, swap operations, lending, and more.
+
+## Installation
+`TBD`
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Contact [support@chaoslabs.xyz](mailto:support@chaoslabs.xyz) to obtain an API key.
+
+### 2. Set Environment Variables
+
+```bash
+export CHAOS_API_KEY="ck-your-api-key"
+```
+
+### 3. Basic Usage
+
+```typescript
+import { Chaos, WALLET_MODEL, extractText, extractBlocks } from '@chaoslabs/ai-sdk';
+
+const chaos = new Chaos({
+  apiKey: process.env.CHAOS_API_KEY,
+  baseUrl: 'https://ai-staging.chaoslabs.co', // Optional, this is the default
+});
+
+const response = await chaos.chat.responses.create({
+  model: WALLET_MODEL,
+  input: [
+    { type: 'message', role: 'user', content: 'What is in my portfolio?' }
+  ],
+  metadata: {
+    user_id: 'user-123',
+    session_id: 'session-abc',
+    wallet_id: '0x...', // Your wallet address
+  },
+});
+
+// Extract text content
+const text = extractText(response);
+console.log(text);
+
+// Extract structured blocks (tables, charts, actions)
+const blocks = extractBlocks(response);
+for (const block of blocks) {
+  console.log(block.type, block);
+}
+```
+
+## API Reference
+
+### Chaos Client
+
+```typescript
+new Chaos(config: ChaosConfig)
+```
+
+**Configuration Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | Required | Your Chaos API key |
+| `baseUrl` | `string` | `https://ai-staging.chaoslabs.co` | API base URL |
+| `timeout` | `number` | `120000` | Request timeout in milliseconds |
+
+> **Important:** API keys are environment-specific. A staging API key will not work with the production API, and vice versa. Make sure your `apiKey` and `baseUrl` are from the same environment.
+
+**Available Environments:**
+
+| Environment | Base URL |
+|-------------|----------|
+| Staging | `https://ai-staging.chaoslabs.co` |
+| Production | Coming soon |
+
+### Models
+
+| Model | Description |
+|-------|-------------|
+| `WALLET_MODEL` | Portfolio operations, swaps, lending, staking |
+
+### Request Metadata
+
+```typescript
+interface RequestMetadata {
+  user_id: string;      // Unique user identifier
+  session_id: string;   // Client-generated session ID for conversation continuity
+  wallet_id?: string;   // Wallet address (required for WALLET_MODEL)
+}
+```
+
+> **⚠️ Upcoming Change:** The `wallet_id` field currently accepts a wallet address string. In a future release, this will be replaced with a `wallet` object that includes additional wallet information (chain, connection status, etc.). We will provide migration guidance when this change is released.
+
+### Rendering Responses
+
+Responses may contain text, blocks, or both. When rendering responses, text should be displayed before blocks.
+
+Use the `extractText` and `extractBlocks` helper functions to extract content from a response:
+
+```typescript
+import { extractText, extractBlocks } from '@chaoslabs/ai-sdk';
+
+const response = await chaos.chat.responses.create({ ... });
+
+// Extract text content (render this first)
+const text = extractText(response);
+if (text) {
+  renderText(text);
+}
+
+// Extract blocks (render after text)
+const blocks = extractBlocks(response);
+for (const block of blocks) {
+  renderBlock(block);
+}
+```
+
+#### Response Structure
+
+```typescript
+interface Response {
+  id: string;
+  object: 'response';
+  model: string;
+  status: 'completed' | 'failed';
+  output: OutputItem[];
+  error?: ResponseError;
+}
+```
+
+
+### Block Types
+
+The SDK returns structured blocks for rich content:
+
+| Block Type | Description |
+|------------|-------------|
+| `table` | Tabular data (portfolio holdings, positions) |
+| `pie_chart` | Distribution charts (allocation breakdown) |
+| `timeseries` | Historical data charts |
+| `transaction_action` | DeFi operations with primitives and risks |
+| `interactive_card` | User prompts and confirmations |
+| `markdown` | Rich text content |
+
+### Helper Functions
+
+```typescript
+// Extract all text from response
+extractText(response: Response): string
+
+// Extract all blocks from response
+extractBlocks(response: Response): Block[]
+
+// Check for transaction risks
+hasRisks(response: Response): boolean
+hasBlockers(response: Response): boolean
+
+// Type guards
+isTableBlock(block: Block): block is TableBlock
+isPieChartBlock(block: Block): block is PieChartBlock
+isTimeseriesBlock(block: Block): block is TimeseriesBlock
+isTransactionActionBlock(block: Block): block is TransactionActionBlock
+isInteractiveCardBlock(block: Block): block is InteractiveCardBlock
+isMarkdownBlock(block: Block): block is MarkdownBlock
+```
+
+### Error Handling
+
+```typescript
+import { ChaosError, ChaosTimeoutError } from '@chaoslabs/ai-sdk';
+
+try {
+  const response = await chaos.chat.responses.create({ ... });
+
+  if (response.status === 'failed') {
+    console.error('Request failed:', response.error);
+    return;
+  }
+
+  // Process successful response
+} catch (error) {
+  if (error instanceof ChaosTimeoutError) {
+    console.error('Request timed out');
+  } else if (error instanceof ChaosError) {
+    console.error('API error:', error.message, error.status);
+  }
+}
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+```bash
+# Install example dependencies
+cd examples
+bun install
+
+# Run examples
+bun run example:01  # Basic query
+bun run example:02  # Swap action
+bun run example:03  # Multi-turn conversation
+bun run example:04  # Block parsing
+bun run example:05  # Error handling
+bun run example:06  # Lending operations
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and exports all types:
+
+```typescript
+import type {
+  ChaosConfig,
+  CreateResponseParams,
+  RequestMetadata,
+  Response,
+  Block,
+  TableBlock,
+  TransactionActionBlock,
+  // ... and more
+} from '@chaoslabs/ai-sdk';
+```
+
+## Requirements
+
+- Node.js 18+ or Bun
+- TypeScript 5.0+ (for TypeScript projects)
+
+## License
+
+This software is proprietary. See [LICENSE](./LICENSE) for terms.
+
+## Support
+
+For questions, issues, or API key requests:
+
+- Email: [support@chaoslabs.xyz](mailto:support@chaoslabs.xyz)
+- Documentation: [https://docs.chaoslabs.xyz](https://docs.chaoslabs.xyz)

package/dist/client.d.ts

@@ -0,0 +1,77 @@
+import type { ChaosConfig, CreateResponseParams, Response } from './types.js';
+import { WALLET_MODEL, ASK_MODEL } from './request.js';
+export { WALLET_MODEL, ASK_MODEL };
+/**
+ * The v1 responses API namespace.
+ */
+declare class V1Responses {
+    private config;
+    private sessionId;
+    private abortController;
+    constructor(config: Required<ChaosConfig>);
+    private generateId;
+    /**
+     * Create a response using v1 API.
+     */
+    create(params: CreateResponseParams): Promise<Response>;
+    /**
+     * Create a non-streaming response.
+     */
+    private createNonStreaming;
+    /**
+     * Cancel the current request.
+     */
+    cancel(): void;
+    /**
+     * Reset the session for a new conversation.
+     */
+    reset(): void;
+}
+/**
+ * The v1 chat API namespace.
+ */
+declare class V1Chat {
+    readonly responses: V1Responses;
+    constructor(config: Required<ChaosConfig>);
+}
+/**
+ * Chaos AI SDK Client - V1 API.
+ *
+ * This client talks to the /v1/chat/stream endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { Chaos, WALLET_MODEL } from '@chaoslabs/ai-sdk-v1';
+ *
+ * const chaos = new Chaos({
+ *   apiKey: 'ck-...',
+ *   baseUrl: 'https://ai-staging.chaoslabs.co'
+ * });
+ *
+ * const response = await chaos.chat.responses.create({
+ *   model: WALLET_MODEL,
+ *   input: [
+ *     { type: 'message', role: 'user', content: 'What is in my portfolio?' }
+ *   ],
+ *   metadata: {
+ *     user_id: 'user-123',
+ *     session_id: 'session-abc',
+ *     wallet_id: '0x...',
+ *   },
+ * });
+ * ```
+ */
+export declare class Chaos {
+    readonly chat: V1Chat;
+    private config;
+    constructor(config: ChaosConfig);
+    /**
+     * Get the API key.
+     */
+    get apiKey(): string;
+    /**
+     * Get the base URL.
+     */
+    get baseUrl(): string;
+}
+export default Chaos;

package/dist/client.js

@@ -0,0 +1,167 @@
+// V1 API Client for /v1/chat/stream
+//
+// This client talks to the new v1 API endpoint with Bearer auth.
+import { ChaosError, ChaosTimeoutError } from './types.js';
+import { toV1WalletRequest, toV1AskRequest, buildV1Headers, buildV1Endpoint, WALLET_MODEL, ASK_MODEL, } from './request.js';
+import { parseV1Stream, toV1Response } from './response.js';
+// Export model constants
+export { WALLET_MODEL, ASK_MODEL };
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_TIMEOUT = 120000; // 2 minutes
+// ============================================================================
+// V1 Responses Class
+// ============================================================================
+/**
+ * The v1 responses API namespace.
+ */
+class V1Responses {
+    config;
+    sessionId;
+    abortController = null;
+    constructor(config) {
+        this.config = config;
+        this.sessionId = this.generateId();
+    }
+    generateId() {
+        return `sdk-${crypto.randomUUID().slice(0, 12)}`;
+    }
+    /**
+     * Create a response using v1 API.
+     */
+    async create(params) {
+        return this.createNonStreaming(params);
+    }
+    /**
+     * Create a non-streaming response.
+     */
+    async createNonStreaming(params) {
+        const responseId = this.generateId();
+        const sessionId = params.metadata.session_id || this.sessionId;
+        // Create abort controller for timeout
+        this.abortController = new AbortController();
+        const timeoutSignal = AbortSignal.timeout(this.config.timeout);
+        const signal = AbortSignal.any([this.abortController.signal, timeoutSignal]);
+        // Build request
+        const endpoint = buildV1Endpoint(this.config.baseUrl);
+        const headers = buildV1Headers(this.config.apiKey);
+        // Check if wallet or ask mode
+        const isWallet = params.model === WALLET_MODEL || params.model.includes('WALLET');
+        const requestBody = isWallet
+            ? toV1WalletRequest(params, sessionId)
+            : toV1AskRequest(params, sessionId);
+        try {
+            // Make request
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(requestBody),
+                signal,
+            });
+            if (!response.ok) {
+                throw new ChaosError(`HTTP error: ${response.status} ${response.statusText}`, response.status);
+            }
+            if (!response.body) {
+                throw new ChaosError('Response body is null');
+            }
+            // Parse NDJSON stream
+            const finalState = await parseV1Stream(response.body);
+            // Convert to Response
+            return toV1Response(responseId, params.model, finalState);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                throw new ChaosTimeoutError(this.config.timeout);
+            }
+            if (error instanceof ChaosError) {
+                throw error;
+            }
+            throw new ChaosError(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            this.abortController = null;
+        }
+    }
+    /**
+     * Cancel the current request.
+     */
+    cancel() {
+        this.abortController?.abort();
+        this.abortController = null;
+    }
+    /**
+     * Reset the session for a new conversation.
+     */
+    reset() {
+        this.cancel();
+        this.sessionId = this.generateId();
+    }
+}
+// ============================================================================
+// V1 Chat Class
+// ============================================================================
+/**
+ * The v1 chat API namespace.
+ */
+class V1Chat {
+    responses;
+    constructor(config) {
+        this.responses = new V1Responses(config);
+    }
+}
+// ============================================================================
+// V1 Chaos Class
+// ============================================================================
+/**
+ * Chaos AI SDK Client - V1 API.
+ *
+ * This client talks to the /v1/chat/stream endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { Chaos, WALLET_MODEL } from '@chaoslabs/ai-sdk-v1';
+ *
+ * const chaos = new Chaos({
+ *   apiKey: 'ck-...',
+ *   baseUrl: 'https://ai-staging.chaoslabs.co'
+ * });
+ *
+ * const response = await chaos.chat.responses.create({
+ *   model: WALLET_MODEL,
+ *   input: [
+ *     { type: 'message', role: 'user', content: 'What is in my portfolio?' }
+ *   ],
+ *   metadata: {
+ *     user_id: 'user-123',
+ *     session_id: 'session-abc',
+ *     wallet_id: '0x...',
+ *   },
+ * });
+ * ```
+ */
+export class Chaos {
+    chat;
+    config;
+    constructor(config) {
+        this.config = {
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl || 'https://ai-staging.chaoslabs.co',
+            timeout: config.timeout || DEFAULT_TIMEOUT,
+        };
+        this.chat = new V1Chat(this.config);
+    }
+    /**
+     * Get the API key.
+     */
+    get apiKey() {
+        return this.config.apiKey;
+    }
+    /**
+     * Get the base URL.
+     */
+    get baseUrl() {
+        return this.config.baseUrl;
+    }
+}
+export default Chaos;

package/dist/converter.d.ts

@@ -0,0 +1,5 @@
+import type { Block } from './types.js';
+/**
+ * Convert a backend block to SDK block format.
+ */
+export declare function convertBlock(raw: Record<string, unknown>): Block | null;

package/dist/converter.js

@@ -0,0 +1,159 @@
+// Block converter from backend format to SDK format
+/**
+ * Convert a backend block to SDK block format.
+ */
+export function convertBlock(raw) {
+    const blockType = raw.blockType;
+    const type = raw.type;
+    // Ask mode content block -> markdown
+    if (type === 'content' && typeof raw.value === 'string') {
+        return {
+            type: 'markdown',
+            content: raw.value,
+        };
+    }
+    // Table block
+    if (blockType === 'table') {
+        return {
+            type: 'table',
+            title: raw.title || '',
+            tableHeaders: raw.tableHeaders || [],
+            rows: raw.tableRows || [],
+        };
+    }
+    // Pie chart block
+    if (blockType === 'chart' && raw.chartType === 'pie') {
+        return {
+            type: 'pie_chart',
+            title: raw.title || '',
+            data: raw.data || [],
+        };
+    }
+    // Timeseries block
+    if (blockType === 'chart' && raw.chartType === 'timeseries') {
+        return {
+            type: 'timeseries',
+            title: raw.title || '',
+            data: raw.series || raw.data,
+        };
+    }
+    // Interactive card block
+    if (blockType === 'interactive') {
+        return {
+            type: 'interactive_card',
+            title: raw.title || '',
+            body: raw.body,
+            style: raw.style || 'options',
+            options: raw.options,
+        };
+    }
+    // Transaction action block
+    if (blockType === 'transaction_action' || type === 'action') {
+        return convertTransactionBlock(raw);
+    }
+    // Info block -> markdown
+    if (type === 'info' && typeof raw.content === 'string') {
+        return {
+            type: 'markdown',
+            content: raw.content,
+        };
+    }
+    // One-of block -> transaction action (simplified)
+    if (type === 'one_of') {
+        const options = raw.options;
+        if (options && options.length > 0) {
+            // Take the first option as a simple representation
+            const firstOption = options[0];
+            return {
+                type: 'transaction_action',
+                title: raw.rationale || 'Choose an option',
+                primitives: convertPrimitives(firstOption.primitives),
+            };
+        }
+    }
+    // Sequence block -> transaction action
+    if (type === 'sequence') {
+        return {
+            type: 'transaction_action',
+            title: raw.notes || 'Sequence',
+            primitives: convertPrimitives(raw.actions),
+        };
+    }
+    return null;
+}
+/**
+ * Convert a backend transaction/action block to SDK format.
+ */
+function convertTransactionBlock(raw) {
+    const primitives = raw.primitives;
+    if (!primitives || !Array.isArray(primitives)) {
+        return null;
+    }
+    const risks = raw.risks;
+    return {
+        type: 'transaction_action',
+        title: raw.notes || 'Transaction',
+        primitives: primitives.map((p) => {
+            const params = p.params;
+            const display = p.display;
+            return {
+                kind: p.primitive || 'unknown',
+                amount: display?.amount || params?.amount || '0',
+                from: display?.from_asset || params?.from_token,
+                to: display?.to_asset || params?.to_token,
+                ...params,
+            };
+        }),
+        risks: risks ? convertRisks(risks) : undefined,
+    };
+}
+/**
+ * Convert primitives array.
+ */
+function convertPrimitives(primitives) {
+    if (!Array.isArray(primitives)) {
+        return [];
+    }
+    return primitives.map((p) => {
+        const prim = p;
+        const params = prim.params;
+        return {
+            kind: prim.primitive || 'unknown',
+            amount: params?.amount || '0',
+            from: params?.from_token,
+            to: params?.to_token,
+            ...params,
+        };
+    });
+}
+/**
+ * Convert backend risks to SDK format.
+ */
+function convertRisks(raw) {
+    return {
+        level: raw.level || 'low',
+        warnings: extractRiskMessages(raw.warnings),
+        blockers: extractRiskMessages(raw.blockers),
+    };
+}
+/**
+ * Extract risk messages from risk check array.
+ */
+function extractRiskMessages(checks) {
+    if (!Array.isArray(checks)) {
+        return [];
+    }
+    return checks
+        .map((check) => {
+        if (typeof check === 'string')
+            return check;
+        if (typeof check === 'object' && check && 'message' in check) {
+            return check.message;
+        }
+        if (typeof check === 'object' && check && 'title' in check) {
+            return check.title;
+        }
+        return null;
+    })
+        .filter((msg) => msg !== null);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Chaos as default, Chaos, WALLET_MODEL, ASK_MODEL } from './client.js';
+export type { V1WalletRequest, V1AskRequest } from './request.js';
+export type { V1StreamEvent, V1FinalState } from './response.js';
+export type { ChaosConfig, CreateResponseParams, RequestMetadata, InputItem, Response, OutputItem, ContentPart, Block, OutputText, ChaosBlock, TableBlock, MarkdownBlock, TransactionActionBlock, Primitive, InteractiveCardBlock, InteractiveOption, TimeseriesBlock, PieChartBlock, Risks, ResponseError, } from './types.js';
+export { ChaosError, ChaosTimeoutError } from './types.js';
+export { extractText, extractBlocks, hasRisks, hasBlockers, isTableBlock, isPieChartBlock, isTimeseriesBlock, isTransactionActionBlock, isInteractiveCardBlock, isMarkdownBlock, isOutputText, isChaosBlock, } from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+// Chaos AI SDK V1 - Public API
+export { Chaos as default, Chaos, WALLET_MODEL, ASK_MODEL } from './client.js';
+// Export error classes
+export { ChaosError, ChaosTimeoutError } from './types.js';
+// Export helper functions
+export { extractText, extractBlocks, hasRisks, hasBlockers, isTableBlock, isPieChartBlock, isTimeseriesBlock, isTransactionActionBlock, isInteractiveCardBlock, isMarkdownBlock, isOutputText, isChaosBlock, } from './types.js';