Hydra Brain

Hydra Brain is a minimal, lightweight AI resilience and failover framework. It registers multiple AI provider endpoints as "heads", monitors their status in real-time, and dynamically selects and falls back to alternate models to guarantee execution uptime.

Core Philosophy: A failed AI model should not stop the system.

---

1. Architectural Map

hydra-brain/
├── main.py                 # Core CLI entry point (Request Execution Router)
│
├── config/
│   └── heads.json          # Priority-based configuration for active model heads
│
├── core/                   # Hydra Runtime Engine
│   ├── hydra.py            # Main Controller coordinating request fallback
│   ├── registry.py         # Loads and validates config heads
│   ├── router.py           # Selects model based on priority and health
│   ├── health.py           # Standard HTTP ping checker for heads
│   └── state.py            # Manages cooldowns and persistent error diagnostics
│
├── providers/              # API Connection Layer
│   ├── base.py             # Abstract base class for providers
│   └── openrouter/         # OpenRouter Package
│       ├── __init__.py     # OpenRouter connection provider
│       └── discovery.py    # Discovery helper for the models endpoint
│
├── registry/               # Discovered Free Models Directory
│   ├── free_models.json    # Envelope-wrapped free models catalog (Single Source of Truth)
│   ├── free_models.csv     # Spreadsheet-compatible copy of free catalog
│   ├── free_models_grouped.json # Free models structured by provider
│   ├── openrouter_models_raw.json # Raw unmodified response from the catalog endpoint
│   ├── inventory_metadata.json # Sync timestamp and model counts metadata
│   └── model_registry.py   # Public registry search, filter, and self-healing APIs
│
├── inventory/              # Standalone Inventory Subsystem (FROZEN v1.0)
│   ├── sync_openrouter.py  # Synchronizes local registry with OpenRouter models endpoint
│   ├── compare_inventory.py# Compares current registry against historical snaps
│   └── validate_inventory.py # Validates registry structure, constraint checks, and IDs
│
├── health/                 # Standalone Health Monitor Subsystem (v0.1)
│   └── monitor.py          # Periodically ping-tests all models and writes latency updates
│
├── docs/                   # Specifications & Documentation
│   ├── architecture.md     # System-wide architecture boundaries and Contracts
│   └── registry_schema.md  # Schema definitions for registry elements
│
├── reports/                # Autogenerated Markdown Reports
│   ├── Inventory_Report.md # Current inventory metrics summary
│   └── Diff_Report.md      # Delta changes computed during sync loops
│
├── logs/
│   └── hydra.log           # Diagnostic log file
│
└── verify.py               # Complete programmatic unit testing suite

---

2. Setup & Installation

Prerequisites

• Python 3.12+
• Runs entirely on Python's built-in standard library. No external pip dependencies are required.

Setup Steps

1. Clone or copy files into your project directory.
2. Initialize .env file:

   cp .env.example .env

3. Open .env and configure your API key:

   OPENROUTER_API_KEY=your_key_here
   HYDRA_MOCK=false

---

3. Operations Guide

A. Model Discovery & Sync

Query the live OpenRouter API and rebuild the local registry:

python -m inventory.sync_openrouter

This updates all registry files and generates a reports/Diff_Report.md detailing any changes since the last run.

B. Registry Validation

Run integrity and constraint checks on the registry:

python -m inventory.validate_inventory

C. Health Checking

Run periodic health checks on all free models in the registry to update their latencies, success rates, and active states:

python -m health.monitor

D. Executing Prompts

Run the main runtime controller to execute prompts using priority fallback:

python main.py "Write a python function to compute Fibonacci numbers."

---

4. Running Unit Tests

Run the full automated test suite containing 14 unit and integration tests:

python verify.py