societyai 0.0.1

package/examples/graph-workflow.ts

@@ -0,0 +1,161 @@
+/**
+ * Example: Using SocietyGraph for Complex Workflows
+ * 
+ * This example demonstrates how to use the graph-based execution engine
+ * to create a sophisticated code review workflow with conditional branching,
+ * loops, and parallel execution.
+ */
+
+import {
+  GraphBuilder,
+  NodeType,
+  AgentBuilder,
+  RoleBuilder,
+  StandardModelBase,
+} from '../src';
+
+// Mock AI Model for demonstration
+class MockModel extends StandardModelBase {
+  constructor(name: string) {
+    super({ name }, async (prompt: unknown) => {
+      // Simulate AI response
+      const promptStr = typeof prompt === 'string' ? prompt : JSON.stringify(prompt);
+      
+      if (promptStr.includes('analyze')) {
+        return 'The code looks good but needs better error handling.';
+      } else if (promptStr.includes('valid')) {
+        return 'valid: true\nThe improvements have been applied successfully.';
+      } else if (promptStr.includes('fix')) {
+        return 'Added try-catch blocks and improved error messages.';
+      }
+      
+      return 'Task completed successfully.';
+    });
+  }
+}
+
+async function runGraphExample(): Promise<void> {
+  console.log('=== Graph-Based Workflow Example ===\n');
+
+  // Create AI models
+  const model = new MockModel('code-analyzer');
+
+  // Create agent roles
+  const analyzerRole = RoleBuilder.create()
+    .withId('analyzer')
+    .withName('Code Analyzer')
+    .withSystemPrompt('You analyze code and identify issues.')
+    .build();
+
+  const fixerRole = RoleBuilder.create()
+    .withId('fixer')
+    .withName('Code Fixer')
+    .withSystemPrompt('You fix code issues.')
+    .build();
+
+  const validatorRole = RoleBuilder.create()
+    .withId('validator')
+    .withName('Code Validator')
+    .withSystemPrompt('You validate code fixes.')
+    .build();
+
+  // Create agents
+  const agents = [
+    AgentBuilder.create()
+      .withId('analyzer-1')
+      .withRole(analyzerRole)
+      .withModel(model)
+      .build(),
+    AgentBuilder.create()
+      .withId('fixer-1')
+      .withRole(fixerRole)
+      .withModel(model)
+      .build(),
+    AgentBuilder.create()
+      .withId('validator-1')
+      .withRole(validatorRole)
+      .withModel(model)
+      .build(),
+  ];
+
+  // Build the graph
+  const graph = GraphBuilder.create()
+    // Start node
+    .addNode('start', NodeType.START)
+    
+    // Analyze the code
+    .addNode('analyze', NodeType.AGENT, { agentId: 'analyzer-1' })
+    
+    // Conditional: Does it need fixing?
+    .addNode('needs-fix', NodeType.CONDITION, {
+      condition: (result) => !result.includes('looks good'),
+    })
+    
+    // Fix the code
+    .addNode('fix', NodeType.AGENT, { agentId: 'fixer-1' })
+    
+    // Validate the fix
+    .addNode('validate', NodeType.AGENT, { agentId: 'validator-1' })
+    
+    // Conditional: Is it valid?
+    .addNode('is-valid', NodeType.CONDITION, {
+      condition: (result) => result.includes('valid: true'),
+    })
+    
+    // Transform for final output
+    .addNode('format', NodeType.TRANSFORM, {
+      transformer: (result) => `✓ Code Review Complete:\n${result}`,
+    })
+    
+    // End node
+    .addNode('end', NodeType.END)
+    
+    // Connect the nodes
+    .addEdge('start', 'analyze')
+    .addEdge('analyze', 'needs-fix')
+    
+    // Conditional edges
+    .addConditionalEdge({
+      from: 'needs-fix',
+      condition: (result) => !result.includes('looks good'),
+      truePath: 'fix',
+      falsePath: 'format',
+    })
+    
+    .addEdge('fix', 'validate')
+    .addEdge('validate', 'is-valid')
+    
+    // Loop back if validation fails (max 3 iterations)
+    .addConditionalEdge({
+      from: 'is-valid',
+      condition: (result) => result.includes('valid: true'),
+      truePath: 'format',
+      falsePath: 'fix',
+    })
+    
+    .addEdge('format', 'end')
+    
+    .build();
+
+  // Execute the graph
+  console.log('Visualizing graph structure:');
+  console.log(graph.visualize());
+  console.log('\nExecuting workflow...\n');
+
+  const result = await graph.execute(
+    'Analyze this TypeScript function for potential issues',
+    agents
+  );
+
+  console.log('Result:', result.output);
+  console.log('\nExecution path:', result.executionPath.join(' → '));
+  console.log('Duration:', result.duration, 'ms');
+  console.log('Success:', result.success);
+}
+
+// Run the example
+if (require.main === module) {
+  runGraphExample().catch(console.error);
+}
+
+export { runGraphExample };

