march-ai-sdk 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "march-ai-sdk",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "TypeScript SDK for building AI agents in the March AI platform",
     "type": "module",
     "main": "./dist/index.js",

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * March Agent SDK - TypeScript framework for building AI agents
- * 
+ *
  * @packageDocumentation
  */
 
@@ -14,12 +14,26 @@ export { Memory } from './memory.js'
 
 // Message types
 export { ConversationMessage } from './conversation-message.js'
-export { type Artifact, type ArtifactType, type ArtifactInput, toArtifact } from './artifact.js'
+
+// Structural streaming components
+export {
+    StructuralStreamer,
+    Artifact,
+    Surface,
+    TextBlock,
+    Stepper,
+} from './structural/index.js'
 
 // Clients
 export { GatewayClient } from './gateway-client.js'
 export { ConversationClient } from './conversation-client.js'
-export { CheckpointClient, type CheckpointConfig, type CheckpointData, type CheckpointMetadata, type CheckpointTuple } from './checkpoint-client.js'
+export {
+    CheckpointClient,
+    type CheckpointConfig,
+    type CheckpointData,
+    type CheckpointMetadata,
+    type CheckpointTuple,
+} from './checkpoint-client.js'
 export { AgentStateClient, type AgentStateResponse } from './agent-state-client.js'
 export { MemoryClient } from './memory-client.js'
 export { AttachmentClient, createAttachmentInfo, type AttachmentInfo } from './attachment-client.js'
@@ -67,4 +81,4 @@ export {
 } from './exceptions.js'
 
 // Version
-export const VERSION = '0.3.0'
+export const VERSION = '0.4.0'

package/src/streamer.ts

@@ -6,8 +6,7 @@
 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 { StructuralStreamer } from './structural/base.js'
 import type { StreamOptions } from './types.js'
 
 /**
@@ -23,9 +22,7 @@ export class Streamer {
 
     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: {
@@ -61,19 +58,22 @@ export class Streamer {
     }
 
     /**
-     * Add an artifact to the message (fluent API).
+     * Bind a structural streamer to this streamer for event sending.
+     *
+     * Returns the structural object itself with streaming capability enabled.
+     *
+     * @param structural - StructuralStreamer instance (Artifact, Surface, etc.)
+     * @returns The same structural object, now bound to this streamer
+     *
+     * @example
+     * ```typescript
+     * const artifact = new Artifact()
+     * s.streamBy(artifact).generating("Creating...")
+     * s.streamBy(artifact).done({ url: "...", type: "image" })
+     * ```
      */
-    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
+    streamBy<T extends StructuralStreamer>(structural: T): T {
+        return structural._bindStreamer(this)
     }
 
     /**
@@ -91,7 +91,7 @@ export class Streamer {
             this.streamedContent += content
         }
 
-        this.send(content, false, persist, eventType)
+        this._send(content, false, persist, eventType)
     }
 
     /**
@@ -120,7 +120,7 @@ export class Streamer {
         }
 
         // Send final done message
-        this.send('', true, false)
+        this._send('', true, false)
 
         // Set pending response schema on conversation
         if (this.responseSchema && this.conversationClient) {
@@ -135,8 +135,9 @@ export class Streamer {
 
     /**
      * Send message to router via gateway.
+     * This method is used internally and by structural streamers.
      */
