README.md

metadata

title: Vera Engine
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 8080
pinned: false

🚀 Vera Engine v1.0

High-Performance AI Orchestrator optimized for the magicpin Vera AI Challenge.

---

🏗️ 1. The Architecture

The system operates on a highly optimized, deterministic fail-fast fallback cascade to guarantee sub-30-second responses on constrained Hugging Face Spaces (2vCPU / 16GB RAM) without compromising reasoning quality.

🌊 4-Tier Fail-Fast Cascade

Instead of relying on a single point of failure, the engine delegates composition to a highly available 4-tier chain:

1. Tier 1 (Speed & Intelligence): NVIDIA NIM (nvidia/nemotron-3-ultra-550b-a55b) - 5s timeout.
2. Tier 2 (Fast Failover): Groq (openai/gpt-oss-20b) - 4s timeout.
3. Tier 3 (Secondary Failover): Gemini (gemini-2.5-flash) - 4s timeout.
4. Tier 4 (Local Airgap): Natively executed qwen2.5-7b-instruct or qwen2.5-3b-instruct (based on system latency) via llama-cpp-python with strict LlamaGrammar enforcement.

Dynamic Time Budgeting If an API returns a 401 or 429, the orchestrator immediately short-circuits to the next tier. Cloud timeouts are strictly capped at 13 seconds cumulative worst-case, reserving a guaranteed 14-second budget for the local airgapped model.

---

⚡ 2. Pipeline Strategy

1. Context Distiller: Instantly processes 500KB+ JSON payloads into dense factual bullet points in < 0.001s.
2. LLM Expander: Takes strict facts and expands them into compelling, natively conversational WhatsApp replies (supporting Hinglish code-mixing).
3. Auto-Repair Loop: Automatically intercepts taboo violations, word-count breaches, and CTA proliferation, dynamically calculating time budgets to fire an intra-tier self-correction prompt before failing over.
4. Strict Schema Constraints: Hardware-level LlamaGrammar (Local) and json_object format (Cloud) guarantee zero JSON parsing failures.

---

🌐 3. API Contract

Endpoint	Method	Purpose	Response Schema
/v1/healthz	GET	Compliant Liveness Probe	{"status": "ok", "uptime_seconds": 100}
/v1/metadata	GET	System Identity	{"version": "1.0", "model": "..."}
/v1/context	POST	Elastic Context Ingestion	{"accepted": true}
/v1/tick	POST	Atomic Trigger Processing	{"actions": [...]}
/v1/reply	POST	Escalated Shield Handling	`{"action": "send

---

🛠️ 4. Technical Stack

• Framework: FastAPI / Uvicorn (Port 8080)
• Local SLM Execution: llama-cpp-python (Pre-compiled CPU Wheels)
• Models: Nemotron 3 Ultra 550B, GPT OSS 20B, Gemini 2.5 Flash, Qwen2.5 7B/3B
• Infrastructure: Dockerized python:3.10-slim on Hugging Face Spaces