{"slug": "how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week", "title": "How much should an LLM decide? Building an avatar that reviews your training week with FastAPI, Gemini and Jev, a judge model", "summary": "A developer built loadline, a FastAPI web app that imports Apple Watch workouts and has a 3D avatar deliver a weekly training review, with Gemini writing the avatar's lines and a judge model called Jev checking them before they are spoken. The design splits work so that code, not the LLM, makes every numeric judgment: fatigue is derived from fitness and fatigue exponential moving averages over 42 and 7 days, and weekly load is compared against the user's own nine-week average, with Gemini receiving those results and only writing the words. The developer said the split was needed because a wrong comparison could lead to wrong advice, and because the same records should always produce the same judgment so it can be tested.", "body_md": "loadline is a web app that reviews your training week with an avatar. It imports the workouts you record on an Apple Watch. Once a week, a 3D avatar speaks a short review of the week: how tired you are, and how much you trained compared with your usual weeks. It then shows two or three options for the next week, and one of them is always to rest or train easy.\n\nYou can try the app without signing up. Click \"Try as a guest\" on the sign-in screen, and the app opens a dashboard with demo data and a weekly review.\n\nThe backend is FastAPI. Gemini writes the avatar's lines, and Jev, a judge model that only returns probabilities, checks them before the avatar speaks. This post is about the question I spent the most time on while designing it: how much should the LLM decide?\n\nThe simplest design sends a week of records to Gemini and asks it for a review. Gemini then has to compare numbers on its own, such as this week's training load against the average of the past nine weeks, or fitness against fatigue. An LLM can get a comparison like that wrong, and the review still sounds confident.\n\nIn this app, a wrong comparison leads to wrong advice. If the model reads a hard week as an easy one, the avatar may tell a tired user to train more.\n\nI also wanted two properties that an LLM does not give on its own. The same records should always produce the same judgment, so that I can test it. And the weekly review should always be created, even when Gemini is busy or Jev does not respond.\n\nSo I split the work. Code makes every judgment that involves numbers, Gemini writes the words, and code decides whether the avatar can use those words.\n\nA weekly review goes through four steps.\n\nOnly steps 2 and 3 use AI.\n\nCode makes two judgments from the records. Both are plain functions in `domain/`, so the same records always give the same result, and unit tests cover them.\n\nThe first judgment asks whether the user is tired. The app computes daily training load from heart rate, and then fitness and fatigue as exponential moving averages of that load over 42 days and 7 days. Form is fitness minus fatigue. `domain/situation.py` divides form by fitness and maps the ratio to `fatigued`, `fresh` or `steady`. Because it uses a ratio, the same thresholds work regardless of how high the user's fitness is. Weeks with too few records, weeks without training, and weeks right after a break get their own values (`not_enough_data`, `no_training`, `returning`) before the ratio is checked.\n\nThe second judgment compares the week's load with the user's own average over the past nine weeks (`domain/effort.py`). Below 0.8 is `light`, 1.5 or above is `heavy`, and anything between is `usual`.\n\nCode also decides whether Gemini may offer more training as an option. After a `heavy` week, the answer is no. Gemini receives this answer together with the two judgments and numbers that code has already computed, such as the number of workouts and the change from the previous week. Gemini never has to compare numbers itself.\n\nGemini decides what the avatar says and how it says it. The request has three parts (`domain/review_prompt.py`, `adapters/gemini.py`).\n\n`system_instruction` in the Gemini API): rules such as never contradicting the judgments, encouragement first, no medical advice, always one option to rest or train easy, and a line that takes about 15 seconds to speak\nThe system prompt states the split directly: \"`situation` was decided by our own code from the numbers. Trust it and never contradict it.\"\n\nReading the numbers aloud adds little, because the dashboard already shows them. So the system prompt lists six well-known training principles and asks Gemini to pick the one that fits the judgments and use it as the reason for its advice. One of them is \"Weeks of steady training add up to more than one big week.\" The prompt also limits numbers: the first sentence of the line has none, and the whole line mentions at most one. VO2max goes to Gemini only as a trend (up, flat or down), not as a value.\n\nHere is the line Gemini wrote for the demo user's latest week. The code judged the week as `steady` with training `usual`, and the user's notes mention a race:\n\nYou kept your routine going smoothly after the race, and that consistency is wonderful. Weeks of steady training add up to more than a single big effort, and your body is responding nicely to the regular work.\n\nFifteen seconds is too short to explain the reasoning, so Gemini also writes an explanation of 80 to 120 words. The app shows it only when the user opens \"Read more\", and the avatar does not read it aloud.\n\nJev (by TypeSafe AI) is a model for judgments only and does not write text. You send it a text and some yes-or-no questions, and it returns the probability of \"yes\" for each question. The code decides what to do with those probabilities.\n\nAfter Gemini writes the review, code joins the line with the labels and descriptions of the options and sends the text to Jev with three questions (`domain/line_check.py`):\n\nThe third question counts only in weeks where code has already decided not to offer more training. The system prompt gives Gemini the same rule, but code checks it again instead of relying on the prompt.\n\nIf any of these probabilities is 0.35 or higher, the app does not use Gemini's line and switches to the fallback lines. The threshold is below 0.5 so that the app also drops lines that Jev is unsure about.\n\nJev also reads the user's notes before the request to Gemini and answers whether they mention pain or sickness (`domain/note_check.py`). If the probability is 0.35 or higher, code sets a health flag, and options to raise volume or intensity are no longer candidates.\n\nThe same call that checks the line also asks Jev which expression fits it: happy, relaxed, sad or surprised. Jev returns its choice with a confidence. If the confidence is below 0.6, code uses the calm expression, relaxed (`domain/expression.py`).\n\nGemini can be busy, Jev can time out, and Gemini can return a line that breaks the length rules. The app handles all of these cases in the same way.\n\nThe code that calls external services lives in `adapters/`. When a call fails for any reason, the adapter logs the reason and returns `None`. The Gemini adapter, for example, tries the models in order from the newest generation to older ones. It moves to the next model on a 429, a 5xx or a network error, and it retries the same model once if the JSON fails the checks on length and the number of options. It returns `None` after a timeout, an authentication error, or when no model gives a valid answer.\n\nThe service in `services/reviews.py` only sees `None`. It does not know why the call failed, and it does not need to. For any `None` from Gemini or Jev, and for any line that Jev flags, it uses the fallback lines in `domain/fallback_review.py`. A line that Jev could not check counts as a line that failed the check. The fallback lines are prepared in English and Japanese and chosen to match the two judgments, so even a fallback review fits the week.\n\nAs a result, a weekly review is always created. If the voice cannot be generated either, the app saves the review without audio and shows only the captions.\n\nThe split between code and AI also decides the folder structure of the backend (`api/app/`).\n\n| Folder | What it does | What it does not do | \n|---|---|---|\n| `routers/` | Receives requests, checks who the user is, and calls `services/` | Calculations or judgments | \n| `services/` | Loads data from the DB, calls `domain/` and`adapters/` in order, and saves the results | Detailed calculations or judgments | \n| `domain/` | Calculations and judgments, such as the two judgments and whether a line can be used | Access to the DB or external services | \n| `adapters/` | Calls Gemini, Jev, `tts/` , Cloud Text-to-Speech and Cloud Storage | Judgments | \n\n`services/` does not import Gemini or Jev. It defines Protocols such as `ReviewWriter` and `LineChecker` and depends only on them. The only place that connects these Protocols to the real adapters is `routers/deps.py`, through FastAPI's `Depends`:\n\n``` php\n@lru_cache\ndef get_review_writer() -> ReviewWriter | None:\n    return gemini_writer(get_settings())\n\nReviewWriterDep = Annotated[ReviewWriter | None, Depends(get_review_writer)]\n```\n\nThe return type allows `None`. When the Gemini project is not configured, `get_review_writer` returns `None`, and the service uses the fallback lines, in the same way as when a call fails.\n\nIn tests, `app.dependency_overrides` replaces these providers. The API tests set them to `None`, so every review in those tests uses the fallback lines. The service tests pass fakes that return fixed answers, so they can check what happens when Jev flags a line without calling Jev. When I added Japanese voices, the change was one more adapter for Google's Text-to-Speech behind the same `Speaker` Protocol.\n\nThis split is not proven yet. I plan to keep using loadline with my own training records and check whether the weekly reviews match how my body actually feels. The thresholds for fatigue and the system prompt will change based on what I find.\n\nTwo smaller changes are also on my list. The avatar appears full-body and small on the dashboard, so its expression is hard to see, and I want to show it closer. Jev already returns a confidence for the expression, so the avatar could also show a stronger or softer expression depending on that confidence.\n\nIf you have built an app where an LLM gives advice, I would like to hear how you decided what to leave to the model. The demo and the source code are linked at the top of this post.", "url": "https://wpnews.pro/news/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week", "canonical_source": "https://dev.to/iotarduino/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week-with-fastapi-40fg", "published_at": "2026-11-22 06:33:30+00:00", "updated_at": "2026-11-22 06:42:32.755773+00:00", "lang": "en", "topics": ["large-language-models", "ai-agents", "ai-tools", "developer-tools"], "entities": ["loadline", "FastAPI", "Gemini", "Jev", "Apple Watch"], "also_reported_by": [], "takeaway": "Move every numeric judgment out of the LLM and into deterministic code, then pass the computed results to the model with a system prompt that says to trust and never contradict them.", "recommendation": {"advice": "Compute fatigue and load comparisons in plain functions and pass the results to the LLM as fixed judgments it must not contradict, so the same records always yield the same review.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week", "markdown": "https://wpnews.pro/news/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week.md", "text": "https://wpnews.pro/news/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week.txt", "jsonld": "https://wpnews.pro/news/how-much-should-an-llm-decide-building-an-avatar-that-reviews-your-training-week.jsonld"}}