LedgerPilot is an AI finance controller for autonomous payment reconciliation. It connects commerce orders, gateway transactions, payout batches, and bank statements, then separates deterministic matching from the residual cases that need human review or a LangGraph-assisted decision path.
Status: Demo Ready
LedgerPilot is a feature-complete, reproducible local demo of an AI-assisted payment reconciliation platform. The verified demo includes deterministic reconciliation, real LangGraph orchestration, human-in-the-loop decisions, double-entry safeguards, audit trails, evaluation, authentication, and a React dashboard.
A hosted public deployment is not currently provided. Production deployment would additionally require durable checkpoint storage, full identity management, rate limiting, and production infrastructure.
- Deterministic reconciliation engine with tiered matching passes
- Real LangGraph workflow for ambiguous residual cases
- Human-in-the-loop decision gates
- Synthetic break generators and evaluation harness
- Audit trail and hash-chained event history
- FastAPI backend with typed frontend integration
- React/Vite dashboard and exception views
- Browser smoke verification for the local demo flow
uv sync --all-groups
cp .env.example .env
uv run ledgerpilot info
uv run uvicorn ledgerpilot.api.main:app --reload --port 8000In a second terminal:
cd web
npm install
npm run devA hosted public deployment is not currently provided. Localhost URLs such as
http://localhost:8000/docs,http://localhost:8000/health, andhttp://localhost:5173only work after the application is running locally.
uv run ledgerpilot db init
uv run ledgerpilot generate --scenario smoke
uv run ledgerpilot ingest --scenario smoke
uv run ledgerpilot evaluate --scenario cleanThis intentionally exercises the deterministic pipeline, the API layer, and the frontend views in a controlled local environment.
The current repository supports the following verified local-demo claims:
- Backend tests: ✅
- Frontend build: ✅
- Frontend lint: ✅
- Deterministic evaluation: ✅
- LangGraph / AI evaluation: ✅
- End-to-end regression: ✅
- Browser/UI smoke verification: ✅
These checks are validated by the repository’s test suite, evaluation CLI, and the frontend build/lint pipeline.
Synthetic payment data
↓
Ingestion + validation
↓
Deterministic reconciliation
↓
Residual breaks
↓
LangGraph AI Controller
↓
VERIFY
↓
DECIDE
↙ ↘
ACT ESCALATE
↓ ↓
Exception Queue → Break Detail / Audit
Each stage is implemented in the current codebase: synthetic data generation, validation and quarantine, deterministic matching passes, residual investigation, verification of arithmetic, and human-in-the-loop approval or escalation.
Most payment systems either rely on a brittle rules engine or hand off too much work to an LLM. LedgerPilot does neither. The design is deliberate:
- deterministic code handles the majority of low-risk matching work
- the AI layer is reserved for ambiguous residuals and explanation
- every decision is grounded in arithmetic and event history
- policy gates prevent silent mis-matches from reaching the ledger
- Models used by the optional LLM integration are configurable. The core reconciliation and evaluation paths do not require an external LLM service.
This creates a practical finance workflow: fast automation for the routine, human oversight for the edge cases, and evidence for every decision.
The project’s original phase plan is now a record of completed implementation milestones rather than a backlog of pending work.
- Phase 0–8: scaffold, deterministic engine, break taxonomy, synthetic data, evaluation harness, ledger invariants, agent graph, API, and frontend views
- deterministic reconciliation engine and break classification
- fee-variance and narration-noise synthetic injectors
- same-seed reproducible generation and deterministic evaluation
- LangGraph orchestration with checkpointed interrupts and resume flow
- human-in-the-loop decision API, exception queue, and break detail views
- audit trail and hash-chain verification
- authentication, run isolation, and end-to-end regression coverage
- end-to-end local demo runs with deterministic matching and human review
- backend tests pass
- frontend build and lint pass
- evaluation scoring runs against real scenarios
- the AI graph executes in validated local-agent evaluation paths
- durable production checkpoint storage
- enterprise identity and RBAC
- rate limiting and standard production security controls
- managed hosting and deployment infrastructure
- broader operational telemetry and alerting
- Core package
- Configuration
- CLI entrypoints
- Deterministic reconciliation engine
- Agent graph
- Audit and hash chain
- API application factory
- API routers
- Frontend app
- Test suite
- Agent graph tests
- Break decision API tests
- E2E demo flow
- Evaluation harness tests
- Security hardening tests
No screenshot assets are currently committed in this repository. The working demo is best reviewed through the live project flow and the test suite, including tests/test_e2e_demo.py and the frontend in web/src.
The project is structured around a disciplined layering model.
- src/ledgerpilot/domain contains pure types and policy
- src/ledgerpilot/recon implements the deterministic matching cascade
- src/ledgerpilot/ledger enforces posting and balance invariants
- src/ledgerpilot/agent hosts the LangGraph workflow
- src/ledgerpilot/audit records immutable reasoning history
- src/ledgerpilot/api exposes the application to the frontend
- web provides the Vite + React dashboard and exception views
LedgerPilot is currently designed for a controlled local demo and evaluation setup.
- Local SQLite is the default configuration rather than a hosted production database
- LangGraph state is process-scoped through the current checkpoint implementation
- Authentication is shared bearer-token based rather than a full enterprise auth system
- A hosted public deployment is not currently provided
- Production work still needed includes infrastructure, monitoring, environment hardening, and deployment automation
This is a credible working prototype and demo platform, but it is not presented as a fully hosted production deployment.
LedgerPilot’s current local demo is strong and reproducible, but the project still has a clear path to production hardening.
- durable checkpoint persistence beyond the process-scoped local demo setup
- stronger identity, authorization, and audit access control
- rate limiting and API protection for multi-user deployment
- containerized or managed deployment infrastructure
- deeper operational telemetry and alerting
The core reconciliation and agent workflows are already functional and verified in this repository; the remaining work is primarily deployment and production readiness rather than core product functionality.
- The project keeps secrets in environment files and expects local operators to manage them responsibly
- The server-side Anthropic key is not part of the browser frontend
- Prompt redaction and read-only tool surfaces are used to reduce model-side risk
- The deterministic ledger logic remains the control layer for money movement
See src/ledgerpilot/config.py and src/ledgerpilot/agent/guards.py for the operational safeguards.
Prerequisites: Python 3.11+, uv, and Node 20+.
uv sync --all-groups
cp .env.example .env
uv run ledgerpilot infoStart the backend:
uv run uvicorn ledgerpilot.api.main:app --reload --port 8000Start the frontend:
cd web
npm install
npm run devRun the test suite:
uv run pytestMIT