societyai 0.0.1

package/examples/structured-output.ts

@@ -0,0 +1,231 @@
+/**
+ * Example: Structured Output with Validation
+ * 
+ * This example demonstrates automatic JSON validation with retry logic
+ * to ensure AI outputs match expected schemas.
+ */
+
+import {
+  StructuredOutputBuilder,
+  StructuredOutputValidator,
+  createSchema,
+  validateJSON,
+  JSONSchema,
+  StandardModelBase,
+} from '../src';
+
+// Mock AI Model that generates JSON
+class JSONGeneratingModel extends StandardModelBase {
+  private attemptCount = 0;
+
+  constructor() {
+    super({ name: 'json-generator' }, async (_prompt: unknown) => {
+      this.attemptCount++;
+      
+      // First attempt: Invalid JSON
+      if (this.attemptCount === 1) {
+        return `Here's the user data:
+{
+  "name": "John Doe",
+  "age": "thirty",
+  "email": "invalid-email"
+}`;
+      }
+      
+      // Second attempt: Valid JSON
+      return `{
+  "name": "John Doe",
+  "age": 30,
+  "email": "john@example.com",
+  "isActive": true
+}`;
+    });
+  }
+
+  resetAttempts(): void {
+    this.attemptCount = 0;
+  }
+}
+
+async function runValidationExample(): Promise<void> {
+  console.log('=== Structured Output Validation Example ===\n');
+
+  // Define JSON schema
+  const userSchema: JSONSchema = {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1 },
+      age: { type: 'number', minimum: 0, maximum: 150 },
+      email: { type: 'string', pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$' },
+      isActive: { type: 'boolean' },
+    },
+    required: ['name', 'age', 'email'],
+  };
+
+  console.log('Expected Schema:');
+  console.log(JSON.stringify(userSchema, null, 2));
+  console.log();
+
+  // Create validator
+  const validator = StructuredOutputBuilder.create()
+    .withSchema(userSchema)
+    .withMaxRetries(3)
+    .build();
+
+  // Test 1: Invalid output
+  console.log('--- Test 1: Validating Invalid Output ---');
+  
+  const invalidOutput = `{
+  "name": "John",
+  "age": "thirty",
+  "email": "not-an-email"
+}`;
+
+  const result1 = validator.validate(invalidOutput);
+  console.log('Valid:', result1.valid);
+  
+  if (!result1.valid && result1.errors) {
+    console.log('Errors found:');
+    result1.errors.forEach(err => {
+      console.log(`  - ${err.path}: ${err.message}`);
+      if (err.expected) console.log(`    Expected: ${err.expected}`);
+      if (err.actual) console.log(`    Actual: ${JSON.stringify(err.actual)}`);
+    });
+  }
+
+  // Test 2: Valid output
+  console.log('\n--- Test 2: Validating Valid Output ---');
+  
+  const validOutput = `{
+  "name": "John Doe",
+  "age": 30,
+  "email": "john@example.com",
+  "isActive": true
+}`;
+
+  const result2 = validator.validate(validOutput);
+  console.log('Valid:', result2.valid);
+  
+  if (result2.valid && result2.data) {
+    console.log('Parsed data:', result2.data);
+  }
+
+  // Test 3: Automatic retry with AI model
+  console.log('\n--- Test 3: Automatic Retry with Error Feedback ---');
+  
+  const model = new JSONGeneratingModel();
+  
+  const agentOutput = await model.process('Generate user data');
+  console.log('Initial AI output:');
+  console.log(agentOutput);
+  console.log();
+
+  const result3 = await validator.validateAndRetry(
+    agentOutput,
+    async (errorFeedback) => {
+      console.log('Retry triggered with feedback:');
+      console.log(errorFeedback);
+      console.log();
+      
+      // Agent retries with error feedback
+      return await model.process(`Previous attempt had errors:\n${errorFeedback}\n\nPlease correct and generate valid JSON.`);
+    }
+  );
+
+  console.log('Final validation result:');
+  console.log('Valid:', result3.valid);
+  
+  if (result3.valid && result3.data) {
+    console.log('Successfully parsed data:', result3.data);
+  }
+
+  // Test 4: Quick validation helper
+  console.log('\n--- Test 4: Quick Validation Helper ---');
+  
+  const quickResult = validateJSON(validOutput, userSchema);
+  console.log('Quick validate:', quickResult.valid);
+
+  // Test 5: Create schema from object
+  console.log('\n--- Test 5: Create Schema from Properties ---');
+  
+  const dynamicSchema = createSchema({
+    title: { type: 'string', required: true, description: 'Article title' },
+    content: { type: 'string', required: true, description: 'Article content' },
+    views: { type: 'number', required: false, description: 'View count' },
+    published: { type: 'boolean', required: false, description: 'Publication status' },
+  });
+
+  console.log('Generated schema:');
+  console.log(JSON.stringify(dynamicSchema, null, 2));
+
+  const articleValidator = new StructuredOutputValidator(dynamicSchema);
+  const articleOutput = `{
+  "title": "Understanding TypeScript",
+  "content": "TypeScript is a powerful language...",
+  "views": 1250,
+  "published": true
+}`;
+
+  const articleResult = articleValidator.validate(articleOutput);
+  console.log('\nValidation result:', articleResult.valid);
+  
+  if (articleResult.valid) {
+    console.log('Article data:', articleResult.data);
+  }
+
+  // Test 6: Complex nested schema
+  console.log('\n--- Test 6: Complex Nested Schema ---');
+  
+  const complexSchema: JSONSchema = {
+    type: 'object',
+    properties: {
+      user: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          profile: {
+            type: 'object',
+            properties: {
+              bio: { type: 'string' },
+              location: { type: 'string' },
+            },
+            required: ['bio'],
+          },
+        },
+        required: ['id', 'profile'],
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        minItems: 1,
+      },
+    },
+    required: ['user', 'tags'],
+  };
+
+  const complexOutput = `{
+  "user": {
+    "id": 123,
+    "profile": {
+      "bio": "Software developer",
+      "location": "San Francisco"
+    }
+  },
+  "tags": ["typescript", "javascript", "react"]
+}`;
+
+  const complexValidator = new StructuredOutputValidator(complexSchema);
+  const complexResult = complexValidator.validate(complexOutput);
+  
+  console.log('Complex validation:', complexResult.valid);
+  if (complexResult.valid) {
+    console.log('Complex data:', JSON.stringify(complexResult.data, null, 2));
+  }
+}
+
+// Run the example
+if (require.main === module) {
+  runValidationExample().catch(console.error);
+}
+
+export { runValidationExample };

