cards.py

"""Generated responsible-AI cards for the optional drafting seam."""

from __future__ import annotations

from pathlib import Path


def render_model_card() -> str:
    """Render the release-regenerated model card."""

    return """---
language:
  - en
  - es
license: apache-2.0
base_model: operator-pinned Amazon Bedrock Claude model_id
pipeline_tag: text-generation
library_name: boto3
model-index:
  - name: Outcome Receipts optional narrative drafter
    results:
      - task:
          type: text-generation
          name: Receipt-constrained narrative drafting
        metrics:
          - type: fail_closed_grounding_rate
            value: 1.0
            name: Unbound numeric spans blocked
---

# Model card — optional narrative drafter

Generated by `receipts cards`. Do not edit by hand.

## Intended use

When explicitly enabled, Claude on Amazon Bedrock rewrites a filled funder-report
template for clarity. It receives the baseline narrative and an allowlist of
receipted display strings. It does not compute metrics, map fields, approve a
report, or verify a number.

## Policy and enforcement

Cloud drafting is off by default. It requires `provider = "bedrock"`,
`enabled = true`, a pinned `model_id`, and the per-run
`--allow-cloud-drafting` flag. The deterministic drafter remains the default.
Every model draft is grounded against raw receipts, suppression rebuilds the
publishable surfaces, and the publishable draft is grounded again before human
approval. Any added, altered, rounded, signed, ranged, or written-out number
blocks export.

## Limitations and evaluation

The model may change meaning without adding a number, produce poor prose, or fail
to follow the allowlist. Grounding proves numeric provenance, not narrative
quality or fairness. Tests inject invented numbers and require the gate to reject
them. A model-based faithfulness judge is not shipped; if added, it must be
calibrated against human labels before gating decisions.

The committed synthetic benchmark is split across English and Spanish numeric
spans. Both language slices enforce the same absolute requirement: no unbound
numeric span survives. This evaluates the mechanical grounding gate, not prose
quality, cultural fit, or translation quality.

## Out-of-scope use

The drafter must not compute, round, map, approve, or verify a figure. It is not a
case-management system, eligibility system, clinical tool, or source-data quality
checker. It must not receive client rows or direct identifiers.

## Environmental footprint

N/A — this repository trains and fine-tunes no model. Bedrock inference energy
and emissions are controlled by the selected provider model and are not exposed
to this offline tool as a measurable training run.

## Human responsibility

A named human approves the final redacted artifact. Approval is not evidence
that the underlying metric definition or source data is correct.

*Last verified: 2026-07-12 · Recheck cadence: on any model, prompt, or Bedrock policy change, and at least quarterly.*
"""


def render_data_card() -> str:
    """Render the release-regenerated data card."""

    return """# Data card — reporting and drafting data flow

Generated by `receipts cards`. Do not edit by hand.

## Motivation

The data path exists to compute funder-report aggregates with reproducible
receipts and to test that the grounding gate blocks invented numeric spans.

## Composition

Inputs are organization-provided CSV exports and author-controlled TOML specs.
The deterministic engine processes source rows locally and emits scalar figures
with query, row-count, and slice-hash receipts. The committed benchmark and
examples are synthetic. They contain English and Spanish narratives, planted
receipt-backed displays, and planted unbound numbers.

## Collection

Operators provide their own CSV and TOML files locally. The project does not
collect, host, scrape, or redistribute those inputs. Synthetic fixtures are
authored in this repository and reviewed with the tests that consume them.

## Preprocessing

CSV rows are validated, loaded into in-memory SQLite, and reduced to scalar
figures. The receipt stores the query, row count, canonical slice hash, and
timestamp. Source rows do not enter the report renderer or model request.

## Uses

The deterministic engine uses local inputs to produce receipts and aggregate
reports. The optional Bedrock request uses the filled narrative and a scalar
display allowlist only. The synthetic benchmark evaluates the fail-closed
numeric grounding behavior; it is not representative of real client outcomes.

## Distribution

Synthetic fixtures and the committed eval report ship under Apache-2.0 with the
repository. Organization-provided source data is never bundled or redistributed.

## Maintenance

The maintainer updates this card, the synthetic fixtures, and the eval report in
the same change that alters the data boundary, grounding policy, suppression
policy, prompt, or model seam. Release CI fails if generated cards drift.

## Cloud boundary

By default, no data leaves the process. With Bedrock drafting explicitly enabled,
the request contains only the filled narrative and scalar display allowlist. It
does not contain source rows, client identifiers, receipt hashes, SQL, or data
paths. Small aggregate values may appear in the first in-memory drafting pass;
organizations must authorize that transfer under their own data policy.

## Publication and privacy

Exports are structurally aggregate-only. Counts from 1 through 10 are redacted
under the CMS-modeled default; complementary, delta, and percentage controls
reduce arithmetic recovery. HUD does not prescribe this numeric floor, so the
applicable local policy remains authoritative. True zeros remain visible.

## Retention and limitations

The application does not create a cloud-side retention policy; Amazon Bedrock
account and logging configuration controls provider-side handling. Local source
files, outputs, ledgers, and bundles remain under operator control. Receipts show
how a number was computed, not whether collection was complete, consensual, or
free from structural bias.

*Last verified: 2026-07-12 · Recheck cadence: on any data-boundary, retention, or model-seam change, and at least quarterly.*
"""


def write_cards(out_dir: Path, *, check: bool = False) -> bool:
    """Write generated cards, or return whether committed cards are current."""

    cards = {
        "model-card.md": render_model_card(),
        "data-card-reporting.md": render_data_card(),
    }
    if check:
        return all(
            (out_dir / name).exists() and (out_dir / name).read_text(encoding="utf-8") == content
            for name, content in cards.items()
        )
    out_dir.mkdir(parents=True, exist_ok=True)
    for name, content in cards.items():
        (out_dir / name).write_text(content, encoding="utf-8")
    return True