march-ai-sdk 0.3.0

package/src/memory.ts

@@ -0,0 +1,68 @@
+/**
+ * March Agent SDK - Memory Helper
+ * Port of Python march_agent/memory.py
+ */
+
+import { MemoryClient } from './memory-client.js'
+import type { MemoryMessage, MemorySearchResult, UserSummary } from './types.js'
+
+/**
+ * Helper class for accessing long-term memory.
+ * Provides convenient methods for storing and searching memories.
+ */
+export class Memory {
+    readonly userId: string
+    readonly conversationId: string
+    private readonly client: MemoryClient
+
+    constructor(
+        userId: string,
+        conversationId: string,
+        client: MemoryClient
+    ) {
+        this.userId = userId
+        this.conversationId = conversationId
+        this.client = client
+    }
+
+    /**
+     * Add messages to memory.
+     */
+    async addMessages(messages: MemoryMessage[]): Promise<number> {
+        const result = await this.client.addMessages(
+            this.userId,
+            this.conversationId,
+            messages
+        )
+        return result.added
+    }
+
+    /**
+     * Add a single message to memory.
+     */
+    async addMessage(role: 'user' | 'assistant', content: string): Promise<void> {
+        await this.addMessages([{ role, content }])
+    }
+
+    /**
+     * Search memory for relevant content.
+     */
+    async search(query: string, limit: number = 10): Promise<MemorySearchResult[]> {
+        return this.client.search(this.userId, query, limit)
+    }
+
+    /**
+     * Get user summary.
+     */
+    async getSummary(): Promise<UserSummary | null> {
+        return this.client.getUserSummary(this.userId)
+    }
+
+    /**
+     * Clear all memories for this user.
+     */
+    async clear(): Promise<number> {
+        const result = await this.client.clearMemory(this.userId)
+        return result.deleted
+    }
+}

package/src/message.ts

