accountable-record-py

Python reference implementation for staged Accountable Record repository verification.

Overview

This project validates Accountable Record-compatible repositories through a staged pipeline.

The verifier can validate its own repository or a target repository passed with --target.

Target validation is internal coherence by default: the target repository declares its identity in SE_MANIFEST.toml, and the pipeline checks that the repository's metadata and derived artifacts cohere with that declaration.

Package Interface

• The Python import package is accountable_record.
• The Python distribution package is accountable-record-py.
• The public command is accountable-record.

Staged Pipeline

s010_identity     repository identity
s020_contract     contract context
s030_sources      source materials
s040_elements     verifiable element declarations
s050_catalog      normalized catalog
s060_exports      machine-readable exports
s070_resolution   reference and lock resolution
s080_generated    generated artifact validation
s090_docs         documentation rendering

Stages run in increasing order. For example:

• run s040 runs s010 through s040.
• run all runs the full pipeline.

Architecture

A stage is a transform:

StageTransform = Callable[[PipelineState], PipelineState]

PipelineRunContext holds fixed run input, including the target repository. PipelineState is an immutable accumulator containing diagnostics and outputs from completed stages.

Identity validation is target-agnostic. SE_MANIFEST.toml is authoritative for repository identity. CITATION.cff is authoritative for contract/publication version when a version exists.

Command Reference

Show command reference

In a machine terminal

Open a machine terminal where you want the project:

git clone https://github.com/structural-explainability/accountable-record-py

cd accountable-record-py
code .

In a VS Code terminal

uv self update
uv python pin 3.14
uv sync --extra dev --extra docs --upgrade

uvx pre-commit install

git add -A
uvx pre-commit run --all-files
# repeat if changes were made
git add -A
uvx pre-commit run --all-files

uv run accountable-record run s010
uv run accountable-record run s020
uv run accountable-record run s030
uv run accountable-record run s040
uv run accountable-record run s050
uv run accountable-record run s060
uv run accountable-record run s070
uv run accountable-record run s080
uv run accountable-record run s090
uv run accountable-record run all

# validate another repository
uv run accountable-record --target ../judicial-record run all

# convenience aliases
uv run accountable-record check
uv run accountable-record build-catalog
uv run accountable-record export
uv run accountable-record resolve-packages
uv run accountable-record write-lock
uv run accountable-record verify-lock
uv run accountable-record validate-generated
uv run accountable-record render-docs

# types, tests, docs
uv run python -m pyright
uv run python -m pytest
uv run python -m zensical build

# deps
uv run lint-imports

# complexity (only A and B allowed)
uv run radon cc src/accountable_record -s -a
uv run radon cc src/accountable_record -s -a -n C

# maintainability
uv run radon mi src/accountable_record -s

# hal and raw
uv run radon hal src/accountable_record
uv run radon raw src/accountable_record

uv run radon raw src/accountable_record -j | uv run python -c "import json, sys; data=json.load(sys.stdin); keys=('loc','lloc','sloc','comments','multi','blank','single_comments'); totals={k:sum(file[k] for file in data.values()) for k in keys}; print('\n'.join(f'{k.upper()}: {v}' for k,v in totals.items()))"

# save progress
git add -A
git commit -m "update"
git push -u origin main

Current snapshot shows modest in size with significant documentation:

LOC: 9556
LLOC: 3913
SLOC: 4967
COMMENTS: 300
MULTI: 2109
BLANK: 1848
SINGLE_COMMENTS: 632

Citation

CITATION.cff

License

MIT

Manifest

SE_MANIFEST.toml