@sparkleideas/agentic-flow 2.0.2-alpha-patch.1

package/agentic-flow/docs/plans/requesty/README.md

@@ -0,0 +1,290 @@
+# Requesty.ai Integration - Planning Documentation
+
+## Overview
+
+This directory contains comprehensive planning documentation for integrating Requesty.ai as a new provider in the agentic-flow project.
+
+**Status:** Planning Complete ✅
+**Implementation Status:** Not Started
+**Estimated Effort:** 13 hours
+**Risk Level:** LOW
+
+## What is Requesty.ai?
+
+Requesty.ai is a unified AI gateway providing:
+- Access to 300+ AI models from OpenAI, Anthropic, Google, Meta, DeepSeek, and more
+- OpenAI-compatible API (drop-in replacement)
+- 80% cost savings vs direct Anthropic API
+- Built-in analytics, caching, and auto-routing
+- Enterprise features (zero downtime, failover, load balancing)
+
+## Documentation Structure
+
+Read the documents in this order:
+
+### 1. [00-overview.md](./00-overview.md) - Start Here
+**Read this first!**
+
+- Executive summary
+- Integration goals
+- Key differentiators vs OpenRouter
+- Strategic benefits
+- Success criteria
+- Risk assessment
+
+**Time to read:** 5 minutes
+
+### 2. [01-api-research.md](./01-api-research.md) - Technical Details
+**For developers implementing the integration**
+
+- Complete API specification
+- Authentication methods
+- Request/response schemas
+- Tool calling format
+- Model naming conventions
+- Rate limits and pricing
+- Error handling
+- Comparison with OpenRouter and Anthropic
+
+**Time to read:** 15 minutes
+
+### 3. [02-architecture.md](./02-architecture.md) - System Design
+**For architects and lead developers**
+
+- High-level architecture diagrams
+- Component breakdown
+- Data flow diagrams
+- File structure
+- Configuration management
+- Error handling strategy
+- Performance considerations
+- Security architecture
+
+**Time to read:** 20 minutes
+
+### 4. [03-implementation-phases.md](./03-implementation-phases.md) - Action Plan
+**For developers ready to implement**
+
+- Step-by-step implementation guide
+- 5 phases with clear deliverables
+- Code examples
+- Acceptance criteria
+- Timeline estimates
+- Post-implementation checklist
+
+**Time to read:** 25 minutes
+**Implementation time:** 13 hours
+
+### 5. [04-testing-strategy.md](./04-testing-strategy.md) - Quality Assurance
+**For QA engineers and testers**
+
+- Unit test specifications
+- Integration test scenarios
+- E2E user workflows
+- Model-specific tests
+- Performance benchmarks
+- Security tests
+- Acceptance criteria
+
+**Time to read:** 15 minutes
+**Testing time:** 3 hours
+
+### 6. [05-migration-guide.md](./05-migration-guide.md) - User Documentation
+**For end users**
+
+- Quick start guide (3 steps)
+- Usage examples
+- Model recommendations
+- Configuration options
+- Migration from other providers
+- Troubleshooting
+- FAQ
+
+**Time to read:** 10 minutes
+
+## Key Findings
+
+### High Compatibility with OpenRouter
+
+The research revealed that Requesty.ai uses **almost identical API format** to OpenRouter:
+
+| Aspect | OpenRouter | Requesty | Compatibility |
+|--------|-----------|----------|---------------|
+| API Format | OpenAI `/chat/completions` | OpenAI `/chat/completions` | 100% |
+| Tool Calling | OpenAI functions | OpenAI functions | 100% |
+| Streaming | SSE (OpenAI) | SSE (OpenAI) | 100% |
+| Auth Method | Bearer token | Bearer token | 100% |
+| Request Schema | OpenAI | OpenAI | 100% |
+| Response Schema | OpenAI | OpenAI | 100% |
+
+**Implication:** We can clone the OpenRouter proxy with minimal changes (~95% code reuse).
+
+### Implementation Approach
+
+**Strategy:** Clone and adapt the existing OpenRouter proxy
+
+**Effort Breakdown:**
+- **Phase 1:** Core Proxy (4 hours) - Clone OpenRouter proxy
+- **Phase 2:** CLI Integration (2 hours) - Add provider detection
+- **Phase 3:** Model Support (2 hours) - Add model definitions
+- **Phase 4:** Testing (3 hours) - Comprehensive validation
+- **Phase 5:** Documentation (2 hours) - User guides
+
+**Total:** 13 hours
+
+### Major Benefits
+
+1. **300+ Models** (vs OpenRouter's 100+)
+2. **Built-in Analytics** (OpenRouter lacks this)
+3. **Auto-Routing** (intelligent model selection)
+4. **Caching** (reduce API costs further)
+5. **80% Cost Savings** (vs direct Anthropic API)
+
+### Risks
+
+**Technical Risks:** LOW
+- API format is well-documented (OpenAI-compatible)
+- Pattern is proven (OpenRouter already works)
+- 95% code reuse minimizes bugs
+
+**Business Risks:** LOW
+- Multi-provider architecture already supports fallbacks
+- Users can easily switch providers
+- No vendor lock-in
+
+## Quick Reference
+
+### Files to Create
+
+```
+agentic-flow/
+└── src/
+    └── proxy/
+        └── anthropic-to-requesty.ts   (~750 lines, 95% from OpenRouter)
+```
+
+### Files to Modify
+
+```
+agentic-flow/
+├── src/
+│   ├── cli-proxy.ts                   (+ ~80 lines)
+│   ├── agents/claudeAgent.ts          (+ ~15 lines)
+│   └── utils/
+│       ├── modelCapabilities.ts       (+ ~50 lines)
+│       └── modelOptimizer.ts          (+ ~100 lines)
+└── README.md                          (+ Requesty section)
+```
+
+### Total Code Impact
+
+| Metric | Count |
+|--------|-------|
+| New files | 1 |
+| Modified files | 4 |
+| New lines of code | ~1,000 |
+| Reused lines | ~750 (95% from OpenRouter) |
+| Original code | ~250 |
+
+## Success Criteria
+
+### Must Have (MVP)
+- [ ] Users can use `--provider requesty` flag
+- [ ] Requesty API key via `REQUESTY_API_KEY` environment variable
+- [ ] Chat completions work with at least 10 tested models
+- [ ] Native tool calling support (MCP tools work)
+- [ ] Streaming responses supported
+- [ ] Error handling and logging
+- [ ] Model override via `--model` flag
+
+### Should Have (V1)
+- [ ] Tool emulation for models without native support
+- [ ] Model capability detection for Requesty models
+- [ ] Integration with model optimizer (`--optimize`)
+- [ ] Analytics and usage tracking
+- [ ] Proxy mode for Claude Code/Cursor
+- [ ] Cost estimation and reporting
+
+## Implementation Checklist
+
+Use this checklist when implementing:
+
+### Phase 1: Core Proxy ✅ Planned
+- [ ] Clone `anthropic-to-openrouter.ts` to `anthropic-to-requesty.ts`
+- [ ] Update class name, base URL, API key variable
+- [ ] Update logging messages
+- [ ] Test compilation
+
+### Phase 2: CLI Integration ✅ Planned
+- [ ] Add `shouldUseRequesty()` method
+- [ ] Add `startRequestyProxy()` method
+- [ ] Integrate into start flow
+- [ ] Update runAgent method
+- [ ] Test CLI detection
+
+### Phase 3: Model Support ✅ Planned
+- [ ] Add 15+ models to `modelCapabilities.ts`
+- [ ] Update `claudeAgent.ts` provider detection
+- [ ] Add 10+ models to model optimizer
+- [ ] Test model detection
+
+### Phase 4: Testing ✅ Planned
+- [ ] Write unit tests (>90% coverage)
+- [ ] Run integration tests (5+ models)
+- [ ] Test tool calling
+- [ ] Test streaming
+- [ ] Validate error handling
+
+### Phase 5: Documentation ✅ Planned
+- [ ] Update README.md
+- [ ] Create migration guide
+- [ ] Update help text
+- [ ] Update .env.example
+
+## Next Steps
+
+1. **Review Planning Docs** - Read 00-overview.md through 05-migration-guide.md
+2. **Get Stakeholder Approval** - Present plan to team/maintainers
+3. **Set Up Test Account** - Get Requesty.ai API key for testing
+4. **Begin Implementation** - Follow 03-implementation-phases.md
+5. **Test Thoroughly** - Use 04-testing-strategy.md
+6. **Ship to Users** - Deploy with 05-migration-guide.md
+
+## Questions?
+
+If you have questions about the implementation plan:
+
+1. Check the FAQ in `05-migration-guide.md`
+2. Review the specific planning document
+3. Open a GitHub issue with questions
+4. Tag the planning document author
+
+## Contributing
+
+If you find gaps in the planning documentation:
+
+1. Open an issue describing the gap
+2. Submit a PR with improvements
+3. Update this README with new findings
+
+## Changelog
+
+- **2025-01-07** - Initial planning documentation created
+- Research completed on Requesty.ai API
+- All 6 planning documents written
+- Ready for implementation
+
+## Credits
+
+**Planning Author:** Claude Code
+**Project:** agentic-flow
+**Based On:** OpenRouter integration pattern
+**Documentation Standard:** SPARC methodology
+
+---
+
+**Ready to implement?** Start with [03-implementation-phases.md](./03-implementation-phases.md)
+
+**Need user docs?** Jump to [05-migration-guide.md](./05-migration-guide.md)
+
+**Want technical details?** Read [02-architecture.md](./02-architecture.md)

package/agentic-flow/docs/providers/LANDING-PAGE-PROVIDER-CONTENT.md

@@ -0,0 +1,204 @@
+# Provider Integration Content for Landing Page
+
+**Suggested Section**: Add this content to https://ruv.io/agentic-flow as a new "Provider Support" section
+
+---
+
+## 🔌 Multi-Provider LLM Support
+
+**agentic-flow** works with multiple LLM providers through intelligent proxy architecture that automatically converts requests to provider-specific formats while maintaining full compatibility with Claude Agent SDK.
+
+### Supported Providers
+
+| Provider | Models | Cost vs Claude | Speed | Setup Required |
+|----------|--------|----------------|-------|----------------|
+| **Anthropic** | Claude 3.5 Sonnet, Opus, Haiku | Baseline | Fast | `ANTHROPIC_API_KEY` |
+| **Gemini** (NEW v1.9.3) | Gemini 2.0 Flash, Pro | **70% cheaper** | **2-5x faster** | `GOOGLE_GEMINI_API_KEY` |
+| **OpenRouter** | 100+ models (GPT-4, Llama, DeepSeek) | Varies | Varies | `OPENROUTER_API_KEY` |
+| **ONNX** | Phi-4 (runs locally) | **100% FREE** | Medium | No key needed |
+
+### Quick Provider Examples
+
+```bash
+# Anthropic (default, highest quality)
+npx agentic-flow --agent coder --task "Build REST API"
+
+# Gemini (fastest, cheapest - NEW in v1.9.3!)
+npx agentic-flow --agent coder --task "Build REST API" --provider gemini
+
+# OpenRouter (access 100+ models)
+npx agentic-flow --agent coder --task "Build REST API" --provider openrouter
+
+# ONNX (100% free, runs locally)
+npx agentic-flow --agent coder --task "Build REST API" --provider onnx
+```
+
+### Gemini Provider - Fully Functional (v1.9.3)
+
+The **Gemini provider is now production-ready** with complete streaming support. Three critical bugs were fixed in v1.9.3:
+
+✅ **Model Selection** - Correctly uses Gemini models instead of Claude model names
+✅ **Streaming Responses** - Full Server-Sent Events (SSE) support with `&alt=sse` parameter
+✅ **Provider Selection** - Respects `--provider` flag and doesn't auto-select incorrectly
+
+**Gemini Benefits:**
+- ⚡ **2-5x faster response times** compared to Anthropic
+- 💰 **70% cost reduction** - great for high-volume tasks
+- 🎯 **Excellent for** code generation, code analysis, refactoring, simple tasks
+- ✅ **Full streaming support** for real-time responses
+- 🔄 **Zero code changes** - drop-in replacement via proxy architecture
+
+**Setup:**
+```bash
+# Get your free Gemini API key from https://ai.google.dev/
+export GOOGLE_GEMINI_API_KEY=your_key_here
+
+# Use Gemini with streaming
+npx agentic-flow --agent coder --task "Create function" --provider gemini --stream
+```
+
+### How Provider Proxies Work
+
+**Intelligent Request Conversion:**
+
+1. **User makes request** → Claude Agent SDK format (Anthropic Messages API)
+2. **Proxy intercepts** → Converts to provider-specific format
+3. **Provider responds** → Native format (Gemini, OpenRouter, etc.)
+4. **Proxy converts back** → Claude Agent SDK format
+5. **User receives** → Standard response, no code changes needed
+
+**Architecture Benefits:**
+- ✅ **Single codebase** works with all providers
+- ✅ **Provider-agnostic** agent development
+- ✅ **Easy switching** between providers via CLI flags
+- ✅ **Cost optimization** - use cheap providers for simple tasks, Claude for complex ones
+- ✅ **Automatic failover** - switch providers if one is down
+
+### Configuration
+
+**Environment Variables:**
+```bash
+# Provider API Keys (set only what you need)
+export ANTHROPIC_API_KEY=sk-ant-...        # Anthropic Claude
+export GOOGLE_GEMINI_API_KEY=AIza...       # Google Gemini
+export OPENROUTER_API_KEY=sk-or-...        # OpenRouter
+
+# Model Selection (optional)
+export COMPLETION_MODEL=claude-sonnet-4-5-20250929  # Anthropic model
+export REASONING_MODEL=gemini-2.0-flash-exp         # Gemini model
+```
+
+**CLI Flags:**
+```bash
+--provider <name>    # anthropic, gemini, openrouter, onnx
+--model <model-id>   # Override default model
+--stream             # Enable streaming responses
+```
+
+### Cost Optimization Strategy
+
+**Smart Provider Selection:**
+
+```bash
+# Simple tasks → Use Gemini (70% cheaper, 5x faster)
+npx agentic-flow --agent coder --task "Add comments" --provider gemini
+
+# Complex reasoning → Use Claude (highest quality)
+npx agentic-flow --agent researcher --task "Analyze architecture" --provider anthropic
+
+# Experimentation → Use ONNX (100% free)
+npx agentic-flow --agent tester --task "Generate tests" --provider onnx
+
+# Access specific models → Use OpenRouter
+npx agentic-flow --agent coder --task "Optimize code" --provider openrouter --model meta-llama/llama-3.2-3b-instruct
+```
+
+### Production Deployment
+
+**High-Volume Applications:**
+```bash
+# Use Gemini for 80% of requests (fast, cheap)
+export DEFAULT_PROVIDER=gemini
+export GOOGLE_GEMINI_API_KEY=...
+
+# Fall back to Claude for complex tasks
+export ANTHROPIC_API_KEY=...
+
+# Run with automatic provider selection
+npx agentic-flow --agent coder --task "..." # Uses Gemini by default
+npx agentic-flow --agent architect --task "..." --provider anthropic # Override for complex tasks
+```
+
+**Monitoring:**
+- Track token usage per provider
+- Monitor response quality
+- Measure cost savings
+- Analyze performance metrics
+
+---
+
+## Why This Matters for Consulting Clients
+
+**Cost Savings:**
+- **70% reduction** in LLM costs using Gemini for appropriate tasks
+- **100% free** local inference with ONNX for development/testing
+- **Flexible budgeting** - scale up/down providers based on needs
+
+**Performance:**
+- **2-5x faster** responses with Gemini for code generation
+- **Real-time streaming** for better user experience
+- **Local inference** option eliminates API latency
+
+**Flexibility:**
+- **100+ models** available via OpenRouter
+- **Zero vendor lock-in** - switch providers anytime
+- **Multi-provider strategies** - use best tool for each job
+
+---
+
+## Technical Specifications
+
+**Proxy Architecture:**
+- Located in `src/proxy/` directory
+- `anthropic-to-gemini.ts` - Gemini proxy (v1.9.3 - fully functional)
+- `anthropic-to-openrouter.ts` - OpenRouter proxy
+- Automatic request/response format conversion
+- Full MCP tool support via function calling conversion
+- Streaming and non-streaming modes
+
+**Supported Features:**
+- ✅ Text generation
+- ✅ Streaming responses (SSE)
+- ✅ Tool calling / Function calling
+- ✅ System prompts
+- ✅ Multi-turn conversations
+- ✅ Temperature control
+- ✅ Token limits
+
+**Verified Compatibility:**
+- Claude Agent SDK
+- Claude Code CLI
+- MCP (Model Context Protocol) tools
+- All 66 specialized agents
+- Multi-agent swarm orchestration
+
+---
+
+## Get Started
+
+```bash
+# Install agentic-flow
+npm install -g agentic-flow@1.9.3
+
+# Setup your preferred provider
+export GOOGLE_GEMINI_API_KEY=your_key_here
+
+# Run your first agent with Gemini
+npx agentic-flow --agent coder --task "Write a hello world function" --provider gemini --stream
+
+# See the cost and speed difference yourself!
+```
+
+**Documentation:** https://github.com/ruvnet/agentic-flow#readme
+**Full Provider Guide:** https://github.com/ruvnet/agentic-flow#-provider-support
+**Latest Release:** v1.9.3 - Gemini Provider Fully Functional