cvprofiles 2.0.0__tar.gz

cvprofiles-2.0.0/.env.example

@@ -0,0 +1,10 @@
+# cvprofiles environment variables
+# Core engine needs NO secrets. Frozen scores + YAML configs suffice.
+#
+# Optional upstream *scoring recipes* (outside the engine) may need keys later.
+# Never import optional scorer env vars from identify/report code paths.
+
+# Example placeholders only — not used by MVP engine:
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# HF_TOKEN=

cvprofiles-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: ci
+
+on:
+  push:
+    branches: [main, "feat/**"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync project (dev extras)
+        run: uv sync --extra dev
+
+      - name: Ruff (src + tests + tools)
+        run: uv run ruff check src tests tools
+
+      - name: Mypy (strict package check)
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest -q --tb=short
+
+      - name: CLI version smoke
+        run: |
+          uv run cvprofiles --version
+          uv run python -c "import cvprofiles; assert cvprofiles.__version__ == '1.1.0a1'"
+
+      - name: Editable install graph hygiene (no LLM / no museum import)
+        run: |
+          uv run python - <<'PY'
+          import ast
+          from pathlib import Path
+          forbidden = ("openai", "anthropic", "httpx", "requests", "litellm")
+          museum = ("v0_poc", "evals.synthetic")
+          bad = []
+          for p in Path("src/cvprofiles").rglob("*.py"):
+              tree = ast.parse(p.read_text(), filename=str(p))
+              for n in ast.walk(tree):
+                  if isinstance(n, ast.Import):
+                      for a in n.names:
+                          if any(a.name == f or a.name.startswith(f + ".") for f in forbidden):
+                              bad.append(f"{p}:{a.name}")
+                          if any(m in a.name for m in museum):
+                              bad.append(f"{p}:museum:{a.name}")
+                  elif isinstance(n, ast.ImportFrom):
+                      mod = n.module or ""
+                      if any(mod == f or mod.startswith(f + ".") for f in forbidden):
+                          bad.append(f"{p}:{mod}")
+                      if any(m in mod for m in museum):
+                          bad.append(f"{p}:museum:{mod}")
+          assert not bad, bad
+          assert Path("evals/synthetic/v0_poc.py").is_file()
+          print("import-graph ok; museum present")
+          PY
+
+      - name: Mini fixture SCORE→REPORT smoke
+        run: |
+          uv run cvprofiles run \
+            --scores data/fixtures/mini_v1/scores.csv \
+            --roles data/fixtures/mini_v1/roles.json \
+            --network data/fixtures/mini_v1/network.yaml \
+            --beta data/fixtures/mini_v1/beta.yaml \
+            --out /tmp/cvprofiles_ci_mini \
+            --seed 0
+          test -f /tmp/cvprofiles_ci_mini/report.html
+          test -f /tmp/cvprofiles_ci_mini/range.json
+          uv run python - <<'PY'
+          import json
+          from pathlib import Path
+          r = json.loads(Path("/tmp/cvprofiles_ci_mini/range.json").read_text())
+          a = json.loads(Path("/tmp/cvprofiles_ci_mini/admissible.json").read_text())
+          assert r["empty"] is False
+          assert "m_slop" not in a["M_star"]
+          assert set(a["M_star"]) == {"m_good", "m_weak"}
+          print("mini fixture smoke ok", a["M_star"], r["L"], r["U"])
+          PY
+
+  # Optional: only runs if sklearn available path wanted later; keep default CI lean.
+  # Realworld spam audit remains a branch eval (needs sklearn + 20newsgroups cache).

cvprofiles-2.0.0/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.dmypy.json
+dmypy.json
+
+# Virtual envs
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Project outputs (keep directory via .gitkeep)
+# Per-seed run dumps are local; proof summaries may be committed.
+reports/runs/*
+!reports/runs/.gitkeep
+# Ignore bulk under summaries except proof JSON + README
+reports/summaries/*
+!reports/summaries/.gitkeep
+!reports/summaries/README.md
+!reports/summaries/v0_1_poc_summary.json
+!reports/summaries/v1_0_package_synth_summary.json
+!reports/summaries/v1_1_package_synth_summary.json
+!reports/summaries/v1_1_protocol_synth_mc50_summary.json
+!reports/summaries/h5_trust_evidence_summary.json
+!reports/.gitkeep
+
+# Large local data (fixtures small enough to commit are OK under data/fixtures)
+data/synthetic/generated/
+*.parquet
+!data/fixtures/**/*.parquet
+
+# Secrets / local overrides
+*.pem
+credentials.json
+
+# Hermes / agent local
+.hermes/plans/
+
+# Real-world audit run dumps (keep data/ + proof JSON; regenerate runs)
+evals/realworld/**/runs_*/
+evals/realworld/**/*.parquet
+
+# H5 Trust: large local raw + aux caches (fetched/copied locally; frozen
+# scores.csv + manifest are committed under evals/h5_trust/data/)
+data/h5_trust_raw/
+data/h5_trust_aux/
+evals/h5_trust/runs_verify/

cvprofiles-2.0.0/AGENTS.md

@@ -0,0 +1,112 @@
+# cvprofiles — Agent Handoff Contract
+
+## Mission
+
+`cvprofiles` is an open academic methods package for **construct-validity profiles**: partial identification over a finite, researcher-supplied menu of measurement functions. It is not a scorer product, an LLM application, an automated theory-authoring system, or a generic causal-sensitivity package.
+
+The package state machine is:
+
+```text
+SCORE → RESTRICT → IDENTIFY → REPORT
+```
+
+- **SCORE:** ingest and validate user-supplied unit×measure scores. Do not generate measures.
+- **RESTRICT:** bind a researcher-authored nomological network and target functional.
+- **IDENTIFY:** compute slacks, the admissible set `M*`, and the headline range `[L,U]`.
+- **REPORT:** produce JSON/HTML audit artifacts a non-coder can inspect.
+
+## Non-negotiable scientific and package locks
+
+- The engine is **score-agnostic and model-free**. No LLM client belongs in the package/import graph.
+- The menu is finite and researcher supplied. Prompt search and measurement generation are upstream workflows, not engine features.
+- The headline range is the image of beta on **survivors only**: `[L,U] = [min B*, max B*]`. Rejected measures may be diagnostic but never enter the range.
+- Empty `M*` and wide ranges are valid scientific outputs. Never automatically loosen thresholds to avoid an empty set.
+- Bootstrap and theta-grid are additive diagnostics. The headline range remains unchanged; theta-grid settings are excluded from the freeze preimage.
+- Paper-relevant numbers require frozen scores, pinned network/beta, fixed seed, package version, and the locked freeze/run-id contract.
+- The annotated `v0.1` tag is immovable and must continue to peel to `fb62b48bcb704f60eee7d6641ed0a344eb72bfda`.
+- `evals/synthetic/v0_poc.py` is a historical museum artifact. Keep it present and **unimported** from `src/`.
+
+## Authority and scope
+
+Augusto owns all main-path empirical/paper choices:
+
+- construct definition, unit/universe, score matrix and scoring protocol, and measurement menu;
+- empirical nomological network `R`, anchors, directions, thresholds, tolerance policy, and beta choice;
+- paper claims, reporting placement, H5/public-baseline choice, release posture, tag, and PyPI publication.
+
+Agents may author oracle networks only for synthetic DGPs. Do not invent an empirical network to make H5 or a paper table move. The existing spam audit is intermediate stress evidence, **not H5**.
+
+The current paper protocol (`docs/16_Paper_Protocol_Freeze.md`) is **LOCKED AS PROVISIONAL SYNTHETIC-ONLY**. It does not authorize empirical/H5 work, engine changes, pushes, tags, PyPI publication, or a release claim by implication. A dated amendment (`docs/16` §8, 2026-08-04) opens the empirical box **for the designated H5 Trust evaluation only**; its first frozen run (n=35) is **preliminary paper-facing evidence** (`reports/summaries/h5_trust_evidence_summary.json`) — a checkpoint, not a release. Final paper lock, tag, and PyPI remain Augusto's.
+
+## Current posture
+
+- Package version: `2.0.0` (v2.0 release; PyPI publication in progress).
+- v1.1 inference layer shipped and **tagged `v1.1.0`** (2026-08-04, `fce31c8`); PyPI release pending.
+- **v2.0 measure discipline ENTRY COMPLETE** (`docs/18_Measure_Discipline_Plan.md`): δ-grid, evaluator growth (`mean_order`/`rank_agree`/`ols_coef`), θ-anchor artifacts all shipped (2026-08-05); DONE phase in progress (publication authorized, tutorial pending).
+- `reports/summaries/v1_1_package_synth_summary.json` is package smoke evidence (seeds `0..4`).
+- `reports/summaries/v1_1_protocol_synth_mc50_summary.json` is a distinct provisional synthetic-only MC50 proof artifact (seeds `0..49`). It is not H5 or a full empirical paper lock.
+- `reports/runs/` contains reproducible bulk outputs and is ignored. Allow-listed proof summaries under `reports/summaries/` are tracked.
+- Intermediate real-world audits live under `evals/realworld/` (`spam_validity` text; `calhousing_validity` tabular). Both are **intermediate / not H5**; their READMEs record capability boundaries (no LLM calls in the engine, no missingness imputation, descriptive correlations only). Do not cite them as paper evidence.
+
+## Where truth lives
+
+| Source | Use |
+|---|---|
+| `README.md` | Orientation, scope, current package posture |
+| `docs/PROJECT_MANIFEST.md` | Machine-readable project state and locks |
+| `docs/12_Decision_Engineering_Log.md` | Append-only engineering/scope decisions |
+| `docs/13_Evaluations_Log.md` | Evidence interpretations and artifact pointers |
+| `docs/15_MVP_Release_Checklist.md` | Release-review input; not release authority |
+| `docs/16_Paper_Protocol_Freeze.md` | Paper-facing locks, open fields, and provenance rule |
+| `docs/17_H5_Trust_Design.md` | H5 Trust design lock (run gated) |
+| `docs/18_Measure_Discipline_Plan.md` | v2.0 scope box: δ-grid, evaluator growth, θ-anchor discipline |
+| `pyproject.toml` | Package version, dependencies, lint/type/test configuration |
+| `.github/workflows/ci.yml` | CI contract |
+| `.gitignore` | Tracked proofs versus ignored run output |
+
+If code and current policy documentation disagree, stop and surface the conflict; do not silently make code, docs, or theory conform.
+
+## Working conventions
+
+1. Read the relevant source, tests, and current decision/protocol docs before changing code.
+2. Use strict TDD for behavioral source changes: write a focused test, observe RED, implement minimally, observe GREEN, then run the relevant module and full suite.
+3. Keep implementation thin and observable. Do not add infrastructure, optional frameworks, or generic extension systems without a fixture and an explicit decision.
+4. For docs/logs, preserve history: append a dated reversal or close-out rather than rewriting a prior decision.
+5. Never commit ignored bulk run output. Verify proof-summary allow-lists before adding generated JSON.
+6. Do not push, tag, publish, rewrite history, or modify `v0.1` without a task-specific explicit user decision.
+
+## Commands
+
+Bootstrap development dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Run the local quality battery:
+
+```bash
+uv run ruff check src tests tools
+uv run mypy src
+uv run pytest -q --tb=short
+uv run cvprofiles --version
+git diff --check
+git rev-parse 'v0.1^{}'
+```
+
+For CLI changes, preserve the contract: stdout is machine-readable JSON; human status messages belong on stderr. Empty `M*` is an exit-0 success path.
+
+Before a commit, inspect `git status -sb`, the diff, and relevant on-disk artifacts. Report measured outputs, not remembered numbers.
+
+## Explicit non-goals unless a dated decision reopens them
+
+- foundation-model training;
+- new annotation campaigns as the main route;
+- SAE/hypothesis-generation core;
+- full PPI/MARS reimplementation;
+- agent-based-model/SCA product work as the spine;
+- proprietary APIs for paper-reproducible work;
+- GUI/SaaS/heavy infrastructure;
+- “automate all empirical economics.”
+
+When in doubt, favor a small, auditable artifact over a clever abstraction. The point is disciplined measurement, not an elaborate machine for avoiding decisions.

cvprofiles-2.0.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable project milestones live here. Detailed decisions → `docs/12_Decision_Engineering_Log.md`. Eval learnings → `docs/13_Evaluations_Log.md`.
+
+Format: keep newest first.
+
+## [1.1.0] — 2026-08-04 (MVP tag `v1.1.0`; PyPI publication separate)
+
+### Engine — v1.1 inference layer (shipped on `main` as dev `1.1.0a1`)
+
+- Bootstrap over observational units (percentile band over non-empty replicates; empty/degenerate counts reported) — **M6 inference layer**
+- Deterministic θ-grid sensitivity surface (diagnostic; λ scales threshold magnitudes only; headline stays λ=1.0; grid excluded from freeze preimage)
+- Additive pipeline, CLI (`--n-boot`, `--theta-grid`), JSON/HTML audit panels, and stale-layer cleanup
+- Package-native battery and inference evidence: `reports/summaries/v1_1_package_synth_summary.json`
+- MVP release checklist: `docs/15_MVP_Release_Checklist.md` (feeds release-review chat)
+- Verification close-out: local ruff clean, 121 tests passed, version smoke and tag checks passed; GitHub Actions green confirmed by Augusto; no tag or PyPI publication attempted
+- PyPI name availability checked (HTTP 404); publication decision remains open and is **not** part of v1.1
+- Independent MC50 proof audit: `tools/verify_v11_protocol_synth_mc50.py` + `tests/test_v11_protocol_synth_mc50_audit.py` validate the provisional synthetic-only protocol table in a read-only pass
+- Strict typing enforcement: `uv run mypy src` is green and enforced in CI; `ruff` now also lints `tools/` in CI
+- Protocol/release documentation reconciliation: README/manifest/open-questions now reflect the provisional synthetic-only lock (`docs/16`), the MC50 proof table, and the new `AGENTS.md`; release posture unchanged
+
+### H5 Trust — first paper-facing evaluation (2026-08-04)
+
+- **Design lock:** `docs/17_H5_Trust_Design.md` — country-level generalized trust; WVS7 × GPS × WDI/WGI; pinned network (gps_trust 0.3 / rule_of_law 0.3 / gini −0.1); δ=0; β=corr_y on log GDP pc; claims boundary
+- **First frozen build:** n=35 countries; `evals/h5_trust/build_dataset.py` (masking, aggregation, coverage rule, canonical hashes); reproducible `--fetch-wdi`/`--fetch-wgi`
+- **Preliminary paper-facing evidence (owner-approved 2026-08-04):** M\*={m_trust_general, m_trust_in_group}, [L,U]=[0.371, 0.624], FA=0, cold H4; θ-grid empties at λ≥1.5; bootstrap band [0.174, 0.752] with 17.5% empty replicates
+- Tracked summary: `reports/summaries/h5_trust_evidence_summary.json`; auditors `tools/verify_h5_trust.py` + `tools/verify_v11_protocol_synth_mc50.py`
+- **Boundary:** preliminary checkpoint; final paper lock, tag, PyPI, and push remain Augusto's
+
+### Release posture (2026-08-04)
+
+- **Packaging fix:** removed duplicate hatchling force-include that broke `uv build` (report.html.j2 added twice); wheel now builds cleanly
+- **Wheel verified from a fresh venv:** template packaged, console script works, H5 run reproduces bit-identical M\* and [L,U]
+- Release checklist recaptured: 157 tests passed, ruff/mypy clean, `v0.1` intact; tag `v1.1.0` and PyPI publication remain Augusto + release-review decisions
+
+### Tag `v1.1.0` (2026-08-04)
+
+- Annotated tag `v1.1.0` created and pushed (Augusto's explicit decision) — symbolizes the MVP: v1.0 spine + v1.1 inference layer + H5 Trust preliminary evidence + packaging/CI fixes
+- Tag-as-symbolization convention (v0.1 precedent): wheel remains dev `1.1.0a1`; PyPI publication is a separate decision with version alignment at publish time
+
+## [Unreleased]
+
+### Planned
+
+- Measure discipline: δ-grid, evaluator registry growth (`mean_order`/`rank_agree`/`ols_coef`), θ-anchor documentation discipline
+- H5 robustness checks + extensions (v2.0 roadmap)
+
+## [1.0.0a1] — 2026-08-01 (spine shipped on `main`)
+
+**v1.0 thin first-principles spine** — SCORE → RESTRICT → IDENTIFY → thin REPORT with `[L,U]=min/max B*`, freeze hashes, mini fixture, package-native synth battery, minimal CI, and an intermediate real-world spam audit (not H5). Merged to `main` @ `3be6367`. Tag decision owned by release-review chat.
+
+### Added
+- **M9 / minimal CI:** `.github/workflows/ci.yml` — uv sync, ruff, pytest, CLI smoke, import-graph hygiene, mini fixture SCORE→REPORT on Python 3.11/3.12
+- **Intermediate real-world audit:** `evals/realworld/spam_validity/` — 20newsgroups multi-measure spamminess stress; `verify_audit.py` exit 0; FA=0; harsh empty; cold H4; **not** main-path H5
+- **M8 / G8:** package-native synth harness (`src/cvprofiles/synth/`); battery drives real SCORE→RESTRICT→IDENTIFY; H1a/H1b/H3/H4 **green** on seeds `0..4`, \(n=1000\); H1_latent diagnostic only (attenuation → 0); proof `reports/summaries/v1_0_package_synth_summary.json`; museum unimported
+- **M7 / G7:** thin REPORT (HTML/JSON); `run_profile` SCORE→REPORT composition; CLI `cvprofiles run` (stdout JSON / stderr crumbs); empty-\(M^*\) first-class; e2e on mini_v1 oracle + harsh
+- **M5 / G5:** \(\beta=\mathrm{corr}_y\); \([L,U]=\min/\max B^*\) on survivors only; empty/point-ID flags; `range.json` notes bootstrap deferred to v1.1
+- **M4 / G4:** IDENTIFY slacks (`corr_min`, `corr_sign`); \(M^*\) + rejection reasons; harsh empty fixture (`network_harsh.yaml`, \(\theta=0.999\)); FA=0 on `m_slop`
+- **M3 / G3:** RESTRICT load/bind network+beta; `RestrictError` at IO boundary; golden network/beta hashes
+- **M2 / G2:** SCORE pipeline (`run_score` / `write_score_artifacts`); default normalization `none`; optional `zscore_measures` on measures only; fail-loud on missing cols / empty / dup unit_id / non-finite; golden `scores_hash` match on mini_v1
+- **M1 / G1:** installable `src/cvprofiles` (`1.0.0a1`) + `pyproject.toml` + thin CLI
+- Pydantic v2 schemas (scores / network / beta / freeze run manifests)
+- Freeze hash + `run_id` util (`cvprofiles.freeze`); algorithm locked in `docs/12`
+- Mini fixture `data/fixtures/mini_v1/` + golden `expected_freeze.json`
+- Contract tests (schemas, freeze bit-stability, import-graph hygiene, mini load)
+- **Phase 0 (v1.0 sprint start):** scope box — thin first-principles spine; M6 bootstrap/θ-grid deferred to v1.1; no M10 this sprint
+- Past-tense docs: public repo + tag `v0.1` @ `fb62b48` live; G7/G8 re-enter from G5 for v1.0; H1a/H1b gates + H1_latent diagnostic pointers
+- `docs/14_Researcher_Input_Guide.md` — DRAFT process guide for composites, anchors, SCORE/RESTRICT prep (not part of tag `v0.1`)
+
+### Planned (later)
+- Paper prereg freeze
+- Public baseline H5 (USER-authored network only)
+- δ-grid, `mean_order`/`rank_agree` evaluators, `ols_coef`, LaTeX report (post-MVP backlog)
+
+## [0.1.0] — 2026-08-01
+
+**Symbolizes v0.1:** methods knowledge base + green synthetic PoC (museum monolith).  
+**Not** a PyPI release. **Not** the package API.
+
+### Added
+- Project scaffold under `~/Hermes/Projects/cvprofiles`
+- Methods-first documentation suite (`docs/01`–`13`, `PROJECT_MANIFEST.md`)
+- Dual live logs (decision/engineering + evaluations)
+- MIT `LICENSE`
+- **`evals/synthetic/v0_poc.py`** monolith (`POC_VERSION=v0_1_poc`) — SCORE→REPORT synthetic battery with gate check
+- Proof summary `reports/summaries/v0_1_poc_summary.json`
+
+### Fixed / learned
+- **v0 → v0.1 hygiene:** distinct `oracle_with_slop`; true empty `all_invalid`; cold determinism; near_miss fails by design
+- **H1 split locked:** H1a/H1b gates; H1_latent diagnostic only (attenuation); no \(\theta\)-loosening
+- v0.1 battery **exit 0** (FA=0, empty honesty, anchor retention, cold OK)
+
+### Explicit non-contents
+- No `src/cvprofiles` package layout
+- No bootstrap / θ-grid inference layer
+- No real-data baseline / H5 network
+- No LLM inside the engine

cvprofiles-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augusto Gonzalez Bonorino
+
+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.

cvprofiles-2.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: cvprofiles
+Version: 2.0.0
+Summary: Construct-validity profiles: admissible measurement sets and construct-identified ranges
+Project-URL: Homepage, https://github.com/Bonorinoa/cvprofiles
+Project-URL: Repository, https://github.com/Bonorinoa/cvprofiles
+Author: Augusto Gonzalez Bonorino
+License: MIT
+License-File: LICENSE
+Keywords: construct-validity,econometrics,measurement,partial-identification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cvprofiles
+
+**Construct-validity profiles for cheap multi-measure AI operationalizations.**
+
+Open, high-observability research tooling that treats construct validity as **partial identification over a menu of measurement functions**, disciplined by a researcher-authored nomological network. The engine returns an admissible measurement set \(M^*\) and a construct-identified range \([L,U]\) for a target functional \(\beta(\cdot)\). Empty sets and wide ranges are scientific features, not product failures.
+
+| | |
+|---|---|
+| **Version** | **v0.1** tagged (methods KB + museum PoC); **v1.1.0 tagged** (MVP: spine + inference layer + H5 Trust evidence); **v2.0.0 release (publication in progress)** |
+| **Status** | Public repo live; tags `v0.1` @ `fb62b48` and **`v1.1.0`** (MVP, 2026-08-04) frozen; protocol draft locked **provisional synthetic-only**; H5 Trust design locked (`docs/17`), first frozen run accepted as **preliminary paper-facing evidence** (n=35, [L,U]=[0.371,0.624]); PyPI publication pending |
+| **Type** | Academic methods tool (Python package + paper) |
+| **Owner** | Augusto Gonzalez Bonorino |
+| **License** | MIT |
+| **GitHub** | https://github.com/Bonorinoa/cvprofiles |
+| **CI** | [![ci](https://github.com/Bonorinoa/cvprofiles/actions/workflows/ci.yml/badge.svg)](https://github.com/Bonorinoa/cvprofiles/actions/workflows/ci.yml) |
+| **Hermes profile** | `cvprofiles` |
+| **Path** | `~/Hermes/Projects/cvprofiles` |
+| **PoC** | `evals/synthetic/v0_poc.py` (`v0_1_poc`) — **museum monolith**, not package |
+| **Proof summary** | `reports/summaries/v0_1_poc_summary.json`, `v1_0_package_synth_summary.json`, `v1_1_package_synth_summary.json`, `v1_1_protocol_synth_mc50_summary.json` (provisional synthetic-only protocol table; not H5 / not a paper result) |
+
+## Thesis spine (one paragraph)
+
+Researcher supplies unit×measure scores (SCORE). Researcher authors a nomological network \(R\) with thresholds \(\theta\) and a target \(\beta(\cdot)\) (RESTRICT). Engine computes sample slacks, keeps admissible measures \(M^*\), maps survivors through \(\beta\), and reports \(B^* / [L,U]\) (IDENTIFY). **v1.0:** \([L,U]=\min/\max B^*\) only. Bootstrap and \(\theta\)-sensitivity are **v1.1**. Measure discipline (δ-grid, evaluator growth, θ-anchor artifacts) is **v2.0**. Audit trail in HTML/JSON (LaTeX later) a non-coder can steer (REPORT). Engine is **score-agnostic and model-free**. No LLM lives inside the engine.
+
+## Document map
+
+Start here, then read in order:
+
+| Doc | Purpose |
+|---|---|
+| [`docs/01_Project_Overview.md`](docs/01_Project_Overview.md) | Goals, users, scope, hard non-goals |
+| [`docs/02_System_Architecture.md`](docs/02_System_Architecture.md) | 4-state machine, IO contracts, determinism |
+| [`docs/03_Methodology.md`](docs/03_Methodology.md) | Menu, slacks, \(M^*\), \(B^*\), inference stance |
+| [`docs/04_Synthetic_DGPs.md`](docs/04_Synthetic_DGPs.md) | Calibrated DGPs + four debug metrics |
+| [`docs/05_Pre_Registration.md`](docs/05_Pre_Registration.md) | Draft H1–H5 (user owns theory) |
+| [`docs/06_Tech_Stack.md`](docs/06_Tech_Stack.md) | Language, numeric stack, packaging |
+| [`docs/07_Software_Development_Strategy.md`](docs/07_Software_Development_Strategy.md) | TDD, gates, agent workflow |
+| [`docs/08_Observability_and_Evaluations.md`](docs/08_Observability_and_Evaluations.md) | Artifacts, metrics, report contract |
+| [`docs/09_MVP_Plan.md`](docs/09_MVP_Plan.md) | Milestones and build order |
+| [`docs/10_Open_Questions.md`](docs/10_Open_Questions.md) | Explicit deferrals |
+| [`docs/11_Glossary.md`](docs/11_Glossary.md) | Notation |
+| [`docs/12_Decision_Engineering_Log.md`](docs/12_Decision_Engineering_Log.md) | **LIVE** engineering decisions |
+| [`docs/13_Evaluations_Log.md`](docs/13_Evaluations_Log.md) | **LIVE** eval runs and learnings |
+| [`docs/14_Researcher_Input_Guide.md`](docs/14_Researcher_Input_Guide.md) | Composites, anchors, SCORE/RESTRICT prep |
+| [`docs/15_MVP_Release_Checklist.md`](docs/15_MVP_Release_Checklist.md) | MVP release checklist (feeds release-review chat) |
+| [`docs/16_Paper_Protocol_Freeze.md`](docs/16_Paper_Protocol_Freeze.md) | Paper-facing locks, open fields, provenance rule |
+| [`docs/17_H5_Trust_Design.md`](docs/17_H5_Trust_Design.md) | H5 Trust design (LOCKED as design; run gated) |
+| [`docs/18_Measure_Discipline_Plan.md`](docs/18_Measure_Discipline_Plan.md) | v2.0 scope box: δ-grid, evaluator growth, θ-anchor discipline |
+| [`tutorials/cvprofiles_tutorial.ipynb`](tutorials/cvprofiles_tutorial.ipynb) | Independent tutorial: synthetic walk-through + H5 replication |
+| [`docs/PROJECT_MANIFEST.md`](docs/PROJECT_MANIFEST.md) | Machine-readable index |
+
+## Roadmap
+
+### v1.0 (this sprint — thin first-principles spine)
+
+1. **Schemas + freeze contract** — typed score matrix, network, \(\beta\), run manifest  
+2. **SCORE → RESTRICT → IDENTIFY** — slacks, \(M^*\), \([L,U]=\min/\max B^*\) (no bootstrap)  
+3. **Thin REPORT** — HTML/JSON; empty \(M^*\) is a clean success  
+4. **Synth harness re-impl** under package/tests (H1a / H2 / H3 / H4; H1_latent diagnostic)  
+5. **Installable package + minimal CI**
+
+### v1.1 (tagged `v1.1.0` 2026-08-04 — MVP; PyPI publication pending)
+
+- Units-only bootstrap with conservative, additive percentile diagnostics
+- Deterministic θ-grid sensitivity surface; headline remains [L,U]=min/max B*
+- Pipeline, CLI, JSON/HTML audit panels, package-native evidence, and minimal CI
+- Version `2.0.0`; tag `v1.1.0` live; v2.0 measure discipline ENTRY complete; PyPI publication in progress
+- Provisional synthetic-only protocol lock (`docs/16`) with an audited MC50 proof table (seeds `0..49`); H5 Trust design locked (`docs/17`), first frozen run (n=35) accepted as **preliminary paper-facing evidence**; empirical/paper inputs remain Augusto-owned
+
+### Remaining backlog
+
+- **Paper-facing protocol freeze:** [`docs/16_Paper_Protocol_Freeze.md`](docs/16_Paper_Protocol_Freeze.md) — construct, score matrix, menu, researcher-authored \(R\), \(\theta\), \(\delta\), \(\beta\), and evidence posture (synthetic-only portion currently locked provisional)
+- **M10 / H5:** country-level generalized trust baseline — design **LOCKED** (`docs/17`); first frozen run (n=35) accepted as **preliminary paper-facing evidence** (`reports/summaries/h5_trust_evidence_summary.json`); final paper lock + release remain Augusto's
+- **v2.0 measure discipline (in progress):** see [`docs/18_Measure_Discipline_Plan.md`](docs/18_Measure_Discipline_Plan.md) — δ-grid tolerance layer, `mean_order`/`rank_agree`/`ols_coef` evaluators, θ-anchor artifacts, and an H5-replication tutorial. LaTeX report remains later backlog.
+
+See [`docs/09_MVP_Plan.md`](docs/09_MVP_Plan.md) for the locked v1.0 scope box and [`docs/15_MVP_Release_Checklist.md`](docs/15_MVP_Release_Checklist.md) for the v1.1 handoff checklist.
+
+## Hard non-goals (unless reopened in the decision log)
+
+- Foundation-model training  
+- New human annotation campaigns as the main path  
+- Hypothesis-generation / SAE pipelines as thesis core  
+- Full PPI/MARS reimplementation as co-equal deliverable  
+- LLM-agent ABMs / SCA product work as this spine  
+- Proprietary API dependence for paper-reproducible results  
+- “Automate all of empirical economics” platforms  
+
+## Working convention
+
+Progress is read from **on-disk artifacts** (slacks, \(M^*\), ranges, `report.html`) and the two live logs — not from git archaeology alone. Paper numbers come only from **frozen score matrices + pinned network + fixed seed**.
+
+## Repo status
+
+- **Tag `v0.1` @ `fb62b48` (live, immovable):** documentation suite + museum synthetic PoC with green gates.  
+  Release: https://github.com/Bonorinoa/cvprofiles/releases/tag/v0.1
+- **`main`:** v1.0 spine through M9 (shipped as `1.0.0a1`) + intermediate spam audit + v1.1 inference layer, merged.
+- **v1.1.0 tagged (2026-08-04):** MVP — v1.0 spine + v1.1 inference layer (units bootstrap + θ-grid) + H5 Trust preliminary evidence. Release version `2.0.0`; PyPI publication in progress.
+- **Not yet:** PyPI release. **v2.0 measure discipline in progress** (`docs/18`): δ-grid, evaluator growth, θ-anchor artifacts, H5-replication tutorial.
+
+### Install (dev)
+
+```bash
+uv sync --extra dev
+uv run pytest -q
+uv run cvprofiles --version
+```
+
+### Museum PoC (expects exit 0; do not import into `src/`)
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv/bin/python numpy pandas
+.venv/bin/python evals/synthetic/v0_poc.py
+```
+
+- Progress is read from on-disk artifacts + `docs/12` / `docs/13`, not git archaeology alone.