QuickRouter 🚀

QuickRouter is an ultra-lean, zero-bloat AI routing bridge designed for SaaS architects and developers. It intercepts code drafts, commands, and prompts copied from the x.ai/bot (Grok) interface and intelligently channels them across local and cloud LLM tiers without heavy autonomous frameworks (No CrewAI, No LangChain, No AutoGen).

---

🏛️ System Architecture

                    ┌────────────────────────────┐
                    │  x.ai / Grok Web Interface │
                    │   (Code Drafts & Prompts)  │
                    └─────────────┬──────────────┘
                                  │
                       [ QuickRouter Engine ]
                    (Smart Heuristic Classifier)
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
 ┌──────────────┐         ┌──────────────┐         ┌────────────────┐
 │  Tier: easy  │         │  Tier: hard  │         │  Tier: free    │
 │ Ollama Local │         │ Antigravity  │         │ Free Cloud API │
 │ (Zero Cost)  │         │ Architectural│         │  Failover Pool │
 └──────┬───────┘         └──────┬───────┘         └───────┬────────┘
        │                        │                         │
  Multi-Model:             Multi-Model:             Multi-Provider:
  - fast (codegemma)       - architect-v1           - Groq (LLaMA 3.3)
  - coder (gpt-oss)        - coder-pro              - OpenRouter Free
  - reasoning (gemma4)                              - Google Gemini Free
                                                    - Mistral AI

LLM Power Tiers:

1. Ollama (Local Engine - Zero Cost):
   • Ideal for boilerplate templates, CRUD endpoints, regex, file utilities, and quick scripts.
   • Multi-Model Support: Built-in presets (fast, coder, reasoning) and dynamic model discovery from local host (http://localhost:11434/api/tags).
2. Antigravity (Architectural Heavy Lifting):
   • Built for complex SaaS architectures, distributed systems, microservices, security protocols, and heavy algorithmic components.
3. Free Cloud API Pool (Multi-Provider Fallback):
   • High-speed fallback chain across Groq, OpenRouter, Google Gemini, and Mistral. If a provider encounters a rate limit or failure, QuickRouter automatically cascades to the next active provider.

---

🔒 Security & Secrets Management

• Environment-Driven (.env): No hardcoded secrets or plaintext keys. All configuration is managed via .env or system environment variables.
• Strict Git Exclusion: .env is permanently excluded via .gitignore.
• Secret Masking: Plaintext tokens are never printed in logs or terminal streams (e.g. sk-1...cdef or [PLACEHOLDER]).
• Path Traversal Protection: Input files are canonicalized; attempts to read .env as a prompt are blocked.
• Built-in Security Audit: Run python router.py --audit at any time to verify git ignore status and secret isolation.

---

⚡ Installation & Setup

1. Clone the Repository

git clone https://github.com/Tiyatrotist/QuickRouter.git
cd QuickRouter

2. Configure Environment Variables

Copy the template and adjust your settings:

cp .env.example .env

Edit .env with your preferred models and keys:

# Ollama
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=codegemma:2b
OLLAMA_MODEL_FAST=codegemma:2b
OLLAMA_MODEL_CODER=gpt-oss:20b
OLLAMA_MODEL_REASONING=gemma4:26b

# Antigravity
ANTIGRAVITY_ENABLED=true
ANTIGRAVITY_BASE_URL=https://api.antigravity.ai/v1
ANTIGRAVITY_API_KEY=your_antigravity_api_key_here
ANTIGRAVITY_MODEL=antigravity-architect-v1

# Free API Pool
GROQ_ENABLED=true
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

3. Install Dependencies (Optional)

pip install -r requirements.txt
# Or install in editable mode:
pip install -e .

---

💻 CLI Usage

Direct Prompt Execution

# 1. Automatic heuristic tier detection
python router.py "Create a distributed transaction pattern using Saga in Python"

# 2. Force local Ollama (easy tier) with debug logs
python router.py "Write a FastAPI CRUD boilerplate for users" --tier easy --debug

# 3. Use a specific model preset (e.g. fast, coder, reasoning)
python router.py "Write a binary search algorithm in Python" -t easy -m fast

# 4. Save output directly to a file
python router.py "PostgreSQL database connection pool class" -t hard -o db_pool.py

# 5. Copy response directly to OS clipboard
python router.py "Generate a regex for validating UUID v4" -t easy --clip

Working with Files

Safely process long code snippets or prompts exported from Grok:

python router.py -f grok_prompt.txt -t hard -o architecture_solution.py

Model Discovery & Security Audit

# List all installed Ollama models and configured cloud providers
python router.py --models

# Run the automated security and secret exposure audit
python router.py --audit

Interactive REPL Mode

Keep a session open while working with Grok:

python router.py --interactive

[QuickRouter] >>> [easy] write a python script to parse a csv file
[QuickRouter] >>> [hard] design a multi-tenant database schema with tenant isolation
[QuickRouter] >>> :models
[QuickRouter] >>> :audit

---

🐍 Python SDK Usage

from quickrouter import GrokBridgeRouter

# Initialize router (loads from .env automatically)
router = GrokBridgeRouter(debug=True)

# 1. Automatic classification based on prompt complexity
prompt = "Design a fault-tolerant microservice architecture for billing"
response = router.route(prompt)
print(response)

# 2. Explicit tier selection ('easy', 'hard', 'free')
easy_code = router.route("Generate UUID helper function", tier="easy", model="fast")
print(easy_code)

# 3. Safe file routing
result = router.route_file("grok_task.txt", tier="hard")
print(result)

---

🧪 Testing

Run the test suite with pytest:

pytest

---

🇹🇷 Türkçe Özet (Turkish Quick Summary)

QuickRouter; x.ai/Grok üzerinden kopyalanan SaaS kod taslaklarını ve komutları harici ağır kütüphaneler (CrewAI, LangChain vb.) kullanmadan yöneten saf Python tabanlı bir yönlendiricidir:

• .env Yapılandırması: Tüm anahtarlar .env dosyasında güvenli bir şekilde saklanır; Git'e sızması .gitignore ve dahili güvenlik kontrolleri ile engellenir.
• Çoklu Model Desteği: Ollama üzerinde tek bir modelle sınırlı kalmaz; fast, coder, reasoning ön ayarlarıyla sistemde yüklü modelleri otomatik algılar. Antigravity ve Ücretsiz Havuzda da yedek (fallback) modeller sunar.
• Güvenlik Denetimi: python router.py --audit komutu ile projedeki gizli anahtar izolasyonunu istediğiniz an test edebilirsiniz.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.