o-switcher 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,286 @@
+# API Reference
+
+## Configuration
+
+### Minimal Config
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"]
+}
+```
+
+Zero config. O-Switcher reads providers from OpenCode automatically.
+
+### Optional Settings
+
+```json
+{
+  "switcher": {
+    "retry": 3,
+    "timeout": 30000
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `retry` | number | 3 | Max retry attempts per target before failover |
+| `timeout` | number | 30000 | Max expected latency in ms |
+
+### Full Config (advanced)
+
+```json
+{
+  "switcher": {
+    "retry": 3,
+    "timeout": 30000,
+    "retry_budget": 3,
+    "failover_budget": 2,
+    "backoff": {
+      "base_ms": 1000,
+      "multiplier": 2,
+      "max_ms": 30000,
+      "jitter": "full"
+    },
+    "routing_weights": {
+      "health": 1.0,
+      "latency": 0.5,
+      "failure": 0.8,
+      "priority": 0.3
+    },
+    "queue_limit": 100,
+    "concurrency_limit": 10,
+    "backpressure_threshold": 50,
+    "circuit_breaker": {
+      "failure_threshold": 5,
+      "failure_rate_threshold": 0.5,
+      "sliding_window_size": 10,
+      "half_open_after_ms": 30000,
+      "half_open_max_probes": 1,
+      "success_threshold": 2
+    },
+    "max_expected_latency_ms": 30000,
+    "targets": []
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `retry_budget` | number | 3 | Max retries per target |
+| `failover_budget` | number | 2 | Max target switches per request |
+| `backoff.base_ms` | number | 1000 | Initial backoff delay |
+| `backoff.multiplier` | number | 2 | Backoff multiplier |
+| `backoff.max_ms` | number | 30000 | Max backoff delay |
+| `backoff.jitter` | string | "full" | Jitter mode: "full", "equal", "none" |
+| `routing_weights.health` | number | 1.0 | Weight for health score |
+| `routing_weights.latency` | number | 0.5 | Weight for latency (negative — lower is better) |
+| `routing_weights.failure` | number | 0.8 | Weight for failure rate (negative — lower is better) |
+| `routing_weights.priority` | number | 0.3 | Weight for operator priority |
+| `queue_limit` | number | 100 | Max requests in admission queue |
+| `concurrency_limit` | number | 10 | Max concurrent requests |
+| `backpressure_threshold` | number | 50 | Queue depth triggering degraded mode |
+| `circuit_breaker.failure_threshold` | number | 5 | Consecutive failures to open circuit |
+| `circuit_breaker.failure_rate_threshold` | number | 0.5 | Failure rate (0-1) to open circuit |
+| `circuit_breaker.sliding_window_size` | number | 10 | Request count for rate calculation |
+| `circuit_breaker.half_open_after_ms` | number | 30000 | ms before probe after circuit opens |
+| `circuit_breaker.half_open_max_probes` | number | 1 | Probe requests allowed in half-open |
+| `circuit_breaker.success_threshold` | number | 2 | Successes to close circuit from half-open |
+| `max_expected_latency_ms` | number | 30000 | Latency normalization ceiling |
+| `targets` | array | auto-discovered | Manual target list (disables auto-discovery) |
+
+### Manual Target Config
+
+When `targets` is present, auto-discovery is disabled:
+
+```json
+{
+  "switcher": {
+    "targets": [
+      {
+        "target_id": "anthropic-main",
+        "provider_id": "anthropic",
+        "profile": "work-key",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 2,
+        "policy_tags": ["primary"],
+        "concurrency_limit": 5
+      }
+    ]
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `target_id` | string | yes | Unique target identifier |
+| `provider_id` | string | yes | Provider name (openai, anthropic, etc.) |
+| `profile` | string | no | Auth profile name (for multi-key setups) |
+| `capabilities` | string[] | yes | What the target can do (e.g. ["chat"]) |
+| `enabled` | boolean | yes | Whether target is active |
+| `operator_priority` | number | yes | Higher = preferred (for ranking) |
+| `policy_tags` | string[] | yes | Tags for policy-based filtering |
+| `concurrency_limit` | number | no | Per-target concurrent request limit |
+
+## Operator Tools
+
+Available as OpenCode tools when the plugin is loaded.
+
+### profiles-list
+
+List all saved auth profiles.
+
+**Args:** none
+
+**Returns:**
+```json
+[
+  {
+    "id": "openai-1",
+    "provider": "openai",
+    "type": "oauth",
+    "created": "2026-04-11T10:00:00Z"
+  },
+  {
+    "id": "openai-2",
+    "provider": "openai",
+    "type": "api-key",
+    "created": "2026-04-11T12:00:00Z"
+  }
+]
+```
+
+### profiles-remove
+
+Remove an auth profile by ID.
+
+**Args:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Profile ID to remove (e.g. "openai-2") |
+
+**Returns:**
+```json
+{ "removed": true, "id": "openai-2" }
+```
+
+### listTargets
+
+Show all routing targets with current state.
+
+**Args:** none
+
+**Returns:**
+```json
+[
+  {
+    "target_id": "openai-1",
+    "provider_id": "openai",
+    "profile": "work-key",
+    "state": "Active",
+    "health_score": 0.95,
+    "latency_ema_ms": 450,
+    "circuit_breaker": "Closed"
+  }
+]
+```
+
+### pauseTarget
+
+Stop routing to a target. Can be resumed later.
+
+**Args:** `{ "target_id": "openai-2" }`
+
+### resumeTarget
+
+Resume a paused or disabled target.
+
+**Args:** `{ "target_id": "openai-2" }`
+
+### drainTarget
+
+Let in-flight requests finish, reject new ones.
+
+**Args:** `{ "target_id": "openai-2" }`
+
+### disableTarget
+
+Fully disable a target.
+
+**Args:** `{ "target_id": "openai-2" }`
+
+### inspectRequest
+
+Show full trace for a request.
+
+**Args:** `{ "request_id": "550e8400-e29b-41d4-a716-446655440000" }`
+
+**Returns:** Full request trace with all attempts, targets, outcomes.
+
+### reloadConfig
+
+Hot-reload configuration without restart.
+
+**Args:** `{ "config": { ... } }`
+
+## Error Classes
+
+| Class | Retryable | What O-Switcher Does |
+|-------|-----------|---------------------|
+| `RateLimited` | yes | Cooldown with Retry-After, then retry |
+| `QuotaExhausted` | no | Disable target |
+| `AuthFailure` | no | One recovery attempt → ReauthRequired |
+| `PermissionFailure` | no | PolicyBlocked |
+| `PolicyFailure` | no | PolicyBlocked |
+| `RegionRestriction` | no | PolicyBlocked |
+| `ModelUnavailable` | no | Immediate failover to next target |
+| `TransientServerFailure` | yes | Retry with backoff |
+| `TransportFailure` | yes | Retry with backoff |
+| `InterruptedExecution` | yes | Save confirmed output, resume |
+
+## Routing Score Formula
+
+```
+score(target) = w_health * health_score
+              - w_latency * normalize(latency_ema_ms)
+              - w_failure * failure_score
+              + w_priority * operator_priority
+```
+
+Highest score wins. Ties broken by `target_id` lexicographic sort.
+
+## Log Output
+
+All logs are structured pino NDJSON. Filter by component:
+
+```bash
+# All routing decisions
+opencode 2>&1 | jq 'select(.component == "policy-engine")'
+
+# All failover events
+opencode 2>&1 | jq 'select(.component == "failover")'
+
+# Circuit breaker transitions
+opencode 2>&1 | jq 'select(.component == "log-subscriber") | select(.event == "circuit_state_change")'
+
+# Request summaries
+opencode 2>&1 | jq 'select(.msg == "request_summary")'
+
+# Profile changes
+opencode 2>&1 | jq 'select(.component == "auth-watcher")'
+```
+
+## Library API
+
+For programmatic use (not as plugin):
+
+```typescript
+import { validateConfig, createRegistry } from 'o-switcher/api';
+
+const config = validateConfig({ targets: [...] });
+const registry = createRegistry(config);
+```
+
+Full API exported from `o-switcher/api` — see TypeScript definitions.