Suvo Health Context Agent

Suvo helps you understand and safely manage your supplements—what to take, when to take it, and what may conflict through intelligent tracking and interaction checks.

Comment

Inspiration

Suvo started from a simple problem: taking supplements is easy, but understanding them is not.

People often combine several products without knowing whether ingredients overlap, whether the total dosage is too high, whether timing matters, or whether two supplements should be taken together. Most health and nutrition apps treat supplements as simple checklist items rather than structured health data.

We built Suvo to make supplement routines easier to understand. The goal is not to replace doctors or pharmacists, but to help users organize what they take, identify potential issues, and prepare better questions for healthcare professionals.

For OpenAI Build Week, we extended Suvo with an AI-assisted label-scanning workflow that turns supplement packaging into structured, reviewable data.

What it does

Suvo helps users manage their supplement routine in one place.

Users can:

  • create and organize a supplement stack
  • track daily intake
  • calculate combined ingredient totals
  • detect duplicate compounds
  • identify known interactions and timing conflicts
  • manage supplements for dependent profiles
  • understand why each warning was produced

The new Build Week feature allows users to photograph a supplement label. GPT-5.6 extracts the product name, serving size, ingredients, quantities, units, directions, and warnings.

The user reviews and confirms the extracted information before Suvo compares the product against their existing stack.

Suvo then produces a safety briefing covering:

  • ingredient overlap
  • projected daily totals
  • timing and spacing issues
  • known interaction rules
  • missing or uncertain information
  • questions to discuss with a pharmacist or physician

GPT-5.6 reads and explains the information. Suvo’s deterministic rule engine performs the actual calculations and produces the findings.

How we built it

Suvo consists of a React Native mobile application, a Go backend, PostgreSQL, and a deterministic supplement-analysis engine.

The label-scanning workflow has four stages.

1. Image capture

Users upload or photograph different parts of a supplement package, including the front label, supplement facts, ingredients, directions, and warnings.

Images are compressed before upload, stored privately, and assigned a role so the extraction pipeline understands what each image represents.

2. Structured extraction with GPT-5.6

The backend sends the label images to GPT-5.6 using a strict structured-output schema.

The model is instructed to:

  • use only information visible in the images
  • preserve the original printed text
  • return missing values as null
  • mark ambiguous or conflicting information
  • avoid inventing common ingredients or dosages
  • avoid producing medical advice or safety conclusions

Each extracted field includes its value, original text, confidence, status, and source evidence.

3. Human review and normalization

AI output is treated as a candidate, not as verified truth.

The user reviews and corrects the extracted product before it can be analyzed. Suvo then maps the printed ingredient names to canonical compounds while preserving important distinctions between chemical forms, elemental quantities, and serving amounts.

For example, Suvo must distinguish between:

  • magnesium
  • magnesium citrate
  • 500 mg magnesium citrate
  • 80 mg elemental magnesium

4. Deterministic stack analysis

After confirmation, Suvo creates a projected version of the user’s stack and evaluates it using its existing rules engine.

The system checks for:

  • exact duplicates
  • related compound overlap
  • projected daily totals
  • dosage limits
  • timing conflicts
  • spacing requirements
  • known supplement interactions
  • unresolved ingredients

GPT-5.6 receives only the structured findings produced by Suvo and converts them into a concise explanation and a set of questions for a healthcare professional.

Codex was used to explore the existing architecture, define the extraction contracts, implement the backend integration, connect the workflow to the rule engine, generate tests, and review failure modes across the mobile and server codebases.

Bonus feature

AI summarizes based on your stack review and daily does intake the amount of information to actiable human reabable converstaion like format. Using GPT 5.6 Luna

Challenges we ran into

Separating AI extraction from medical judgment

The largest challenge was deciding where the model’s responsibility should end.

It would have been simpler to ask GPT-5.6 to read the label and directly decide whether a product was safe. That approach would be difficult to test, audit, and reproduce.

We instead enforced a strict boundary:

GPT-5.6
Unstructured label → structured candidate data

User
Candidate data → confirmed data

Suvo
Confirmed data → deterministic findings

GPT-5.6
Deterministic findings → clear explanation

Inconsistent supplement labels

Supplement labels vary significantly between products and markets.

Common problems include:

  • values shown per capsule versus per serving
  • several chemical forms grouped together
  • elemental and source amounts shown separately
  • proprietary blends
  • bilingual packaging
  • footnotes and daily-value symbols
  • information split across several panels

The extraction model had to preserve ambiguity instead of forcing every label into a complete but potentially incorrect structure.

Ingredient normalization

Reading text from an image is only the first step. The extracted ingredient must be matched to a canonical compound without losing medically relevant distinctions.

