Hypothesis Engine — Design Specification
Purpose
The hypothesis engine watches a user’s suspected foods and correlator output, detects patterns in the sensitivity category graph, and generates two types of output: positive suggestions (foods to test next) and negative signals (categories that appear clear). It is the primary differentiator between Confidente and a simple food journal.
Inputs
- A user (with their suspect foods and correlation history)
- The current sensitivity category graph (foods → categories → severity levels)
- Active washout windows from the current meal plan
Output
A collection of HypothesisSuggestion records, each containing:
- The suggested food
- The reason category (which pattern triggered the suggestion)
- Status: pending, accepted, rejected
- The evidence that triggered it (which suspected foods share this category)
And optionally, a set of cleared category signals.
Spec 1: Category Pattern Detection
What
When 2 or more of a user’s suspected foods share a sensitivity category, the engine suggests additional high-severity foods in that category that the user hasn’t considered.
Why
Users suspect individual foods. They rarely think in terms of chemical categories. If someone reacts to avocado, red wine, and leftover chicken, they’re unlikely to spontaneously connect “all three are high histamine” and think to test aged cheese. The engine surfaces this pattern and directs testing toward the underlying mechanism rather than individual foods.
Behavior
For each sensitivity category, count how many of the user’s suspected foods have membership in that category (at any severity level). If the count meets or exceeds the category’s threshold, generate suggestions from the pool of high-severity foods in that category that are not already suspected.
Threshold Requirement
Do not suggest foods that are already suspected. Do not suggest foods with low or medium severity in the category — only high severity candidates are worth the testing investment.
Spec 2: Evidence-Tier-Aware Thresholds
What
Categories with weaker evidence bases require more suspected foods before the engine generates suggestions.
Why
Histamine intolerance and FODMAP sensitivity have substantial clinical trial evidence supporting them as distinct entities. Lectin sensitivity (outside of acute raw-legume toxicity) and glutamate sensitivity rest on thinner evidence. Applying the same 2-food threshold to all categories would generate spurious suggestions for weakly-evidenced categories, eroding user trust.
Behavior
The threshold for triggering suggestions varies by category evidence tier:
- Strong evidence (histamine, FODMAP): threshold = 2 suspected foods
- Moderate evidence (salicylate, oxalate): threshold = 2 suspected foods
- Emerging evidence (glutamate, lectin, capsaicin): threshold = 3 suspected foods
The tier assignment should be a configurable attribute on FoodSensitivityCategory (not hardcoded logic), so it can be updated as evidence evolves.
Spec 3: Washout-Aware Suggestion Timing
What
The engine does not surface suggestions for a category that is currently in an active washout window.
Why
Washout windows exist to clear a specific category’s mediator load before the next test exposure. Suggesting a new histamine food during a histamine washout would contaminate the experimental design. The suggestion should be queued and surfaced only after the washout clears.
Behavior
For each category that meets the suggestion threshold, check whether any active WashoutWindow exists for that category in the user’s current meal plan where start_date <= today <= end_date. If so, skip that category entirely for this run.
The suggestion will be generated on the next run after the washout expires, assuming the threshold conditions are still met.
Spec 4: Idempotency
What
Running the engine multiple times with the same inputs produces the same set of suggestions. No duplicates.
Why
The engine may be triggered on every change to suspect foods, after each correlator run, or on a schedule. It must not create duplicate HypothesisSuggestion records.
Behavior
Use find_or_create_by on the unique combination of (user, suggested_food, reason_category). If a suggestion already exists (regardless of status), do not create another. Return only newly created suggestions from the call.
Spec 5: Negative Hypothesis Generation
What
When the user has sufficient data showing no correlation between their food intake and a category, the engine surfaces a “clear” signal for that category.
Why
Unnecessary dietary restriction is a real harm. If someone has been avoiding all high-histamine foods for a month based on suspicion but the correlator shows no histamine-category signal, they should know. “Your data doesn’t show a histamine pattern” is as valuable as “your data suggests histamine is a problem” — it lets the user relax restrictions and redirect testing effort.
This also aligns with the HIT vs MCAS distinction. Dietary histamine elimination that doesn’t improve symptoms suggests the problem isn’t dietary histamine — which changes the intervention strategy entirely.
Behavior
The engine should expose a cleared_categories method (or equivalent output) that identifies categories where:
- The user has eaten high-severity foods in that category on at least 10 days (enough data to draw a conclusion)
- The correlator shows no significant positive correlation (p > 0.3 or FDR non-significant) between any high-severity food in that category and any symptom type
- No washout window is currently active for that category (the data was collected under valid testing conditions)
When these conditions are met, the engine generates a message: “Based on [N] days of data, your symptoms don’t appear to correlate with [category] foods. Consider relaxing [category] restrictions to simplify your diet.”
Important Caveat
The engine should note that a clear signal means “no detectable pattern at this data volume” — not “definitively not sensitive.” Subtle effects, interactions with confounders, or effects that only manifest under specific conditions (e.g., histamine sensitivity only during perimenstrual phase) may require more data or subgroup analysis to detect.
Spec 6: Multi-Category Food Handling
What
A food that belongs to multiple categories (e.g., tomatoes: histamine + salicylate + glutamate + lectin) counts toward each category’s threshold independently.
Why
Multi-category foods are the most informative test candidates because they contribute data to multiple hypotheses simultaneously. But a single food should not inflate a single category’s count — suspecting tomatoes doesn’t count as two histamine suspects.
Behavior
When counting suspected foods per category, each unique food counts once per category it belongs to. If both tomatoes and avocado are suspected, and both are in the histamine and salicylate categories, that’s 2 histamine suspects and 2 salicylate suspects — both categories meet the threshold.
The engine should include this multi-category information in its suggestion reasoning: “Avocado, red wine, and leftover chicken are all high histamine. Avocado and red wine are also high salicylate. You might want to test both categories.”
Spec 7: Temporal Lag Context in Suggestions
What
Suggestions include the expected symptom timing for the category, so the user can validate whether their experience matches.
Why
If the engine suggests histamine-category testing but the user’s symptoms are consistently delayed by 24+ hours, the temporal profile doesn’t match histamine (15-60 min onset). The user knowing this can reject the histamine hypothesis and the engine can consider whether the food’s other category memberships (salicylate, lectin) better explain the delayed pattern.
Behavior
Each suggestion includes a plain-language temporal context: “Histamine reactions typically appear within 1-2 hours of eating. Does that match your experience with [suspected foods]?”
This is informational — it doesn’t block the suggestion. But it gives the user a self-check that improves hypothesis accuracy.
Dependencies
- Symptom Correlator — provides correlation data for negative hypothesis evaluation
- FoodSensitivityCategory (with evidence_tier attribute)
- FoodCategoryMembership
- UserSuspectFood
- WashoutWindow
- Sensitivity Categories — temporal profiles per category
Consumers
- Meal Plan Generator — accepted suggestions trigger re-scheduling
- User-facing suggestions UI
- Cleared categories → dietary guidance simplification