Recommendations and AI¶
The Python API (chart.recommendations) ranks the published heat actions in
the action repository for a saved plan's country and writes a
short insight beside the ranking
(POST /saved-plans/{id}/recommendations). The web app does not show either
for now: the "Recommended for your plan" panel and its placeholder AI insight
were removed from the actions page, which opens a saved plan on the plan's
season.
What is configurable¶
An administrator chooses, under Settings → Recommendations:
| Setting | Options |
|---|---|
| Ranker | Rules (default) or a self-hosted classifier |
| Insight provider | Template (default, no AI), Amazon Bedrock, Anthropic, OpenAI or compatible server |
| Model | Picked from the provider's own model list, or typed when the provider cannot list |
Credentials and endpoints are set on the API server only and never stored in the database or sent to the browser. An option the environment does not enable is shown disabled with the variable to set.
| Variable | Enables |
|---|---|
AWS_REGION + instance role |
Amazon Bedrock (Converse API). Needs the chart[bedrock] extra, which the core image installs, and IAM permission for bedrock:InvokeModel, bedrock:ListFoundationModels and bedrock:ListInferenceProfiles. |
ANTHROPIC_API_KEY |
Anthropic Messages API. |
OPENAI_API_KEY |
OpenAI. |
OPENAI_BASE_URL |
Any OpenAI-compatible server instead of OpenAI, e.g. a small model served by vLLM or Ollama on the sandbox VM (http://<vm>:11434/v1 for Ollama). A key is optional. |
CHART_INSIGHT_MODELS |
Comma-separated model IDs offered when a provider cannot list its models. |
CHART_RECOMMENDER_URL |
The self-hosted classifier (contract below). |
On the sandbox these are read from .env.prod by infra/aws/docker-compose.yml.
How it behaves¶
- Candidates: the published actions tagged Extreme heat for the plan's country (generic actions plus that country's own), in its wording.
- Rules ranking (always available). Each action scores:
| Matches | Score |
|---|---|
| Plan's timing (before, during or after the heat season) | 4 |
Plan's outcome (Low birth weight for lbw, Under-5 mortality for under_5_mortality) |
3 |
| Cost Low or No additional cost | 2 |
| Cost Medium | 1 |
The cost scores apply only when heat risk is not clearly raised. Ties keep feed order, and each ranked action carries its reasons. The repository is small and there is no record yet of what planners chose, so CHART uses these explicit rules rather than a trained model. - Classifier: replaces only the order. The rule reasons are still shown. If the classifier errors or times out, the rules order is returned with a note saying so. - Insight: the template unless a provider and model are chosen. The model receives only the plan's figure, risk reading, timing and the ranked actions, and is told to use nothing else. Any provider failure returns the template with a note. A generated insight is stored on the plan and reused until the provider, model or ranking changes, so page views do not call the model again. - The figures and the ranking never depend on the insight.
Every settings change writes a recommendation_settings_changed audit event
with the values before and after.
Classifier contract¶
A classifier is any HTTP service, for example a small scikit-learn or gradient-boosted model behind FastAPI on the sandbox VM. CHART calls:
POST {CHART_RECOMMENDER_URL}/rank
{
"plan": {"outcome": "lbw", "country_code": "KE", "risk_level": "possible",
"timing": "before", "percent": 4.2, "ratio": {...} | null},
"candidates": [{"id": "rec...", "title": "...", "seasons": ["before", "during"],
"cost_level": "Low", "health_outcomes": ["Low birth weight"],
"target_populations": ["Pregnant women"],
"action_types": ["..."], "departments": ["Health"]}]
}
→ 200 {"model": "recommender-v1", "scores": {"<candidate id>": 0.82, ...}}
Higher scores rank first; candidates without a score rank last. The returned
model is shown on the page as provenance.
Towards a trained or fine-tuned model¶
The rules ranking is the baseline any classifier must beat. To curate
training data, record for each saved plan which recommended actions planners
open, assign and complete (action progress is held in the browser today and
would first need to be stored by the API). Those labels, with the plan
features above, train a classifier served behind the contract. The same data,
with reviewed example insights, can fine-tune a small language model served
through OPENAI_BASE_URL; no CHART code changes are needed to switch to it.