ZimAgent

Offline CRUD + Semantic Search for Wikipedia ZIM Archives

A production-grade PyQt5 desktop application that lets you read, write, edit, and semantically search any Kiwix .zim archive — with local LLM question answering, animated pipeline visualisation, and a built-in MCP server for Claude Desktop / LangChain integration.

Fully offline. No internet connection required after initial model download.

---

📸 Screenshot

---

🚀 Quick Start

1. Clone & Install

git clone https://github.com/yourname/zim-agent-gui
cd zim-agent-gui

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate       # Linux/macOS
.venv\Scripts\activate.bat      # Windows

# Install dependencies
pip install -r requirements.txt

2. Download a ZIM file

# Small Wikipedia excerpt for testing (~90 MB)
wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_wp1_2023-11.zim \
     -O data/test.zim

3. Download GGUF Models (for RAG + LLM)

Place models in the models/ folder:

File	Purpose	Source
embeddinggemma-300m-q4_k_m.gguf	Sentence embeddings	HuggingFace
qwen-0.5b-q4_k_m.gguf	Answer generation	HuggingFace

# Install TurboRag
pip install turborag-ahx47

4. Launch

python run_app.py
# or
python -m zimagent

---

📦 File Structure

zim-agent-gui/
├── zimagent/                    # Main Python package
│   ├── __init__.py
│   ├── __main__.py              # python -m zimagent
│   ├── main.py                  # App entry-point (QApplication)
│   ├── main_window.py           # Full PyQt5 UI (~600 lines)
│   ├── zim_reader.py            # ZIM article reading (libzim)
│   ├── zim_manager.py           # CRUD + SQLite overlay
│   ├── mcp_server.py            # FastMCP tool server
│   ├── indexer.py               # ZIM → TurboRag indexer
│   ├── agent.py                 # High-level ZimAgent orchestrator
│   ├── semantic_search.py       # TurboRag adapter
│   ├── worker_threads.py        # QThread workers (index, MCP, stats)
│   └── resources/
│       └── style.qss            # Dark cyberpunk QSS theme
│
├── models/                      # GGUF models (user-provided)
│   ├── embeddinggemma-300m-q4_k_m.gguf
│   └── qwen-0.5b-q4_k_m.gguf
│
├── data/                        # ZIM files + index
│
├── scripts/
│   ├── build_exe.bat            # Windows .exe via PyInstaller
│   ├── build_deb.sh             # Linux .deb package
│   └── DEBIAN/control
│
├── run_app.py                   # Standalone launcher
├── requirements.txt
├── setup.py
└── README.md

---

🧩 Features

Dashboard

• ZIM Archive Input & CRUD — open any .zim, see file size + article count
• Pipeline Visualization — animated dashed-arrow diagram: ZIM Reader → Chunking → Gemma Embedding → TurboVec Index + SQLite FTS5
• Query & Results — ask a question, see semantic results + LLM answer
• MCP Server mini-panel — one-click toggle with live status

CRUD Operations

• Full article tree (namespaces A/, B/, …)
• HTML viewer (QWebEngineView or plain text fallback)
• Write new articles, edit existing, soft-delete with restore
• Every change stored in SQLite overlay (base ZIM untouched)
• Full action log

Semantic Search

• Semantic search powered by TurboRag vector index
• Relevance bar for each result
• LLM-generated answer with source attribution
• Runs in background thread (UI never blocks)

MCP Server

• Exposes 8 MCP tools to Claude Desktop / any MCP client
• SSE or stdio transport
• Configurable host + port
• Live server log

---

⚙️ Configuration

Open ⚙ Settings in the sidebar to configure:

• Embedding model path
• LLM model path
• Vector index path

These are saved for the current session (persistent config coming in v1.1).

---

📦 Building Installers

Windows .exe

pip install pyinstaller
scripts\build_exe.bat
# Output: dist\ZimAgent.exe

Linux .deb

sudo apt install fakeroot dpkg-dev
bash scripts/build_deb.sh
# Output: zimagent_1.0.0_amd64.deb
sudo dpkg -i zimagent_1.0.0_amd64.deb

---

🔌 MCP Integration (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zimagent": {
      "command": "python",
      "args": ["-m", "zim_agent.mcp_server",
               "--zim", "/path/to/wikipedia.zim",
               "--transport", "stdio"]
    }
  }
}

Or start SSE server from the MCP Server tab and connect via: http://127.0.0.1:8002/sse

---

📋 MCP Tools Reference

Tool	Parameters	Description
zim_read_article	path	Read article by URL path
zim_search	query, max_results	Full-text + prefix search
zim_write_article	path, title, html	Create or replace article
zim_edit_article	path, new_html, [new_title]	Edit article content
zim_delete_article	path	Soft-delete article
zim_restore_article	path	Restore deleted article
zim_list_modified	—	List all overlay changes
zim_stats	—	Archive + index statistics

---

🧱 Dependencies

Package	Purpose
PyQt5	GUI framework
PyQtWebEngine	HTML article rendering
libzim	ZIM file reading
turborag-ahx47	Semantic search + RAG
fastmcp	MCP server
psutil	CPU/RAM monitoring

---

📄 License

MIT — see LICENSE.