Source: HackerNews brain

Build a type-safe financial extraction engine with Pydantic AI structured output, where field validators catch bad invoice math at runtime.

Khi một endpoint có tới 6–8 query param, lặp lại Annotated ở từng endpoint vừa dài dòng vừa dễ sót ràng buộc. FastAPI có tính năng Query Parameter Model: gom toàn bộ query params vào một Pydantic BaseModel, rồi khai báo filters: Annotated — FastAPI tự validate, tự sinh tài liệu /docs, mọi endpoint chỉ còn một tham số.

> Part of a series on building **Balance** , a portfolio rebalancing app, as a solo developer. Balance started as a Brazilian-only app: B3 tickers, prices in reais, Brazilian income tax. Then came US stocks. Then crypto. The naïve path would have been three apps glued together — three price fetchers, three sets of forms, three rebalancing engines. Instead, the whole thing pivots on a single field: class Portfolio(BaseModel): market = models.CharField( max_length=6, choices=[('BR', 'Brasil'), ('US', 'Estados Unidos'), ('CRYPTO', 'Cripto')], default='BR', ) `market` is the one axis of variation. Everything market-specific branches on it — and crucially, the **rebalancing engine itself doesn't.** Let me show where the branches live and why the core stays untouched. ## Where the code actually differs Three markets differ in four concrete places: Concern | BR | US | Crypto ---|---|---|--- Price source | BRAPI → Yahoo (`.SA`) | Yahoo (direct) | Binance Currency symbol | R$ | $ | $ Tax rules | IR (20k exemption) | Capital Gains (FIFO) | IR cripto (35k) Quantity precision | whole shares | whole shares | 8 decimals Notice what's _not_ on that list: the rebalancing math, the category/target model, the deposit flow, the snapshots. That's ~90% of the domain, shared verbatim. ## Branch 1: price routing The price service picks a source from the portfolio's market. The trick is keeping the _interface_ identical — every path returns a `Decimal | None`: def _fetch_price(self, ticker: str, market: str) -> Decimal | None: if market == 'CRYPTO': return fetch_crypto_price(ticker) # Binance, no .SA if market == 'US': return self._fetch_yahoo(ticker) # AAPL, not AAPL.SA # BR: BRAPI first, Yahoo with .SA as fallback return self._fetch_brapi(ticker) or self._fetch_yahoo(f'{ticker}.SA') Callers never know which source answered. They get a price or a `None`, and the cache (`MarketPrice`) sits in front of all three. New market = new branch here, nothing else in the pipeline changes. ## Branch 2: market-aware forms A US ticker is `AAPL`. A Brazilian one is `PETR4`. A crypto one is `BTC`. The form adapts its validation, asset-class choices and currency labels from the portfolio's market: class AssetForm(forms.ModelForm): def __init__(self, *args, market='BR', **kwargs): super().__init__(*args, **kwargs) if market == 'US': self._ticker_re = r'^[A-Z]{1,6}$' self.fields['asset_class'].choices = STOCK_ETF_ONLY self.fields['current_price'].label = 'Price ($)' elif market == 'CRYPTO': self._ticker_re = r'^[A-Z]{2,10}$' self.fields['quantity'].widget.attrs['step'] = '0.00000001' else: # BR self._ticker_re = r'^[A-Z]{3,6}\d{0,2}$' Same `ModelForm`, three personalities. The view just passes `market=portfolio.market`. ## Branch 3: precision (the sharp edge) This is the one that bites. A stock quantity of `2` is fine in `decimal_places=2`. A crypto quantity of `0.00123456` silently rounds to `0.00`. The fix was to widen the precision everywhere money or quantity flows — `Asset.quantity`, `current_price`, `avg_cost`, `MarketPrice.price`, `Transaction` fields — all to `max_digits=20, decimal_places=8`. But that would over-format stocks ("2.00000000 shares"). So the _display_ branches, while the _storage_ doesn't: {% if is_crypto %} {{ asset.quantity|floatformat:"-8" }} {# 0.00123456 #} {% else %} {{ asset.quantity|floatformat:"0" }} {# 2 #} {% endif %} `floatformat:"-8"` strips trailing zeros, so `1.50000000` shows as `1.5`. Store wide, render narrow. ## Branch 4: the rebalancing engine _almost_ doesn't branch I said the engine is shared — that's 95% true. The one place it peeks at `market` is where whole-share assumptions break: if self.portfolio.market == 'CRYPTO': quantity = (budget / price).quantize(Decimal('0.00000001')) # fraction else: quantity = int(budget / price) # whole units That's it. Two or three of these guards across the whole service. Everything else — gap calculation, budget distribution, leftover spending — is market-agnostic because it works in _money_ , and money is the same shape in every market. ## The trade-off I'd flag The honest downside: `if market == 'CRYPTO'` sprinkled across the codebase is a smell that's tolerable at three markets and would rot at ten. If a fourth market with genuinely different mechanics showed up (say, options), I'd refactor those branches into a strategy object — `market.quantize(budget, price)` — rather than keep growing the conditionals. But premature abstraction has its own cost. At three markets, the branches are few, local, and obvious. Designing a pluggable "market backend" architecture on day one would have been more code to serve a flexibility I didn't yet need. The principle that held up: **model the axis of variation explicitly (`market`), branch where behavior genuinely differs, and keep the shared core working in the most general currency you have — money.** _Balance runs Brazilian, US and crypto portfolios through one rebalancing engine, with a consolidated dashboard that converts everything to a single currency. Link in profile. How do you handle multi-tenant-style variation in your apps — branching or strategy objects? Curious in the comments._

