ORION-AI

ORION-AI

ORION-AI is a local AI cybersecurity assistant and cybersecurity copilot with two user surfaces: a Web Dashboard and an Assistant UI. It helps you manage engagements, log events, track coverage, generate notes and reports, search a local Vault, and query tasks/notes through configurable providers.

Product Overview

ORION-AI is designed for day-to-day AI security operations workflows. You can use the Web Dashboard for structured work (engagements, events, coverage, reports, notes, tasks, Vault management) and use the Assistant UI for conversational interaction (voice push-to-talk and text), with behavior controlled by the in-app configuration.

Installation Guide

System Requirements

  • Python 3.11 or 3.12.
  • pip (Python package installer).
  • Internet access for installing Python packages and optional external integrations.
  • For full Assistant App Mode experience (voice + typed prompt runtime): install optional voice dependencies from requirements-voice.txt.
  • Optional local AI: Ollama, if you want local model responses instead of Gemini.
  • Desktop environment required for native App Mode window (pywebview).

Installation (From ZIP Download)

  1. Download the project ZIP from your website/download page.
  2. Extract the ZIP to a folder on your computer.
  3. Open a terminal in the extracted folder.

macOS

cd ~/Downloads/<extracted-folder-name>
python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

# Optional: install voice prerequisites if you want Assistant App Mode voice runtime
brew install portaudio ffmpeg
pip install -r requirements-voice.txt

# Launch App Mode (recommended)
python app_mode.py

Windows (PowerShell)

cd "$HOME\Downloads\<extracted-folder-name>"
py -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -r requirements.txt

# Optional: voice dependencies for Assistant App Mode voice runtime
pip install -r requirements-voice.txt

# If PyAudio build fails, install Microsoft C++ Build Tools and retry:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
# Optional fallback player for edge-tts:
# winget install Gyan.FFmpeg

# Launch App Mode (recommended)
python app_mode.py

If activation is blocked by PowerShell policy, run this once in the same PowerShell window, then activate again:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Linux (Ubuntu/Debian baseline)

cd ~/Downloads/<extracted-folder-name>
sudo apt update
sudo apt install -y python3-venv
python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

# Optional: voice prerequisites and voice dependencies
sudo apt install -y portaudio19-dev ffmpeg
pip install -r requirements-voice.txt

# Launch App Mode (recommended)
python app_mode.py

Linux Native Window Requirements (pywebview)

On Linux, ORION-AI App Mode uses pywebview, which requires a supported GUI backend.

Unlike macOS and Windows (where the required runtime is usually available by default), many Linux installations - especially minimal setups (Hyprland, i3, Arch minimal, server environments, Raspberry Pi, containers) - do not include the required GTK or Qt Python bindings.

If you attempt to run:

python app_mode.py

and see an error similar to:

You must have either QT or GTK with Python extensions installed in order to use pywebview.

it means your system is missing the necessary GUI backend.

Recommended Fix (Ubuntu/Debian)

Install GTK bindings:

sudo apt update
sudo apt install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0

Then run:

python app_mode.py

Alternative (Qt backend)

You may install Qt bindings instead:

pip install qtpy PyQt6

Optional: Ollama (Local AI)

If you want local AI responses:

  1. Install Ollama from https://ollama.com/download.
  2. Pull the default model used by ORION-AI:
ollama pull llama3.2:3b
  1. In ORION-AI Config, select Local model (Ollama) and keep model name llama3.2:3b.
  2. Use Test local model in Config to verify availability.

Run Modes

App Mode (Recommended)

python app_mode.py
  • Starts backend + voice runtime + native assistant window.
  • First launch opens Config if no saved config exists.
  • Later launches open Assistant UI directly.

Web Dashboard Mode

uvicorn app.main:app --host 127.0.0.1 --port 8000

Then open:

First Launch Behavior

  • If no runtime config exists, ORION-AI starts at Config.
  • After saving core settings, it enters Assistant mode.
  • Default config file location: ~/.orion-ai/config.json.
  • Default SQLite database location: database/orion-ai.db in the project folder (unless overridden).

User Surfaces

Web Dashboard

