Metadata-Version: 2.4
Name: hermes-blind
Version: 0.1.4
Summary: Local recovery anchors for Claude Code and Codex sessions, plus evidence-gated evaluation prompts
Author-email: Hermes Labs <roli@hermes-labs.ai>
License-Expression: MIT
Project-URL: Homepage, https://hermes-labs.ai/open-source
Project-URL: Documentation, https://github.com/hermes-labs-ai/hermes-blind#readme
Project-URL: Source, https://github.com/hermes-labs-ai/hermes-blind
Project-URL: Issues, https://github.com/hermes-labs-ai/hermes-blind/issues
Project-URL: Changelog, https://github.com/hermes-labs-ai/hermes-blind/blob/main/CHANGELOG.md
Project-URL: Evaluation, https://github.com/hermes-labs-ai/hermes-blind/blob/main/EVALUATION.md
Keywords: ai-agents,claude-code,codex,drift-recovery,llm-evaluation,prompt-engineering,session-recovery
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Hermes Blind

**Recover the original goal of a long Claude Code or Codex session—and add evidence constraints to evaluation prompts.**

[![PyPI](https://img.shields.io/pypi/v/hermes-blind.svg)](https://pypi.org/project/hermes-blind/)
[![Python](https://img.shields.io/pypi/pyversions/hermes-blind.svg)](https://pypi.org/project/hermes-blind/)
[![CI](https://github.com/hermes-labs-ai/hermes-blind/actions/workflows/ci.yml/badge.svg)](https://github.com/hermes-labs-ai/hermes-blind/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/hermes-labs-ai/hermes-blind/blob/main/LICENSE)
[![Status: experimental](https://img.shields.io/badge/status-experimental-orange.svg)](#evidence-and-limits)

Long agent sessions can lose the shape of the request that started them.
Hermes Blind reads the first user turn from a local Claude Code or Codex JSONL
log and writes a compact recovery anchor you can inspect and paste back into
the session. It also provides a small prompt wrapper for evaluations that asks
the model to disclose prior exposure, quote its evidence, and hedge when the
evidence is thin.

The package is deterministic, dependency-free at runtime, and local: it makes
no model calls and sends no network requests.

## Install

For the isolated command-line app:

```bash
pipx install hermes-blind
```

Or install it into your current Python environment:

```bash
python -m pip install hermes-blind
```

Requires Python 3.10+.

## Recover a long agent session

The lowest-friction path is to give your coding agent this instruction:

> Install `hermes-blind`. Find the JSONL log for this Claude Code or Codex
> session, then run `hermes-blind apply --session <path> --format auto
> --turn <current-turn-number> --out recovery.md`. Show me the generated
> anchor and use it to restate my original goals before continuing. Do not
> overwrite files or share the session text.

Or run it directly:

```bash
hermes-blind apply \
  --session /path/to/session.jsonl \
  --format auto \
  --turn 9 \
  --out recovery.md
```

The generated markdown starts like this:

```markdown
# Recovery scaffold (anchor-extracted from turn 1, applied at turn 9)

## Original anchor
- stated_goal: "Ship the onboarding flow and verify the clean install"

## Session state
- session file: rollout.jsonl
- user turns observed: 9
```

`--format auto` recognizes Claude Code and Codex JSONL shapes. The default
`goals` mode preserves up to 12 goal-carrying sentences from the first user
turn; `first-sentence` keeps the compact legacy behavior and `full` includes
up to 4,000 characters.

The `--turn` value is only a label in the output. Hermes Blind does not detect
drift or decide when recovery is needed. Existing output files are preserved
unless `--force` is explicit, and the input session file can never be used as
the output path.

Recovery files include user-authored text. Inspect them before sharing.

## Add evidence constraints to an evaluation prompt

From the CLI:

```bash
hermes-blind apply \
  --variant v1 \
  --prompt "Score this release from quoted evidence."
```

This prints a wrapped prompt without calling a model:

```text
[HERMES-BLIND]
If you have prior exposure to this target or its author, state it in one line.
Score using only quoted evidence from the target text below.
Unknown or thin evidence = hedge; do not confabulate.
[/HERMES-BLIND]

Score this release from quoted evidence.
```

Or use the Python API:

```python
from hermes_blind import wrap

prompt = wrap(
    "Rate this paper on novelty from 0 to 10 and cite the target text.",
    variant="v1",
)
```

Available variants are `null`, `micro`, `short`, `v1`, `full`, `placebo`, and
`gate-only`. The `null` variant is an exact no-op for controlled comparisons.
The package also exposes the dependency-free intent and scope preambles used
by [Hermes Rubric](https://github.com/hermes-labs-ai/hermes-rubric).

## Evidence and limits

The repository tests and CI cover deterministic wrapping, Claude Code and
Codex JSONL parsing, recovery modes, safe output handling, package
installation, and CLI invocation.

A frozen nine-session extraction audit found that the default goal-set anchor
represented 40 of 66 pre-listed goals, compared with 7 of 66 for the earlier
first-sentence heuristic. That supports better mission representation in the
generated artifact for the evaluated sessions. It does **not** establish that
reinserting the artifact changes model behavior or improves task outcomes.
See the [evaluation report](https://github.com/hermes-labs-ai/hermes-blind/blob/main/EVALUATION.md)
for the method, limitations, sanitized results, and receipt hashes.

Not established:

- reliable bias reduction from the evaluation prefix;
- successful behavioral recovery after inserting an anchor;
- automatic drift detection or an optimal intervention turn;
- adversarial prompt-injection resistance; or
- non-English behavior.

Treat the output as a transparent scaffold for a human or agent to inspect,
not as a security boundary or independent evaluator.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check src tests
pytest -q
python -m build
twine check dist/*
```

See the [changelog](https://github.com/hermes-labs-ai/hermes-blind/blob/main/CHANGELOG.md)
for release history and the
[contribution guide](https://github.com/hermes-labs-ai/hermes-blind/blob/main/CONTRIBUTING.md)
for contribution guidance.

## License

MIT. See the [license](https://github.com/hermes-labs-ai/hermes-blind/blob/main/LICENSE).

Built by [Hermes Labs](https://hermes-labs.ai).
