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
• Standardized HTTP client using axios for all API calls

Installation

npm install @axiom-lattice/client-sdk

Usage

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",
  environment: "web", // Optional: "web" (default) or "wechat-miniprogram"
});

// 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

Runtime Environment Support

As of version 1.0.13, the client SDK now supports different runtime environments through the environment configuration option. Currently supported environments are:

• "web" (default): Uses axios for all HTTP requests, including streaming responses
• "wechat-miniprogram": Uses a custom WeChat Mini Program HTTP client implementation for compatibility with WeChat Mini Programs

To specify the environment:

const client = new Client({
  // ... other options
  environment: "wechat-miniprogram", // For WeChat Mini Program environments
});

The WeChat Mini Program environment uses a different approach for streaming responses since true streaming is not supported in that environment. It uses a polling mechanism instead.

HTTP Client Standardization

As of version 1.0.12, the client SDK now uses axios exclusively for all HTTP requests, including streaming responses. Previously, the SDK used a combination of axios for regular requests and the native fetch API for streaming. This change standardizes the HTTP client implementation across the SDK.

Benefits:

• Consistent error handling
• Unified request/response interceptors
• Simplified maintenance and debugging
• Better compatibility with different JavaScript environments

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:

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.

WeChatClient

A specialized client implementation for WeChat Mini Programs that uses the native wx API for network requests.

import { WeChatClient } from "@axiom-lattice/client-sdk";

// Create a WeChat client
const client = new WeChatClient({
  baseURL: "https://api.example.com",
  apiKey: "your-api-key",
  assistantId: "your-assistant-id",
  transport: "sse",
});

// Use the same API methods as the standard Client
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",
    },
  ],
});

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