package/examples/memory-system.ts

@@ -0,0 +1,155 @@
+/**
+ * Example: Memory System
+ * 
+ * This example demonstrates the multi-level memory system including
+ * short-term, long-term, and entity memory.
+ */
+
+import {
+  MemoryBuilder,
+} from '../src';
+
+async function runMemoryExample(): Promise<void> {
+  console.log('=== Memory System Example ===\n');
+
+  // Create memory system
+  const memory = MemoryBuilder.create()
+    .withShortTermMemory({
+      maxMessages: 10,
+      summarizeAfter: 20,
+      decayRate: 0.1,
+    })
+    .withLongTermMemory({
+      maxEntries: 100,
+    })
+    .build();
+
+  console.log('--- Short-Term Memory ---');
+  
+  // Add conversation history
+  await memory.add('User asked about TypeScript features', {
+    type: 'conversation',
+    importance: 0.7,
+  });
+
+  await memory.add('Explained TypeScript generics', {
+    type: 'conversation',
+    importance: 0.8,
+  });
+
+  await memory.add('User wants to learn about decorators', {
+    type: 'conversation',
+    importance: 0.9,
+  });
+
+  const shortTerm = memory.getShortTerm();
+  const recentMemories = shortTerm.getRecent(5);
+  
+  console.log(`Recent memories: ${recentMemories.length}`);
+  recentMemories.forEach(m => {
+    console.log(`- ${m.content} (importance: ${m.importance?.toFixed(2)})`);
+  });
+
+  console.log('\n--- Long-Term Memory ---');
+  
+  // Add facts to long-term memory
+  await memory.add('TypeScript is a typed superset of JavaScript', {
+    type: 'fact',
+    importance: 1.0,
+  });
+
+  await memory.add('TypeScript compiles to plain JavaScript', {
+    type: 'fact',
+    importance: 0.9,
+  });
+
+  await memory.add('Generics provide type-safe reusable components', {
+    type: 'fact',
+    importance: 0.8,
+  });
+
+  // Retrieve relevant facts
+  const context = await memory.retrieve('TypeScript generics', {
+    includeShortTerm: true,
+    includeLongTerm: true,
+    limit: 3,
+  });
+
+  console.log('Retrieved context for "TypeScript generics":');
+  console.log(context);
+
+  console.log('\n--- Entity Memory ---');
+  
+  const entities = memory.getEntities();
+
+  // Add entities
+  entities.upsert('John Doe', 'person', [
+    'Prefers TypeScript over JavaScript',
+    'Learning about decorators',
+    'Works as a software engineer',
+  ]);
+
+  entities.upsert('React', 'framework', [
+    'Popular UI library',
+    'Works well with TypeScript',
+    'Uses JSX syntax',
+  ]);
+
+  entities.upsert('TypeScript', 'language', [
+    'Statically typed',
+    'Compiles to JavaScript',
+    'Developed by Microsoft',
+  ]);
+
+  // Search entities
+  const foundEntities = entities.search('TypeScript');
+  console.log(`Found ${foundEntities.length} entities related to "TypeScript":`);
+  
+  foundEntities.forEach(entity => {
+    console.log(`\n${entity.name} (${entity.type}):`);
+    entity.facts.forEach(fact => console.log(`  - ${fact}`));
+  });
+
+  // Get entity by type
+  const people = entities.getByType('person');
+  console.log(`\n${people.length} person entities:`);
+  people.forEach(p => console.log(`- ${p.name}`));
+
+  console.log('\n--- Memory Statistics ---');
+  
+  const stats = memory.getStats();
+  console.log('Short-term messages:', stats.shortTerm.messages);
+  console.log('Long-term total:', stats.longTerm.total);
+  console.log('Long-term by type:', stats.longTerm.byType);
+  console.log('Entities total:', stats.entities.total);
+  console.log('Entities by type:', stats.entities.byType);
+
+  console.log('\n--- Advanced: Importance Decay ---');
+  
+  // Simulate time passing
+  shortTerm.applyDecay();
+  
+  const decayedMemories = shortTerm.getRecent(5);
+  console.log('After decay:');
+  decayedMemories.forEach(m => {
+    console.log(`- ${m.content} (importance: ${m.importance?.toFixed(2)})`);
+  });
+
+  console.log('\n--- Advanced: Entity Updates ---');
+  
+  // Update existing entity with new facts
+  entities.upsert('John Doe', 'person', [
+    'Completed TypeScript decorators tutorial',
+  ]);
+
+  const john = entities.get('John Doe', 'person');
+  console.log(`\nJohn Doe's facts (${john?.facts.length} total):`);
+  john?.facts.forEach(fact => console.log(`  - ${fact}`));
+}
+
+// Run the example
+if (require.main === module) {
+  runMemoryExample().catch(console.error);
+}
+
+export { runMemoryExample };

