🔮 Oracle

A local-first, self-evolving multi-agent council. You give Oracle a goal (text or voice); a set of specialized agents — each backed by one of your local Ollama models — debate, research, critique, and refine in a loop until a Verifier gate + weighted consensus agree the goal is done. Every agent message streams to a UI and can be spoken aloud. Oracle continuously learns from the web, arXiv, and Hugging Face, is grounded in your Obsidian vault and an ingested document library, builds a knowledge graph, and evolves a per-agent "DNA" under organic (Darwinian) selection.

Everything runs on your machine against local models by default — no network required. Cloud models are opt-in.

See PLAN.md for the full design and phase roadmap.

On "sentient": Oracle builds the machinery of apparent agency — persistent memory, curiosity, self-reflection, and self-modification. It is not a claim of consciousness. See PLAN.md §12.

What it does

• Council loop — propose → critique → verify rounds until the completion gate passes or a budget (rounds / wall-clock) is hit. Each round is a small DAG so the Critic and Verifier run concurrently. Live Stop control. Council modes: council · paper · story · math · markets · supply-chain.
• Memory & grounding — a dependency-light persistent vector store (SQLite + numpy cosine kNN, embeddings from local nomic-embed-text), your Obsidian vault (sandboxed write-back into an oracle/ subtree), and an ingested document library (PDF/EPUB/HTML/Markdown, drop-folder or crawler).
• Knowledge graph — a networkx graph DB of documents, entities, and relations (vault wikilinks + LLM-extracted triples), browsable in the UI.
• Continuous learning — a daily learner (arXiv + curated curriculum) plus an always-on ambient loop that reads fresh news and discusses it live, a peer-to-peer gossip loop, and agent-driven scouting of live headlines.
• Evolving DNA — each agent has a versioned genome (temperature + a persona "lens" + learned lessons). Runs score fitness; organic selection culls the unfit and breeds the fastest-improving, with speciation, genealogy, and rollback.
• Reinforcement learning — an LLM-judge scores each run into a reward; high-reward outputs become few-shot exemplars (in-context RL) and corrective lessons attach to genomes (verbal RL). An offline LoRA path is documented in backend/training/.
• Voice, both ways — push-to-talk fills a goal via STT; a toggle narrates the council with a distinct per-agent voice. Uses local Voicebox when present, the browser's Web Speech API otherwise.
• Local + optional cloud models — the Ollama registry binds each role to a best-fit local model; optional cloud providers (Anthropic / OpenAI / Gemini / xAI) are configured per-key in the UI (keys stored locally, gitignored).

The UI is a single React app with tabs for Oracle · Live · Gossip · Council · Memory · Library · Graph · Learn · Evolve · RL · Models · Settings.

The council loop & the consensus gate

A run completes only when both hold (see backend/app/consensus.py):

1. the Verifier — which owns the hard gate — reports every acceptance criterion met (a veto), and
2. the weighted consensus score across the voting roles clears a threshold.

Two roles vote. The Critic is adversarial and votes "done" when no blocking (high-severity) issue remains — low/medium nits lower its confidence but don't veto. Because the Verifier's all_met is already the hard veto, it carries the lighter weight in the score (critic 0.6 / verifier 0.4) so the same signal isn't counted twice. A Verifier-hysteresis tie-breaker lets the gate owner complete a run when it's satisfied at high confidence for N consecutive rounds even if the Critic stays stuck — so one dissenting voice can't veto forever.

Tunable via env (all ORACLE_-prefixed): CONSENSUS_THRESHOLD (0.75), MAX_ROUNDS (8), WALL_CLOCK_SECONDS (900), VERIFIER_HYSTERESIS_ROUNDS (2), VERIFIER_HYSTERESIS_CONFIDENCE (0.9).

Prerequisites

• Ollama running locally (ollama serve) with at least one model pulled.
• Python 3.11+ and Node 18+.

Run (dev)

Background control script (start/stop both without holding a terminal):

./oracle.sh start      # start backend + frontend in the background
./oracle.sh status     # health of both
./oracle.sh stop       # stop both
./oracle.sh restart
./oracle.sh logs [backend|frontend]   # tail logs (default: both)

Or a foreground launcher (Ctrl-C stops both, hot-reload on):

./run-dev.sh

• Backend: http://localhost:8020 (API docs at /docs)
• Frontend: http://localhost:5174
• Override ports: BACKEND_PORT=… FRONTEND_PORT=… ./oracle.sh start. Backend env (e.g. ORACLE_AMBIENT_AUTOSTART=false) is inherited. Logs/PIDs live in .run/ (gitignored).

Or run the backend alone:

cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --reload --port 8020
curl http://localhost:8020/api/models | python3 -m json.tool

Tests

The council gate is covered by a fast, dependency-free test suite:

cd backend
.venv/bin/python -m pytest tests/            # with pytest (pip install -r requirements-dev.txt)
.venv/bin/python tests/test_consensus.py     # or standalone, no pytest needed

Configuration

Copy .env.example to .env and edit. All defaults are local-first and offline-capable; cloud fallback is off by default. Key vars: ORACLE_OLLAMA_BASE_URL, ORACLE_VAULT_PATH, ORACLE_VOICE_ENABLED, the loop budgets and gate thresholds above, and the learning/ambient/gossip toggles.

Cloud provider API keys are entered in the Settings tab and stored locally in backend/data/ (gitignored) — never commit them.

Voice / Voicebox

Oracle's voice uses Voicebox when its backend is running on port 17493, otherwise the browser's Web Speech API. To run Voicebox's backend only (no Tauri/Rust needed):

git clone https://github.com/jamiepine/voicebox.git && cd voicebox
python3 -m venv backend/venv && backend/venv/bin/pip install -r backend/requirements.txt
backend/venv/bin/uvicorn backend.main:app --port 17493

Note: the Kokoro TTS engine needs Python 3.12 (brew install python@3.12); on 3.13 the backend runs and Oracle detects it, but preset-voice audio generation needs a 3.12 venv. Oracle falls back to browser speech meanwhile.

Layout

Oracle/
├── PLAN.md            # full design + phase roadmap
├── backend/           # FastAPI + Ollama registry (Python)
│   ├── app/           # council loop, consensus, memory, evolution, connectors, pipelines
│   ├── skills/        # Claude-style skill files appended to agent prompts
│   ├── training/      # offline LoRA path (exemplars → JSONL → adapter)
│   └── tests/         # pytest suite (also runs standalone)
├── frontend/          # Vite + React + TypeScript UI
├── docker-compose.yml # backend container (uses host Ollama)
├── oracle.sh          # background start/stop/status control script
└── run-dev.sh         # one-command foreground dev launcher

License

Released under the MIT License — © 2026 Sudhakar Kakarakayala.