Metadata-Version: 2.4
Name: clap-llm
Version: 2.0.0
Summary: CLAP: Chat Local And Persistent - Local LLM conversation tool with Ollama
Author-email: Frederick <wedonotuse@outlook.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/cycleuser/CLAP
Project-URL: Repository, https://github.com/cycleuser/CLAP.git
Keywords: llm,ollama,rag,local-ai,chatbot,pyside6
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: mistune>=3.0.0
Requires-Dist: Pillow>=9.0.0
Provides-Extra: rag
Requires-Dist: pypdf>=4.0.0; extra == "rag"
Requires-Dist: python-docx>=0.8.11; extra == "rag"
Provides-Extra: web
Requires-Dist: flask>=2.3.0; extra == "web"
Provides-Extra: zim
Requires-Dist: libzim>=3; extra == "zim"
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=7.3.0; extra == "dev"
Requires-Dist: ruff>=0.0.270; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: clap-llm[cli,dev,rag,web,zim]; extra == "all"
Dynamic: license-file

# CLAP: Chat Local And Persistent – Design and Implementation of Contextual Dialogue Loadable under Privacy-Sensitive Network Scenarios with the Ollama Framework’s Local Large Language Model Semantic Interaction Software

**Version:** 2.0.0

## 1. Introduction

In recent years, the internet has permeated every aspect of daily life, and online services, epitomized by large language models (LLMs), have become the darlings of the digital age. However, the use of LLMs in privacy-sensitive contexts poses certain privacy risks and confronts users with the challenge of dialogue continuity.

Regarding privacy, LLMs that rely on network access are susceptible to man-in-the-middle attacks during conversation sessions. Furthermore, user interactions with service providers may lead to the collection of dialogue data, potentially utilized for purposes beyond the original intent.
On another front, without proper archiving of online conversations, resuming previous discussions becomes difficult in privacy-conscious scenarios. Additionally, ensuring the sanitization and deletion of dialogue records is a formidable task.

To address these issues, we present `CLAP`, short for "Chat Local And Persistent." This software is designed for local, persistent dialogues and is built atop the `Ollama` framework, leveraging `Ollama-Python` to interface with locally managed LLMs. `CLAP` facilitates interaction with local LLMs while storing the full conversation state as portable JSON session files with a `.clap` extension (v1 files are imported losslessly), enabling users to load these files for dialogue continuation. It also supports exporting dialogue transcripts as Markdown documents.

CLAP ships a local web workspace and a PySide6 desktop GUI, and enables semantic interaction with local LLMs offline, with a ten-language interface, branchable sessions, structured annotations, and citation-checked answers over external ZIM libraries — ensuring privacy and data independence. Developed in Python, it enjoys broad compatibility across platforms, including Windows 10/11 and GNU/Linux.

The development harnesses PySide6 for GUI design and BeeWare for project packaging, ensuring stability and ease of use.

## 2. Environment

Benefitting from the cross-platform capabilities of PySide6 and other foundational libraries, `CLAP` operates seamlessly across various hardware and OS environments. It offers flexible installation options catering to diverse user needs and system configurations, enabling secure, efficient, and platform-agnostic interaction with local LLMs.