@@ -0,0 +1,178 @@
+/**
+ * March Agent SDK - Message
+ * Port of Python march_agent/message.py
+ */
+
+import { Conversation } from './conversation.js'
+import { Memory } from './memory.js'
+import { ConversationClient } from './conversation-client.js'
+import { MemoryClient } from './memory-client.js'
+import { AttachmentClient, createAttachmentInfo } from './attachment-client.js'
+import type { AttachmentInfo, KafkaHeaders } from './types.js'
+
+/**
+ * Represents an incoming message to the agent.
+ */
+export class Message {
+    readonly content: string
+    readonly conversationId: string
+    readonly userId: string
+    readonly headers: Record<string, string>
+    readonly rawBody: Record<string, unknown>
+    readonly conversation?: Conversation
+    readonly memory?: Memory
+    readonly metadata?: Record<string, unknown>
+    readonly schema?: Record<string, unknown>
+    readonly attachment?: AttachmentInfo
+
+    private readonly attachmentClient?: AttachmentClient
+
+    constructor(options: {
+        content: string
+        conversationId: string
+        userId: string
+        headers: Record<string, string>
+        rawBody: Record<string, unknown>
+        conversation?: Conversation
+        memory?: Memory
+        metadata?: Record<string, unknown>
+        schema?: Record<string, unknown>
+        attachment?: AttachmentInfo
+        attachmentClient?: AttachmentClient
+    }) {
+        this.content = options.content
+        this.conversationId = options.conversationId
+        this.userId = options.userId
+        this.headers = options.headers
+        this.rawBody = options.rawBody
+        this.conversation = options.conversation
+        this.memory = options.memory
+        this.metadata = options.metadata
+        this.schema = options.schema
+        this.attachment = options.attachment
+        this.attachmentClient = options.attachmentClient
+    }
+
+    /**
+     * Create Message from Kafka message data.
+     */
+    static fromKafkaMessage(
+        body: Record<string, unknown>,
+        headers: KafkaHeaders,
+        options: {
+            conversationClient?: ConversationClient
+            memoryClient?: MemoryClient
+            attachmentClient?: AttachmentClient
+            agentName?: string
+        } = {}
+    ): Message {
+        const conversationId = headers.conversationId ?? ''
+        const userId = headers.userId ?? 'anonymous'
+
+        // Parse metadata from header
+        let metadata: Record<string, unknown> | undefined
+        if (headers.messageMetadata) {
+            try {
+                metadata = JSON.parse(headers.messageMetadata)
+            } catch {
+                // Ignore parse errors
+            }
+        }
+
+        // Parse schema from header
+        let schema: Record<string, unknown> | undefined
+        if (headers.messageSchema) {
+            try {
+                schema = JSON.parse(headers.messageSchema)
+            } catch {
+                // Ignore parse errors
+            }
+        }
+
+        // Parse attachment from header or body
+        let attachment: AttachmentInfo | undefined
+        if (headers.attachment) {
+            try {
+                const attachmentData = JSON.parse(headers.attachment)
+                attachment = createAttachmentInfo(attachmentData)
+            } catch {
+                // Ignore parse errors
+            }
+        }
+        // Fallback to body attachment
+        if (!attachment && body.attachment) {
+            try {
+                attachment = createAttachmentInfo(body.attachment as Record<string, unknown>)
+            } catch {
+                // Ignore parse errors
+            }
+        }
+
+        // Create conversation helper
+        let conversation: Conversation | undefined
+        if (conversationId && options.conversationClient) {
+            conversation = new Conversation(
+                conversationId,
+                options.conversationClient,
+                options.agentName
+            )
+        }
+
+        // Create memory helper
+        let memory: Memory | undefined
+        if (options.memoryClient && userId && conversationId) {
+            memory = new Memory(userId, conversationId, options.memoryClient)
+        }
+
+        return new Message({
+            content: (body.content as string) ?? '',
+            conversationId,
+            userId,
+            headers: headers as Record<string, string>,
+            rawBody: body,
+            conversation,
+            memory,
+            metadata,
+            schema,
+            attachment,
+            attachmentClient: options.attachmentClient,
+        })
+    }
+
+    /**
+     * Check if message has an attachment.
+     */
+    hasAttachment(): boolean {
+        return this.attachment !== undefined
+    }
+
+    /**
+     * Download attachment as bytes (Buffer).
+     * 
+     * @throws Error if no attachment is available
+     */
+    async getAttachmentBytes(): Promise<Buffer> {
+        if (!this.attachment) {
+            throw new Error('No attachment available')
+        }
+        if (!this.attachmentClient) {
+            throw new Error('AttachmentClient not available')
+        }
+        return this.attachmentClient.download(this.attachment.url)
+    }
+
+    /**
+     * Get attachment as base64 string (for LLM vision APIs).
+     * 
+     * @throws Error if no attachment is available
+     */
+    async getAttachmentBase64(): Promise<string> {
+        if (!this.attachment) {
+            throw new Error('No attachment available')
+        }
+        if (!this.attachmentClient) {
+            throw new Error('AttachmentClient not available')
+        }
+        return this.attachmentClient.downloadAsBase64(this.attachment.url)
+    }
+}

package/src/proto/gateway.proto

