Reconcile account exports and draft a sourced plan¶
examples/finance-exports/humagen.yaml runs a native agent, ledger, on the
account exports in one conversation. A script does the arithmetic: it removes
duplicate rows, reconciles each export's balances and totals the months and
the debts. The agent runs it with the shell tool in a sandbox, reports what
does not reconcile, and writes a plan in which every amount is copied from
the script's output with its source. It orders what the numbers show. It
gives no financial advice, and nothing here reaches a bank or moves money.
Before #383 this example ran on the Claude Code program in a folder on the
host, whose allow rules refused every command but the script and every write
outside out/. Those rules are gone with it; see below for what holds now.
Prepare the folder¶
Put in one folder the exports you authorize, a file authorized.txt naming
them one a line, and a copy of examples/finance-exports/reconcile.py. These
go into the conversation, so leave out any export the agent must not read. An
export is a CSV that starts with # key: value lines (account, kind as
bank, card or loan, period_start, period_end, opening_balance,
closing_balance, and for a debt apr_percent and minimum_payment),
followed by the header id,date,description,amount. Money in is positive. Two
rows are one transaction when they have the same account and id, and nothing
else is merged, so two purchases of the same amount on one day both stay. An
amount is digits with at most two decimals. The script stops, and writes no
figures, on an amount written any other way and on two rows with one account
and id that disagree on date, description or amount: it lists those in
out/conflicts.csv and leaves the choice to you.
Start the agent and add the files¶
The profile runs each run's tools in a Docker instance of
python:3.13-alpine, so the host needs a running Docker daemon and that
image (docker pull python:3.13-alpine). Set a provider key in the shell
(ANTHROPIC_API_KEY, OPENAI_API_KEY or GOOGLE_API_KEY; the agent tries
them in that order) and start the example:
In another terminal, put the folder's files into a new conversation with the
files API (examples/conversation-files.sh starts a conversation no agent
answers yet and saves each file under its own name):
python3 examples/finance-exports/make-fixture.py exports # or your own folder
thread=$(sh examples/conversation-files.sh new "Exports")
sh examples/conversation-files.sh put "$thread" exports/authorized.txt exports/reconcile.py \
$(grep -v -e '^#' -e '^$' exports/authorized.txt | sed 's|^|exports/|')
That puts only the exports authorized.txt names. The generated folder also
holds other-person-savings.csv, an export that is not authorized, and it
stays out of the conversation. The files API takes UTF-8 text only, at most
2 MiB a file. Open the conversation in the
console, or post to it with POST /api/threads/{id}/messages, and tag
@ledger.
What holds now:
- The agent has
file_list,file_read,file_write,shellandpublish_artifact. The shell runs in the run's instance, which has no network and is destroyed when the run ends; what is written underout/is kept with the conversation. The instance runs withrunc, which shares the host's kernel: use it for trusted local trials only. - Inside the instance the shell can run any command and write anywhere in the
working directory. "Run only
python3 reconcile.py",authorized.txtand "only underout/" are instructions in the prompt, not controls. A file the agent must not see should not be in the conversation. - Do not swap in the
localorunisolatedsandbox kind. The local kind runs the shell as host processes with the server's privileges, unconfined: every export and anything else the server can read is in reach, its environment is empty, and the shell's default search path finds only commands in/usr/local/bin,/bin,/usr/binand the like (not, for example,/opt/homebrew/bin). Unisolated refuses the shell. - A native turn makes at most 10 rounds of tool calls.
- The exports are sent to the model provider as the agent reads them.
Ask for the reconciliation and the plan¶
Reconcile the authorized exports in this conversation. Tell me how many
transactions there are once duplicates are removed and where the duplicates
came from, which exports do not reconcile and by how much, and what each debt
is, with its rate and minimum. Then write a plan to out/plan.csv: the monthly figures
and debts copied from the summary with their source, and your suggestions for
which debt to pay down first and why as proposals. Say what the exports do not
show.
A plan row that carries an amount names its source as out/summary.csv:N, the
line of the summary it copies, the header being line 1.
Check it yourself¶
Fetch what was written into the folder that holds the exports, then check it there:
sh examples/conversation-files.sh get "$thread" exports out/transactions.csv out/reconciliation.csv out/summary.csv out/plan.csv
python3 examples/finance-exports/check.py exports
The checker shares no code with the script: its rules are written out a second
time, including the words that give a category. From the exports it rebuilds
every transaction with its date, description, amount, category, the file and
line it is first on and the lines of its exact copies, and the balance
differences and the monthly and debt figures. It fails when anything under
out/ differs field for field, when a row comes from a file that is not
authorized, when copies of a transaction disagree, when an amount is not whole
cents, when the summary is not exactly the rows the exports give (each month
and category, and for each debt its balance, rate, date and file from the
statement with the latest period end, and its minimum payment), when a plan
amount is not the summary line its source names, or when a proposal carries an
amount.
runs both against twenty-six cases that must pass or fail: the generated exports untouched, nineteen changes to what was written, and six changes to the exports themselves.
What was checked, and what was not¶
On this native profile:
- It passes
humagen config checkand starts and stops with no provider key. reconcile.pyran unchanged inpython:3.13-alpinewith no network, outside Humagen: 33 transactions, 4 duplicate rows removed, the card export reported as not reconciling.regress.pypasses its 26 cases, andconversation-files.shput the four authorized exports,authorized.txtandreconcile.pyinto a conversation on a running server, leaving the fifth export out.- It has not been run with a live model. That the agent runs the script through the shell tool, and anything it reports or writes, is not shown. Rerun the prompt and the checker before relying on it.
Before #383, on the removed Claude Code profile, with five invented exports
from examples/finance-exports/make-fixture.py (two checking exports that
overlap by two weeks, a card statement whose closing balance is 25.00 away
from its rows, a loan, and a fifth export in the folder and not authorized):
- That agent reported 33 transactions after 4 duplicate rows were removed, all from the overlap, and kept the two coffees of one day as two.
- That agent reported the card statement as not reconciling, by 2,500 cents, and did not explain it away.
- That agent's plan copied 26 amounts from the summary, each naming its line, and made proposals with no amount.
- That agent did not open the export that is not authorized, and the exports were unchanged.
- On a copy in which one transaction's second copy has another amount, the script stopped, and that agent reported the two lines, chose neither and wrote no plan.
- That profile's allow rules refused
python3 -c "print(1)"and writes outsideout/. The native profile refuses neither.
Not checked:
- Real exports. Every name and number is invented. A bank's own export format has to be put into the format above first, and no bank's format was tried.
- Whether the plan is good advice. Nobody qualified reviewed it.
- Categories. The script assigns them from words in the description. A
description it does not know is
other. - Interest going forward, currencies, joint or business accounts, taxes.
- Anything in a spreadsheet or a cloud folder. The exports were files.