healthy-diet-ai-agent: a Bun backend that keeps dietary guideline versions apart
Healthy Diet AI Agent is a Bun + TypeScript backend for nutrition chat, food-image analysis, RAG document ingestion, and knowledge-grounded diet guidance.
At a glance
- What is it?
- The repository ships a nutrition chat and food-image agent with a switchable SQLite or Supabase storage layer, plus a version-aware RAG evaluation suite that most nutrition bots skip. The design is opinionated and the documentation is uneven, so adoption depends on whether the retrieval problem matches yours.
- Who is it for?
- Adopt it if you need a self-hosted nutrition agent whose retrieval layer can distinguish guideline versions, and you are willing to read src/server/agentRuntime.ts and agent_config.json rather than rely on a setup guide. Do not adopt it if you need a documented HTTP contract or a maintained release line; the README has no release history and the deployment section is truncated.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 31 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The version-conflict problem this repository was built around
Dietary guidance is revised. A national ministry issues a new edition of its food guidelines, the previous edition stays in circulation, and any retrieval system that indexes both will happily return a passage from the superseded one. The README names this directly: a "Version-Aware & Policy-Aware RAG evaluation engine for resolving multi-version dietary guideline temporal conflicts", with the frozen suites living under experiments/version_aware_rag/. That is a narrower and more interesting target than generic nutrition chat. The audience is whoever has to answer diet questions with citations that hold up: a clinic building an internal assistant, a public health team with a document archive, or a developer extending the original PU-Hub/healthy-diet stack. The repository also carries MOHW data synchronization (src/server/mohwNews.ts) and a knowledge graph extractor, which suggests the intended corpus is official Taiwanese health ministry material rather than the open web. If your corpus is a single undated set of documents, the version-aware machinery is overhead you will pay for and never use.
Two storage backends behind one adapter layer
The storage directory is split into sqlite/ and supabase/ adapters under a common abstraction, and the README describes the backend as switchable between sqlite and supabase. Standalone mode runs on SQLite with the database file kept in data/, and the README states that the Docker default is standalone SQLite mode. Integration mode keeps Supabase so the service can reconnect to the existing health-diet-api ecosystem. This is the most consequential design decision in the repository, because it determines what you operate. SQLite mode means a single container with a file on disk, no external service, and the CLI entry point at src/cli.ts available alongside the HTTP server at src/index.ts. Supabase mode means your retrieval and agent state live in a hosted Postgres with its own access model, and docs/supabase holds the configuration and scripts for that path. The cost of supporting both is visible in the schema split: docs/sqlite and docs/supabase each carry their own definitions, so a change to one is not automatically a change to the other. Pick one mode and stay in it; running both against the same deployment is not something the README describes.
Ingestion: PDF to Markdown, then embeddings, then a graph
The pipeline has three distinct stages, each with its own module. First, src/rag_clean/pdf_to_clean_markdown.py converts official guideline PDFs into structured Markdown; the README specifically calls out that it preserves "table prose descriptions", which matters because nutrient tables in guideline documents are where the numbers live and where naive PDF extraction produces garbage. Second, src/server/knowledgeIngestion.ts handles file uploads, parsing and embedding ingestion, writing parsed Markdown into knowledge_base/ingested_markdown/ with uploads landing temporarily in knowledge_base/uploads/. Third, src/server/knowledgeGraph.ts extracts and searches structured relations, and src/server/ragDocuments.ts exposes CRUD and indexer routes over the document store. A separate sync task in src/server/mohwNews.ts pulls public clarification content into knowledge_base/mohw_clarifications/. Note that the PDF tool is Python while everything else is TypeScript and Bun, so a deployment that wants to re-ingest source PDFs needs a Python runtime in addition to Bun. The README does not describe how that tool is invoked from the Node side, and I cannot confirm from the material whether it is called automatically during ingestion or run manually by an operator.
Getting it running: what the README actually gives you
The README states Bun 1.2+ and TypeScript 6 in its badges, and lists Express 5, LangChain, LangGraph and DeepAgents as the agent stack, with an OpenAI-compatible API route and optional Google Gemini routing. Deployment is Docker Compose via compose.yml, and package.json holds the runner scripts. Beyond that, the setup instructions are thin. The README's Deployment section is truncated in the supplied material, so I cannot state the exact commands for bringing the stack up, the environment variable names the config validator in src/config expects, or the port the Express server binds. What I can point at with confidence is the file layout: agent_config.json at the repository root holds "declarative behavior controls and default parameters for the agent", src/config/ contains the logger and environment validators, and src/cli.ts is the terminal entry point for standalone use. Treat agent_config.json as the first file to read, not the README. Anyone evaluating this repository should budget time for reading the source before the first run, because the documentation does not carry you from clone to working endpoint.
Where the repository is weakest
There are no releases. The material shows no release history at all, which means no versioned artifact, no changelog surface you can pin to, and no signal about what a breaking change would look like. The README does include a Planned Features list (personalized suggestions from user profiles, richer multimodal meal analysis, expanded admin and ingestion tooling, advanced multi-step agent workflows), and the presence of four unshipped headline features alongside a truncated deployment section tells you the project is mid-refactor. The README says as much: the direction was adjusted after the repository "started receiving more attention and views", and the team is "gradually refactoring this repository into a standalone, independently deployable AI agent service". Gradual refactoring plus no releases is a real adoption risk for anyone who needs a stable interface. The second weakness is the Python dependency in an otherwise Bun-only stack. The third is that the HTTP API surface is undocumented here; the router handlers live in src/serverHandlers.ts and the bootstrap in src/server/httpRuntime.ts, so the contract exists only in code. If you need a documented API before you commit, this is the wrong repository today.
How it differs from a general-purpose RAG framework
A general framework such as LangChain's own retrieval chains, or a hosted assistant platform, gives you document chunking, embedding, vector search and a prompt template, and leaves temporal reasoning entirely to you. The usual workaround is to filter by a metadata date field and hope the corpus is tagged consistently. This repository instead treats version and policy as first-class parameters, with the README describing "parameterizable retrieval rules" and a frozen evaluation suite under experiments/version_aware_rag/ that exists specifically to measure whether the retrieval layer resolves conflicts between guideline editions correctly. That is the substantive difference: not better embeddings, but an evaluation harness aimed at a failure mode generic stacks do not measure. The trade-off is scope. A general framework will connect to far more data sources and has a much larger user base to draw answers from. This one is built around ministry guideline documents, MOHW clarifications and a nutrition rule file at knowledge_base/NUTRITION_RULES.md, and it will not reward you for pointing it at a wiki dump. Choose it when temporal correctness of dietary guidance is the actual requirement, not when you just want a chatbot over PDFs.
Maintenance cost and the MIT licence
The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That is the easy part. The maintenance cost sits elsewhere. You inherit a stack with four moving agent layers (LangChain, LangGraph, DeepAgents, plus the runtime in src/server/agentRuntime.ts), a storage abstraction with two implementations to keep in sync, a Python preprocessing tool outside the Bun toolchain, and an ingestion pipeline with four separate source directories under knowledge_base/. Every one of those is a surface that can break independently. Because there are no releases, upgrades mean tracking the main branch and reading technical_docs/ for architectural and changelog notes rather than diffing version tags. The README states the repository is not archived and the last push was 2026-08-16, so the project is active, but active is not the same as stable. For a team of one or two engineers with a fixed corpus, that is manageable. For a team that needs to hand the service to an operations group with a runbook, the missing deployment documentation and absent release tags are the blockers to resolve before anything else. Nothing here constitutes legal advice; read the MIT text in the repository if licensing terms matter to your organisation.
Editorial conclusion
Adopt it if you need a self-hosted nutrition agent whose retrieval layer can distinguish guideline versions, and you are willing to read src/server/agentRuntime.ts and agent_config.json rather than rely on a setup guide. Do not adopt it if you need a documented HTTP contract or a maintained release line; the README has no release history and the deployment section is truncated. Verify first that the Bun 1.2+ and TypeScript 6 badge claims match your toolchain, that docs/sqlite contains the schema you expect, and that whichever OpenAI-compatible endpoint you plan to route through is actually accepted by the config in src/config.
Community notes