march-ai-sdk 0.3.0

package/README.md

@@ -0,0 +1,732 @@
+# March Agent SDK (TypeScript)
+
+TypeScript SDK for building AI agents in the March AI platform. Provides agent registration, message handling via Kafka (through Agent Gateway), streaming responses, and integrations with LangGraph and Vercel AI SDK.
+
+## Quick Start
+
+The fastest way to get started is with the CLI:
+
+```bash
+npx march-start my-agent
+cd my-agent
+# Edit .env with your configuration
+pnpm dev
+```
+
+## Overview
+
+The March Agent SDK (`march-ai-sdk`) enables developers to build AI agents that integrate with the March AI Management platform. Agents register themselves, receive messages through Kafka topics, and stream responses back to users.
+
+### Key Features
+
+- **Agent Registration**: Automatic registration with AI Inventory
+- **Message Handling**: Function-based handlers with sender filtering
+- **Response Streaming**: Chunked responses via Kafka/Centrifugo
+- **Conversation History**: Access to message history via Conversation Store
+- **LangGraph Integration**: HTTP-based checkpoint saver for LangGraph graphs
+- **Vercel AI SDK Integration**: Persistent message history for Vercel AI SDK
+- **Attachment Handling**: Download images and PDFs for processing
+- **Long-term Memory**: Semantic search across user conversations
+- **Error Handling**: Automatic error responses to users on handler failures
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Your Agent Application                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│    MarchAgentApp                                                            │
+│    ├── registerMe() → Agent                                                 │
+│    │   ├── onMessage() handler                                              │
+│    │   └── streamer() → Streamer                                            │
+│    └── run() → Start consume loop                                           │
+│                                                                             │
+│    Extensions:                                                              │
+│    ├── HTTPCheckpointSaver (LangGraph)                                      │
+│    └── VercelAIMessageStore (Vercel AI SDK)                                 │
+│                                                                             │
+└──────────────────────────────────┬──────────────────────────────────────────┘
+                                   │ gRPC (Kafka) + HTTP (APIs)
+                                   ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Agent Gateway                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  gRPC: AgentStream (bidirectional)      HTTP: /s/{service}/* proxy          │
+│  - Auth                                 - /s/ai-inventory/*                 │
+│  - Subscribe/Unsubscribe                - /s/conversation-store/*           │
+│  - Produce/Consume messages             - /s/ai-memory/*                    │
+│                                         - /s/attachment/*                   │
+└─────────────────┬───────────────────────────────────┬───────────────────────┘
+                  │                                   │
+                  ▼                                   ▼
+           ┌──────────────┐                  ┌────────────────────┐
+           │    Kafka     │                  │   AI Inventory /   │
+           │  {agent}.inbox │                │ Conversation Store │
+           └──────────────┘                  └────────────────────┘
+```
+
+### Message Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Provider
+    participant Router
+    participant Gateway as Agent Gateway
+    participant Agent as Your Agent
+    participant ConvStore as Conversation Store
+
+    User->>Provider: Send message
+    Provider->>Router: Kafka: router.inbox
+    Router->>Gateway: Kafka: {agent}.inbox
+    Gateway->>Agent: gRPC stream: message
+
+    Agent->>ConvStore: Get conversation history
+    ConvStore-->>Agent: Message history
+
+    loop Streaming Response
+        Agent->>Gateway: gRPC stream: content chunk
+        Gateway->>Router: Kafka: router.inbox
+        Router->>Provider: Kafka: user.inbox
+        Provider->>User: WebSocket: chunk
+    end
+
+    Agent->>Gateway: gRPC stream: done=true
+```
+
+## Installation
+
+```bash
+# Using pnpm
+pnpm add march-ai-sdk
+
+# Using npm
+npm install march-ai-sdk
+
+# Using yarn
+yarn add march-ai-sdk
+```
+
+Or scaffold a new project with the CLI:
+
+```bash
+npx march-start my-agent
+```
+
+### Peer Dependencies
+
+The SDK requires the following peer dependencies:
+
+```bash
+pnpm add @grpc/grpc-js @grpc/proto-loader zod
+```
+
+### Optional Extensions
+
+```bash
+# For LangGraph support
+pnpm add @langchain/langgraph @langchain/langgraph-checkpoint @langchain/core
+
+# For Vercel AI SDK support
+pnpm add ai @ai-sdk/openai
+```
+
+## Quick Start
+
+```typescript
+import { config } from 'dotenv'
+import { MarchAgentApp, Message } from 'march-ai-sdk'
+
+// Load environment variables
+config({ path: '.env', override: true })
+
+// Initialize the app
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL || 'agent-gateway:8080',
+    apiKey: process.env.GATEWAY_API_KEY || 'your-api-key',
+})
+
+async function main() {
+    // Register an agent
+    const agent = await app.registerMe({
+        name: 'my-assistant',
+        about: 'A helpful AI assistant',
+        document: 'Answers general questions and provides helpful information.',
+        representationName: 'My Assistant',
+    })
+
+    // Handle messages
+    agent.onMessage(async (message: Message, sender: string) => {
+        // Access conversation history
+        const history = await message.conversation?.getHistory({ limit: 10 })
+
+        // Stream response
+        const streamer = agent.streamer(message)
+        streamer.stream('Hello! ')
+        streamer.stream('How can I help you today?')
+        await streamer.finish()
+    })
+
+    // Run the agent
+    await app.run()
+}
+
+main().catch(console.error)
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GATEWAY_URL` | Agent Gateway endpoint | Required |
+| `GATEWAY_API_KEY` | API key for authentication | Required |
+| `HEARTBEAT_INTERVAL` | Heartbeat frequency (seconds) | `60` |
+| `CONNECTION_SECURE` | Use TLS for connections | `false` |
+
+### MarchAgentApp Options
+
+```typescript
+interface AppOptions {
+    gatewayUrl: string       // Gateway endpoint (host:port)
+    apiKey: string           // Authentication key
+    heartbeatInterval?: number  // Heartbeat frequency in seconds (default: 60)
+    maxConcurrentTasks?: number // Max concurrent message handlers (default: 100)
+    errorMessageTemplate?: string // Error message sent to users
+    secure?: boolean         // Use TLS for gRPC and HTTPS for HTTP (default: false)
+}
+
+const app = new MarchAgentApp({
+    gatewayUrl: 'agent-gateway:8080',
+    apiKey: 'your-api-key',
+    heartbeatInterval: 60,
+    secure: false,
+    errorMessageTemplate: 'Sorry, something went wrong. Please try again.',
+})
+```
+
+## API Reference
+
+### MarchAgentApp
+
+Main application class for initializing and running agents.
+
+```typescript
+import { MarchAgentApp } from 'march-ai-sdk'
+
+const app = new MarchAgentApp({
+    gatewayUrl: 'agent-gateway:8080',
+    apiKey: 'your-api-key',
+})
+
+// Register an agent
+const agent = await app.registerMe({
+    name: 'agent-name',           // Unique identifier (used for routing)
+    about: 'Short description',   // Brief description for agent selection
+    document: 'Full docs...',     // Detailed documentation
+    representationName: 'Name',   // Display name (optional)
+    baseUrl: 'http://...',        // Base URL for artifacts (optional)
+    metadata: { key: 'value' },   // Additional metadata (optional)
+    relatedPages: [               // Related pages (optional)
+        { name: 'Dashboard', endpoint: '/dashboard' }
+    ],
+})
+
+// Start consuming messages (blocks until shutdown)
+await app.run()
+```
+
+### Agent
+
+Handles message registration and response streaming.
+
+```typescript
+// Register message handler (all senders)
+agent.onMessage(async (message, sender) => {
+    // Handle message
+})
+
+// Filter by sender
+agent.onMessage(async (message, sender) => {
+    // Only handles messages from 'user'
+}, { senders: ['user'] })
+
+// Exclude sender
+agent.onMessage(async (message, sender) => {
+    // Handles all except 'other-agent'
+}, { senders: ['~other-agent'] })
+```
+
+### Message
+
+Represents an incoming message with conversation context.
+
+```typescript
+agent.onMessage(async (message: Message, sender: string) => {
+    // Core properties
+    message.id                  // Message ID
+    message.conversationId      // Conversation ID
+    message.userId              // User who sent the message
+    message.content             // Message content
+    message.createdAt           // Timestamp
+
+    // Metadata
+    message.metadata            // Custom metadata from frontend
+    message.schema              // JSON schema for form responses
+
+    // Attachments
+    message.hasAttachment()     // Check if attachment exists
+    message.attachment          // AttachmentInfo object
+    await message.getAttachmentBytes()   // Download as Buffer
+    await message.getAttachmentBase64()  // Download as base64 string
+
+    // Conversation history
+    await message.conversation?.getHistory({ limit: 10 })
+    await message.conversation?.getAgentHistory({ limit: 10 })
+
+    // Long-term memory
+    await message.memory?.queryAboutUser({ query: '...', limit: 5 })
+    await message.memory?.getUserSummary()
+})
+```
+
+#### Message Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Message ID |
+| `conversationId` | `string` | Conversation ID |
+| `userId` | `string` | User who sent the message |
+| `content` | `string` | Message content |
+| `createdAt` | `string` | ISO timestamp |
+| `metadata` | `Record<string, unknown> \| undefined` | Custom metadata |
+| `schema` | `Record<string, unknown> \| undefined` | JSON schema for forms |
+| `attachment` | `AttachmentInfo \| undefined` | File attachment metadata |
+| `conversation` | `Conversation \| undefined` | Conversation helper |
+| `memory` | `Memory \| undefined` | Long-term memory helper |
+
+### Streamer
+
+Streams response chunks back to the user (or another agent).
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    // Basic streaming
+    const streamer = agent.streamer(message)
+    streamer.stream('Chunk 1...')
+    streamer.stream('Chunk 2...')
+    await streamer.finish()
+
+    // Streaming with options
+    const streamer2 = agent.streamer(message, {
+        sendTo: 'user',      // or another agent name
+        awaiting: true,      // Set awaiting_route to this agent
+    })
+
+    // Non-persisted content (not saved to DB)
+    streamer2.stream('Thinking...', { persist: false, eventType: 'thinking' })
+
+    // Persisted content
+    streamer2.stream('Here is my response...')
+
+    // Set response schema for forms
+    streamer2.setResponseSchema({
+        type: 'object',
+        properties: {
+            name: { type: 'string' }
+        }
+    })
+
+    // Add artifacts
+    streamer2.addArtifact({
+        url: '/dashboard/123',
+        type: 'iframe',
+        title: 'Dashboard',
+    })
+
+    // Set message metadata
+    streamer2.setMessageMetadata({
+        model: 'gpt-4o',
+        confidence: 0.95,
+    })
+
+    await streamer2.finish()
+})
+```
+
+#### Streamer Methods
+
+| Method | Description |
+|--------|-------------|
+| `stream(content, options?)` | Stream a content chunk |
+| `write(content, persist?)` | Alias for stream() |
+| `finish(awaiting?)` | Finish streaming with done=true signal |
+| `setResponseSchema(schema)` | Set JSON Schema for form rendering |
+| `setMessageMetadata(metadata)` | Set message metadata |
+| `addArtifact(artifact)` | Add an artifact to the message |
+| `setArtifacts(artifacts)` | Set all artifacts at once |
+
+## Extensions
+
+### LangGraph Integration
+
+Use `HTTPCheckpointSaver` to persist LangGraph state via the Conversation Store checkpoint API.
+
+```typescript
+import { MarchAgentApp, Message } from 'march-ai-sdk'
+import { HTTPCheckpointSaver } from 'march-ai-sdk/extensions/langgraph'
+import { StateGraph, START, END, Annotation } from '@langchain/langgraph'
+import { ChatOpenAI } from '@langchain/openai'
+import { HumanMessage, AIMessage, BaseMessage } from '@langchain/core/messages'
+
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL!,
+    apiKey: process.env.GATEWAY_API_KEY!,
+})
+
+// Create checkpointer
+const checkpointer = new HTTPCheckpointSaver(app)
+
+// Define state
+const StateAnnotation = Annotation.Root({
+    messages: Annotation<BaseMessage[]>({
+        reducer: (x, y) => x.concat(y),
+    }),
+})
+
+// Create graph
+const llm = new ChatOpenAI({ model: 'gpt-4o-mini', streaming: true })
+
+async function respond(state: typeof StateAnnotation.State) {
+    const response = await llm.invoke(state.messages)
+    return { messages: [response] }
+}
+
+const graph = new StateGraph(StateAnnotation)
+    .addNode('respond', respond)
+    .addEdge(START, 'respond')
+    .addEdge('respond', END)
+
+const compiled = graph.compile({ checkpointer })
+
+// Register agent
+const agent = await app.registerMe({
+    name: 'langgraph-agent',
+    about: 'Agent using LangGraph for state management',
+    document: 'Uses LangGraph to maintain conversation state.',
+})
+
+agent.onMessage(async (message: Message, sender: string) => {
+    const config = { configurable: { thread_id: message.conversationId } }
+
+    // Add user message and invoke graph
+    const result = await compiled.invoke(
+        { messages: [new HumanMessage(message.content)] },
+        config
+    )
+
+    // Stream response
+    const streamer = agent.streamer(message)
+    const lastMessage = result.messages[result.messages.length - 1]
+    streamer.stream(lastMessage.content as string)
+    await streamer.finish()
+})
+
+await app.run()
+```
+
+### Vercel AI SDK Integration
+
+Use `VercelAIMessageStore` to persist message history for Vercel AI SDK.
+
+```typescript
+import { MarchAgentApp, Message } from 'march-ai-sdk'
+import { VercelAIMessageStore } from 'march-ai-sdk/extensions/vercel-ai'
+import { streamText, CoreMessage } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const app = new MarchAgentApp({
+    gatewayUrl: process.env.GATEWAY_URL!,
+    apiKey: process.env.GATEWAY_API_KEY!,
+})
+
+// Create message store
+const store = new VercelAIMessageStore(app)
+
+const agent = await app.registerMe({
+    name: 'vercel-ai-agent',
+    about: 'Agent using Vercel AI SDK',
+    document: 'Uses Vercel AI SDK for LLM interactions.',
+})
+
+agent.onMessage(async (message: Message, sender: string) => {
+    // Load previous messages
+    const history = await store.load(message.conversationId)
+
+    // Build messages array
+    const messages: CoreMessage[] = [
+        { role: 'system', content: 'You are a helpful assistant.' },
+        ...history,
+        { role: 'user', content: message.content }
+    ]
+
+    const streamer = agent.streamer(message)
+
+    // Stream response
+    const result = await streamText({
+        model: openai('gpt-4o'),
+        messages,
+        onChunk: ({ chunk }) => {
+            if (chunk.type === 'text-delta') {
+                streamer.stream(chunk.textDelta)
+            }
+        }
+    })
+
+    await streamer.finish()
+
+    // Save updated history
+    await store.save(message.conversationId, [
+        ...history,
+        { role: 'user', content: message.content },
+        { role: 'assistant', content: result.text }
+    ])
+})
+
+await app.run()
+```
+
+#### VercelAIMessageStore Methods
+
+| Method | Description |
+|--------|-------------|
+| `load(conversationId)` | Load message history |
+| `save(conversationId, messages)` | Save message history |
+| `clear(conversationId)` | Clear message history |
+| `append(conversationId, messages)` | Append to existing history |
+| `getLastMessages(conversationId, count)` | Get last N messages |
+
+## Advanced Usage
+
+### Inter-Agent Communication
+
+Agents can send messages to other agents using the `sendTo` option.
+
+```typescript
+// Handle user messages - forward to specialist
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message, { sendTo: 'specialist-agent' })
+    streamer.stream('Forwarding your question to the specialist...')
+    await streamer.finish()
+}, { senders: ['user'] })
+
+// Handle specialist responses - send back to user
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message, { sendTo: 'user' })
+    streamer.stream(`The specialist says: ${message.content}`)
+    await streamer.finish()
+}, { senders: ['specialist-agent'] })
+```
+
+### Dynamic Forms with Response Schema
+
+Request structured input from users using JSON Schema forms.
+
+```typescript
+agent.onMessage(async (message, sender) => {
+    // Check if this is a form response
+    if (message.schema) {
+        const data = JSON.parse(message.content)
+        const streamer = agent.streamer(message)
+        streamer.stream(`Thank you, ${data.name}! I received your message.`)
+        await streamer.finish()
+        return
+    }
+
+    // Request form input
+    const streamer = agent.streamer(message, { awaiting: true })
+    streamer.setResponseSchema({
+        type: 'object',
+        title: 'Contact Information',
+        properties: {
+            name: { type: 'string', title: 'Full Name' },
+            email: { type: 'string', format: 'email', title: 'Email' },
+            message: { type: 'string', title: 'Message' }
+        },
+        required: ['name', 'email']
+    })
+    streamer.stream('Please fill out your contact information:')
+    await streamer.finish()
+})
+```
+
+### Error Handling
+
+Customize error handling behavior:
+
+```typescript
+const app = new MarchAgentApp({
+    gatewayUrl: '...',
+    apiKey: '...',
+    errorMessageTemplate: 'Sorry, something went wrong. Please try again.',
+})
+
+const agent = await app.registerMe({ ... })
+
+// Disable automatic error responses
+agent.sendErrorResponses = false
+
+agent.onMessage(async (message, sender) => {
+    try {
+        // Your logic
+    } catch (error) {
+        // Custom error handling
+        const streamer = agent.streamer(message)
+        streamer.stream(`I encountered an issue: ${error}`)
+        await streamer.finish()
+    }
+})
+```
+
+## Project Structure
+
+```
+ai-ts-framework/
+├── src/
+│   ├── index.ts              # Package exports
+│   ├── app.ts                # MarchAgentApp
+│   ├── agent.ts              # Agent class
+│   ├── message.ts            # Message class
+│   ├── streamer.ts           # Streamer class
+│   ├── conversation.ts       # Conversation helper
+│   ├── memory.ts             # Memory helper
+│   ├── conversation-client.ts # HTTP client for Conversation Store
+│   ├── checkpoint-client.ts  # HTTP client for checkpoints
+│   ├── agent-state-client.ts # HTTP client for agent state
+│   ├── memory-client.ts      # HTTP client for AI Memory
+│   ├── attachment-client.ts  # HTTP client for attachments
+│   ├── gateway-client.ts     # gRPC client for Agent Gateway
+│   ├── heartbeat.ts          # Heartbeat manager
+│   ├── api-paths.ts          # API endpoint configuration
+│   ├── types.ts              # TypeScript types
+│   ├── exceptions.ts         # Custom exceptions
+│   ├── proto/
+│   │   └── gateway.proto     # gRPC protocol definition
+│   └── extensions/
+│       ├── index.ts
+│       ├── langgraph.ts      # LangGraph HTTPCheckpointSaver
+│       └── vercel-ai.ts      # Vercel AI MessageStore
+├── tests/
+│   ├── agent.test.ts
+│   ├── app.test.ts
+│   ├── checkpoint-client.test.ts
+│   ├── message.test.ts
+│   └── streamer.test.ts
+├── tsup.config.ts            # Build configuration
+├── vitest.config.ts          # Test configuration
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+### Building
+
+```bash
+# Build the package
+pnpm build
+
+# Type check without building
+pnpm typecheck
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| @grpc/grpc-js | gRPC communication with Agent Gateway |
+| @grpc/proto-loader | Protobuf loading |
+| zod | Schema validation |
+
+### Optional Dependencies
+
+| Package | Install Command | Purpose |
+|---------|-----------------|---------|
+| @langchain/langgraph | `pnpm add @langchain/langgraph` | LangGraph state management |
+| @langchain/langgraph-checkpoint | `pnpm add @langchain/langgraph-checkpoint` | Checkpoint interface |
+| ai | `pnpm add ai` | Vercel AI SDK |
+| @ai-sdk/openai | `pnpm add @ai-sdk/openai` | OpenAI provider for Vercel AI |
+
+## TypeScript Types
+
+The SDK exports all types for TypeScript users:
+
+```typescript
+import type {
+    // Core types
+    Message,
+    Streamer,
+    Agent,
+    MarchAgentApp,
+
+    // Options
+    AppOptions,
+    RegisterOptions,
+    StreamOptions,
+    StreamerOptions,
+
+    // Data types
+    KafkaMessage,
+    AgentRegistrationData,
+    AttachmentInfo,
+    ConversationData,
+
+    // Memory types
+    MemoryMessage,
+    MemorySearchResult,
+    UserSummary,
+
+    // Handler types
+    MessageHandler,
+    SenderFilterOptions,
+} from 'march-ai-sdk'
+```
+
+## Exceptions
+
+The SDK provides typed exceptions:
+
+```typescript
+import {
+    MarchAgentError,      // Base error class
+    RegistrationError,    // Agent registration failed
+    KafkaError,          // Kafka communication error
+    ConfigurationError,  // Invalid configuration
+    APIException,        // HTTP API error
+    HeartbeatError,      // Heartbeat failed
+    GatewayError,        // Gateway communication error
+} from 'march-ai-sdk'
+```
+
+## License
+
+MIT