package/examples/tool-calling.ts

@@ -0,0 +1,163 @@
+/**
+ * Example: Tool Calling System
+ * 
+ * This example demonstrates how agents can use tools to perform
+ * actions like calculations, web searches, and data storage.
+ */
+
+import {
+  ToolBuilder,
+  ToolRegistry,
+  ToolExecutor,
+  BuiltInTools,
+  AgentBuilder,
+  RoleBuilder,
+  StandardModelBase,
+} from '../src';
+
+// Mock AI Model that calls tools
+class ToolCallingModel extends StandardModelBase {
+  constructor() {
+    super({ name: 'tool-caller' }, async (prompt: unknown) => {
+      const promptStr = typeof prompt === 'string' ? prompt : JSON.stringify(prompt);
+      
+      // Simulate tool calling
+      if (promptStr.includes('calculate')) {
+        return JSON.stringify({
+          tool: 'calculator',
+          parameters: { expression: '125 * 8 + 42' }
+        });
+      } else if (promptStr.includes('previous output')) {
+        return 'The calculation result is 1042. This is the answer to your question.';
+      }
+      
+      return 'I can help you with calculations, string manipulation, and data storage.';
+    });
+  }
+}
+
+async function runToolExample(): Promise<void> {
+  console.log('=== Tool Calling Example ===\n');
+
+  // Create tool registry
+  const registry = new ToolRegistry();
+
+  // Register built-in tools
+  registry.register(BuiltInTools.calculator());
+  registry.register(BuiltInTools.stringManipulation());
+  registry.register(BuiltInTools.storage());
+
+  // Create a custom tool
+  const webSearchTool = ToolBuilder.create()
+    .withName('web_search')
+    .withDescription('Search the web for information')
+    .withParameters({
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        maxResults: { type: 'number', description: 'Max results', default: 5 },
+      },
+      required: ['query'],
+    })
+    .withExecutor(async (params) => {
+      // Simulate web search
+      const query = params.query as string;
+      return {
+        results: [
+          { title: `Result 1 for "${query}"`, url: 'https://example.com/1' },
+          { title: `Result 2 for "${query}"`, url: 'https://example.com/2' },
+        ],
+      };
+    })
+    .build();
+
+  registry.register(webSearchTool);
+
+  console.log('Registered tools:', registry.getAll().map(t => t.name).join(', '));
+  console.log();
+
+  // Create tool executor
+  const executor = new ToolExecutor(registry);
+
+  // Create agent with tools
+  const model = new ToolCallingModel();
+  const agentRole = RoleBuilder.create()
+    .withId('assistant')
+    .withName('Tool-Using Assistant')
+    .withSystemPrompt('You are an assistant that can use tools to help users.')
+    .build();
+
+  const agent = AgentBuilder.create()
+    .withId('assistant-1')
+    .withRole(agentRole)
+    .withModel(model)
+    .build();
+
+  // Agent executor function
+  const agentExecutor = async (input: string): Promise<string> => {
+    const prompt = agent.role.promptTemplate?.replace('{input}', input) || input;
+    return await agent.model.process(prompt);
+  };
+
+  // Execute agent with tool calling loop
+  console.log('Query: What is 125 * 8 + 42?\n');
+  
+  const result = await executor.executeWithTools(
+    agentExecutor,
+    'What is 125 * 8 + 42? Please calculate it.',
+    undefined,
+    5 // max iterations
+  );
+
+  console.log('Final output:', result.output);
+  console.log('\nTool calls made:', result.toolResults.length);
+  
+  for (const toolResult of result.toolResults) {
+    console.log(`- ${toolResult.tool}: ${toolResult.success ? '✓' : '✗'}`);
+    if (toolResult.result) {
+      console.log(`  Result:`, toolResult.result);
+    }
+  }
+
+  // Test string manipulation tool
+  console.log('\n--- String Manipulation ---');
+  
+  const stringResult = await registry.execute({
+    name: 'string_manipulation',
+    parameters: {
+      text: 'Hello World',
+      operation: 'reverse',
+    },
+  });
+
+  console.log('Reverse "Hello World":', stringResult.result);
+
+  // Test storage tool
+  console.log('\n--- Data Storage ---');
+  
+  await registry.execute({
+    name: 'storage',
+    parameters: {
+      operation: 'set',
+      key: 'user_preference',
+      value: 'dark_mode',
+    },
+  });
+
+  const storedValue = await registry.execute({
+    name: 'storage',
+    parameters: {
+      operation: 'get',
+      key: 'user_preference',
+    },
+  });
+
+  console.log('Stored value:', storedValue.result);
+}
+
+// Run the example
+if (require.main === module) {
+  runToolExample().catch(console.error);
+}
+
+export { runToolExample };

