\\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 hourly from 8 a.m. through 8 p.m., plus a 4 a.m. overnight run, 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.

Continuous integration and delivery

Validate every branch; deploy only from main

Stormy AI uses two push-triggered GitHub Actions workflows with different responsibilities and permissions. .github/workflows/tests.yml validates every branch without a GitHub environment or production secrets. .github/workflows/deploy.yml responds only to pushes on main; its deployment jobs use the prod GitHub environment and are the only jobs that receive AWS credentials.

Continuous integration reproduces the local checks

The Test and lint workflow checks out the exact commit, installs uv with dependency caching, installs the project's configured Python version, and recreates the locked environment with uv sync --frozen. It then delegates to make lint and make test. The Makefile is the shared contract: flake8, isort, Black, and pytest run through the same commands locally and in GitHub. The workflow needs only read access to repository contents. It runs for branch pushes; there is no separate pull_request trigger.

Continuous delivery routes only the work that changed

The Deploy workflow first uses dorny/paths-filter to classify the commit. Application, configuration, dependency, test, or container changes start a native ARM64 build and publish wx_briefing_agent:latest to ECR. Docker Buildx reuses a GitHub Actions cache to avoid rebuilding every unchanged layer. Changes under infra/ start the Terraform path, which configures AWS and runs make infra-init, make infra-plan, and make infra-apply. Because the Makefile supports both paths, changing it activates both jobs.

The prod environment scopes deployment secrets, while the deploy-main concurrency group queues production runs instead of cancelling one halfway through an image push or Terraform apply. AWS authentication currently uses access-key secrets. The image is published only as latest, and the Terraform job automatically applies after planning in the same job; it does not save an immutable image tag or a reviewed plan artifact for rollback.

Code walkthrough

The LangGraph state machine

The entry point in main.py passes a location to run_briefing(). That function constructs a prompt requesting 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 instructs the model to call every tool once per briefing unless it fails or returns unusable data, in a sensible order: geocode, alerts, current conditions, MRMS, HRRR, NEXRAD analysis and plot, the METAR station-model plot, lightning, skew-T, GFS, forecast, Area Forecast Discussion, then the write-up. The graph does not separately reject a final answer when the model stops early, so completion remains model-driven.

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 thirteen 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 radar image if the model omitted it. ensure_metar_image_markdown() places the station-model map in Current Weather, preferably immediately after radar. ensure_gfs_guidance_markdown() does the same for all required day-one through day-three charts. normalize_briefing_images() converts Markdown image syntax and normalizes existing <img> tags into consistently sized 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/metar/<YYYY-MM-DD>/<HH_MM>.png
s3://stormy-ai-files/forecast_zones/<zone-id>.png
s3://stormy-ai-files/models/gfs/<YYYY-MM-DD>/<type>/<forecast_hour>.png
s3://stormy-ai-files/latest.txt  →  newest briefing S3 URI

The briefing key uses its generation time converted to UTC. Radar and METAR keys use their source observation times, while GFS keys use the model-cycle date.

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:baseten. The model factory normalizes the provider suffix and sends requests through the Hugging Face router's OpenAI-compatible endpoint. This is a pragmatic cloud choice: the ECS task can reach a hosted, tool-capable chat model without running a separate model-serving stack. 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 thirteen 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.