GeniusBot

The desktop cockpit for Arbora.
_{A unified, visual control deck over the Arbora multi-agent ecosystem.}

Documentation · Architecture · Concepts

Version: 5.2.1

Overview

GeniusBot is the premium, unified cockpit and visual control deck built on top of Arbora and its agent-utilities control plane. It integrates every specialist agent and MCP package in the fleet into a single-pane-of-glass user interface, offering 1-click execution, embedded hybrid terminals, zero-nesting visual layouts, and a zero-trust hardware protection layer.

GeniusBot provides a centralized graphical cockpit designed to eliminate tedious click-through fatigue. It maps specialist agent parameter schemas directly to custom QSS-themed form widgets on the fly.

Operators can trigger actions, monitor running terminal inputs via the embedded agent-terminal-ui, and secure dangerous CLI calls using the Zero-Trust Tool-Guard interceptor.

Key Capabilities

• Dynamic, schema-driven control panels for every specialist agent and MCP package in the fleet.
• An embedded hybrid terminal (xterm.js) for interactive, in-cockpit sessions.
• A zero-trust Tool-Guard that intercepts and confirms sensitive mutations before execution.
• Ask-Data (NL→Query), engine metrics/PromQL, and federated search over the Arbora gateway.
• A fleet supervisory cockpit: worker topology and the ActionPolicy approval inbox.

Table of Contents

1. Overview
2. Key Capabilities
3. Features
4. Architecture
5. Installation
6. Usage
7. Packaging & Executables
8. Documentation References
9. License

✨ Features

• Zero-Nesting Dynamic UI: Navigation categorized into flat category menus (Dashboard, Infra, Media, Productivity, Research).
• Dynamic Card Schema Grid: PySide6 widgets are built automatically from specialist agent tool specifications.
• Embedded Hybrid Terminal: Hosts local xterm.js to run interactive terminal loops directly in the cockpit.
• Zero-Trust Security Tool Guard: Prompts native authorization dialogs to review arguments before executing dangerous mutations.
• Runnable Background Workers: Utilizes thread pools (QThreadPool) to prevent GUI freezes during execution loops.
• Visual Trading Dashboard: Snappy native C++ charting engine (PySide6.QtCharts) with OHLCV candlestick/line toggles, strategy indicator overlay crossovers (MACD/RSI), orderbook bids/asks depth volumes, and thread-safe crypto news feeds.
• Ask Data (NL→Query): Ask the Knowledge Graph a question in plain English; the engine generates an auditable read-only query (UQL/Cypher/SQL/SPARQL), runs it, and synthesizes an answer with citations — over the gateway /api/graph/ask-data and /api/graph/nl-query routes.
• Engine Metrics & Status: Query engine observability with PromQL (/api/graph/promql) and watch the shared content-addressed KV-cache occupancy (/api/graph/kvcache).
• Federated Search: Fan one query across every registered external graph and rank the merged results (/api/graph/federated-search).

🏛️ Architecture

GeniusBot is engineered as a lightweight PySide6 GUI client wrapper around the agent-utilities logic engine.

graph TD
    subgraph GUI ["GeniusBot Cockpit (PySide6)"]
        Sidebar["Left Category Sidebar"]
        GridDeck["Central Dynamic Card Grid"]
        ToolGuard["Tool Guard Modal Interceptor"]
        TerminalPanel["xterm.js WebEngine Panel"]
    end

    subgraph Backend ["agent-utilities Powerhouse"]
        Discovery["Agent Specialist Discovery"]
        Executor["Background Agent Worker Loop"]
        KG["Epistemic Knowledge Graph"]
    end

    Sidebar --> GridDeck
    GridDeck -->|Introspect Schemas| Discovery
    GridDeck -->|Trigger Safe Action| Executor
    GridDeck -->|Sensitive Action| ToolGuard
    ToolGuard -->|Operator Approved| Executor
    TerminalPanel -.->|Interactive Terminal| Executor

Detailed architectural diagrams and component breakdowns are located in the Documentation Overview.

🛠️ Installation

1. Modern Virtual Environment (via uv)

Create a virtual environment and sync standard requirements:

# Setup virtual environment
uv venv

# Sync requirements
uv pip sync requirements.txt

2. Standard pip

Install standard stable packages:

pip install geniusbot

Install with all ecosystem plugins:

pip install geniusbot[all]

🌍 Environment Variables

GeniusBot can be configured using environment variables or a .env file in the project root:

🚀 Usage

Launch the desktop cockpit:

uv run geniusbot

To run in headless or virtual Linux environments (CI/CD):

QT_QPA_PLATFORM=offscreen uv run geniusbot

📦 Packaging & Executables

PyInstaller Compiling

Compiling GeniusBot as a single standalone executable:

python -m pip install --upgrade pyinstaller
git clone https://github.com/Knuckles-Team/geniusbot.git
cd geniusbot
python -m venv .venv
./.venv/Scripts/activate
python -m pip install -r ./requirements.txt
python -m pip install -r ./build-requirements.txt
python -m pip install --upgrade pandas scipy numpy pydantic
pyinstaller --name geniusbot `
  --log-level DEBUG `
  --onefile --windowed `
  --paths "./geniusbot" `
  --icon='./geniusbot/img/geniusbot.ico' `
  --recursive-copy-metadata=opentelemetry_api `
  --recursive-copy-metadata=opentelemetry_sdk `
  --recursive-copy-metadata=opentelemetry_exporter_otlp_proto_grpc `
  --exclude-module pygame `
  --exclude-module tkinter `
   ./geniusbot/geniusbot.py

Windows Setup Installer

Generate a Windows MSI setup package:

iscc "./setup.iss"

📚 Documentation References

For deep architectural guidelines and code documentation, explore:

• docs/index.md — Documentation Entrypoint & Quickstart.
• docs/overview.md — Detailed Architecture & Security Guardrails.
• docs/concepts.md — Concept Registries (CONCEPT:GB-GBOT.cockpit.gbot through 8.0).

Start at the GeniusBot documentation for the hosted, always-current version of the same material.

Contributing

See AGENTS.md for contribution and validation guidance.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.