\\Stormy AI Technical Deep Dive\\

Architecture and infrastructure

A scheduled batch job, not a continuously running service

Stormy AI only needs compute while it is building a briefing. EventBridge Scheduler launches one ECS Fargate task at midnight, 6 a.m., noon, and 6 p.m. in the America/New_York timezone. Each run uses the configured default location (Atco, NJ 08004 unless overridden). Fargate pulls the ARM64 container from ECR, retrieves the Hugging Face token from Secrets Manager, gathers public weather and geocoding data over an egress-only network path, and exits after the report is written.

Code walkthrough

The LangGraph state machine

The entry point in main.py passes a location to run_briefing(). That function constructs a strict request requiring every tool, invokes the compiled graph, collects plot metadata from the resulting tool messages, normalizes image markup, and writes the finished report.

1. Structured state beside the conversation

WeatherState extends LangGraph's MessagesState. The message list contains the conversation and tool responses, while five explicit fields hold only the meteorological data needed for deterministic fusion. This distinction keeps the diagnostic code from scraping values back out of arbitrary prose.

class WeatherState(MessagesState):
    mrms: NotRequired[dict | None]
    nexrad: NotRequired[dict | None]
    hrrr: NotRequired[dict | None]
    lightning: NotRequired[dict | None]
    diagnosis: NotRequired[dict | None]

2. Four graph nodes and one loop

The graph is small on purpose. reset_weather prevents stale data from crossing runs. The agent node calls the configured chat model with all tools bound. The tools node wraps LangGraph's ToolNode and calls gc.collect() after each batch to release large GRIB and radar allocations. collect_weather copies selected results into structured state before returning control to the model.

START → reset_weather → agent
                         │
                 tool calls present?
                    yes  │  no
                         ▼   └────────────→ END
                       tools
                         ▼
                  collect_weather
                         └───────────────→ agent

There is no separate planner model and no persistent checkpointer. The same model chooses tools and writes the final report. The conditional edge ends only when the last AI message contains no tool calls. The system prompt requires every tool exactly once per briefing, in a sensible order: geocode, alerts, current conditions, MRMS, HRRR, NEXRAD analysis and plot, lightning, skew-T, GFS, forecast, Area Forecast Discussion, then the write-up.

3. Tool messages become typed weather inputs

collect_weather_results() scans only messages since the most recent HumanMessage. It maps four tool names to state fields, parses JSON-like content with parse_tool_content(), and keeps the newest result if a tool was called more than once.

WEATHER_TOOL_STATE_MAP = {
    "get_mrms_precipitation": "mrms",
    "analyze_nexrad_level2": "nexrad",
    "get_hrrr_environment": "hrrr",
    "get_lightning": "lightning",
}

The radar plotting tool is deliberately absent from this map. A PNG path belongs in the finished report, but it is not meteorological evidence. When both MRMS and HRRR are present, the collector calls diagnose_precipitation() and stores its returned dictionary under diagnosis.

4. The diagnosis is injected back into the prompt

On the next pass through call_model(), build_system_prompt() serializes the diagnosis as JSON inside a <weather_diagnosis> block. The prompt tells the model that this block takes precedence over its own interpretation of raw fields. If only one of the minimum inputs has arrived, the prompt instead tells the model to continue gathering data.

Tool implementation

The twelve tools and what their code actually does

The tools are not thin wrappers around one commercial weather endpoint. They acquire several public datasets, handle their coordinate systems and file formats, perform spatial and thermodynamic calculations, and return either structured dictionaries or official NWS text. Pydantic schemas constrain the arguments the model can send.

Deterministic meteorology

Why some conclusions stay outside the language model

Radar reflectivity alone cannot establish surface precipitation type. A model flag alone cannot prove anything is falling. Stormy AI resolves that problem in diagnostics.py, where explicit functions interpret each source and combine them into a single auditable dictionary.

Briefing assembly and publishing

The LLM output is not written directly to disk

The final AI message first passes through deterministic post-processing in briefing.py. ensure_radar_image_markdown() inserts the public radar image if the model omitted it. ensure_gfs_guidance_markdown() does the same for all required day-one through day-three charts. normalize_briefing_images() converts Markdown or bare S3 image references into sized HTTPS <img> elements.

s3://stormy-ai-files/briefings/<YYYY-MM-DD>/<zip>/<HH_MM>.md  (UTC keys)
s3://stormy-ai-files/radar/<YYYY-MM-DD>/<HH_MM>.png
s3://stormy-ai-files/models/gfs/<YYYY-MM-DD>/<type>/<forecast_hour>.png
s3://stormy-ai-files/latest.txt  →  newest briefing S3 URI

This site's /stormy-ai/ route reads latest.txt, validates the returned S3 URI, fetches that object, renders the Markdown, and returns a friendly 503 state when S3 is unavailable. This page lives at /stormy-ai/about/. The agent repository and the website can therefore be deployed independently.

Language-model selection

Choosing the model for a long, tool-heavy weather run

Model selection for Stormy AI is less about finding the model with the most creative prose and more about finding one that can reliably finish a long agent run. A briefing can contain several rounds of tool calls, large NWS text products, structured radar and model results, and metadata for many generated images. The model has to retain that context, call every required tool, preserve units and timestamps, and stop calling tools when it is finally ready to write.

The current cloud selection

The checked-in deployment configuration selects zai-org/GLM-5.3-Flash, routed through the Hugging Face Inference API to Baseten. This is a pragmatic cloud choice: the ECS task can reach a hosted, tool-capable chat model without running a second model-serving stack, and the provider is available through the same OpenAI-compatible interface already used by LangChain. It is the current deployment choice, not a claim that one model will remain best forever.

Why temperature is zero

The configured temperature is 0 because the desired variability comes from the atmosphere, not from the wording engine. Lower sampling variability helps keep section order, tool behavior, units, and phrasing more repeatable between scheduled runs. It does not make the report deterministic—the source data, provider behavior, and tool-call sequence can still vary—but it removes unnecessary creativity from a factual briefing workflow.

llm:
  provider: huggingface
  model: zai-org/GLM-5.3-Flash:baseten
  temperature: 0
  huggingface:
    base_url: https://router.huggingface.co/v1
    inference_provider: baseten

How the code keeps the choice replaceable

create_chat_model() is a small factory. It returns ChatOllama for local execution or an OpenAI-compatible ChatOpenAI client for Hugging Face Inference Providers. Environment variables can override the provider, model, inference provider, Ollama base URL, and temperature. Everything after that factory receives the same LangChain chat-model contract, so agent.py, the tool schemas, and the graph edges do not know which backend was selected.

A replacement model should be evaluated with the complete workflow: whether it geocodes first, calls all twelve tools with valid arguments, waits for the diagnostic state, preserves source values, includes the required report sections, and finishes without entering a tool loop. A good standalone answer is not enough. The test that matters is a complete, meteorologically faithful briefing.