Metadata-Version: 2.4
Name: voxkage
Version: 1.1.15
Summary: VoxKage - OS-level Agentic AI Assistant. Autonomous, Persistent, Aware.
Author: Ayush Dwivedi
License: Apache-2.0
Project-URL: Homepage, https://github.com/ayushdwivedi001/VoxKage
Project-URL: Repository, https://github.com/ayushdwivedi001/VoxKage
Keywords: ai,assistant,agentic,os,automation,mcp,gemini
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0
Requires-Dist: ddgs>=9.14.4
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: lxml_html_clean>=0.1.0
Requires-Dist: aiohttp
Requires-Dist: PyYAML>=6.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyautogui>=0.9
Requires-Dist: pygetwindow>=0.0.9
Requires-Dist: Pillow>=10.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Requires-Dist: winshell>=0.6; sys_platform == "win32"
Requires-Dist: winotify>=1.1; sys_platform == "win32"
Requires-Dist: pywinauto>=0.6; sys_platform == "win32"
Requires-Dist: pycaw>=20240210; sys_platform == "win32"
Requires-Dist: comtypes>=1.3; sys_platform == "win32"
Requires-Dist: python-docx>=1.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-pptx>=0.6
Requires-Dist: pystray>=0.19
Requires-Dist: spotipy>=2.23
Requires-Dist: PyGithub>=2.1
Requires-Dist: google-auth>=2.22
Requires-Dist: google-auth-oauthlib>=1.1
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: python-telegram-bot>=20.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Requires-Dist: PyMuPDF>=1.23; extra == "browser"
Provides-Extra: rag
Provides-Extra: vision
Requires-Dist: opencv-python>=4.8; extra == "vision"
Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "vision"
Provides-Extra: docs-plus
Requires-Dist: docx2pdf>=0.1; extra == "docs-plus"
Requires-Dist: pdf2docx>=0.5; extra == "docs-plus"
Provides-Extra: full
Requires-Dist: voxkage[browser,docs_plus,rag,vision]; extra == "full"
Dynamic: license-file

<div align="center">
 
  <p align="center">
    <img src="assets/VoxKage_Readme.png" alt="VoxKage Agentic OS Assistant" width="100%" style="max-width: 900px; border-radius: 10px;">
  </p>

  <br>
  <h1>VoxKage</h1>
  <h3><i>Unified Agentic OS Coordinator & MCP Network</i></h3>
  <p>Connects your coding CLIs (Antigravity, OpenCode, Claude Code, DeepSeek Harness) with a unified MCP server network, dynamic self-learning memory, and deep compiler verification.</p>
  <br>

  <p align="center">
    <a href="https://pypi.org/project/voxkage/" target="_blank">
      <img src="https://img.shields.io/pypi/v/voxkage?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI&color=0ea5e9&cacheSeconds=3600" alt="PyPI Version">
    </a>
    <img src="https://img.shields.io/badge/Platform-Windows_|_macOS_|_Linux-3b82f6?style=for-the-badge&logo=windows&logoColor=white" alt="Platform">
    <img src="https://img.shields.io/badge/License-Apache_2.0-green?style=for-the-badge" alt="License">
    <img src="https://img.shields.io/badge/Python-3.10%2B-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  </p>

  <p align="center">
    <img src="https://img.shields.io/badge/Install-pipx_install_voxkage-ff6b35?style=for-the-badge&logo=python&logoColor=white" alt="Install">
    <img src="https://img.shields.io/badge/Engines-Antigravity_|_OpenCode_|_Claude_|_DSH-8b5cf6?style=for-the-badge" alt="Engines">
    <img src="https://img.shields.io/badge/Memory-SQLite_FTS5_(Zero_GPU)-10b981?style=for-the-badge" alt="Memory">
  </p>

  <br>
  <hr width="100%">
  <br>
</div>

<p align="center">
  [<a href="#quick-start"><strong>Quick Start</strong></a>] •
  [<a href="#supported-engines"><strong>Supported Engines</strong></a>] •
  [<a href="#core-capabilities"><strong>Capabilities</strong></a>] •
  [<a href="#cli-reference"><strong>CLI Commands</strong></a>] •
  [<a href="#local-development"><strong>Contributing</strong></a>] •
  [<a href="#troubleshooting"><strong>Troubleshooting</strong></a>]
</p>

<br>
<hr width="100%">
<br>

<a name="quick-start"></a>
## 🚀 Quick Start (60 Seconds)

