@marshmallo/marlo 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,11 @@
-# Marlo TypeScript SDK
+# @marshmallo/marlo
 
-The official TypeScript SDK for [Marlo](https://marshmallo.ai) - agent observability and learning platform.
+The official TypeScript SDK for [Marlo](https://marshmallo.ai) - the agent learning platform.
+
+Marlo enables AI agents to learn and improve autonomously in production. It captures agent behavior, evaluates outcomes, and turns failures into actionable learnings.
+
+[![npm version](https://img.shields.io/npm/v/@marshmallo/marlo.svg)](https://www.npmjs.com/package/@marshmallo/marlo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Installation
 
@@ -13,269 +18,155 @@ npm install @marshmallo/marlo
 ```typescript
 import * as marlo from '@marshmallo/marlo';
 
-// Initialize with your API key
-await marlo.init(process.env.MARLO_API_KEY!);
+// Initialize
+await marlo.init(process.env.MARLO_API_KEY);
 
 // Register your agent
-marlo.agent(
-  'my-agent',
-  'You are a helpful assistant.',
-  [{ name: 'search', description: 'Search the web' }],
-  null,
-  { model: 'gpt-4' }
-);
+marlo.agent('support-bot', 'You are a customer support agent.', [
+  { name: 'lookup_order', description: 'Find order by ID' }
+]);
 
 // Track a task
-const task = marlo.task('thread-123', 'my-agent').start();
-task.input('Hello, how can you help?');
+const task = marlo.task('thread-123', 'support-bot').start();
+task.input('Where is my order?');
 
 // Your agent logic here...
-task.llm({
-  model: 'gpt-4',
-  usage: { input_tokens: 50, output_tokens: 100 },
-  messages: [{ role: 'user', content: 'Hello' }],
-  response: 'I can help with many things!',
-});
-
-task.output('I can help with many things!');
+
+task.output('Your order ships tomorrow.');
 task.end();
 
 // Shutdown before exit
 await marlo.shutdown();
 ```
 
-## Features
+## Why Marlo?
+
+Agents fail silently in production. The same mistakes repeat because failures aren't captured in a reusable form. Marlo solves this with a learning loop:
 
-- **Task Tracking**: Capture agent inputs, outputs, and interactions
-- **LLM Call Recording**: Track model usage, tokens, and responses
-- **Tool Call Logging**: Record tool invocations and results
-- **Multi-Agent Support**: Track parent-child agent relationships
-- **Learnings Integration**: Fetch and apply learnings from past interactions
-- **Buffered Sending**: Automatic batching and retry for reliability
+1. **Capture** - Record LLM calls, tool calls, and outcomes
+2. **Evaluate** - Score task outcomes automatically
+3. **Learn** - Generate guidance from failures
+4. **Apply** - Inject learnings into future tasks
 
-## API Reference
+## API
 
-### Initialization
+### Initialize
 
 ```typescript
-// Initialize the SDK
 await marlo.init(apiKey);
-
-// Check if SDK is enabled
-marlo.isEnabled(): boolean;
-
-// Get the client instance
-marlo.getClient(): MarloClient | null;
-
-// Shutdown and flush pending events
-await marlo.shutdown();
 ```
 
-### Agent Registration
+### Register Agent
 
 ```typescript
-marlo.agent(
-  name: string,
-  systemPrompt: string,
-  tools: ToolDefinition[],
-  mcp?: McpDefinition[] | null,
-  modelConfig?: ModelConfig | null
-): string;
+marlo.agent(name, systemPrompt, tools, mcp?, modelConfig?);
 ```
 
-| Parameter | Description |
-|-----------|-------------|
-| `name` | Unique identifier for your agent |
-| `systemPrompt` | System prompt used by your agent |
-| `tools` | List of tool definitions `[{ name: "...", description: "..." }]` |
-| `mcp` | Optional list of MCP server definitions |
-| `modelConfig` | Optional model configuration `{ model: "gpt-4", ... }` |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Unique agent identifier |
+| `systemPrompt` | `string` | Agent's system prompt |
+| `tools` | `ToolDefinition[]` | Available tools |
+| `mcp` | `McpDefinition[]` | MCP servers (optional) |
+| `modelConfig` | `ModelConfig` | Model settings (optional) |
 
-### Task Tracking
+### Track Tasks
 
 ```typescript
-// Create and start a task
-const task = marlo.task(threadId: string, agentName: string, threadName?: string).start();
-
-// Record events
-task.input(text);                           // User input
-task.output(text);                          // Agent response
-task.llm({ model, usage, messages?, response? });  // LLM call
-task.tool(name, input, output, error?);     // Tool call
-task.reasoning(text);                       // Chain-of-thought
-task.error(message);                        // Mark task as failed
-
-// Fetch learnings
-const learnings = await task.getLearnings();
+const task = marlo.task(threadId, agentName, threadName?).start();
 
-// Create child task for multi-agent
-const child = task.child(agentName).start();
+task.input(text);           // User input
+task.output(text);          // Agent response
+task.llm({ model, usage, messages?, response? });
+task.tool(name, input, output, error?);
+task.reasoning(text);       // Chain-of-thought
+task.error(message);        // Mark as failed
 
-// End the task
-task.end(hasError?: boolean);
+task.end();
 ```
 
-### Task Methods
-
-#### `task.input(text: string)`
-Record the user's input message.
-
-#### `task.output(text: string)`
-Record the agent's final response.
-
-#### `task.llm(params)`
-Track an LLM call.
+### Fetch Learnings
 
 ```typescript
-task.llm({
-  model: 'gpt-4',
-  usage: { input_tokens: 100, output_tokens: 50 },
-  messages: [{ role: 'user', content: 'Hello' }],
-  response: 'Hi there!',
-});
-```
-
-#### `task.tool(name, input, output, error?)`
-Track a tool call.
+const learnings = await task.getLearnings();
 
-```typescript
-task.tool(
-  'search',
-  { query: 'weather' },
-  { result: 'sunny' },
-  undefined  // Optional error message
-);
+if (learnings?.learnings_text) {
+  // Inject into your agent's context
+  systemPrompt += `\n\nLearnings:\n${learnings.learnings_text}`;
+}
 ```
 
-#### `task.reasoning(text: string)`
-Record chain-of-thought or reasoning steps.
+### Multi-Agent
 
-#### `task.error(message: string)`
-Mark the task as failed with an error message.
+```typescript
+const parent = marlo.task('thread-1', 'orchestrator').start();
+parent.input('Research AI trends');
 
-#### `task.getLearnings()`
-Fetch learnings from past interactions.
+const child = parent.child('researcher').start();
+child.input('Search for AI trends');
+child.output('Found 3 sources...');
+child.end();
 
-```typescript
-const learnings = await task.getLearnings();
-if (learnings) {
-  // Apply learnings to your agent
-}
+parent.output('Report complete');
+parent.end();
 ```
 
-#### `task.child(agentName: string)`
-Create a child task for multi-agent workflows.
-
-## Complete Example
+### Shutdown
 
 ```typescript
-import * as marlo from '@marshmallo/marlo';
-
-// Initialize
-await marlo.init('mk_abc123');
-
-// Register agent with tools
-marlo.agent(
-  'support-bot',
-  'You are a customer support agent.',
-  [
-    { name: 'lookup_order', description: 'Find order by ID' },
-    { name: 'check_inventory', description: 'Check product stock' },
-  ],
-  null,
-  { model: 'gpt-4', temperature: 0.7 }
-);
-
-async function handleMessage(threadId: string, userMessage: string): Promise<string> {
-  const task = marlo.task(threadId, 'support-bot').start();
-  task.input(userMessage);
-
-  try {
-    // Get learnings to improve responses
-    const learnings = await task.getLearnings();
-
-    // Build messages
-    const messages = [
-      { role: 'system', content: 'You are a customer support agent.' },
-      { role: 'user', content: userMessage },
-    ];
-
-    // Call LLM
-    const response = await llm.chat(messages);
-    const answer = response.content;
-
-    // Track the LLM call
-    task.llm({
-      model: 'gpt-4',
-      usage: {
-        input_tokens: response.usage.promptTokens,
-        output_tokens: response.usage.completionTokens,
-      },
-      messages,
-      response: answer,
-    });
-
-    // Track any tool calls
-    if (response.toolCalls) {
-      for (const toolCall of response.toolCalls) {
-        const result = await executeTool(toolCall);
-        task.tool(toolCall.name, toolCall.arguments, result);
-      }
-    }
-
-    task.output(answer);
-    return answer;
-  } catch (error) {
-    task.error(error instanceof Error ? error.message : 'Unknown error');
-    throw error;
-  } finally {
-    task.end();
-  }
-}
-
-// Cleanup on shutdown
 await marlo.shutdown();
 ```
 
-## Multi-Agent Example
+## Full Example
 
 ```typescript
 import * as marlo from '@marshmallo/marlo';
 
-await marlo.init('mk_abc123');
+await marlo.init(process.env.MARLO_API_KEY);
 
-marlo.agent('orchestrator', 'You coordinate tasks.', []);
-marlo.agent('researcher', 'You research topics.', []);
-marlo.agent('writer', 'You write content.', []);
+marlo.agent('support-bot', 'You are a customer support agent.', [
+  { name: 'lookup_order', description: 'Find order by ID' }
+]);
 
-const mainTask = marlo.task('doc-123', 'orchestrator').start();
-mainTask.input('Write a report about AI');
+async function handleMessage(input: string, threadId: string) {
+  const task = marlo.task(threadId, 'support-bot').start();
+  task.input(input);
 
-// Delegate to researcher
-const research = mainTask.child('researcher').start();
-research.input('Research AI trends');
-research.output('AI trends: ...');
-research.end();
+  // Apply learnings from past interactions
+  const learnings = await task.getLearnings();
+  let systemPrompt = 'You are a customer support agent.';
+  if (learnings?.learnings_text) {
+    systemPrompt += `\n\nLearnings:\n${learnings.learnings_text}`;
+  }
 
-// Delegate to writer
-const writer = mainTask.child('writer').start();
-writer.input('Write report based on research');
-writer.output('# AI Report\n...');
-writer.end();
+  // Track tool call
+  task.tool('lookup_order', { id: '123' }, { status: 'shipped' });
 
-mainTask.output('Report completed');
-mainTask.end();
-```
+  // Track LLM call
+  const response = 'Your order ships tomorrow.';
+  task.llm({
+    model: 'gpt-4',
+    usage: { input_tokens: 100, output_tokens: 25 },
+    messages: [{ role: 'user', content: input }],
+    response
+  });
 
-## Environment Variables
+  task.output(response);
+  task.end();
 
-```bash
-MARLO_API_KEY=your-api-key
+  return response;
+}
 ```
 
 ## Requirements
 
-- Node.js 18.0.0 or later
+- Node.js 18+
+
+## Links
+
+- [Documentation](https://docs.marshmallo.ai)
+- [Dashboard](https://marshmallo.ai)
+- [Python SDK](https://pypi.org/project/marlo-sdk)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@marshmallo/marlo",
-  "version": "0.1.0",
-  "description": "Marlo SDK for agent observability and learning",
+  "version": "0.1.2",
+  "description": "The official TypeScript SDK for Marlo - the agent learning platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",