@mah-sdk/orchestrator

Multi-Agent Hierarchy Orchestrator — a pluggable, provider-agnostic multi-agent AI task execution engine.

Features

• Provider-agnostic: Built-in Anthropic + OpenAI adapters, or bring your own via IAIProvider
• Consumer-defined hierarchy: Define 2–50 agents in any structure. Engine validates and operates.
• File processing: PDF, Word, Excel, CSV, text, and OCR (6 built-in processors)
• Auto-migration: 10-table PostgreSQL schema, created automatically on init()
• Validation cascade: Tier 1 mechanical checks + Tier 2 cross-model semantic validation (premium)
• Audit everything: Every operation logged with timestamp, agent, task, and detail

Quick Start

npm install @mah-sdk/orchestrator

import { init, AnthropicAdapter } from '@mah-sdk/orchestrator';

const orchestrator = await init({
  db: {
    host: 'localhost',
    port: 5432,
    database: 'mah',
    user: 'postgres',
    password: 'secret',
    ssl: false,
  },
  ai: {
    primary: {
      adapter: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: 'claude-sonnet-4-5-20250929',
      }),
    },
  },
});

const result = await orchestrator.processInstruction('Generate a privacy policy');
console.log(result.status, result.output);

Custom Hierarchy

const orchestrator = await init({
  db: { /* ... */ },
  ai: { /* ... */ },
  hierarchy: [
    { id: 'classifier', displayName: 'Classifier', level: 'L1', reportsTo: null, agentConfig: { role_definition: 'Classify tasks', /* ... */ } },
    { id: 'executor', displayName: 'Executor', level: 'L2', reportsTo: 'classifier', agentConfig: { role_definition: 'Execute tasks', /* ... */ } },
    { id: 'validator', displayName: 'Validator', level: 'L2', reportsTo: 'classifier', agentConfig: { role_definition: 'Validate output', /* ... */ } },
  ],
});

File Processing

const result = await orchestrator.processInstruction('Review this contract', {
  files: [{ path: '/uploads/contract.pdf', name: 'contract.pdf', mimeType: 'application/pdf' }],
});

Optional peer dependencies for file processing:

• pdf-parse — PDF extraction
• mammoth — Word document extraction
• xlsx — Excel spreadsheet extraction
• tesseract.js — OCR for images

Install only what you need: npm install pdf-parse mammoth

CLI

npx @mah-sdk/orchestrator health
npx @mah-sdk/orchestrator migrate:status
npx @mah-sdk/orchestrator version

License

MIT — see LICENSE

Premium features available under commercial license. See LICENSE-COMMERCIAL.