# FoodGuard

**Verified food-safety screening for AI agents.**

FoodGuard is an open-source MCP server and Claude Agent Skill that gives AI agents deterministic, source-grounded tools for food allergens, Indian packaged-food labels, official regulations, recalls, and preliminary process hazards.

It is infrastructure for trustworthy agents—not an "AI food-safety expert" prompt.

> [!IMPORTANT]
> FoodGuard produces screening results, not legal certification, medical advice, or a completed HACCP plan. v0.1 supports India first and intentionally abstains when information or live verification is unavailable.

## Why it exists

Small food businesses and consumers increasingly ask AI systems consequential questions. Model memory alone is a poor source for rules that change, differ by jurisdiction, and can affect health. FoodGuard makes those systems show their work:

```text
User → Claude / MCP host → FoodGuard rule engine → official evidence → grounded answer
```

Every finding carries an outcome, confidence, matched input, source IDs, official URLs, retrieval dates, limitations, and a clear screening boundary.

## What v0.1 can do

| Tool | What it does | Safety behavior |
|---|---|---|
| `identify_allergens` | Finds configured Indian priority-allergen names and common derivatives | Flags ambiguous terms; never equates no match with allergen-free |
| `audit_food_label` | Screens OCR/transcribed Indian label text for common declaration indicators | Distinguishes text presence from visual/legal compliance |
| `identify_process_hazards` | Produces preliminary review prompts for manufacturing steps | Does not assign CCPs or invent critical limits |
| `search_regulations` | Searches a curated official-source registry | States that coverage is not the complete body of law |
| `get_regulation_section` | Returns official source metadata and an evidence paraphrase | Directs users to authoritative wording |
| `source_freshness` | Shows source age and review status | Makes staleness visible |
| `check_food_recall` | Routes India checks to the official live portal | Abstains rather than fabricating a no-recall result |

## Quick start

Requirements: Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/TechTharun/foodguard.git
cd foodguard
uv sync --extra dev
uv run foodguard-mcp
```

The server uses stdio by default. The repository includes `.mcp.json`, so project-aware Claude Code sessions can discover it after dependencies are installed.

To inspect the server interactively:

```bash
uv run mcp dev src/foodguard/server.py
```

## Example

Ask Claude:

> Use FoodGuard to identify allergens in wheat flour, sodium caseinate, soy lecithin, peanut, and natural flavour.

FoodGuard returns structured findings resembling:

```json
{
  "outcome": "REVIEW_REQUIRED",
  "findings": [
    {"code": "ALLERGEN_CEREALS_GLUTEN", "outcome": "DETECTED"},
    {"code": "ALLERGEN_MILK", "outcome": "DETECTED"},
    {"code": "ALLERGEN_SOYBEAN", "outcome": "DETECTED"},
    {"code": "ALLERGEN_GROUNDNUT", "outcome": "DETECTED"},
    {"code": "ALLERGEN_AMBIGUOUS_INGREDIENT", "outcome": "REVIEW_REQUIRED"}
  ],
  "disclaimer": "Screening result only..."
}
```

Claude can explain the result, but the evidence and abstention behavior come from FoodGuard.

## Claude Agent Skill

The bundled skill is at `.claude/skills/food-safety/SKILL.md`. It teaches Claude when to call each tool, how to preserve uncertainty, and when to escalate to official or professional review. It includes short reference files for evidence policy and multi-tool workflows.

## FoodGuard-Eval

The starter benchmark contains 30 transparent cases covering direct allergens, derivatives, multiple allergens, negatives, and correct abstention.

```bash
uv run foodguard-eval
uv run pytest
uv run ruff check .
```

CI runs linting, unit tests, an in-memory MCP client test, and the benchmark on Python 3.11 and 3.12. Benchmark scores in this repository are computed—never hand-written.

## Design principles

- **Evidence before eloquence:** official sources and limitations travel with claims.
- **Abstention is a feature:** missing or ambiguous data produces review, not confident prose.
- **Deterministic core:** the MCP server wraps ordinary testable Python functions.
- **Jurisdiction first:** India rules are explicit rather than silently generalized worldwide.
- **No hidden live claims:** v0.1 tells you when a live source must be checked.
- **Agent-agnostic:** Claude is the first-class experience, but any MCP-compatible host can use the server.

Read [the architecture](docs/architecture.md), [evidence contract](docs/evidence-contract.md), and [safety model](docs/safety-model.md).

## Roadmap

- verified FSSAI amendment monitoring and source diffs;
- reliable live recall ingestion with provenance;
- label-image OCR with bounding-box evidence;
- supplier-specification and compound-ingredient workflows;
- larger expert-reviewed public evals;
- additional jurisdictions behind separate rule packs.

## Contributing

Food-safety professionals, developers, researchers, translators, and accessibility reviewers are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Please report security problems privately as described in [SECURITY.md](SECURITY.md).

## License

Apache-2.0. See [LICENSE](LICENSE).