Hugging Face's logo

Spaces:
build-small-hackathon
/
Vital
Running

App Files Community
Vital / README.md
eddyejembi's picture
eddyejembi
Update README.md
87307fc verified
preview code
|
Raw
History Blame Contribute Delete
9.95 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade
metadata 
title: Vitál
emoji: 💚
colorFrom: green
colorTo: indigo
sdk: gradio
sdk_version: 6.18.0
python_version: 3.12.12
app_file: space_app.py
app_port: 7860
pinned: true
license: mit
short_description: A local-first wellness companion.
tags:
  - track:backyard
  - sponsor:nvidia
  - sponsor:modal
  - achievement:fieldnotes
  - build-small-hackathon
  - backyard-ai
  - gradio
  - agentic
  - best-agent
  - local-first
  - sqlite
  - modal
  - vllm
  - nemotron
models:
  - nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16

Vitál

Your laptop already knows your schedule. Vitál makes it care about your health.

Vitál is an ambient wellness companion for people who live at their laptops. It plans the day, nudges the user at the right time, logs wellness actions, and coaches from local history instead of acting like a generic chatbot.

If you remove Nemotron, Vitál loses onboarding, daily planning, coach writes, briefings, and weekly reports — it is not a CRUD app with a chatbox.

For the hackathon Space, judges land directly on Amara's pre-seeded profile. No onboarding is required during judging. The full local version also includes first-run onboarding, desktop notifications, local voice reminders, and optional webcam-based desk-break detection.

Demo Video: Demo video

Social post: Vitál: A Wellness OS for People Who Live at Their Laptops

TL;DR for judges

Track Backyard AI — built around Amara, a remote software engineer in Lagos who wants steadier energy, better meals, light movement, and medication consistency
Small-model bet NVIDIA Nemotron 3 Nano 4B BF16 (~4B params) on Modal via vLLM — under the 32B cap; workflow + schemas + tools do the heavy lifting
Sponsor alignment Nemotron (primary reasoning model) · Modal (GPU inference, scale-to-zero)
Hosted demo path Open Space → Amara's dashboard → Coach read/write → weekly report
Agentic pieces Onboarding (2 calls), daily scheduler, coach tool loop, morning briefing, weekly report
Guardrails JSON schemas per pipeline, Python validation, retries, template fallbacks
Local-first posture Profile, plans, logs, schedules, and reports persist in SQLite on device
Space mode DEMO_MODE=true — TTS, webcam presence, and desktop notifications disabled (no local hardware on HF)
Full local mode install.bat / Start_Vital.bat — Kokoro TTS, plyer notifications, OpenCV desk breaks, APScheduler

What to try first

  1. Open the Space. You should land on Amara's Home dashboard, already onboarded.
  2. Check Home for today's briefing, medication checklist, metrics, and generated schedule.
  3. Open Nutrition and Movement to see today's hydration, meal, and exercise plan.
  4. In Coach, try: "How am I doing on water today?"
  5. Then try a write action: "Log lunch: moi moi and orange".
  6. Return to Nutrition and refresh. The food log should now include the meal.
  7. Open Report and generate a weekly report if one is not already present.

Coach is not answering from vibes. It calls tools, reads Amara's SQLite-backed state, and writes new logs when asked.

Why this is Backyard AI

Most wellness trackers need hardware or cloud accounts. Vitál is a wellness OS for the machine you already have — built for the messy reality of desk work skipped lunches, long sitting sessions, and it runs on the machine the user already has.

  • Starts from a personal profile, not a generic system prompt.
  • Generates a daily schedule from goals, medications, local foods, sleep/wake times, prior logs, and weather.
  • Nudges with desktop and voice reminders in local mode.
  • Reads today's actual logs before advising.
  • Writes back when the user logs food, water, exercise, or medication.

Amara is the demo profile; local onboarding generates a different plan for whoever runs it — same codebase.

Why Nemotron 3 Nano 4B

Size ~4B parameters — comfortably under the hackathon 32B cap
Tool calling Coach uses OpenAI-style tools (log_food, get_todays_logs, etc.) via vLLM --enable-auto-tool-choice
Structured output Separate JSON schemas for onboarding, daily plan, coach reply, and weekly report — not one free-form chat
Reasoning format Nemotron's reasoning parser plugin runs on the Modal server (nano_v3_reasoning_parser.py)
Context budget 8192-token window on Modal; app uses VITAL_MAX_TOKENS=4096 so prompts + completions fit without truncation

The bet: a small model pushed hard with schemas, validation, tool loops, and Python fallbacks — not a bigger model with a single prompt.

Why Modal

GPU when needed Nemotron runs on Modal A10G with vLLM
Scale to zero scaledown_window=15min — no 24/7 GPU bill for a personal wellness app
OpenAI-compatible API One VITAL_LLM_BASE_URL for local dev, Windows users, and the HF Space
Separation of concerns Space = Gradio UI + SQLite demo; Modal = inference only
Cached weights HF + vLLM volumes on Modal avoid cold-download on every deploy

