📸 Breakfast photo → macros
The way to log food in HealthOS isn't to enter grams—it's to send a photo of the dish. Vision (the Gemini model) looks at the image, estimates protein and the other macros, and raises flags (e.g., high saturated fat) and records everything in a food_log. You just check the response.
🟢 New here? Two terms
- Vision (Gemini) — is the AI model that “sees” the photo. Instead of describing it yourself, the model reads the image and returns an estimate of the food and macros.
- Macro — “macronutrient”: protein, carbohydrates, and fat. These are the three numbers the coach tracks day to day.
📊 How to read: follow the image from left to right. The purple box (the vision) is the step that does the work: it reads the image, estimates, and marks the flags. The end of the line shows that this data doesn’t die in the log—it reappears in the next day’s retrieval (topic 6).
📷 You take a photo
Take a photo of your plate and send it on Telegram, with a short caption if you want to help ("scrambled eggs and avocado").
🧠 Vision estimates
Gemini identifies the items, estimates protein/fat/carbs, and flags relevant issues (e.g., high saturated fat).
🗄️ Saves and confirms
The line goes into food_log and the coach confirms in one sentence: "~38g protein, low saturated fat, logged".
▶ Copy and use in Telegram
Goal: log breakfast without typing a single macro.
You send
[📷 foto do prato] + legenda: <ex.: ovos mexidos e abacate>
The coach responds
~38g proteína, baixa gordura saturada, registrado ✓
/today — the meal appears in today’s list; or run this on the server python3 agent/scripts/db.py select food_log --limit 1 and see the recorded row. The numbers are illustrative.Key concepts
You send the image; vision does the math.
Protein and macros are approximate, not weighed.
Warnings like "high saturated fat."
One sentence closes out the log in chat.
🗄️ food_log: what gets recorded
Each photo becomes a structured row in the table food_log. It’s more than text: these are fields the coach adds up and cross-references later (daily intake, trend, pattern). That’s why it “remembers” what you ate — it’s all in rows, not in a conversation that gets lost.
🧾 What typically goes in the line
✓ Great for
- ✓Trend: "you hit your protein target on 5 of the last 7 days".
- ✓Pattern: "every time you eat dinner late, your sleep suffers".
- ✓Frictionless logging — all you have to do is take a photo.
✗ Does not replace
- ✗Weighing food — the photo is vision estimate, not a scale.
- ✗Clinical precision for a restricted medical diet.
- ✗Guess what’s hidden in the dish (sauce, oil).
💡 Good for trends, not for gram-level accuracy
The photo's macros are estimates: great for seeing the direction over the course of weeks, not to calculate an exact calorie count. If a number really matters (medical diet, aggressive cutting), weigh the food and correct the entry — topic 5 shows you how.
Key concepts
Summable fields, not loose text.
Warnings for the coach to read later.
The value lies in the pattern across weeks.
Vision, not a scale.
🏋️ Log your workout
Training is also a signal. You describe it in free text — type, duration, and intensity — and the coach writes a row to the table workouts. This closes the other side of the equation: what comes in (food) and what you burn (workout), both alongside recovery.
▶ Copy and use in Telegram
Goal: log today’s session as one row in workouts.
You send
treino: <tipo> <duração> intensidade <baixa|média|alta> ex.: treino: push 45min intensidade alta
The coach responds
Push 45min, intensidade alta — registrado. Põe carbo perto da sessão. ✓
/today and see the workout in the list; or on the server python3 agent/scripts/db.py select workouts --limit 1.💡 Free text, not a form
You don’t need to memorize a format. "I went for an easy half-hour run" works just as well — the agent extracts the type, duration, and intensity from the sentence. The structured example above is just the fastest way.
Key concepts
The table where your workout becomes a row.
Type, duration, intensity.
Describe it freely; the agent extracts the details.
Today’s load weighs on tomorrow.
🎬 Exercise demo clip (optional)
This is an extra. The script exercise_clip.py uses ffmpeg to create a short clip demonstrating an exercise — useful when you can't remember how to perform a movement. It's not part of the logging; it's an on-demand visual aid.
🟢 New here?
ffmpeg — is a command-line tool for processing video and audio. In HealthOS it only shows up here, to generate the exercise clip; the rest of the coach doesn’t depend on it.
▶ Copy and run on the server
Goal: generate a demo clip of an exercise (requires ffmpeg to be installed).
Command
python3 agent/scripts/exercise_clip.py "<nome do exercício>"
ex.: python3 agent/scripts/exercise_clip.py "agachamento búlgaro"
exercise_clip.py)” passes when the clip is generated without errors.🧭 Can skip without losing anything
If you haven't installed ffmpeg or don't use clips, HealthOS remains 100% functional — food, training, recovery, and blood pressure don't depend on this step. It's a convenience, not a foundation.
Key concepts
Generates the movement demo clip.
The video tool behind it.
The coach runs without this.
You generate it when you need it.
✏️ Correct what the AI got wrong
The vision model guesses—and the coach says when it's guessing. This is intentional: the record stays honest and you stay in control. When the estimate is wrong, you correct it in a message and the line is updated. You are the human verification.
✓ It’s worth correcting when
- ✓The vision model got the quantity wrong ("it was 2 eggs, not 3").
- ✓An item was missing (the olive oil, the sauce).
- ✓The coach explicitly said it was uncertain.
✗ No need to panic when
- ✗The estimate is close — it’s a trend, not a scale.
- ✗You just want the week’s direction, not the exact gram amount.
- ✗Looking for clinical accuracy from a photo—use a scale for that.
▶ Copy and use in Telegram
Goal: correct an estimate that was off.
You send
na verdade era <correção>
ex.: na verdade eram 2 ovos, não 3, e tinha azeite
The coach responds
Corrigido: ~30g proteína, gordura um pouco maior. Linha atualizada. ✓
/today again—the meal appears with the corrected numbers in place of the old ones.⚠️ AI can be confident and wrong
The coach is an AI model: it can make confident guesses. Treat its estimate as a starting point, not the truth. For anything that really matters to your health, check with a professional — this is not medical advice.
Key concepts
The coach signals uncertainty.
One message updates the row.
You are quality control.
Confident doesn’t mean correct.
🔁 Yesterday in tomorrow’s recovery
This is where the loop closes. The late dinner, the glass of wine, the hard workout — all of that goes in as a row today, and comes back tomorrow morning within recovery. The coach doesn't just show the number: it points to the probable cause, based on what you logged. That's why logging is worth it.
📊 How to read: the three boxes form a loop. What you log (purple) changes recovery (red), which changes the advice (cyan) — and the dashed line closes the loop back to food. It's the same loop as Module 1.1, now viewed from the perspective of the person logging.
💡 Logging is what gives the number a cause
Without yesterday’s record, tomorrow’s recovery would just be a number on its own. With it, it becomes explanation: “it was the wine,” “it was the late dinner.” The more you log, the more the coach learns your personal triggers.
Key concepts
Today’s choice becomes tomorrow’s number.
The coach explains why, not just what.
Without data, the number is orphaned.
You learn what affects you.
🩺 Blood pressure and weight
The two quickest logs of the day: the blood pressure (BP) e o morning weight (weigh-in). Each one is a message. Blood pressure goes in the table vitals; weight, in weigh_ins. Along with food, they let the coach connect salt and blood pressure, or dinner and weight.
🟢 New here?
- BP — “blood pressure.” It comes in two numbers: systolic/diastolic (e.g., 120/80).
- weigh-in — weigh yourself, preferably at the same time every day (in the morning, before eating) so the trend is comparable.
▶ Copy and use in Telegram
Goal: log your morning blood pressure and weight.
You send
pressão <sistólica>/<diastólica> peso <kg> ex.: pressão 124/79 · peso 78.4
The coach responds
BP 124/79 registrada (vitals). Peso 78,4kg registrado (weigh_ins). ✓
vitals row" and "A weight message writes a weigh_ins row"; or python3 agent/scripts/db.py select vitals --limit 1.🧂 The author's example: salt × pressure
In the author's case, logging food and blood pressure together revealed a pattern: after saltier meals, his blood pressure went up by about 10-15%. This kind of connection only appears because both data points live in the same database. It’s one person’s experience, an illustrative number — it is not a target for you.
⚠️ Not medical advice
Blood pressure is serious clinical data. The coach doesn’t diagnose or change medication — it logs and points out patterns for you to take to your doctor. Anything outside the normal range is for a healthcare professional, not the bot.
Key concepts
The blood pressure (BP) table.
The morning weight table.
A pattern that only appears when you cross-reference data.
It records; the doctor decides.
✅ Self-check (optional): why are the photo macros "good for trends, not for exact amounts"?
📋 Module summary
Next module:
3.3 — Memory, patterns, and supplements: how the coach remembers your history, spots patterns over weeks, and organizes your supplement schedule.