# DocNeedle

Local-first deterministic doc lookup/update prototype using SQLite FTS5.

DocNeedle has two separate modes of use:

1. Normal CLI usage: index a markdown tree, search it, read a chunk, run stale-term checks.
2. Benchmark usage: run the repo's evaluation scripts against a real corpus and task set.

Do not mix them. The benchmark scripts are repo-specific evaluation harnesses, not the normal way to use the tool.

## Requirements

- Python 3.11+
- SQLite with FTS5 support
- `uv` recommended for environment setup
- `rg` required only for the benchmark baselines

## Setup

Create a local virtualenv and install the repo in editable mode:

```bash
uv venv
source .venv/bin/activate
uv pip install -e . pytest
```

Quick verification:

```bash
python -m docneedle.cli --help
python -m pytest -q
```

## Normal CLI usage

This is the main product surface.

### 1) Build or refresh an index

```bash
python -m docneedle.cli index \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --changed-only \
  --json
```

Notes:
- `--root` is the markdown corpus root.
- `--db` is the SQLite database DocNeedle will create/update.
- `--changed-only` does incremental refresh instead of full rebuild.

### 2) Search

```bash
python -m docneedle.cli search \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --query "home action center doc index router" \
  --limit 8 \
  --json
```

Optional:
- `--feature <name>` filters search results to one feature.

### 3) Read a result chunk

Take a `chunk_id` from search output, then:

```bash
python -m docneedle.cli read \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --chunk-id <chunk-id> \
  --json
```

### 4) Run a stale/conflict check

```bash
python -m docneedle.cli check \
  --root /path/to/docs \
  --db /tmp/docneedle.sqlite \
  --topic "weight logging" \
  --terms '["weight check-in", "ranked steps recommendation"]' \
  --json
```

## CLI commands

- `index`: parse markdown and write chunk/file metadata into SQLite.
- `search`: retrieve ranked chunk candidates for a query.
- `read`: fetch one chunk payload by `chunk_id`.
- `check`: scan for stale/conflicting phrases for a topic.

## Benchmark setup

Use this only if you want to reproduce the repo's evaluation runs.

Current benchmark scripts are under:

- `benchmarks/real-doc/run_real_doc_benchmark.py`
- `benchmarks/holdout-doc/run_holdout_doc_benchmark.py`
- `benchmarks/dev-broad-doc/run_dev_broad_doc_benchmark.py`

These scripts are not generic. They currently hardcode:

- a real docs root (`ROOT`)
- the expected repo/worktree location (`WORK_ROOT`)
- temp DB paths
- report output paths
- task JSON locations for some benchmark sets

Before running them on another machine or corpus, patch those constants near the top of each script.

Minimum benchmark prerequisites:

- repo installed in a venv
- target markdown corpus exists locally
- `rg` installed
- write access to the configured artifact/report paths

## Benchmark usage

### Real-doc benchmark

```bash
python benchmarks/real-doc/run_real_doc_benchmark.py
```

Produces artifacts in `benchmarks/real-doc/` and writes a markdown report to the configured `REPORT_PATH` inside the script.

### Holdout benchmark

```bash
python benchmarks/holdout-doc/run_holdout_doc_benchmark.py
```

Uses `benchmarks/holdout-doc/holdout_tasks.json` and writes summary artifacts to `benchmarks/holdout-doc/` plus the configured report path.

### Broad dev benchmark

```bash
python benchmarks/dev-broad-doc/run_dev_broad_doc_benchmark.py
```

Uses `benchmarks/dev-broad-doc/dev_tasks.json`, compares against the configured holdout task file, and writes artifacts/report to the paths configured in the script.

## When to use which path

Use normal CLI usage when you want to:
- index your own docs
- answer a query
- inspect one result chunk
- detect stale terms/conflicts

Use benchmark scripts when you want to:
- measure retrieval quality on a fixed task set
- compare DocNeedle against `rg` baselines
- generate evaluation reports
- detect regressions after ranking/parser changes

## Current MVP limitations

- No LLM or remote API is used for indexing or retrieval.
- Index data lives in SQLite with FTS5.
- Patch mechanics are scaffolded but not exposed as a CLI command in this MVP slice.
- Benchmark scripts are still author-environment-oriented and need constant/path cleanup before they become portable.