march-ai-sdk 0.3.0

package/src/agent.ts

@@ -0,0 +1,293 @@
+/**
+ * March Agent SDK - Agent
+ * Port of Python march_agent/agent.py
+ */
+
+import { Message } from './message.js'
+import { Streamer } from './streamer.js'
+import { HeartbeatManager } from './heartbeat.js'
+import { ConfigurationError } from './exceptions.js'
+import type { GatewayClient } from './gateway-client.js'
+import type { ConversationClient } from './conversation-client.js'
+import type { MemoryClient } from './memory-client.js'
+import type { AttachmentClient } from './attachment-client.js'
+import type {
+    AgentRegistrationData,
+    MessageHandler,
+    SenderFilterOptions,
+    StreamerOptions,
+    KafkaMessage,
+} from './types.js'
+
+/**
+ * Filter for matching message senders.
+ */
+export class SenderFilter {
+    private readonly _include: Set<string> = new Set()
+    private readonly _exclude: Set<string> = new Set()
+    readonly matchAll: boolean
+
+    constructor(senders?: string[]) {
+        if (!senders || senders.length === 0) {
+            this.matchAll = true
+        } else {
+            this.matchAll = false
+            for (const sender of senders) {
+                if (sender.startsWith('~')) {
+                    this._exclude.add(sender.slice(1))
+                } else {
+                    this._include.add(sender)
+                }
+            }
+        }
+    }
+
+    /**
+     * Get included senders as an array (for compatibility with Python tests).
+     */
+    get include(): string[] {
+        return Array.from(this._include)
+    }
+
+    /**
+     * Get excluded senders as an array (for compatibility with Python tests).
+     */
+    get exclude(): string[] {
+        return Array.from(this._exclude)
+    }
+
+    /**
+     * Check if sender matches this filter.
+     */
+    matches(sender: string): boolean {
+        // If excluded, reject
+        if (this._exclude.has(sender)) {
+            return false
+        }
+        // If match all or explicitly included
+        if (this.matchAll || this._include.size === 0) {
+            return true
+        }
+        return this._include.has(sender)
+    }
+}
+
+// Message handlers stored as tuples: [SenderFilter, MessageHandler]
+type RegisteredHandler = [SenderFilter, MessageHandler]
+
+/**
+ * Core agent class that handles messaging via the Agent Gateway.
+ */
+export class Agent {
+    readonly name: string
+    readonly agentData: AgentRegistrationData
+    sendErrorResponses: boolean = true
+    errorMessageTemplate: string
+
+    private readonly gatewayClient: GatewayClient
+    private readonly conversationClient?: ConversationClient
+    private readonly memoryClient?: MemoryClient
+    private readonly attachmentClient?: AttachmentClient
+    private readonly heartbeatInterval: number
+
+    private messageHandlers: RegisteredHandler[] = []
+    private heartbeatManager?: HeartbeatManager
+    private initialized: boolean = false
+    private running: boolean = false
+
+    constructor(options: {
+        name: string
+        gatewayClient: GatewayClient
+        agentData: AgentRegistrationData
+        heartbeatInterval?: number
+        conversationClient?: ConversationClient
+        memoryClient?: MemoryClient
+        attachmentClient?: AttachmentClient
+        errorMessageTemplate?: string
+    }) {
+        this.name = options.name
+        this.gatewayClient = options.gatewayClient
+        this.agentData = options.agentData
+        this.heartbeatInterval = options.heartbeatInterval ?? 60
+        this.conversationClient = options.conversationClient
+        this.memoryClient = options.memoryClient
+        this.attachmentClient = options.attachmentClient
+        this.errorMessageTemplate = options.errorMessageTemplate ??
+            'I encountered an error while processing your message. Please try again or contact support if the issue persists.'
+    }
+
+    /**
+     * Register a message handler.
+     * 
+     * Usage:
+     *   agent.onMessage(async (message, sender) => { ... })
+     *   agent.onMessage(handler, { senders: ['user'] })
+     */
+    onMessage(handler: MessageHandler): void
+    onMessage(handler: MessageHandler, options: SenderFilterOptions): void
+    onMessage(
+        handler: MessageHandler,
+        options?: SenderFilterOptions
+    ): void {
+        const filter = new SenderFilter(options?.senders)
+        this.messageHandlers.push([filter, handler])
+    }
+
+    /**
+     * Initialize agent after gateway connection is established.
+     */
+    initializeWithGateway(): void {
+        if (this.initialized) {
+            return
+        }
+
+        // Register message handler with gateway
+        const topic = `${this.name}.inbox`
+        this.gatewayClient.registerHandler(topic, (msg) => {
+            this.handleKafkaMessage(msg)
+        })
+
+        // Start heartbeat
+        this.heartbeatManager = new HeartbeatManager(
+            this.gatewayClient,
+            this.name,
+            this.heartbeatInterval
+        )
+        this.heartbeatManager.start()
+
+        this.initialized = true
+    }
+
+    /**
+     * Get sender from message headers.
+     */
+    private getSender(headers: Record<string, string>): string {
+        return headers.from_ ?? headers.from ?? 'user'
+    }
+
+    /**
+     * Find first handler that matches the sender.
+     */
+    private findMatchingHandler(sender: string): MessageHandler | undefined {
+        for (const [filter, handler] of this.messageHandlers) {
+            if (filter.matches(sender)) {
+                return handler
+            }
+        }
+        return undefined
+    }
+
+    /**
+     * Handle incoming Kafka message.
+     */
+    private handleKafkaMessage(kafkaMsg: KafkaMessage): void {
+        // Run handler asynchronously
+        this.handleMessageAsync(kafkaMsg).catch((error) => {
+            console.error('Error in message handler:', error)
+        })
+    }
+
+    /**
+     * Async message handling with error recovery.
+     */
+    private async handleMessageAsync(kafkaMsg: KafkaMessage): Promise<void> {
+        let message: Message | undefined
+
+        try {
+            // Create message from Kafka data
+            message = Message.fromKafkaMessage(
+                kafkaMsg.body,
+                kafkaMsg.headers,
+                {
+                    conversationClient: this.conversationClient,
+                    memoryClient: this.memoryClient,
+                    attachmentClient: this.attachmentClient,
+                    agentName: this.name,
+                }
+            )
+
+            // Find matching handler
+            const sender = this.getSender(kafkaMsg.headers)
+            const handler = this.findMatchingHandler(sender)
+
+            if (!handler) {
+                console.warn(`No handler matched for sender: ${sender}`)
+                return
+            }
+
+            // Call handler
+            await handler(message, sender)
+
+        } catch (error) {
+            console.error('Error handling message:', error)
+
+            // Send error response if we have a message
+            if (message && this.sendErrorResponses) {
+                await this.sendErrorResponse(message, error as Error)
+            }
+        }
+    }
+
+    /**
+     * Send error response to user when handler fails.
+     */
+    private async sendErrorResponse(message: Message, _error: Error): Promise<void> {
+        try {
+            const streamer = this.streamer(message, { sendTo: 'user' })
+            streamer.stream(this.errorMessageTemplate)
+            await streamer.finish()
+        } catch (err) {
+            console.error('Failed to send error response:', err)
+        }
+    }
+
+    /**
+     * Create a new Streamer for streaming responses.
+     */
+    streamer(message: Message, options: StreamerOptions = {}): Streamer {
+        return new Streamer({
+            agentName: this.name,
+            originalMessage: message,
+            gatewayClient: this.gatewayClient,
+            conversationClient: this.conversationClient,
+            awaiting: options.awaiting ?? false,
+            sendTo: options.sendTo ?? 'user',
+        })
+    }
+
+    /**
+     * Mark agent as ready to consume messages.
+     */
+    startConsuming(): void {
+        if (this.messageHandlers.length === 0) {
+            throw new ConfigurationError('No message handlers registered')
+        }
+
+        if (!this.initialized) {
+            throw new ConfigurationError('Agent not initialized with gateway')
+        }
+
+        this.running = true
+        console.log(`Agent ${this.name} is now consuming messages`)
+    }
+
+    /**
+     * Shutdown agent gracefully.
+     */
+    shutdown(): void {
+        this.running = false
+
+        if (this.heartbeatManager) {
+            this.heartbeatManager.stop()
+        }
+
+        console.log(`Agent ${this.name} shutdown`)
+    }
+
+    /**
+     * Check if agent is running.
+     */
+    isRunning(): boolean {
+        return this.running
+    }
+}

