proagents 1.6.16 → 1.6.18

package/.proagents/ai-models/cost-management.md

@@ -1,362 +0,0 @@
-# Cost Management
-
-Manage and optimize AI model costs.
-
----
-
-## Overview
-
-Track and control AI usage costs to stay within budget.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Cost Management                           │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Usage Tracking ──► Cost Calculation ──► Budget Control    │
-│        │                  │                   │             │
-│        ▼                  ▼                   ▼             │
-│  Token Counting      Rate Application     Alerts/Limits    │
-│  Request Logging     Provider Totals      Fallback Logic   │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Cost Configuration
-
-### Budget Limits
-
-```yaml
-ai:
-  cost:
-    # Daily spending limit
-    daily_limit: 50.00
-
-    # Weekly limit
-    weekly_limit: 250.00
-
-    # Monthly limit
-    monthly_limit: 1000.00
-
-    # Alert thresholds (percentage of limit)
-    alerts:
-      - threshold: 50
-        action: "notify"
-      - threshold: 80
-        action: "notify"
-      - threshold: 100
-        action: "block_or_fallback"
-
-    # On limit reached
-    on_limit:
-      action: "fallback"  # or "block"
-      fallback_model: "claude-3-haiku"
-```
-
-### Per-Team Budgets
-
-```yaml
-ai:
-  cost:
-    team_budgets:
-      frontend:
-        daily: 20.00
-        monthly: 400.00
-
-      backend:
-        daily: 25.00
-        monthly: 500.00
-
-      mobile:
-        daily: 15.00
-        monthly: 300.00
-```
-
----
-
-## Pricing Reference
-
-### Claude Models (Anthropic)
-
-| Model | Input (/1M tokens) | Output (/1M tokens) |
-|-------|-------------------|---------------------|
-| Opus | $15.00 | $75.00 |
-| Sonnet | $3.00 | $15.00 |
-| Haiku | $0.25 | $1.25 |
-
-### GPT Models (OpenAI)
-
-| Model | Input (/1M tokens) | Output (/1M tokens) |
-|-------|-------------------|---------------------|
-| GPT-4 Turbo | $10.00 | $30.00 |
-| GPT-4 | $30.00 | $60.00 |
-| GPT-3.5 | $0.50 | $1.50 |
-
-### Gemini Models (Google)
-
-| Model | Input (/1M tokens) | Output (/1M tokens) |
-|-------|-------------------|---------------------|
-| Gemini Pro | $0.50 | $1.50 |
-| Gemini Ultra | $7.00 | $21.00 |
-
----
-
-## Usage Tracking
-
-### View Current Usage
-
-```bash
-# Show today's usage
-proagents ai usage
-
-# Show weekly usage
-proagents ai usage --period week
-
-# Show by project
-proagents ai usage --by project
-
-# Show by model
-proagents ai usage --by model
-```
-
-### Usage Dashboard
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ AI Usage - January 2024                                     │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│ Today's Spend: $12.45 / $50.00                             │
-│ ████████████░░░░░░░░░░░░░░ 25%                             │
-│                                                             │
-│ This Month: $234.56 / $1000.00                             │
-│ ████████░░░░░░░░░░░░░░░░░░ 23%                             │
-│                                                             │
-│ By Model:                                                   │
-│ ├── claude-3-sonnet: $156.78 (67%)                        │
-│ ├── claude-3-opus: $45.23 (19%)                           │
-│ ├── claude-3-haiku: $18.90 (8%)                           │
-│ └── gpt-4: $13.65 (6%)                                    │
-│                                                             │
-│ By Task:                                                    │
-│ ├── Code Analysis: $89.45                                  │
-│ ├── Code Generation: $78.34                                │
-│ ├── Documentation: $34.56                                  │
-│ └── Quick Tasks: $32.21                                   │
-│                                                             │
-│ Tokens Used:                                                │
-│ ├── Input: 2.3M tokens                                    │
-│ └── Output: 890K tokens                                   │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Cost Optimization
-
-### Smart Model Selection
-
-```yaml
-ai:
-  optimization:
-    # Use cheaper models for simple tasks
-    auto_downgrade:
-      enabled: true
-      rules:
-        - task_type: "simple"
-          prefer: "haiku"
-        - task_type: "medium"
-          prefer: "sonnet"
-        - task_type: "complex"
-          prefer: "opus"
-
-    # Estimate before execution
-    estimate_first: true
-    confirm_expensive: true  # Confirm if > $1
-```
-
-### Caching
-
-```yaml
-ai:
-  caching:
-    enabled: true
-    ttl: "24h"
-
-    # Cache identical requests
-    request_cache: true
-
-    # Cache code analysis
-    analysis_cache: true
-    analysis_ttl: "7d"
-```
-
-### Token Optimization
-
-```yaml
-ai:
-  optimization:
-    # Compress context when possible
-    compress_context: true
-
-    # Truncate long files
-    max_file_tokens: 10000
-
-    # Summarize instead of full context
-    use_summaries: true
-```
-
----
-
-## Cost Alerts
-
-### Configuration
-
-```yaml
-ai:
-  alerts:
-    cost:
-      - name: "Daily 50%"
-        condition: "daily_spend >= daily_limit * 0.5"
-        channels: ["slack"]
-
-      - name: "Daily 80%"
-        condition: "daily_spend >= daily_limit * 0.8"
-        channels: ["slack", "email"]
-
-      - name: "Daily Limit"
-        condition: "daily_spend >= daily_limit"
-        channels: ["slack", "email", "sms"]
-        action: "fallback_to_cheaper"
-
-      - name: "Monthly 90%"
-        condition: "monthly_spend >= monthly_limit * 0.9"
-        channels: ["email"]
-        action: "notify_admin"
-```
-
-### Alert Example
-
-```
-🔔 AI Cost Alert
-
-Daily spend has reached 80% of limit.
-
-Current: $40.12 / $50.00
-Remaining: $9.88
-
-Top Consumers:
-• Code analysis: $18.45
-• Feature implementation: $12.34
-
-Recommendation: Consider using Haiku for remaining tasks today.
-
-[View Details] [Adjust Limit]
-```
-
----
-
-## Cost Reports
-
-### Generate Report
-
-```bash
-# Monthly cost report
-proagents ai report --period month
-
-# Export to CSV
-proagents ai report --format csv --output costs.csv
-```
-
-### Report Contents
-
-```markdown
-# AI Cost Report - January 2024
-
-## Summary
-- Total Spend: $845.67
-- Budget: $1000.00
-- Remaining: $154.33
-
-## By Provider
-| Provider | Spend | % of Total |
-|----------|-------|------------|
-| Anthropic | $678.45 | 80% |
-| OpenAI | $134.22 | 16% |
-| Google | $33.00 | 4% |
-
-## By Model
-| Model | Requests | Tokens | Cost |
-|-------|----------|--------|------|
-| claude-3-sonnet | 1,234 | 4.5M | $456.78 |
-| claude-3-opus | 89 | 890K | $178.90 |
-| claude-3-haiku | 567 | 1.2M | $42.77 |
-
-## By Team
-| Team | Spend | Budget | Status |
-|------|-------|--------|--------|
-| Frontend | $312.45 | $400 | ✅ |
-| Backend | $398.22 | $500 | ✅ |
-| Mobile | $135.00 | $300 | ✅ |
-
-## Trends
-- Daily average: $28.19
-- Peak day: Jan 15 ($67.89)
-- Lowest day: Jan 1 ($3.45)
-
-## Recommendations
-1. Consider caching repeated analysis requests
-2. Use Haiku for config/quick changes
-3. Team Backend approaching limit - review usage
-```
-
----
-
-## Budget Actions
-
-### On Budget Exceeded
-
-```yaml
-ai:
-  cost:
-    on_limit_exceeded:
-      # Options: block, fallback, notify_only, emergency_only
-      action: "fallback"
-
-      fallback_chain:
-        - "claude-3-haiku"
-        - "gpt-3.5-turbo"
-
-      emergency_override:
-        enabled: true
-        requires: "admin_approval"
-        max_additional: 20.00
-```
-
-### Manual Controls
-
-```bash
-# Pause AI usage
-proagents ai pause
-
-# Resume AI usage
-proagents ai resume
-
-# Emergency override (with approval)
-proagents ai override --reason "Critical production fix"
-```
-
----
-
-## Best Practices
-
-1. **Set Conservative Limits**: Start low, increase as needed
-2. **Enable Alerts Early**: Get notified at 50%
-3. **Use Right-Sized Models**: Don't use Opus for simple tasks
-4. **Enable Caching**: Avoid duplicate requests
-5. **Review Weekly**: Check usage patterns
-6. **Optimize Prompts**: Reduce token usage
-7. **Train Team**: Make team aware of costs