Best for structured workflows:

  • Engagement creation and event logging.
  • Coverage and timeline review.
  • Report and notes generation.
  • Vault path/index/search management.
  • Aggregated task review.
  • Embedded configuration screen.
  • Built-in text assistant panel.

Assistant UI (Voice + Text)

Best for conversational workflows:

  • Push-to-talk microphone interaction.
  • Typed prompt input.
  • Live state transitions (listening, thinking, speaking, cooldown, idle).
  • Direct navigation to Config.

API/CLI-Only Capabilities (Not UI Features)

  • Task completion endpoint exists, but no current button/chat flow in UI for completing tasks.
  • /assistant/chat session endpoint exists, but current UI does not use it.
  • Advanced note export targets (notes_provider_targets) are API payload features, not dashboard controls.

Web Dashboard Guide

Global Navigation

Sidebar pages:

  • Operations
  • Vault
  • Reporting
  • Notes
  • Tasks
  • Config

Top bar shows:

  • API/UI status chips.
  • Live voice/WebSocket indicators from assistant event stream.

Dashboard Assistant Panel

Open with the floating Assistant button.

  • Text-only query panel.
  • Sends requests directly to assistant query endpoint.
  • Shows assistant answers and source bullets when response includes Sources:.

Operations (/)

What you can do:

  • Create engagement with Name, Description, and Metadata JSON.
  • Select/open existing engagements.
  • Add events manually to the selected engagement.
  • Convert uncovered phases into tasks using Convert Gaps To Tasks.

Expected results:

  • Engagement names must be unique.
  • Metadata must be valid JSON object if provided.
  • Event creation updates timeline and coverage immediately.
  • Gap-to-task sync reports created and skipped.

Engagement Detail (/dashboard/engagement/{id})

What you can do:

  • View engagement details and phase coverage status.
  • Add events with phase, severity, source, tags, description, evidence paths.
  • Switch timeline view:
    • Chronological
    • Grouped
  • Trigger AI analysis for summary/actions/risk notes.
  • Convert coverage gaps to tasks.

Expected results:

  • Coverage score is recalculated from event counts per phase.
  • AI analysis appears when provider is available, otherwise an error message is shown.

Vault (/dashboard/vault)

What you can do:

  • Register local folder paths.
  • Enable/disable registered paths.
  • Reindex all enabled paths or index one path.
  • Search indexed snippets.

What is indexed:

  • File extensions: .md, .txt, .log, .json.
  • Common build/cache folders are ignored.
  • Paths must be accessible local directories.

Expected results:

  • Status shows paths/files/chunks and indexing run stats.
  • Search returns file path, chunk id, snippet, rank.

Reporting (/dashboard/report/{id})

What you can do:

  • Toggle Include Vault Evidence.
  • Toggle Include AI Sections.
  • Set optional vault query.
  • Refresh report preview.
  • Download markdown report.

Expected results:

  • Preview renders both markdown source and HTML output.
  • Download generates a timestamped report file in reports/.

Notes (/dashboard/notes/{id})

What you can do:

  • Generate or append notes for engagement.
  • Optionally include Vault snippets with query.
  • Preview raw markdown and rendered notes.

Expected results:

  • First generation creates notes/engagement_<id>.md.
  • Later generations append incremental update sections.

Tasks (/dashboard/tasks)

What you can do:

  • View aggregated tasks from enabled providers.
  • Filter by Today, This Week, This Month, All.
  • Toggle Show Completed.

Expected results:

  • Tasks are sorted by urgency.
  • Overdue and due-today are visually prioritized.
  • This page is read-only for task status changes.

Config (/dashboard/config)

Embedded version of the same Config UI used by App Mode. Uses same persistence and provider logic.

Assistant Guide

Voice Mode

  • Use microphone button in Assistant UI to start/stop push-to-talk capture.
  • App does not auto-listen continuously in App Mode UI.
  • Voice is paused automatically while Config screen is active.
  • If microphone is unavailable, UI shows warning and Retry Mic.

Text Mode

  • Type message and send from Assistant UI.
  • Dashboard assistant panel and Assistant UI text are different flows:
    • Dashboard panel sends direct assistant queries immediately.
    • Assistant UI text sends direct POST /assistant/query requests and renders replies/errors immediately.