Vitál's data stays local (SQLite). Modal hosts only the reasoning brain for this v1 hackathon build.

Architecture 

flowchart LR
    Browser[Browser / Gradio UI]
    SQLite[(SQLite vital.db)]
    Scheduler[APScheduler]
    TTS[Kokoro TTS]
    Presence[OpenCV presence]
    Modal[Modal vLLM + Nemotron 4B]

    Browser --> SQLite
    Browser -->|HTTPS OpenAI API| Modal
    Scheduler --> SQLite
    Scheduler --> TTS
    Presence --> TTS

HF Space (demo): Browser → Gradio → SQLite → Modal (no TTS / camera / OS notifications).

Local app (full): Same stack plus Kokoro voice, plyer desktop alerts, and webcam desk-break detection.

LLM pipelines and guardrails

Pipeline What goes in What comes out Guardrails
Onboarding Call 1 Profile ≤3 follow-up questions FOLLOW_UP_JSON_SCHEMA, retry once
Onboarding Call 2 Profile + answers Full wellness plan (jobs, schema, frameworks) ONBOARDING_PLAN_JSON_SCHEMA, validation
Daily schedule Profile + logs + prior-week meals + weather Timed hydration / meal / exercise jobs Schema + template fallback + repair pass
Coach Chat history + DB context Tool loop → final COACH_REPLY_JSON_SCHEMA Tool arg validation, food-log nudge + Python fallback
Morning briefing Profile + today's plan Short spoken narrative Cached in DB per day
Weekly report Week stats + logs Narrative + highlights + focus Schema + template fallback

Coach tools (examples): get_todays_logs, get_todays_schedule, get_medications_today, log_food, log_water, log_exercise, get_weekly_summary, write_weekly_report.

How it works (runtime layers)

Layer What happens
UI Gradio 6 — Home, Nutrition, Movement, Coach, Report, Settings
Brain Nemotron 3 Nano 4B on Modal (vLLM, OpenAI /v1/chat/completions)
State SQLite — profile, logs, food/exercise, daily plans, scheduler jobs, reports
Scheduler APScheduler loads jobs from DB; fires notifications + optional TTS
Local hardware Kokoro TTS, plyer notifications, OpenCV presence (local only)
Fallbacks Template daily plan, template weekly report, copy-yesterday plan

Modal deploy (reproduce the LLM endpoint) 

modal secret create huggingface HF_TOKEN=hf_xxxx
modal deploy infra/vllm_serve.py

Copy the printed URL into .env:

VITAL_LLM_BASE_URL=https://<workspace>--vital-nemotron-serve.modal.run/v1
VITAL_MODEL_ID=nemotron3-nano-4B-BF16

Server flags that matter for Vitál: --enable-auto-tool-choice, Nemotron reasoning parser, max-model-len=8192, A10G GPU. See infra/vllm_serve.py.

Hosted Space vs local app

The Hugging Face Space is a judge-friendly demo with a pre-seeded SQLite profile so the first screen is already useful. Hardware-specific features are disabled:

  • no local speech output (Kokoro runs on the user's machine, not Modal)
  • no webcam presence checks
  • no desktop push notifications

The local app is the full experience: voice reminders, native notifications, and desk-break detection without storing or transmitting webcam frames.

Privacy posture

Vitál is local-first, not fully offline.

Persistent wellness data lives in SQLite on the machine running the app. Each LLM call receives only the context needed for that action (profile summary, today's logs, schedule, weather). v2 direction: fully on-device inference; v1 uses Modal-hosted Nemotron for reliability.

Local setup 

git clone https://github.com/eddyejembi/vital
cd vital
cp .env.example .env   # set VITAL_LLM_BASE_URL and VITAL_MODEL_ID
uv sync
uv run python app.py   # -> http://127.0.0.1:7860

On Windows:

install.bat
Start_Vital.bat

Recommended .env tuning (8192 context model on Modal):

VITAL_LLM_BASE_URL=https://<your-modal-endpoint>/v1
VITAL_MODEL_ID=nemotron3-nano-4B-BF16
VITAL_MAX_TOKENS=4096
VITAL_CONTEXT_LIMIT=8192
VITAL_DAILY_SCHEDULE_MAX_TOKENS=4096
DEMO_MODE=false

Built with

  • Gradio 6 · SQLite · APScheduler
  • Modal · vLLM · NVIDIA Nemotron 3 Nano 4B BF16
  • Kokoro TTS · OpenCV · plyer (local only)

Team(Members): Eddy Ejembi GitHub: https://github.com/eddyejembi/vital

Built for the Build Small Hackathon (Gradio × Hugging Face) — Backyard AI track.