march-ai-sdk 0.3.0 → 0.4.0

package/README.md

@@ -339,13 +339,6 @@ agent.onMessage(async (message, sender) => {
         }
     })
 
-    // Add artifacts
-    streamer2.addArtifact({
-        url: '/dashboard/123',
-        type: 'iframe',
-        title: 'Dashboard',
-    })
-
     // Set message metadata
     streamer2.setMessageMetadata({
         model: 'gpt-4o',
@@ -365,8 +358,105 @@ agent.onMessage(async (message, sender) => {
 | `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 |
+| `streamBy(structural)` | Bind a structural streamer for artifacts, surfaces, etc. |
+
+### Structural Streaming
+
+The SDK provides structural streaming components for rich content like artifacts, surfaces, text blocks, and steppers.
+
+#### Artifact
+
+Stream file artifacts (images, documents, iframes) with progress indication:
+
+```typescript
+import { Artifact } from 'march-ai-sdk'
+
+agent.onMessage(async (message, sender) => {
+    const streamer = agent.streamer(message)
+    
+    // Create an artifact
+    const artifact = new Artifact()
+    
+    // Signal generation started (optional)
+    streamer.streamBy(artifact).generating('Creating chart...', 0.5)
+    
+    // ... do work ...
+    
+    // Signal completion with artifact details
+    streamer.streamBy(artifact).done({
+        url: 'https://example.com/chart.png',
+        type: 'image',
+        title: 'Sales Chart',
+        description: 'Q4 2024 sales data',
+        metadata: { size: 1024, mimeType: 'image/png' }
+    })
+    
+    streamer.stream('Here is your chart!')
+    await streamer.finish()
+})
+```
+
+#### Surface
+
+Stream embedded interactive components (iframes, embeds):
+
+```typescript
+import { Surface } from 'march-ai-sdk'
+
+const surface = new Surface()
+streamer.streamBy(surface).generating('Loading calendar...')
+streamer.streamBy(surface).done({
+    url: 'https://cal.com/embed/user',
+    type: 'iframe',  // default
+    title: 'Schedule a Meeting'
+})
+```
+
+#### TextBlock
+
+Stream collapsible text content with titles and variants:
+
+```typescript
+import { TextBlock } from 'march-ai-sdk'
+
+const block = new TextBlock()
+streamer.streamBy(block).setVariant('thinking')
+streamer.streamBy(block).streamTitle('Analyzing...')
+streamer.streamBy(block).streamBody('Step 1: Checking data\n')
+streamer.streamBy(block).streamBody('Step 2: Processing\n')
+streamer.streamBy(block).updateTitle('Analysis Complete')
+streamer.streamBy(block).done()
+```
+
+Variants: `thinking`, `note`, `warning`, `error`, `success`
+
+#### Stepper
+
+Stream multi-step progress indicators:
+
+```typescript
+import { Stepper } from 'march-ai-sdk'
+
+const stepper = new Stepper({ steps: ['Fetch Data', 'Process', 'Generate Report'] })
+streamer.streamBy(stepper).startStep(0)
+// ... do work ...
+streamer.streamBy(stepper).completeStep(0)
+streamer.streamBy(stepper).startStep(1)
+streamer.streamBy(stepper).addStep('Verify')  // Add dynamic step
+streamer.streamBy(stepper).completeStep(1)
+streamer.streamBy(stepper).startStep(2)
+streamer.streamBy(stepper).completeStep(2)
+streamer.streamBy(stepper).done()
+```
+
+#### Structural Streaming Components
+
+| Component | Purpose | Key Methods |
+|-----------|---------|-------------|
+| `Artifact` | Files, images, documents | `generating()`, `done()`, `error()` |
+| `Surface` | Embedded iframes/widgets | `generating()`, `done()`, `error()` |
+| `TextBlock` | Collapsible text content | `streamTitle()`, `streamBody()`, `setVariant()`, `done()` |
+| `Stepper` | Multi-step progress | `startStep()`, `completeStep()`, `failStep()`, `addStep()`, `done()` |
 
 ## Extensions
 
@@ -612,6 +702,13 @@ ai-ts-framework/
 │   ├── api-paths.ts          # API endpoint configuration
 │   ├── types.ts              # TypeScript types
 │   ├── exceptions.ts         # Custom exceptions
+│   ├── structural/           # Structural streaming components
+│   │   ├── index.ts          # Structural exports
+│   │   ├── base.ts           # StructuralStreamer base class
+│   │   ├── artifact.ts       # Artifact component
+│   │   ├── surface.ts        # Surface component
+│   │   ├── text-block.ts     # TextBlock component
+│   │   └── stepper.ts        # Stepper component
 │   ├── proto/
 │   │   └── gateway.proto     # gRPC protocol definition
 │   └── extensions/
@@ -623,7 +720,8 @@ ai-ts-framework/
 │   ├── app.test.ts
 │   ├── checkpoint-client.test.ts
 │   ├── message.test.ts
-│   └── streamer.test.ts
+│   ├── streamer.test.ts
+│   └── structural-streaming.test.ts
 ├── tsup.config.ts            # Build configuration
 ├── vitest.config.ts          # Test configuration
 ├── tsconfig.json
@@ -688,6 +786,13 @@ import type {
     Agent,
     MarchAgentApp,
 
+    // Structural streaming
+    StructuralStreamer,
+    Artifact,
+    Surface,
+    TextBlock,
+    Stepper,
+
     // Options
     AppOptions,
     RegisterOptions,

package/dist/{app-C_umwZXh.d.ts → app-Cf_umb8u.d.ts}

@@ -491,52 +491,43 @@ declare class GatewayClient {
 }
 
 /**
- * March Agent SDK - Artifact Types
- * Port of Python march_agent/artifact.py
+ * March Agent SDK - Structural Streaming Base
+ * Port of Python march_agent/structural/base.py
+ *
+ * Base class for structural streaming objects.
  */
 
 /**
- * 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)
+ * 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.
  */
-interface ArtifactInput {
-    url: string;
-    type: ArtifactType | string;
-    title?: string;
-    description?: string;
-    metadata?: Record<string, unknown>;
+declare abstract class StructuralStreamer {
+    readonly id: string;
+    protected _streamer?: Streamer;
+    constructor(id?: string);
+    /**
+     * 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;
+    /**
+     * 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;
 }
-/**
- * Convert artifact input to validated artifact
- */
-declare function toArtifact(input: ArtifactInput): Artifact;
 
 /**
  * March Agent SDK - Streamer
@@ -555,9 +546,7 @@ declare class Streamer {
     private awaiting;
     private responseSchema?;
     private messageMetadata?;
-    private artifacts;
     private streamedContent;
-    private firstChunkSent;
     private finished;
     constructor(options: {
         agentName: string;
@@ -576,13 +565,21 @@ declare class Streamer {
      */
     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).
+     * 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" })
+     * ```
      */
-    setArtifacts(artifacts: ArtifactInput[]): this;
+    streamBy<T extends StructuralStreamer>(structural: T): T;
     /**
      * Stream a content chunk.
      */
@@ -597,8 +594,9 @@ declare class Streamer {
     finish(awaitingOverride?: boolean): Promise<void>;
     /**
      * Send message to router via gateway.
+     * This method is used internally and by structural streamers.
      */
-    private send;
+    _send(content: string, done: boolean, persist?: boolean, eventType?: string): void;
     /**
      * Store response schema on conversation for form validation.
      */
@@ -787,4 +785,4 @@ declare class MarchAgentApp {
     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 };
+export { Agent as A, Conversation as C, GatewayClient as G, type KafkaMessage as K, MarchAgentApp as M, type ProduceAck as P, type RegisterOptions as R, StructuralStreamer as S, type UserSummary as U, SenderFilter as a, Message as b, Streamer as c, Memory as d, ConversationMessage as e, ConversationClient as f, MemoryClient as g, AttachmentClient as h, createAttachmentInfo as i, type AttachmentInfo as j, type KafkaHeaders as k, type AgentRegistrationData as l, type MessageHandler as m, type SenderFilterOptions as n, type StreamOptions as o, type StreamerOptions as p, type AppOptions as q, type ConversationData as r, type GetMessagesOptions as s, type MemoryMessage as t, type MemorySearchResult as u };

package/dist/extensions/langgraph.d.ts

@@ -1,4 +1,4 @@
-import { M as MarchAgentApp } from '../app-C_umwZXh.js';
+import { M as MarchAgentApp } from '../app-Cf_umb8u.js';
 import 'zod';
 
 /**

package/dist/extensions/vercel-ai.d.ts

@@ -1,4 +1,4 @@
-import { M as MarchAgentApp } from '../app-C_umwZXh.js';
+import { M as MarchAgentApp } from '../app-Cf_umb8u.js';
 import 'zod';
 
 /**

package/dist/index.d.ts

@@ -1,7 +1,287 @@
-import { G as GatewayClient } from './app-C_umwZXh.js';
-export { A as Agent, a as AgentRegistrationData, b as AppOptions, c as Artifact, d as ArtifactInput, e as ArtifactType, f as AttachmentClient, g as AttachmentInfo, C as Conversation, h as ConversationClient, i as ConversationData, j as ConversationMessage, k as GetMessagesOptions, K as KafkaHeaders, l as KafkaMessage, M as MarchAgentApp, m as Memory, n as MemoryClient, o as MemoryMessage, p as MemorySearchResult, q as Message, r as MessageHandler, P as ProduceAck, R as RegisterOptions, S as SenderFilter, s as SenderFilterOptions, t as StreamOptions, u as Streamer, v as StreamerOptions, U as UserSummary, w as createAttachmentInfo, x as toArtifact } from './app-C_umwZXh.js';
+import { S as StructuralStreamer, G as GatewayClient } from './app-Cf_umb8u.js';
+export { A as Agent, l as AgentRegistrationData, q as AppOptions, h as AttachmentClient, j as AttachmentInfo, C as Conversation, f as ConversationClient, r as ConversationData, e as ConversationMessage, s as GetMessagesOptions, k as KafkaHeaders, K as KafkaMessage, M as MarchAgentApp, d as Memory, g as MemoryClient, t as MemoryMessage, u as MemorySearchResult, b as Message, m as MessageHandler, P as ProduceAck, R as RegisterOptions, a as SenderFilter, n as SenderFilterOptions, o as StreamOptions, c as Streamer, p as StreamerOptions, U as UserSummary, i as createAttachmentInfo } from './app-Cf_umb8u.js';
 import 'zod';
 
+/**
+ * March Agent SDK - Artifact Structural Streamer
+ * Port of Python march_agent/structural/artifact.py
+ *
+ * Artifact structural streamer for file/image/iframe artifacts.
+ */
+
+/**
+ * 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"
+ * })
+ * ```
+ */
+declare class Artifact extends StructuralStreamer {
+    protected _generateId(): string;
+    getEventTypePrefix(): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Signal artifact generation failed.
+     *
+     * @param message - Error message
+     * @returns this for method chaining
+     */
+    error(message: string): this;
+}
+
+/**
+ * March Agent SDK - Surface Structural Streamer
+ * Port of Python march_agent/structural/surface.py
+ *
+ * Surface structural streamer for embedded interactive components.
+ */
+
+/**
+ * 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" })
+ * ```
+ */
+declare class Surface extends StructuralStreamer {
+    protected _generateId(): string;
+    getEventTypePrefix(): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Signal surface loading failed.
+     *
+     * @param message - Error message
+     * @returns this for method chaining
+     */
+    error(message: string): this;
+}
+
+/**
+ * March Agent SDK - TextBlock Structural Streamer
+ * Port of Python march_agent/structural/text_block.py
+ *
+ * TextBlock structural streamer for collapsible text content.
+ */
+
+/**
+ * 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()
+ * ```
+ */
+declare class TextBlock extends StructuralStreamer {
+    readonly initialTitle?: string;
+    constructor(options?: {
+        id?: string;
+        title?: string;
+    });
+    protected _generateId(): string;
+    getEventTypePrefix(): string;
+    /**
+     * Stream title content (appends to existing).
+     *
+     * @param content - Content to append to title
+     * @returns this for method chaining
+     */
+    streamTitle(content: string): this;
+    /**
+     * Stream body content (appends to existing).
+     *
+     * @param content - Content to append to body
+     * @returns this for method chaining
+     */
+    streamBody(content: string): this;
+    /**
+     * Replace entire title.
+     *
+     * @param title - New title (replaces existing)
+     * @returns this for method chaining
+     */
+    updateTitle(title: string): this;
+    /**
+     * Replace entire body.
+     *
+     * @param body - New body (replaces existing)
+     * @returns this for method chaining
+     */
+    updateBody(body: string): this;
+    /**
+     * 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;
+    /**
+     * Mark text block as complete.
+     *
+     * @returns this for method chaining
+     */
+    done(): this;
+}
+
+/**
+ * March Agent SDK - Stepper Structural Streamer
+ * Port of Python march_agent/structural/stepper.py
+ *
+ * Stepper structural streamer for multi-step progress indicators.
+ */
+
+/**
+ * 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()
+ * ```
+ */
+declare class Stepper extends StructuralStreamer {
+    readonly steps: string[];
+    private _initialized;
+    constructor(options?: {
+        id?: string;
+        steps?: string[];
+    });
+    protected _generateId(): string;
+    getEventTypePrefix(): string;
+    /**
+     * Send initialization event with steps if not already sent.
+     * This is automatically called before any other stepper event.
+     */
+    private _ensureInitialized;
+    /**
+     * Mark step as in progress.
+     *
+     * @param index - Step index to start
+     * @returns this for method chaining
+     */
+    startStep(index: number): this;
+    /**
+     * Mark step as complete.
+     *
+     * @param index - Step index to complete
+     * @returns this for method chaining
+     */
+    completeStep(index: number): this;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Update step label.
+     *
+     * @param index - Step index to update
+     * @param label - New label
+     * @returns this for method chaining
+     */
+    updateStepLabel(index: number, label: string): this;
+    /**
+     * Mark stepper as complete (all steps finished).
+     *
+     * @returns this for method chaining
+     */
+    done(): this;
+}
+
 /**
  * March Agent SDK - Checkpoint Client
  * Port of Python march_agent/checkpoint_client.py
@@ -255,6 +535,6 @@ declare class GatewayError extends MarchAgentError {
  * @packageDocumentation
  */
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.4.0";
 
-export { AI_INVENTORY_PATHS, APIException, AgentStateClient, type AgentStateResponse, CONVERSATION_STORE_PATHS, CheckpointClient, type CheckpointConfig, type CheckpointData, type CheckpointMetadata, type CheckpointTuple, ConfigurationError, GatewayClient, GatewayError, HeartbeatError, HeartbeatManager, KafkaError, MEMORY_PATHS, MarchAgentError, RegistrationError, SERVICES, type ServiceName, VERSION };
+export { AI_INVENTORY_PATHS, APIException, AgentStateClient, type AgentStateResponse, Artifact, CONVERSATION_STORE_PATHS, CheckpointClient, type CheckpointConfig, type CheckpointData, type CheckpointMetadata, type CheckpointTuple, ConfigurationError, GatewayClient, GatewayError, HeartbeatError, HeartbeatManager, KafkaError, MEMORY_PATHS, MarchAgentError, RegistrationError, SERVICES, type ServiceName, Stepper, StructuralStreamer, Surface, TextBlock, VERSION };