package/src/api-paths.ts

@@ -0,0 +1,60 @@
+/**
+ * March Agent SDK - API Paths Configuration
+ * 
+ * Centralized configuration for all API endpoint paths.
+ * This allows easy configuration if API versions or paths change.
+ */
+
+/**
+ * API paths for AI Inventory service.
+ */
+export const AI_INVENTORY_PATHS = {
+    /** Register a new agent */
+    AGENT_REGISTER: '/api/v1/agents/register',
+    /** Send heartbeat */
+    HEALTH_HEARTBEAT: '/api/v1/health/heartbeat',
+} as const
+
+/**
+ * API paths for Conversation Store service.
+ * Note: These paths don't have /api/v1/ prefix.
+ */
+export const CONVERSATION_STORE_PATHS = {
+    /** Get/update conversation by ID */
+    CONVERSATION: (conversationId: string) => `/conversations/${conversationId}`,
+    /** Get messages for a conversation */
+    CONVERSATION_MESSAGES: (conversationId: string) => `/conversations/${conversationId}/messages`,
+    /** Checkpoints base path */
+    CHECKPOINTS: '/checkpoints/',
+    /** Checkpoint by thread ID */
+    CHECKPOINT_THREAD: (threadId: string) => `/checkpoints/${threadId}`,
+    /** Agent state by conversation ID */
+    AGENT_STATE: (conversationId: string) => `/agent-state/${conversationId}`,
+} as const
+
+/**
+ * API paths for AI Memory service.
+ * Note: These paths don't have /api/v1/ prefix.
+ */
+export const MEMORY_PATHS = {
+    /** User memory base */
+    USER_MEMORY: (userId: string) => `/memory/${userId}`,
+    /** Add messages to memory */
+    USER_MESSAGES: (userId: string) => `/memory/${userId}/messages`,
+    /** Search user memory */
+    USER_SEARCH: (userId: string) => `/memory/${userId}/search`,
+    /** Get user summary */
+    USER_SUMMARY: (userId: string) => `/memory/${userId}/summary`,
+} as const
+
+/**
+ * Service names for gateway proxy routing.
+ */
+export const SERVICES = {
+    AI_INVENTORY: 'ai-inventory',
+    CONVERSATION_STORE: 'conversation-store',
+    AI_MEMORY: 'ai-memory',
+    ATTACHMENT: 'attachment',
+} as const
+
+export type ServiceName = typeof SERVICES[keyof typeof SERVICES]

