societyai 0.0.1

package/examples/README.md

@@ -0,0 +1,234 @@
+# SocietyAI Examples
+
+This directory contains comprehensive examples demonstrating all features of SocietyAI.
+
+## Available Examples
+
+### 1. Graph-Based Workflow (`graph-workflow.ts`)
+
+Demonstrates the new graph-based execution engine with:
+
+- Conditional branching
+- Loop support
+- Parallel execution
+- Dynamic routing
+
+**Run:**
+
+```bash
+ts-node examples/graph-workflow.ts
+```
+
+### 2. Tool Calling System (`tool-calling.ts`)
+
+Shows how agents can use tools to:
+
+- Perform calculations
+- Manipulate strings
+- Store and retrieve data
+- Call custom functions
+
+**Run:**
+
+```bash
+ts-node examples/tool-calling.ts
+```
+
+### 3. Memory System (`memory-system.ts`)
+
+Demonstrates multi-level memory:
+
+- Short-term conversation history
+- Long-term fact storage
+- Entity tracking
+- Importance-based retrieval
+
+**Run:**
+
+```bash
+ts-node examples/memory-system.ts
+```
+
+### 4. Structured Output Validation (`structured-output.ts`)
+
+Shows automatic validation with retry:
+
+- JSON Schema validation
+- Error feedback to agents
+- Automatic retry logic
+- Complex nested schemas
+
+**Run:**
+
+```bash
+ts-node examples/structured-output.ts
+```
+
+### 5. Metrics and Observability (`metrics-tracking.ts`)
+
+Comprehensive tracking of:
+
+- Token usage
+- Execution time
+- Cost estimation
+- OpenTelemetry export
+- Performance profiling
+
+**Run:**
+
+```bash
+ts-node examples/metrics-tracking.ts
+```
+
+### 6. Complete Integration (`complete-integration.ts`)
+
+End-to-end example using all features together:
+
+- Graph-based workflow
+- Tool calling
+- Memory system
+- Output validation
+- Metrics tracking
+
+**Run:**
+
+```bash
+ts-node examples/complete-integration.ts
+```
+
+## Running All Examples
+
+```bash
+npm run examples
+```
+
+Or run them individually:
+
+```bash
+# Graph workflow
+npm run example:graph
+
+# Tool calling
+npm run example:tools
+
+# Memory system
+npm run example:memory
+
+# Structured output
+npm run example:validation
+
+# Metrics tracking
+npm run example:metrics
+
+# Complete integration
+npm run example:complete
+```
+
+## Key Concepts Demonstrated
+
+### Graph-Based Execution
+
+- **DAG Support**: Directed Acyclic Graphs for complex workflows
+- **Conditional Edges**: Dynamic routing based on runtime conditions
+- **Loop Support**: Iterative processing with termination conditions
+- **Parallel Execution**: Run multiple agents simultaneously
+
+### Tool Calling
+
+- **Function Definitions**: JSON Schema-based tool definitions
+- **Parameter Validation**: Automatic validation of tool inputs
+- **Result Handling**: Structured tool result processing
+- **Error Recovery**: Retry logic for failed tool calls
+
+### Memory System
+
+- **Short-Term Memory**: Recent conversation with auto-summarization
+- **Long-Term Memory**: Persistent facts with semantic search
+- **Entity Memory**: Track specific entities and their facts
+- **Importance Scoring**: Priority-based memory retrieval
+
+### Structured Output
+
+- **Schema Validation**: JSON Schema-based validation
+- **Automatic Retry**: Retry with error feedback
+- **Type Safety**: Fully typed validated outputs
+- **Complex Schemas**: Support for nested objects and arrays
+
+### Observability
+
+- **Token Tracking**: Per-agent token usage monitoring
+- **Cost Estimation**: Automatic cost calculation
+- **Performance Profiling**: Detailed timing metrics
+- **OpenTelemetry**: Industry-standard trace export
+
+## Advanced Patterns
+
+### Combining Features
+
+```typescript
+// Create a graph with tools, memory, and validation
+const graph = GraphBuilder.create()
+  .addNode('agent-with-tools', NodeType.AGENT, {
+    agentId: 'tool-user',
+    memory: memorySystem,
+    validator: outputValidator,
+  })
+  .build();
+
+// Execute with full metrics
+tracker.start('workflow');
+const result = await graph.execute(input, agents);
+tracker.end('workflow', { tokens: tokenMetrics });
+```
+
+### Real-World Use Cases
+
+1. **Code Review Pipeline**: Analyze → Fix → Validate loop with tools
+2. **Data Processing**: Parallel processing with aggregation
+3. **Research Assistant**: Memory-enhanced information gathering
+4. **API Integration**: Tool calling for external services
+5. **Quality Assurance**: Structured output validation for consistency
+
+## Best Practices
+
+1. **Memory Management**: Balance short-term and long-term storage
+2. **Tool Design**: Keep tools focused and well-documented
+3. **Schema Design**: Start simple, add complexity as needed
+4. **Metrics Collection**: Track what matters for your use case
+5. **Graph Design**: Minimize cycles, use conditions wisely
+
+## Troubleshooting
+
+### Common Issues
+
+**Graph validation fails:**
+
+- Ensure START and END nodes exist
+- Check all edges reference valid nodes
+- Verify conditional logic is correct
+
+**Tool execution fails:**
+
+- Validate parameter schemas match tool definitions
+- Check required parameters are provided
+- Ensure tool executors handle errors
+
+**Memory retrieval is slow:**
+
+- Limit result count with `limit` parameter
+- Use importance scoring for prioritization
+- Consider implementing vector provider for semantic search
+
+**Validation keeps retrying:**
+
+- Check schema matches expected output format
+- Verify agent understands schema requirements
+- Add schema description to agent prompt
+
+## Contributing
+
+Found a bug or want to add a new example? Please submit a pull request or open an issue on GitHub.
+
+## License
+
+MIT License - see LICENSE file for details

