LedgerBridge

Phase 1 ingestion engine of the FundLens suite. Ingests messy extracts from alternative-asset fund-accounting systems, normalizes them into a canonical data model anchored to the AICPA Audit Data Standards, validates them, and emits audit-ready output.

See ledgerbridge.md for the full project context and docs/canonical-schema-v1.md for the schema and validation rules.

Quickstart

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Generate the synthetic golden dataset (deterministic from seed)
python src/truth_engine.py

# Run the validation + determinism tests
pytest -q

Generated CSVs land in ledgerbridge_truth_out/ (gitignored). The generator prints a self-validation report; all rules should pass on the clean dataset.

Structure

ledgerbridge/
├── ledgerbridge.md              # project context — read first
├── CLAUDE_CODE_KICKOFF.md       # paste-in prompt to resume the build
├── README.md
├── requirements.txt
├── docs/
│   └── canonical-schema-v1.md   # full schema + validation rules
├── src/
│   ├── truth_engine.py          # Stage 1: deterministic synthetic truth engine (validated)
│   ├── error_injection.py       # Stage 1b: labeled corruption + ground-truth manifest
│   ├── emit_sources.py          # Stage 2 CLI: write messy flavored workbooks
│   ├── emitters/                # Stage 2: canonical truth → source-flavored messy Excel
│   │   ├── base.py              #   shared emit/read machinery (lossless round-trip)
│   │   ├── atlas.py             #   human-report flavor (Investran-ish)
│   │   └── meridian.py          #   machine-export flavor (Geneva-ish)
│   ├── run_pipeline.py          # Stage 4 CLI: ingest → validate → exceptions log (+ --demo)
│   ├── pipeline/                # Stage 4: ingestion pipeline
│   │   ├── source_adapter.py    #   flavored workbook → canonical frames (flavor auto-detect)
│   │   ├── validators.py        #   row-level validation engine → exceptions log
│   │   └── scoring.py           #   exceptions log vs manifest → precision/recall
│   ├── export_canonical.py      # Stage 5 CLI: canonical model → audit-ready output
│   └── output/                  # Stage 5: output adapters
│       ├── ads.py               #   AICPA ADS GL flat-file export (schema conformance)
│       └── requested.py         #   auditor-template audit pack (physical-format conformance)
├── tests/
│   ├── test_truth_engine.py     # validation + determinism tests
│   ├── test_error_injection.py  # injection isolation + manifest fidelity
│   ├── test_emitters.py         # round-trip losslessness + source-agnosticism
│   ├── test_pipeline.py         # ingest → detect → score (perfect on injected truth)
│   └── test_output.py           # ADS conformance/losslessness + physical-format adapter
└── data/                        # generated output (gitignored)

Status

• Stage 1 — synthetic truth engine (self-validating, deterministic)
• Stage 1b — error injection (labeled corruption + ground-truth manifest)
• Stage 2 — source-flavored messy Excel emitters (Atlas + Meridian, lossless round-trip)
• Stage 4 — ingestion pipeline: source adapter → canonical → validation → exceptions log, scored against the Stage 1b manifest (precision/recall)
• Stage 5 — output adapters: AICPA ADS GL flat-file export (schema conformance) + an auditor-template audit pack (physical-format conformance); both can bundle the exceptions log
• Output adapters — ADS default + requested-format
• Investran source adapter

Compliance: synthetic data only. Never use employer or real fund-administrator extracts.