feat(add-meal): add a model-assisted meal-text interpreter (#633)

[simonoppowa]

Closes #633. First of three for tier 1b of #599.

What tier 1b is

A model does the language work — segmenting a sentence, reading two eggs or 2个鸡蛋. The database still supplies every number. No macro is ever invented, so "every number is cited" holds and #250 does not need reopening.

This PR is the client only. Nothing in the app calls it yet — no UI, no key storage, no wiring. The key is a constructor parameter. Those are #634 and #635.

The design that makes it safe

MealTextInterpreter returns the same MealTextParseResult the deterministic parser returns. That makes an implementation a drop-in alternative to parseMealText: the resolver, review rows and write path are untouched and do not know which produced the items.

Two guarantees, both enforced rather than documented:

1. The tool schema has no macro fields. The model has nowhere to put a calorie count, so it cannot supply one. A test asserts the schema exposes exactly {query, quantity, unit} and nothing else — so the review question becomes "did someone add a field to this schema?" rather than "did the model behave?".

2. Model output is held to the parser's bounds. Everything returned passes through the new validateParsedMealItems, the same FoodNameValidator / > 0 / <= 10000 / known-unit rules parseMealText enforces. A model cannot write to the diary under looser rules than a regex.

The boundary I held

The prompt asks for a quantity only when the user stated one. Inferring that half an avocado is about 100 g is estimation, not parsing — and estimating mass is the first step back toward estimating nutrition, which is what #250 was closed over. With nothing stated the field is omitted and the review row's existing serving-size default fills it, exactly as for the deterministic parser.

I flagged this as the one open question before starting and proceeded on that answer. Say if you want it drawn elsewhere — it is one line of the prompt and one test.

Failure behaviour

The tool call is forced, so a prose reply is not a shape any caller has to handle. Anything unexpected — no tool call, malformed body, non-200 — raises MealTextInterpreterException rather than guessing, so #635 can fall back to the deterministic parser instead of showing an error.

The exception carries no response body: provider payloads can echo the submitted text, and this reaches logs. The network-error path deliberately does not log the underlying error for the same reason, and a test asserts the submitted text does not appear in the exception string.

Auth failures are marked non-transient (isTransient == false) so a caller can distinguish "your key is wrong" from "try again later".

Choices worth a second opinion

• Model pinned to claude-haiku-4-5, not an alias. A silent model change would move behaviour the user never asked to change. Overridable per instance.
• An unrecognised unit is dropped, not rejected. 2 cups flour keeps the food and the 2, and the row defaults the unit — refusing the row outright would lose a usable food over a unit the review row guesses better than we can.
• kg/l are not accepted by validateParsedMealItems. parseMealText converts them itself before validating; this entry point does no extraction, so accepting them would log 2 g for 2 kg. Covered by a test.

Verification

26 new tests (19 for the interpreter, 7 for the validator). flutter test 1108/1108, flutter analyze clean, formatter clean.

No live API call has been made. Every test fakes http.Client. The request shape — forced tool_choice, x-api-key and anthropic-version headers — is asserted against the documented contract, not against a real response. One live call before #635 ships would be worth it, and I have not made one.

No new dependency

http was already a direct dependency.

[Copilot]

Pull request overview

Adds the tier-1b “model-assisted meal-text interpreter” client-side building blocks for the Add Meal flow, ensuring model output is structurally unable to carry nutrition data and is validated to the same bounds as the deterministic parser.

Changes:

• Introduces a MealTextInterpreter interface (+ exception type) that returns MealTextParseResult to remain drop-in compatible with the existing parser pipeline.
• Adds an Anthropic Messages API implementation that forces a tool call and validates model output via shared parsing bounds.
• Adds validateParsedMealItems plus comprehensive unit tests for schema safety, validation behavior, and failure modes.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
lib/features/add_meal/util/meal_text_parser.dart	Adds validateParsedMealItems to enforce deterministic-parser bounds on externally produced ParsedMealItems.
lib/features/add_meal/domain/meal_text_interpreter.dart	Defines the interpreter interface and a non-leaky exception surface for callers to fall back safely.
lib/features/add_meal/data/anthropic_meal_text_interpreter.dart	Implements Anthropic-backed interpreter with forced tool schema and strict response parsing.
test/unit_test/meal_text_parser_test.dart	Adds tests for validateParsedMealItems behavior (bounds, indexing, unit handling).
test/unit_test/anthropic_meal_text_interpreter_test.dart	Adds tests covering request shape, schema constraints, response parsing, validation, and error handling.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

test/unit_test/anthropic_meal_text_interpreter_test.dart:341

• This test currently waits for the production 20s timeout to elapse (because FakeClient.hangs never completes and AnthropicMealTextInterpreter uses .timeout(const Duration(seconds: 20))). That adds ~20 seconds to the unit test suite runtime. Use package:fake_async to elapse time instantly and assert the future completes with MealTextInterpreterException without real waiting.

    test('a stalled connection does not hang forever', () async {
      final client = FakeClient(hangs: true);

      await expectLater(
        interpreterWith(client).interpret('toast'),
        throwsA(isA<MealTextInterpreterException>()),
      );
    });