-    private send(
+    _send(
         content: string,
         done: boolean,
         persist: boolean = true,
@@ -155,18 +156,12 @@ export class Streamer {
             headers.eventType = eventType
         }
 
-        // Include metadata, artifacts, and schema on first chunk (only once)
-        if (!this.firstChunkSent) {
-            this.firstChunkSent = true
-
+        // Include metadata and schema on first chunk (only once)
+        if (this.streamedContent.length === 0 && !this.finished) {
             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)
             }

package/src/structural/artifact.ts

@@ -0,0 +1,97 @@
+/**
+ * March Agent SDK - Artifact Structural Streamer
+ * Port of Python march_agent/structural/artifact.py
+ *
+ * Artifact structural streamer for file/image/iframe artifacts.
+ */
+
+import { StructuralStreamer, generateShortId } from './base.js'
+
+/**
+ * Manages artifact lifecycle: generating -> done.
+ *
+ * Artifacts are files, images, iframes that are generated and displayed.
+ * Artifact data is persisted to database on done().
+ *
+ * @example
+ * ```typescript
+ * const artifact = new Artifact()  // ID auto-generated
+ * s.streamBy(artifact).generating("Creating chart...", 0.5)
+ * s.streamBy(artifact).done({
+ *     url: "https://example.com/chart.png",
+ *     type: "image",
+ *     title: "Sales Chart"
+ * })
+ * ```
+ */
+export class Artifact extends StructuralStreamer {
+    protected _generateId(): string {
+        return `artifact-${generateShortId()}`
+    }
+
+    getEventTypePrefix(): string {
+        return 'artifact'
+    }
+
+    /**
+     * Signal artifact is being generated.
+     *
+     * @param message - Status message (e.g., "Creating chart...")
+     * @param progress - Progress value 0.0-1.0
+     * @returns this for method chaining
+     */
+    generating(message?: string, progress?: number): this {
+        const data: Record<string, unknown> = {}
+        if (message !== undefined) {
+            data.message = message
+        }
+        if (progress !== undefined) {
+            data.progress = progress
+        }
+        return this._sendEvent('generating', data)
+    }
+
+    /**
+     * Signal artifact is complete and persist to database.
+     *
+     * @param options - Artifact completion options
+     * @param options.url - URL to artifact
+     * @param options.type - Artifact type (image, iframe, document, video, audio, code, link, file)
+     * @param options.title - Display title
+     * @param options.description - Optional description
+     * @param options.metadata - Additional metadata (size, mimeType, dimensions, etc.)
+     * @returns this for method chaining
+     */
+    done(options: {
+        url: string
+        type: string
+        title?: string
+        description?: string
+        metadata?: Record<string, unknown>
+    }): this {
+        const data: Record<string, unknown> = {
+            url: options.url,
+            type: options.type,
+        }
+        if (options.title) {
+            data.title = options.title
+        }
+        if (options.description) {
+            data.description = options.description
+        }
+        if (options.metadata) {
+            data.metadata = options.metadata
+        }
+        return this._sendEvent('done', data)
+    }
+
+    /**
+     * Signal artifact generation failed.
+     *
+     * @param message - Error message
+     * @returns this for method chaining
+     */
+    error(message: string): this {
+        return this._sendEvent('error', { message })
+    }
+}

package/src/structural/base.ts

@@ -0,0 +1,83 @@
+/**
+ * March Agent SDK - Structural Streaming Base
+ * Port of Python march_agent/structural/base.py
+ *
+ * Base class for structural streaming objects.
+ */
+
+import type { Streamer } from '../streamer.js'
+
+/**
+ * Abstract base class for structural streaming objects.
+ *
+ * Structural streamers generate events but don't hold streaming state.
+ * The Streamer binds to them via streamBy() to enable streaming.
+ */
+export abstract class StructuralStreamer {
+    readonly id: string
+    protected _streamer?: Streamer
+
+    constructor(id?: string) {
+        this.id = id ?? this._generateId()
+    }
+
+    /**
+     * Generate a unique ID for this streamer type.
+     */
+    protected abstract _generateId(): string
+
+    /**
+     * Get the event type prefix (e.g., 'artifact', 'text_block').
+     */
+    abstract getEventTypePrefix(): string
+
+    /**
+     * Bind this structural streamer to a Streamer instance.
+     * Called by Streamer.streamBy(). Returns self for chaining.
+     */
+    _bindStreamer(streamer: Streamer): this {
+        this._streamer = streamer
+        return this
+    }
+
+    /**
+     * Send an event through the bound streamer.
+     *
+     * Creates event payload and sends via streamer._send().
+     * Returns self for method chaining.
+     */
+    protected _sendEvent(action: string, data: Record<string, unknown> = {}): this {
+        if (!this._streamer) {
+            throw new Error(
+                `${this.constructor.name} not bound to a Streamer. ` +
+                `Call streamer.streamBy() first.`
+            )
+        }
+
+        // Build event body
+        const body = { id: this.id, ...data }
+
+        // Build event type
+        const eventType = `${this.getEventTypePrefix()}:${action}`
+
+        // Send through streamer using existing _send() method
+        // content = stringified JSON body
+        // eventType = structural event type
+        // persist = false (structural events not persisted as content)
+        this._streamer._send(
+            JSON.stringify(body),
+            false, // done
+            false, // persist
+            eventType
+        )
+
+        return this
+    }
+}
+
+/**
+ * Generate a short random hex string for IDs.
+ */
+export function generateShortId(): string {
+    return Math.random().toString(16).slice(2, 10)
+}

package/src/structural/index.ts

@@ -0,0 +1,12 @@
+/**
+ * March Agent SDK - Structural Streaming Module
+ * Port of Python march_agent/structural/__init__.py
+ *
+ * Exports all structural streaming components.
+ */
+
+export { StructuralStreamer, generateShortId } from './base.js'
+export { Artifact } from './artifact.js'
+export { Surface } from './surface.js'
+export { TextBlock } from './text-block.js'
+export { Stepper } from './stepper.js'

package/src/structural/stepper.ts

@@ -0,0 +1,131 @@
+/**
+ * March Agent SDK - Stepper Structural Streamer
+ * Port of Python march_agent/structural/stepper.py
+ *
+ * Stepper structural streamer for multi-step progress indicators.
+ */
+
+import { StructuralStreamer, generateShortId } from './base.js'
+
+/**
+ * Manages multi-step progress indicator.
+ *
+ * Stepper events are NOT persisted to database.
+ * IDs are auto-generated - no need to provide them manually.
+ *
+ * @example
+ * ```typescript
+ * const stepper = new Stepper({ steps: ["Fetch", "Process", "Report"] })  // ID auto-generated
+ * s.streamBy(stepper).startStep(0)
+ * s.streamBy(stepper).completeStep(0)
+ * s.streamBy(stepper).startStep(1)
+ * s.streamBy(stepper).addStep("Verify")  // Dynamic step
+ * s.streamBy(stepper).completeStep(1)
+ * s.streamBy(stepper).done()
+ * ```
+ */
+export class Stepper extends StructuralStreamer {
+    readonly steps: string[]
+    private _initialized: boolean = false
+
+    constructor(options?: { id?: string; steps?: string[] }) {
+        super(options?.id)
+        this.steps = options?.steps ?? []
+    }
+
+    protected _generateId(): string {
+        return `stepper-${generateShortId()}`
+    }
+
+    getEventTypePrefix(): string {
+        return 'stepper'
+    }
+
+    /**
+     * Send initialization event with steps if not already sent.
+     * This is automatically called before any other stepper event.
+     */
+    private _ensureInitialized(): this {
+        if (!this._initialized && this.steps.length > 0) {
+            this._sendEvent('init', { steps: this.steps })
+            this._initialized = true
+        }
+        return this
+    }
+
+    /**
+     * Mark step as in progress.
+     *
+     * @param index - Step index to start
+     * @returns this for method chaining
+     */
+    startStep(index: number): this {
+        this._ensureInitialized()
+        return this._sendEvent('start_step', { index })
+    }
+
+    /**
+     * Mark step as complete.
+     *
+     * @param index - Step index to complete
+     * @returns this for method chaining
+     */
+    completeStep(index: number): this {
+        this._ensureInitialized()
+        return this._sendEvent('complete_step', { index })
+    }
+
+    /**
+     * Mark step as failed.
+     *
+     * @param index - Step index that failed
+     * @param error - Optional error message
+     * @returns this for method chaining
+     */
+    failStep(index: number, error?: string): this {
+        this._ensureInitialized()
+        const data: Record<string, unknown> = { index }
+        if (error) {
+            data.error = error
+        }
+        return this._sendEvent('fail_step', data)
+    }
+
+    /**
+     * Add a new step dynamically.
+     *
+     * @param label - Step label
+     * @param index - Optional position to insert at
+     * @returns this for method chaining
+     */
+    addStep(label: string, index?: number): this {
+        this._ensureInitialized()
+        const data: Record<string, unknown> = { label }
+        if (index !== undefined) {
+            data.index = index
+        }
+        return this._sendEvent('add_step', data)
+    }
+
+    /**
+     * Update step label.
+     *
+     * @param index - Step index to update
+     * @param label - New label
+     * @returns this for method chaining
+     */
+    updateStepLabel(index: number, label: string): this {
+        this._ensureInitialized()
+        return this._sendEvent('update_step_label', { index, label })
+    }
+
+    /**
+     * Mark stepper as complete (all steps finished).
+     *
+     * @returns this for method chaining
+     */
+    done(): this {
+        this._ensureInitialized()
+        return this._sendEvent('done')
+    }
+}

package/src/structural/surface.ts

@@ -0,0 +1,93 @@
+/**
+ * March Agent SDK - Surface Structural Streamer
+ * Port of Python march_agent/structural/surface.py
+ *
+ * Surface structural streamer for embedded interactive components.
+ */
+
+import { StructuralStreamer, generateShortId } from './base.js'
+
+/**
+ * Manages embedded surface lifecycle (similar to Artifact).
+ *
+ * Surfaces are embedded interactive components (iframes, embeds).
+ * Surface data is persisted to database as artifacts with surface type.
+ *
+ * @example
+ * ```typescript
+ * const surface = new Surface()
+ * s.streamBy(surface).generating("Loading calendar...")
+ * s.streamBy(surface).done({ url: "https://cal.com/embed", type: "iframe" })
+ * ```
+ */
+export class Surface extends StructuralStreamer {
+    protected _generateId(): string {
+        return `surface-${generateShortId()}`
+    }
+
+    getEventTypePrefix(): string {
+        return 'surface'
+    }
+
+    /**
+     * Signal surface is loading.
+     *
+     * @param message - Status message (e.g., "Loading calendar...")
+     * @param progress - Progress value 0.0-1.0
+     * @returns this for method chaining
+     */
+    generating(message?: string, progress?: number): this {
+        const data: Record<string, unknown> = {}
+        if (message !== undefined) {
+            data.message = message
+        }
+        if (progress !== undefined) {
+            data.progress = progress
+        }
+        return this._sendEvent('generating', data)
+    }
+
+    /**
+     * Signal surface is ready and persist to database.
+     *
+     * @param options - Surface completion options
+     * @param options.url - URL to surface
+     * @param options.type - Surface type (default: iframe)
+     * @param options.title - Display title
+     * @param options.description - Optional description
+     * @param options.metadata - Additional metadata
+     * @returns this for method chaining
+     */
+    done(options: {
+        url: string
+        type?: string
+        title?: string
+        description?: string
+        metadata?: Record<string, unknown>
+    }): this {
+        const data: Record<string, unknown> = {
+            url: options.url,
+            type: options.type ?? 'iframe',
+        }
+        if (options.title) {
+            data.title = options.title
+        }
+        if (options.description) {
+            data.description = options.description
+        }
+        if (options.metadata) {
+            data.metadata = options.metadata
+        }
+        return this._sendEvent('done', data)
+    }
+
+    /**
+     * Signal surface loading failed.
+     *
+     * @param message - Error message
+     * @returns this for method chaining
+     */
+    error(message: string): this {
+        return this._sendEvent('error', { message })
+    }
+}

package/src/structural/text-block.ts

@@ -0,0 +1,102 @@
+/**
+ * March Agent SDK - TextBlock Structural Streamer
+ * Port of Python march_agent/structural/text_block.py
+ *
+ * TextBlock structural streamer for collapsible text content.
+ */
+
+import { StructuralStreamer, generateShortId } from './base.js'
+
+/**
+ * Manages collapsible text block with title and body.
+ *
+ * Both title and body support streaming (append) and update (replace).
+ * TextBlock events are NOT persisted to database.
+ *
+ * @example
+ * ```typescript
+ * const block = new TextBlock()  // ID auto-generated
+ * s.streamBy(block).setVariant("thinking")
+ * s.streamBy(block).streamTitle("Deep ")
+ * s.streamBy(block).streamTitle("Analysis...")
+ * s.streamBy(block).streamBody("Step 1: Check patterns\n")
+ * s.streamBy(block).streamBody("Step 2: Validate\n")
+ * s.streamBy(block).updateTitle("Analysis Complete")
+ * s.streamBy(block).done()
+ * ```
+ */
+export class TextBlock extends StructuralStreamer {
+    readonly initialTitle?: string
+
+    constructor(options?: { id?: string; title?: string }) {
+        super(options?.id)
+        this.initialTitle = options?.title
+    }
+
+    protected _generateId(): string {
+        return `text_block-${generateShortId()}`
+    }
+
+    getEventTypePrefix(): string {
+        return 'text_block'
+    }
+
+    /**
+     * Stream title content (appends to existing).
+     *
+     * @param content - Content to append to title
+     * @returns this for method chaining
+     */
+    streamTitle(content: string): this {
+        return this._sendEvent('stream_title', { content })
+    }
+
+    /**
+     * Stream body content (appends to existing).
+     *
+     * @param content - Content to append to body
+     * @returns this for method chaining
+     */
+    streamBody(content: string): this {
+        return this._sendEvent('stream_body', { content })
+    }
+
+    /**
+     * Replace entire title.
+     *
+     * @param title - New title (replaces existing)
+     * @returns this for method chaining
+     */
+    updateTitle(title: string): this {
+        return this._sendEvent('update_title', { title })
+    }
+
+    /**
+     * Replace entire body.
+     *
+     * @param body - New body (replaces existing)
+     * @returns this for method chaining
+     */
+    updateBody(body: string): this {
+        return this._sendEvent('update_body', { body })
+    }
+
+    /**
+     * Set visual variant.
+     *
+     * @param variant - Visual style (thinking, note, warning, error, success)
+     * @returns this for method chaining
+     */
+    setVariant(variant: 'thinking' | 'note' | 'warning' | 'error' | 'success' | string): this {
+        return this._sendEvent('set_variant', { variant })
+    }
+
+    /**
+     * Mark text block as complete.
+     *
+     * @returns this for method chaining
+     */
+    done(): this {
+        return this._sendEvent('done')
+    }
+}