@neural-trader/agentic-accounting-agents

🤖 Multi-Agent Swarm for Autonomous Accounting

@neural-trader/agentic-accounting-agents provides specialized autonomous agents for accounting automation with agentic-flow coordination. Deploy intelligent swarms that learn, adapt, and optimize accounting operations with 84.8% solve rate and 32.3% token reduction.

Leverage ReasoningBank learning, BullMQ job queues, and distributed coordination to automate tax calculations, compliance monitoring, fraud detection, and reporting at scale.

✨ Features

• 🤖 7 Specialized Agents - Tax compute, ingestion, compliance, forensic, reporting, harvesting, and learning
• 🧠 ReasoningBank Integration - Adaptive learning from past decisions with trajectory tracking
• 🔄 Agentic-Flow Coordination - Multi-agent orchestration with dynamic task allocation
• 📊 Performance Tracking - Real-time metrics, decision logging, and success/failure analysis
• 🔐 Base Agent Framework - Extensible foundation with events, error handling, and observability
• ⚡ Job Queue Support - BullMQ integration for distributed task processing
• 🎯 Priority Scheduling - Task prioritization (low/medium/high/critical)
• 🗄️ AgentDB Memory - Vector-based memory coordination across agents
• 📈 Swarm Patterns - Hierarchical, mesh, and adaptive coordination topologies
• 🔍 Decision Auditability - Complete audit trail of agent decisions and outcomes

🎯 Benefits

Why Use Multi-Agent Accounting?

• Autonomous Operation: Agents work independently and collaboratively without human intervention
• Continuous Learning: ReasoningBank adapts to your patterns and improves over time
• Fault Tolerance: Swarm coordination ensures resilience against individual agent failures
• Scalability: Distribute workload across multiple agents for parallel processing
• Specialization: Each agent is optimized for specific accounting tasks
• Observability: Full visibility into agent decisions, performance, and outcomes

📦 Quick Start

Installation

npm install @neural-trader/agentic-accounting-agents

Basic Usage

import {
  TaxComputeAgent,
  IngestionAgent,
  ComplianceAgent,
  HarvestAgent
} from '@neural-trader/agentic-accounting-agents';

// 1. Create specialized agents
const taxAgent = new TaxComputeAgent('tax-001');
const ingestionAgent = new IngestionAgent('ingest-001');
const complianceAgent = new ComplianceAgent('compliance-001');
const harvestAgent = new HarvestAgent('harvest-001');

// 2. Start agents
await Promise.all([
  taxAgent.start(),
  ingestionAgent.start(),
  complianceAgent.start(),
  harvestAgent.start()
]);

// 3. Execute tasks in parallel
const results = await Promise.all([
  // Ingest transactions
  ingestionAgent.execute({
    taskId: 'ingest-001',
    description: 'Ingest Coinbase transactions',
    priority: 'high',
    data: { source: 'coinbase', startDate: '2024-01-01', endDate: '2024-12-31' }
  }),

  // Calculate taxes
  taxAgent.execute({
    taskId: 'tax-001',
    description: 'Calculate tax liabilities',
    priority: 'high',
    data: { sale, lots, compareAll: true }
  }),

  // Check compliance
  complianceAgent.execute({
    taskId: 'compliance-001',
    description: 'Validate compliance',
    priority: 'medium',
    data: { transactions, jurisdiction: 'US' }
  }),

  // Find harvesting opportunities
  harvestAgent.execute({
    taskId: 'harvest-001',
    description: 'Scan for tax-loss harvesting',
    priority: 'medium',
    data: { positions, currentPrices, taxRate: 0.35 }
  })
]);

// 4. Check results
results.forEach(result => {
  if (result.success) {
    console.log('Agent task completed:', result.data);
    console.log('Duration:', result.metrics?.duration, 'ms');
  } else {
    console.error('Agent task failed:', result.error);
  }
});

// 5. Stop agents
await Promise.all([
  taxAgent.stop(),
  ingestionAgent.stop(),
  complianceAgent.stop(),
  harvestAgent.stop()
]);

📚 Detailed Tutorial

Step 1: Understanding the Base Agent

All agents extend the BaseAgent class, which provides:

import { BaseAgent, AgentConfig, AgentTask, AgentResult } from '@neural-trader/agentic-accounting-agents';

