AI Providers Integration
Relevant source files
The following files were used as context for generating this wiki page:
Oboete integrates with various AI providers to curate coding session transcripts into structured memory records. The system uses a fallback chain architecture to manage multiple providers, ensuring reliability through automatic failover, rate limit handling, and budget tracking.
Sources: src/provider.rs:1-12, src/config.rs:1-5
Provider Architecture
The integration supports two main types of AI providers: OpenAI-compatible HTTP endpoints and subscription-based Command Line Interfaces (CLIs). Providers are organized into a prioritized chain that Oboete traverses until a valid response is received.
Provider Types
| Type | Description | Examples |
|---|---|---|
| OpenAI | REST API endpoints using OpenAI-compatible JSON schemas. | Groq, OpenRouter, Mistral, NIM. |
| CLI | Headless execution of subscription-based coding agents. | claude, codex, agy, grok. |
Sources: src/config.rs:151-185, src/provider.rs:326-340
Curation Logic Flow
The following diagram illustrates how the Chain actor processes a curation request across multiple providers.
The Chain::run function iterates through configured providers, skipping those in a "down" state or over budget.
Sources: src/provider.rs:141-260
Configuration and Budgeting
Providers are defined in config.toml. Each entry includes specific limits to control spending and prevent API exhaustion.
Configuration Structure
The Config struct defines the global state, while Provider enums handle specific backend settings.
daily_budget: Maximum number of calls allowed per day.limits: Defines token ceilings and USD prices for paid entries.paid_usd_per_month: A global cap on total spending across all paid providers.
Sources: src/config.rs:11-30, src/config.rs:188-212
Tier System
Oboete categorizes providers into tiers to determine priority and claim authority:
- Tier 3 (Paid): High-priority providers with explicit USD costs.
- Tier 2 (Subscription): CLI-based agents or marked API entries.
- Tier 1 (Free/Local): Default providers used to minimize costs.
Sources: src/config.rs:244-255
Execution and Error Handling
Oboete implements sophisticated error handling to manage the volatility of AI services.
Cooldown and Backoff
Providers that fail are temporarily disabled using the following rules:
- 429 (Rate Limit): Resets after a specific wait time or a default 45-second period.
- Outage (5xx/Auth): Triggers a 10-minute cooldown.
- Circuit Breaker: If a provider fails three times in a row without a specific cooldown, it is disabled for 30 minutes.
- Exponential Backoff: Repeated 429 errors without a reset time double the cooldown period up to one hour.
Sources: src/provider.rs:25-45, src/provider.rs:297-324
CLI Isolation
When running CLI providers like claude or codex, Oboete enforces strict isolation:
- Environment Scrubbing: Only essential variables (e.g.,
PATH,HOME, proxy settings) are passed to the sub-process. - Scratch Directories: Each run occurs in a random, private temporary directory.
- Process Groups: CLIs run in their own process groups to ensure all descendants are killed on timeout.
Sources: src/provider.rs:498-510, src/provider.rs:757-775, src/provider.rs:790-805
Curation Schema
Curation results must follow a strict JSON schema. This ensures the output can be reliably parsed into the Oboete database.
{
"type": "object",
"properties": {
"claims": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "string"},
"kind": {"type": "string", "enum": ["decision", "preference", "lesson", "fix", "open item", "repo fact", "change"]},
"status": {"type": "string", "enum": ["decided", "proposed", "retracted", "done"]},
"body": {"type": "string"},
"quote": {"type": "string"},
"line": {"type": "string"}
}
}
},
"summary": {"type": "string"}
}
}
Sources: src/curate.rs:1367-1400
Monitoring and Diagnostics
The oboete doctor command provides real-time visibility into the status of AI provider integrations.
Diagnostic Outputs
- Last Calls: Displays the outcome, latency, and details of the 5 most recent provider calls.
- Provider State: Shows which providers are currently resting and when they will be available.
- Pending Curation: Lists records waiting for curation and the reasons for delay (e.g., waiting on budget or owner action).
Sources: src/setup.rs:1141-1185
Provider Call Statistics
The internal viewer (oboete view) aggregates provider performance data from providers.db.
| Field | Description |
|---|---|
| OK | Number of successful calls. |
| Failed | Number of failed calls (errors, invalid output, etc.). |
| Waited | Total occurrences of rate-limit waits. |
| Avg ms | Average response time for successful calls. |
Sources: src/view.rs:434-455
Summary
The AI Providers Integration provides a resilient layer for processing raw coding events into structured memory. By abstracting various API and CLI backends behind a unified fallback chain, Oboete maintains high availability and strict cost control. The integration includes specialized isolation for local CLI agents and detailed telemetry for monitoring provider health.