Important:

  • Assistant UI typed prompts do not depend on the voice runtime loop.
  • Voice runtime status only affects microphone/PTT controls.
  • If Vault is enabled and configured as the default notes/context provider, assistant retrieval is limited to indexed local Vault content.

What Assistant Can Do

  • System: date/time answers.
  • Tasks: list tasks, today/tomorrow, birthday-style task lookup, create tasks via natural language.
  • Engagement: summarize coverage and gaps.
  • Notes/Vault: retrieve notes results from configured notes provider.
  • General questions: AI-generated response from selected provider.

When Vault is enabled and configured as the default notes/context provider, ORION-AI does not use external AI model knowledge for information retrieval; answers are strictly grounded in indexed local Vault content. To allow model-based responses outside local Vault context (Gemini/Ollama without local indexed context), disable Vault in Config.

Current Limits

  • No current UI flow to complete tasks.
  • No edit/delete flows for engagements/events in UI.
  • /assistant/chat is not wired into current user UI.

Configuration Guide (Detailed)

Configuration sections are independent. You can save one section without overwriting unrelated sections.

Language

Options:

  • Spanish (es)
  • English (en)

Effects:

  • Config UI language.
  • Assistant UI language labels.
  • Assistant reply language defaults.

AI Provider

Options:

  • Gemini (remote API)
  • Ollama (local model)

Fields:

  • Gemini API key
  • Ollama model name
  • Fallback toggle (Allow fallback to Gemini if local model is unavailable)

Actions:

  • Test selected provider connectivity.
  • Save AI section independently.

Behavior when missing:

  • Gemini selected without key: setting is saved with warning; AI responses may be unavailable.
  • Ollama unavailable: requests fail unless fallback is enabled and Gemini is configured.

Default Providers

Set defaults for:

  • Task provider
  • Notes provider

Defaults are used when assistant/user action does not specify provider explicitly.

Todoist

Controls:

  • Enabled toggle
  • API token
  • Save, Test connection, Disconnect

Notes:

  • Credentials are stored locally.
  • Disconnect clears credentials and disables provider.

Vault Context Paths

Controls:

  • Enabled toggle
  • Add/remove path list
  • Save, Test connection, Disconnect

Behavior:

  • Paths are normalized and saved.
  • Missing paths can be saved with warnings.
  • Vault indexing/search requires valid accessible folders.
  • If Vault is enabled and configured as the default notes/context provider, assistant information retrieval is local-only and uses indexed Vault content exclusively.

To allow model-based responses outside local Vault context, disable Vault in Config.

Integrations (Tasks + Notes)

Provider cards:

  • Google Tasks (OAuth)
  • Microsoft To Do (OAuth)
  • Trello (token/key)
  • GitHub Issues (PAT + repo)
  • Notion (internal token + page/database)

Card actions:

  • Save
  • Test
  • Disconnect
  • Connect OAuth (Google/Microsoft)

Independent Saving and Persistence Rules

  • Save Language, Save AI, Save Defaults, provider-card Save, and Todoist/Vault saves are separate.
  • Provider toggles call enable/disable immediately.
  • Credentials are intentionally not re-rendered back into fields after save.
  • Save All & Enter saves core config sections and enters Assistant.
  • Integration card credentials (Google/Microsoft/Trello/GitHub/Notion) should be saved on their own cards.

Language Behavior (UI + Assistant)

  • Assistant responses follow configured default language.
  • Config and Assistant UI labels also follow this choice.
  • Dashboard page labels are currently fixed (English layout text).

Vault Behavior Rules

Vault preference is applied when Vault is configured and enabled as notes context. When Vault is enabled and configured as the default notes/context provider, ORION-AI does not use external AI model knowledge to retrieve information. All answers are strictly grounded in the indexed local Vault content. To allow model-based responses outside the Vault context (Gemini/Ollama without local indexed context), disable Vault in Config.

Exact behavior:

  • Explicit notes/vault questions use notes-provider routing and prefer the configured default notes provider.
  • If default notes provider is Vault and it is enabled/configured, responses are Vault-grounded.
  • For general intents, assistant may auto-check Vault first; if relevant chunks are found, it answers from Vault context.
  • If Vault is disabled/unavailable:
    • Notes/vault intents return a configuration-required message.
    • General intents fall back to configured AI provider.
  • If no relevant Vault content is found for explicit Vault query, response includes Sources: - none.