// Every agent has this structure
class CustomAgent extends BaseAgent {
  constructor(agentId: string) {
    super({
      agentId,
      agentType: 'CUSTOM',
      enableLearning: true,
      enableMetrics: true,
      logLevel: 'info'
    });
  }

  // Must implement execute method
  async execute(task: AgentTask): Promise<AgentResult> {
    return await this.executeWithMetrics(async () => {
      // Your agent logic here

      // Log decisions for ReasoningBank
      await this.logDecision(
        'scenario',
        'decision',
        'rationale',
        'SUCCESS'
      );

      return { /* your result */ };
    });
  }
}

Step 2: Tax Compute Agent

The TaxComputeAgent handles all tax calculation methods with intelligent strategy selection.

import { TaxComputeAgent } from '@neural-trader/agentic-accounting-agents';
import { Transaction, TaxLot } from '@neural-trader/agentic-accounting-types';

const taxAgent = new TaxComputeAgent('tax-001');
await taxAgent.start();

// Execute tax calculation
const result = await taxAgent.execute({
  taskId: 'calc-001',
  description: 'Calculate capital gains',
  priority: 'high',
  data: {
    sale: {
      id: 'sale-001',
      asset: 'BTC',
      type: 'SELL',
      quantity: '1.5',
      price: '45000',
      timestamp: new Date(),
      // ... other transaction fields
    },
    lots: [
      {
        id: 'lot-001',
        asset: 'BTC',
        quantity: '1.0',
        costBasis: '30000',
        acquisitionDate: new Date('2023-01-01'),
        // ... other lot fields
      },
      // ... more lots
    ],
    compareAll: true,          // Compare all methods
    enableCache: true,         // Cache results
    detectWashSales: true      // Check wash sale violations
  }
});

if (result.success) {
  const calc = result.data.calculation;
  console.log(`Method: ${calc.method}`);
  console.log(`Disposals: ${calc.disposals.length}`);
  console.log(`Net gain/loss: $${calc.netGainLoss}`);
  console.log(`Short-term: $${calc.shortTermGainLoss}`);
  console.log(`Long-term: $${calc.longTermGainLoss}`);

  // Check comparison if requested
  if (result.data.comparison) {
    console.log(`Best method: ${result.data.comparison.best}`);
    console.log(`Savings: $${result.data.comparison.savings}`);
  }

  // Check wash sales
  if (result.data.washSales && result.data.washSales.length > 0) {
    console.warn(`Wash sale violations: ${result.data.washSales.length}`);
  }
}

// Get agent status
const status = taxAgent.getExtendedStatus();
console.log(`Agent: ${status.agentId}`);
console.log(`Cache hits: ${status.cache.hits}`);
console.log(`Decisions logged: ${status.decisionCount}`);

Step 3: Ingestion Agent

The IngestionAgent autonomously ingests transactions from multiple sources.

import { IngestionAgent } from '@neural-trader/agentic-accounting-agents';

const ingestionAgent = new IngestionAgent('ingest-001');
await ingestionAgent.start();

// Ingest from Coinbase
const coinbaseResult = await ingestionAgent.execute({
  taskId: 'coinbase-001',
  description: 'Ingest Coinbase Q4 2024',
  priority: 'high',
  data: {
    source: 'coinbase',
    config: {
      apiKey: process.env.COINBASE_API_KEY,
      apiSecret: process.env.COINBASE_API_SECRET,
      startDate: '2024-10-01',
      endDate: '2024-12-31'
    },
    batchSize: 1000,
    validateOnIngestion: true
  }
});

// Ingest from CSV
const csvResult = await ingestionAgent.execute({
  taskId: 'csv-001',
  description: 'Ingest manual transactions',
  priority: 'medium',
  data: {
    source: 'csv',
    filePath: './transactions.csv',
    mapping: {
      date: 'timestamp',
      symbol: 'asset',
      amount: 'quantity',
      price: 'price',
      type: 'type'
    }
  }
});

// Agent learns from ingestion patterns
const decisions = ingestionAgent.getRecentDecisions();
decisions.forEach(d => {
  console.log(`${d.scenario}: ${d.decision} (${d.outcome})`);
});

Step 4: Compliance Agent

