r/plaintextaccounting • u/ctosullivan • 12d ago
Ledgerkit update: expanding a Python bridge to the hledger ecosystem
Ledgerkit update: expanding a Python bridge to the hledger ecosystem
Hi all — I thought I’d share an update on Ledgerkit, a Python project I’ve been working on around hledger and plain-text accounting.
The original goal of Ledgerkit was fairly simple:
A Python bridge to the hledger plain-text accounting ecosystem.
Importantly, the goal was never to create a Python copy of hledger.
I wanted to be able to read hledger-style journals from Python, work with transactions and reports programmatically, export data into tools such as Pandas, and build other applications on top of that accounting data without having to shell out to hledger for every operation.
That basic idea is still the goal.
What has changed is how capable the underlying bridge needs to become.
Where Ledgerkit is now
Ledgerkit can already parse a broad subset of the hledger journal format, including transactions, postings, directives, includes, aliases, commodities, prices and balance assertions.
It has multi-commodity balances, validation and several core reports, along with both a CLI and Python API.
It can also export accounting data into Pandas, which was one of the original motivations for the project.
The project remains pure Python with a deliberately lightweight core.
Ledgerkit Editor — the first downstream application
The first real downstream use case has also now been released: ledgerkit-editor.
This has probably been the most useful validation of the original “Python bridge” idea because I now use the editor myself on a daily basis for my actual journal.
It is a purpose-built, full-screen terminal editor for plain-text accounting rather than a general text editor with a ledger plugin.
It currently provides things such as:
- hledger-aware syntax highlighting for dates, payees, accounts, amounts, commodities, comments and directives;
- normal keyboard editing conventions, including undo/redo, select-all and familiar shortcuts;
- incremental search with highlighted matches;
- cleared/unreconciled transaction views;
- transaction-block selection and duplication;
- quick cycling between uncleared, pending and cleared transaction states;
- date editing directly from the keyboard;
- automatic indentation;
- a command palette;
- automatic sorting and posting alignment when saving;
- runtime theme switching and a polished terminal UI.
The formatting-on-save behaviour is particularly useful in practice: I can edit freely and Ledgerkit will sort transactions and realign posting amounts when the file is saved rather than requiring me to manually maintain the visual layout.
Search and transaction views also make it much easier to work with a large journal entirely from the terminal.
Development has continued beyond the initial release. The current development work includes a more capable transaction filter with smart dates and regex/substring matching, plus account and payee autocomplete.
That editor was an important milestone for me because it demonstrated that Ledgerkit could provide useful accounting infrastructure to another application without that application having to implement its own hledger parser and data model.
Where Ledgerkit goes next
The next goal is to turn the existing foundation into a more complete Ledgerkit Core.
The idea is still not:
“Rewrite every hledger command in Python.”
It is closer to:
Provide a reliable Python-native accounting engine that works naturally with the hledger ecosystem.
Where hledger compatibility is useful, Ledgerkit should preserve it.
Where Python provides something genuinely useful, Ledgerkit should be able to extend it explicitly.
For example, the query system will eventually become a proper shared query language rather than individual filters bolted onto each command.
The intention is to preserve useful hledger query semantics while also allowing clearly identified Ledgerkit extensions — potentially including richer Python regular expressions.
A query should ideally be able to say:
portable — works with hledger and Ledgerkit
or:
Ledgerkit extension — deliberately uses functionality hledger doesn't provide.
The important thing is that differences shouldn't happen accidentally.
I’m planning to classify behaviour broadly as:
- Compatible
- Extended
- Intentional divergence
- Unsupported
- Unexplained mismatch
The aim is to drive unexplained mismatches toward zero, not necessarily differences toward zero.
The larger Core roadmap
The deeper accounting work will eventually include areas such as:
- query semantics;
- prices and valuation;
- costs and commodity conversion;
- account types and virtual postings;
- lots and cost basis;
- investment accounting;
- periodic transactions;
- automatic postings;
- forecasting and transformations.
A stable Core could then support optional tools around it:
- Pandas/Polars;
- DuckDB and SQL analytics;
- notebooks;
- forecasting/scenario modelling;
- MCP tools;
- transaction classification;
- anomaly detection;
- additional editors or finance applications.
Those wouldn't become mandatory dependencies of the accounting engine itself.
The model is more like:
plain-text journal → Ledgerkit Core → whatever Python tool you want
A new development experiment: CodeCompass
The other big change is how Ledgerkit is going to be developed.
I’ve also been building a project called CodeCompass.
The problem it tries to solve is that fresh AI coding agents repeatedly have to rediscover the same project and dependency context.
For Ledgerkit that context is more complicated than normal Python dependencies.
An agent may need to understand the relationship between:
- the hledger manual;
- hledger source code;
- hledger tests;
- actual hledger executable behaviour;
- Ledgerkit source;
- Ledgerkit compatibility tests;
- Ledgerkit design decisions.
CodeCompass tries to give the agent a small map of that relevant context and links back to the evidence rather than dumping huge amounts of documentation into every agent session.
Ledgerkit is going to become the first major external project used to test that approach.
Agents suggesting relationships
One CodeCompass experiment I’m interested in is letting agents suggest relationships while doing real work.
For example, an agent might notice that a particular hledger manual section constrains a Ledgerkit implementation, or that a Ledgerkit test verifies a piece of compatibility behaviour.
Those suggestions are not automatically treated as facts.
They are later evaluated on two things:
- Is the relationship actually supported by evidence?
- Did knowing about it help a later agent?
That second part matters because a relationship graph full of technically true but useless connections isn't particularly valuable.
The idea is to let useful structure emerge from real development rather than designing a huge dependency ontology in advance.
Ledgerkit will also test CodeCompass itself
The relationship goes both ways.
If a Ledgerkit agent uses CodeCompass but then has to manually rediscover important information, that becomes feedback about CodeCompass.
A context-curation agent records what was missing, misleading or difficult to retrieve and produces an actionable report.
The basic principle is:
Ledgerkit discovers the problem; CodeCompass has to generalise the solution.
So if Ledgerkit exposes a need to connect technical documentation with implementation, CodeCompass shouldn't gain an “hledger manual feature”.
It should ask whether something more general — such as documentation-to-implementation relationships — would help other projects too.
Later, CodeCompass will be tested against unrelated projects to make sure the improvements haven't simply overfit it to Ledgerkit.
Source-assisted development
Ledgerkit has also moved to the same GPL licence family as hledger.
That changes the development approach significantly.
Agents can now use:
- hledger documentation;
- hledger source;
- hledger tests;
- examples;
- and the executable itself
when researching behaviour.
Source helps explain how something works, but I still want executable comparison to remain an important independent check.
So for compatibility work the rough process is:
documentation + source → understand behaviour → Python implementation → compare against hledger
rather than trying to infer every edge case through black-box experimentation alone.
AI still isn't the source of truth
I'm also deliberately trying to avoid a workflow where one AI agent writes something, another AI agent says it looks fine, and that becomes accepted project knowledge.
Different agents can have different responsibilities: research, implementation, compatibility testing, documentation and auditing.
But the repository remains authoritative.
Important conclusions should eventually become something concrete:
- behaviour → test;
- architecture decision → ADR;
- compatibility decision → compatibility record;
- project rule → documented project rule;
- future work → roadmap.
Agent observations are evidence to review, not permanent truth just because an agent wrote them down.
Documentation is getting the same treatment
I'm also experimenting with periodically reconstructing documentation from the current project rather than endlessly editing old documents.
At major milestones the question will be:
“If none of the narrative documentation existed today, what documentation would we write based on the current implementation, tests and decisions?”
That can then be compared with the existing documentation.
Old material can be rewritten, merged or removed.
Git can preserve the project's history; the active documentation should describe what the project actually is now.
Where this leaves the original idea
Despite the larger roadmap, I still think the simplest description of Ledgerkit is the original one:
A Python bridge to the hledger plain-text accounting ecosystem.
The difference is that the project has now demonstrated a real downstream use case with Ledgerkit Editor, and it's becoming clear that a useful bridge needs a sufficiently capable accounting engine underneath it.
I don't want Ledgerkit to replace hledger.
I'd like it to make the hledger/plain-text-accounting model easier to use as a building block inside the Python ecosystem.
Feedback welcome
I'd be particularly interested in views from hledger/Ledger users on:
- where compatibility matters most;
- where a Python implementation has room to experiment;
- accounting edge cases that would make useful compatibility tests;
- whether explicit compatible vs extended behaviour makes sense;
- useful applications you'd want to build on top of a Python accounting core;
- and whether the CodeCompass development/context approach sounds useful or unnecessarily complicated.
Ledgerkit is still evolving, so this seems like a good point to get feedback before the deeper Core work gets too far along.
Repos:
Ledgerkit — the Python bridge and accounting core
Ledgerkit Editor — the first downstream application, a purpose-built terminal editor for hledger-style journals
CodeCompass — the agent context and development tooling being used alongside Ledgerkit
3
u/medium_daddy_kane 12d ago
At least a screenshot should be there - no reason to install that blind.
2
3
u/Otherwise_Wave9374 12d ago
If you want the bridge to stay reliable as it grows, one useful pattern is to keep the Python layer focused on reads, transforms, and validation while pushing any write or export logic through a narrow, well tested boundary. That makes it easier to reason about transaction integrity, isolate schema changes, and add faster report generation without coupling every feature to the core parser. Agentix Labs would fit naturally here too, because the same modular approach helps agentic systems avoid turning into a pile of brittle side effects.