jigyasa-grover/startup-on-a-shoestring

Startup on a Shoestring is a Python demo that shows how to enforce strict cost and token budgets on an AI agent, framed as the challenge of building an MVP landing page with only fifty cents to spend. The core of the project is a budget monitor built on the Google Antigravity SDK that intercepts the agent's execution at each step and shuts it down before it overspends. The monitor plugs into lifecycle hooks provided by the SDK. Before each turn, it checks whether the cumulative spend has crossed a threshold and blocks execution if it has. After each tool call, it records what the agent produced and updates the running cost tally. Four policy rules engage automatically as the budget gets used up: at 50% spend, older conversation history gets trimmed to avoid the context growing too large, at 80%, temperature is forced to zero to stop creative reasoning loops, also at 80%, the model's reasoning budget gets restricted to conserve the final fraction of the allowance, and at 100%, execution halts immediately with an error. Costs are calculated in real time using Gemini pricing. The monitor tracks per-turn usage (the delta between this turn's total and the last checkpoint) as well as the cumulative total across the whole session. It also measures turn latency, tokens per second, and a runway estimator showing how many tokens remain. A FastAPI web dashboard shows all of this updating in real time. You can run two simulation modes from the dashboard: one with a 2500-token limit where the agent successfully ships a landing page, and one with a 1000-token limit where the budget guardrail triggers mid-build and locks the screen with an error overlay. A live mode requires a Gemini API key and connects to a real model. The project includes a detailed tutorial document alongside the code explaining the architecture and the design decisions behind the budget policy system.