package/.proagents/ai-models/fallbacks.md

@@ -1,342 +0,0 @@
-# AI Model Fallbacks
-
-Configure fallback strategies when primary AI models are unavailable.
-
----
-
-## Fallback Chain
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Fallback Chain                            │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Request ──▶ Primary Model                                  │
-│                   │                                         │
-│              [Available?]                                   │
-│              /         \                                    │
-│           Yes           No                                  │
-│            │             │                                  │
-│            ▼             ▼                                  │
-│         Process    Secondary Model                          │
-│                         │                                   │
-│                    [Available?]                             │
-│                    /         \                              │
-│                 Yes           No                            │
-│                  │             │                            │
-│                  ▼             ▼                            │
-│              Process     Tertiary Model                     │
-│                               │                             │
-│                          [Continue...]                      │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Configuration
-
-### Fallback Chain Setup
-
-```yaml
-ai:
-  fallbacks:
-    enabled: true
-
-    # Primary chain
-    chain:
-      - model: "claude-3-opus"
-        provider: "anthropic"
-      - model: "gpt-4-turbo"
-        provider: "openai"
-      - model: "claude-3-sonnet"
-        provider: "anthropic"
-      - model: "gpt-4"
-        provider: "openai"
-      - model: "claude-3-haiku"
-        provider: "anthropic"
-
-    # When to trigger fallback
-    triggers:
-      - "rate_limit"
-      - "timeout"
-      - "service_unavailable"
-      - "model_overloaded"
-      - "quota_exceeded"
-```
-
-### Provider-Specific Settings
-
-```yaml
-ai:
-  providers:
-    anthropic:
-      api_key_env: "ANTHROPIC_API_KEY"
-      timeout: 30000
-      max_retries: 2
-
-    openai:
-      api_key_env: "OPENAI_API_KEY"
-      timeout: 30000
-      max_retries: 2
-
-    google:
-      api_key_env: "GOOGLE_AI_KEY"
-      timeout: 30000
-      max_retries: 2
-```
-
----
-
-## Fallback Triggers
-
-### Automatic Triggers
-
-| Trigger | Description | Action |
-|---------|-------------|--------|
-| `rate_limit` | API rate limit hit | Immediate fallback |
-| `timeout` | Request timed out | Retry then fallback |
-| `service_unavailable` | 503 error | Immediate fallback |
-| `model_overloaded` | Model capacity | Immediate fallback |
-| `quota_exceeded` | Billing limit | Fallback + alert |
-| `error_5xx` | Server errors | Retry then fallback |
-
-### Configuration
-
-```yaml
-ai:
-  fallbacks:
-    triggers:
-      rate_limit:
-        action: "immediate_fallback"
-        notify: false
-
-      timeout:
-        threshold: 30000  # ms
-        retry_count: 1
-        action: "retry_then_fallback"
-
-      quota_exceeded:
-        action: "fallback_and_alert"
-        alert_channel: "slack:#ai-alerts"
-```
-
----
-
-## Retry Logic
-
-### Retry Configuration
-
-```yaml
-ai:
-  fallbacks:
-    retry:
-      enabled: true
-      max_attempts: 3
-
-      # Backoff strategy
-      backoff:
-        type: "exponential"  # exponential, linear, fixed
-        initial_delay: 1000  # ms
-        max_delay: 10000     # ms
-        multiplier: 2
-
-      # Retry conditions
-      retry_on:
-        - "timeout"
-        - "error_5xx"
-        - "network_error"
-
-      # Don't retry these
-      no_retry:
-        - "rate_limit"
-        - "invalid_request"
-        - "auth_error"
-```
-
-### Retry Flow
-
-```
-Request Failed
-     │
-     ▼
-[Retryable Error?]
-     │
-    Yes ──▶ Wait (backoff) ──▶ Retry
-     │              │
-     │         [Max Attempts?]
-     │              │
-     │             Yes ──▶ Fallback to Next Model
-     │              │
-     │             No ──▶ Retry Again
-     │
-    No ──▶ Fallback Immediately
-```
-
----
-
-## Graceful Degradation
-
-### Quality Tiers
-
-```yaml
-ai:
-  fallbacks:
-    degradation:
-      # Define quality tiers
-      tiers:
-        premium:
-          models: ["claude-3-opus", "gpt-4-turbo"]
-          features: ["full"]
-
-        standard:
-          models: ["claude-3-sonnet", "gpt-4"]
-          features: ["full"]
-
-        basic:
-          models: ["claude-3-haiku", "gpt-3.5-turbo"]
-          features: ["limited"]
-          disabled:
-            - "complex_analysis"
-            - "large_context"
-
-      # Notify on degradation
-      notify_on_degradation: true
-      notification_channel: "slack:#ai-status"
-```
-
-### Feature Limitations
-
-```yaml
-ai:
-  fallbacks:
-    degradation:
-      feature_fallbacks:
-        # If complex analysis unavailable
-        complex_analysis:
-          fallback_to: "basic_analysis"
-          notify: true
-
-        # If large context unavailable
-        large_context:
-          fallback_to: "chunked_processing"
-          max_chunk_size: 4000
-```
-
----
-
-## Health Monitoring
-
-### Provider Health Checks
-
-```yaml
-ai:
-  health:
-    enabled: true
-    check_interval: "60s"
-
-    checks:
-      anthropic:
-        endpoint: "https://api.anthropic.com/health"
-        timeout: 5000
-
-      openai:
-        endpoint: "https://api.openai.com/v1/models"
-        timeout: 5000
-
-    # Pre-emptive fallback
-    preemptive:
-      enabled: true
-      unhealthy_threshold: 3  # consecutive failures
-```
-
-### Health Dashboard
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ AI Provider Health                                          │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│ Anthropic                                                   │
-│ ├── claude-3-opus:   ✅ Healthy (45ms)                     │
-│ ├── claude-3-sonnet: ✅ Healthy (32ms)                     │
-│ └── claude-3-haiku:  ✅ Healthy (28ms)                     │
-│                                                             │
-│ OpenAI                                                      │
-│ ├── gpt-4-turbo:     ✅ Healthy (120ms)                    │
-│ ├── gpt-4:           ⚠️ Degraded (850ms)                   │
-│ └── gpt-3.5-turbo:   ✅ Healthy (95ms)                     │
-│                                                             │
-│ Current Routing: claude-3-opus (primary)                    │
-│ Fallback Ready: gpt-4-turbo                                │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Fallback Logging
-
-### Log Events
-
-```yaml
-ai:
-  fallbacks:
-    logging:
-      enabled: true
-
-      log_events:
-        - "fallback_triggered"
-        - "retry_attempt"
-        - "provider_switch"
-        - "degradation_activated"
-
-      include:
-        - "original_model"
-        - "fallback_model"
-        - "trigger_reason"
-        - "latency"
-```
-
-### Log Example
-
-```json
-{
-  "event": "fallback_triggered",
-  "timestamp": "2024-01-15T10:30:00Z",
-  "original_model": "claude-3-opus",
-  "fallback_model": "gpt-4-turbo",
-  "trigger": "rate_limit",
-  "retry_attempts": 0,
-  "latency_impact": "+150ms"
-}
-```
-
----
-
-## Commands
-
-```bash
-# Check fallback status
-proagents ai fallback-status
-
-# Test fallback chain
-proagents ai test-fallback
-
-# Force fallback (for testing)
-proagents ai use-fallback --model gpt-4
-
-# View fallback history
-proagents ai fallback-history --last 24h
-```
-
----
-
-## Best Practices
-
-1. **Multiple Providers**: Use models from different providers
-2. **Similar Capabilities**: Fallback models should have similar features
-3. **Monitor Costs**: Track cost differences between models
-4. **Test Regularly**: Periodically test fallback chain
-5. **Alert on Fallback**: Know when primary is unavailable
-6. **Graceful Degradation**: Plan for reduced capabilities