Metadata-Version: 2.5
Name: geniusbot
Version: 5.2.0
Summary: The Ever-learning and ever-improving tool!
Project-URL: Homepage, https://github.com/Knuckles-Team/geniusbot
Author: Repository Maintainers
License: MIT
License-File: LICENSE
Keywords: agent,desktop,genius,geniusbot,mcp,qt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.15,>=3.12
Requires-Dist: arbora>=0.1.2
Requires-Dist: epistemic-graph<3,>=2.27.3
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: pyside6>=6.12.0
Requires-Dist: pywin32; sys_platform == 'win32'
Requires-Dist: winshell>=0.6; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: mypy>=2.4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest-qt>=4.5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.17.1; extra == 'dev'
Requires-Dist: types-docker>=7.2.0.20261006; extra == 'dev'
Requires-Dist: types-requests>=2.33.0.20261006; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'test'
Requires-Dist: pytest-qt>=4.5.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.4.0; extra == 'test'
Requires-Dist: pytest>=9.1.1; extra == 'test'
Requires-Dist: ruff>=0.17.1; extra == 'test'
Provides-Extra: types
Requires-Dist: mypy>=2.4.0; extra == 'types'
Requires-Dist: types-docker>=7.2.0.20261006; extra == 'types'
Requires-Dist: types-requests>=2.33.0.20261006; extra == 'types'
Description-Content-Type: text/markdown

# GeniusBot

<p align="center">
  <img src="docs/assets/brands/geniusbot-logo-v1.png" alt="GeniusBot logo" width="220">
</p>

<p align="center">
  <b>The desktop cockpit for Arbora.</b><br>
  <sub>A unified, visual control deck over the Arbora multi-agent ecosystem.</sub>
</p>

[![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot/forks)
[![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot/graphs/contributors)
[![GitHub license](https://img.shields.io/github/license/Knuckles-Team/geniusbot)](LICENSE)
[![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot/issues)
[![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/geniusbot)](https://github.com/Knuckles-Team/geniusbot)
[![PyPI - Version](https://img.shields.io/pypi/v/geniusbot)](https://pypi.org/project/geniusbot/)
[![PyPI - Downloads](https://img.shields.io/pypi/dd/geniusbot)](https://pypi.org/project/geniusbot/)
[![PyPI - License](https://img.shields.io/pypi/l/geniusbot)](https://pypi.org/project/geniusbot/)
[![Build](https://github.com/Knuckles-Team/geniusbot/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/geniusbot/actions/workflows/release.yml)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://knuckles-team.github.io/geniusbot/)

<p align="center">
  <a href="https://knuckles-team.github.io/geniusbot/">Documentation</a> ·
  <a href="https://knuckles-team.github.io/geniusbot/overview/">Architecture</a> ·
  <a href="https://knuckles-team.github.io/geniusbot/concepts/">Concepts</a>
</p>

*Version: 5.2.0*

## Overview

GeniusBot is the premium, unified cockpit and visual control deck built on top of
[Arbora](https://knuckles-team.github.io/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](#overview)
2. [Key Capabilities](#key-capabilities)
3. [Features](#-features)
4. [Architecture](#-architecture)
5. [Installation](#-installation)
6. [Usage](#-usage)
7. [Packaging & Executables](#-packaging--executables)
8. [Documentation References](#-documentation-references)
9. [License](#-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.

```mermaid
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](docs/overview.md).

---

## 🛠️ Installation

### 1. Modern Virtual Environment (via uv)
Create a virtual environment and sync standard requirements:
```bash
# Setup virtual environment
uv venv

# Sync requirements
uv pip sync requirements.txt
```

### 2. Standard pip
Install standard stable packages:
```bash
pip install geniusbot
```

Install with all ecosystem plugins:
```bash
pip install geniusbot[all]
```

---

## 🌍 Environment Variables

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

| Variable | Description | Default / Example |
|----------|-------------|-------------------|
| `QT_QPA_PLATFORM` | Headless Qt Platform (set to `offscreen` for CI/CD or Docker) | `offscreen` |
| `LANGFUSE_PUBLIC_KEY` | Langfuse Observability Public Key | `pk-lf-...` |
| `LANGFUSE_SECRET_KEY` | Langfuse Observability Secret Key | `sk-lf-...` |
| `LANGFUSE_HOST` | Langfuse Host URL | `https://cloud.langfuse.com` |
| `LOGFIRE_TOKEN` | Pydantic Logfire Telemetry Token | |
| `TERM` | Terminal type for the embedded terminal emulator | `xterm-256color` |
| `_MEIPASS` / `_MEIPASS2` | PyInstaller temp directories for bundled app context | *(Used internally)* |

---

## 🚀 Usage

Launch the desktop cockpit:
```bash
uv run geniusbot
```

To run in headless or virtual Linux environments (CI/CD):
```bash
QT_QPA_PLATFORM=offscreen uv run geniusbot
```

---

## 📦 Packaging & Executables

### PyInstaller Compiling
Compiling GeniusBot as a single standalone executable:
```powershell
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:
```bash
iscc "./setup.iss"
```

---

## 📚 Documentation References
For deep architectural guidelines and code documentation, explore:
* [docs/index.md](docs/index.md) — Documentation Entrypoint & Quickstart.
* [docs/overview.md](docs/overview.md) — Detailed Architecture & Security Guardrails.
* [docs/concepts.md](docs/concepts.md) — Concept Registries (`CONCEPT:GB-GBOT.cockpit.gbot` through `8.0`).

Start at the [GeniusBot documentation](https://knuckles-team.github.io/geniusbot/) for the
hosted, always-current version of the same material.

---

## Contributing

See [AGENTS.md](AGENTS.md) for contribution and validation guidance.

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
