# 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

```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",
  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:

```typescript
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:

```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.

### WeChatClient

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

```typescript
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
