proagents 1.6.17 → 1.6.19

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

package/.proagents/ai-models/model-config.md

@@ -1,318 +0,0 @@
-# Model Configuration
-
-Configure AI models and providers for your workflow.
-
----
-
-## Provider Setup
-
-### Anthropic (Claude)
-
-```yaml
-ai:
-  providers:
-    anthropic:
-      api_key: "${ANTHROPIC_API_KEY}"
-      base_url: "https://api.anthropic.com"  # Optional
-
-      models:
-        claude-3-opus:
-          max_tokens: 4096
-          temperature: 0.7
-          context_window: 200000
-
-        claude-3-sonnet:
-          max_tokens: 4096
-          temperature: 0.7
-          context_window: 200000
-
-        claude-3-haiku:
-          max_tokens: 4096
-          temperature: 0.7
-          context_window: 200000
-
-      rate_limits:
-        requests_per_minute: 50
-        tokens_per_minute: 100000
-```
-
-### OpenAI (GPT)
-
-```yaml
-ai:
-  providers:
-    openai:
-      api_key: "${OPENAI_API_KEY}"
-      organization: "${OPENAI_ORG}"  # Optional
-
-      models:
-        gpt-4-turbo:
-          max_tokens: 4096
-          temperature: 0.7
-          context_window: 128000
-
-        gpt-4:
-          max_tokens: 8192
-          temperature: 0.7
-          context_window: 8192
-
-        gpt-3.5-turbo:
-          max_tokens: 4096
-          temperature: 0.7
-          context_window: 16384
-
-      rate_limits:
-        requests_per_minute: 60
-        tokens_per_minute: 90000
-```
-
-### Google (Gemini)
-
-```yaml
-ai:
-  providers:
-    google:
-      api_key: "${GOOGLE_API_KEY}"
-      project_id: "${GOOGLE_PROJECT}"  # For Vertex AI
-
-      models:
-        gemini-pro:
-          max_tokens: 2048
-          temperature: 0.7
-          context_window: 32000
-
-        gemini-ultra:
-          max_tokens: 8192
-          temperature: 0.7
-          context_window: 32000
-```
-
-### Local Models (Ollama)
-
-```yaml
-ai:
-  providers:
-    ollama:
-      base_url: "http://localhost:11434"
-
-      models:
-        llama2:
-          context_window: 4096
-          temperature: 0.7
-
-        codellama:
-          context_window: 16384
-          temperature: 0.5
-
-        mistral:
-          context_window: 8192
-          temperature: 0.7
-```
-
----
-
-## Model Selection
-
-### Default Model
-
-```yaml
-ai:
-  default_provider: "anthropic"
-  default_model: "claude-3-sonnet"
-```
-
-### Per-Task Models
-
-```yaml
-ai:
-  task_routing:
-    # Complex analysis
-    code_analysis:
-      model: "claude-3-opus"
-      reason: "Best for deep code understanding"
-
-    # Code generation
-    code_generation:
-      model: "claude-3-sonnet"
-      reason: "Good balance of speed and quality"
-
-    # Quick tasks
-    quick_tasks:
-      model: "claude-3-haiku"
-      reason: "Fast for simple tasks"
-
-    # Documentation
-    documentation:
-      model: "gpt-4"
-      reason: "Good at technical writing"
-
-    # Tests
-    test_generation:
-      model: "claude-3-sonnet"
-      reason: "Understands code context well"
-```
-
----
-
-## Model Parameters
-
-### Temperature
-
-Controls randomness/creativity:
-
-```yaml
-models:
-  # Creative tasks (docs, names)
-  creative:
-    temperature: 0.9
-
-  # Balanced tasks (code)
-  balanced:
-    temperature: 0.7
-
-  # Deterministic tasks (analysis)
-  precise:
-    temperature: 0.3
-```
-
-### Max Tokens
-
-Control response length:
-
-```yaml
-models:
-  # Short responses
-  short:
-    max_tokens: 1024
-
-  # Standard responses
-  standard:
-    max_tokens: 4096
-
-  # Long responses
-  long:
-    max_tokens: 8192
-```
-
-### System Prompts
-
-```yaml
-ai:
-  system_prompts:
-    code_analysis: |
-      You are an expert code analyst. Analyze the provided code
-      for patterns, issues, and improvements.
-
-    code_generation: |
-      You are a senior developer. Write clean, well-documented
-      code following the project's conventions.
-
-    documentation: |
-      You are a technical writer. Write clear, concise
-      documentation for developers.
-```
-
----
-
-## Model Comparison
-
-### Claude Models
-
-| Model | Speed | Quality | Cost | Best For |
-|-------|-------|---------|------|----------|
-| Opus | Slow | Excellent | $$$ | Complex analysis |
-| Sonnet | Medium | Very Good | $$ | General development |
-| Haiku | Fast | Good | $ | Quick tasks |
-
-### OpenAI Models
-
-| Model | Speed | Quality | Cost | Best For |
-|-------|-------|---------|------|----------|
-| GPT-4 Turbo | Fast | Excellent | $$ | Large context tasks |
-| GPT-4 | Medium | Excellent | $$$ | Complex reasoning |
-| GPT-3.5 | Fast | Good | $ | Simple tasks |
-
-### Selection Guide
-
-```
-Task Complexity → Model Selection
-
-Simple (config, typos)    → Haiku / GPT-3.5
-Medium (bug fixes, small) → Sonnet / GPT-4 Turbo
-Complex (architecture)    → Opus / GPT-4
-```
-
----
-
-## Testing Models
-
-### Connectivity Test
-
-```bash
-# Test all configured providers
-proagents ai test
-
-# Test specific provider
-proagents ai test --provider anthropic
-
-# Test specific model
-proagents ai test --model claude-3-opus
-```
-
-### Output
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ AI Model Test Results                                       │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│ Anthropic:                                                  │
-│ ├── claude-3-opus: ✅ Connected (latency: 450ms)           │
-│ ├── claude-3-sonnet: ✅ Connected (latency: 280ms)         │
-│ └── claude-3-haiku: ✅ Connected (latency: 120ms)          │
-│                                                             │
-│ OpenAI:                                                     │
-│ ├── gpt-4-turbo: ✅ Connected (latency: 380ms)             │
-│ ├── gpt-4: ✅ Connected (latency: 520ms)                   │
-│ └── gpt-3.5-turbo: ✅ Connected (latency: 150ms)           │
-│                                                             │
-│ Google:                                                     │
-│ └── gemini-pro: ❌ API key invalid                         │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `ANTHROPIC_API_KEY` | Anthropic API key |
-| `OPENAI_API_KEY` | OpenAI API key |
-| `OPENAI_ORG` | OpenAI organization ID |
-| `GOOGLE_API_KEY` | Google AI API key |
-| `PROAGENTS_DEFAULT_MODEL` | Override default model |
-
-### Secure Key Storage
-
-```bash
-# Use system keychain
-proagents ai config --set-key anthropic --secure
-
-# Use environment file
-# .env.local (gitignored)
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-```
-
----
-
-## Best Practices
-
-1. **Start with Sonnet/GPT-4**: Good balance for most tasks
-2. **Use Haiku for Speed**: Quick operations, simple fixes
-3. **Reserve Opus for Complex**: Deep analysis, architecture
-4. **Set Cost Limits**: Prevent unexpected charges
-5. **Test Regularly**: Ensure API keys are valid
-6. **Use Environment Variables**: Never commit API keys