proagents 1.0.0

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

@@ -0,0 +1,362 @@
+# 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

@@ -0,0 +1,342 @@
+# 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