Metadata-Version: 2.2
Name: gangdan
Version: 1.0.0
Summary: Offline Development Assistant powered by Ollama and ChromaDB
Author: GangDan Contributors
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/cycleuser/GangDan
Project-URL: Repository, https://github.com/cycleuser/GangDan
Project-URL: Issues, https://github.com/cycleuser/GangDan/issues
Keywords: ollama,chromadb,rag,offline,assistant,flask
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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 :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0
Requires-Dist: flask-cors>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: chromadb>=1.0

# GangDan - Offline Dev Assistant

A local-first, offline programming assistant powered by [Ollama](https://ollama.ai/) and [ChromaDB](https://www.trychroma.com/). Chat with LLMs, build a vector knowledge base from documentation, run terminal commands, and get AI-generated shell suggestions -- all from a single browser tab.

> **GangDan (纲担)** -- Principled and Accountable.

![Chat Panel](images/chat.png)

## Features

- **RAG Chat** -- Ask questions with optional retrieval from a local ChromaDB knowledge base and/or web search (DuckDuckGo, SearXNG, Brave). Responses stream in real-time via SSE.
- **AI Command Assistant** -- Describe what you want to do in natural language; the assistant generates a shell command you can drag-and-drop into the terminal, execute, and auto-summarize.
- **Built-in Terminal** -- Run commands directly in the browser with stdout/stderr display.
- **Documentation Manager** -- One-click download and indexing of 25+ popular library docs (Python, Rust, Go, JS, C/C++, CUDA, Docker, etc.). Batch operations and GitHub repo search included.
- **10-Language UI** -- Switch between Chinese, English, Japanese, French, Russian, German, Italian, Spanish, Portuguese, and Korean without page reload.
- **Proxy Support** -- None / system / manual proxy modes for both the chat backend and documentation downloads.
- **Offline by Design** -- Runs entirely on your machine. No cloud APIs required.

## Screenshots

| Chat | Terminal |
|:----:|:--------:|
| ![Chat](images/chat.png) | ![Terminal](images/terminal.png) |

| Documentation | Settings |
|:-------------:|:--------:|
| ![Docs](images/documents.png) | ![Settings](images/setting.png) |

## Requirements

- Python 3.10+
- [Ollama](https://ollama.ai/) running locally (default `http://localhost:11434`)
- A chat model pulled in Ollama (e.g. `ollama pull qwen2.5`)
- An embedding model for RAG (e.g. `ollama pull nomic-embed-text`)

## Quick Start

```bash
# 1. Clone or copy this folder
cd gangdan

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Make sure Ollama is running
ollama serve

# 4. Launch GangDan
python app.py
```

Open [http://127.0.0.1:5000](http://127.0.0.1:5000) in your browser.

## Project Structure

```
gangdan/
├── app.py                  # Flask backend (routes, Ollama client, ChromaDB, i18n)
├── requirements.txt        # Python dependencies
├── templates/
│   └── index.html          # Jinja2 HTML template
├── static/
│   ├── css/
│   │   └── style.css       # Application styles (dark theme)
│   └── js/
│       ├── i18n.js          # Internationalization & state management
│       ├── utils.js         # Panel switching & toast notifications
│       ├── markdown.js      # Markdown / LaTeX (KaTeX) rendering
│       ├── chat.js          # Chat panel & SSE streaming
│       ├── terminal.js      # Terminal & AI command assistant
│       ├── docs.js          # Documentation download & indexing
│       └── settings.js      # Settings panel & initialization
├── images/                 # Screenshots
└── data/                   # Created at runtime
    ├── gangdan_config.json # Persisted settings
    ├── docs/               # Downloaded documentation
    └── chroma/             # ChromaDB vector store
```

## Architecture

The frontend and backend are fully decoupled:

- **Backend** (`app.py`) -- A single Python file containing Flask routes, the Ollama client, ChromaDB manager, documentation downloader, web searcher, and conversation manager. All server-side configuration is injected into the template via a `window.SERVER_CONFIG` block.
- **Frontend** (`templates/` + `static/`) -- Pure HTML/CSS/JS with no build step. JavaScript files are loaded in dependency order and share state through global functions. KaTeX is loaded from CDN for LaTeX rendering.

ChromaDB is initialized with automatic corruption recovery: if the database is damaged, it is backed up and recreated transparently.

## Configuration

All settings are managed through the **Settings** tab in the UI:

| Setting | Description |
|---------|-------------|
| Ollama URL | Ollama server address (default `http://localhost:11434`) |
| Chat Model | Model for conversation (e.g. `qwen2.5:7b-instruct`) |
| Embedding Model | Model for RAG embeddings (e.g. `nomic-embed-text`) |
| Reranker Model | Optional reranker for better search results |
| Proxy Mode | `none` / `system` / `manual` for network requests |

Settings are persisted to `data/gangdan_config.json`.

## License

This project is for personal and educational use.
