Ranking recipes and checking explanations in Python.

THE WORK

The project.

Brimfox AI Core gives recipe ranking and explanation checks a small, independently startable Python service. One endpoint reorders supplied recipe candidates using explicit weights. Another compares explanation text with supplied grounding and returns support counts and warnings. These are deterministic helpers around a recipe workflow, not a model that retrieves or generates recipes.

The Laravel client makes that separate process usable as an HTTP dependency. It sends structured JSON, authentication and trace identifiers, applies connection and request timeouts, and distinguishes an exhausted timeout from other service failures. Optional logs describe the request without recording its raw payload values.

The remaining step is the product connection. Brimfox still creates explanations through its PHP provider, validator, cache and fallback; no caller in that response invokes these Python helpers. The service and client establish a concrete integration foundation, while enablement, result acceptance and end-to-end failure behavior remain work for the application that will consume it.

IMPLEMENTATION

Design choices.

1. Explicit weights and support counts make the prototype's calculations inspectable. They provide a starting point for evaluation, without implying learned ranking quality or semantic verification.
2. The Python package owns helper calculations; Laravel retains the recipe response and its user context. That separation keeps authority with the product, which still has to decide whether a helper result is useful enough to accept.
3. Retries cover connection failures and server errors rather than every unsuccessful status. This avoids repeatedly sending rejected requests, while making retry time part of the latency a synchronous caller must budget for.
4. Configuration validation and request execution are separate operations. Registering a client or setting an enable flag does not prove that a product route checks the flag or uses the service.
5. The verifier reports counts instead of silently editing generated text. An application can then define an acceptance or fallback rule explicitly, after tightening nested input validation and evaluating cases the current lexical check handles poorly.

HOW IT FITS TOGETHER

Architecture.

• FastAPI runs under Uvicorn with separate health, information, ranking and verification routes. Pydantic checks the request envelope and the ranking limit, but nested candidates, explanations, grounding and configuration remain permissive dictionaries.
• The reranker adds query-token coverage, phrase matches, ingredient readiness and substitution coverage to each supplied candidate score. It sorts that existing set and returns the requested 1–20 results without fetching recipes or calling a model.
• The explanation checker selects text units, rejects a fixed list of unsafe phrases and measures keyword overlap with supplied grounding. It returns supported and dropped counts, warnings and an aggregate outcome; it does not return a cleaned explanation.
• A shared authentication dependency checks configured bearer credentials in constant time. Production-like environments refuse protected calls without a configured token, while health remains public and other environments can allow no-token calls.
• Laravel makes synchronous JSON requests with separate connection and request timeouts. Connection failures and server errors can be retried within a configured limit; the result carries status and latency, or a typed exception explains the failure.
• Laravel continues to own user-scoped context, provider calls, final validation, caching and fallback. The Python request objects and payload factory exist alongside that path, but no product caller currently joins them to it.

ACCESS & INPUT

Security controls.

• Protected endpoints use constant-time bearer comparison. A production-like environment with no configured service token returns 503; when a token is configured, absent or incorrect credentials return 401.
• The health route is unauthenticated, and other environments permit helper calls without credentials when no token is configured. Those choices make correct environment settings and network exposure part of any deployment review.
• The container recipe selects a non-root application user. That is an implemented packaging control, not evidence that a container has been built, deployed or isolated on a network.
• When Laravel request logging is enabled, it records route, trace identifier, latency, status, payload key names and candidate counts. Raw request values are not included in that logging path.
• The Python helpers do not call providers or own account, authorization or database decisions. A support outcome describes their lexical checks, not factual correctness or medical and allergy safety.
• Laravel defaults the service to disabled and validates connection settings when enabled. Its low-level HTTP client does not enforce the enable flag, so the eventual product caller must make that check before sending a request.

CHECKS & RESULTS

What was checked.

A source review shows what the code does. It is not a fresh test of the running app.

1. Code and development records reviewedReviewed11 September 2026

   The code, tests and available development records were checked. Reported test results keep their original scope. No fresh app or live deployment check was run for this write-up.

   Scope of this check

   Code review, not a fresh run of the app