Metadata-Version: 2.3
Name: mykb
Version: 0.2.0
Summary: Local CLI search engine for personal knowledge bases with hybrid BM25 + vector search
Keywords: search,knowledge-base,vector-search,meilisearch,embedding,cli
Author: Reorx
Author-email: Reorx <novoreorx@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Database :: Front-Ends
Requires-Dist: click>=8.0
Requires-Dist: meilisearch>=0.31
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: sentence-transformers==5.1.2
Requires-Dist: torch==2.9.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: httpx>=0.25
Requires-Dist: pyseekdb>=1.0 ; extra == 'seekdb'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/reorx/mykb
Project-URL: Issues, https://github.com/reorx/mykb/issues
Project-URL: Repository, https://github.com/reorx/mykb
Provides-Extra: seekdb
Description-Content-Type: text/markdown

# mykb

本地知识库搜索引擎 CLI，支持 BM25 全文搜索 + 向量语义搜索的混合检索。

## 特性

- **Hybrid Search**: BM25 全文 + 向量语义混合搜索
- **本地 Embedding**: 使用 `embeddinggemma-300m` 本地生成 embedding，无需 API
- **多数据源**: 目前支持 Obsidian vault，可扩展 Twitter、Telegram 等
- **增量索引**: 基于内容 hash，只索引变化的文档
- **可插拔后端**: 支持 Meilisearch 和 SeekDB

## 安装

```bash
# 基础安装（Meilisearch 后端）
pip install mykb

# 带 SeekDB 支持
pip install mykb[seekdb]
```

### 依赖

- **Meilisearch 后端**: 需要运行 [Meilisearch](https://www.meilisearch.com/) 服务
- **SeekDB 后端**: 嵌入式模式无需外部服务（macOS 15+ / Linux）

## 快速开始

```bash
# 1. 配置 Meilisearch
mykb config set meilisearch.url http://localhost:7700

# 2. 添加 collection（Obsidian vault）
mykb collection add my-notes --path ~/Documents/Obsidian --source obsidian

# 3. 索引（含 embedding）
mykb index my-notes --embed

# 4. 搜索
mykb search "机器学习"          # BM25 全文
mykb vsearch "AI 技术趋势"      # 向量语义
mykb query "深度学习入门" --ratio 0.5  # 混合搜索
```

## 配置

配置文件: `~/.mykb/config.toml`

```toml
[backend]
type = "meilisearch"  # 或 "seekdb"

[backend.meilisearch]
url = "http://localhost:7700"
api_key = ""

[backend.seekdb]
path = "~/.mykb/seekdb.db"  # 嵌入式模式
fulltext_analyzer = "ik"     # ik | space | ngram

[embedding]
model = "google/embeddinggemma-300m"
chunk_size = 800
chunk_overlap = 0.15

[collections.my-notes]
source = "obsidian"
path = "/path/to/vault"
mask = "**/*.md"
exclude = [".obsidian/**", ".trash/**"]
```

## 命令

| 命令 | 说明 |
|------|------|
| `mykb collection add/ls/rm` | 管理 collection |
| `mykb index [--embed] [--full]` | 索引文档 |
| `mykb embed [--full]` | 补充 embedding |
| `mykb search <query>` | BM25 全文搜索 |
| `mykb vsearch <query>` | 向量语义搜索 |
| `mykb query <query> [--ratio]` | 混合搜索 |
| `mykb status` | 查看状态 |

## 后端对比

| 特性 | Meilisearch | SeekDB |
|------|-------------|--------|
| 部署 | 独立服务 | 嵌入式 / 服务 |
| BM25 速度 | ⚡ 快 (~2ms) | 慢 (~30ms) |
| Vector 速度 | 快 (~3ms) | ⚡ 更快 (~1ms) |
| Hybrid 速度 | ⚡ 快 (~4ms) | 慢 (~33ms) |
| 资源占用 | 低 | 高 |

**建议**: 
- 通用场景用 **Meilisearch**
- 纯向量搜索场景可考虑 **SeekDB**

## 开发

```bash
# 安装开发依赖
uv sync --all-extras

# 运行测试
uv run pytest

# Benchmark
uv run python scripts/benchmark_seekdb.py --backend meilisearch -n 1000
```

## License

MIT
