hermeneutic

# hermeneutic repository (latest tagged release v0.1.12)

Hermeneutic is a local-first Python 3.10+ toolkit for three distinct jobs:

1. mine correction triples from supported Claude Code, Codex, and OpenAI-style chat logs;
2. optionally retrieve similar prior corrections with a local Ollama embedding index;
3. run eight fixed deterministic English regex checks on outgoing drafts.

Mining personalizes the corpus and optional retrieval. It does not generate or modify gate rules. The `hermeneutic gate` CLI is regex-only; the optional three-stage `Router` is a separate Python API configured by its caller.

## Exact installation

Install the current release from PyPI:

```bash
python3 -m pip install 'hermeneutic==0.1.12'
```

For repository-only integrations, evaluations, and forward-deployed tooling after the release tag exists:

```bash
git clone --branch v0.1.12 --depth 1 https://github.com/hermes-labs-ai/hermeneutic.git
cd hermeneutic
python3 -m pip install .
```

The `v0.1.12` tag does not contain the unreleased native Qwen extension. From an exact checkout or ref that contains `qwen-extension.json`, install it with:

```bash
qwen extensions install . --consent
```

The core has zero required Python runtime dependencies. Source builds use `hatchling>=1.24`. Optional compile/retrieval needs local Ollama plus `nomic-embed-text`; optional Router stages need external caller-selected tools or functions.

## Central CLI workflow

```bash
printf '%s\n' 'Done — shipped 14 files, all tests pass.' | hermeneutic gate
```

Expected first line: `RISK — highest severity: high`.

- `hermeneutic mine <dir> --out <triples.jsonl>`: extract correction triples.
- `hermeneutic bucket <triples.jsonl>`: print fixed category counts.
- `hermeneutic gate [--draft <file>]`: run the fixed English gate; medium/high risk exits 1.
- `hermeneutic compile-index --triples <triples.jsonl>`: build the optional local embedding index.
- `hermeneutic compile [prompt]`: retrieve a deterministic warning preamble when matches exist.
- `hermeneutic harvest`, `promote`, and `stats`: local review and audit workflow.

## Evidence boundary

- Historical derivation: 326 corrections from 1,423 sessions belonging to one user; private triples are not shipped.
- Current direct gate coverage on the separate later frozen 346-triple corpus: 115/346 (33.24%), retrospective derivation-set coverage and not held out.
- Current production-path same-bucket retrieval: 88/104 (84.6%) at CLI/hook defaults; 94/104 (90.4%) at Python defaults.
- Prior 83.7% and 98/100 retrieval figures are historical experiments whose evaluators differed from the current production path.
- Precision, false-positive rate on ordinary prompts, generalization, and downstream model effectiveness are unmeasured.

## Scope and maturity

The fixed gate is English-only and advisory unless a caller blocks before sending. The current repository includes a live-verified Qwen Code 0.23.2 native Stop extension; its exact host and provider boundary is recorded in `evals/qwen-code/RESULTS.md`. The Claude prompt-context compile hook and Codex plugin are mechanically tested, not live-host certified. Cursor and OpenHands documents are design sketches. Current Claude Stop, Cline, and Windsurf adapters are removed from the ready-support matrix because host contracts drifted.

## Privacy

Core mining, bucketing, gate, harvest, review, and promotion are local and make no network calls. The built-in compile path uses localhost Ollama; Python callers can override that URL and own the resulting endpoint policy. Telemetry is off by default. Triples, embeddings, raw telemetry, and injected context can contain sensitive text; review before sharing.

## Project

- Repository: https://github.com/hermes-labs-ai/hermeneutic
- Documentation: README.md
- Citation: CITATION.cff
- Security: SECURITY.md
- License: Apache-2.0
- Public display author: Rolando Bosch, Hermes Labs