underwrite 0.1.0__tar.gz → 0.1.1__tar.gz

{underwrite-0.1.0 → underwrite-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: underwrite
-Version: 0.1.0
+Version: 0.1.1
 Summary: Local evidence normalization, measurement, and acceptance checks
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-<h1><img src="assets/brand/underwrite-logo.png" alt="underwrite" width="640"></h1>
+<h1><img src="https://raw.githubusercontent.com/ntts9990/underwrite/main/assets/brand/underwrite-logo.png" alt="underwrite" width="640"></h1>
 
 ### Know what your eval files actually support.
 
@@ -26,11 +26,11 @@ Find mismatches. Keep missing evidence visible. Know what to check next.
 [![CI](https://github.com/ntts9990/underwrite/actions/workflows/ci.yml/badge.svg)](https://github.com/ntts9990/underwrite/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/underwrite)](https://pypi.org/project/underwrite/)
 [![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-blue)](https://pypi.org/project/underwrite/)
-[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/ntts9990/underwrite/blob/main/LICENSE)
 
 **[Try it](#quickstart)** · [Use with an agent](#agent-use) · [Supported formats](#supported-formats) · [Docs](#documentation)
 
-**English** · [한국어](README.ko.md)
+**English** · [한국어](https://github.com/ntts9990/underwrite/blob/main/README.ko.md)
 
 </div>
 
@@ -50,29 +50,35 @@ quality score. No Docker, dashboard, or provider credentials are needed to
 inspect the supported local files.
 
 > [!NOTE]
-> **This README describes the `0.1.0` source tree and matching wheels.** The older
-> PyPI `0.0.1` lacks these workflows; use the source quickstart or matching
-> `0.1.0` app/core wheels. The older build's `pins refresh` needs a separate
-> caution; see [Published installation](#install).
+> **This guide targets `underwrite==0.1.1`.** Its CLI and Python workflows work
+> without a checkout. The older `0.0.1` artifacts lack these workflows and have
+> a separate `pins refresh` caution; see [Install](#install).
 
 ## Quickstart
 
-Requires **Python 3.12+** and [uv](https://docs.astral.sh/uv/).
-This checkout is tested with CPython 3.12 on Linux and macOS. File-based CLI
-workflows require Unix/POSIX file APIs, including ordinary artifact reads.
+Requires **Python 3.12+** and [uv](https://docs.astral.sh/uv/); the optional
+synthetic download below uses `curl`.
+File-based CLI workflows are tested with CPython 3.12 on Linux and macOS. They
+require Unix/POSIX file APIs, including for ordinary artifact reads.
 
-**1. Check the file.** Run a bundled synthetic example—no API key or adjacent
-repository required:
+**1. Install and check a file.** The app-only install resolves a compatible
+`underwrite-core` automatically. Download the public synthetic example; no
+checkout or API key is needed:
 
 ```sh
-git clone https://github.com/ntts9990/underwrite.git
-cd underwrite
-uv sync --frozen --all-groups
-
-uv run --frozen --no-sync underwrite audit-promptfoo \
-  fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json --json
+uv tool install 'underwrite==0.1.1'
+underwrite capabilities --json
+example_dir=$(mktemp -d)
+curl -fsSLo "$example_dir/promptfoo.json" \
+  https://raw.githubusercontent.com/ntts9990/underwrite/cb913d39bce628b93dcd3b06fcc4ce36f9dc66af/fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json
+underwrite audit-promptfoo "$example_dir/promptfoo.json" \
+  --version 0.123.0 --json
 ```
 
+The same `uv tool install` command updates an older uv-managed `underwrite`
+tool without `--force`. If your shell cannot find `underwrite`, run
+`uv tool update-shell` and open a new shell.
+
 **2. Read the finding.** The producer summary declares **3 results**, including
 **1 failure**; the file contains **2 rows**, with **0 failure rows**. The command
 reports the difference without guessing which side is wrong. Selected fields
@@ -104,12 +110,21 @@ explicit. Exit `0` means the report was produced, not that the counts agree or
 the source's verdict was verified. To keep the input and analysis together,
 [save them in a local record](#keep-results-you-can-return-to).
 
+For your own completed Promptfoo export, replace the example path and select its
+supported source version. The synthetic download above is a constructed example,
+not an unchanged producer export.
+
 <details>
 <summary><strong>Try the native measurement → acceptance workflow</strong></summary>
 
-From the same checkout, run the included synthetic binary-event example:
+This example uses policies and fixtures in the GitHub checkout; they are not
+included in the installed package. To run it, prepare a checkout first:
 
 ```sh
+git clone https://github.com/ntts9990/underwrite.git
+cd underwrite
+uv sync --frozen --all-groups
+
 mkdir -p output
 uv run --frozen --no-sync underwrite ingest \
   --format underwrite.evidence-bundle --version v1 \
@@ -131,7 +146,7 @@ This measures a synthetic binary-event proportion, not general quality or latenc
 The `read.v2` uses an explicit `measurement_policy.v3`; calibration diagnostics do
 not vote on its verdict. The final classification is `screened`, requires human
 review, and keeps `merge_authorized` false. Repeat `--read` for each required claim.
-See [measurement meaning](AGENT_USAGE.md#measurement-meaning-and-migration).
+See [measurement meaning](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#measurement-meaning-and-migration).
 
 </details>
 
@@ -165,12 +180,12 @@ inputs and results for later review.
 
 ## Agent use
 
-Give your coding agent the prepared checkout and an exported artifact. It can
+Give your coding agent the installed CLI and a completed local export. It can
 discover the available routes, execute them, and use the JSON in its response:
 
 ```sh
-uv run --frozen --no-sync underwrite --help
-uv run --frozen --no-sync underwrite capabilities --json
+underwrite --help
+underwrite capabilities --json
 ```
 
 Python callers can use
@@ -180,16 +195,17 @@ interpreting any producer-specific field.
 
 Example task for an agent with terminal access:
 
-> Read `skills/underwrite-review/SKILL.md` in this checkout. Review
-> `fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json` as a
-> Promptfoo 0.123.0 export. Use `capabilities --json` and `audit-promptfoo`.
+> Review `/absolute/path/to/completed-promptfoo-export.json` with the installed
+> `underwrite` 0.1.1 CLI as a Promptfoo 0.123.0 export. Use `capabilities --json`
+> and `audit-promptfoo --version 0.123.0`.
 > Report `declared_relation`, `producer_stats`, `row_tallies`, `raw_hash`,
 > `limitations`, and the next useful action. Do not rerun the producer or treat
 > exit `0` as agreement or approval.
 
-The optional [underwrite-review skill](skills/underwrite-review/SKILL.md) provides
-reusable guidance for Codex and Claude Code. [Setup and usage](AGENT_USAGE.md#optional-artifact-review-skill)
-are explicit: the skill does not install the CLI or add a background service.
+The optional [underwrite-review skill](https://github.com/ntts9990/underwrite/blob/main/skills/underwrite-review/SKILL.md) provides
+reusable guidance for Codex and Claude Code. [Setup and usage](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#optional-artifact-review-skill)
+are explicit: the skill lives in the repository, not the PyPI package, and does
+not install the CLI or add a background service.
 The same CLI and importable Python APIs are available to your own automation.
 
 ## Supported formats
@@ -199,23 +215,34 @@ export, or version offered by each producer. Select the version explicitly.
 
 | Your input | Supported profile | Start here |
 | --- | --- | --- |
-| **goppi** | Completed baseline exchange manifest v2; separate paired-handoff route | [`audit-baseline`](AGENT_USAGE.md#audit-a-completed-goppi-baseline-as-common-evidence) for descriptive common JSON · [`project-baseline`](AGENT_USAGE.md#project-a-completed-goppi-baseline-into-event-observations) for native measurement · [`review-handoff`](AGENT_USAGE.md#review-a-completed-paired-handoff-in-one-call) |
-| **Langfuse** | `4.35.0` server blob exports: observations-v2 and scores JSON arrays | [`audit-langfuse`](AGENT_USAGE.md#account-for-langfuse-score-kinds-and-associations), with an optional content-minimized row index |
-| **DeepEval** | Ordinary TestRun JSON, `4.1.1` or `4.2.8` | [`audit-deepeval`](AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors) |
-| **Promptfoo** | Eval output JSON, `0.123.0` or `0.124.1` | [`audit-promptfoo`](AGENT_USAGE.md#source-checkout-pilot-audit-promptfoo-counts) |
-| **External common result** | `evidence_result.v1` JSON from a producer | [`inspect-result`](AGENT_USAGE.md#inspect-an-external-common-result) for contract screening and availability counts, with optional evidence-item `next_action` and declared metric-binding counts |
+| **goppi** | Completed baseline exchange manifest v2; separate paired-handoff route | [`audit-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#audit-a-completed-goppi-baseline-as-common-evidence) for descriptive common JSON · [`project-baseline`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#project-a-completed-goppi-baseline-into-event-observations) for native measurement · [`review-handoff`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#review-a-completed-paired-handoff-in-one-call) |
+| **Langfuse** | `4.35.0` server blob exports: observations-v2 and scores JSON arrays | [`audit-langfuse`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-langfuse-score-kinds-and-associations), with an optional content-minimized row index |
+| **DeepEval** | Ordinary TestRun JSON, `4.1.1` or `4.2.8` | [`audit-deepeval`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors) |
+| **Promptfoo** | Eval output JSON, `0.123.0` or `0.124.1` | [`audit-promptfoo`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#source-checkout-pilot-audit-promptfoo-counts) |
+| **External common result** | `evidence_result.v1` JSON from a producer | [`inspect-result`](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#inspect-an-external-common-result) for contract screening and availability counts, with optional evidence-item `next_action` and declared metric-binding counts |
 | **Native evidence** | `underwrite.evidence-bundle` / `v1` | `ingest` → `measure` → `accept` |
 | **Inspect AI** | `inspect.eval-log` / `0.3.263` | `ingest` |
 | **OpenInference** | `openinference.traces` / `0.1.38` | `ingest` |
 | **OTLP JSON** | `otlp-json.traces` / `0.160.0` | `ingest` |
 
+For completed exports already on your machine, the installed CLI accepts them
+directly; select the exact producer profile you have:
+
+```sh
+underwrite audit-promptfoo /path/to/promptfoo-output.json --version 0.124.1 --json
+underwrite audit-deepeval /path/to/deepeval-test-run.json --version 4.2.8 --json
+underwrite audit-langfuse --observations /path/to/observations.json \
+  --scores /path/to/scores.json --json
+underwrite audit-baseline --exchange /path/to/goppi-baseline-exchange --json
+```
+
 DeepEval accounting defaults to `4.1.1`; select `--version 4.2.8` for that
 profile. For a reusable owner-asserted metric-name pack and common descriptive
-JSON, see the [DeepEval binding workflow](AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors).
+JSON, see the [DeepEval binding workflow](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#account-for-deepeval-scores-and-evaluator-errors).
 Promptfoo accounting defaults to `0.123.0`; select `--version 0.124.1`
 for that profile. Langfuse's version identifies the server export, not its SDK.
-See [artifact requirements](AGENT_USAGE.md#get-the-right-producer-artifact) and
-[producer checks](EVIDENCE_REVIEW.md) for the tested scope and fixture origins.
+See [artifact requirements](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#get-the-right-producer-artifact) and
+[producer checks](https://github.com/ntts9990/underwrite/blob/main/EVIDENCE_REVIEW.md) for the tested scope and fixture origins.
 
 Generic `ingest` / `project` normalizes supported exports to an observation;
 external observations do not enter the current `measure` path. goppi uses its
@@ -232,16 +259,14 @@ not executed tool calls or an agent trajectory.
 ## Keep results you can return to
 
 Use `records` when you want the analysis and its selected source bytes retained
-together. For example, after the source quickstart:
+together. For a completed local Promptfoo export:
 
 ```sh
-mkdir -p output
-uv run --frozen --no-sync underwrite records audit-promptfoo \
-  fixtures/examples/evidence/synthetic-promptfoo-count-mismatch.json \
-  --root output/review-store --id demo-001 --json
+underwrite records audit-promptfoo /path/to/promptfoo-output.json \
+  --version 0.123.0 --root ./review-store --id review-001 --json
 
-uv run --frozen --no-sync underwrite records read-json \
-  --root output/review-store --id demo-001 \
+underwrite records read-json \
+  --root ./review-store --id review-001 \
   --name analysis/accounting.json --json
 ```
 
@@ -251,11 +276,11 @@ measurement, and `records replay-measure` recalculates it from verified saved
 inputs using the current engine, without executing the original producer.
 For an exact completed goppi baseline v2 directory, `records audit-baseline`
 captures its five files and the descriptive result together in one call; see
-[the goppi record workflow](STORAGE.md#retain-a-completed-goppi-baseline).
+[the goppi record workflow](https://github.com/ntts9990/underwrite/blob/main/STORAGE.md#retain-a-completed-goppi-baseline).
 
 Records retain raw inputs, which may contain private content. Choose a private
-local POSIX filesystem and a backup strategy; this checkout's ignored `output/`
-is a demo location, not a backup. [Storage contracts and recovery](STORAGE.md).
+local POSIX filesystem and a backup strategy; `./review-store` is only an example
+location, not a backup. [Storage contracts and recovery](https://github.com/ntts9990/underwrite/blob/main/STORAGE.md).
 
 ## What the result means
 
@@ -274,19 +299,41 @@ probability, and a successful command is not approval to ship.
 
 ## Install
 
-For the workflows on this page, use the [source quickstart](#quickstart) or
-matching `0.1.0` app/core wheels. `uv sync` selects the workspace
-`underwrite-core`; locally built wheels must pair app and core from the same
-checkout.
-
-<details>
-<summary>Install the older published PyPI 0.0.1</summary>
+Install the versioned app; its dependency resolves the compatible core. Use
+`underwrite --help` and `underwrite capabilities --json` to see the installed
+profiles:
 
 ```sh
-uv tool install 'underwrite==0.0.1'
+uv tool install 'underwrite==0.1.1'
 underwrite --help
+underwrite capabilities --json
 ```
 
+The same `uv tool install` command updates an older uv-managed installation
+without `--force`. If the executable is not on `PATH`, run `uv tool update-shell`
+and open a new shell.
+
+For the importable Python API, install into a Python 3.12 environment instead:
+
+```sh
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python 'underwrite==0.1.1'
+.venv/bin/python - <<'PY'
+from pathlib import Path
+from underwrite.instrument.ingest.accounting import audit_promptfoo_file
+
+result = audit_promptfoo_file(Path("/path/to/promptfoo-output.json"), version="0.123.0")
+print(result["declared_relation"])
+PY
+```
+
+The installed distributions contain runtime code and schemas. The guide,
+synthetic fixtures, optional agent skill, and contributor tools live in the
+GitHub repository and require a checkout if you want to run those examples.
+
+<details>
+<summary>Historical 0.0.1 and its pin-manifest caution</summary>
+
 The older published [app](https://pypi.org/project/underwrite/0.0.1/) and
 [core](https://pypi.org/project/underwrite-core/0.0.1/) do not include the
 `0.1.0` measurement, accounting, records, handoff, or `capabilities` workflows.
@@ -309,7 +356,7 @@ Use `underwrite <command> --help` for options. Alongside the workflows above,
 a manifest with an expected hash, `check` examines release evidence linkage,
 `absence` checks population presence, `boundary scan` checks configured verdict
 vocabulary, and `drift check` / `pins refresh` work with supplied pin registries.
-[JSON contracts](contracts/) define each command family's results and errors.
+[JSON contracts](https://github.com/ntts9990/underwrite/tree/main/contracts/) define each command family's results and errors.
 
 Legacy `absence` and `drift check` exemption files and `boundary scan` allowlists
 are bounded to 1 MiB, 64 JSON container levels, and 1024 policy entries each.
@@ -356,21 +403,24 @@ budget, and checks the fully serialized 1 MiB manifest before its first write.
 
 ## Documentation
 
+These guides and examples are on GitHub, outside the runtime wheel. The installed
+package includes the schemas needed for its CLI and Python APIs.
+
 | Explore | Guide |
 | --- | --- |
-| Run from an agent, choose inputs, interpret JSON | [Agent usage](AGENT_USAGE.md) |
-| Compare declarations, paired evidence, and goppi handoffs | [Evidence workflows](AGENT_USAGE.md#source-checkout-pilot-compare-declarations) |
-| Save, verify, retrieve, and recalculate | [Local records](STORAGE.md) |
-| Understand producer fixtures and tested boundaries | [Producer evidence](EVIDENCE_REVIEW.md) |
-| Extend the CLI and pure calculation core | [Contributing](CONTRIBUTING.md) · [Architecture rules](AGENTS.md) |
+| Run from an agent, choose inputs, interpret JSON | [Agent usage](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md) |
+| Compare declarations, paired evidence, and goppi handoffs | [Evidence workflows](https://github.com/ntts9990/underwrite/blob/main/AGENT_USAGE.md#source-checkout-pilot-compare-declarations) |
+| Save, verify, retrieve, and recalculate | [Local records](https://github.com/ntts9990/underwrite/blob/main/STORAGE.md) |
+| Understand producer fixtures and tested boundaries | [Producer evidence](https://github.com/ntts9990/underwrite/blob/main/EVIDENCE_REVIEW.md) |
+| Extend the CLI and pure calculation core | [Contributing](https://github.com/ntts9990/underwrite/blob/main/CONTRIBUTING.md) · [Architecture rules](https://github.com/ntts9990/underwrite/blob/main/AGENTS.md) |
 
 ## Contributing
 
 Bring a reproducible artifact, a concrete workflow, or a fix.
 [Open an issue](https://github.com/ntts9990/underwrite/issues) with the producer
 version and expected result; share only sanitized examples. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for local preflight and PR checks, and
-[SECURITY.md](SECURITY.md) for private vulnerability reports.
+[CONTRIBUTING.md](https://github.com/ntts9990/underwrite/blob/main/CONTRIBUTING.md) for local preflight and PR checks, and
+[SECURITY.md](https://github.com/ntts9990/underwrite/blob/main/SECURITY.md) for private vulnerability reports.
 
 <details>
 <summary>Maintainers: future PyPI releases</summary>
@@ -392,5 +442,5 @@ and [PyPI Trusted Publisher guide](https://docs.pypi.org/trusted-publishers/usin
 
 ## License
 
-[Apache-2.0](LICENSE). [LICENSING.md](LICENSING.md) records the adapted policy
+[Apache-2.0](https://github.com/ntts9990/underwrite/blob/main/LICENSE). [LICENSING.md](https://github.com/ntts9990/underwrite/blob/main/LICENSING.md) records the adapted policy
 templates' CC licenses.