docs: restructure documentation into multilevel directory layout
New structure: docs/ split into 11 subdirectories (getting-started/, agents/, providers/, sidecar/, multi-machine/, plugins/, config/, production/, architecture/, contributing/, pro/). New files: - docs/README.md: navigation index with audience table - docs/getting-started/quickstart.md: install, build, first session - docs/config/ref-settings.md: all env vars, config files, databases - docs/architecture/overview.md: split from architecture.md (>300 lines) - docs/pro/README.md: Pro edition overview - docs/pro/features/analytics.md: analytics dashboard docs - docs/pro/features/cost-intelligence.md: budget + router docs Remaining docs being written by background agents — will be committed in follow-up when complete.
This commit is contained in:
Hibryda
parent
738574b9f0
commit
8251321dac
7 changed files with 1268 additions and 59 deletions
238
docs/pro/features/cost-intelligence.md
Normal file
238
docs/pro/features/cost-intelligence.md
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
# Cost Intelligence
|
||||
|
||||
> This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.
|
||||
|
||||
Cost Intelligence comprises two systems: the Budget Governor (hard cost controls) and the Smart Model Router (cost-aware model selection). Both operate at the per-project level and integrate with the agent launch pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Budget Governor
|
||||
|
||||
### Purpose
|
||||
|
||||
The Budget Governor enforces per-project monthly token budgets. It prevents runaway costs by warning at a soft limit and blocking agent launches at a hard limit.
|
||||
|
||||
### Budget Configuration
|
||||
|
||||
Each project can have a monthly budget with two thresholds:
|
||||
|
||||
| Threshold | Default | Behavior |
|
||||
|-----------|---------|----------|
|
||||
| Soft limit | 80% of budget | Emits a warning notification. Agent proceeds. |
|
||||
| Hard limit | 100% of budget | Blocks agent launch. Returns error to UI. |
|
||||
|
||||
Budgets are denominated in USD. The governor tracks cumulative cost for the current calendar month by summing `cost_usd` from `session_metrics` and `pro_budget_log`.
|
||||
|
||||
### Emergency Override
|
||||
|
||||
When the hard limit is reached, the UI displays a confirmation dialog with the current spend and budget. The user can authorize an emergency override that allows the next session to proceed. Overrides are logged in `pro_budget_log` with `override = true`. Each override is single-use; subsequent launches require a new override.
|
||||
|
||||
### SQLite Tables
|
||||
|
||||
Both tables reside in `agor_pro.db`.
|
||||
|
||||
```sql
|
||||
CREATE TABLE pro_budgets (
|
||||
project_id TEXT PRIMARY KEY,
|
||||
monthly_budget_usd REAL NOT NULL,
|
||||
soft_limit_pct REAL NOT NULL DEFAULT 0.80,
|
||||
hard_limit_pct REAL NOT NULL DEFAULT 1.00,
|
||||
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||||
updated_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||
);
|
||||
|
||||
CREATE TABLE pro_budget_log (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
project_id TEXT NOT NULL,
|
||||
session_id TEXT NOT NULL,
|
||||
cost_usd REAL NOT NULL,
|
||||
cumulative_usd REAL NOT NULL,
|
||||
month TEXT NOT NULL, -- YYYY-MM format
|
||||
override INTEGER NOT NULL DEFAULT 0,
|
||||
logged_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||
);
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
#### pro_budget_set
|
||||
|
||||
Creates or updates a budget for a project.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
| `monthlyBudgetUsd` | `f64` | Yes | Monthly budget in USD |
|
||||
| `softLimitPct` | `f64` | No | Soft limit percentage (default 0.80) |
|
||||
| `hardLimitPct` | `f64` | No | Hard limit percentage (default 1.00) |
|
||||
|
||||
#### pro_budget_get
|
||||
|
||||
Returns the budget configuration for a project. Returns `null` if no budget is set.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
#### pro_budget_check
|
||||
|
||||
Pre-dispatch hook. Checks whether the project can launch a new agent session.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
**Response: `BudgetCheckResult`**
|
||||
|
||||
```typescript
|
||||
interface BudgetCheckResult {
|
||||
allowed: boolean;
|
||||
currentSpendUsd: number;
|
||||
budgetUsd: number;
|
||||
pctUsed: number; // 0.0 to 1.0
|
||||
softLimitReached: boolean;
|
||||
hardLimitReached: boolean;
|
||||
month: string; // YYYY-MM
|
||||
}
|
||||
```
|
||||
|
||||
#### pro_budget_log_usage
|
||||
|
||||
Records cost for a completed session. Called by the agent dispatcher on session end.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
| `sessionId` | `String` | Yes | Session identifier |
|
||||
| `costUsd` | `f64` | Yes | Session cost |
|
||||
| `override` | `bool` | No | Whether this was an emergency override |
|
||||
|
||||
#### pro_budget_reset
|
||||
|
||||
Resets the cumulative spend for a project's current month. Deletes all `pro_budget_log` entries for the current month.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
#### pro_budget_list
|
||||
|
||||
Returns budgets and current spend for all projects.
|
||||
|
||||
**Response: `Vec<ProjectBudgetStatus>`**
|
||||
|
||||
```typescript
|
||||
interface ProjectBudgetStatus {
|
||||
projectId: string;
|
||||
monthlyBudgetUsd: number;
|
||||
currentSpendUsd: number;
|
||||
pctUsed: number;
|
||||
softLimitReached: boolean;
|
||||
hardLimitReached: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Pre-Dispatch Integration
|
||||
|
||||
The budget check is wired into the agent launch path:
|
||||
|
||||
1. User triggers agent start in AgentPane.
|
||||
2. `AgentSession.startQuery()` calls `pro_budget_check` before invoking the sidecar.
|
||||
3. If `softLimitReached`: toast warning, agent proceeds.
|
||||
4. If `hardLimitReached`: blocks launch, shows override dialog.
|
||||
5. On override confirmation: calls `pro_budget_log_usage` with `override: true`, then proceeds.
|
||||
6. On session completion: `agent-dispatcher` calls `pro_budget_log_usage` with actual cost.
|
||||
|
||||
---
|
||||
|
||||
## Smart Model Router
|
||||
|
||||
### Purpose
|
||||
|
||||
The Smart Model Router recommends which model to use for a given agent session based on the project's routing profile and the agent's role. It does not force model selection -- it provides a recommendation that the user can accept or override.
|
||||
|
||||
### Routing Profiles
|
||||
|
||||
Three built-in profiles define model preferences:
|
||||
|
||||
#### CostSaver
|
||||
|
||||
Minimizes cost by preferring smaller models for routine tasks.
|
||||
|
||||
| Role | Recommended Model |
|
||||
|------|-------------------|
|
||||
| Manager | claude-sonnet-4-5-20250514 |
|
||||
| Architect | claude-sonnet-4-5-20250514 |
|
||||
| Tester | claude-haiku-4-5-20250514 |
|
||||
| Reviewer | claude-haiku-4-5-20250514 |
|
||||
| Default (no role) | claude-sonnet-4-5-20250514 |
|
||||
|
||||
#### QualityFirst
|
||||
|
||||
Maximizes output quality by preferring the most capable model.
|
||||
|
||||
| Role | Recommended Model |
|
||||
|------|-------------------|
|
||||
| Manager | claude-opus-4-5-20250514 |
|
||||
| Architect | claude-opus-4-5-20250514 |
|
||||
| Tester | claude-sonnet-4-5-20250514 |
|
||||
| Reviewer | claude-sonnet-4-5-20250514 |
|
||||
| Default (no role) | claude-opus-4-5-20250514 |
|
||||
|
||||
#### Balanced
|
||||
|
||||
Default profile. Balances cost and quality per role.
|
||||
|
||||
| Role | Recommended Model |
|
||||
|------|-------------------|
|
||||
| Manager | claude-sonnet-4-5-20250514 |
|
||||
| Architect | claude-opus-4-5-20250514 |
|
||||
| Tester | claude-haiku-4-5-20250514 |
|
||||
| Reviewer | claude-sonnet-4-5-20250514 |
|
||||
| Default (no role) | claude-sonnet-4-5-20250514 |
|
||||
|
||||
### Commands
|
||||
|
||||
#### pro_router_recommend
|
||||
|
||||
Returns the recommended model for a given project and role.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
| `role` | `String` | No | Agent role (manager/architect/tester/reviewer) |
|
||||
|
||||
**Response:**
|
||||
|
||||
```typescript
|
||||
interface RouterRecommendation {
|
||||
model: string;
|
||||
profile: string; // CostSaver | QualityFirst | Balanced
|
||||
reason: string; // Human-readable explanation
|
||||
}
|
||||
```
|
||||
|
||||
#### pro_router_set_profile
|
||||
|
||||
Sets the routing profile for a project.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
| `profile` | `String` | Yes | Profile name: CostSaver, QualityFirst, or Balanced |
|
||||
|
||||
#### pro_router_get_profile
|
||||
|
||||
Returns the current routing profile for a project. Defaults to Balanced.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `projectId` | `String` | Yes | Project identifier |
|
||||
|
||||
#### pro_router_list_profiles
|
||||
|
||||
Returns all available routing profiles with their role-to-model mappings. Takes no arguments.
|
||||
|
||||
### Integration with Agent Launch
|
||||
|
||||
The router recommendation is surfaced in the AgentPane model selector. When a project has a routing profile set, the recommended model appears as a highlighted option in the dropdown. The user retains full control to select any available model.
|
||||
Loading…
Add table
Add a link
Reference in a new issue