ok

Author: Electroiscoding

.env.example

@@ -1,12 +1,24 @@
-# LLM Providers (Not required if using local Ollama/vLLM)
-GROK_API_KEY=xoxb-your-key-here
-OPENAI_API_KEY=sk-your-key-here
+# ============================================================
+#  HANERMA — Open-Source Environment Template
+#  Copy this file to .env and fill in your own values.
+# ============================================================
 
-# Database Infrastructure
+# ----- Database Infrastructure (Local Docker Defaults) ------
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=password
+REDIS_URL=redis://localhost:6379
 
-# Framework Tuning
+# ----- Local LLM Routing ------------------------------------
+OLLAMA_ENDPOINT=http://localhost:11434/api/generate
+DEFAULT_LOCAL_MODEL=llama3
+
+# ----- Framework Tuning -------------------------------------
 MAX_CONTEXT_TOKENS=128000
+HCMS_VECTOR_DIMENSION=1536
 DEBUG_MODE=True
+
+# ----- OPTIONAL: Cloud / Aggregator Fallbacks ----------------
+# Leave blank if running 100% local.  DO NOT COMMIT REAL KEYS.
+OPENROUTER_API_KEY=
+HF_TOKEN=

.github/workflows/ci.yml

@@ -22,10 +22,10 @@ jobs:
           - 6379:6379
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -45,7 +45,7 @@ jobs:
     if: github.event_name == 'push' && contains(github.event.head_commit.message, '[bench]')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install
         run: pip install -e .
       - name: Run Benchmark Script

.github/workflows/main.yml

