Metadata-Version: 2.4
Name: llm-wiki-tools
Version: 0.4.0
Summary: CLI tools to read and manage LLM Wiki projects on GitHub
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markitdown>=0.1.0
Requires-Dist: anthropic>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# llm-wiki-tools

CLI tools to implement an **Agentic LLM Wiki**. Manage project knowledge as a "compiled codebase" that AI agents can read, write, and patch surgically.

**No MCP server. No heavy infrastructure. Just Python, Markdown, and Git.**

---

## The Concept: Knowledge as Code

Inspired by Andrej Karpathy's vision, this tool treats documentation like software:
1.  **Raw Sources (`raw/`)**: Immutable "source code" (PDFs, docs, transcripts).
2.  **The Wiki (`wiki/`)**: "Compiled binary" (Markdown) optimized for LLM consumption.
3.  **The Agent (Claude Code)**: The "compiler" that ingests sources and patches the wiki.

---

## How it works

```text
local disk (Wiki Repo)             GitHub (Source of Truth)
──────────────────────────────    ──────────────────────────
wiki-my-project/
  raw/       ── generate ──┐
  updates/   ── update   ──┤
                           ▼
  wiki/ (Local Markdown) ──┴──► [git push] ──► GitHub Repo
                                                  │
                                                  │
  wiki-read (Local First) ◄───────────────────────┘
  (Used by Claude in any repo)
```

- **`wiki-manage`**: Operates on your **local disk**. It converts sources and writes Markdown files directly to your `wiki/` folder. You review and `git push` manually.
- **`wiki-read`**: Used by agents to consult knowledge. It checks the local `wiki/` folder first (for uncommitted changes) and falls back to the GitHub API.

---

## Install

```bash
pip install llm-wiki-tools
```

For image vision support (OCR for PDFs/Images via Claude Sonnet):
```bash
pip install "llm-wiki-tools[vision]"
```

---

## Requirements

- **Python 3.10+**
- **GitHub Token**: Exported as `GITHUB_TOKEN`. Required for `wiki-read` and identifying the repo.
- **Anthropic API Key** (Optional): Exported as `ANTHROPIC_API_KEY`. Enables OCR for images/PDFs.

---

## Configuration (`.project`)

Place a `.project` file at the root of your project.

### In the Wiki Repo (Full Access)
```json
{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project",
  "wiki_local_path": "/Users/you/projects/wiki-my-project"
}
```

### In a Project Repo (Read-Only)
```json
{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project"
}
```

---

## Commands

### `wiki-read` (Consult Knowledge)
- `wiki-read <page>`: Print page content.
- `wiki-read --list`: List all pages.
- `wiki-read --search "query"`: Full-text search across the wiki.

### `wiki-manage` (Maintain Knowledge)
- **Status**: `wiki-manage status` (File counts and pending updates).
- **Ingestion**: 
    - `wiki-manage generate`: Convert `raw/` files and emit for agent analysis.
    - `wiki-manage update`: Convert `updates/` files, emit, and move them to `raw/`.
- **Surgical Writing (via STDIN)**:
    - `wiki-manage write <page>`: Write/Overwrite a full page.
    - `wiki-manage patch <page> "<header>" <action>`: Modify a specific section.
- **Maintenance**:
    - `wiki-manage lint`: Check for broken links, orphan pages, and missing requirements.
    - `wiki-manage delete <page>`: Delete a page locally.

---

## Surgical Patching

The `patch` command allows agents to modify specific sections of a page without rewriting the entire document. This saves tokens and prevents hallucinations.

**Actions:**
- `append`: Insert content at the end of the section.
- `prepend`: Insert content immediately after the header.
- `replace`: Replace the section body.
- `delete`: Remove the entire section (header included).

**Example:**
```bash
cat << 'EOF' | wiki-manage patch architecture "## Database" replace
The project uses PostgreSQL 16 on AWS RDS.
EOF
```

---

## Agent Guidelines (`CLAUDE.md`)

Add this to your Wiki Repo's `CLAUDE.md` to guide the AI:

```markdown
## Wiki Management Rules
- **Sources**: `raw/` is immutable. Never edit files there.
- **Ingestion**: Use `wiki-manage update` to process new docs.
- **Editing**: Prefer `wiki-manage patch` for surgical updates to existing pages.
- **Writing**: Use `cat << 'EOF' | wiki-manage ...` for all write/patch ops.
- **Changelog**: Always update `wiki/changelog.md` after any modification.
- **Validation**: Run `wiki-manage lint` before finishing a task.
- **Git**: You write to local `wiki/` only. The human will push to GitHub.
```

---

## Required Pages
- `index.md`: Must contain links to all other pages.
- `changelog.md`: A reverse-chronological log of updates.

---

## Publishing to PyPI

1. Bump version in `pyproject.toml`.
2. `pip install build twine`
3. `python -m build`
4. `twine upload dist/*`

---