package/package.json

@@ -0,0 +1,94 @@
+{
+    "name": "societyai",
+    "version": "0.0.1",
+    "description": "A powerful TypeScript library for creating collaborative multi-agent AI systems. Build sophisticated workflows where AI agents with different roles work together to solve complex problems.",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "module": "dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "require": "./dist/index.js",
+            "import": "./dist/index.js"
+        }
+    },
+    "engines": {
+        "node": ">=16.0.0",
+        "npm": ">=7.0.0"
+    },
+    "scripts": {
+        "build": "tsc",
+        "build:watch": "tsc --watch",
+        "watch": "tsc --watch",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage",
+        "lint": "eslint src --ext .ts",
+        "lint:fix": "eslint src --ext .ts --fix",
+        "format": "prettier --write \"src/**/*.ts\"",
+        "format:check": "prettier --check \"src/**/*.ts\"",
+        "typecheck": "tsc --noEmit",
+        "validate": "npm run typecheck && npm run lint && npm run test",
+        "prepare": "npm run build",
+        "prepublishOnly": "npm run validate && npm run build",
+        "prepack": "npm run build",
+        "check": "node scripts/check-package.js",
+        "clean": "rm -rf dist",
+        "clean:all": "rm -rf dist node_modules package-lock.json"
+    },
+    "keywords": [
+        "ai",
+        "artificial-intelligence",
+        "agents",
+        "multi-agent",
+        "multi-agent-systems",
+        "collaboration",
+        "llm",
+        "large-language-models",
+        "prompt",
+        "prompt-engineering",
+        "society",
+        "workflow",
+        "orchestration",
+        "typescript",
+        "openai",
+        "anthropic",
+        "claude",
+        "gpt",
+        "chatgpt",
+        "model-agnostic",
+        "rag",
+        "memory",
+        "tools",
+        "function-calling"
+    ],
+    "author": "Benoit Petit <contact@societyai.dev> (https://github.com/benoitpetit)",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/jest": "^29.5.11",
+        "@types/node": "^20.10.6",
+        "@typescript-eslint/eslint-plugin": "^6.17.0",
+        "@typescript-eslint/parser": "^6.17.0",
+        "eslint": "^8.56.0",
+        "jest": "^29.7.0",
+        "prettier": "^3.1.1",
+        "ts-jest": "^29.1.1",
+        "typescript": "^5.3.3"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md",
+        "docs",
+        "examples"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/benoitpetit/societyai"
+    },
+    "bugs": {
+        "url": "https://github.com/benoitpetit/societyai/issues"
+    },
+    "homepage": "https://github.com/benoitpetit/societyai#readme"
+}