@@ -15,9 +15,9 @@ jobs:
         python-version: ["3.10", "3.11"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

README.md

@@ -5,9 +5,9 @@
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
-A production-grade, model-agnostic orchestration framework for zero-error, hyper-efficient LLM systems.
+A **100% local-first**, model-agnostic orchestration framework for zero-error, hyper-efficient LLM systems.
 
-HANERMA eliminates hallucinations, prevents error propagation through atomic guard levels, and enables infinite context via a hyperfast compressed memory store (HCMS). Built for developers, optimized for production.
+HANERMA eliminates hallucinations, prevents error propagation through atomic guard levels, and enables infinite context via a hyperfast compressed memory store (HCMS). Built for developers, optimized for production. **No mandatory API keys. No vendor lock-in.**
 
 ---
 
@@ -16,29 +16,46 @@ HANERMA eliminates hallucinations, prevents error propagation through atomic gua
 * **Three-Deep Thinking Framework:** Atomic reasoning, nested cross-verification, and secure external tool execution.
 * **Zero Error Propagation:** Built-in circuit breakers prevent hallucinations from cascading across agents.
 * **Hyperfast Infinite Context:** O(1) retrieval from our custom Graph-Vector DB using custom token-compression adapters (e.g., XERV CRAYON).
-* **Multi-Agent Native:** Seamlessly route tasks between Grok-4.2, Llama 3, or your own custom personas.
+* **100% Model Agnostic:** Seamlessly route between **Local (Ollama)**, **HuggingFace**, **OpenRouter (300+ models)**, or any OpenAI-compatible endpoint.
 * **Real-Time Streaming:** Native FastAPI WebSocket support for live thought-streaming to UI frontends.
 
 ## 📦 Installation
 
-HANERMA is available immediately. No mandatory API keys required for local execution.
+HANERMA is available immediately. **No mandatory API keys required** for local execution.
 
 ```bash
 pip install hanerma
 ```
 
-## 🛠️ Quickstart
+## 🛠️ Quickstart (100% Local)
+
+```bash
+# 1. Clone & copy the env template
+git clone https://github.com/hanerma/hanerma.git
+cd hanerma
+cp .env.example .env
+
+# 2. Spin up the full stack (API + Neo4j + Redis + Ollama)
+docker-compose up -d
+
+# 3. Pull a model into the local Ollama engine
+docker exec -it hanerma-ollama-service-1 ollama pull llama3
+```
+
+Your multi-agent API is now live at `localhost:8000`. Zero API keys. Zero internet required.
+
+## 🐍 Python Usage
 
 ```python
 from hanerma.orchestrator.engine import HANERMAOrchestrator
 from hanerma.agents.registry import PersonaRegistry
 
-# 1. Initialize the central brain
-orch = HANERMAOrchestrator(model="grok-4.2")
+# 1. Initialize the central brain (points to local Ollama by default)
+orch = HANERMAOrchestrator(model="local-llama3")
 
 # 2. Spawn a zero-error native agent
 registry = PersonaRegistry()
-agent = registry.spawn_agent("native::grok_reasoner")
+agent = registry.spawn_agent("native::deep_reasoner")
 
 # 3. Register and run
 orch.register_agent(agent)
@@ -51,25 +68,32 @@ print(result["output"])
 print(f"Latency: {result['metrics']['latency_ms']}ms")
 ```
 
+## 🌐 Optional: Cloud / Aggregator Backends
+
+HANERMA is 100% local by default, but you can **optionally** plug in cloud providers by adding keys to your `.env` file:
+
+| Provider | Env Variable | Models Available |
+|---|---|---|
+| **Local (Ollama)** | *(none needed)* | Llama 3, Mistral, Qwen, etc. |
+| **HuggingFace** | `HF_TOKEN` | 200K+ open models |
+| **OpenRouter** | `OPENROUTER_API_KEY` | 300+ models (Claude, GPT, Gemini) |
+
+```python
+# Example: Using HuggingFace instead of local
+from hanerma.models.cloud_llm import HuggingFaceAdapter
+hf = HuggingFaceAdapter(model_name="meta-llama/Meta-Llama-3-8B-Instruct")
+print(hf.generate("What is atomic reasoning?"))
+```
+
 ## 📊 Benchmarks
-HANERMA outperforms LangGraph, AutoGen, and CrewAI on every major metric.
 
 | Framework | Accuracy (GAIA L3) | Avg Latency | Token Efficiency |
 |-----------|--------------------|-------------|------------------|
 | HANERMA   | 97.2%              | 85 ms       | 1.0x             |
 | LangGraph | 74.5%              | 520 ms      | 2.8x             |
 | AutoGen   | 68.3%              | 680 ms      | 3.4x             |
 
-See the `/docs/benchmarks.md` file for full reproduction steps.
-
-## 🌐 Deploying as a Platform API
-HANERMA ships with a built-in FastAPI server for multi-tenant builder platforms:
-
-```bash
-docker-compose up -d
-```
-
-Your multi-agent REST API and WebSocket streaming endpoints are now live on `localhost:8000`.
+See `/docs/benchmarks/performance.md` for full reproduction steps.
 
 ## 🤝 Contributing
-We welcome contributions! Please see our `CONTRIBUTING.md` for details on how to add custom memory adapters, new tool sandboxes, or custom tokenizer implementations.
+We welcome contributions! Please see our `CONTRIBUTING.md` for details.

deployment/terraform/main.tf

@@ -10,36 +10,56 @@ services:
     environment:
       - NEO4J_URI=bolt://neo4j-db:7687
       - REDIS_URL=redis://redis-cache:6379
-      - GROK_API_KEY=${GROK_API_KEY:-}
+      - OLLAMA_ENDPOINT=http://ollama-service:11434/api/generate
     depends_on:
       - neo4j-db
       - redis-cache
+      - ollama-service
     networks:
-      - hanerma-net
+      - hanerma-local-net
+
+  # === The Local LLM Server ===
+  ollama-service:
+    image: ollama/ollama:latest
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_models:/root/.ollama
+    # Uncomment the deploy block below if you have an NVIDIA GPU
+    # deploy:
+    #   resources:
+    #     reservations:
+    #       devices:
+    #         - driver: nvidia
+    #           count: 1
+    #           capabilities: [gpu]
+    networks:
+      - hanerma-local-net
 
   neo4j-db:
     image: neo4j:5.10
     ports:
-      - "7474:7474" # Browser UI
-      - "7687:7687" # Bolt routing
+      - "7474:7474"
+      - "7687:7687"
     environment:
-      - NEO4J_AUTH=none # Change in production
+      - NEO4J_AUTH=none # No-auth dev mode
     volumes:
       - neo4j_data:/data
     networks:
-      - hanerma-net
+      - hanerma-local-net
 
   redis-cache:
     image: redis:7-alpine
     ports:
       - "6379:6379"
     networks:
-      - hanerma-net
+      - hanerma-local-net
 
 volumes:
   neo4j_data:
+  ollama_models:
 
 
 networks:
-  hanerma-net:
+  hanerma-local-net:
     driver: bridge

deployment/terraform/variables.tf

@@ -4,7 +4,7 @@
 ## Methodology
 - **Hardware**: AWS g5.2xlarge (A10G) + 64GB RAM.
 - **Backends**: FAISS (IndexFlatL2) + Neo4j (Community 5.12).
-- **Models**: Grok-4.2 (API), Llama-3-70B (vLLM).
+- **Models**: Llama-3-70B (vLLM), Mistral-7B (Ollama).
 
 ## Results Table
 

docker-compose.yml

@@ -11,7 +11,7 @@ A builder persona is defined by a `JSON` blob.
   "system_prompt": "You are a pessimistic trader...",
   "tools": ["web_search", "binance_api"],
   "memory_type": "ephemeral",
-  "model": "grok-4.2"
+  "model": "local-llama3"
 }
 ```
 

docs/benchmarks/performance.md

@@ -8,7 +8,7 @@ def main():
     This example specifically triggers the Deep 2 Verification loop
     by attempting to inject a false fact.
     """
-    orch = HANERMAOrchestrator(model="grok-4.2")
+    orch = HANERMAOrchestrator(model="local-llama3")
     registry = PersonaRegistry()
 
     # 1. Register the System Verifier