Metadata-Version: 2.3
Name: docs-kit
Version: 0.1.5
Summary: Fetch docs, embed locally, expose to AI agents via skills.
License: MIT License
        
        Copyright (c) 2026 Docs Kit Limited
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Requires-Python: <3.14,>=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: fastembed>=0.6.0
Requires-Dist: filelock>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.2.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qdrant-client>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# docs-kit

[![PyPI version](https://img.shields.io/pypi/v/docs-kit)](https://pypi.org/project/docs-kit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/docs-kit)](https://pypi.org/project/docs-kit/)
[![CI](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/docs-kit/docs-kit/actions/workflows/ci.yml)

Fetch docs from GitBook, Mintlify, or local files, embed them locally, and teach AI agents to search them via installed **skills** (CLI commands). No API keys for the default embedding path. No background server or MCP.

## What it does

- Fetches public docs from **GitBook** and **Mintlify** sites via `/llms-full.txt` and `/llms.txt`, with a **sitemap.xml** fallback on Mintlify when those endpoints are missing
- **`docs-kit ingest`:** `--provider auto` (default) uses a combined strategy (llms endpoints → sitemap). **`--provider gitbook`** uses the GitBook-only fetcher; **`--provider mintlify`** uses the same pipeline as `auto`
- Ingests local `.md` and `.txt` files
- Stores vectors in **embedded Qdrant** on disk — typically `~/.docs-kit/qdrant` when using the auto-created user config, or `.docs-kit/qdrant` (resolved relative to your `docs-kit.yaml`) for a project-local config from `docs-kit init`
- **Hybrid retrieval** (dense embeddings + sparse / BM25-style vectors) for `docs-kit query` and agent-driven queries
- Installs **skill files** into Claude Code, Cursor, Codex, OpenCode, and Claude Desktop so agents run `docs-kit` over the shell
- Concurrent CLI runs coordinate with a **file lock** on the local Qdrant path

## Install

Recommended: **`pipx`** so `docs-kit` is on your PATH:

```bash
pipx install docs-kit
```

Install `pipx` if needed:

```bash
brew install pipx
pipx ensurepath
```

Or **`pip`** inside a virtual environment:

```bash
pip install docs-kit
```

Optional: the repo includes an **`npx-wrapper/`** npm package that bootstraps Python and runs the same CLI (`npx docs-kit …` when published or linked locally).

## Quickstart

```bash
# 1. Install (once)
pipx install docs-kit

# 2. Ingest docs
docs-kit ingest https://docs.example.com

# 3. Install skill into your agent
docs-kit install claude-code   # or: cursor, codex, opencode, claude-desktop

# 4. Use the agent — it can run docs-kit query / list / ingest when relevant
```

No server to start. On first use, config and the default vector store path are created under **`~/.docs-kit/`** unless you use a project-local `docs-kit.yaml`.

## How it works

docs-kit installs a **skill** (Markdown + YAML frontmatter) into each tool’s skills directory. The skill tells the agent when to use docs-kit and which commands to run (`query`, `list`, `ingest`, `remove`, `inspect`, `doctor`, …). Agents execute **`docs-kit`** via their normal terminal integration.

For more architecture detail (config resolution, layout, security posture), see [docs/project-overview.md](docs/project-overview.md).

## Install targets

| Command | Where the skill lands |
|---------|------------------------|
| `docs-kit install claude-code` | `~/.claude/skills/docs-kit/SKILL.md` |
| `docs-kit install codex` | `~/.codex/skills/docs-kit/SKILL.md` (also mirrors to `~/.agents/skills/docs-kit/SKILL.md` for compatibility) |
| `docs-kit install cursor` | `~/.cursor/skills/docs-kit/SKILL.md` + marked block in `~/.cursor/AGENTS.md` when needed |
| `docs-kit install opencode` | `~/.config/opencode/skills/docs-kit/SKILL.md` (and may mirror under `~/.agents/skills/` if absent) |
| `docs-kit install claude-desktop` | `~/.docs-kit/exports/claude-desktop/docs-kit.zip` — upload via Claude Desktop **Customize → Skills** |

`codex-app` and `codex-desktop` are accepted aliases for the Codex install path.

Use **`--project`** with `claude-code` for `.claude/skills/docs-kit/SKILL.md` in the current repo.

## Commands

### `docs-kit install <agent>`

Install the docs-kit skill into a supported agent.

```bash
docs-kit install claude-code
docs-kit install cursor
docs-kit install codex
docs-kit install opencode
docs-kit install claude-desktop
docs-kit install claude-code --project
docs-kit install cursor --config ./docs-kit.yaml
```

If no config is found, **`~/.docs-kit/docs-kit.yaml`** is created automatically (non-project installs).

### `docs-kit ingest <path-or-url>`

Ingest a local file, directory, or documentation URL.

```bash
docs-kit ingest ./docs
docs-kit ingest https://docs.example.com
docs-kit ingest https://docs.example.com --provider gitbook
docs-kit ingest ./docs --recreate
```

`--provider`: `auto` (default), `gitbook`, or `mintlify`.

### `docs-kit query <text>`

Run hybrid retrieval from the CLI.

```bash
docs-kit query "How do I authenticate?"
docs-kit query "getting started" --limit 3
docs-kit query "season 5 end date" --full
docs-kit query "..." --config ./docs-kit.yaml
```

Use `--full` when you want the entire chunk body instead of the default preview.

### `docs-kit list`

List ingested sources with ingestion timestamps.

```bash
docs-kit list
docs-kit list --config ./docs-kit.yaml
```

### `docs-kit fetch <url>`

Download **GitBook** docs as Markdown files only (does not embed). For Mintlify or mixed hosting, use **`docs-kit ingest`** or copy files locally first.

```bash
docs-kit fetch https://docs.example.com
docs-kit fetch https://docs.example.com --output ./downloaded-docs
```

### `docs-kit remove <source>`

Remove an ingested source by URL or file path.

```bash
docs-kit remove https://docs.example.com/page
docs-kit remove ./docs/getting-started.md
```

### `docs-kit inspect`

Show collection stats and embedding settings.

```bash
docs-kit inspect
docs-kit inspect --config ./docs-kit.yaml
```

### `docs-kit doctor`

Check `docs-kit` on PATH, effective config, Qdrant path / connectivity, and which skills are installed.

For Codex installs, `doctor` reports both the native `~/.codex/skills/...` install and the shared compatibility mirror under `~/.agents/skills/...` when present.

```bash
docs-kit doctor
docs-kit doctor --config ./docs-kit.yaml
```

### `docs-kit init`

Create a project-local **`docs-kit.yaml`** (optional if you rely on `~/.docs-kit/docs-kit.yaml`).

```bash
docs-kit init
docs-kit init --dir ./sandbox
```

## Configuration

**Resolution order:** `--config` → `./docs-kit.yaml` in the current working directory → `~/.docs-kit/docs-kit.yaml` (created on first use when applicable).

Example **project-local** `docs-kit.yaml` from `docs-kit init`:

```yaml
embedding:
  provider: fastembed
  model: BAAI/bge-small-en-v1.5

vector_store:
  provider: qdrant
  local_path: .docs-kit/qdrant   # resolved relative to this file’s directory
  collection_name: knowledge_base
  retrieval_limit: 5
  score_threshold: 0.35

ingestion:
  chunk_size: 800
  chunk_overlap: 120
  bm25_model: Qdrant/bm25
```

The auto-created **user** config under `~/.docs-kit/` sets `local_path` to an absolute directory under **`~/.docs-kit/qdrant`**. To use a **remote** Qdrant instance, set `vector_store.url` and leave local storage unused.

## Supported sources

| Source | Strategy |
|--------|----------|
| GitBook sites | `/llms-full.txt` → `/llms.txt` (GitBook fetcher); `auto` / `mintlify` use the broader pipeline below |
| Mintlify & typical llms.txt sites | `/llms-full.txt` → `/llms.txt` → `/sitemap.xml` |
| Local `.md` / `.txt` | Read from disk |

## Requirements

- **Python 3.11–3.13** (`requires-python` excludes 3.14+ while dependencies such as `onnxruntime` lack wheels)
- Disk space for the embedding model (on the order of tens of MB for the default model)

If your default `python` is 3.14:

```bash
pipx install docs-kit --python python3.13
```

## Migration from v0.1.x

Older releases configured an **MCP server** in agent settings. That integration has been removed in favor of **skills + CLI**.

1. Remove legacy **`mcpServers.docs-kit`** (or equivalent) from `~/.claude/settings.json`, Cursor MCP config, `~/.codex/config.toml`, etc.
2. Run **`docs-kit install <agent>`** again to install skills.
3. Existing **`~/.docs-kit/docs-kit.yaml`** and ingested data remain valid; any unused **`mcp:`** section in YAML can be deleted for clarity.