@@ -0,0 +1,99 @@
+syntax = "proto3";
+package gateway;
+option go_package = "agent-gateway/internal/grpc/pb";
+
+// Bidirectional streaming service for agent communication
+service AgentGateway {
+  // Main bidirectional stream for all agent communication
+  rpc AgentStream(stream ClientMessage) returns (stream ServerMessage);
+}
+
+// Client -> Server messages
+message ClientMessage {
+  oneof payload {
+    AuthRequest auth = 1;
+    SubscribeRequest subscribe = 2;
+    UnsubscribeRequest unsubscribe = 3;
+    ProduceRequest produce = 4;
+    PingRequest ping = 5;
+  }
+}
+
+// Server -> Client messages
+message ServerMessage {
+  oneof payload {
+    AuthResponse auth_response = 1;
+    KafkaMessage message = 2;
+    ProduceAck produce_ack = 3;
+    SubscribeAck subscribe_ack = 4;
+    UnsubscribeAck unsubscribe_ack = 5;
+    PongResponse pong = 6;
+    ErrorResponse error = 7;
+  }
+}
+
+message AuthRequest {
+  string api_key = 1;
+  repeated string agent_names = 2;
+}
+
+message AuthResponse {
+  string connection_id = 1;
+  repeated string subscribed_topics = 2;
+}
+
+message SubscribeRequest {
+  string agent_name = 1;
+}
+
+message SubscribeAck {
+  string topic = 1;
+}
+
+message UnsubscribeRequest {
+  string agent_name = 1;
+}
+
+message UnsubscribeAck {
+  string agent_name = 1;
+}
+
+message ProduceRequest {
+  string topic = 1;
+  string key = 2;
+  map<string, string> headers = 3;
+  bytes body = 4;  // JSON as bytes
+  string correlation_id = 5;
+}
+
+message ProduceAck {
+  string topic = 1;
+  int32 partition = 2;
+  int64 offset = 3;
+  string correlation_id = 4;
+}
+
+message KafkaMessage {
+  string topic = 1;
+  int32 partition = 2;
+  int64 offset = 3;
+  string key = 4;
+  map<string, string> headers = 5;
+  bytes body = 6;  // JSON as bytes
+  int64 timestamp = 7;
+}
+
+message PingRequest {
+  int64 timestamp = 1;
+}
+
+message PongResponse {
+  int64 client_timestamp = 1;
+  int64 server_timestamp = 2;
+}
+
+message ErrorResponse {
+  string code = 1;
+  string message = 2;
+  string correlation_id = 3;
+}

package/src/streamer.ts