The ComplianceAgent monitors transactions for regulatory compliance in real-time.

import { ComplianceAgent } from '@neural-trader/agentic-accounting-agents';

const complianceAgent = new ComplianceAgent('compliance-001');
await complianceAgent.start();

// Monitor compliance
const result = await complianceAgent.execute({
  taskId: 'compliance-001',
  description: 'Monitor US compliance',
  priority: 'critical',
  data: {
    transactions,
    jurisdiction: 'US',
    level: 'federal',
    region: 'CA',
    enableRealtime: true,
    alertThreshold: 'medium'
  }
});

// Listen for violations
complianceAgent.on('violation', (violation) => {
  console.warn('COMPLIANCE VIOLATION:', violation);

  if (violation.severity === 'critical') {
    // Send immediate alert
    sendSlackAlert(violation);
  }
});

// Get violation summary
if (result.success) {
  const summary = result.data.summary;
  console.log(`Violations: ${summary.totalViolations}`);
  console.log(`Critical: ${summary.criticalCount}`);
  console.log(`High: ${summary.highCount}`);
  console.log(`Medium: ${summary.mediumCount}`);

  // Agent recommends actions
  summary.recommendations.forEach(rec => {
    console.log(`- ${rec.action}: ${rec.description}`);
  });
}

Step 5: Forensic Agent

The ForensicAgent detects patterns, anomalies, and fraud indicators.

import { ForensicAgent } from '@neural-trader/agentic-accounting-agents';

const forensicAgent = new ForensicAgent('forensic-001');
await forensicAgent.start();

// Analyze transactions
const result = await forensicAgent.execute({
  taskId: 'forensic-001',
  description: 'Analyze transaction patterns',
  priority: 'high',
  data: {
    transactions,
    enablePatternDetection: true,
    enableAnomalyDetection: true,
    enableFraudScoring: true,
    minSupport: 0.1,
    minConfidence: 0.6,
    anomalyThreshold: 0.85
  }
});

if (result.success) {
  const analysis = result.data;

  // Check patterns
  console.log(`Patterns detected: ${analysis.patterns.length}`);
  analysis.patterns.forEach(p => {
    console.log(`- ${p.description} (support: ${p.support}, confidence: ${p.confidence})`);
  });

  // Check anomalies
  console.log(`Anomalies detected: ${analysis.anomalies.length}`);
  analysis.anomalies.forEach(a => {
    console.log(`- ${a.transactionId}: ${a.type} (score: ${a.score})`);
  });

  // Check fraud scores
  const highRisk = analysis.fraudScores.filter(s => s.score > 0.8);
  console.log(`High fraud risk: ${highRisk.length}`);
  highRisk.forEach(f => {
    console.warn(`- ${f.transactionId}: ${f.score} - ${f.reason}`);
  });
}

Step 6: Harvest Agent

The HarvestAgent autonomously identifies and executes tax-loss harvesting opportunities.

import { HarvestAgent } from '@neural-trader/agentic-accounting-agents';

const harvestAgent = new HarvestAgent('harvest-001');
await harvestAgent.start();

// Scan for opportunities
const result = await harvestAgent.execute({
  taskId: 'harvest-001',
  description: 'Scan portfolio for TLH opportunities',
  priority: 'high',
  data: {
    positions,
    currentPrices,
    recentTransactions,
    taxRate: 0.35,
    minSavings: 100,            // Minimum $100 savings
    autoExecute: false,         // Manual approval
    findReplacements: true      // Find correlated assets
  }
});

if (result.success) {
  const opportunities = result.data.opportunities;
  const harvestable = opportunities.filter(o => o.recommendation === 'HARVEST');

  console.log(`Harvestable opportunities: ${harvestable.length}`);
  console.log(`Total potential savings: $${result.data.totalPotentialSavings}`);

  // Review opportunities
  harvestable.forEach(opp => {
    console.log(`\n${opp.asset}:`);
    console.log(`  Loss: $${opp.unrealizedLoss}`);
    console.log(`  Savings: $${opp.potentialTaxSavings}`);
    console.log(`  Wash sale risk: ${opp.washSaleRisk ? 'YES' : 'NO'}`);

    if (opp.replacements) {
      console.log(`  Replacements: ${opp.replacements.join(', ')}`);
    }
  });

  // Agent generates execution plan
  const plan = result.data.executionPlan;
  console.log(`\nExecution plan: ${plan.actions.length} actions`);
}

