Executive Summary
Bill Splittr is an agent built with the Railtracks framework that makes bill splitting and payment tracking accurate, persistent, and audit-friendly. Every expense, payment, balance, and settlement is derived from explicit, traceable transactions never opaque agent behavior so debts and credits are always clear. With Railtracks under the hood, all actions are validated, replayable, and deterministic, ensuring users can always see who paid, who owes, and why.
Architecture
The local bill‑splitter is designed as a structured, technically robust system for managing shared expenses end to end. Bills, whether simple or multi‑line, are processed through a parsing agent that automatically extracts items, quantities, and costs, eliminating manual entry. A deterministic splitting engine then allocates each member’s share with consistent, math‑accurate logic. It supports persistent creation of users and groups its current prototype operates with ten users across three groups built on a clean data model that maintains identities and historical transactions. A dockerized deployment is also in development, enabling developers to spin up the full environment locally with a single command for testing, debugging, or extending the system.
Design
Railtracks has a strong typing and explicit orchestration of agentic workflows. It supports the capabilities the agent needs and provides seamless execution for builders.
- Tool as Node: Each backend tool (add transaction, parse bill, update balance) was mapped to a function node. These nodes are then assembled by the Railtracks agent, making stateful orchestration completely deterministic and auditable. No more surprises from unpredictable LLM calls!
- Schema-Backed Outputs: With Pydantic, our agent nodes must return well-formed summaries (e.g., of group balances), reducing glue code and parsing errors downstream.
- Async-by-Design: Because Railtracks treats all tool calls as first-class async functions, plugging into web or desktop UI updates becomes trivial: especially in event-driven or agent-composed applications.
- Minimal Boilerplate, Maximum Safety: Unlike generalized frameworks (like LangChain), Railtracks forced us to make orchestration and logic explicit, reducing accidental misuse and granting us full control over agent behavior.
Core Implementation Highlights
- Ledger as JSON: Every user, group, expense, and net balance lives in a local (atomic-write safe!) JSON file. The tools layer enforces referential integrity—no “ghost users,” always correct math.
- Rigorously Auditable Deltas: Transactions generate directed edges: A owes B $X. All debits/credits are explicit, making every balance traceable back to source entries. When reloading or after manual edits, a “rebuild” tool replays all transactions to guarantee correctness.
- Validated Everywhere: Helper functions for group/user lookups and strong input validation mean any inconsistent call fails early—with helpful errors.
- Edge-Case Ready: Bill splitting isn’t always even: we handle remainder cents deterministically (by index), automate cancellation of offsetting debts (no more cycles), and allow full ledger rebuilding on demand.
Other frameworks were put to the test, but Railtracks fit the bill best. The framework excels when you want explicit, tightly bounded logic paths: tools mapped directly, agent flows unambiguous. Other frameworks offered more integrations and retrievers that is great for LLM-augmented search or complex pipelines, but is an overkill and more error-prone for our local deterministic workflow.
- Predictable Agent Invocations: With Railtracks, our main splitter agent always calls init_store → records a transaction → updates and returns balances in one flow—every time. We can guarantee and test this order.
- Less Ceremony, Faster Iteration: Setting up the tools, wiring agents, and defining schemas took minutes, not hours.
- Easy Containerization: With such a clear state model and few dependencies, dockerizing the application for any teammate was a snap.
Try and Explore Bill Splittr
Build Smarter Agents Faster, Easier for Free
Download Railtracks from GitHub and get access to powerful agent orchestration tools that simplify complex agentic flows.
