CookHero: an LLM, RAG and ReAct agent stack for meal planning and diet logging
CookHero是一个基于 LLM + RAG + Agent + 多模态的智能饮食与烹饪管理平台，支持智能菜谱查询、个性化饮食计划、AI 饮食记录、营养分析、Web 搜索增强，以及可扩展的 ReAct Agent / Subagent 工具体系，帮助厨房新手轻松成为“烹饪英雄”。
At a glance
- What is it?
- CookHero is a Python and FastAPI platform that combines a Milvus-backed recipe knowledge base with a ReAct agent, subagents and multimodal diet logging. It is a self-hosted system with a long dependency list, and the README is honest about what you have to run yourself.
- Who is it for?
- Adopt CookHero if you want a self-hosted diet and recipe assistant where the retrieval layer, the agent loop and the logging schema are all visible and editable, and you are willing to run PostgreSQL, Redis, Milvus, MinIO and Etcd alongside it.
- Can I use it commercially?
- Yes. Apache-2.0 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 26 days ago.
- What is it written in?
- Mainly Python, 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 gap CookHero fills between a recipe site and a food diary
Most recipe tools stop at retrieval. You search, you get a page, and the planning and logging happen somewhere else. CookHero links the two halves by keeping a global recipe corpus and a personal recipe corpus in the same retrieval path, then feeding the results into an agent that also owns the planning and logging tools. The README states that the built-in recipes come from Anduin2017/HowToCook, and that users can upload private recipes which the system analyses and indexes. That means a query can draw on both without the user choosing a source.
The target user is stated plainly: kitchen beginners, people managing fitness, fat loss or blood sugar, people with allergies, and families. The allergy case is the one that shapes the design most, because it forces the retrieval layer to carry metadata rather than just text. The README lists metadata filtering by cooking time, difficulty and nutritional content as a separate retrieval stage alongside vector search and BM25. That is a different architecture from a plain semantic search over recipe text, and it is the part worth judging the project on.
How retrieval, the agent loop and the tool hub fit together
The retrieval path has three stages the README names explicitly: vector search on Milvus for semantic similarity, BM25 for keyword matching, and a reranker model such as Qwen3-Reranker applied to the merged candidate set. Metadata filters sit alongside these. A two-level cache (Redis plus Milvus) is described as reducing response time, though the README gives no numbers, so treat the caching claim as a design statement rather than a measured result.
Above retrieval sits the agent. The README describes a ReAct reasoning and action loop with an AgentHub that manages agents, tools and providers in one place. Tools are grouped by function: diet tools for plan management, diet records and nutrition analysis; knowledge base retrieval, which returns citable sources; Tavily web search; image generation through DALL-E 3 or compatible models with upload to imgbb; a calculator; and date and time helpers including timezone conversion. Subagents are the interesting layer. Each subagent has its own system prompt and its own tool set, and can be called as a tool by the main agent. The README notes that users create, enable and disable subagents from a personal centre, and that the front end has an Agents panel in the tool selector.
Streaming is handled with SSE, and the README says the event stream shows tool calls and their results as they happen, with main-agent and subagent traces displayed in separate layers. For anyone debugging why an agent picked the wrong recipe, that trace separation is more useful than a single flat log. Context compression is also mentioned for long conversations, with token reduction as the stated goal.
What you actually run: Docker infrastructure, a Python backend and a Vite front end
The README gives a Docker-first path. After cloning and copying .env.example to .env, you enter the deployments directory and run docker-compose up -d, which the README says starts PostgreSQL on 5432, Redis on 6379, Milvus on 19530, MinIO on 9001 and Etcd internally. Back in the project root you create a virtual environment, install requirements.txt, then run python -m scripts.howtocook_loader to initialise the database. The backend starts with uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload, and the front end with npm install followed by npm run dev in the frontend directory. The README lists http://localhost:5173 for the UI, http://localhost:5173/diet for diet management, and http://localhost:8000/docs for the API documentation.
Configuration is split between .env and config.yml. The .env.example carries separate keys for the main LLM, a fast model used for intent recognition and query rewriting, a vision model, and the reranker, plus DATABASE_PASSWORD, optional REDIS_PASSWORD and MILVUS_USER/MILVUS_PASSWORD, WEB_SEARCH_API_KEY for Tavily, AMAP_API_KEY for a map MCP server, IMAGE_GENERATION_API_KEY and IMGBB_STORAGE_API_KEY, JWT_SECRET_KEY with JWT_ALGORITHM=HS256, ACCESS_TOKEN_EXPIRE_MINUTES=60 and REFRESH_TOKEN_EXPIRE_DAYS=7. Rate limiting is controlled by RATE_LIMIT_ENABLED=true with per-minute caps for login (5), conversation (30) and global (100). Account safety keys include LOGIN_MAX_FAILED_ATTEMPTS=5, LOGIN_LOCKOUT_MINUTES=15, MAX_MESSAGE_LENGTH=10000, MAX_IMAGE_SIZE_MB=5 and PROMPT_GUARD_ENABLED=true.
config.yml holds the layered LLM provider setup (fast, normal, vision), the data path data/HowToCook, the embedding model BAAI/bge-small-zh-v1.5, and the vector store type set to milvus. The README excerpt cuts off mid-key in the vector_store block, so check the repository for the full schema before editing it.
Where CookHero is the wrong tool, and where the documentation runs thin
The infrastructure footprint is the first constraint. Five services have to be healthy before the backend is useful, and Milvus in particular is not a component you casually restart. If you want a recipe assistant on a laptop with no Docker, this is not it.
External API dependence is the second. The README's own .env.example implies at least four model endpoints (main, fast, vision, reranker) plus Tavily for web search and imgbb for image persistence. Remove any of them and a documented feature degrades. Image generation and multimodal logging both depend on imgbb, so a self-hosted deployment still ships user images to a third party.
The documentation is uneven. Security has its own document at docs/SECURITY.md and the README points to it, which suggests that area is maintained. The RAG evaluation system is described in terms of RAGAS metrics (faithfulness and answer relevancy) run asynchronously in the background with results stored in PostgreSQL, but the README gives no thresholds, no alerting rules, and no example of what a failing evaluation looks like. The same applies to the caching claim and to the context compression feature: both are described, neither is quantified. Treat those as mechanisms you will have to measure yourself.
Language coverage is another open question. The default embedding model, BAAI/bge-small-zh-v1.5, is a Chinese model, and the README's primary language is Chinese with an English translation under docs/README_EN.md. If your recipe corpus is predominantly English, the retrieval quality of the vector stage is something to test rather than assume.
How it differs from a plain LangChain retrieval chain
The closest comparison is a LangChain retrieval chain wired to a vector store. That gives you semantic search over documents and a prompt template, and it stops there. CookHero adds three things that a chain does not have by default: a ReAct loop with a tool registry, a subagent layer where each expert carries its own prompt and tool subset, and a persistent diet domain model with plans, records, nutrition targets and source tagging (manual, AI text, AI image).
The trade-off is coupling. A retrieval chain is easy to swap out; CookHero's retrieval is entangled with the diet schema, because metadata filters read from recipe attributes that the loader script populates. If you only want the RAG half, you are still installing PostgreSQL and the diet tables. If you only want the diet logging half, you are still running Milvus. The project is designed as one product, not as composable libraries, and the README reflects that by presenting Docker Compose as the recommended path rather than offering a lighter mode.
MCP support is the one extension point that escapes the coupling. The README says users can register their own MCP servers with authentication headers, and the AMAP_API_KEY entry in .env.example is a concrete instance of that. For teams already running MCP servers internally, this is the cheapest way to add capability without touching the agent code.
Maintenance cost, licence and what to check before committing
The licence is Apache-2.0, which permits commercial use and modification and requires that you preserve the licence and notice files. That is a summary, not legal advice; read the LICENSE file in the repository for the actual terms. One attribution point matters in practice: the built-in recipe corpus comes from Anduin2017/HowToCook, and the README thanks that project's contributors. If you redistribute CookHero with the bundled recipes, check the upstream project's own licence separately, because Apache-2.0 on CookHero does not automatically cover third-party content it ships.
Upgrade cost is driven by pinned dependencies. The README's badges name Python 3.12+, FastAPI 0.122, LangChain 1.1, Milvus 2.6, NeMo Guardrails 0.12 and RAGAS 0.2. LangChain and RAGAS both move quickly, and the agent layer is built directly on LangChain, so a major LangChain release is a real migration rather than a version bump. There are no releases listed for this repository, which means there is no tagged version to pin against; you would be tracking main.
Before adopting, verify three things in your own environment. First, that python -m scripts.howtocook_loader completes and populates Milvus with the HowToCook corpus. Second, that your embedding choice matches your corpus language, given the BAAI/bge-small-zh-v1.5 default. Third, that your Tavily and imgbb quotas cover expected usage, since both are load-bearing for documented features. Nothing in the README substitutes for running those checks.
Editorial conclusion
Adopt CookHero if you want a self-hosted diet and recipe assistant where the retrieval layer, the agent loop and the logging schema are all visible and editable, and you are willing to run PostgreSQL, Redis, Milvus, MinIO and Etcd alongside it. Do not adopt it if you need a hosted product, a mobile-first experience, or a system that works without an external LLM API key, since the .env.example lists separate keys for the main model, the fast model, the vision model and the reranker. Verify first that scripts.howtocook_loader completes against your Milvus instance and that the BAAI/bge-small-zh-v1.5 embedding model is the one you want, because the README documents that as the default in config.yml.
Community notes