A wrong match can affect dosage totals, interaction rules, and timing recommendations. Unknown or ambiguous ingredients therefore remain visible and unresolved instead of being silently mapped.

Preventing unsupported AI explanations

The explanation layer must not introduce warnings that were not produced by Suvo.

Every generated explanation is linked to one or more deterministic finding IDs. Responses that reference unknown findings or introduce unsupported dosage claims are rejected.

Accomplishments that we're proud of

We built a complete workflow that combines AI flexibility with deterministic safety logic.

The parts we are most proud of are:

  • field-level provenance for extracted information
  • explicit uncertainty instead of hidden assumptions
  • mandatory user review before analysis
  • deterministic and reproducible safety findings
  • preservation of original label text alongside normalized data
  • graceful fallback when AI explanation generation fails
  • a clear boundary between AI output, user confirmation, and Suvo calculations

Suvo was already a functioning supplement-management application before Build Week. The new workflow integrates into the existing product rather than operating as a disconnected chatbot or prototype.

What we learned

We learned that AI is most reliable in this domain when it is given a narrow responsibility.

GPT-5.6 is effective at interpreting inconsistent labels and converting them into structured candidates. It should not be treated as the final authority for dosage, interactions, or medical safety.

We also learned that uncertainty is part of the product, not an implementation failure. A trustworthy system should expose missing amounts, conflicting labels, and unresolved ingredients rather than hiding them behind a confident response.

The strongest architecture was not “AI does everything.” It was:

  • AI handles messy input
  • users confirm what entered the system
  • deterministic rules produce findings
  • AI makes those findings easier to understand

AI-assisted software development

AI was not only part of Suvo’s user-facing functionality. It also played a major role in how the feature was designed and implemented.

Codex was used as an engineering partner across the existing mobile and backend codebases. Instead of generating isolated snippets, it helped trace domain models, inspect API boundaries, understand the supplement rule engine, and identify where the new workflow should integrate without duplicating existing logic.

We used Codex to:

  • explore the existing Go and React Native architecture
  • define structured extraction and provenance models
  • design database migrations and API contracts
  • implement GPT-5.6 integration
  • connect confirmed products to the deterministic analysis engine
  • generate unit and integration tests
  • review concurrency, validation, privacy, and failure handling
  • identify stale-analysis and authorization risks
  • refine the implementation across several iterations

The most valuable part of the process was using AI for repository-scale reasoning. Suvo already had established concepts for products, compounds, stacks, profiles, schedules, and interaction rules. The challenge was not writing a single endpoint. It was introducing a new AI workflow while preserving those existing boundaries.

We treated AI-generated code the same way as any other code contribution: it had to fit the architecture, pass tests, handle production failures, and remain understandable to a human maintainer.

This led to a development model where AI accelerated exploration and implementation, while engineering judgment remained responsible for architecture, safety boundaries, and final review. Playbook used: https://github.com/ahmedalaahagag/product-engineer-handbook

Continuous learning and feedback

We also used a lightweight repository memory system to make AI-assisted development improve over time instead of resetting with every session.

Two files supported this workflow:

  • lessons_learned.md captured mistakes, failed approaches, review findings, and implementation patterns discovered during development.
  • memory.md preserved stable architectural context, domain constraints, naming conventions, safety boundaries, and important decisions about the Suvo codebase.

After each significant implementation or review cycle, Codex updated these files with the parts worth retaining. Later sessions could use that context before making changes, reducing repeated exploration and preventing previously identified mistakes from being reintroduced.

Examples of retained knowledge included:

  • AI extraction must never bypass user confirmation
  • deterministic rules remain the source of safety findings
  • compound forms and elemental amounts must not be collapsed incorrectly
  • candidate products must not enter the public catalog automatically
  • changes to dosage or product data invalidate previous analysis results
  • model output must remain schema-validated and provenance-aware

This created a feedback loop:

Implementation
    ↓
Testing and review
    ↓
Lessons captured
    ↓
Repository memory updated
    ↓
Better context for the next development session

The goal was not to let the AI make autonomous architectural decisions. The goal was to give it durable project context so it could work more consistently across long-running development sessions.

This approach made AI-assisted development cumulative. Each iteration left behind structured knowledge that improved the next one, while the repository itself remained the source of truth.

What's next for Suvo

The next steps are to expand the same architecture to more types of health context while preserving the same safety boundaries.

Planned areas include:

  • medication-list import
  • improved multilingual label extraction
  • product reformulation detection
  • shared caregiver and dependent profiles
  • pharmacist-ready stack summaries
  • stronger catalog enrichment from confirmed labels
  • more detailed dosage and timing rules
  • user-controlled contribution of verified product data

The long-term goal is for Suvo to become a reliable context layer for supplement use: helping users understand what they take, how products relate to one another, and which questions require professional review.

Built With

Share this project:

Updates