Your retro-futuristic, locally operated AI assistant.
Orac is a Linux-hosted conversational AI system built around a local LLM, Oracle Database, a voice pipeline, optional internet retrieval, and a governed plugin runtime. It is designed for local operation and explicit control over credentials, retrieval, plugins, and home-automation integrations.
- Local LLM conversations through Ollama or another compatible configured service.
- Persistent conversation and configuration data in Oracle Database.
- Local speech recognition with Faster Whisper.
- Wake-word activation with openWakeWord, plus optional Porcupine support.
- Speech synthesis through Kokoro with Piper fallback.
- Explicit or policy-controlled internet retrieval through a local SearXNG service.
- Deterministic, core-owned dialogue routing across plugins, authorised local knowledge, internet retrieval, and ordinary LLM conversation.
- Manifest-driven plugins with scoped configuration, secrets, execution policy, service lifecycle, database deployment, packaged APEX application installation, shared navigation, and audit boundaries.
- Home Assistant inventory synchronisation, area/device listings, temperature and humidity queries, live light-state read-back, and allowlisted interaction with lights, switches, and scenes.
- Rich light interaction for supported Home Assistant entities, including brightness, colour, and colour-temperature changes validated against live device capabilities.
- The bundled Weather plugin answers current-condition and short-forecast questions for explicit or configured locations through Open-Meteo.
- The bundled Drop Box plugin scans configured folders, creates durable jobs, and hands verified local text and Markdown documents to Core-managed ingestion, chunking, embedding, and provenance services. Ingested content can support opt-in, scope-authorised grounded dialogue retrieval.
- Browser and desktop display surfaces for runtime state and transcripts.
- Oracle APEX administration, including framework-managed plugin applications such as Home Assistant Status and Drop Box Admin, plus backup and restore tooling for the local deployment.
Orac is under active development. Several foundations are operational, while some advertised capabilities remain intentionally constrained:
- Home Assistant mutations are deliberately limited to exact, allowlisted light, switch, and scene operations. Arbitrary services, whole-home commands, and control of locks, alarms, climate, covers, fans, scripts, and automations are not enabled.
- Local-knowledge dialogue retrieval is disabled by default and currently supports UTF-8 text and Markdown ingestion. The shipped hash embedding is development/test infrastructure, lexical relevance is the current evidence gate, and native Oracle vector search is not yet part of the runtime.
- Barge-in, native playback, and acoustic echo cancellation include experimental modes and require explicit configuration.
- Media control remains a policy-blocked scaffold, and the OpenAI-compatible gateway settings are reserved for a future service.
- Detailed future work remains in the project backlog and is not presented as current runtime capability.
The following optional integrations are planned but are not currently implemented runtime capabilities:
- IndexTTS2 voice design behind the existing TTS provider abstraction. Piper and Kokoro remain the supported baseline, and cloning or designing a real person's voice would require explicit consent.
- Open WebUI integration as an optional user interface into Orac, potentially through the planned OpenAI-compatible gateway. Orac would continue to own routing, plugin policy, persistence, and local knowledge.
- A Raspberry Pi smart-speaker satellite with a thin audio/display software stack for microphone capture, playback, Orac status, and optional kiosk display. Processing and authority would remain with the central Orac runtime; LiveKit is a candidate transport rather than a committed dependency.
| Component | Role | Required |
|---|---|---|
| Orac AI engine | Conversation orchestration, plugins, context, retrieval | Yes |
| Oracle Database + ORDS/APEX | Persistence, core administration, and framework-managed plugin APEX applications | Yes for the supported local stack |
| Local LLM service | Model inference, normally Ollama | Yes |
| SearXNG | Local/private search provider | When internet retrieval is enabled |
| Faster Whisper | Local speech-to-text | For voice operation |
| Kokoro or Piper | Local text-to-speech | For spoken responses |
| Home Assistant plugin | Inventory, live state and sensor queries, and allowlisted light/switch/scene interaction | Optional |
| Drop Box plugin + Core knowledge | Scheduled local document discovery, durable ingestion, and scope-authorised grounded retrieval | Optional |
| Weather plugin | Open-Meteo current conditions and short forecasts | Optional |
Orac uses SearXNG as its local/private search provider. See Internet Retrieval for installation, configuration, and troubleshooting.
The supported deployment path assumes Linux, Docker Engine with Buildx, bash,
sudo, Python 3.12+, and a local checkout.
git clone https://github.com/Avalon60/orac.git
cd orac
python3 -m venv .venv
source .venv/bin/activate
pip install -e .Then:
- Review
resources/config/orac.envandresources/config/orac.ini. - Create the installer database credential with
bin/dbconn-mgr.sh -c orac. - Deploy the local database with
bin/orac-db-deploy.sh. - Start the complete stack with
bin/orac-ctl.sh start. - Confirm status with
bin/orac-ctl.sh status.
Read Installation before deploying a new host. The
deployment script currently supports only TOPOLOGY=db-local.
- Documentation index
- Installation
- Configuration reference
- Runtime user preferences
- Plugins
- Home Assistant
- Drop Box and local document ingestion
- Weather
- Internet retrieval
- Dialogue routing and local knowledge
- Voice pipeline
- APEX administration
- Backup and restore
- Docker Compose deployment
- Architecture overview
bin/orac-ctl.sh start
bin/orac-ctl.sh stop
bin/orac-ctl.sh restart
bin/orac-ctl.sh status
bin/orac-ctl.sh compose-check
bin/orac-ctl.sh logsUse bin/orac.sh only when controlling the host AI engine independently from
the Compose-managed services.
This project is licensed under the MIT License. See LICENSE.
Orac is named after the computer from Blake's 7, combining a retro science fiction reference with a modern local AI system.