package/src/app.ts

@@ -0,0 +1,235 @@
+/**
+ * March Agent SDK - Main Application
+ * Port of Python march_agent/app.py
+ */
+
+import { Agent } from './agent.js'
+import { GatewayClient } from './gateway-client.js'
+import { ConversationClient } from './conversation-client.js'
+import { MemoryClient } from './memory-client.js'
+import { AttachmentClient } from './attachment-client.js'
+import { RegistrationError, ConfigurationError } from './exceptions.js'
+import { AI_INVENTORY_PATHS, SERVICES } from './api-paths.js'
+import type { AppOptions, RegisterOptions, AgentRegistrationData } from './types.js'
+
+/**
+ * Main application class for March AI Agent framework.
+ * 
+ * @example
+ * ```typescript
+ * import { MarchAgentApp } from 'march-ai-sdk'
+ * 
+ * const app = new MarchAgentApp({
+ *   gatewayUrl: 'agent-gateway:8080',
+ *   apiKey: 'your-api-key',
+ * })
+ * 
+ * const agent = app.registerMe({
+ *   name: 'my-agent',
+ *   about: 'A helpful assistant',
+ *   document: 'Detailed description...',
+ * })
+ * 
+ * agent.onMessage(async (message, sender) => {
+ *   const streamer = agent.streamer(message)
+ *   streamer.stream('Hello!')
+ *   await streamer.finish()
+ * })
+ * 
+ * app.run()
+ * ```
+ */
+export class MarchAgentApp {
+    readonly gatewayClient: GatewayClient
+    readonly conversationClient: ConversationClient
+    readonly memoryClient: MemoryClient
+    readonly attachmentClient: AttachmentClient
+
+    private readonly heartbeatInterval: number
+    private readonly _maxConcurrentTasks: number
+    private readonly errorMessageTemplate: string
+
+    private agents: Agent[] = []
+    private running: boolean = false
+    private shutdownRequested: boolean = false
+
+    constructor(options: AppOptions) {
+        this.heartbeatInterval = options.heartbeatInterval ?? 60
+        this._maxConcurrentTasks = options.maxConcurrentTasks ?? 100
+        this.errorMessageTemplate = options.errorMessageTemplate ??
+            'I encountered an error while processing your message. Please try again or contact support if the issue persists.'
+
+        // Create gateway client
+        this.gatewayClient = new GatewayClient(
+            options.gatewayUrl,
+            options.apiKey,
+            options.secure ?? false
+        )
+
+        // Create HTTP clients using gateway proxy URLs
+        this.conversationClient = new ConversationClient(
+            this.gatewayClient.conversationStoreUrl
+        )
+
+        this.memoryClient = new MemoryClient(
+            this.gatewayClient.aiMemoryUrl
+        )
+
+        this.attachmentClient = new AttachmentClient(
+            this.gatewayClient.attachmentUrl
+        )
+    }
+
+    /**
+     * Register an agent with the backend.
+     */
+    async registerMe(options: RegisterOptions): Promise<Agent> {
+        // Register with AI Inventory
+        const agentData = await this.registerWithInventory(options)
+
+        // Create agent instance
+        const agent = new Agent({
+            name: options.name,
+            gatewayClient: this.gatewayClient,
+            agentData,
+            heartbeatInterval: this.heartbeatInterval,
+            conversationClient: this.conversationClient,
+            memoryClient: this.memoryClient,
+            attachmentClient: this.attachmentClient,
+            errorMessageTemplate: this.errorMessageTemplate,
+        })
+
+        this.agents.push(agent)
+        console.log(`Registered agent: ${options.name}`)
+
+        return agent
+    }
+
+    /**
+     * Register agent with AI Inventory service.
+     */
+    private async registerWithInventory(options: RegisterOptions): Promise<AgentRegistrationData> {
+        // Build registration payload (API expects camelCase)
+        const payload: Record<string, unknown> = {
+            name: options.name,
+            about: options.about,
+            document: options.document,
+            representationName: options.representationName || options.name,
+        }
+
+        if (options.baseUrl) {
+            payload.baseUrl = options.baseUrl
+        }
+
+        if (options.metadata) {
+            payload.metadata = options.metadata
+        }
+
+        if (options.relatedPages) {
+            payload.relatedPages = options.relatedPages
+        }
+
+        // Register via gateway HTTP proxy
+        try {
+            const response = await this.gatewayClient.httpPost(
+                SERVICES.AI_INVENTORY,
+                AI_INVENTORY_PATHS.AGENT_REGISTER,
+                payload
+            )
+
+            if (!response.ok) {
+                const errorText = await response.text()
+                console.error('Registration failed:', response.status, errorText)
+                throw new RegistrationError(
+                    `Failed to register agent ${options.name}: ${response.status}`
+                )
+            }
+
+            const data = await response.json() as Record<string, unknown>
+
+            return {
+                id: data.id as string,
+                name: data.name as string,
+                about: data.about as string,
+                document: data.document as string,
+                representationName: data.representationName as string | undefined,
+                baseUrl: data.baseUrl as string | undefined,
+                metadata: data.metadata as Record<string, unknown> | undefined,
+                relatedPages: data.relatedPages as { name: string; endpoint: string }[] | undefined,
+            }
+        } catch (error) {
+            if (error instanceof RegistrationError) throw error
+            throw new RegistrationError(`Failed to register agent ${options.name}: ${error}`)
+        }
+    }
+
+    /**
+     * Start all registered agents and block until shutdown.
+     */
+    async run(): Promise<void> {
+        if (this.agents.length === 0) {
+            throw new ConfigurationError('No agents registered')
+        }
+
+        // Connect to gateway
+        const agentNames = this.agents.map((a) => a.name)
+        console.log(`Connecting to gateway with agents: ${agentNames.join(', ')}`)
+
+        try {
+            const topics = await this.gatewayClient.connect(agentNames)
+            console.log(`Connected. Subscribed to topics: ${topics.join(', ')}`)
+        } catch (error) {
+            throw new ConfigurationError(`Failed to connect to gateway: ${error}`)
+        }
+
+        // Initialize all agents
+        for (const agent of this.agents) {
+            agent.initializeWithGateway()
+            agent.startConsuming()
+        }
+
+        this.running = true
+        console.log('Agent app is running. Press Ctrl+C to stop.')
+
+        // Set up shutdown handlers
+        process.on('SIGINT', () => this.shutdown())
+        process.on('SIGTERM', () => this.shutdown())
+
+        // Keep the process alive
+        await this.consumeLoop()
+    }
+
+    /**
+     * Main consume loop.
+     */
+    private async consumeLoop(): Promise<void> {
+        while (this.running && !this.shutdownRequested) {
+            // The gateway client handles message dispatch via callbacks
+            // We just need to keep the event loop alive
+            await new Promise((resolve) => setTimeout(resolve, 100))
+        }
+    }
+
+    /**
+     * Shutdown all agents gracefully.
+     */
+    shutdown(): void {
+        if (this.shutdownRequested) {
+            return
+        }
+
+        console.log('\nShutting down...')
+        this.shutdownRequested = true
+        this.running = false
+
+        // Shutdown all agents
+        for (const agent of this.agents) {
+            agent.shutdown()
+        }
+
+        // Close gateway connection
+        this.gatewayClient.close()
+
+        console.log('Shutdown complete')
+    }
+}

