KizilelmaAI

Problem

I worked in the finance track of the BTK Academy Hackathon 2026. The concrete problem I took on: someone trying to manage a budget under high inflation struggles to sort their own spending into meaningful categories, and then to get from that list to an actionable plan. Keeping a spreadsheet solves the data-entry problem but not the interpretation problem. My goal was a backend that takes free-text expense lines, categorises them, and can then produce a budget plan grounded in Turkish economic conditions.

Approach

A FastAPI backend exposes four endpoints: /chat (multi-turn conversation), /harcama-analiz (agentic categorisation plus report), /butce-olustur (budget plan) and /health. The model is gemini-2.5-flash, accessed through the google-genai SDK. Rather than leaving categorisation to free text, I declared it as a function declaration: the kategorize_harcama tool must pick a category from a closed enum (groceries, transport, rent, bills, entertainment, health, clothing, education, savings, other), pick a risk level from three, and return a short recommendation. The analysis flow runs in two passes: the first call produces tool calls, the code collects them and counts the category distribution, and the second call feeds that distribution back into the prompt to write the markdown report. The frontend is React 18 + Vite; conversation history arrives from the client and build_contents converts it into Gemini's user/model role format, so the server keeps no session state.

Decisions and trade-offs

• 01I did categorisation through Gemini function calling rather than free text (types.FunctionDeclaration with an enum-constrained types.Schema), because I wanted categories drawn from a fixed set and required fields guaranteed by the schema; the alternative was asking the model for JSON, which lets category names drift between runs and forces you to hand-catch parse failures.
• 02I split expense analysis into two calls: a tool-call pass first, then a report pass where the collected category distribution is fed back into the prompt. Asking for structured category output and a long markdown report in a single turn weakened both; the alternative was one call, and I traded one extra request of latency for a cleaner separation.
• 03I set temperature per endpoint: 0.7 for chat, 0.3 for expense analysis, 0.4 for budgeting. Chat wants fluency while categorisation and reporting want consistency; the alternative of one global temperature made either the chat wooden or the analysis loose.
• 04I collected the system prompt into a single constant and wrote explicit limits into it (give no definitive investment advice, stay within general information, politely decline non-finance questions). In a finance context the model drifts into an advisory register on its own; the alternative was scattering those limits across each endpoint's prompt, which made the boundaries inconsistent between endpoints.
• 05When no API key is present I leave the client as None and let endpoints return 500, because failing loudly beats quietly emitting a fake or empty answer; the alternative was returning a canned default, which during a demo could be mistaken for a real response.

Outcome

NO MEASUREMENT — I can't claim a number here, because the repo has no tests, no evaluation set and no recorded runs. What concretely exists: a working four-endpoint FastAPI service (chat, expense analysis, budget creation, health), one enum-constrained tool declaration, the two-pass analysis flow, per-endpoint temperature settings, and a React 18 + Vite frontend. The /harcama-analiz response returns the analysis text alongside the total spend, the category distribution and how many agent calls were made (agent_calls) — so the agentic behaviour is reported back to the client in a measurable form. The repo's CLAUDE.md records the competition calendar: submission 2026-05-19, preliminary jury 2026-05-20 to 05-30, jury presentation 2026-06-05. There is NO competition result, score or placement in the repo, and this page claims none. An honest note on technical debt: frontend/src still carries unused leftovers from Vite's vanilla-TypeScript template (main.ts, counter.ts, style.css, assets/typescript.svg) — index.html only loads /src/main.jsx, so those are dead files.

Stack