> Parte de uma série sobre construir o **Balance** , um app de rebalanceamento de carteira, como dev solo. O Balance começou como um app só do Brasil: tickers da B3, preços em reais, IR brasileiro. Depois vieram ações dos EUA. Depois cripto. O caminho ingênuo teria sido três apps colados — três buscadores de preço, três conjuntos de formulários, três motores de rebalanceamento. Em vez disso, tudo gira em torno de um único campo: class Portfolio(BaseModel): market = models.CharField( max_length=6, choices=[('BR', 'Brasil'), ('US', 'Estados Unidos'), ('CRYPTO', 'Cripto')], default='BR', ) `market` é o único eixo de variação. Tudo que é específico de mercado ramifica nele — e, crucialmente, o **motor de rebalanceamento em si não ramifica.** Deixa eu mostrar onde os branches vivem e por que o núcleo fica intocado. ## Onde o código realmente difere Três mercados diferem em quatro pontos concretos: Aspecto | BR | US | Cripto ---|---|---|--- Fonte de preço | BRAPI → Yahoo (`.SA`) | Yahoo (direto) | Binance Símbolo de moeda | R$ | $ | $ Regras de IR | IR (isenção 20k) | Capital Gains (FIFO) | IR cripto (35k) Precisão de quantidade | ações inteiras | ações inteiras | 8 casas Repare no que _não_ está na lista: a matemática do rebalanceamento, o modelo de categoria/meta, o fluxo de aporte, os snapshots. Isso é ~90% do domínio, compartilhado idêntico. ## Branch 1: roteamento de preço O serviço de preço escolhe a fonte pelo mercado da carteira. O truque é manter a _interface_ idêntica — todo caminho retorna `Decimal | None`: def _fetch_price(self, ticker: str, market: str) -> Decimal | None: if market == 'CRYPTO': return fetch_crypto_price(ticker) # Binance, sem .SA if market == 'US': return self._fetch_yahoo(ticker) # AAPL, não AAPL.SA # BR: BRAPI primeiro, Yahoo com .SA como fallback return self._fetch_brapi(ticker) or self._fetch_yahoo(f'{ticker}.SA') Os callers nunca sabem qual fonte respondeu. Eles recebem um preço ou um `None`, e o cache (`MarketPrice`) fica na frente das três. Novo mercado = novo branch aqui, nada mais no pipeline muda. ## Branch 2: formulários conscientes do mercado Um ticker dos EUA é `AAPL`. Um brasileiro é `PETR4`. Um de cripto é `BTC`. O formulário adapta validação, choices de classe e labels de moeda a partir do mercado da carteira: class AssetForm(forms.ModelForm): def __init__(self, *args, market='BR', **kwargs): super().__init__(*args, **kwargs) if market == 'US': self._ticker_re = r'^[A-Z]{1,6}$' self.fields['asset_class'].choices = STOCK_ETF_ONLY self.fields['current_price'].label = 'Preço ($)' elif market == 'CRYPTO': self._ticker_re = r'^[A-Z]{2,10}$' self.fields['quantity'].widget.attrs['step'] = '0.00000001' else: # BR self._ticker_re = r'^[A-Z]{3,6}\d{0,2}$' O mesmo `ModelForm`, três personalidades. A view só passa `market=portfolio.market`. ## Branch 3: precisão (a aresta afiada) Esse é o que morde. Uma quantidade de ações `2` cabe em `decimal_places=2`. Uma quantidade de cripto `0.00123456` arredonda silenciosamente pra `0.00`. A correção foi alargar a precisão em todo lugar onde dinheiro ou quantidade passa — `Asset.quantity`, `current_price`, `avg_cost`, `MarketPrice.price`, campos de `Transaction` — tudo para `max_digits=20, decimal_places=8`. Mas isso formataria ações demais ("2.00000000 ações"). Então o _display_ ramifica, enquanto o _armazenamento_ não: {% if is_crypto %} {{ asset.quantity|floatformat:"-8" }} {# 0.00123456 #} {% else %} {{ asset.quantity|floatformat:"0" }} {# 2 #} {% endif %} `floatformat:"-8"` remove zeros à direita, então `1.50000000` vira `1.5`. Guarda largo, mostra estreito. ## Branch 4: o motor de rebalanceamento _quase_ não ramifica Eu disse que o motor é compartilhado — isso é 95% verdade. O único ponto em que ele olha o `market` é onde a suposição de "ações inteiras" quebra: if self.portfolio.market == 'CRYPTO': quantity = (budget / price).quantize(Decimal('0.00000001')) # fração else: quantity = int(budget / price) # unidades inteiras É isso. Dois ou três desses guardas no serviço inteiro. Todo o resto — cálculo de gap, distribuição de orçamento, gasto do troco — é agnóstico ao mercado porque trabalha em _dinheiro_ , e dinheiro tem a mesma forma em todo mercado. ## O trade-off que eu sinalizo A desvantagem honesta: `if market == 'CRYPTO'` espalhado pelo código é um cheiro tolerável com três mercados e que apodreceria com dez. Se um quarto mercado com mecânica genuinamente diferente aparecesse (digamos, opções), eu refatoraria esses branches num objeto de estratégia — `market.quantize(budget, price)` — em vez de seguir engordando os condicionais. Mas abstração prematura tem seu próprio custo. Com três mercados, os branches são poucos, locais e óbvios. Projetar uma arquitetura plugável de "backend de mercado" no dia 1 seria mais código pra servir uma flexibilidade que eu ainda não precisava. O princípio que se sustentou: **modele o eixo de variação explicitamente (`market`), ramifique onde o comportamento genuinamente difere, e mantenha o núcleo compartilhado trabalhando na moeda mais geral que você tem — dinheiro.** _O Balance roda carteiras brasileiras, americanas e cripto por um só motor de rebalanceamento, com dashboard consolidado que converte tudo numa moeda. Link no perfil. Como você lida com variação tipo multi-tenant nos seus apps — branch ou objeto de estratégia? Curioso nos comentários._

