@axiom-lattice/client-sdk 0.1.1

package/README.md

@@ -0,0 +1,163 @@
+# Axiom Lattice Client SDK
+
+A TypeScript client for the Axiom Lattice Agent Service API.
+
+## Overview
+
+The Client SDK provides a simple interface for interacting with the Axiom Lattice Agent Service API. It handles authentication, request/response formatting, and error handling.
+
+## Features
+
+- Create and manage threads
+- Send messages and receive responses
+- Stream responses with event-based callbacks
+- Register client-side tools
+- Handle tool calls and responses
+- Process streaming message chunks with ChunkMessageMerger
+
+## Installation
+
+```bash
+npm install @axiom-lattice/client-sdk
+```
+
+## Usage
+
+```typescript
+import { Client, createSimpleMessageMerger } from "@axiom-lattice/client-sdk";
+
+// Create a client
+const client = new Client({
+  baseURL: "https://api.example.com",
+  apiKey: "your-api-key",
+  assistantId: "your-assistant-id",
+  transport: "sse",
+});
+
+// Create a thread
+const threadId = await client.createThread({
+  metadata: { user: "user123" },
+});
+
+// Send a message
+const response = await client.chat.send({
+  threadId,
+  messages: [
+    {
+      role: "user",
+      content: "Hello, how can you help me?",
+      id: "msg-1",
+    },
+  ],
+});
+
+// Stream a message
+const stopStreaming = client.chat.stream(
+  {
+    threadId,
+    messages: [
+      {
+        role: "user",
+        content: "Tell me a story",
+        id: "msg-2",
+      },
+    ],
+  },
+  (event) => {
+    console.log("Event:", event);
+  },
+  () => {
+    console.log("Stream completed");
+  },
+  (error) => {
+    console.error("Stream error:", error);
+  }
+);
+
+// Stop streaming if needed
+// stopStreaming();
+
+// Use ChunkMessageMerger to process streaming chunks
+const merger = createSimpleMessageMerger();
+
+// Process user message
+merger.push({
+  type: "human",
+  data: {
+    id: "user-1",
+    content: "Hello",
+  },
+});
+
+// Process AI message with tool calls
+merger.push({
+  type: "ai",
+  data: {
+    id: "ai-1",
+    content: "I need to search for that.",
+    tool_calls: [
+      {
+        name: "search",
+        args: { query: "typescript" },
+        id: "search-1",
+      },
+    ],
+  },
+});
+
+// Process tool response
+merger.push({
+  type: "tool",
+  data: {
+    id: "tool-1",
+    content: "Search results: ...",
+    tool_call_id: "search-1",
+  },
+});
+
+// Get merged messages
+const messages = merger.getMessages();
+```
+
+## Migration Notes
+
+### ChunkMessageMerger
+
+The `ChunkMessageMerger` module has been moved from the web project to the client-sdk package. It provides functionality for processing streaming message chunks and merging them into complete messages.
+
+To use it:
+
+```typescript
+import { createSimpleMessageMerger } from "@axiom-lattice/client-sdk";
+
+const merger = createSimpleMessageMerger();
+// Use merger methods: push, getMessages, reset, etc.
+```
+
+### Future Migration Plans
+
+The current web project uses its own implementation of `useChat` that is tightly integrated with the web app's API and message format. In the future, we plan to migrate the web project to use the react-sdk's `useChat` hook, which provides a more standardized interface for chat interactions.
+
+Steps for future migration:
+
+1. Update the web project's message types to align with the react-sdk's message format
+2. Replace direct API calls with client-sdk methods
+3. Integrate the react-sdk's useChat hook
+4. Update UI components to work with the new message format
+
+## API Reference
+
+### Client
+
+The main client class for interacting with the Axiom Lattice Agent Service API.
+
+### ChunkMessageMerger
+
+A utility for processing streaming message chunks and merging them into complete messages.
+
+- `createSimpleMessageMerger()`: Creates a new message merger instance
+  - `push(chunk)`: Processes a message chunk
+  - `getMessages()`: Gets all messages with tool calls merged
+  - `getMessagesWithoutToolCalls()`: Gets messages without tool calls
+  - `initialMessages(msgs)`: Initializes with existing messages
+  - `reset()`: Resets the merger state

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+import { Message, MessageChunk, AssistantMessage } from '@axiom-lattice/protocols';
+
+/**
+ * Core types for the Axiom Lattice Client SDK
+ */
+
+/**
+ * Transport method for client-server communication
+ * Note: Currently only "ws" is used for tool registration
+ */
+type Transport = "sse" | "ws";
+/**
+ * Configuration options for the Client
+ */
+interface ClientConfig {
+    /**
+     * Base URL for the API
+     */
+    baseURL: string;
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Assistant identifier
+     */
+    assistantId: string;
+    /**
+     * Transport method (Server-Sent Events or WebSocket)
+     */
+    transport: Transport;
+    /**
+     * Request timeout in milliseconds (optional, defaults to 30000)
+     */
+    timeout?: number;
+    /**
+     * Additional headers to include in requests (optional)
+     */
+    headers?: Record<string, string>;
+    /**
+     * Configuration for retry behavior (optional)
+     */
+    retry?: RetryConfig;
+}
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     */
+    maxRetries: number;
+    /**
+     * Initial delay between retries in milliseconds
+     */
+    initialDelayMs: number;
+    /**
+     * Maximum delay between retries in milliseconds
+     */
+    maxDelayMs: number;
+    /**
+     * Factor to multiply delay by after each retry attempt
+     */
+    backoffFactor: number;
+}
+/**
+ * Thread creation options
+ */
+interface CreateThreadOptions {
+    /**
+     * Optional metadata for the thread
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Thread information
+ */
+interface Thread {
+    /**
+     * Thread identifier
+     */
+    id: string;
+    /**
+     * Thread metadata
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Thread creation timestamp
+     */
+    createdAt: string;
+}
+/**
+ * Chat send options
+ */
+interface ChatSendOptions {
+    /**
+     * Thread identifier
+     */
+    threadId: string;
+    /**
+     * Messages to send
+     */
+    messages: Message[];
+}
+/**
+ * Chat stream options
+ */
+interface ChatStreamOptions extends ChatSendOptions {
+    /**
+     * Whether to run in background (optional)
+     */
+    background?: boolean;
+}
+/**
+ * Stream callbacks interface
+ */
+interface StreamCallbacks {
+    /**
+     * Called when a stream event is received
+     */
+    onEvent: (event: MessageChunk) => void;
+    /**
+     * Called when the stream completes
+     */
+    onComplete?: () => void;
+    /**
+     * Called when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Chat response
+ */
+interface ChatResponse {
+    /**
+     * Response message
+     */
+    message: AssistantMessage;
+    /**
+     * Trace ID for debugging
+     */
+    traceId: string;
+}
+/**
+ * Tool registration options
+ */
+interface RegisterToolOptions {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Tool parameter schema
+     */
+    schema: object;
+    /**
+     * Tool handler function
+     */
+    handler: (params: any) => Promise<any>;
+}
+/**
+ * Get messages options
+ */
+interface GetMessagesOptions {
+    /**
+     * Thread identifier
+     */
+    threadId: string;
+    /**
+     * Maximum number of messages to return
+     */
+    limit?: number;
+    /**
+     * Message ID to start from (for pagination)
+     */
+    after?: string;
+    /**
+     * Whether to return messages in reverse chronological order
+     */
+    reverse?: boolean;
+}
+/**
+ * Thread list options
+ */
+interface ListThreadsOptions {
+    /**
+     * Maximum number of threads to return
+     */
+    limit?: number;
+    /**
+     * Offset for pagination
+     */
+    offset?: number;
+}
+/**
+ * Run options
+ */
+interface RunOptions {
+    /**
+     * Thread identifier
+     */
+    threadId: string;
+    /**
+     * Message to send
+     */
+    message: string;
+    /**
+     * Files to attach (optional)
+     */
+    files?: any[];
+    /**
+     * Command to execute (optional)
+     */
+    command?: any;
+    /**
+     * Whether to stream the response (optional)
+     */
+    streaming?: boolean;
+    /**
+     * Whether to run in background (optional)
+     */
+    background?: boolean;
+}
+/**
+ * Agent state
+ */
+interface AgentState {
+    values: {
+        messages: Message[];
+        [key: string]: any;
+    };
+    tasks: Array<{
+        interrupts: Array<{
+            value: any;
+        }>;
+    }>;
+}
+/**
+ * Custom error classes
+ */
+declare class ApiError extends Error {
+    statusCode: number;
+    responseBody?: any | undefined;
+    constructor(message: string, statusCode: number, responseBody?: any | undefined);
+}
+declare class NetworkError extends Error {
+    constructor(message: string);
+}
+declare class AuthenticationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Main client class for interacting with the Axiom Lattice Agent Service API
+ */
+declare class Client {
+    private client;
+    private config;
+    private assistantId;
+    private tenantId;
+    private registeredTools;
+    /**
+     * Creates a new Client instance
+     * @param config - Configuration options for the client
+     */
+    constructor(config: ClientConfig);
+    /**
+     * Sets up axios interceptors for error handling
+     * @private
+     */
+    private setupInterceptors;
+    /**
+     * Set tenant ID for multi-tenant environments
+     * @param tenantId - Tenant identifier
+     */
+    setTenantId(tenantId: string): void;
+    /**
+     * Creates a new thread
+     * @param options - Options for creating a thread
+     * @returns A promise that resolves to the thread ID
+     */
+    createThread(options: CreateThreadOptions): Promise<string>;
+    /**
+     * Retrieves thread information
+     * @param threadId - Thread identifier
+     * @returns A promise that resolves to the thread information
+     */
+    getThread(threadId: string): Promise<Thread>;
+    /**
+     * Lists all threads
+     * @param options - Options for listing threads
+     * @returns A promise that resolves to an array of threads
+     */
+    listThreads(options?: ListThreadsOptions): Promise<Thread[]>;
+    /**
+     * Deletes a thread
+     * @param threadId - Thread identifier
+     * @returns A promise that resolves when the thread is deleted
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Retrieves messages from a thread
+     * @param options - Options for retrieving messages
+     * @returns A promise that resolves to an array of messages
+     */
+    getMessages(options: GetMessagesOptions): Promise<Message[]>;
+    /**
+     * Retrieves agent state
+     * @param threadId - Thread identifier
+     * @returns A promise that resolves to the agent state
+     */
+    getAgentState(threadId: string): Promise<AgentState>;
+    /**
+     * Gets agent graph visualization
+     * @returns A promise that resolves to the graph visualization data
+     */
+    getAgentGraph(): Promise<string>;
+    /**
+     * Run agent with options
+     * @param options - Options for running the agent
+     * @returns A promise that resolves to the run result or a stream
+     */
+    run(options: RunOptions): Promise<any>;
+    /**
+     * Stream run results
+     * @param options - Options for streaming run results
+     * @param onEvent - Callback function that receives stream events
+     * @param onComplete - Optional callback function called when streaming completes
+     * @param onError - Optional callback function called when an error occurs
+     * @returns A function that can be called to stop the stream
+     */
+    private streamRun;
+    /**
+     * Chat namespace for sending messages and streaming responses
+     */
+    chat: {
+        /**
+         * Sends a message to a thread and receives a response
+         * @param options - Options for sending a message
+         * @returns A promise that resolves to the chat response
+         */
+        send: (options: ChatSendOptions) => Promise<ChatResponse>;
+        /**
+         * Sends a message to a thread and streams the response
+         * @param options - Options for streaming a message
+         * @param onEvent - Callback function that receives stream events
+         * @param onComplete - Optional callback function called when streaming completes
+         * @param onError - Optional callback function called when an error occurs
+         * @returns A function that can be called to stop the stream
+         */
+        stream: (options: ChatStreamOptions, onEvent: (event: MessageChunk) => void, onComplete?: () => void, onError?: (error: Error) => void) => (() => void);
+    };
+    /**
+     * Tools namespace for registering and unregistering client-side tools
+     */
+    tools: {
+        /**
+         * Registers a client-side tool
+         * @param options - Options for registering a tool
+         */
+        register: (options: RegisterToolOptions) => void;
+        /**
+         * Unregisters a client-side tool
+         * @param name - Tool name
+         */
+        unregister: (name: string) => void;
+    };
+}
+
+/**
+ * ChunkMessageMerger
+ *
+ * A utility for handling streaming message chunks and merging them into complete messages.
+ */
+
+/**
+ * Creates a simple message merger for handling streaming message chunks
+ * @returns An object with methods to push chunks and retrieve merged messages
+ */
+declare function createSimpleMessageMerger(): {
+    push: (chunk: MessageChunk) => void;
+    initialMessages: (msgs: any[]) => void;
+    getMessages: () => any[];
+    getMessagesWithoutToolCalls: () => any[];
+    reset: () => void;
+};
+
+export { AgentState, ApiError, AuthenticationError, ChatResponse, ChatSendOptions, ChatStreamOptions, Client, ClientConfig, CreateThreadOptions, GetMessagesOptions, ListThreadsOptions, NetworkError, RegisterToolOptions, RetryConfig, RunOptions, StreamCallbacks, Thread, Transport, createSimpleMessageMerger };