Tourtoise

-- ✅ filters first, similarity within candidates, rerank after
WITH candidates AS (
  SELECT d.id, d.name
  FROM destinations d
  WHERE d.country = :country
    AND d.tags && :interests      -- structured half
    AND d.season_ok(@:travel_month)
)
SELECT c.content, c.embedding <=> :query_vec AS dist  -- semantic half
FROM destination_chunks c
JOIN candidates cd ON cd.id = c.destination_id
ORDER BY dist
LIMIT 24;   -- → rerank(candidates, keep=8) in Python

class TripState(BaseModel):
    prefs: Preferences
    visited: set[str] = set()
    budget_left: Decimal

    def lock(self, poi_id: str, cost: Decimal) -> bool:
        if poi_id in self.visited or cost > self.budget_left:
            return False
        self.visited.add(poi_id)
        self.budget_left -= cost
        return True

# ✅ one state object, validated at every handoff
async def plan_trip(trip):
    state = TripState(prefs=await pref_agent.interview(trip))
    for day in range(trip.length):
        await planner_agent.draft_day(trip, day, state)  # shares state
    TripState.model_validate(state)  # contract check

# ✅ budget is a guardrail, checked before persist
async def validate_budget(trip, items) -> Budget:
    total = sum(i.cost_est for i in items)
    if total > trip.prefs.budget_total * OVERSHOOT:
        swaps = await propose_swaps(items, deficit=total - trip.prefs.budget_total)
        raise BudgetExceeded(swaps=swaps)
    return Budget(planned_total=total, currency=trip.currency)