Inspiration
The idea for Hito came from a very real, very human problem right here in Medellín. I noticed that freelancers—like Laura, a local designer—weren't losing money because they didn't know how to generate an invoice. They were losing money because asking for it is an emotional burden. Writing that awkward "just a gentle reminder" email often gets delayed, softened, and ultimately sent to a client who has learned that being late has no consequences. I wanted to build a system that takes the emotion out of getting paid by automating the entire contract-to-cash pipeline.
How we built it
Hito is designed to be a deeply integrated workflow, not just a thin wrapper around a language model. I built it to prioritize privacy, deterministic safety, and real financial utility: Backend & Database: Python, FastAPI, and SQLite handle the core logic and state management.
Frontend: React and AG Grid provide a responsive, data-rich user interface.
AI Engine: Qwen2.5 3B Instruct runs entirely locally through Ollama on a laptop CPU. This ensures the contract never leaves the machine—meaning zero API keys, no per-token billing, and absolute data privacy.
Payment Infrastructure: The financial rails are built on PayPal Invoicing v2 and Payouts v1. The system listens for signature-verified PayPal webhooks to detect when a payment arrives, and seamlessly splits the funds among collaborators using the Payouts API.
Challenges we ran into
Building an autonomous financial agent meant I couldn't just trust the AI to do everything right. The biggest challenges involved reigning in the LLM's non-deterministic nature and navigating payment flows:
Math and Hallucinations: LLMs are notoriously bad at arithmetic. I had to architect the system so the model never does the math. All payment splits and remainders are calculated using pure Python Decimal logic, reconciled to ensure payouts never exceed the original payment.
Safeguarding Agent Actions: The agent that parses the contract and drafts the invoice cannot approve it. I implemented seven deterministic code checks to block it, plus an independent model pass that verifies quoted clauses against the actual contract text. If the model hallucinates a convincing paraphrase, or wrongly claims a reminder is a "final reminder," the system catches it and flags it for the user rather than rewriting it behind their back.
PayPal API Complexities: Integrating the PayPal REST API sandbox involved navigating complex bidirectional transfer constraints, debugging UNCLAIMED statuses for receiver accounts, and managing OAuth 2.0 authentication flows for batch payouts.
Accomplishments that we're proud of
100% Local AI: Running Qwen2.5 3B entirely on a laptop CPU via Ollama, ensuring zero API costs and absolute data privacy.
Deterministic Guardrails: Constraining the LLM with 7 strict code checks and a secondary model pass so it never hallucinates clauses or acts unsupervised.
Custom ML Risk Model: Building a logistic regression model from scratch in pure Python to dictate reminder tones based on real payment probabilities, not AI guesses.
Flawless Financial Math: Using strict Python Decimal logic for splits and reconciliation so the LLM never touches the numbers.
End-to-End PayPal Integration: Seamlessly connecting Invoicing v2, Payouts v1, OAuth 2.0, and signature-verified webhooks into a fully automated pipeline.
What we learned
Tone is risk, not style: We learned to use traditional machine learning (logistic regression) rather than AI prompts to dictate reminder tones based on real payment probabilities.
Keep AI away from math: We learned that LLMs cannot be trusted with financial arithmetic; strict deterministic code is mandatory for calculating splits and remainders.
Wrap AI in strict guardrails: The most reliable AI applications don't replace standard logic—they are securely wrapped within it to catch hallucinations and prevent unauthorized actions.
What's next for Hito
Broader Payment Rails: Expanding beyond PayPal to integrate Stripe and local LatAm payment networks (like PSE or Pix) for easier cross-border payments.
Bilingual Support: Natively parsing contracts and sending automated, risk-adjusted emails in Spanish, honoring our Medellín roots.
Predictive Dashboards: Evolving our logistic regression risk model into a visual cash flow forecaster so freelancers know exactly when to expect their money.
Built With
- fastapi
- javascript
- ollama
- paypal
- python
- react