Step 7: Reporting Agent

The ReportingAgent generates tax reports and exports them in multiple formats.

import { ReportingAgent } from '@neural-trader/agentic-accounting-agents';

const reportingAgent = new ReportingAgent('reporting-001');
await reportingAgent.start();

// Generate IRS Form 8949
const result = await reportingAgent.execute({
  taskId: 'report-001',
  description: 'Generate 2024 Form 8949',
  priority: 'high',
  data: {
    reportType: 'form-8949',
    taxYear: 2024,
    taxpayerId: '123-45-6789',
    transactions: disposals,
    method: 'HIFO',
    exportFormats: ['pdf', 'csv', 'json'],
    outputDir: './reports'
  }
});

if (result.success) {
  const report = result.data.report;
  console.log(`Form 8949 generated:`);
  console.log(`  Total disposals: ${report.totalDisposals}`);
  console.log(`  Short-term gain/loss: $${report.shortTermGainLoss}`);
  console.log(`  Long-term gain/loss: $${report.longTermGainLoss}`);
  console.log(`  Net gain/loss: $${report.netGainLoss}`);

  // Files exported
  console.log(`\nExported files:`);
  result.data.exports.forEach(exp => {
    console.log(`  - ${exp.format}: ${exp.filepath}`);
  });
}

// Generate Schedule D
const scheduleDResult = await reportingAgent.execute({
  taskId: 'report-002',
  description: 'Generate Schedule D',
  priority: 'high',
  data: {
    reportType: 'schedule-d',
    form8949: result.data.report,
    exportFormats: ['pdf']
  }
});

Step 8: Learning Agent

The LearningAgent continuously improves system performance using ReasoningBank.

import { LearningAgent } from '@neural-trader/agentic-accounting-agents';

const learningAgent = new LearningAgent('learning-001');
await learningAgent.start();

// Analyze past decisions
const result = await learningAgent.execute({
  taskId: 'learning-001',
  description: 'Analyze Q4 performance',
  priority: 'low',
  data: {
    startDate: '2024-10-01',
    endDate: '2024-12-31',
    agents: ['tax-001', 'compliance-001', 'harvest-001'],
    optimizationGoal: 'success_rate'
  }
});

if (result.success) {
  const insights = result.data.insights;

  console.log('Learning insights:');
  console.log(`  Success rate: ${insights.successRate}%`);
  console.log(`  Average duration: ${insights.avgDuration}ms`);
  console.log(`  Top patterns: ${insights.topPatterns.length}`);

  // Recommendations for improvement
  insights.recommendations.forEach(rec => {
    console.log(`\n${rec.agent}:`);
    console.log(`  - ${rec.recommendation}`);
    console.log(`  - Expected improvement: ${rec.expectedImprovement}`);
  });

  // Agent updates strategies
  await learningAgent.applyRecommendations(insights.recommendations);
}

Step 9: Swarm Coordination

Coordinate multiple agents using agentic-flow for complex workflows.

import {
  TaxComputeAgent,
  IngestionAgent,
  ComplianceAgent,
  HarvestAgent,
  ReportingAgent
} from '@neural-trader/agentic-accounting-agents';

// Create agent swarm
const swarm = {
  ingestion: new IngestionAgent('ingest-001'),
  tax: new TaxComputeAgent('tax-001'),
  compliance: new ComplianceAgent('compliance-001'),
  harvest: new HarvestAgent('harvest-001'),
  reporting: new ReportingAgent('reporting-001')
};

// Start all agents
await Promise.all(Object.values(swarm).map(agent => agent.start()));