To use `CLAP`, users must first download the Ollama framework from its [official website](https://ollama.com/download). Subsequently, they execute a command such as `ollama pull gemma:2b` to download a chosen offline LLM model, which defaults to being stored in `~/.ollama/models/`. Note that while Ollama installation and model downloads require an internet connection, once completed, `CLAP` can operate entirely offline.

### 2.1 Development Environment

The development environment includes:

| Component | Version | Purpose |
|-----------|---------|---------|
| ollama    | 0.1.41  | LLM runtime tool |
| ollama-python | 0.2.0 | Python interface for LLMs |
| Python    | 3.12    | Runtime support |
| PySide6   | 6.6.2   | GUI library |
| beeware   | 0.3.0   | Project framework |
| briefcase | 0.3.16  | Packaging tool |
| matplotlib | 3.8.3 | Plotting library |
| numpy     | 1.26.4  | Numerical computing |
| pandas    | 2.2.1   | Data analysis |
| scipy     | 1.12.0  | Scientific computing |
| toga      | 0.4.2   | Native GUI toolkit |
| toga-chart| 0.2.0   | Chart components for Toga |
| openpyxl  | 3.1.2   | Excel file handling |
| scikit-learn | 1.4.1.post1 | Machine learning library |

### 2.2 Hardware Requirements

Minimum hardware specifications include:

| Component | Requirement |
|-----------|-------------|
| Processor | Dual-core, 64-bit, 1GHz+ (Intel/AMD x86_64, ARM64) |
| GPU       | CUDA12.1 compatible |
| RAM       | 8GB+ |
| Disk Space | 128GB+ |

### 2.3 System Requirements

Supported operating systems:

| OS         | Minimum Version | Architecture |
|------------|-----------------|--------------|
| Windows 10 | 1809            | 64-bit       |
| Windows 11 | 23H2            | 64-bit       |
| Ubuntu     | 22.04.4         | 64-bit       |

## 3. Installation

## 3.1 Install Ollama first

Before installing `CLAP`, ensure that the Ollama framework is correctly installed and configured. Follow the official Ollama installation guide to set up the environment and download the desired LLM model.

Please navigate to the ollama website for detailed instructions: https://ollama.com/download  .
And download the model you want to use after installing Ollama.
For example, you can use the following command to download the gemma model:
```bash
ollama pull gemma:2b
```

## 3.2 Clone and Run from Source

Suitable for all OS users, especially GNU/Linux users, requiring Python 3.10+ and Ollama dependencies.

Clone the repository and install dependencies, then run the application. 
The commands are as follows:
```bash
git clone https://github.com/cycleuser/CLAP.git
cd CLAP
pip install -e ".[rag,web,zim,cli]"
clap --web          # web workspace at http://127.0.0.1:5057
clap                # desktop GUI (PySide6)
```

## 3.3 Install from PyPI

```bash
pip install "clap-llm[rag,web,zim,cli]"
clap --web
```

# 4 Interface


![](./images/initial.png)

![](./images/select_model.png)

![](./images/select_role.png)

![](./images/select_memory.png)

![](./images/select_language.png)

![](./images/load_image.png)

![](./images/image_loaded.png)

![](./images/image_chat.png)

![](./images/load_pdf.png)

![](./images/pdf_loaded.png)

![](./images/pdf_chat.png)
# 5 Web 工作台、ZIM 外置知识库与「有依据」模式

除了桌面 GUI，CLAP 提供一套只监听本机的 Web 工作台（默认 `127.0.0.1:5057`；macOS 的 5000 端口被 AirPlay 占用，故不采用）：

```bash
clap --web              # 打开 http://127.0.0.1:5057
clap --web --port 5057  # 显式指定端口
```

工作台包含四个页面：

- **对话**（`/`）：SSE 流式对话、按 provider 分组的模型下拉、分支切换与任意消息分叉、
  结构化标注、**暂停**（服务端真取消，已出文本保留）、**导出**（Markdown / HTML / JSON，
  点下载后由浏览器选择保存位置）、**分享**（下载 `.clapshare`，不含密钥与本机路径）、**续期**
  （确定性摘要桥接，下一条消息自动携带）。会话本身也可以一键下载为 `.clap`，或从本机选择
  `.clap` 文件加载。
- **对话不会因刷新丢失**：每次改动都会自动保存到 `~/.clap/web_session.clap`，刷新页面或重启
  服务后自动恢复。工具栏的「清空对话」一键重置；每条消息头部有「删除」，可以只删这一条
  （后续消息自动接回上一级）或删除这一条及之后。
- **方图输出**（写文章配图）：`/figure?lang=en&theme=light` 会把当前最后一组问答渲染成
  1200×1200 的浅色卡片（截图时用 2 倍缩放得到 2400×2400），包含问题、回答、引用来源和依据度。
- **知识库**（`/kb`）：ZIM 外置库列表与离线全文检索，点结果直接读原文。
- **时间轴**（`/timeline?file=…`）：渲染指定 `.clap` 会话的时间轴图。
- **接口**（`/api-docs`）：全部端点的契约说明。

## 5.1 ZIM 外置知识库

ZIM（Kiwix 归档）本身就是「带倒排索引的只读知识源」。CLAP **不复制、不入库、不出网**，
直接用 `libzim` 查询归档内建索引：

```bash
export CLAP_ZIM_ROOTS="$HOME/Documents/重点文献"   # 默认值即此目录
```

五类素材已在本机验证：AAAI 2023–2025（33,199 条）、物理讲义（9,342 条）、
世界文学名著（588 条）、诺奖作品（561 条）、相声文本（259 条）。中文「量子」、
英文「transformer」等检索均在 0.1 秒级返回命中。

除 ZIM 外，还可以在「知识库」页添加**纯文本资料**（`.txt` / `.md` / `.markdown` / `.text`）：
可以上传文件，也可以填一个文件或目录路径批量加入。PDF、Word、图片等格式会被拒绝
（无法逐字核对，不能作为依据）。文本资料默认存放在 `~/.clap/text_sources/`
（可用 `CLAP_TEXT_ROOTS` 改路径），检索与 ZIM 一起参与「有依据」模式的取证。
只要至少配置了一个资料源（ZIM 或文本），对话页的有依据模式就会**默认开启**；
手动关掉的选择会被记住。

## 5.2 「有依据」模式：每一步都能回到原文

开启后，每次提问都按同一顺序进行：

1. **先搜资料**：在所有 ZIM 里检索相关内容，长问句会自动去掉标点和疑问词，
   再按关键内容分别检索后合并；
2. **只依据资料回答**：模型只能看检索到的编号材料，说事实的句子要带 `[n]` 引用；
   资料里没有的，就直接回「来源未提及」，不猜也不补常识；
3. **逐句对回原文**：每句都拿去和被引用的那段原文对照，给出「依据度」
   （有据句数 / 可核对的句数）。中文回答、英文原文的情况按术语和人名核对；
   确实没法逐字对照的句子单独计为「跨语言未核对」，不会被判成编造；
4. **能点开核对**：点回答里的 `[1]` 直接展开 ZIM 原文（库名 + 路径），
   导出的文档里同样附来源清单和依据度。

界面支持中文 / English 切换（右上角），选择会记住，也会跟随浏览器语言。目前提供中文、English、日本語、Français、Русский、Deutsch、Español、Português、Italiano、한국어 十种界面语言，以及浅色、深色、跟随系统三种主题；两项选择都会记住。

## 5.3 模型设置：导入 JSON 或手动填写

点顶栏的齿轮打开「模型设置」：

- **导入 JSON**：直接粘贴或选择 opencode / pi / CLAP 风格的配置文件，一键导入服务商、端点、密钥和模型清单。密钥只写入本机配置文件（`~/.config/clap/settings.json`，权限 0600），导入结果与界面上只显示掩码。
- **手动填写**：服务商标识、Base URL、API key、模型名称（逗号分隔）。模型名称留空时才从端点自动获取；端点不提供模型列表时，手填的 ID 会直接用于下拉框。
- **默认模型**：默认使用 `deepseek / deepseek-flash`，也可以在面板里改成任意已配置的模型。
- **测试连接**：逐个服务商检查可用性与模型列表，不会回显密钥。

模型调用全部经由服务商层（OpenAI 兼容 HTTP）：凭证从环境变量
（`*_API_KEY` / `*_TOKEN` / `*_KEY`）、`~/.config/opencode/opencode.json`、
`~/.pi/agent/auth.json` 读入内存，界面与接口只显示掩码，任何响应、日志、导出物
都不包含明文密钥；ollama 默认走 `ollama.com/v1`，本地守护进程需显式
`CLAP_OLLAMA_LOCAL=1`。
