Budget-Aware Orchestrator

[TobleroneX]

Task 006: Budget-Aware Orchestrator

Description

Create BudgetOrchestrator that wraps existing agent execution with cost estimation, prioritization, and budget enforcement.

Size

L (3 days)

Dependencies

• Depends on: [003, 004, 005]
• Must run after all dependent tasks complete
• No parallel execution

Acceptance Criteria

Core Implementation

• Create lib/agent-architecture/core/budget-orchestrator.ts
• Implement BudgetOrchestrator class
• Cost estimation engine (estimateCosts method)
• Agent prioritization logic (critical > high > medium > optional)
• Budget enforcement (hard stop at max per-lead budget)
• Track actual vs estimated costs
• Cost accuracy validation (±15% target)

Integration

• Non-breaking integration with existing enrichment flow
• Wrap existing agent execution without modifying agent code
• Maintain backward compatibility
• Configuration options for budget limits

Testing

• Unit tests for orchestration logic
• Unit tests for cost estimation
• Unit tests for prioritization algorithm
• Unit tests for budget enforcement
• Integration tests with mock agents
• Cost accuracy validation tests

Documentation

• API documentation for BudgetOrchestrator
• Configuration guide
• Usage examples
• Cost estimation methodology documentation

Technical Notes

Agent Priority Levels

1. Critical: Essential data (company basics, contact info)
2. High: Important enrichment (tech stack, funding)
3. Medium: Valuable insights (news, competitors)
4. Optional: Nice-to-have data (social signals)

Cost Estimation Approach

• Track historical API costs per agent
• Factor in data source pricing (Firecrawl, external APIs)
• Account for retry attempts
• Include buffer for estimation variance

Budget Enforcement Strategy

• Pre-execution: Estimate total costs, skip optional agents if needed
• During execution: Track running costs, halt if approaching limit
• Post-execution: Log actual costs, update estimation model

Integration Points

• Hook into existing enrichment pipeline
• Respect current agent interface
• Add budget configuration to enrichment settings
• Provide cost reporting in enrichment results