package/examples/advanced-patterns.ts

@@ -0,0 +1,115 @@
+import { 
+  GraphBuilder, 
+  NodeType, 
+  SocietyAsModel, 
+  PipelinePatterns,
+  AgentBuilder,
+  RoleBuilder,
+  AIModel
+} from '../src';
+
+// Simple Mock Model for demonstration
+class MockModel implements AIModel {
+  constructor(private nameStr: string) {}
+  
+  name(): string { return this.nameStr; }
+  
+  async process(prompt: unknown): Promise<string> {
+    return `[Response from ${this.nameStr} to: "${String(prompt).substring(0, 20)}..."]`;
+  }
+  
+  supportsPromptType(): boolean { return true; }
+}
+
+async function demonstrateRecursiveSociety(): Promise<void> {
+  console.log('=== Recursive Society Demo ===');
+  
+  // 1. Create a Sub-Society (e.g., a "Translation Team")
+  const translator = AgentBuilder.create()
+    .withId('translator')
+    .withName('Translator')
+    .withRole(RoleBuilder.create().withId('translator').withSystemPrompt('Translate to French').build())
+    .withModel(new MockModel('TranslatorBot'))
+    .build();
+    
+  const editor = AgentBuilder.create()
+    .withId('editor')
+    .withName('Editor')
+    .withRole(RoleBuilder.create().withId('editor').withSystemPrompt('Fix grammar').build())
+    .withModel(new MockModel('EditorBot'))
+    .build();
+    
+  const teamGraph = GraphBuilder.create()
+    .addNode('start', NodeType.START)
+    .addNode('translate', NodeType.AGENT, { agentId: 'translator' })
+    .addNode('edit', NodeType.AGENT, { agentId: 'editor' })
+    .addNode('end', NodeType.END)
+    .addEdge('start', 'translate')
+    .addEdge('translate', 'edit')
+    .addEdge('edit', 'end')
+    .build();
+    
+  // Wrap the society as an AI Model
+  const translationTeamModel = new SocietyAsModel(
+    teamGraph, 
+    [translator, editor], 
+    { name: 'TranslationTeam' }
+  );
+  
+  // 2. Create the Main Society that uses the sub-society
+  const projectManager = AgentBuilder.create()
+    .withId('pm')
+    .withName('ProjectManager')
+    .withRole(RoleBuilder.create().withId('pm').withSystemPrompt('Manage project').build())
+    .withModel(new MockModel('ManagerBot'))
+    .build();
+    
+  const translationAgent = AgentBuilder.create()
+    .withId('translation_dept')
+    .withName('Translation Department')
+    .withRole(RoleBuilder.create().withId('dept').withSystemPrompt('Handle translations').build())
+    .withModel(translationTeamModel) // Using the sub-society as the model
+    .build();
+    
+  const companyGraph = GraphBuilder.create()
+    .addNode('start', NodeType.START)
+    .addNode('plan', NodeType.AGENT, { agentId: 'pm' })
+    .addNode('execute', NodeType.AGENT, { agentId: 'translation_dept' })
+    .addNode('end', NodeType.END)
+    .addEdge('start', 'plan')
+    .addEdge('plan', 'execute')
+    .addEdge('execute', 'end')
+    .build();
+    
+  console.log('Main Society Structure (Mermaid):');
+  console.log(companyGraph.toMermaid());
+  
+  // Execute
+  const result = await companyGraph.execute(
+    'Please translate the documentation', 
+    [projectManager, translationAgent]
+  );
+  
+  console.log('\nFinal Output:', result.output);
+}
+
+async function demonstratePatterns(): Promise<void> {
+  console.log('\n=== Patterns Demo ===');
+  
+  // Create a Self-Correction Graph
+  const correctionGraph = PipelinePatterns.selfCorrection(
+    'generator_agent',
+    'validator_agent',
+    3
+  );
+  
+  console.log('Self-Correction Pattern Structure:');
+  console.log(correctionGraph.visualize());
+}
+
+async function main(): Promise<void> {
+  await demonstrateRecursiveSociety();
+  await demonstratePatterns();
+}
+
+main().catch(console.error);

