HopRouter: Smart Local/Remote AI Router

HopRouter is a hybrid, token-efficient AI agent built for the AMD Developer Hackathon: ACT II. It handles all 8 required task categories - factual knowledge, mathematical reasoning, sentiment classification, text summarisation, named entity recognition, code debugging, logical reasoning, and code generation - by intelligently deciding, per task, whether to answer locally for free or route the request to a Fireworks AI model. The router classifies each incoming prompt using lightweight keyword and structural heuristics, at zero cost. Categories a small local model (Qwen2.5-0.5B, running fully on CPU) can answer reliably - sentiment analysis and short factual questions - are resolved locally, counting as zero tokens toward the final score. Everything else is routed to the best-suited Fireworks model: kimi-k2p7-code for code debugging and generation, and minimax-m3 for math, logic, summarisation, and named entity recognition. A safety-net layer validates local answers before accepting them (checking for recognizable sentiment labels, well-formed output, etc.) and escalates to Fireworks if the local answer looks unreliable, protecting the all-or-nothing accuracy gate. During development, we discovered the Gemma models listed in ALLOWED_MODELS return 404 errors on the Fireworks serverless endpoint (they require separate on-demand deployment), so HopRouter deliberately avoids them in favor of confirmed-working models, trading the Gemma bonus prize for submission reliability. The container reads /input/tasks.json, writes /output/results.json, and routes every remote call through FIREWORKS_BASE_URL as required. All responses are capped well under the 30-second per-request limit, with the local model pre-downloaded at build time and warmed up at startup to avoid runtime network dependency. Built with Python, PyTorch (CPU-only), Hugging Face Transformers, and Docker, HopRouter reflects a background in ETL/data pipeline engineering applied to LLM orchestration.