recension 0.5.0__tar.gz

recension-0.5.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# Docs / examples build output (regenerated, never committed)
+site/
+docs/examples/generated/
+examples/output/
+
+# Run records written by the CLI / examples
+run_record.json
+optimized_prompt.txt
+
+# Internal build/spec/maintainer docs, kept local, not published (end-user markdown only)
+CLAUDE.md
+recension_PRD.md
+RELEASING.md
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

recension-0.5.0/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.5.0] - 2026-06-11
+
+Shareable audits and an ecosystem seam.
+
+### Added
+
+- `recension report <record.json> -o report.html` renders a run record into a single standalone HTML
+  audit page (inline CSS, no assets, no network): baseline and final scores, the locked test estimate
+  and overfit flag, every round's diagnosis and candidates with significance/guard/leakage detail, the
+  accepted diff, the per-slice breakdown, the token ledger, and the integrity status. New public
+  `render_report`.
+- A pluggable `Proposer` interface (`ReflectiveOptimizer(proposer=...)`) so candidate generation can be
+  supplied by an external optimizer (DSPy, GEPA, or your own) while recension keeps owning versioning,
+  held-out measurement, leakage detection, and the audit record. Ships `DefaultProposer` (the built-in
+  reflective loop) and `CallableProposer` (wrap plain functions). New "Bring your own optimizer" docs.
+
+## [0.4.0] - 2026-06-11
+
+Multi-dimensional evaluation: one number hides regressions. All additions are opt-in.
+
+### Added
+
+- Per-slice reporting: set `slice_by` to an `Example.metadata` key and the record carries per-subgroup
+  baseline-vs-final scores (`SliceScore`), so a run that improves overall while regressing a segment is
+  visible. `slice_tolerance` controls when a slice is announced as regressed.
+- Guarded acceptance: `guards=[...]` of secondary objectives that must not regress. A candidate that
+  improves the primary metric but lowers a guard beyond `guard_tolerance` is rejected, with the
+  incumbent-vs-candidate guard scores recorded (`GuardScore`). Ships the `MaxLength` guard objective.
+- Cost ledger: an optional model-usage capability (`SupportsUsage` / `TokenUsage`). `MockModel` reports
+  synthetic deterministic counts; `AnthropicModel` reads `response.usage`. The record carries per-round
+  and total input/output tokens. Models without usage report zeros.
+- CLI config keys: `slice_by`, `slice_tolerance`, `guards`, `guard_tolerance`.
+
+## [0.3.0] - 2026-06-11
+
+Prompts as tested, tamper-evident artifacts.
+
+### Added
+
+- `recension check`: a prompt regression guard for CI. Scores the current artifact against a baseline
+  (a prior record's score or a literal) on the validation or test split and exits non-zero on a
+  regression, so a prompt change that hurts your eval set fails the build. Backed by the new public
+  `score_artifact` helper. Docs include a GitHub Actions recipe.
+- Tamper-evident records: `RunRecord.verify()` checks the embedded artifact's content-addressed
+  version chain (catching edited text/ids with no external reference), `RunRecord.fingerprint()` is a
+  deterministic content hash, and `sign()` / `verify_signature()` add optional HMAC signing
+  (`RECENSION_SIGNING_KEY`). New `recension verify` command; `recension show` prints an integrity line.
+  `TextArtifact.verify()` exposes the version-chain check directly.
+
+## [0.2.0] - 2026-06-10
+
+Honest measurement. Both additions are opt-in; 0.1.0 code is unaffected.
+
+### Added
+
+- Optional locked `test` split on `EvalSet` (records with `split: "test"`). The optimizer scores the
+  final incumbent on it exactly once and records `final_test_score`, the `validation`/`test` gap, and
+  a `validation_overfit` flag when the gap exceeds `overfit_gap` (default 0.1). This gives an unbiased
+  final estimate that the repeated selection on `validation` cannot.
+- Significance-based acceptance (`accept_significant`, with `alpha` and `bootstrap_resamples`). When
+  on, a candidate is accepted only if its validation gain is statistically significant (a seeded
+  paired-bootstrap confidence interval excluding 0), not merely above `min_improvement`. The bootstrap
+  is recorded on the round's best candidate. New stdlib-only `recension.stats` module; new
+  `SignificanceRecord`.
+- CLI config keys for the above (`accept_significant`, `alpha`, `bootstrap_resamples`, `overfit_gap`)
+  and a `test` split in `examples/cli/`.
+
+## [0.1.0] - 2026-06-10
+
+Initial release.
+
+### Added
+
+- `TextArtifact`: versioned text with content-addressed version ids, unified
+  diffs (stdlib `difflib`), append-only rollback, and full `Provenance` on
+  every accepted version (diagnosis, scores, rejected sibling candidates, diff).
+- `EvalSet` / `Example` with an enforced train/validation split; loaders
+  `from_records` and `from_jsonl`. Split-integrity violations raise
+  `DegenerateEvalError`.
+- Objectives: `ExactMatch`, token-level `F1`, and model-graded `LLMJudge`
+  (flagged as model-graded in run records).
+- `ReflectiveOptimizer`: the propose/test/accept loop, with failures diagnosed on
+  train, distinct candidates generated and scored on validation, acceptance
+  gated on `min_improvement` plus leakage checks.
+- `Budget`: caller-controlled candidates per round, rounds, diagnosis depth,
+  and a hard `max_model_calls` ceiling (`BudgetExceeded` carries the partial
+  audit record).
+- Leakage heuristics: verbatim validation spans and implausible
+  validation-vs-train gains; surfaced as flags, or raised via strict mode.
+- `RunRecord` / `RoundRecord` / `CandidateRecord`: a complete, serializable
+  audit record of every run, with the full artifact embedded.
+- Model layer: provider-agnostic `Model` protocol, deterministic `MockModel`
+  (the entire test suite runs offline), and an optional Anthropic backend
+  (`recension[anthropic]`; API key from the environment only).
+- CLI: `recension run --config run.yaml`, `recension show`, `recension diff`.
+- Three reproducible worked examples and a docs site (MkDocs + API reference)
+  with pages regenerated from real offline runs.

recension-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Nyström
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recension-0.5.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: recension
+Version: 0.5.0
+Summary: Measured optimization of the text layer around a language model: versioned artifacts, held-out evaluation, leakage detection, and a complete audit record.
+Project-URL: Homepage, https://github.com/AnthonyNystrom/recension
+Project-URL: Documentation, https://anthonynystrom.github.io/recension/
+Project-URL: Repository, https://github.com/AnthonyNystrom/recension
+Project-URL: Changelog, https://github.com/AnthonyNystrom/recension/blob/main/CHANGELOG.md
+Author-email: Anthony Nyström <nystrom.anthony@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: auditability,evaluation,llm,prompt-optimization,provenance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Provides-Extra: webapp
+Requires-Dist: flask>=3.0; extra == 'webapp'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/recension-logo-dark.svg">
+    <img src="docs/assets/recension-logo.svg" alt="recension" width="340">
+  </picture>
+</p>
+
+# recension
+
+Measured optimization of the text layer around a language model (prompts, context templates, skill and instruction files) with the rigor normally reserved for weight training: a held-out objective, a baseline, versioned artifacts, and a complete audit trail.
+
+The name comes from textual criticism. A *recension* is the revision of a text by collating variant readings and keeping the best-supported one. That is the loop this library runs: propose multiple candidate edits, test each against held-out evidence, commit only what measurably improves, and record why.
+
+## Why
+
+The usual way to improve a prompt is to edit it, eyeball a few outputs, and ship. There is no held-out measurement, no record of why a change was made, and no defense against overfitting to the handful of cases you inspected. `recension` replaces that loop with a measured one:
+
+- **No edit is accepted without a held-out score that beats the incumbent.** Failures are diagnosed on a train split; acceptance happens only on a validation split, and can require the gain to be *statistically significant* rather than above an epsilon. An optional locked test split gives an unbiased final estimate.
+- **Every accepted version carries provenance**: the failures that motivated it, the diagnosis, every sibling candidate considered (with scores), and the diff. A reviewer who didn't run the optimization can reconstruct every decision.
+- **One number doesn't hide regressions.** Optional per-slice scores, non-regression guard objectives, and a token-cost ledger surface what an aggregate averages away.
+- **Leakage is checked, not assumed away.** Heuristics flag candidates that embed validation content or show implausible validation gains.
+- **Records are built to be acted on.** Gate a prompt in CI with `recension check`, detect tampering with `recension verify`, and share a standalone HTML audit with `recension report`.
+- **Compute is a dial.** Candidates per round, rounds, diagnosis depth, and a hard ceiling on model calls are all caller-controlled.
+
+## Real-world use cases
+
+- **Production classification and extraction** (support-ticket triage, invoice fields, moderation): improve a labeling prompt on labeled data with measured, regression-safe edits.
+- **RAG context templates**: tune how retrieved chunks are assembled into the prompt with the model held fixed, so the metric move is attributable to the text.
+- **Agent and skill instructions**: optimize longer instruction files judged by an `LLMJudge` rubric when there is no gold answer.
+- **Governance and audit**: ship a replayable, tamper-evident `RunRecord` for every prompt change; gate merges in CI with `recension check`, and hand reviewers a standalone HTML audit with `recension report`.
+
+Full write-ups, plus a "how it works" walkthrough, are on the [documentation site](https://anthonynystrom.github.io/recension/).
+
+## Prior art, honestly
+
+DSPy and GEPA own the optimization mechanics this library's `ReflectiveOptimizer` performs; if you want state-of-the-art prompt optimization algorithms, look there. `recension`'s contribution is the **measurement and governance shell** around a text artifact: versioned artifacts with provenance, leakage detection, the complete audit record, and budgeted update-time compute. That delegation is a real seam, not a promise: the `Proposer` protocol lets an external engine supply the candidate edits while recension keeps owning the artifact, the measurement, and the record (see the [Bring your own optimizer](https://anthonynystrom.github.io/recension/ecosystem/) guide).
+
+## Install
+
+```bash
+pip install recension              # core: zero provider dependencies
+pip install "recension[anthropic]" # adds the Anthropic backend
+```
+
+Python 3.12+. The core (and the whole test suite) runs against a deterministic `MockModel` with no API key and no network.
+
+## Quickstart
+
+```python
+from recension import (
+    Budget, EvalSet, ExactMatch, MockModel, ReflectiveOptimizer, TextArtifact,
+)
+
+artifact = TextArtifact.from_text("Label the sentiment of the message.")
+
+# Held-out examples, split into train (for diagnosis) and validation (for
+# acceptance). Load from a JSONL file with EvalSet.from_jsonl(path) instead.
+evalset = EvalSet.from_records([
+    {"id": "t1", "input": "Absolutely love this", "expected": "positive", "split": "train"},
+    {"id": "t2", "input": "Broke after a day", "expected": "negative", "split": "train"},
+    {"id": "v1", "input": "Terrible support", "expected": "negative", "split": "validation"},
+    {"id": "v2", "input": "Exceeded expectations", "expected": "positive", "split": "validation"},
+])
+
+optimizer = ReflectiveOptimizer(
+    artifact=artifact,
+    evalset=evalset,
+    objective=ExactMatch(),
+    model=MockModel(),          # offline mock; see below for the real backend
+    budget=Budget(candidates_per_round=4, rounds=3, max_model_calls=200),
+    seed=7,
+)
+record = optimizer.run()
+
+print(record.summary())         # baseline → accepted versions → final score
+record.save("run_record.json")  # the complete audit artifact
+```
+
+To run against a real model, install the extra (`pip install "recension[anthropic]"`), set `ANTHROPIC_API_KEY` in your environment, and use the Anthropic backend:
+
+```python
+from recension.models.anthropic import AnthropicModel  # kept off the top-level import so the core needs no provider deps
+
+optimizer = ReflectiveOptimizer(..., model=AnthropicModel())
+```
+
+API keys are read from the environment only, never from code or config.
+
+## CLI
+
+```bash
+recension run --config run.yaml      # execute an optimization, write the record
+recension show run_record.json       # baseline, accepted diffs, score progression, integrity
+recension diff run_record.json vA vB # diff between two artifact versions
+recension check --config run.yaml --baseline run_record.json  # CI guard: exit non-zero on regression
+recension verify run_record.json     # detect tampering (content-addressed version chain)
+recension report run_record.json -o report.html  # standalone HTML audit page
+```
+
+A runnable, fully commented config and dataset live in [`examples/cli/`](examples/cli) (`recension run --config examples/cli/run.yaml`); the config schema and a GitHub Actions recipe for `recension check` are in the [CLI guide](https://anthonynystrom.github.io/recension/cli/).
+
+## Documentation
+
+Full docs, API reference, and three worked examples (each reproducible offline against `MockModel`): **https://anthonynystrom.github.io/recension/**
+
+## License
+
+MIT

recension-0.5.0/README.md

@@ -0,0 +1,108 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/recension-logo-dark.svg">
+    <img src="docs/assets/recension-logo.svg" alt="recension" width="340">
+  </picture>
+</p>
+
+# recension
+
+Measured optimization of the text layer around a language model (prompts, context templates, skill and instruction files) with the rigor normally reserved for weight training: a held-out objective, a baseline, versioned artifacts, and a complete audit trail.
+
+The name comes from textual criticism. A *recension* is the revision of a text by collating variant readings and keeping the best-supported one. That is the loop this library runs: propose multiple candidate edits, test each against held-out evidence, commit only what measurably improves, and record why.
+
+## Why
+
+The usual way to improve a prompt is to edit it, eyeball a few outputs, and ship. There is no held-out measurement, no record of why a change was made, and no defense against overfitting to the handful of cases you inspected. `recension` replaces that loop with a measured one:
+
+- **No edit is accepted without a held-out score that beats the incumbent.** Failures are diagnosed on a train split; acceptance happens only on a validation split, and can require the gain to be *statistically significant* rather than above an epsilon. An optional locked test split gives an unbiased final estimate.
+- **Every accepted version carries provenance**: the failures that motivated it, the diagnosis, every sibling candidate considered (with scores), and the diff. A reviewer who didn't run the optimization can reconstruct every decision.
+- **One number doesn't hide regressions.** Optional per-slice scores, non-regression guard objectives, and a token-cost ledger surface what an aggregate averages away.
+- **Leakage is checked, not assumed away.** Heuristics flag candidates that embed validation content or show implausible validation gains.
+- **Records are built to be acted on.** Gate a prompt in CI with `recension check`, detect tampering with `recension verify`, and share a standalone HTML audit with `recension report`.
+- **Compute is a dial.** Candidates per round, rounds, diagnosis depth, and a hard ceiling on model calls are all caller-controlled.
+
+## Real-world use cases
+
+- **Production classification and extraction** (support-ticket triage, invoice fields, moderation): improve a labeling prompt on labeled data with measured, regression-safe edits.
+- **RAG context templates**: tune how retrieved chunks are assembled into the prompt with the model held fixed, so the metric move is attributable to the text.
+- **Agent and skill instructions**: optimize longer instruction files judged by an `LLMJudge` rubric when there is no gold answer.
+- **Governance and audit**: ship a replayable, tamper-evident `RunRecord` for every prompt change; gate merges in CI with `recension check`, and hand reviewers a standalone HTML audit with `recension report`.
+
+Full write-ups, plus a "how it works" walkthrough, are on the [documentation site](https://anthonynystrom.github.io/recension/).
+
+## Prior art, honestly
+
+DSPy and GEPA own the optimization mechanics this library's `ReflectiveOptimizer` performs; if you want state-of-the-art prompt optimization algorithms, look there. `recension`'s contribution is the **measurement and governance shell** around a text artifact: versioned artifacts with provenance, leakage detection, the complete audit record, and budgeted update-time compute. That delegation is a real seam, not a promise: the `Proposer` protocol lets an external engine supply the candidate edits while recension keeps owning the artifact, the measurement, and the record (see the [Bring your own optimizer](https://anthonynystrom.github.io/recension/ecosystem/) guide).
+
+## Install
+
+```bash
+pip install recension              # core: zero provider dependencies
+pip install "recension[anthropic]" # adds the Anthropic backend
+```
+
+Python 3.12+. The core (and the whole test suite) runs against a deterministic `MockModel` with no API key and no network.
+
+## Quickstart
+
+```python
+from recension import (
+    Budget, EvalSet, ExactMatch, MockModel, ReflectiveOptimizer, TextArtifact,
+)
+
+artifact = TextArtifact.from_text("Label the sentiment of the message.")
+
+# Held-out examples, split into train (for diagnosis) and validation (for
+# acceptance). Load from a JSONL file with EvalSet.from_jsonl(path) instead.
+evalset = EvalSet.from_records([
+    {"id": "t1", "input": "Absolutely love this", "expected": "positive", "split": "train"},
+    {"id": "t2", "input": "Broke after a day", "expected": "negative", "split": "train"},
+    {"id": "v1", "input": "Terrible support", "expected": "negative", "split": "validation"},
+    {"id": "v2", "input": "Exceeded expectations", "expected": "positive", "split": "validation"},
+])
+
+optimizer = ReflectiveOptimizer(
+    artifact=artifact,
+    evalset=evalset,
+    objective=ExactMatch(),
+    model=MockModel(),          # offline mock; see below for the real backend
+    budget=Budget(candidates_per_round=4, rounds=3, max_model_calls=200),
+    seed=7,
+)
+record = optimizer.run()
+
+print(record.summary())         # baseline → accepted versions → final score
+record.save("run_record.json")  # the complete audit artifact
+```
+
+To run against a real model, install the extra (`pip install "recension[anthropic]"`), set `ANTHROPIC_API_KEY` in your environment, and use the Anthropic backend:
+
+```python
+from recension.models.anthropic import AnthropicModel  # kept off the top-level import so the core needs no provider deps
+
+optimizer = ReflectiveOptimizer(..., model=AnthropicModel())
+```
+
+API keys are read from the environment only, never from code or config.
+
+## CLI
+
+```bash
+recension run --config run.yaml      # execute an optimization, write the record
+recension show run_record.json       # baseline, accepted diffs, score progression, integrity
+recension diff run_record.json vA vB # diff between two artifact versions
+recension check --config run.yaml --baseline run_record.json  # CI guard: exit non-zero on regression
+recension verify run_record.json     # detect tampering (content-addressed version chain)
+recension report run_record.json -o report.html  # standalone HTML audit page
+```
+
+A runnable, fully commented config and dataset live in [`examples/cli/`](examples/cli) (`recension run --config examples/cli/run.yaml`); the config schema and a GitHub Actions recipe for `recension check` are in the [CLI guide](https://anthonynystrom.github.io/recension/cli/).
+
+## Documentation
+
+Full docs, API reference, and three worked examples (each reproducible offline against `MockModel`): **https://anthonynystrom.github.io/recension/**
+
+## License
+
+MIT

recension-0.5.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "recension"
+version = "0.5.0"
+description = "Measured optimization of the text layer around a language model: versioned artifacts, held-out evaluation, leakage detection, and a complete audit record."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Anthony Nyström", email = "nystrom.anthony@gmail.com" }]
+keywords = ["prompt-optimization", "llm", "evaluation", "provenance", "auditability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# DESIGN NOTE: PyYAML is the single runtime dependency, required only because the
+# PRD specifies YAML config files for the CLI. Everything else is stdlib.
+dependencies = ["pyyaml>=6.0"]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40"]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.13",
+    "ruff>=0.8",
+    "build>=1.2",
+    "twine>=5.0",
+    "types-PyYAML",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
+# DESIGN NOTE: Flask powers only the optional `examples/webapp` live demo; it is
+# never imported by the library, so it stays out of the core and docs groups.
+webapp = ["flask>=3.0"]
+
+[project.scripts]
+recension = "recension.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/AnthonyNystrom/recension"
+Documentation = "https://anthonynystrom.github.io/recension/"
+Repository = "https://github.com/AnthonyNystrom/recension"
+Changelog = "https://github.com/AnthonyNystrom/recension/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["recension"]
+
+[tool.hatch.build.targets.sdist]
+include = ["recension", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+files = ["recension", "tests"]
+
+[[tool.mypy.overrides]]
+module = "anthropic.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

recension-0.5.0/recension/__init__.py

@@ -0,0 +1,74 @@
+"""recension: measured optimization of the text layer around a language model.
+
+Versioned artifacts with provenance, held-out evaluation, leakage detection,
+and a complete audit record. See the README for the prior-art boundary:
+optimization mechanics are well covered by DSPy and GEPA; recension's
+contribution is the measurement-and-governance shell around a text artifact.
+"""
+
+from __future__ import annotations
+
+from .artifact import Provenance, RejectedCandidate, TextArtifact, Version
+from .budget import Budget
+from .evalset import EvalSet, Example
+from .exceptions import (
+    ArtifactError,
+    BudgetExceeded,
+    ConfigError,
+    DegenerateEvalError,
+    LeakageDetected,
+    RecensionError,
+)
+from .models import Message, MockModel, Model
+from .objective import F1, ExactMatch, LLMJudge, MaxLength, Objective
+from .optimizer import ReflectiveOptimizer, score_artifact
+from .proposer import CallableProposer, DefaultProposer, FailureCase, Proposer
+from .record import (
+    CandidateRecord,
+    GuardScore,
+    RoundRecord,
+    RunRecord,
+    SignificanceRecord,
+    SliceScore,
+)
+from .report import render_report
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "ArtifactError",
+    "Budget",
+    "BudgetExceeded",
+    "CallableProposer",
+    "CandidateRecord",
+    "ConfigError",
+    "DefaultProposer",
+    "DegenerateEvalError",
+    "EvalSet",
+    "ExactMatch",
+    "Example",
+    "F1",
+    "FailureCase",
+    "GuardScore",
+    "LLMJudge",
+    "MaxLength",
+    "LeakageDetected",
+    "Message",
+    "MockModel",
+    "Model",
+    "Objective",
+    "Proposer",
+    "Provenance",
+    "RecensionError",
+    "ReflectiveOptimizer",
+    "RejectedCandidate",
+    "RoundRecord",
+    "RunRecord",
+    "SignificanceRecord",
+    "SliceScore",
+    "TextArtifact",
+    "render_report",
+    "score_artifact",
+    "Version",
+    "__version__",
+]