Headroom

Current terms: a $120,000 job reaches −$13,000 in the delayed collection scenario, leaving a $23,000 gap to the reserve.
Proposed terms: move $23,000 into the deposit; keep the $120,000 total and preserve the $10,000 reserve in both declared scenarios.
benchmark
benchmark

Inspiration

A profitable job can still miss payroll.

A small contractor wins a $120,000 project. It looks like growth—until materials must be bought now, payroll lands on Friday, and the customer pays only after an inspection, an invoice, and a collection delay.

The owner needs an answer to one consequential question:

“Can we take this job without borrowing or missing payroll—and what would make it work?”

We built Headroom around that moment: help a business create room for its next yes.

What it does

Headroom turns a company's books, reviewed commitments, payment terms, and supporting evidence into an inspectable cash decision. It shows where cash falls short, why it happens, and the smallest supported payment change within the allowed options.

In our flagship demonstration:

A $120,000 job pushes the worst modeled cash balance to −$13,000.
Headroom finds a $23,000 timing change: move money from the final installment into the deposit.
The schedule changes from $42k / $30k / $48k to $65k / $30k / $25k.
Revenue stays $120,000. The worst balance reaches the required $10,000 reserve across both declared collection scenarios.
One cent less fails within that permitted adjustment family.

This becomes a concrete proposal the owner can discuss with the customer, with its assumptions and evidence visible. It does not silently execute payments or change the contract.

Headroom also tests the uncomfortable cases. Two supplier overruns can each look affordable while their combination breaches the reserve. Missing payroll-tax information blocks a supported verdict. Permission to invoice is never confused with money already in the bank.

Try the live workspace: headroom-lahacks.vercel.app

How we built it

Interpretation learns; financial authority stays in code. We gave each layer a narrow responsibility.

1. Books → a grounded starting position. Our adapter reconstructs 2,419 rows of Intuit's supplied synthetic bank data into a $74,882.38 starting balance, with provenance and the available-cash assumption exposed. The future job and commitments are disclosed constructed additions; this is not a live QuickBooks connection.

2. Contracts → typed proposals. We fine-tune Qwen through Veri to propose structured payment rules: source and amount references, nested AND/OR conditions, invoice clocks, and explicit ambiguity. Schema, reference, and business-rule validation precede owner review. An extractor cannot invent a balance or activate a financial term.

3. Evidence → repeatable judgments. TypeSafe's Jev evaluates small questions: is this prerequisite met, not met, unknown, or conflicting? Eligibility, actual invoice issuance, contractual due date, and bank settlement remain separate events.

4. Scenarios → exact arithmetic. A deterministic TypeScript engine uses integer cents, dated obligations, conservative same-day ordering, and bounded joint scenarios. Every proposed adjustment conserves the contract total and is recalculated against every declared case.

5. Experience → a measured MetaHarness. Anthropic Claude proposes bounded changes to evidence selection, batching, and dependency-aware caching. A separate fixed evaluator accepts a candidate only if useful coverage and correctness survive. The candidate cannot rewrite expected answers, financial rules, or its own pass criteria.

6. Failures → observable fixes. Sentry connects errors, source maps, traces, AI spans, logs, and masked Replay. Its evidence helped us fix a real oversized-response defect and add input, computation, and output bounds.

The application uses Next.js, React, and TypeScript on Vercel. The public demo calculates cash decisions from reviewed structured inputs and replays genuine recorded provider experiments; visitors do not allocate GPUs or spend model credits.

Challenges we ran into

The hardest problems were the distinctions that make an answer trustworthy. “Eligible to invoice,” “invoice issued,” “payment due,” and “cash received” can be weeks apart. A misplaced OR can change whether payment is even claimable. Unknown is not zero, and a successful model response is not verified evidence.

Our V4 fine-tuned extractor improved JSON formatting but failed the business-quality gate. We rejected it. Its failures led to a new 336-example V5 corpus, separately reviewed 24-case development and 48-case final sets, a tokenizer audit, and stricter absolute usefulness thresholds. V5 completed 300 training steps through Veri. Its first export regressed; rebuilding the same saved adapter on the pinned BF16 base improved development from 9/24 to 15/24 material-exact outputs. We froze that candidate before final queries.

The final comparison is complete. Both models received the same 48 untouched synthetic clauses, prompts, schema and decoding:

Final outcome	Base	V5 tuned export
Material-exact outputs	13/48	28/48
Fully valid outputs	41/48	45/48
Correct supported proposals	9/32	19/32
Incorrect validated proposals (lower is better)	21	14

Measured improvement; not promoted. Fourteen validated proposals still contain material mismatches, supported coverage misses the 26/32 floor, and both uncertainty classes miss 7/8 status accuracy. Ambiguous-status accuracy falls from 7/8 to 6/8. Our fixed gate rejects promotion; the cash demo retains reviewed inputs. All 96 actual final responses and scores are public. This measures the trained/exported pipeline on a small synthetic test, not general customer-contract accuracy.

We also built bounded spending, durable experiment records, and resource-cleanup checks so experiments remain affordable and recoverable.

Accomplishments we're proud of

An actionable business outcome: an exact, conserved payment proposal that moves the worst modeled cash point from −$13k to a $10k reserve.
A real, measured MetaHarness improvement: Jev requests fell 18 → 6, and input tokens fell 12,666 → 3,998, while preserving 20/21 correct judgments, 15/21 decisive judgments, and zero false MET judgments across seven synthetic evidence updates. The remaining error is published too. This is one fixed workload, not a general accuracy or speed claim.
Measured model learning: V5 more than doubled material-exact final outputs (13/48 → 28/48) and correct supported proposals (9/32 → 19/32). The stricter gate still rejects promotion; every response and remaining error is preserved.
Observability that changed the implementation: a Sentry-investigated response-expansion defect produced 83,662,869 bytes in development. The corrected production regression returned 428,167 bytes, retaining all 256 scenario summaries and the worst-case timeline. These are response-size measurements in separate environments, not a latency benchmark.
Reproducible evidence: public source, synthetic training data, frozen evaluation cases, actual predictions, source provenance, and a no-key demo rehearsal command.
A coherent visual direction: Paper helped us create 11 product and storyboard artboards, implementation references, and cash-chart geometry derived from the engine. The launch film is the next production step.

What we learned

Self-improvement needs a fixed definition of better. More valid JSON does not mean more correct interpretation. Fewer model calls matter only when correctness and useful coverage survive.

A useful financial agent also makes uncertainty actionable. “We need the payroll-tax amount” gives an owner a next step. A confident number with an invisible assumption does not.

What's next for Headroom

Our next milestones are verified QuickBooks ingestion, invoice-to-bank matching, stronger Boolean-condition and uncertainty handling on a broader independently adjudicated corpus, and a sharper collaborative frontend and demo film. The exposed V5 final remains historical evidence; the next candidate needs a new untouched test. We have prepared a 33-source California research pack for future cited obligation discovery; retrieval is not integrated, and jurisdiction must be checked before applying it to a business.

We will expand the independently adjudicated corpus while preserving the reviewed financial engine and owner-approval boundary. The goal is an assistant that earns more responsibility through evidence.

Try Headroom · Explore the code and evidence

Demo boundaries: supplied synthetic books plus disclosed constructed future scenarios; no live customer outcome claim. The two collection paths are declared cases, not an exhaustive forecast. Proposed terms still require agreement and actual settlement.