// Execute coordinated workflow
async function endOfYearWorkflow() {
  // 1. Ingest all transactions
  const ingestionResult = await swarm.ingestion.execute({
    taskId: 'eoy-ingest',
    description: 'Ingest year-end transactions',
    priority: 'critical',
    data: { sources: ['coinbase', 'binance'], year: 2024 }
  });

  if (!ingestionResult.success) {
    throw new Error('Ingestion failed');
  }

  const transactions = ingestionResult.data.transactions;

  // 2. Parallel: Check compliance + Find harvesting opportunities
  const [complianceResult, harvestResult] = await Promise.all([
    swarm.compliance.execute({
      taskId: 'eoy-compliance',
      description: 'Year-end compliance check',
      priority: 'critical',
      data: { transactions, jurisdiction: 'US' }
    }),
    swarm.harvest.execute({
      taskId: 'eoy-harvest',
      description: 'Year-end TLH scan',
      priority: 'high',
      data: { positions, currentPrices, taxRate: 0.35 }
    })
  ]);

  // 3. Calculate taxes for all disposals
  const disposals = transactions.filter(t => t.type === 'SELL');
  const taxResults = await Promise.all(
    disposals.map(disposal =>
      swarm.tax.execute({
        taskId: `tax-${disposal.id}`,
        description: `Calculate tax for ${disposal.asset}`,
        priority: 'high',
        data: { sale: disposal, lots, compareAll: true }
      })
    )
  );

  // 4. Generate reports
  const reportResult = await swarm.reporting.execute({
    taskId: 'eoy-report',
    description: 'Generate year-end reports',
    priority: 'high',
    data: {
      reportTypes: ['form-8949', 'schedule-d'],
      taxYear: 2024,
      disposals: taxResults.map(r => r.data.calculation),
      exportFormats: ['pdf', 'csv']
    }
  });

  return {
    transactions: ingestionResult.data,
    compliance: complianceResult.data,
    harvesting: harvestResult.data,
    taxes: taxResults,
    reports: reportResult.data
  };
}

// Execute workflow
const results = await endOfYearWorkflow();
console.log('End-of-year workflow completed:', results);

// Stop all agents
await Promise.all(Object.values(swarm).map(agent => agent.stop()));

🏗️ API Documentation

Base Agent

BaseAgent

abstract class BaseAgent extends EventEmitter {
  constructor(config: AgentConfig)

  // Start the agent
  async start(): Promise<void>

  // Stop the agent
  async stop(): Promise<void>

  // Execute task (must be implemented by subclasses)
  abstract execute(task: AgentTask): Promise<AgentResult>

  // Get agent status
  getStatus(): AgentStatus

  // Get recent decisions
  getRecentDecisions(limit?: number): DecisionLog[]

  // Clear decision history
  clearDecisions(): void

  // Protected methods for subclasses
  protected async learn(data: Record<string, any>): Promise<void>
  protected async logDecision(...): Promise<void>
  protected async executeWithMetrics<T>(taskFn: () => Promise<T>): Promise<AgentResult<T>>

  // Events: 'started', 'stopped', 'decision', 'error'
}

interface AgentConfig {
  agentId: string
  agentType: string
  enableLearning?: boolean
  enableMetrics?: boolean
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
}

interface AgentTask {
  taskId: string
  description: string
  priority: 'low' | 'medium' | 'high' | 'critical'
  data: unknown
  metadata?: Record<string, unknown>
}

interface AgentResult<T = unknown> {
  success: boolean
  data?: T
  error?: Error
  metrics?: {
    startTime: number
    endTime: number
    duration: number
    memoryUsed?: number
  }
  metadata?: Record<string, unknown>
}

Tax Compute Agent

TaxComputeAgent

class TaxComputeAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute tax calculation
  async execute(task: TaxCalculationTask): Promise<AgentResult<TaxComputeResult>>

  // Compare all methods
  async compareAllMethods(sale: Transaction, lots: TaxLot[]): Promise<any>

  // Invalidate cache
  invalidateCache(asset?: string): number

  // Get cache statistics
  getCacheStats(): CacheStats

  // Get extended status
  getExtendedStatus(): ExtendedStatus
}

interface TaxCalculationTask extends AgentTask {
  data: {
    sale: Transaction
    lots: TaxLot[]
    profile?: TaxProfile
    method?: TaxMethod
    compareAll?: boolean
    enableCache?: boolean
    detectWashSales?: boolean
  }
}

interface TaxComputeResult {
  calculation: TaxCalculation
  recommendation?: MethodRecommendation
  comparison?: MethodComparison
  washSales?: WashSale[]
  cacheHit?: boolean
  performance: {
    validationTime: number
    calculationTime: number
    totalTime: number
  }
}

Ingestion Agent

IngestionAgent

class IngestionAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute ingestion task
  async execute(task: IngestionTask): Promise<AgentResult<IngestionResult>>

  // Get supported sources
  getSupportedSources(): string[]

  // Get ingestion statistics
  getIngestionStats(): IngestionStats
}

Compliance Agent

ComplianceAgent

class ComplianceAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute compliance check
  async execute(task: ComplianceTask): Promise<AgentResult<ComplianceResult>>

  // Get supported jurisdictions
  getSupportedJurisdictions(): string[]

  // Get violation summary
  getViolationSummary(): ViolationSummary

  // Events: 'violation', 'warning', 'alert'
}

Forensic Agent

ForensicAgent

class ForensicAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute forensic analysis
  async execute(task: ForensicTask): Promise<AgentResult<ForensicResult>>

  // Get analysis summary
  getAnalysisSummary(): AnalysisSummary
}

Harvest Agent

HarvestAgent

class HarvestAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute harvesting scan
  async execute(task: HarvestTask): Promise<AgentResult<HarvestResult>>

  // Get opportunity statistics
  getOpportunityStats(): OpportunityStats
}

Reporting Agent

ReportingAgent

class ReportingAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute report generation
  async execute(task: ReportingTask): Promise<AgentResult<ReportingResult>>

  // Get supported report types
  getSupportedReportTypes(): string[]

  // Get export formats
  getExportFormats(): string[]
}

Learning Agent

LearningAgent

class LearningAgent extends BaseAgent {
  constructor(agentId?: string)

  // Execute learning analysis
  async execute(task: LearningTask): Promise<AgentResult<LearningResult>>

  // Apply recommendations
  async applyRecommendations(recommendations: Recommendation[]): Promise<void>

  // Get learning metrics
  getLearningMetrics(): LearningMetrics
}

🏛️ Architecture

Agent Swarm Topology

┌─────────────────────────────────────────────────────────────────┐
│                    Agent Coordination Layer                       │
│                    (Agentic-Flow + BullMQ)                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Ingestion   │  │     Tax      │  │  Compliance  │          │
│  │    Agent     │─▶│   Compute    │─▶│    Agent     │          │
│  │              │  │    Agent     │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                 │                  │                   │
│         ▼                 ▼                  ▼                   │
│  ┌──────────────────────────────────────────────────┐          │
│  │          ReasoningBank Learning Layer            │          │
│  │         (Decision Trajectories + Verdicts)       │          │
│  └──────────────────────────────────────────────────┘          │
│         │                 │                  │                   │
│         ▼                 ▼                  ▼                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   Harvest    │  │   Forensic   │  │   Reporting  │         │
│  │    Agent     │  │    Agent     │  │    Agent     │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│         │                 │                  │                   │
│         └─────────────────┴──────────────────┘                  │
│                           │                                      │
│                           ▼                                      │
│                  ┌──────────────┐                               │
│                  │   Learning   │                               │
│                  │    Agent     │                               │
│                  └──────────────┘                               │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                      Storage Layer                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │   AgentDB    │  │    Redis     │  │     Core     │         │
│  │ Vector Memory│  │  Job Queue   │  │   Library    │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Agent Workflow

Task Request                Agent Processing              Result
────────────                ────────────────              ──────

┌──────────┐
│  Task    │
│ Priority │
└────┬─────┘
     │
     ▼
┌──────────┐     ┌─────────────┐     ┌──────────┐     ┌──────────┐
│ BullMQ   │────▶│ Agent Queue │────▶│  Agent   │────▶│  Execute │
│ Enqueue  │     │ (Priority)  │     │  Start   │     │   Task   │
└──────────┘     └─────────────┘     └──────────┘     └────┬─────┘
                                                             │
                                                             ▼
                                                      ┌──────────┐
                                                      │Validation│
                                                      └────┬─────┘
                                                           │
                          ┌────────────────────────────────┴──────┐
                          │                                        │
                          ▼                                        ▼
                   ┌──────────┐                           ┌──────────┐
                   │  Cache   │                           │ Business │
                   │  Check   │                           │  Logic   │
                   └────┬─────┘                           └────┬─────┘
                        │                                      │
                 Cache  │  Cache                               │
                  Hit   │  Miss                                │
                        │                                      │
                   ┌────┴─────┐                          ┌────┴─────┐
                   │  Return  │                          │ Decision │
                   │  Cached  │                          │ Logging  │
                   └──────────┘                          └────┬─────┘
                                                              │
                                                              ▼
                                                       ┌──────────┐
                                                       │ Learning │
                                                       │  Update  │
                                                       └────┬─────┘
                                                            │
                                                            ▼
                                                       ┌──────────┐
                                                       │  Result  │
                                                       │ + Metrics│
                                                       └──────────┘