### 1. Install VoxKage
Install globally using [`pipx`](https://github.com/pypa/pipx) (recommended) or `pip`:

```bash
pipx install voxkage
```

### 2. Initialize Environment
Run the interactive setup wizard:

```bash
voxkage init
```

The setup wizard automatically detects your installed coding CLIs, configures persistent storage at `~/.voxkage/`, and scaffolds all MCP server registrations across your providers.

### 3. Launch Your Preferred CLI
Start coding with your active engine:

```bash
voxkage             # Launches configured default interface
voxkage status      # Health check all 15 MCP servers & active integrations
voxkage tray        # Launches the background system tray manager
```

---

<a name="supported-engines"></a>
## ⚡ Supported Interface Engines

VoxKage unifies your toolset and memory across 4 major coding assistants. You can use any one of them (or all four):

| Interface Engine | CLI Command | Installation / Setup Command | Config Location |
|---|---|---|---|
| **Antigravity CLI / IDE** | `agy` | [antigravity.dev](https://antigravity.dev) | `~/.gemini/antigravity-cli/mcp/` & `GEMINI.md` |
| **OpenCode CLI** | `opencode` | `npm install -g @opencode/cli` | `~/.config/opencode/opencode.json` & `AGENTS.md` |
| **Claude Code** | `claude` | `npm install -g opencode-starter` | `~/.claude.json` & `CLAUDE.md` |
| **DeepSeek Harness** | `dsh web` | `npm install -g @deepseek-ai/dsh` | `~/.dsh/config.yml` & `.agents/AGENTS.md` |

> [!NOTE]
> If you have at least one engine installed, VoxKage works immediately. Missing engines are shown during `voxkage init` with their one-line install command.

---

<a name="core-capabilities"></a>
## 🧠 Core Capabilities & Architecture

```
┌────────────────────────────────────────────────────────────────────────┐
│                          VOXKAGE COORDINATOR                           │
│      Antigravity (agy) │ OpenCode │ Claude Code │ DeepSeek Harness     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
    ┌───────────────────────────────┴───────────────────────────────┐
    ▼                                                               ▼
┌──────────────────────────────────────┐  ┌──────────────────────────────────────┐
│       Core MCP Servers (15)          │  │        Active Integrations (8)       │
├──────────────────────────────────────┤  ├──────────────────────────────────────┤
│ • voxkage-cognitive-core (Reasoning) │  │ • Telegram Remote Daemon             │
│ • voxkage-memory (Soul DB & TF-IDF)  │  │ • Gmail Automation                   │
│ • voxkage-rag (Local SQLite FTS5)    │  │ • Spotify Playback Control           │
│ • voxkage-websearch (Fast DuckDuckGo)│  │ • GitHub Actions & Commits           │
│ • voxkage-browser (Playwright)       │  │ • Netlify & Supabase MCP             │
│ • voxkage-system & oscontrol         │  │ • Sequential Thinking MCP            │
│ • voxkage-devserver & coding (ACE)   │  │ • Google Colab Integration           │
│ • voxkage-gui, notify, file, session │  │                                      │
└──────────────────────────────────────┘  └──────────────────────────────────────┘
```

### 1. Dynamic Recursive Self-Improvement (`voxkage-cognitive-core`)
Instead of rigid checklists, VoxKage uses a dynamic, model-driven self-improvement loop:
- **`cognitive_think`**: Multi-step reasoning that **automatically retrieves relevant past incident fixes & prevention rules** from Soul Memory before code is edited.
- **`verify_workspace`**: Deep compiler and syntax validation across Python (`py_compile`), JavaScript/TypeScript (`node --check`), HTML (extracts `<script>` modules for syntax validation), and JSON/YAML.
- **`record_incident`**: Logs concrete bugs, root causes, solutions, and prevention rules at the end of a task into `~/.voxkage/cognitive/incidents.jsonl` and SQLite memory.
- **`cognitive_optimize`**: Displays active prevention rules and memory index health.

### 2. Two-Tier Memory Architecture
- **Tier 1 (Lean Prompt Injection)**: Personal identity and core user preferences are injected into `CLAUDE.md` / `GEMINI.md` (~1.5k chars max). Never triggers 40k context limit warnings.
- **Tier 2 (Dynamic SQLite & RAG)**: Problem/solution logs, bug resolutions, and technical learnings are stored in `~/.voxkage/memory.jsonl` and `rag_database.db`, queried dynamically on-demand via `search_memory("<keywords>")`.

### 3. Remote Telegram Control
Control and query your desktop assistant remotely from your phone:
```bash
voxkage plugins telegram setup   # Configure Telegram bot token & chat ID
```

---

<a name="cli-reference"></a>
## 🛠️ CLI Reference

```bash
voxkage init              # Interactive setup & multi-engine scanner
voxkage status            # Inspect active MCP servers, engines, and integrations
voxkage tray              # Start the background system tray manager
voxkage rag index <path>  # Index a directory into SQLite FTS5 RAG database
voxkage rag search <q>    # Search indexed documents via full-text search
voxkage plugins list      # Show installed community and core plugins
voxkage plugins setup <p> # Configure plugin credentials (telegram, spotify, etc.)
voxkage upgrade           # Check and upgrade to the latest VoxKage release
```

---

<a name="local-development"></a>
## 💻 Local Development & Contributing

We welcome community contributions, bug fixes, and new plugins!

### 1. Clone the Repository
```bash
git clone https://github.com/ayushdwivedi001/VoxKage.git
cd VoxKage
```

### 2. Create Virtual Environment & Install Dependencies
```bash
python -m venv venv

# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

pip install -e .
pip install build twine pytest
```

### 3. Verify Syntax & Run Tests
```bash
python -m py_compile voxkage/cli.py voxkage/mcp_servers/cognitive_core_server.py
python -m voxkage.cli status
```

### 4. Submitting a Pull Request
1. Fork the repository and create a feature branch (`git checkout -b feature/amazing-feature`).
2. Commit your changes (`git commit -m "feat: add amazing feature"`).
3. Push to your branch (`git push origin feature/amazing-feature`).
4. Open a Pull Request on GitHub.

---

<a name="troubleshooting"></a>
## ❓ Troubleshooting

### 1. Permission Denied on Windows during `pipx upgrade`
If Windows locks `python.exe` while VoxKage background tasks or system tray are running:
```powershell
Get-Process -Name "pythonw" -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep 2
pipx install voxkage --force
```

### 2. Re-scaffold MCP Server Registrations
If you installed a new engine (e.g. DeepSeek Harness or OpenCode) after initial setup:
```bash
voxkage init
```
This re-scaffolds the schema files and configurations for all detected engines.

---

## 📄 License

Distributed under the Apache 2.0 License. See `LICENSE` for more information.