@@ -0,0 +1,242 @@
+/**
+ * March Agent SDK - Streamer
+ * Port of Python march_agent/streamer.py
+ */
+
+import type { Message } from './message.js'
+import type { GatewayClient } from './gateway-client.js'
+import type { ConversationClient } from './conversation-client.js'
+import type { Artifact, ArtifactInput } from './artifact.js'
+import { toArtifact } from './artifact.js'
+import type { StreamOptions } from './types.js'
+
+/**
+ * Handles streaming responses back to the conversation via the gateway.
+ */
+export class Streamer {
+    private readonly agentName: string
+    private readonly originalMessage: Message
+    private readonly gatewayClient: GatewayClient
+    private readonly conversationClient?: ConversationClient
+    private readonly sendTo: string
+    private awaiting: boolean
+
+    private responseSchema?: Record<string, unknown>
+    private messageMetadata?: Record<string, unknown>
+    private artifacts: Artifact[] = []
+    private streamedContent: string = ''
+    private firstChunkSent: boolean = false
+    private finished: boolean = false
+
+    constructor(options: {
+        agentName: string
+        originalMessage: Message
+        gatewayClient: GatewayClient
+        conversationClient?: ConversationClient
+        awaiting?: boolean
+        sendTo?: string
+    }) {
+        this.agentName = options.agentName
+        this.originalMessage = options.originalMessage
+        this.gatewayClient = options.gatewayClient
+        this.conversationClient = options.conversationClient
+        this.awaiting = options.awaiting ?? false
+        this.sendTo = options.sendTo ?? 'user'
+    }
+
+    /**
+     * Set response schema for form rendering (fluent API).
+     */
+    setResponseSchema(schema: Record<string, unknown>): this {
+        this.responseSchema = schema
+        return this
+    }
+
+    /**
+     * Set message metadata (fluent API).
+     */
+    setMessageMetadata(metadata: Record<string, unknown>): this {
+        this.messageMetadata = metadata
+        return this
+    }
+
+    /**
+     * Add an artifact to the message (fluent API).
+     */
+    addArtifact(artifact: ArtifactInput): this {
+        this.artifacts.push(toArtifact(artifact))
+        return this
+    }
+
+    /**
+     * Set all artifacts at once (replaces any existing).
+     */
+    setArtifacts(artifacts: ArtifactInput[]): this {
+        this.artifacts = artifacts.map(toArtifact)
+        return this
+    }
+
+    /**
+     * Stream a content chunk.
+     */
+    stream(content: string, options: StreamOptions = {}): void {
+        const { persist = true, eventType } = options
+
+        if (this.finished) {
+            console.warn('Streamer.stream() called after finish()')
+            return
+        }
+
+        if (persist) {
+            this.streamedContent += content
+        }
+
+        this.send(content, false, persist, eventType)
+    }
+
+    /**
+     * Alias for stream() - write a content chunk.
+     */
+    write(content: string, persist: boolean = true): void {
+        this.stream(content, { persist })
+    }
+
+    /**
+     * Finish streaming with done=true signal.
+     */
+    async finish(awaitingOverride?: boolean): Promise<void> {
+        if (this.finished) {
+            return
+        }
+
+        this.finished = true
+
+        // Determine final awaiting value
+        let finalAwaiting = awaitingOverride ?? this.awaiting
+
+        // If response schema was set and awaiting not explicitly false, set awaiting
+        if (this.responseSchema && awaitingOverride !== false) {
+            finalAwaiting = true
+        }
+
+        // Send final done message
+        this.send('', true, false)
+
+        // Set pending response schema on conversation
+        if (this.responseSchema && this.conversationClient) {
+            await this.setPendingResponseSchema()
+        }
+
+        // Set awaiting route
+        if (finalAwaiting && this.conversationClient) {
+            await this.setAwaitingRoute()
+        }
+    }
+
+    /**
+     * Send message to router via gateway.
+     */
+    private send(
+        content: string,
+        done: boolean,
+        persist: boolean = true,
+        eventType?: string
+    ): void {
+        // Build headers (matching Python implementation)
+        const headers: Record<string, string> = {
+            conversationId: this.originalMessage.conversationId,
+            userId: this.originalMessage.userId,
+            from_: this.agentName,
+            to_: this.sendTo,
+            nextRoute: this.sendTo,
+        }
+
+        if (eventType) {
+            headers.eventType = eventType
+        }
+
+        // Include metadata, artifacts, and schema on first chunk (only once)
+        if (!this.firstChunkSent) {
+            this.firstChunkSent = true
+
+            if (this.messageMetadata) {
+                headers.messageMetadata = JSON.stringify(this.messageMetadata)
+            }
+
+            if (this.artifacts.length > 0) {
+                headers.artifacts = JSON.stringify(this.artifacts)
+            }
+
+            if (this.responseSchema) {
+                headers.responseSchema = JSON.stringify(this.responseSchema)
+            }
+        }
+
+        // Build body (matching Python implementation - includes persist)
+        const body: Record<string, unknown> = {
+            content,
+            done,
+            persist,
+        }
+
+        if (eventType) {
+            body.eventType = eventType
+        }
+
+        // Produce message via gateway
+        this.gatewayClient.produce(
+            'router.inbox',
+            this.originalMessage.conversationId,
+            headers,
+            body
+        )
+    }
+
+    /**
+     * Store response schema on conversation for form validation.
+     */
+    private async setPendingResponseSchema(): Promise<void> {
+        if (!this.conversationClient || !this.responseSchema) return
+
+        try {
+            await this.conversationClient.updateConversation(
+                this.originalMessage.conversationId,
+                { pendingResponseSchema: this.responseSchema } as never
+            )
+        } catch (error) {
+            console.error('Failed to set pending response schema:', error)
+        }
+    }
+
+    /**
+     * Set awaiting_route to this agent's name.
+     */
+    private async setAwaitingRoute(): Promise<void> {
+        if (!this.conversationClient) return
+
+        try {
+            await this.conversationClient.updateConversation(
+                this.originalMessage.conversationId,
+                { awaitingRoute: this.agentName } as never
+            )
+        } catch (error) {
+            console.error('Failed to set awaiting route:', error)
+        }
+    }
+
+    /**
+     * Get the accumulated streamed content.
+     */
+    getStreamedContent(): string {
+        return this.streamedContent
+    }
+
+    /**
+     * Support for async disposal (TypeScript 5.2+ "using" syntax).
+     */
+    async [Symbol.asyncDispose](): Promise<void> {
+        if (!this.finished) {
+            await this.finish()
+        }
+    }
+}