march-start-cli 0.1.4 → 0.1.5

package/dist/template/README.md

@@ -284,14 +284,25 @@ agent.onMessage(async (message, sender) => {
 })
 ```
 
-#### Artifacts
+#### Structural Streaming (Artifacts, Surfaces, TextBlocks, Steppers)
 
-Attach files, documents, or iframes to your response:
+The SDK provides structural streaming components for rich content.
+
+##### Artifacts
+
+Stream file artifacts with progress indication:
 
 ```typescript
+import { Artifact } from '@march/agent'
+
 const streamer = agent.streamer(message)
+const artifact = new Artifact()
+
+// Optional: show generation progress
+streamer.streamBy(artifact).generating('Generating report...', 0.5)
 
-streamer.addArtifact({
+// Signal completion with artifact details
+streamer.streamBy(artifact).done({
     url: `/api/reports/lab-results.pdf`,
     type: 'document',
     title: 'Lab Results',
@@ -299,27 +310,71 @@ streamer.addArtifact({
     metadata: { size: 1024000, mimeType: 'application/pdf' }
 })
 
-streamer.addArtifact({
+streamer.stream('Here are your results.')
+await streamer.finish()
+```
+
+##### Surfaces (Embedded iframes)
+
+Stream embedded interactive content:
+
+```typescript
+import { Surface } from '@march/agent'
+
+const surface = new Surface()
+streamer.streamBy(surface).generating('Loading dashboard...')
+streamer.streamBy(surface).done({
     url: `/dashboard/${message.conversationId}`,
     type: 'iframe',
     title: 'Patient Dashboard',
     description: 'Interactive dashboard showing conversation statistics',
 })
+```
 
-streamer.stream('Here are your results.')
-await streamer.finish()
+##### TextBlocks (Collapsible Content)
+
+Stream collapsible text with variants:
+
+```typescript
+import { TextBlock } from '@march/agent'
+
+const block = new TextBlock()
+streamer.streamBy(block).setVariant('thinking')
+streamer.streamBy(block).streamTitle('Analyzing symptoms...')
+streamer.streamBy(block).streamBody('Checking medical database...\n')
+streamer.streamBy(block).streamBody('Cross-referencing symptoms...\n')
+streamer.streamBy(block).updateTitle('Analysis Complete')
+streamer.streamBy(block).done()
+```
+
+Variants: `thinking`, `note`, `warning`, `error`, `success`
+
+##### Steppers (Multi-step Progress)
+
+Show multi-step progress indicators:
+
+```typescript
+import { Stepper } from '@march/agent'
+
+const stepper = new Stepper({ steps: ['Fetch Records', 'Analyze', 'Generate Report'] })
+streamer.streamBy(stepper).startStep(0)
+// ... fetch records ...
+streamer.streamBy(stepper).completeStep(0)
+streamer.streamBy(stepper).startStep(1)
+// ... analyze ...
+streamer.streamBy(stepper).completeStep(1)
+streamer.streamBy(stepper).startStep(2)
+// ... generate ...
+streamer.streamBy(stepper).completeStep(2)
+streamer.streamBy(stepper).done()
 ```
 
-| Artifact Type | Use Case |
-|---------------|----------|
-| `document` | PDFs, reports, guides |
-| `image` | Charts, diagrams, photos |
-| `iframe` | Interactive content, dashboards |
-| `video` | Tutorials, demos |
-| `audio` | Voice messages |
-| `code` | Source code snippets |
-| `link` | External URLs |
-| `file` | Generic downloads |
+| 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()` |
 
 ---
 

package/dist/template/env.example

@@ -1,6 +1,6 @@
 # Agent Configuration
 AGENT_NAME=my-agent
-AGENT_ABOUT=A helpful AI assistant
+AGENT_ABOUT="A helpful AI assistant"
 
 # Gateway Configuration
 GATEWAY_URL=agent-gateway:8080

package/dist/template/src/agent.ts

@@ -21,13 +21,13 @@ import { ChatOpenAI } from '@langchain/openai'
 import { HumanMessage, AIMessage, SystemMessage, type BaseMessage } from '@langchain/core/messages'
 
 // Import from local framework (change to 'march-ai-sdk' when published)
-import { MarchAgentApp, Message } from '../../ai-ts-framework/dist/index.js'
+import { MarchAgentApp, Message, Artifact, Surface } from '../../ai-ts-framework/dist/index.js'
 
 // ============================================================================
 // CONFIGURATION
 // ============================================================================
 
-const AGENT_NAME = process.env.AGENT_NAME || 'my-agent'
+const AGENT_NAME = process.env.AGENT_NAME || 'my-agent-ts'
 const AGENT_ABOUT = process.env.AGENT_ABOUT || 'A helpful AI assistant'
 
 const SYSTEM_PROMPT = `You are a helpful AI assistant. Your role is to assist users with their questions and tasks.
@@ -144,15 +144,20 @@ async function main() {
             hasAttachment: message.hasAttachment(),
         })
 
-        // Add artifacts for testing frontend rendering
-        streamer.addArtifact({
+        // Add structural streaming components for testing frontend rendering
+        
+        // Surface for interactive dashboard (iframe)
+        const dashboard = new Surface()
+        streamer.streamBy(dashboard).done({
             url: `/api/dashboard/${message.conversationId}`,
             type: 'iframe',
             title: 'Patient Dashboard',
             description: 'Interactive dashboard showing conversation statistics',
         })
 
-        streamer.addArtifact({
+        // Artifact for document
+        const report = new Artifact()
+        streamer.streamBy(report).done({
             url: `/api/artifacts/document/${message.conversationId}`,
             type: 'document',
             title: 'Health Summary Report',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "march-start-cli",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "description": "CLI to scaffold new March AI agent projects",
     "type": "module",
     "bin": {