💡 Advanced Features

⚠️ Important Notes

Redis Required: BullMQ coordination requires Redis 5+. Install and configure before using job queues.

Agent IDs: Must be unique across your system. Use descriptive IDs like 'tax-001', 'ingest-prod-01'.

Priority: Higher priority tasks execute first in the queue (critical > high > medium > low).

💡 Pro Tips

Tip: Enable enableLearning: true to leverage ReasoningBank for adaptive decision-making.

Tip: Listen to agent events (agent.on('decision')) for real-time observability.

Tip: Use Promise.all() to execute multiple agents in parallel for maximum throughput.

🎯 Best Practices

Note: Always call agent.start() before executing tasks and agent.stop() when done.

Note: Use try/catch blocks when executing tasks to handle failures gracefully.

Note: Call agent.clearDecisions() periodically to prevent memory leaks in long-running agents.

🔗 Related Packages

This package is part of the Neural Trader Agentic Accounting ecosystem:

• @neural-trader/agentic-accounting-core - Core business logic and utilities
• @neural-trader/agentic-accounting-types - Shared TypeScript types and interfaces
• @neural-trader/agentic-accounting-rust-core - Rust NAPI bindings for high-performance calculations

Full Stack Example

// Agents for autonomous execution
import { TaxComputeAgent, HarvestAgent } from '@neural-trader/agentic-accounting-agents';

// Core library for business logic
import { TaxLossHarvestingService } from '@neural-trader/agentic-accounting-core';

// Types for shared interfaces
import { Transaction, Position } from '@neural-trader/agentic-accounting-types';

// Create agent swarm + core services
const harvesting = new TaxLossHarvestingService();
const harvestAgent = new HarvestAgent('harvest-001');
const taxAgent = new TaxComputeAgent('tax-001');

await harvestAgent.start();
await taxAgent.start();

// Agent finds opportunities (autonomous)
const harvestResult = await harvestAgent.execute({
  taskId: 'harvest-001',
  description: 'Find TLH opportunities',
  priority: 'high',
  data: { positions, currentPrices }
});

// Agent calculates taxes (autonomous)
const taxResults = await Promise.all(
  harvestResult.data.opportunities.map(opp =>
    taxAgent.execute({
      taskId: `tax-${opp.id}`,
      description: 'Calculate harvest tax impact',
      priority: 'high',
      data: { sale: opp.position, lots: opp.position.lots }
    })
  )
);

console.log('Autonomous harvesting completed:', {
  opportunities: harvestResult.data.opportunities.length,
  calculations: taxResults.length,
  totalSavings: harvestResult.data.totalPotentialSavings
});

🛠️ Development

Scripts

# Build TypeScript
npm run build

# Run tests
npm test
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

# Benchmarks
npm run bench:coordination  # Agent coordination performance
npm run bench:all          # All benchmarks

Performance Benchmarks

Agent Startup: <50ms per agent
Task Execution: 100-500ms (varies by complexity)
Decision Logging: <5ms per decision
ReasoningBank Query: <10ms (AgentDB vector search)
Job Queue Throughput: 1000+ tasks/sec (BullMQ + Redis)
Memory per Agent: ~20MB baseline + task data

📄 License

Dual-licensed under MIT OR Apache-2.0. Choose the license that best fits your project.

🙏 Credits

Created by ruv.io as part of the Neural Trader platform.

• Website: neural-trader.ruv.io
• Repository: github.com/ruvnet/neural-trader
• Documentation: docs.neural-trader.ruv.io

Powered By

• Agentic-Flow - Multi-agent coordination framework
• AgentDB - Vector database for agent memory
• BullMQ - Distributed job queue system
• ReasoningBank - Adaptive learning from experience
• Redis - In-memory data store for job queues

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Built with ❤️ by the Neural Trader team