@framers/agentos 0.1.2 → 0.1.3

package/README.md

@@ -274,269 +274,293 @@ for await (const chunk of agent.processRequest({
 
 ---
 
-## Documentation
-
-### Core Concepts
-
-| Guide | Description |
-|-------|-------------|
-| [Architecture](./docs/ARCHITECTURE.md) | System design and component overview |
-| [Deep Dive](./docs/AGENTOS_ARCHITECTURE_DEEP_DIVE.md) | Detailed architecture walkthrough |
-| [Extensions](./docs/RFC_EXTENSION_STANDARDS.md) | Extension system and standards |
-| [Ecosystem](./docs/ECOSYSTEM.md) | Related repos and packages |
-
-### Agent Features
-
-| Guide | Description |
-|-------|-------------|
-| [Planning Engine](./docs/PLANNING_ENGINE.md) | Multi-step task planning and execution |
-| [Human-in-the-Loop](./docs/HUMAN_IN_THE_LOOP.md) | Approval workflows and oversight |
-| [Agent Communication](./docs/AGENT_COMMUNICATION.md) | Inter-agent messaging patterns |
-| [Self-Building Agents](./docs/RECURSIVE_SELF_BUILDING_AGENTS.md) | Recursive agent construction |
-| [Structured Output](./docs/STRUCTURED_OUTPUT.md) | JSON schema validation |
-| [Evaluation Framework](./docs/EVALUATION_FRAMEWORK.md) | Testing and quality assurance |
-
-### Storage & Memory
-
-| Guide | Description |
-|-------|-------------|
-| [RAG Configuration](./docs/RAG_MEMORY_CONFIGURATION.md) | Memory and retrieval setup |
-| [SQL Storage](./docs/SQL_STORAGE_QUICKSTART.md) | SQLite/PostgreSQL setup |
-| [Client-Side Storage](./docs/CLIENT_SIDE_STORAGE.md) | Browser storage options |
-| [Migration Guide](./docs/MIGRATION_TO_STORAGE_ADAPTER.md) | Upgrading storage adapters |
-
-### Operations
-
-| Guide | Description |
-|-------|-------------|
-| [Cost Optimization](./docs/COST_OPTIMIZATION.md) | Token usage and cost management |
-| [Platform Support](./docs/PLATFORM_SUPPORT.md) | Supported platforms and environments |
-| [Releasing](./docs/RELEASING.md) | How to publish new versions |
-| [API Reference](./docs/api/index.html) | TypeDoc-generated API docs |
+## Documentation
+
+### Core Concepts
+
+| Guide | Description |
+|-------|-------------|
+| [Architecture](./docs/ARCHITECTURE.md) | System design and component overview |
+| [Guardrails](./docs/GUARDRAILS_USAGE.md) | Safety controls and mid-stream intervention |
+| [Extensions](./docs/RFC_EXTENSION_STANDARDS.md) | Extension system and standards |
+| [Ecosystem](./docs/ECOSYSTEM.md) | Related repos and packages |
+
+### Agent Features
+
+| Guide | Description |
+|-------|-------------|
+| [Planning Engine](./docs/PLANNING_ENGINE.md) | Multi-step task planning and execution |
+| [Human-in-the-Loop](./docs/HUMAN_IN_THE_LOOP.md) | Approval workflows and oversight |
+| [Agent Communication](./docs/AGENT_COMMUNICATION.md) | Inter-agent messaging patterns |
+| [Self-Building Agents](./docs/RECURSIVE_SELF_BUILDING_AGENTS.md) | Recursive agent construction |
+| [Structured Output](./docs/STRUCTURED_OUTPUT.md) | JSON schema validation |
+| [Evaluation Framework](./docs/EVALUATION_FRAMEWORK.md) | Testing and quality assurance |
+
+### Storage & Memory
+
+| Guide | Description |
+|-------|-------------|
+| [RAG Configuration](./docs/RAG_MEMORY_CONFIGURATION.md) | Memory and retrieval setup |
+| [SQL Storage](./docs/SQL_STORAGE_QUICKSTART.md) | SQLite/PostgreSQL setup |
+| [Client-Side Storage](./docs/CLIENT_SIDE_STORAGE.md) | Browser storage options |
+
+### Operations
+
+| Guide | Description |
+|-------|-------------|
+| [Cost Optimization](./docs/COST_OPTIMIZATION.md) | Token usage and cost management |
+| [Platform Support](./docs/PLATFORM_SUPPORT.md) | Supported platforms and environments |
+| [Releasing](./docs/RELEASING.md) | How to publish new versions |
+| [API Reference](./docs/api/index.html) | TypeDoc-generated API docs |
+---
+
+## Examples
+
+### Structured Data Extraction
+
+```typescript
+import { AgentOS, StructuredOutputManager } from '@framers/agentos';
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
+});
+
+// Extract typed data from unstructured text
+const structured = new StructuredOutputManager({ llmProviderManager: agent.llmProviderManager });
+const contact = await structured.generate({
+  prompt: 'Extract: "Meeting with Sarah Chen (sarah@startup.io) on Jan 15 re: Series A"',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      email: { type: 'string', format: 'email' },
+      date: { type: 'string' },
+      topic: { type: 'string' }
+    },
+    required: ['name', 'email']
+  },
+  schemaName: 'ContactInfo'
+});
+// → { name: 'Sarah Chen', email: 'sarah@startup.io', date: 'Jan 15', topic: 'Series A' }
+```
+
+### Human-in-the-Loop Approvals
+
+```typescript
+import { HumanInteractionManager } from '@framers/agentos';
+
+const hitl = new HumanInteractionManager({ defaultTimeoutMs: 300000 });
+
+// Gate high-risk operations with human approval
+const decision = await hitl.requestApproval({
+  action: {
+    type: 'database_mutation',
+    description: 'Archive 50K inactive accounts older than 2 years',
+    severity: 'high',
+    metadata: { affectedRows: 50000, table: 'users' }
+  },
+  alternatives: [
+    { action: 'soft_delete', description: 'Mark as inactive instead of archiving' },
+    { action: 'export_first', description: 'Export to CSV before archiving' }
+  ]
+});
+
+if (decision.approved) {
+  await executeArchive();
+} else if (decision.selectedAlternative) {
+  await executeAlternative(decision.selectedAlternative);
+}
+```
+
+### Autonomous Task Planning
+
+```typescript
+import { AgentOS, PlanningEngine } from '@framers/agentos';
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
+});
+
+const planner = new PlanningEngine({ llmProvider: agent.llmProviderManager, strategy: 'react' });
+
+// Decompose complex goals into executable steps with ReAct reasoning
+const plan = await planner.generatePlan({
+  goal: 'Migrate authentication from sessions to JWT',
+  constraints: ['Zero downtime', 'Backwards compatible for 30 days', 'Audit logging required'],
+  context: { currentStack: 'Express + Redis sessions', userCount: '50K' }
+});
+
+for await (const step of planner.executePlan(plan.id)) {
+  console.log(`[${step.status}] ${step.action}`);
+  if (step.requiresHumanApproval) {
+    const approved = await promptUser(step.description);
+    if (!approved) break;
+  }
+}
+```
+
+### Multi-Agent Collaboration
+
+```typescript
+import { AgentOS, AgencyRegistry, AgentCommunicationBus } from '@framers/agentos';
+
+// Create specialized agents
+const researcher = new AgentOS();
+await researcher.initialize({ llmProvider: llmConfig, persona: 'Research analyst' });
+
+const writer = new AgentOS();
+await writer.initialize({ llmProvider: llmConfig, persona: 'Technical writer' });
+
+// Register in agency with shared communication
+const agency = new AgencyRegistry();
+const bus = new AgentCommunicationBus();
+agency.register('researcher', researcher, { bus });
+agency.register('writer', writer, { bus });
+
+// Agents coordinate via message passing
+bus.on('research:complete', async ({ findings }) => {
+  await writer.processRequest({
+    message: `Write documentation based on: ${JSON.stringify(findings)}`
+  });
+});
+
+await researcher.processRequest({ message: 'Analyze the authentication module' });
+```
+
+### Guardrails: Mid-Stream Decision Override
+
+```typescript
+import { AgentOS } from '@framers/agentos';
+import { CostCeilingGuardrail } from './guardrails/CostCeilingGuardrail';
+
+const costGuard = new CostCeilingGuardrail({
+  maxCostUsd: 0.05,  // 5 cents per request
+  inputTokenPricePer1k: 0.0001,
+  outputTokenPricePer1k: 0.0002,
+  budgetExceededText: 'Response exceeded cost ceiling. Please refine your request.'
+});
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
+  guardrailService: costGuard
+});
+
+// Agent generates expensive response → guardrail intercepts → substitutes budget message
+// Agents can "change their mind" before delivery based on cost, content policy, or quality checks
+```
+
+See [Guardrails Usage Guide](./docs/GUARDRAILS_USAGE.md) for complete documentation.
+
+### Non-Streaming Response
+
+```typescript
+import { AgentOS } from '@framers/agentos';
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
+});
+
+// Collect full response without streaming
+const chunks = [];
+for await (const chunk of agent.processRequest({ message: 'Explain OAuth 2.0 briefly' })) {
+  if (chunk.type === 'content') {
+    chunks.push(chunk.content);
+  }
+}
+const fullResponse = chunks.join('');
+```
+
+### Mood-Adaptive Responses
+
+```typescript
+import { AgentOS, GMIMood } from '@framers/agentos';
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+  persona: {
+    name: 'Support Agent',
+    moodAdaptation: {
+      enabled: true,
+      defaultMood: GMIMood.EMPATHETIC,
+      allowedMoods: [GMIMood.EMPATHETIC, GMIMood.FOCUSED, GMIMood.ANALYTICAL],
+      sensitivityFactor: 0.7,
+      // Mood-specific prompt modifiers
+      moodPrompts: {
+        [GMIMood.EMPATHETIC]: 'Prioritize understanding and emotional support.',
+        [GMIMood.FRUSTRATED]: 'Acknowledge difficulty, offer step-by-step guidance.',
+        [GMIMood.ANALYTICAL]: 'Provide detailed technical explanations with examples.'
+      }
+    }
+  }
+});
+
+// Agent automatically adapts tone based on conversation context
+for await (const chunk of agent.processRequest({
+  message: 'This is so frustrating, nothing works!'
+})) {
+  // Response adapts with empathetic tone, mood shifts to EMPATHETIC
+}
+```
+
+### Contextual Prompt Adaptation
+
+```typescript
+import { AgentOS } from '@framers/agentos';
+
+const agent = new AgentOS();
+await agent.initialize({
+  llmProvider: llmConfig,
+  persona: {
+    name: 'Adaptive Tutor',
+    // Dynamic prompt elements injected based on runtime context
+    contextualPromptElements: [
+      {
+        id: 'beginner-guidance',
+        type: 'SYSTEM_INSTRUCTION_ADDON',
+        content: 'Explain concepts simply, avoid jargon, use analogies.',
+        criteria: { userSkillLevel: ['novice', 'beginner'] },
+        priority: 10
+      },
+      {
+        id: 'expert-mode',
+        type: 'SYSTEM_INSTRUCTION_ADDON',
+        content: 'Assume deep technical knowledge, be concise, skip basics.',
+        criteria: { userSkillLevel: ['expert', 'advanced'] },
+        priority: 10
+      },
+      {
+        id: 'debugging-context',
+        type: 'FEW_SHOT_EXAMPLE',
+        content: { role: 'assistant', content: 'Let\'s trace through step by step...' },
+        criteria: { taskHint: ['debugging', 'troubleshooting'] }
+      }
+    ],
+    // Meta-prompts for self-reflection and planning
+    metaPrompts: [
+      {
+        id: 'mid-conversation-check',
+        trigger: 'every_n_turns',
+        triggerConfig: { n: 5 },
+        prompt: 'Assess: Is the user making progress? Should I adjust my approach?'
+      }
+    ]
+  }
+});
+
+// Prompts automatically adapt based on user context and task
+await agent.updateUserContext({ skillLevel: 'expert' });
+for await (const chunk of agent.processRequest({ message: 'Explain monads' })) {
+  // Uses expert-mode prompt element, skips beginner explanations
+}
+```
+
 ---
 
-## Examples
-
-### Structured Data Extraction
-
-```typescript
-import { AgentOS, StructuredOutputManager } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
-});
-
-// Extract typed data from unstructured text
-const structured = new StructuredOutputManager({ llmProviderManager: agent.llmProviderManager });
-const contact = await structured.generate({
-  prompt: 'Extract: "Meeting with Sarah Chen (sarah@startup.io) on Jan 15 re: Series A"',
-  schema: {
-    type: 'object',
-    properties: {
-      name: { type: 'string' },
-      email: { type: 'string', format: 'email' },
-      date: { type: 'string' },
-      topic: { type: 'string' }
-    },
-    required: ['name', 'email']
-  },
-  schemaName: 'ContactInfo'
-});
-// → { name: 'Sarah Chen', email: 'sarah@startup.io', date: 'Jan 15', topic: 'Series A' }
-```
-
-### Human-in-the-Loop Approvals
-
-```typescript
-import { HumanInteractionManager } from '@framers/agentos';
-
-const hitl = new HumanInteractionManager({ defaultTimeoutMs: 300000 });
-
-// Gate high-risk operations with human approval
-const decision = await hitl.requestApproval({
-  action: {
-    type: 'database_mutation',
-    description: 'Archive 50K inactive accounts older than 2 years',
-    severity: 'high',
-    metadata: { affectedRows: 50000, table: 'users' }
-  },
-  alternatives: [
-    { action: 'soft_delete', description: 'Mark as inactive instead of archiving' },
-    { action: 'export_first', description: 'Export to CSV before archiving' }
-  ]
-});
-
-if (decision.approved) {
-  await executeArchive();
-} else if (decision.selectedAlternative) {
-  await executeAlternative(decision.selectedAlternative);
-}
-```
-
-### Autonomous Task Planning
-
-```typescript
-import { AgentOS, PlanningEngine } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
-});
-
-const planner = new PlanningEngine({ llmProvider: agent.llmProviderManager, strategy: 'react' });
-
-// Decompose complex goals into executable steps with ReAct reasoning
-const plan = await planner.generatePlan({
-  goal: 'Migrate authentication from sessions to JWT',
-  constraints: ['Zero downtime', 'Backwards compatible for 30 days', 'Audit logging required'],
-  context: { currentStack: 'Express + Redis sessions', userCount: '50K' }
-});
-
-for await (const step of planner.executePlan(plan.id)) {
-  console.log(`[${step.status}] ${step.action}`);
-  if (step.requiresHumanApproval) {
-    const approved = await promptUser(step.description);
-    if (!approved) break;
-  }
-}
-```
-
-### Multi-Agent Collaboration
-
-```typescript
-import { AgentOS, AgencyRegistry, AgentCommunicationBus } from '@framers/agentos';
-
-// Create specialized agents
-const researcher = new AgentOS();
-await researcher.initialize({ llmProvider: llmConfig, persona: 'Research analyst' });
-
-const writer = new AgentOS();
-await writer.initialize({ llmProvider: llmConfig, persona: 'Technical writer' });
-
-// Register in agency with shared communication
-const agency = new AgencyRegistry();
-const bus = new AgentCommunicationBus();
-agency.register('researcher', researcher, { bus });
-agency.register('writer', writer, { bus });
-
-// Agents coordinate via message passing
-bus.on('research:complete', async ({ findings }) => {
-  await writer.processRequest({
-    message: `Write documentation based on: ${JSON.stringify(findings)}`
-  });
-});
-
-await researcher.processRequest({ message: 'Analyze the authentication module' });
-```
-
-### Non-Streaming Response
-
-```typescript
-import { AgentOS } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
-});
-
-// Collect full response without streaming
-const chunks = [];
-for await (const chunk of agent.processRequest({ message: 'Explain OAuth 2.0 briefly' })) {
-  if (chunk.type === 'content') {
-    chunks.push(chunk.content);
-  }
-}
-const fullResponse = chunks.join('');
-```
-
-### Mood-Adaptive Responses
-
-```typescript
-import { AgentOS, GMIMood } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
-  persona: {
-    name: 'Support Agent',
-    moodAdaptation: {
-      enabled: true,
-      defaultMood: GMIMood.EMPATHETIC,
-      allowedMoods: [GMIMood.EMPATHETIC, GMIMood.FOCUSED, GMIMood.ANALYTICAL],
-      sensitivityFactor: 0.7,
-      // Mood-specific prompt modifiers
-      moodPrompts: {
-        [GMIMood.EMPATHETIC]: 'Prioritize understanding and emotional support.',
-        [GMIMood.FRUSTRATED]: 'Acknowledge difficulty, offer step-by-step guidance.',
-        [GMIMood.ANALYTICAL]: 'Provide detailed technical explanations with examples.'
-      }
-    }
-  }
-});
-
-// Agent automatically adapts tone based on conversation context
-for await (const chunk of agent.processRequest({
-  message: 'This is so frustrating, nothing works!'
-})) {
-  // Response adapts with empathetic tone, mood shifts to EMPATHETIC
-}
-```
-
-### Contextual Prompt Adaptation
-
-```typescript
-import { AgentOS } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: llmConfig,
-  persona: {
-    name: 'Adaptive Tutor',
-    // Dynamic prompt elements injected based on runtime context
-    contextualPromptElements: [
-      {
-        id: 'beginner-guidance',
-        type: 'SYSTEM_INSTRUCTION_ADDON',
-        content: 'Explain concepts simply, avoid jargon, use analogies.',
-        criteria: { userSkillLevel: ['novice', 'beginner'] },
-        priority: 10
-      },
-      {
-        id: 'expert-mode',
-        type: 'SYSTEM_INSTRUCTION_ADDON',
-        content: 'Assume deep technical knowledge, be concise, skip basics.',
-        criteria: { userSkillLevel: ['expert', 'advanced'] },
-        priority: 10
-      },
-      {
-        id: 'debugging-context',
-        type: 'FEW_SHOT_EXAMPLE',
-        content: { role: 'assistant', content: 'Let\'s trace through step by step...' },
-        criteria: { taskHint: ['debugging', 'troubleshooting'] }
-      }
-    ],
-    // Meta-prompts for self-reflection and planning
-    metaPrompts: [
-      {
-        id: 'mid-conversation-check',
-        trigger: 'every_n_turns',
-        triggerConfig: { n: 5 },
-        prompt: 'Assess: Is the user making progress? Should I adjust my approach?'
-      }
-    ]
-  }
-});
-
-// Prompts automatically adapt based on user context and task
-await agent.updateUserContext({ skillLevel: 'expert' });
-for await (const chunk of agent.processRequest({ message: 'Explain monads' })) {
-  // Uses expert-mode prompt element, skips beginner explanations
-}
-```
-
----
-
 ## Roadmap
 
 | Version | Status | Features |