package/examples/metrics-tracking.ts

@@ -0,0 +1,243 @@
+/**
+ * Example: Metrics and Observability
+ * 
+ * This example demonstrates comprehensive tracking of token usage,
+ * execution time, costs, and OpenTelemetry-compatible trace export.
+ */
+
+import {
+  MetricsBuilder,
+  MetricsTracker,
+  TokenCounter,
+  PerformanceProfiler,
+  CommonCostConfigs,
+  StandardModelBase,
+} from '../src';
+
+// Example model with token tracking (for reference)
+// This class demonstrates how to integrate metrics tracking into a custom model
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class TrackedModel extends StandardModelBase {
+  constructor(name: string, private tracker: MetricsTracker) {
+    super({ name }, async (prompt: unknown) => {
+      const promptStr = typeof prompt === 'string' ? prompt : JSON.stringify(prompt);
+      
+      // Simulate processing
+      await new Promise(resolve => setTimeout(resolve, 100));
+      
+      const response = `Processed: ${promptStr.substring(0, 50)}...`;
+      
+      // Track tokens
+      // Count tokens for tracking
+      // const tokens = TokenCounter.count(promptStr, response);
+      
+      return response;
+    });
+  }
+}
+
+async function runMetricsExample(): Promise<void> {
+  console.log('=== Metrics and Observability Example ===\n');
+
+  // Create metrics tracker
+  const tracker = MetricsBuilder.create()
+    .withTokenTracking()
+    .withCostTracking(CommonCostConfigs['gpt-4'])
+    .withCostTracking(CommonCostConfigs['claude-3-sonnet'])
+    .build();
+
+  console.log('--- Basic Tracking ---');
+  
+  // Start tracking a workflow
+  tracker.start('workflow-1', { userId: 'user123', task: 'analysis' });
+  
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 150));
+  
+  // End tracking with token metrics
+  const snapshot1 = tracker.end('workflow-1', {
+    tokens: {
+      inputTokens: 500,
+      outputTokens: 300,
+      totalTokens: 800,
+      model: 'gpt-4',
+    },
+    custom: {
+      apiCalls: 3,
+      cacheHits: 1,
+    },
+  });
+
+  console.log('Workflow completed:');
+  console.log('- Duration:', snapshot1.execution.duration, 'ms');
+  console.log('- Tokens:', snapshot1.tokens?.totalTokens);
+  console.log('- Estimated cost:', `$${snapshot1.cost?.totalCost.toFixed(4)}`);
+  console.log('- Custom metrics:', snapshot1.custom);
+
+  // Track multiple workflows
+  console.log('\n--- Multiple Workflows ---');
+  
+  for (let i = 0; i < 3; i++) {
+    tracker.start(`agent-${i}`);
+    await new Promise(resolve => setTimeout(resolve, Math.random() * 100));
+    
+    tracker.end(`agent-${i}`, {
+      tokens: {
+        inputTokens: Math.floor(Math.random() * 500) + 100,
+        outputTokens: Math.floor(Math.random() * 300) + 50,
+        totalTokens: 0,
+        model: 'claude-3-sonnet',
+      },
+    });
+  }
+
+  // Get aggregated metrics
+  const aggregated = tracker.getAggregated();
+  
+  console.log('Aggregated metrics:');
+  console.log('- Total executions:', aggregated.totalExecutions);
+  console.log('- Successful:', aggregated.successfulExecutions);
+  console.log('- Average duration:', aggregated.averageDuration.toFixed(2), 'ms');
+  console.log('- Total tokens:', aggregated.totalTokens);
+  console.log('- Total cost:', `$${aggregated.totalCost?.toFixed(4)}`);
+
+  // Track failure
+  console.log('\n--- Failure Tracking ---');
+  
+  tracker.start('failing-workflow');
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  try {
+    throw new Error('Simulated failure');
+  } catch (error) {
+    tracker.fail('failing-workflow', error as Error);
+  }
+
+  const failedMetrics = tracker.getAggregated();
+  console.log('Failed executions:', failedMetrics.failedExecutions);
+
+  // Performance profiling
+  console.log('\n--- Performance Profiling ---');
+  
+  const profiler = new PerformanceProfiler();
+  
+  profiler.mark('start');
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  profiler.mark('phase-1-complete');
+  await new Promise(resolve => setTimeout(resolve, 75));
+  
+  profiler.mark('phase-2-complete');
+  await new Promise(resolve => setTimeout(resolve, 25));
+  
+  profiler.mark('end');
+  
+  const phase1Duration = profiler.measure('phase-1', 'start', 'phase-1-complete');
+  const phase2Duration = profiler.measure('phase-2', 'phase-1-complete', 'phase-2-complete');
+  const totalDuration = profiler.measure('total', 'start', 'end');
+  
+  console.log('Phase 1 duration:', phase1Duration, 'ms');
+  console.log('Phase 2 duration:', phase2Duration, 'ms');
+  console.log('Total duration:', totalDuration, 'ms');
+  
+  console.log('\nAll measures:', profiler.getMeasures());
+
+  // Token estimation
+  console.log('\n--- Token Estimation ---');
+  
+  const text1 = 'This is a short text message.';
+  const text2 = 'This is a much longer text message with more content and details that will result in more tokens being counted.';
+  
+  console.log('Text 1 estimated tokens:', TokenCounter.estimate(text1));
+  console.log('Text 2 estimated tokens:', TokenCounter.estimate(text2));
+  
+  const promptTokens = TokenCounter.count(text2, text1);
+  console.log('Prompt + response tokens:', promptTokens);
+
+  // Export metrics
+  console.log('\n--- Metrics Export ---');
+  
+  const jsonExport = tracker.export();
+  console.log('JSON export length:', jsonExport.length, 'characters');
+  console.log('(Truncated preview):', jsonExport.substring(0, 200), '...');
+
+  // OpenTelemetry export
+  const otelTraces = tracker.exportOTel();
+  console.log('\nOpenTelemetry traces:', otelTraces.length);
+  console.log('Sample trace:');
+  console.log({
+    name: otelTraces[0]?.name,
+    duration: otelTraces[0]?.endTimeUnixNano - otelTraces[0]?.startTimeUnixNano,
+    status: otelTraces[0]?.status.code,
+    attributes: Object.keys(otelTraces[0]?.attributes || {}),
+  });
+
+  // Filter history
+  console.log('\n--- Filtered History ---');
+  
+  const workflow1History = tracker.getHistory({ id: 'workflow-1' });
+  console.log('Workflow-1 executions:', workflow1History.length);
+  
+  const successfulHistory = tracker.getHistory({ success: true });
+  console.log('Successful executions:', successfulHistory.length);
+  
+  const failedHistory = tracker.getHistory({ success: false });
+  console.log('Failed executions:', failedHistory.length);
+
+  // Per-agent breakdown
+  console.log('\n--- Per-Agent Breakdown ---');
+  
+  const byAgent = aggregated.byAgent;
+  if (byAgent) {
+    for (const [agentId, snapshots] of Object.entries(byAgent)) {
+      console.log(`\n${agentId}:`);
+      console.log(`  - Executions: ${snapshots.length}`);
+      
+      const totalDuration = snapshots.reduce((sum, s) => sum + (s.execution.duration || 0), 0);
+      console.log(`  - Total duration: ${totalDuration}ms`);
+      
+      const totalTokens = snapshots.reduce((sum, s) => sum + (s.tokens?.totalTokens || 0), 0);
+      if (totalTokens > 0) {
+        console.log(`  - Total tokens: ${totalTokens}`);
+      }
+      
+      const totalCost = snapshots.reduce((sum, s) => sum + (s.cost?.totalCost || 0), 0);
+      if (totalCost > 0) {
+        console.log(`  - Total cost: $${totalCost.toFixed(4)}`);
+      }
+    }
+  }
+
+  // Cost comparison across models
+  console.log('\n--- Cost Comparison ---');
+  
+  const models = [
+    { name: 'gpt-4', tokens: 1000 },
+    { name: 'gpt-4-turbo', tokens: 1000 },
+    { name: 'gpt-3.5-turbo', tokens: 1000 },
+    { name: 'claude-3-opus', tokens: 1000 },
+    { name: 'claude-3-sonnet', tokens: 1000 },
+  ];
+
+  console.log('Cost for 1000 tokens (500 input + 500 output):');
+  
+  for (const model of models) {
+    const config = CommonCostConfigs[model.name as keyof typeof CommonCostConfigs];
+    if (config) {
+      const inputCost = (500 / 1000) * config.inputCostPer1K;
+      const outputCost = (500 / 1000) * config.outputCostPer1K;
+      const totalCost = inputCost + outputCost;
+      
+      console.log(`- ${model.name}: $${totalCost.toFixed(4)}`);
+    }
+  }
+}
+
+// Run the example
+if (require.main === module) {
+  (async (): Promise<void> => {
+    await runMetricsExample().catch(console.error);
+  })();
+}
+
+export { runMetricsExample };