Built for the AMD Developer Hackathon 2026 - Track 1: Hybrid Token-Efficient Routing Agent
An intelligent, multi-tier routing system designed to maximize task-solving accuracy while minimizing cloud API token costs. By leveraging local GPU resources for quick validation and classification, the system routes tasks dynamically across deterministic solvers, local hardware, and tiered cloud LLMs.
The router processes tasks through a 5-tier waterfall designed to maximize cost savings:
graph TD
%% Define Styles
classDef default fill:#141414,stroke:#f5f5f5,stroke-width:1px,color:#f5f5f5;
classDef startNode fill:#f5f5f5,stroke:#f5f5f5,color:#0a0a0a;
classDef solverNode fill:#00e676,stroke:#00e676,stroke-width:1px,color:#0a0a0a;
classDef cloudNode fill:#ff5252,stroke:#ff5252,stroke-width:1px,color:#ffffff;
A[Input Task Query]:::startNode --> B[Regex Heuristics Classifier]
B --> C{T0: Deterministic Solvers}
C -- "Solved (Free)" --> D[Return Output Answer]:::solverNode
C -- "Unsolved" --> E[T1: Local LLM Gemma/Qwen]
E --> F{Confidence Gate}
F -- "High Confidence (Free)" --> D
F -- "Low Confidence" --> G[T2: Fireworks Cheap Model Mixtral]
G --> H{Validation Gate}
H -- "Verified" --> D
H -- "Uncertain" --> I[T3: Fireworks Strong Model Llama 70B]:::cloudNode
I --> D
Here is a visual breakdown of the Control Center Dashboard and how it tracks operations:
Visualizes real-time metrics (Total processed tasks, Estimated Token Savings, Local Solver Rate, and P95 Pipeline Latency) computed directly from Firestore.
Allows developers to monitor log entries as they sync from Firestore, paginated into pages of 5 items.
Lets you test prompts locally and witness how the orchestrator cascades each task through the routing waterfall.
Displays the live percentage breakdown of which tiers are solving tasks, helping tune model confidence thresholds.
Real-time stats update instantly when other team members submit tasks from other clients.
The system is optimized around the official competition scoring logic:
- Accuracy Score: Percentage of correct answers.
- Token Penalty: Cost incurred through paid Fireworks cloud tokens.
- Local & Solver Runs (Tier 0 & Tier 1): Incur zero token penalty, keeping your evaluation runs cheap and boosting the total leaderboard score.
Create a .env file in the root directory:
# Fireworks API Configuration
FIREWORKS_API_KEY=fw_your_api_key_here
FIREWORKS_BASE_URL=https://api.fireworks.ai/inference/v1
# HuggingFace Configuration (For Local Model Download / Serverless API)
HF_TOKEN=hf_your_token_here
MODEL_NAME=google/gemma-3-12b-it
USE_HF_SERVERLESS=true
# Local Model Server Link
LOCAL_MODEL_URL=http://localhost:8000
# Tuning Thresholds
HIGH_CONFIDENCE_THRESHOLD=0.85
MEDIUM_CONFIDENCE_THRESHOLD=0.60
# Telemetry & Optimization
ENABLE_CACHE=true
ENABLE_DASHBOARD=false
LOG_LEVEL=info
LOG_DB_PATH=../../data/logs/tasks.dbCreate a .env file in the services/dashboard/ directory:
# Gemini API Key for AI-Assist Smart Classifier
VITE_GEMINI_API_KEY=your-gemini-api-key-here
# Firebase Configuration (Google Auth + Firestore)
VITE_FIREBASE_API_KEY=your-firebase-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id
VITE_FIREBASE_MEASUREMENT_ID=your-measurement-id- Docker & Docker Compose
- AMD GPU with ROCm support (for local inference acceleration)
- Fireworks AI API Key
- Firebase Project Credentials
- Clone the repository and navigate to the project directory:
git clone <your-repo-url> cd HybridRouter
- Set up your environment variables following the Environment Configuration templates above.
- Boot up the entire multi-service container pipeline:
docker compose up --build
- Access the React Dashboard at
http://localhost:5173.
If running services individually:
- Local Model Server (FastAPI):
cd services/local-model-server pip install -r requirements.txt python main.py - Orchestrator Backend (Express):
cd services/orchestrator npm install npm run dev - Frontend App (Vite):
cd services/dashboard npm install npm run dev
HybridRouter/
├── README.md # ← You are here
├── AGENTS.md # Agent behavioral instructions
├── .env.example # Environment variable template
├── docker-compose.yml # Multi-service Docker setup
│
├── docs/ # 📚 Technical documentation
│ ├── README.md # Documentation index
│ ├── Architecture.png # Architecture flow visual
│ ├── architecture.md # System architecture deep-dive
│ ├── classifier.md # Task classifier documentation
│ ├── tier0-deterministic-solvers.md # Deterministic solver docs
│ ├── tier1-local-model.md # Local model server docs
│ ├── tier2-tier3-fireworks.md # Fireworks escalation docs
│ └── API-reference.md # API endpoints reference
│
├── services/ # 🔧 Application services
│ ├── orchestrator/ # Node.js + Express orchestrator
│ │ ├── src/
│ │ │ ├── classifier.js # Heuristics classifier
│ │ │ ├── router.js # Waterfall router rules
│ │ │ ├── solvers/
│ │ │ │ ├── deterministic.js # Math, regex, parsing solvers
│ │ │ │ ├── localLlm.js # Local model connector
│ │ │ │ └── fireworksClient.js # Fireworks integration
│ │ │ └── server.js # Express API server
│ │ ├── main.js # Entry point (batch mode)
│ │ ├── package.json
│ │ └── Dockerfile
│ │
│ ├── local-model-server/ # Python + FastAPI local server
│ │ ├── main.py # FastAPI entry point
│ │ ├── api/
│ │ │ └── routes.py # Inference paths
│ │ ├── requirements.txt
│ │ └── Dockerfile
│ │
│ └── dashboard/ # React + Vite frontend
│ ├── src/
│ │ ├── components/
│ │ │ ├── CustomCursor.jsx # Fluid cursor component
│ │ │ ├── MetricsCards.jsx # Stats card boxes
│ │ │ ├── Playground.jsx # Input simulator form
│ │ │ ├── DecisionDistribution.jsx # Distribution charts
│ │ │ └── LiveLogs.jsx # Paginated audit log datatable
│ │ ├── pages/
│ │ │ ├── Home.jsx # Portal landing page
│ │ │ └── Console.jsx # Live control center page
│ │ ├── App.jsx # Routes & global configurations
│ │ └── index.css # Theme style rules
│ ├── package.json
│ └── Dockerfile
Built with 🧠 by Team TetraFourge for the AMD Developer Hackathon 2026
Maximize accuracy. Minimize tokens. Win.