ithrl 0.1.0__tar.gz → 0.2.0__tar.gz

{ithrl-0.1.0 → ithrl-0.2.0}/.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 *.py[cod]
 .pytest_cache/
 .ruff_cache/
+.rumdl_cache/
 .hypothesis/
 .pyrefly/
 .coverage

{ithrl-0.1.0 → ithrl-0.2.0}/CHANGELOG.md

@@ -1,8 +1,56 @@
 # CHANGELOG
 
-<!-- version list -->
+## v0.2.0 (2026-11-02)
 
-## v0.1.0 (2026-10-17)
+### Bug Fixes
+
+- **codex**: Bound and account for physical provider requests
+  ([#33](https://github.com/eberkut/ithrl/pull/33),
+  [`88529d6`](https://github.com/eberkut/ithrl/commit/88529d6f8b930dbcc546a0011f085c67d0bef1ac))
+
+- **copilot**: Recover catalogue connections and qualify fuzzing
+  ([#37](https://github.com/eberkut/ithrl/pull/37),
+  [`ff6cf63`](https://github.com/eberkut/ithrl/commit/ff6cf6324325f7f6dad8f8c9c80ea58bfe4e249a))
+
+- **copilot**: Restore native session prefixes through the CLI
+  ([#34](https://github.com/eberkut/ithrl/pull/34),
+  [`36845dd`](https://github.com/eberkut/ithrl/commit/36845ddb8239c0a488552297aaa70e6211979e59))
+
+- **fuzz**: Preserve accounting and validate campaign recovery
+  ([#25](https://github.com/eberkut/ithrl/pull/25),
+  [`f1f4793`](https://github.com/eberkut/ithrl/commit/f1f479318fe914f3033667b65381f7101bd3aaea))
+
+- **sampling**: Enforce calibration budgets and report durable progress
+  ([#32](https://github.com/eberkut/ithrl/pull/32),
+  [`bd40577`](https://github.com/eberkut/ithrl/commit/bd40577c734d70b36e59a9e6d3babafa1502bfd3))
+
+### Features
+
+- **extract**: Support literal predicates for native decisions
+  ([#31](https://github.com/eberkut/ithrl/pull/31),
+  [`3b18c2b`](https://github.com/eberkut/ithrl/commit/3b18c2bdd814c4e4c3bf79825a8cab77eb433661))
+
+- **fuzz**: Add mutation and sampled comparison services
+  ([`56ee8b8`](https://github.com/eberkut/ithrl/commit/56ee8b8c5e1370b91db6c9c952eb8ceec19c95ae))
+
+- **fuzz**: Expose inspectable campaigns and saved results
+  ([#24](https://github.com/eberkut/ithrl/pull/24),
+  [`e60e472`](https://github.com/eberkut/ithrl/commit/e60e47230b99e50ff42de7cd8fb89b3769e6d6e2))
+
+- **fuzz**: Persist campaigns and recover interrupted execution
+  ([#22](https://github.com/eberkut/ithrl/pull/22),
+  [`806667f`](https://github.com/eberkut/ithrl/commit/806667f47e8bae1ccbf9b32fadc511ca559675d0))
+
+- **fuzz**: Qualify native Codex text appends ([#28](https://github.com/eberkut/ithrl/pull/28),
+  [`a5b880b`](https://github.com/eberkut/ithrl/commit/a5b880b60ef9834bb57b2c4950e18cd17ff0b275))
+
+### Performance Improvements
+
+- Streamline local workflows and harden result publication
+  ([#36](https://github.com/eberkut/ithrl/pull/36),
+  [`43b9d81`](https://github.com/eberkut/ithrl/commit/43b9d81d0dcff85708da5c914986a68bbe8141db))
+
+## v0.1.0 (2026-10-23)
 
 ### Bug Fixes
 

{ithrl-0.1.0 → ithrl-0.2.0}/CONTRIBUTING.md

@@ -1,11 +1,28 @@
 # Contributing
 
-Start with an [issue](https://github.com/eberkut/ithrl/issues) describing the problem or proposed
-change. Pull requests are limited to collaborators; discuss the work before preparing one.
+Open an [issue](https://github.com/eberkut/ithrl/issues) for a bug report, question or proposed
+change. Pull requests are limited to collaborators. If you are not a collaborator and want to
+implement a change, agree on scope and ask the maintainer about access in the issue before preparing
+a PR.
 
 For bug reports, include the ithrl version, platform, sanitized error code and steps to reproduce.
 Keep full sessions, cases, proprietary source and credentials out of public reports. Report
-suspected vulnerabilities through [private vulnerability reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+suspected vulnerabilities through
+[private vulnerability reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+
+## First contribution
+
+1. Find an existing issue or open one, and agree on scope with the maintainer.
+2. Follow [development setup](#development-setup) to prepare the locked environment.
+3. Make a focused change using [Preparing a change](#preparing-a-change), and run the relevant
+   [checks](#checks).
+4. Open a PR linking the issue and explaining the change and its validation. Follow the
+   [review requirements](#pull-request-review).
+
+For task-specific instructions, see [documentation](#documentation),
+[workflows and dependencies](#workflow-and-dependency-checks),
+[integration tests](#credential-free-integration-tests) or
+[native smoke tests](#opt-in-native-smoke-tests).
 
 ## Development setup
 
@@ -13,7 +30,7 @@ Use [uv](https://docs.astral.sh/uv/) and Python 3.12, 3.13 or 3.14. Python 3.14
 development version. From the repository root:
 
 ```bash
-uv sync --locked --all-groups
+uv sync --locked --all-groups --all-extras
 uv run ithrl --help
 ```
 
@@ -28,6 +45,8 @@ Run the same entry points used by CI:
 uv lock --check
 uv run ruff check .
 uv run ruff format --check .
+uv run rumdl fmt --check .
+uv run rumdl check .
 uv run pyrefly check
 uv run pytest --ignore=tests/packaging
 uv run radon cc src/ithrl --min B --show-complexity --total-average
@@ -36,7 +55,8 @@ uv build --sdist --wheel --no-sources
 ITHRL_DIST_DIR=dist uv run pytest -o addopts= tests/packaging
 ```
 
-Non-packaging tests and the synthetic example need no provider credentials or network requests.
+Non-packaging tests and the synthetic example need no provider credentials or external network
+access. Native-runner tests need Linux, Bubblewrap and OpenSSL; their HTTPS fixture runs locally.
 Packaging checks may download build and runtime dependencies. Radon reports are review signals.
 
 CI runs tests, dependency audits and installed-package checks on Python 3.12–3.14. It builds one
@@ -47,6 +67,21 @@ an isolated tool, pass its path to `uv tool install` or `pipx install`.
 For local matrix runs, set `UV_PYTHON` on every command. Use separate environments, test caches and
 coverage files for parallel runs; otherwise run versions sequentially.
 
+Install the local hooks with `uv run pre-commit install`; run them on the whole repository with
+`uv run pre-commit run --all-files`. Ruff and rumdl format files in place. CI checks formatting
+without modifying files.
+
+Recognized Markdown-only PRs skip Python linting, typing, unit-test matrices and dependency audits.
+They retain Markdown formatting/linting, documentation tests, the strict site build, workflow and
+dependency review, and all package build/install checks. Mixed changes, unknown paths, configuration
+changes and PRs with 3,000 or more changed files run full validation. Rename detection considers
+both paths; deletions participate. Failed path detection fails the required Workflows check.
+Main-branch, scheduled, manual and release runs always perform full validation.
+
+The required `Python tests` check summarizes the test matrix. It accepts a skipped matrix only
+after successful Markdown-only classification. Failed classification, missing decisions, test
+failures and unexpected skips fail this check.
+
 ## Workflow and dependency checks
 
 For GitHub Actions or Dependabot changes, use the jactionlint release pinned in
@@ -58,12 +93,13 @@ jactionlint --no-online --strict-exit
 
 CI uses its default correctness/security profile, with online lookups and automatic fixes disabled.
 
-Audit the resolved runtime dependencies and every dependency group, including development, docs
-and audit tooling, from `uv.lock`. Run this in Bash with the locked environment synchronized:
+Audit the resolved runtime dependencies, optional extras and every dependency group, including
+development, docs and audit tooling, from `uv.lock`. Run this in Bash with the locked environment
+synchronized:
 
 ```bash
 set -o pipefail
-uv export --locked --all-groups --no-emit-project --format requirements.txt |
+uv export --locked --all-groups --all-extras --no-emit-project --format requirements.txt |
   uv run --locked --group audit pip-audit --strict --disable-pip --require-hashes -r /dev/stdin
 ```
 
@@ -72,25 +108,48 @@ package names and versions without installing those packages, resolving alternat
 fixes. CI evaluates markers on each supported Python version. This covers locked versions rather
 than every version permitted by package dependency ranges.
 
-GitHub's dependency graph and Dependency Review use the inventory GitHub has for each commit.
-Before relying on them for `uv.lock` coverage, compare the hosted package/version inventory with
-the locked export on each supported Python version. The PR dependency-review job rejects newly
-introduced known vulnerabilities at any severity across runtime, development and unknown scopes.
-It uses a read-only token and does not check out or execute PR code. If it reports incomplete
-dependency snapshots, wait for GitHub's graph update and rerun the job. No license allowlist is
-enforced by this check. Keep the lockfile audit above as the full-inventory CI gate; Dependabot
-version updates alone do not establish dependency-graph coverage.
+For dependency changes, run the lockfile audit above on each supported Python version. GitHub's
+dependency graph may omit packages from `uv.lock`, so Dependabot and Dependency Review cannot
+replace that audit.
+
+The PR dependency-review job rejects newly introduced known vulnerabilities at any severity across
+runtime, development and unknown scopes. It uses a read-only token and does not check out or execute
+PR code. If it reports incomplete dependency snapshots, wait for GitHub's graph update and rerun
+the job. License checks are disabled.
 
 CI runs weekly on Monday at 06:17 UTC to detect new advisories. Dependabot checks Python, Actions
 and pre-commit dependencies weekly, groups minor/patch updates and leaves majors individually
 reviewable. Ordinary updates have a seven-day cooldown; security updates have none. Updates are
-never automatically merged. Hosted dependency-graph coverage is a separate verification gate.
+never automatically merged.
 
 ## Documentation
 
-README owns the quick start; `docs/` owns user guides and reference. Support, security and conduct
-policies live at the repository root. Keep private sessions, cases and credentials out of
-documentation and generated output.
+Use `uv run rumdl fmt .` to format Markdown, then `uv run rumdl check .` to lint it. The same
+version and `pyproject.toml` configuration apply to pre-commit and CI. Prose wraps at 100
+characters; commands and tables retain their layout. MkDocs syntax is recognized within `docs/`. The
+generated CLI reference has narrow exceptions for Typer's prompts, option alignment and wrapping;
+its byte-for-byte generation check remains enforced. The generated changelog is checked under the
+shared rules.
+
+Keep installation and first-use instructions in README, and detailed user guides and reference in
+`docs/`. Support, security and conduct policies live at the repository root. Keep private sessions,
+cases and credentials out of documentation and generated output.
+
+[ROADMAP.md](ROADMAP.md) describes future direction. GitHub issues own actionable scope,
+dependencies, acceptance criteria and status; release milestones group scope and the public
+[Project](https://github.com/users/eberkut/projects/1/views/4) provides views of those same issues.
+Link implementation pull requests to their owning issues and record relevant validation before
+closing them. Keep future plans separate from current support claims.
+
+Use [architecture](docs/architecture.md) to locate current contracts,
+[decision records](docs/decisions/index.md) for significant choices and alternatives, and
+[research](docs/research/index.md) for methods, measurements and reproducibility. Amend the owning
+document instead of maintaining a second plan. A new decision record should explain context,
+decision, alternatives and consequences; supersede an old decision explicitly when needed.
+
+Before evaluating a new study, declare its tested domain, criteria, seeds, budget and intended
+claims. Report costs across complete workflows, including failed and incomplete work, and document
+the alternatives and limitations needed to interpret the results.
 
 The optional `docs` dependency group pins MkDocs and the shadcn theme. Search runs in the browser;
 fonts and scripts are served with the site. GitHub star-count requests and raw Markdown copying
@@ -100,13 +159,16 @@ When changing the theme or enabled extensions, check that asset list and the
 To preview the site locally:
 
 ```bash
-uv sync --locked --all-groups
+uv sync --locked --all-groups --all-extras
 uv run --group docs mkdocs serve
 ```
 
-`mkdocs.yml` admits only the named public files under `docs/`. When adding a page, update its
-navigation and file allowlist, the sdist include list in `pyproject.toml`, and the documentation
-manifests in the documentation and packaging tests. Never set `docs_dir` to the repository root.
+`mkdocs.yml` admits public pages and Markdown files in the dedicated `docs/decisions/` and
+`docs/research/` directories. These directories contain publication-ready material only. Add new
+pages to navigation; a page within an admitted directory needs no per-file package/test entry.
+When adding a public directory or asset type, update the site/sdist publication boundaries and
+their tests together. Never set `docs_dir` to the repository root. Keep raw evidence and generated
+research outputs outside the documentation sources.
 
 After changing CLI options or help, regenerate the committed reference with Typer:
 
@@ -132,7 +194,7 @@ runs in a separate `github-pages` environment job without checking out or execut
 Pull requests receive read-only documentation checks through CI and cannot deploy.
 
 Repository administrators must select **Settings → Pages → Source: GitHub Actions** and restrict
-the `github-pages` environment to `main` before the first deployment. No custom domain, separate
+the `github-pages` environment to `main`. No custom domain, separate
 site repository, `gh-pages` branch or personal access token is needed. After a successful
 deployment, check the published pages, navigation and static assets at the URL above.
 
@@ -153,8 +215,15 @@ accounting and budget refusal:
 uv run pytest -o addopts= tests/integration/test_native_calibration.py -q
 ```
 
+Fuzz CLI tests cover harness-free inspection, consent, bounded collection, unsuccessful outcomes,
+interruption and exact resume without provider requests:
+
+```bash
+uv run pytest -o addopts= tests/integration/test_fuzz_cli.py -q
+```
+
 These tests establish local contracts. Native qualification is recorded in the
-[measurement notes](docs/native-runs.md#compatibility-and-measurements).
+[measurements](docs/measurements.md).
 
 ## Opt-in native smoke tests
 
@@ -188,13 +257,13 @@ uv run pytest -o addopts= tests/live -m native_smoke -s \
 ```
 
 Every invocation creates fresh private state, harmless session content and an empty original
-workspace. Calibration requires two matching attempts and permits at most two, each bounded at
-120 seconds plus cancellation grace. Final-response profiles allow up to two provider calls;
-Copilot shell allows up to four, with `pwd` visible but denied.
+workspace. Calibration requires two matching attempts and permits at most two, each bounded at 120
+seconds plus cancellation grace. Codex allows up to 32 provider calls across the two attempts;
+either Copilot profile allows up to two. In the shell profile, `pwd` is visible but denied.
 
-Returned actions never execute. Hosted tools, MCP and tool-side network effects remain forbidden.
-An input-token cap cannot be enforced. Private evidence records known counts and unknown
-acceptance explicitly. Unsupported or unsuccessful profiles fail the test without skipping or retrying.
+Returned actions never execute. Hosted tools, MCP and tool-side network effects remain forbidden. An
+input-token cap cannot be enforced. Private evidence records known counts and unknown acceptance
+explicitly. Unsupported or unsuccessful profiles fail the test without skipping or retrying.
 
 ## Preparing a change
 
@@ -206,8 +275,28 @@ Changes to native protocols, reconstruction, permissions or provider accounting
 the affected safety boundary. Mock tests establish local contracts; claims of native support also
 need capability, isolation, calibration and live-use evidence for the target profile.
 
+### Pull request review
+
+Pull requests are squash-merged, with the PR title becoming the commit subject. Use a Conventional
+Commit title, such as `fix(codex): handle overload responses` or
+`docs: explain confirmation results`. The title check reruns on title edits and new pushes; it reads
+metadata without checking out PR code. Make sure the required CI and CodeQL checks pass and resolve
+review conversations before merging.
+
+CodeRabbit reviews PRs when they are ready for review and posts feedback in a walkthrough and
+inline comments. Address relevant findings or explain why a suggestion does not apply. The
+maintainer makes the final review and merge decisions.
+
+CodeRabbit's optional planning and code-generation features are configured in
+[`.coderabbit.yaml`](.coderabbit.yaml). A paid CodeRabbit account is not required to contribute.
+
 ## Preparing a release
 
+The release procedures below are for maintainers with repository and package-publishing access.
+
+For every feature, aim for parity across supported harnesses. Any exception must be clearly
+justified and documented before release.
+
 Python Semantic Release, pinned in the `release` dependency group, calculates versions from
 Conventional Commits. `pyproject.toml` is the version source; installed CLI and Codex client
 metadata read that distribution version. The tool generates `CHANGELOG.md` from the full release
@@ -256,8 +345,8 @@ ownership and the following repository/index settings:
 - Release-tag rules permit the maintainer's signed-tag creation and prevent unapproved tag
   replacement or deletion. The workflow never creates a tag.
 
-The dispatch gate admits the repository's current maintainer identity and requires the full source
-SHA and exact final `X.Y.Z` version. Replace the placeholders with the reviewed values:
+The release workflow accepts dispatches only from the repository maintainer. Supply the full source
+commit SHA and exact final `X.Y.Z` version. Replace the placeholders with the reviewed values:
 
 ```bash
 gh workflow run release.yml --repo eberkut/ithrl --ref main \

ithrl-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: ithrl
+Version: 0.2.0
+Summary: Find smaller agent contexts that preserve a selected model behavior
+Project-URL: Source, https://github.com/eberkut/ithrl
+Project-URL: Issues, https://github.com/eberkut/ithrl/issues
+Project-URL: Documentation, https://eberkut.github.io/ithrl/
+Project-URL: Changelog, https://github.com/eberkut/ithrl/releases
+Author: Vincent Morel
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.12
+Requires-Dist: filelock>=3.32.4
+Requires-Dist: github-copilot-sdk==1.0.28
+Requires-Dist: jsonschema>=4.25
+Requires-Dist: packaging>=24.2
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: pydantic>=2.12
+Requires-Dist: rich>=14
+Requires-Dist: typer>=0.16
+Provides-Extra: fuzz
+Requires-Dist: scipy>=1.18; extra == 'fuzz'
+Description-Content-Type: text/markdown
+
+# ithrl
+
+[![PyPI](https://img.shields.io/pypi/v/ithrl.svg)](https://pypi.org/project/ithrl/)
+[![CI](https://github.com/eberkut/ithrl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/eberkut/ithrl/actions/workflows/ci.yml)
+
+`ithrl` turns saved Codex and GitHub Copilot sessions into debugging experiments. Search for a
+smaller context that preserves a chosen response or tool request, or a small text change that alters
+it.
+
+[Documentation](https://eberkut.github.io/ithrl/) · [Try it](#try-it) ·
+[Supported inputs](#supported-inputs)
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install ithrl
+```
+
+You can also install with `pipx install ithrl` or, in an existing virtual environment,
+`python -m pip install ithrl`. For context fuzzing, use `'ithrl[fuzz]'` in place of `ithrl` in
+the installation command.
+
+Tested on Python 3.12–3.14. Native runners require Linux. APIs and saved formats may change before
+1.0; keep your source sessions and record the version used for each case.
+
+## Try it
+
+The bundled deterministic example needs no account, agent installation or model access:
+
+```bash
+mkdir -m 700 ithrl-demo
+ithrl extract --example --output ithrl-demo/case
+ithrl shrink ithrl-demo/case --observation-store ithrl-demo/observations.sqlite
+```
+
+The result removes half the context items and confirms that the target is preserved. Output excerpt:
+
+```text
+Reduced and confirmed
+  context items   10 -> 5
+  original test   target observed
+  search          1-minimal; all valid single removals tested
+  confirmation    target preserved
+  observations    15
+  No network requests or provider calls. No actions executed.
+```
+
+Inspect the saved result in `ithrl-demo/case/results/`; the
+[results guide](https://github.com/eberkut/ithrl/blob/main/docs/results.md) explains its files.
+Use a new directory to repeat the example; extraction refuses to overwrite an existing case.
+
+## Commands
+
+- `ithrl extract` browses saved sessions and creates a case from a selected decision.
+- `ithrl shrink CASE` searches for context removals that preserve the selected behavior.
+- `ithrl fuzz CASE --config PRIVATE_TOML` searches for and simplifies text appends that decrease how
+  often the selected behavior occurs, with independent confirmation.
+
+For example, extract a saved session file:
+
+```bash
+ithrl extract path/to/session.jsonl --output .ithrl/case
+```
+
+Extraction makes no provider calls. Native experiments require Linux, usable Bubblewrap, an
+installed harness and model access. Review the provider, safety controls and call/time budget in the
+[native-run guide](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md) before execution.
+Returned actions are observed and denied. Cases contain copied session content; keep them private.
+
+## Supported inputs
+
+| Input | Extracted decisions | Reduction | Fuzzing |
+| --- | --- | --- | --- |
+| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner |
+| Codex CLI rollouts | Final responses | Experimental native runner | Experimental prior-user text appends |
+| Copilot CLI session events | Final responses and shell requests | Experimental final-response and denied `bash` runner | Experimental prior-user text appends for final-response targets |
+
+Native Codex and Copilot final-response fuzzing supports appending text to eligible prior user
+input while preserving the fixed triggering input. The
+[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#context-fuzzing)
+starts with a local example and covers native execution.
+
+[Saved-session measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
+include a confirmed reduction for one Codex session and its chosen predicate: 50.17% lower mean
+input tokens per confirmation observation, using a 20-percentage-point preservation margin.
+The measurements report resource usage and unsuccessful outcomes alongside completed runs. Check
+[native compatibility](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#compatibility-and-measurements)
+for the installed harness's requirements.
+
+## Documentation
+
+Read the [documentation site](https://eberkut.github.io/ithrl/) or browse the guides below.
+
+- [Native runs](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md): session selection,
+  experiment configuration, preflight, model execution and measured resource usage.
+- [Results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md): saved files,
+  result interpretation, budgets, resume and sensitive data.
+- [Contributing](https://github.com/eberkut/ithrl/blob/main/CONTRIBUTING.md): issue-first
+  collaboration, checkout setup, checks and smoke tests.
+- [Roadmap](https://github.com/eberkut/ithrl/blob/main/ROADMAP.md): current priorities and planned
+  capabilities.
+- [Architecture](https://github.com/eberkut/ithrl/blob/main/docs/architecture.md): implementation
+  boundaries and decisions.
+- [Research](https://github.com/eberkut/ithrl/blob/main/docs/research/index.md): feasibility
+  studies, statistical methods and measurements.
+
+For help, bugs or proposals, see [Support](https://github.com/eberkut/ithrl/blob/main/SUPPORT.md).
+Report vulnerabilities through
+[private reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+
+## Name
+
+Pronounce `ithrl` as **Ithuriel**, the angel whose spear reveals Satan in disguise in Milton's
+[*Paradise Lost*](https://rpo.library.utoronto.ca/content/paradise-lost-book-iv-1674).
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/eberkut/ithrl/blob/main/LICENSE).

ithrl-0.2.0/README.md

@@ -0,0 +1,120 @@
+# ithrl
+
+[![PyPI](https://img.shields.io/pypi/v/ithrl.svg)](https://pypi.org/project/ithrl/)
+[![CI](https://github.com/eberkut/ithrl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/eberkut/ithrl/actions/workflows/ci.yml)
+
+`ithrl` turns saved Codex and GitHub Copilot sessions into debugging experiments. Search for a
+smaller context that preserves a chosen response or tool request, or a small text change that alters
+it.
+
+[Documentation](https://eberkut.github.io/ithrl/) · [Try it](#try-it) ·
+[Supported inputs](#supported-inputs)
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install ithrl
+```
+
+You can also install with `pipx install ithrl` or, in an existing virtual environment,
+`python -m pip install ithrl`. For context fuzzing, use `'ithrl[fuzz]'` in place of `ithrl` in
+the installation command.
+
+Tested on Python 3.12–3.14. Native runners require Linux. APIs and saved formats may change before
+1.0; keep your source sessions and record the version used for each case.
+
+## Try it
+
+The bundled deterministic example needs no account, agent installation or model access:
+
+```bash
+mkdir -m 700 ithrl-demo
+ithrl extract --example --output ithrl-demo/case
+ithrl shrink ithrl-demo/case --observation-store ithrl-demo/observations.sqlite
+```
+
+The result removes half the context items and confirms that the target is preserved. Output excerpt:
+
+```text
+Reduced and confirmed
+  context items   10 -> 5
+  original test   target observed
+  search          1-minimal; all valid single removals tested
+  confirmation    target preserved
+  observations    15
+  No network requests or provider calls. No actions executed.
+```
+
+Inspect the saved result in `ithrl-demo/case/results/`; the
+[results guide](https://github.com/eberkut/ithrl/blob/main/docs/results.md) explains its files.
+Use a new directory to repeat the example; extraction refuses to overwrite an existing case.
+
+## Commands
+
+- `ithrl extract` browses saved sessions and creates a case from a selected decision.
+- `ithrl shrink CASE` searches for context removals that preserve the selected behavior.
+- `ithrl fuzz CASE --config PRIVATE_TOML` searches for and simplifies text appends that decrease how
+  often the selected behavior occurs, with independent confirmation.
+
+For example, extract a saved session file:
+
+```bash
+ithrl extract path/to/session.jsonl --output .ithrl/case
+```
+
+Extraction makes no provider calls. Native experiments require Linux, usable Bubblewrap, an
+installed harness and model access. Review the provider, safety controls and call/time budget in the
+[native-run guide](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md) before execution.
+Returned actions are observed and denied. Cases contain copied session content; keep them private.
+
+## Supported inputs
+
+| Input | Extracted decisions | Reduction | Fuzzing |
+| --- | --- | --- | --- |
+| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner |
+| Codex CLI rollouts | Final responses | Experimental native runner | Experimental prior-user text appends |
+| Copilot CLI session events | Final responses and shell requests | Experimental final-response and denied `bash` runner | Experimental prior-user text appends for final-response targets |
+
+Native Codex and Copilot final-response fuzzing supports appending text to eligible prior user
+input while preserving the fixed triggering input. The
+[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#context-fuzzing)
+starts with a local example and covers native execution.
+
+[Saved-session measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
+include a confirmed reduction for one Codex session and its chosen predicate: 50.17% lower mean
+input tokens per confirmation observation, using a 20-percentage-point preservation margin.
+The measurements report resource usage and unsuccessful outcomes alongside completed runs. Check
+[native compatibility](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#compatibility-and-measurements)
+for the installed harness's requirements.
+
+## Documentation
+
+Read the [documentation site](https://eberkut.github.io/ithrl/) or browse the guides below.
+
+- [Native runs](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md): session selection,
+  experiment configuration, preflight, model execution and measured resource usage.
+- [Results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md): saved files,
+  result interpretation, budgets, resume and sensitive data.
+- [Contributing](https://github.com/eberkut/ithrl/blob/main/CONTRIBUTING.md): issue-first
+  collaboration, checkout setup, checks and smoke tests.
+- [Roadmap](https://github.com/eberkut/ithrl/blob/main/ROADMAP.md): current priorities and planned
+  capabilities.
+- [Architecture](https://github.com/eberkut/ithrl/blob/main/docs/architecture.md): implementation
+  boundaries and decisions.
+- [Research](https://github.com/eberkut/ithrl/blob/main/docs/research/index.md): feasibility
+  studies, statistical methods and measurements.
+
+For help, bugs or proposals, see [Support](https://github.com/eberkut/ithrl/blob/main/SUPPORT.md).
+Report vulnerabilities through
+[private reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+
+## Name
+
+Pronounce `ithrl` as **Ithuriel**, the angel whose spear reveals Satan in disguise in Milton's
+[*Paradise Lost*](https://rpo.library.utoronto.ca/content/paradise-lost-book-iv-1674).
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/eberkut/ithrl/blob/main/LICENSE).