app_code = r''' import os, json, uuid import streamlit as st from typing import TypedDict, List, Dict, Any, Optional from pydantic import BaseModel, Field from openai import OpenAI from langgraph.graph import StateGraph, START, END from langgraph.types import Command, interrupt from langgraph.checkpoint.memory import InMemorySaver def tool_search_flights(origin: str, destination: str, depart_date: str, return_date: str, budget_usd: int) -> Dict: options = [ {"airline": "SkyJet", "route": f"{origin}->{destination}", "depart": depart_date, "return": return_date, "price_usd": int(budget_usd*0.55)}, {"airline": "AeroBlue", "route": f"{origin}->{destination}", "depart": depart_date, "return": return_date, "price_usd": int(budget_usd*0.70)}, {"airline": "Nimbus Air", "route": f"{origin}->{destination}", "depart": depart_date, "return": return_date, "price_usd": int(budget_usd*0.62)}, ] options = sorted(options, key=lambda x: x["price_usd"]) return {"tool": "search_flights", "top_options": options[:2]} def tool_search_hotels(city: str, nights: int, budget_usd: int, preferences: List) -> Dict: base = max(60, int(budget_usd / max(nights, 1))) picks = [ {"name": "Central Boutique", "city": city, "nightly_usd": int(base*0.95), "notes": ["walkable", "great reviews"]}, {"name": "Riverside Stay", "city": city, "nightly_usd": int(base*0.80), "notes": ["quiet", "good value"]}, {"name": "Modern Loft Hotel", "city": city, "nightly_usd": int(base*1.10), "notes": ["new", "gym"]}, ] if "luxury" in : picks = sorted(picks, key=lambda x: -x["nightly_usd"]) else: picks = sorted(picks, key=lambda x: x["nightly_usd"]) return {"tool": "search_hotels", "top_options": picks[:2]} def tool_build_day_by_day(city: str, days: int, vibe: str) -> Dict: blocks = [] for d in range(1, days+1): blocks.append({ "day": d, "morning": f"{city}: coffee + a must-see landmark", "afternoon": f"{city}: {vibe} activity + local lunch", "evening": f"{city}: sunset spot + dinner + optional night walk" }) return {"tool": "draft_itinerary", "days": blocks} ''' …