Citations:

  • Vault-grounded answers include a Sources: block with source file paths.
  • Source bullets indicate which local indexed files informed the answer.

AI Provider Switching and Feature Impact

Switching AI provider affects:

  • General assistant responses.
  • AI engagement analysis output.
  • AI sections in reports.

Fallback:

  • Ollama can fall back to Gemini if enabled and Gemini key exists.

If AI provider is unavailable:

  • Assistant returns provider-unavailable guidance.
  • AI analysis may fail for that request.
  • Reports can still be generated with deterministic fallback sections.

Typical Workflows

1) Create a New Engagement and Log Events

  • Open Operations.
  • Create engagement.
  • Add events with phase/severity/title/content.
  • Review timeline and coverage.

2) Check Coverage and Create Follow-up Tasks

  • Open engagement detail.
  • Review gaps.
  • Click Convert Gaps To Tasks.
  • Review task output and then open Tasks.

3) Generate Notes and Report

  • Open Notes page and generate notes.
  • Open Reporting page.
  • Toggle Vault/AI options as needed.
  • Refresh preview and download markdown.

4) Ask Assistant Questions Grounded in Vault

  • Configure and index Vault.
  • Ask notes/vault question in assistant.
  • Review answer and Sources citations.

5) Review Cross-Provider Task Load

  • Open Tasks.
  • Filter by time horizon.
  • Toggle completed tasks.
  • Prioritize overdue and due-today rows.

Troubleshooting

Missing Configuration

Symptoms:

  • Assistant asks to configure provider.
  • AI responses unavailable.

Fix:

  • Open Config, save relevant section, run provider test.

Provider Not Connected

Symptoms:

  • Task/notes provider calls fail.

Fix:

  • Verify credentials and IDs.
  • Re-run OAuth connect where applicable.
  • Use Disconnect then reconnect if needed.

Vault Not Indexed

Symptoms:

  • Vault search returns no results.
  • Vault-grounded assistant answers unavailable.

Fix:

  • Register valid paths.
  • Ensure path is enabled.
  • Run indexing from Vault page.

Microphone Not Detected

Symptoms:

  • Mic button disabled.
  • No microphone detected / input unavailable.

Fix:

  • Grant OS microphone permissions.
  • Connect/select usable microphone.
  • Use Retry Mic.

Assistant UI Typed Prompt Not Completing

Symptoms:

  • Prompt appears queued but no response.

Fix:

  • Run App Mode or Assistant Mode so runtime loop is active.
  • Dashboard assistant panel can still be used for direct text queries.

AI Provider Unreachable

Symptoms:

  • AI test fails.
  • Assistant returns provider unavailable.

Fix:

  • Check Gemini key or local Ollama availability.
  • Enable fallback if desired.

Privacy and Data

Stored Locally

  • Runtime config file, including integration credentials: ~/.orion-ai/config.json.
  • SQLite database with engagements/events/coverage/vault index metadata.
  • Generated notes in project notes/.
  • Generated reports in project reports/.

Sent to External Services

Only when those features are enabled:

  • Gemini requests (remote AI).
  • Task/notes provider API calls (Todoist, Google, Microsoft, Trello, GitHub, Notion).
  • Google STT fallback audio (if Google STT backend is used).
  • Edge TTS text (if edge-tts fallback is used).

Privacy Mode

  • Reduces sensitive log output by redacting transcript/response-like fields.

FAQ

Do I need all providers configured before starting?

No. You can start with local engagement/event workflows and configure providers later.

Where is configuration saved?

By default in ~/.orion-ai/config.json.

Why are secret fields blank after I save?

The UI does not re-display saved secrets for safety. They remain stored unless disconnected/overwritten.

Can I use ORION-AI without voice dependencies?

Yes for Web Dashboard and API workflows. Full Assistant App Mode runtime behavior is best with voice dependencies installed.

Can I use local AI only?

Yes. Install Ollama, pull llama3.2:3b, select local model in Config, and test connection.

Does ORION-AI browse the live web for answers?

Not by default. General answers come from configured model knowledge; Vault-grounded answers come from your indexed local notes.