march-ai-sdk 0.3.0

package/dist/app-C_umwZXh.d.ts

@@ -0,0 +1,790 @@
+import { z } from 'zod';
+
+/**
+ * March Agent SDK - Shared Types
+ * Port of Python march_agent types
+ */
+
+interface KafkaMessage {
+    topic: string;
+    partition: number;
+    offset: number;
+    key: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    timestamp: number;
+}
+interface KafkaHeaders {
+    conversationId?: string;
+    userId?: string;
+    from_?: string;
+    to_?: string;
+    messageMetadata?: string;
+    messageSchema?: string;
+    attachment?: string;
+    [key: string]: string | undefined;
+}
+interface AgentRegistrationData {
+    id: string;
+    name: string;
+    about: string;
+    document: string;
+    representationName?: string;
+    baseUrl?: string;
+    metadata?: Record<string, unknown>;
+    relatedPages?: RelatedPage[];
+}
+interface RelatedPage {
+    name: string;
+    endpoint: string;
+}
+interface RegisterOptions {
+    name: string;
+    about: string;
+    document: string;
+    representationName?: string;
+    baseUrl?: string;
+    metadata?: Record<string, unknown>;
+    relatedPages?: RelatedPage[];
+}
+interface MessageHandler {
+    (message: any, sender: string): void | Promise<void>;
+}
+interface SenderFilterOptions {
+    senders?: string[];
+}
+interface StreamOptions {
+    persist?: boolean;
+    eventType?: string;
+}
+interface StreamerOptions {
+    awaiting?: boolean;
+    sendTo?: string;
+}
+declare const AttachmentInfoSchema: z.ZodObject<{
+    url: z.ZodString;
+    filename: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    fileType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    filename: string;
+    contentType: string;
+    size?: number | undefined;
+    fileType?: string | undefined;
+}, {
+    url: string;
+    filename: string;
+    contentType: string;
+    size?: number | undefined;
+    fileType?: string | undefined;
+}>;
+type AttachmentInfo = z.infer<typeof AttachmentInfoSchema>;
+interface ConversationMessageData {
+    id: string;
+    conversationId: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    from?: string;
+    to?: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface ProduceAck {
+    topic: string;
+    partition: number;
+    offset: number;
+    correlationId?: string;
+}
+interface AppOptions {
+    gatewayUrl: string;
+    apiKey: string;
+    heartbeatInterval?: number;
+    maxConcurrentTasks?: number;
+    errorMessageTemplate?: string;
+    secure?: boolean;
+}
+interface ConversationData {
+    id: string;
+    userId: string;
+    agentId?: string;
+    awaitingRoute?: string;
+    pendingResponseSchema?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface GetMessagesOptions {
+    role?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+interface MemoryMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp?: string;
+}
+interface MemorySearchResult {
+    content: string;
+    similarity: number;
+    metadata?: Record<string, unknown>;
+}
+interface UserSummary {
+    userId: string;
+    summary: string;
+    updatedAt: string;
+}
+
+/**
+ * March Agent SDK - Conversation Client
+ * Port of Python march_agent/conversation_client.py
+ */
+
+/**
+ * HTTP client for interacting with conversation-store API.
+ */
+declare class ConversationClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Get conversation metadata.
+     */
+    getConversation(conversationId: string): Promise<ConversationData>;
+    /**
+     * Get messages from a conversation.
+     */
+    getMessages(conversationId: string, options?: GetMessagesOptions): Promise<ConversationMessageData[]>;
+    /**
+     * Update conversation fields (PATCH).
+     */
+    updateConversation(conversationId: string, data: Partial<ConversationData>): Promise<ConversationData>;
+}
+
+/**
+ * March Agent SDK - Conversation Message
+ * Port of Python march_agent/conversation_message.py
+ */
+
+/**
+ * Represents a message from conversation history.
+ */
+declare class ConversationMessage {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly role: 'user' | 'assistant' | 'system';
+    readonly content: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly createdAt: Date;
+    readonly metadata?: Record<string, unknown>;
+    constructor(data: ConversationMessageData);
+    /**
+     * Create from API response
+     */
+    static fromApiResponse(data: Record<string, unknown>): ConversationMessage;
+    /**
+     * Check if this is a user message
+     */
+    isUser(): boolean;
+    /**
+     * Check if this is an assistant message
+     */
+    isAssistant(): boolean;
+}
+
+/**
+ * March Agent SDK - Conversation Helper
+ * Port of Python march_agent/conversation.py
+ */
+
+interface GetHistoryOptions {
+    limit?: number;
+    offset?: number;
+}
+interface GetAgentHistoryOptions extends GetHistoryOptions {
+    agentName?: string;
+}
+/**
+ * Helper class for accessing conversation history.
+ * Provides convenient methods for fetching messages.
+ */
+declare class Conversation {
+    readonly conversationId: string;
+    private readonly client;
+    private readonly agentName?;
+    constructor(conversationId: string, client: ConversationClient, agentName?: string);
+    /**
+     * Get all messages in the conversation.
+     */
+    getHistory(options?: GetHistoryOptions): Promise<ConversationMessage[]>;
+    /**
+     * Get messages to/from the current agent.
+     * Useful for getting conversation history for a specific agent.
+     */
+    getAgentHistory(options?: GetAgentHistoryOptions): Promise<ConversationMessage[]>;
+    /**
+     * Get the last N messages.
+     */
+    getLastMessages(count: number): Promise<ConversationMessage[]>;
+    /**
+     * Get user messages only.
+     */
+    getUserMessages(options?: GetHistoryOptions): Promise<ConversationMessage[]>;
+    /**
+     * Get assistant messages only.
+     */
+    getAssistantMessages(options?: GetHistoryOptions): Promise<ConversationMessage[]>;
+}
+
+/**
+ * March Agent SDK - Memory Client
+ * Port of Python march_agent/memory_client.py
+ */
+
+/**
+ * Async HTTP client for AI memory API.
+ * Provides long-term memory storage and semantic search.
+ */
+declare class MemoryClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Add messages to memory for a user/conversation.
+     */
+    addMessages(userId: string, conversationId: string, messages: MemoryMessage[]): Promise<{
+        added: number;
+    }>;
+    /**
+     * Search memory for relevant content.
+     */
+    search(userId: string, query: string, limit?: number): Promise<MemorySearchResult[]>;
+    /**
+     * Get user summary.
+     */
+    getUserSummary(userId: string): Promise<UserSummary | null>;
+    /**
+     * Clear user's memory.
+     */
+    clearMemory(userId: string): Promise<{
+        deleted: number;
+    }>;
+}
+
+/**
+ * March Agent SDK - Memory Helper
+ * Port of Python march_agent/memory.py
+ */
+
+/**
+ * Helper class for accessing long-term memory.
+ * Provides convenient methods for storing and searching memories.
+ */
+declare class Memory {
+    readonly userId: string;
+    readonly conversationId: string;
+    private readonly client;
+    constructor(userId: string, conversationId: string, client: MemoryClient);
+    /**
+     * Add messages to memory.
+     */
+    addMessages(messages: MemoryMessage[]): Promise<number>;
+    /**
+     * Add a single message to memory.
+     */
+    addMessage(role: 'user' | 'assistant', content: string): Promise<void>;
+    /**
+     * Search memory for relevant content.
+     */
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    /**
+     * Get user summary.
+     */
+    getSummary(): Promise<UserSummary | null>;
+    /**
+     * Clear all memories for this user.
+     */
+    clear(): Promise<number>;
+}
+
+/**
+ * March Agent SDK - Attachment Client
+ * Port of Python march_agent/attachment_client.py
+ */
+
+/**
+ * Create AttachmentInfo from API data
+ */
+declare function createAttachmentInfo(data: Record<string, unknown>): AttachmentInfo;
+/**
+ * HTTP client for downloading attachments.
+ */
+declare class AttachmentClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Build full URL for an attachment.
+     */
+    private buildUrl;
+    /**
+     * Download attachment as bytes (Buffer).
+     */
+    download(url: string): Promise<Buffer>;
+    /**
+     * Download attachment as base64 string.
+     * Useful for LLM vision APIs.
+     */
+    downloadAsBase64(url: string): Promise<string>;
+}
+
+/**
+ * March Agent SDK - Message
+ * Port of Python march_agent/message.py
+ */
+
+/**
+ * Represents an incoming message to the agent.
+ */
+declare 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?;
+    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;
+    });
+    /**
+     * Create Message from Kafka message data.
+     */
+    static fromKafkaMessage(body: Record<string, unknown>, headers: KafkaHeaders, options?: {
+        conversationClient?: ConversationClient;
+        memoryClient?: MemoryClient;
+        attachmentClient?: AttachmentClient;
+        agentName?: string;
+    }): Message;
+    /**
+     * Check if message has an attachment.
+     */
+    hasAttachment(): boolean;
+    /**
+     * Download attachment as bytes (Buffer).
+     *
+     * @throws Error if no attachment is available
+     */
+    getAttachmentBytes(): Promise<Buffer>;
+    /**
+     * Get attachment as base64 string (for LLM vision APIs).
+     *
+     * @throws Error if no attachment is available
+     */
+    getAttachmentBase64(): Promise<string>;
+}
+
+/**
+ * March Agent SDK - Gateway Client
+ * Port of Python march_agent/gateway_client.py
+ *
+ * gRPC client for communicating with the Agent Gateway.
+ */
+
+/**
+ * Client for communicating with the Agent Gateway.
+ * Provides gRPC bidirectional streaming for Kafka consume/produce.
+ */
+declare class GatewayClient {
+    private readonly gatewayUrl;
+    private readonly apiKey;
+    private readonly secure;
+    private client?;
+    private stream?;
+    private _connectionId?;
+    private messageQueue;
+    private pendingProduceAcks;
+    private pendingSubscribeAcks;
+    private messageHandlers;
+    private correlationCounter;
+    private connected;
+    constructor(gatewayUrl: string, apiKey: string, secure?: boolean);
+    /**
+     * HTTP URL for AI Inventory service via proxy.
+     */
+    get aiInventoryUrl(): string;
+    /**
+     * HTTP URL for Conversation Store service via proxy.
+     */
+    get conversationStoreUrl(): string;
+    /**
+     * HTTP URL for AI Memory service via proxy.
+     */
+    get aiMemoryUrl(): string;
+    /**
+     * HTTP URL for Attachment service via proxy.
+     */
+    get attachmentUrl(): string;
+    /**
+     * Register a handler for a topic.
+     */
+    registerHandler(topic: string, handler: (msg: KafkaMessage) => void): void;
+    /**
+     * Connect to the gateway and authenticate.
+     */
+    connect(agentNames: string[]): Promise<string[]>;
+    /**
+     * Handle incoming server messages.
+     */
+    private handleServerMessage;
+    /**
+     * Subscribe to an additional agent's topic.
+     */
+    subscribe(agentName: string): Promise<string>;
+    /**
+     * Unsubscribe from an agent's topic.
+     */
+    unsubscribe(agentName: string): void;
+    /**
+     * Produce a message to Kafka via the gateway.
+     */
+    produce(topic: string, key: string, headers: Record<string, string>, body: Record<string, unknown>, correlationId?: string): void;
+    /**
+     * Produce a message and wait for acknowledgment.
+     */
+    produceAndWait(topic: string, key: string, headers: Record<string, string>, body: Record<string, unknown>): Promise<ProduceAck>;
+    /**
+     * Consume a single message (polling from queue).
+     */
+    consumeOne(_timeout?: number): KafkaMessage | null;
+    /**
+     * Send a ping to the gateway.
+     */
+    ping(): void;
+    /**
+     * Make a sync POST request (used for registration).
+     */
+    httpPost(service: string, path: string, body: unknown): Promise<Response>;
+    /**
+     * Check if connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Close the gateway connection.
+     */
+    close(): void;
+}
+
+/**
+ * March Agent SDK - Artifact Types
+ * Port of Python march_agent/artifact.py
+ */
+
+/**
+ * Valid artifact types for message attachments
+ */
+declare const ArtifactTypeSchema: z.ZodEnum<["document", "image", "iframe", "video", "audio", "code", "link", "file"]>;
+type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
+/**
+ * Schema for artifact validation
+ */
+declare const ArtifactSchema: z.ZodObject<{
+    url: z.ZodString;
+    type: z.ZodEnum<["document", "image", "iframe", "video", "audio", "code", "link", "file"]>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    type: "code" | "document" | "image" | "iframe" | "video" | "audio" | "link" | "file";
+    metadata?: Record<string, unknown> | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+}, {
+    url: string;
+    type: "code" | "document" | "image" | "iframe" | "video" | "audio" | "link" | "file";
+    metadata?: Record<string, unknown> | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+}>;
+type Artifact = z.infer<typeof ArtifactSchema>;
+/**
+ * Input type for adding artifacts (without strict validation)
+ */
+interface ArtifactInput {
+    url: string;
+    type: ArtifactType | string;
+    title?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Convert artifact input to validated artifact
+ */
+declare function toArtifact(input: ArtifactInput): Artifact;
+
+/**
+ * March Agent SDK - Streamer
+ * Port of Python march_agent/streamer.py
+ */
+
+/**
+ * Handles streaming responses back to the conversation via the gateway.
+ */
+declare class Streamer {
+    private readonly agentName;
+    private readonly originalMessage;
+    private readonly gatewayClient;
+    private readonly conversationClient?;
+    private readonly sendTo;
+    private awaiting;
+    private responseSchema?;
+    private messageMetadata?;
+    private artifacts;
+    private streamedContent;
+    private firstChunkSent;
+    private finished;
+    constructor(options: {
+        agentName: string;
+        originalMessage: Message;
+        gatewayClient: GatewayClient;
+        conversationClient?: ConversationClient;
+        awaiting?: boolean;
+        sendTo?: string;
+    });
+    /**
+     * Set response schema for form rendering (fluent API).
+     */
+    setResponseSchema(schema: Record<string, unknown>): this;
+    /**
+     * Set message metadata (fluent API).
+     */
+    setMessageMetadata(metadata: Record<string, unknown>): this;
+    /**
+     * Add an artifact to the message (fluent API).
+     */
+    addArtifact(artifact: ArtifactInput): this;
+    /**
+     * Set all artifacts at once (replaces any existing).
+     */
+    setArtifacts(artifacts: ArtifactInput[]): this;
+    /**
+     * Stream a content chunk.
+     */
+    stream(content: string, options?: StreamOptions): void;
+    /**
+     * Alias for stream() - write a content chunk.
+     */
+    write(content: string, persist?: boolean): void;
+    /**
+     * Finish streaming with done=true signal.
+     */
+    finish(awaitingOverride?: boolean): Promise<void>;
+    /**
+     * Send message to router via gateway.
+     */
+    private send;
+    /**
+     * Store response schema on conversation for form validation.
+     */
+    private setPendingResponseSchema;
+    /**
+     * Set awaiting_route to this agent's name.
+     */
+    private setAwaitingRoute;
+    /**
+     * Get the accumulated streamed content.
+     */
+    getStreamedContent(): string;
+    /**
+     * Support for async disposal (TypeScript 5.2+ "using" syntax).
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * March Agent SDK - Agent
+ * Port of Python march_agent/agent.py
+ */
+
+/**
+ * Filter for matching message senders.
+ */
+declare class SenderFilter {
+    private readonly _include;
+    private readonly _exclude;
+    readonly matchAll: boolean;
+    constructor(senders?: string[]);
+    /**
+     * Get included senders as an array (for compatibility with Python tests).
+     */
+    get include(): string[];
+    /**
+     * Get excluded senders as an array (for compatibility with Python tests).
+     */
+    get exclude(): string[];
+    /**
+     * Check if sender matches this filter.
+     */
+    matches(sender: string): boolean;
+}
+/**
+ * Core agent class that handles messaging via the Agent Gateway.
+ */
+declare class Agent {
+    readonly name: string;
+    readonly agentData: AgentRegistrationData;
+    sendErrorResponses: boolean;
+    errorMessageTemplate: string;
+    private readonly gatewayClient;
+    private readonly conversationClient?;
+    private readonly memoryClient?;
+    private readonly attachmentClient?;
+    private readonly heartbeatInterval;
+    private messageHandlers;
+    private heartbeatManager?;
+    private initialized;
+    private running;
+    constructor(options: {
+        name: string;
+        gatewayClient: GatewayClient;
+        agentData: AgentRegistrationData;
+        heartbeatInterval?: number;
+        conversationClient?: ConversationClient;
+        memoryClient?: MemoryClient;
+        attachmentClient?: AttachmentClient;
+        errorMessageTemplate?: string;
+    });
+    /**
+     * 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;
+    /**
+     * Initialize agent after gateway connection is established.
+     */
+    initializeWithGateway(): void;
+    /**
+     * Get sender from message headers.
+     */
+    private getSender;
+    /**
+     * Find first handler that matches the sender.
+     */
+    private findMatchingHandler;
+    /**
+     * Handle incoming Kafka message.
+     */
+    private handleKafkaMessage;
+    /**
+     * Async message handling with error recovery.
+     */
+    private handleMessageAsync;
+    /**
+     * Send error response to user when handler fails.
+     */
+    private sendErrorResponse;
+    /**
+     * Create a new Streamer for streaming responses.
+     */
+    streamer(message: Message, options?: StreamerOptions): Streamer;
+    /**
+     * Mark agent as ready to consume messages.
+     */
+    startConsuming(): void;
+    /**
+     * Shutdown agent gracefully.
+     */
+    shutdown(): void;
+    /**
+     * Check if agent is running.
+     */
+    isRunning(): boolean;
+}
+
+/**
+ * March Agent SDK - Main Application
+ * Port of Python march_agent/app.py
+ */
+
+/**
+ * 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()
+ * ```
+ */
+declare class MarchAgentApp {
+    readonly gatewayClient: GatewayClient;
+    readonly conversationClient: ConversationClient;
+    readonly memoryClient: MemoryClient;
+    readonly attachmentClient: AttachmentClient;
+    private readonly heartbeatInterval;
+    private readonly _maxConcurrentTasks;
+    private readonly errorMessageTemplate;
+    private agents;
+    private running;
+    private shutdownRequested;
+    constructor(options: AppOptions);
+    /**
+     * Register an agent with the backend.
+     */
+    registerMe(options: RegisterOptions): Promise<Agent>;
+    /**
+     * Register agent with AI Inventory service.
+     */
+    private registerWithInventory;
+    /**
+     * Start all registered agents and block until shutdown.
+     */
+    run(): Promise<void>;
+    /**
+     * Main consume loop.
+     */
+    private consumeLoop;
+    /**
+     * Shutdown all agents gracefully.
+     */
+    shutdown(): void;
+}
+
+export { Agent as A, Conversation as C, GatewayClient as G, type KafkaHeaders as K, MarchAgentApp as M, type ProduceAck as P, type RegisterOptions as R, SenderFilter as S, type UserSummary as U, type AgentRegistrationData as a, type AppOptions as b, type Artifact as c, type ArtifactInput as d, type ArtifactType as e, AttachmentClient as f, type AttachmentInfo as g, ConversationClient as h, type ConversationData as i, ConversationMessage as j, type GetMessagesOptions as k, type KafkaMessage as l, Memory as m, MemoryClient as n, type MemoryMessage as o, type MemorySearchResult as p, Message as q, type MessageHandler as r, type SenderFilterOptions as s, type StreamOptions as t, Streamer as u, type StreamerOptions as v, createAttachmentInfo as w, toArtifact as x };