package/src/artifact.ts

@@ -0,0 +1,59 @@
+/**
+ * March Agent SDK - Artifact Types
+ * Port of Python march_agent/artifact.py
+ */
+
+import { z } from 'zod'
+
+/**
+ * Valid artifact types for message attachments
+ */
+export const ArtifactTypeSchema = z.enum([
+    'document',
+    'image',
+    'iframe',
+    'video',
+    'audio',
+    'code',
+    'link',
+    'file',
+])
+
+export type ArtifactType = z.infer<typeof ArtifactTypeSchema>
+
+/**
+ * Schema for artifact validation
+ */
+export const ArtifactSchema = z.object({
+    url: z.string(),
+    type: ArtifactTypeSchema,
+    title: z.string().optional(),
+    description: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+
+export type Artifact = z.infer<typeof ArtifactSchema>
+
+/**
+ * Input type for adding artifacts (without strict validation)
+ */
+export interface ArtifactInput {
+    url: string
+    type: ArtifactType | string
+    title?: string
+    description?: string
+    metadata?: Record<string, unknown>
+}
+
+/**
+ * Convert artifact input to validated artifact
+ */
+export function toArtifact(input: ArtifactInput): Artifact {
+    return ArtifactSchema.parse({
+        url: input.url,
+        type: input.type,
+        title: input.title,
+        description: input.description,
+        metadata: input.metadata,
+    })
+}