package/examples/complete-integration.ts

@@ -0,0 +1,327 @@
+/**
+ * Example: Complete Integration
+ * 
+ * This example demonstrates all new features working together:
+ * - Graph-based execution
+ * - Tool calling
+ * - Memory system
+ * - Structured output validation
+ * - Metrics tracking
+ */
+
+import {
+  GraphBuilder,
+  NodeType,
+  ToolRegistry,
+  ToolExecutor,
+  ToolBuilder,
+  MemoryBuilder,
+  MemorySystem,
+  StructuredOutputValidator,
+  createSchema,
+  MetricsBuilder,
+  CommonCostConfigs,
+  AgentBuilder,
+  RoleBuilder,
+  StandardModelBase,
+} from '../src';
+
+// Advanced AI Model with all features
+class AdvancedModel extends StandardModelBase {
+  constructor(
+    name: string,
+    private memory: MemorySystem,
+    private toolExecutor: ToolExecutor,
+    private validator?: StructuredOutputValidator
+  ) {
+    super({ name }, async (prompt: unknown) => {
+      const promptStr = typeof prompt === 'string' ? prompt : JSON.stringify(prompt);
+      
+      // Retrieve relevant context from memory
+      const context = await this.memory.retrieve(promptStr, { limit: 3 });
+      
+      // Generate response with context
+      let response = `Based on context:\n${context}\n\n`;
+      
+      if (promptStr.includes('calculate')) {
+        response += '{"tool": "calculator", "parameters": {"expression": "100 * 5"}}';
+      } else if (promptStr.includes('user data')) {
+        response = `{
+  "name": "Alice Johnson",
+  "age": 28,
+  "email": "alice@example.com",
+  "role": "Software Engineer",
+  "skills": ["TypeScript", "React", "Node.js"]
+}`;
+      } else {
+        response += 'Analysis complete. Ready for next step.';
+      }
+      
+      // Store in memory
+      await this.memory.add(response, {
+        type: 'conversation',
+        importance: 0.7,
+      });
+      
+      return response;
+    });
+  }
+}
+
+async function runCompleteExample(): Promise<void> {
+  console.log('=== Complete Integration Example ===\n');
+  console.log('This example combines all new features:\n');
+  console.log('✓ Graph-based workflow execution');
+  console.log('✓ Tool calling capabilities');
+  console.log('✓ Multi-level memory system');
+  console.log('✓ Structured output validation');
+  console.log('✓ Comprehensive metrics tracking\n');
+
+  // 1. Setup Metrics Tracker
+  console.log('--- Setting up Metrics Tracker ---');
+  const tracker = MetricsBuilder.create()
+    .withTokenTracking()
+    .withCostTracking(CommonCostConfigs['gpt-4'])
+    .build();
+  
+  tracker.start('complete-workflow', { scenario: 'user-onboarding' });
+
+  // 2. Setup Memory System
+  console.log('--- Initializing Memory System ---');
+  const memory = MemoryBuilder.create()
+    .withShortTermMemory({ maxMessages: 20 })
+    .withLongTermMemory({ maxEntries: 100 })
+    .build();
+
+  // Add some initial knowledge
+  await memory.add('System supports user onboarding workflow', {
+    type: 'fact',
+    importance: 1.0,
+  });
+  
+  await memory.add('Users must provide name, email, and role', {
+    type: 'fact',
+    importance: 0.9,
+  });
+
+  // Add entity
+  memory.getEntities().upsert('UserOnboardingService', 'service', [
+    'Validates user data',
+    'Stores user profiles',
+    'Sends welcome emails',
+  ]);
+
+  // 3. Setup Tool Registry
+  console.log('--- Registering Tools ---');
+  const toolRegistry = new ToolRegistry();
+  
+  // Calculator tool
+  const calculatorTool = ToolBuilder.create()
+    .withName('calculator')
+    .withDescription('Perform calculations')
+    .withParameters({
+      type: 'object',
+      properties: {
+        expression: { type: 'string' },
+      },
+      required: ['expression'],
+    })
+    .withExecutor(async (params) => {
+      const result = eval(params.expression as string);
+      return { result };
+    })
+    .build();
+
+  // Email sender tool
+  const emailTool = ToolBuilder.create()
+    .withName('send_email')
+    .withDescription('Send email to user')
+    .withParameters({
+      type: 'object',
+      properties: {
+        to: { type: 'string' },
+        subject: { type: 'string' },
+        body: { type: 'string' },
+      },
+      required: ['to', 'subject', 'body'],
+    })
+    .withExecutor(async (params) => {
+      console.log(`  📧 Email sent to ${params.to}`);
+      return { success: true, messageId: 'msg_' + Date.now() };
+    })
+    .build();
+
+  toolRegistry.register(calculatorTool);
+  toolRegistry.register(emailTool);
+
+  const toolExecutor = new ToolExecutor(toolRegistry);
+
+  // 4. Setup Structured Output Validator
+  console.log('--- Configuring Validation Schema ---');
+  const userSchema = createSchema({
+    name: { type: 'string', required: true },
+    age: { type: 'number', required: true },
+    email: { type: 'string', required: true },
+    role: { type: 'string', required: true },
+    skills: { type: 'array', required: false },
+  });
+
+  const validator = new StructuredOutputValidator(userSchema);
+
+  // 5. Create Agents with Advanced Models
+  console.log('--- Creating Intelligent Agents ---');
+  
+  const dataCollectorRole = RoleBuilder.create()
+    .withId('data-collector')
+    .withName('Data Collector')
+    .withSystemPrompt('You collect and validate user data.')
+    .build();
+
+  const validatorRole = RoleBuilder.create()
+    .withId('validator')
+    .withName('Data Validator')
+    .withSystemPrompt('You validate user data against schema.')
+    .build();
+
+  const notifierRole = RoleBuilder.create()
+    .withId('notifier')
+    .withName('Notification Service')
+    .withSystemPrompt('You send notifications to users.')
+    .build();
+
+  const agents = [
+    AgentBuilder.create()
+      .withId('collector-1')
+      .withRole(dataCollectorRole)
+      .withModel(new AdvancedModel('collector-model', memory, toolExecutor, validator))
+      .build(),
+    
+    AgentBuilder.create()
+      .withId('validator-1')
+      .withRole(validatorRole)
+      .withModel(new AdvancedModel('validator-model', memory, toolExecutor, validator))
+      .build(),
+    
+    AgentBuilder.create()
+      .withId('notifier-1')
+      .withRole(notifierRole)
+      .withModel(new AdvancedModel('notifier-model', memory, toolExecutor))
+      .build(),
+  ];
+
+  // 6. Build Execution Graph
+  console.log('--- Building Execution Graph ---');
+  const graph = GraphBuilder.create()
+    .addNode('start', NodeType.START)
+    
+    // Collect user data
+    .addNode('collect', NodeType.AGENT, { agentId: 'collector-1' })
+    
+    // Validate the data
+    .addNode('validate', NodeType.AGENT, { agentId: 'validator-1' })
+    
+    // Check if validation passed
+    .addNode('is-valid', NodeType.CONDITION, {
+      condition: (result) => result.includes('"email"') && result.includes('@'),
+    })
+    
+    // Calculate onboarding bonus (example tool usage)
+    .addNode('calculate-bonus', NodeType.TRANSFORM, {
+      transformer: (result) => {
+        return result + '\nOnboarding bonus: $500';
+      },
+    })
+    
+    // Send welcome email
+    .addNode('notify', NodeType.AGENT, { agentId: 'notifier-1' })
+    
+    // Final formatting
+    .addNode('format', NodeType.TRANSFORM, {
+      transformer: (result) => `✅ User Onboarded Successfully\n\n${result}`,
+    })
+    
+    .addNode('end', NodeType.END)
+    
+    // Connect nodes
+    .addEdge('start', 'collect')
+    .addEdge('collect', 'validate')
+    .addEdge('validate', 'is-valid')
+    
+    .addConditionalEdge({
+      from: 'is-valid',
+      condition: (result) => result.includes('"email"') && result.includes('@'),
+      truePath: 'calculate-bonus',
+      falsePath: 'collect', // Retry data collection
+    })
+    
+    .addEdge('calculate-bonus', 'notify')
+    .addEdge('notify', 'format')
+    .addEdge('format', 'end')
+    
+    .build();
+
+  // 7. Execute the Complete Workflow
+  console.log('\n--- Executing Complete Workflow ---\n');
+  
+  const result = await graph.execute(
+    'Onboard new user: Please collect user data, validate it, and send welcome notification.',
+    agents
+  );
+
+  console.log('\n--- Workflow Results ---');
+  console.log('Output:', result.output);
+  console.log('\nExecution path:', result.executionPath.join(' → '));
+  console.log('Duration:', result.duration, 'ms');
+  console.log('Success:', result.success);
+
+  // 8. Collect and Display Metrics
+  console.log('\n--- Performance Metrics ---');
+  
+  const metrics = tracker.end('complete-workflow', {
+    tokens: {
+      inputTokens: 1200,
+      outputTokens: 800,
+      totalTokens: 2000,
+      model: 'gpt-4',
+    },
+    custom: {
+      nodesExecuted: result.nodeResults.size,
+      toolCalls: 2,
+    },
+  });
+
+  console.log('Total duration:', metrics.execution.duration, 'ms');
+  console.log('Tokens used:', metrics.tokens?.totalTokens);
+  console.log('Estimated cost:', `$${metrics.cost?.totalCost.toFixed(4)}`);
+  console.log('Nodes executed:', metrics.custom?.nodesExecuted);
+
+  // 9. Display Memory State
+  console.log('\n--- Memory State ---');
+  const memoryStats = memory.getStats();
+  console.log('Short-term messages:', memoryStats.shortTerm.messages);
+  console.log('Long-term facts:', memoryStats.longTerm.total);
+  console.log('Entities tracked:', memoryStats.entities.total);
+
+  // 10. Display Recent Conversations
+  console.log('\n--- Recent Memory ---');
+  const recentMemories = memory.getShortTerm().getRecent(3);
+  recentMemories.forEach((mem, idx) => {
+    console.log(`${idx + 1}. ${mem.content.substring(0, 100)}...`);
+  });
+
+  // 11. Export Telemetry
+  console.log('\n--- Exporting Telemetry ---');
+  const otelTraces = tracker.exportOTel();
+  console.log('Generated', otelTraces.length, 'OpenTelemetry traces');
+  console.log('Ready for export to observability platform');
+
+  console.log('\n✅ Complete workflow executed successfully!');
+  console.log('All systems integrated and working together.');
+}
+
+// Run the example
+if (require.main === module) {
+  runCompleteExample().catch(console.error);
+}
+
+export { runCompleteExample };