Input
Profile
What are credits?
- 1 credit = 1 weather report generation
- Credits refresh monthly based on your plan
- Org members share the organization's credit pool
API Keys
Save this key — it will not be shown again
Loading keys...
Usage
No generation history yet
Files
0 files
0 B
Now Playing
No files yet
Organization Feed
External apps (e.g. GRN player) use this URL to consume your forecasts. Authenticate with X-API-Key header.
Loading...
Loading...
Webhook
Configure a URL where notifications are sent when weather reports are completed or fail.
Subscribed Events
Organization
Create an organization to share credits with your team.
Org Credits: 0
Plan: free
Members
System Overview
High-level architecture and how each layer connects
Galactic Radio Weather is a production FastAPI service that generates broadcast-quality AI weather reports with natural-sounding TTS audio. It serves three types of clients simultaneously:
🌐
Web Browser
Firebase OAuth
⌨
CLI Tool
API Key Auth
🤖
AI Agent
A2A Protocol
FastAPI Application
REST /api/v1/* • JSON-RPC /a2a • Static Frontend
Weather
Open-Meteo API
LLM
Gemini 2.5 Pro
TTS
Gemini / ElevenLabs
Storage
Google Cloud Storage
Firestore Database
Users • Jobs • DJs • Configs • Orgs • API Keys
FrameworkFastAPI + Uvicorn
Python3.12+
DatabaseCloud Firestore
DeployCloud Run (GCP)
AuthFirebase Auth
BuildCloud Build + Docker
Generation Pipeline
How a weather report goes from request to broadcast-ready audio
1
Request Received
User submits location, time of day, voice, duration, and optional DJ personality. Credit is deducted (1 credit per generation).
POST /api/v1/weather/generate2
Fetch Weather Data
Calls Open-Meteo API with geocoded coordinates. Returns current conditions, today/tomorrow forecast, hourly data, and alerts.
WeatherService.fetch_full(location, date)3
LLM Script Generation
Sends weather data + system prompt + user prompt to Gemini 2.5 Pro. The LLM writes a broadcast-ready weather script.
LLMService.generate_weather_report()Model: Gemini 2.5 ProRetry: checks for error indicators
4
Text-to-Speech
Converts the script to natural-sounding audio. Supports Gemini TTS (default) and ElevenLabs.
TTSProvider.generate_audio(text, voice_id)Gemini TTS: Alnilam, Kore, PuckElevenLabs: Premium voices
5
Audio Processing
Uses FFmpeg to process the raw audio. Handles format conversion and quality optimization.
AudioProcessingService.process_audio_for_duration()6
Upload to Cloud Storage
Final MP3 is uploaded to Google Cloud Storage with a signed URL.
StorageService.upload_audio() → signed_urlFailure Handling: If any step fails, the credit is automatically refunded and the job is marked as failed with a descriptive error message.
Authentication
Three auth methods serving different client types
Web
Firebase OAuth
Google Sign-In popup via Firebase Auth SDK. The frontend sends the Firebase ID token as a Bearer token.
Google Popup→Firebase Token→Backend verify_id_token()
Uses a separate Firebase project (grn-weather-auth-only) dedicated to authentication.
CLI / API
API Key
User API keys (prefixed grw_) generated at signup. Sent via X-API-Key header.
X-API-Key header→APIKeyValidator→Firestore lookup
Service
Service API Keys
For service-to-service communication. Configured in SERVICE_API_KEYS env var. Grants SERVICE role.
Roles: USER (default), ADMIN (superuser), SERVICE (machine-to-machine). Admin check:
require_admin() dependency.Credit System
Usage-based billing with tiered subscription plans
Free
$0/mo
3 credits
Popular
Starter
$10/mo
50 credits
Pro
$25/mo
200 credits
Business
$50/mo
500 credits
1 credit = 1 weather report generation. Getting weather data alone is free. Credits are deducted before generation and refunded on failure.
Organizations share a credit pool among members.
A2A Protocol (Agent-to-Agent)
Google's open protocol for AI agents to discover and use our service
The A2A layer runs alongside the existing REST API. Any A2A-compatible agent can discover our service via the Agent Card, then interact using JSON-RPC messages.
🤖
AI Agent
1. Discover
Agent Card
GET /.well-known/agent.json
🤖
AI Agent
2. Send Message
JSON-RPC
POST /a2a
3. Execute
Executor
Skill Router → Pipeline
Agent Skills
generate_weather_report
Full pipeline: LLM script + TTS audio. Costs 1 credit.
weatheraudiotts
generate_dj_weather_report
Same pipeline but with a DJ personality overlay. Costs 1 credit.
djbroadcast
get_weather_data
Returns raw weather data as structured JSON. Free, no credits.
weatherfree
purchase_credits
Buy credits using AP2 payment mandates.
paymentap2
JSON-RPC Methods
| Method | Description |
|---|---|
message/send | Send a message to the agent, returns task result |
message/stream | Send + stream progress via SSE events |
tasks/get | Get current status and artifacts of a task |
tasks/cancel | Cancel a running generation task |
AP2 Payments (Agent Payment Protocol)
How AI agents pay for weather report generation
AP2 is Google's protocol for agent-to-merchant payments using cryptographic IntentMandates. Agents include a payment mandate in the A2A message DataPart.
1
Agent Sends IntentMandate
Included as a DataPart with key ap2.mandates.IntentMandate in the A2A message.
2
Validate Mandate
Check expiry timestamp and verify merchant name matches.
AP2PaymentHandler.validate_mandate()3
Authorize & Generate
If valid, authorize 1 credit and proceed with generation.
4
Return PaymentReceipt
On success, a ap2.PaymentReceipt DataPart is returned.
Price: $1.00 per creditCurrency: USD
MCP Server (Model Context Protocol)
Streamable HTTP tool server for remote agent access
The MCP server exposes weather generation operations as tools that remote agents can discover and call using the standard MCP protocol.
🤖
Remote Agent
1. Initialize
MCP Endpoint
POST /api/v1/weather-mcp
🤖
Remote Agent
2. tools/call
Tool Router
weather.dj_generate
3. Execute
Pipeline
LLM → TTS → GCS
Available Tools (10)
weather.generate
Generate weather report with TTS audio.
weathertts1 credit
weather.dj_generate
Generate with DJ personality.
djbroadcast1 credit
weather.status
Poll job progress.
statusfree
weather.forecast
Look up cached forecast audio.
cachefree
weather.data
Raw weather data.
weatherfree
weather.voices
List available TTS voices.
ttsfree
dj.list / dj.info
List DJ personalities or get details.
djfree
files.list / files.delete
Manage generated audio files.
storagefree
Connection Config
{
"mcpServers": {
"galactic-radio-weather": {
"type": "http",
"url": "https://galactic-radio-weather-355622637773.us-central1.run.app/api/v1/weather-mcp",
"headers": { "X-API-Key": "${GRW_SERVICE_API_KEY}" }
}
}
}
Protocol Details
| Property | Value |
|---|---|
| Transport | Streamable HTTP |
| Protocol Version | 2025-11-25 |
| Format | JSON-RPC 2.0 |
| Auth | X-API-Key header (service keys) |
| Session | Mcp-Session-Id returned on initialize |
| Env Variable | GRW_SERVICE_API_KEY |
Prompt Engineering
How the AI generates weather scripts
Prompt Architecture
System Prompt
Defines the AI's personality and output format.
User Prompt Template
The request template with placeholders for location, time, etc.
Duration Templates
15s: Quick headline · 30s: Brief overview · 60s: Full report
Context Injection
Weather data, location, date, time, voice info, and DJ traits are appended automatically.
Customization
Users can override prompts per-session via the "Style" button. Custom prompts can be fetched from an external URL. Changes are browser-session only.
API Reference
REST endpoints and their purpose
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/health | Health check | None |
| POST | /api/v1/weather/generate | Generate weather report | Required |
| GET | /api/v1/weather/status/{id} | Poll job status | Required |
| GET | /api/v1/weather/voices | List available voices | Required |
| GET | /api/v1/forecast/{location}/weather | Get weather data (free) | Required |
| POST | /api/v1/dj/generate | Generate DJ weather report | Required |
| GET | /api/v1/dj/list | List DJ personalities | Required |
| POST | /api/v1/users/oauth-signin | Create/get user profile | Firebase |
| GET | /api/v1/users/me | Get current user profile | Required |
| POST | /api/v1/users/api-keys | Generate new API key | Required |
| GET | /api/v1/files | List user's audio files | Required |
| MCP Server Endpoints | |||
| POST | /api/v1/weather-mcp | MCP JSON-RPC endpoint | Service key |
| A2A Protocol Endpoints | |||
| GET | /.well-known/agent.json | Agent Card discovery | None |
| POST | /a2a | A2A JSON-RPC endpoint | Required |
CLI Tool (grw)
Command-line interface for power users and automation
Install: pip install -e ".[cli]" — then use grw from the terminal.
Weather Generation
grw generate "Beverly Hills, CA"Generate a weather report for a location
grw generate "NYC" --voice Kore --duration 30 --tod morningGenerate with specific voice, duration, and time of day
grw generate "Tokyo" --dj <uuid>Generate with a DJ personality
Utilities
grw voicesList all available voices
grw status <job_id>Check generation job status
grw djsList available DJ personalities
A2A Agent Commands
grw agent cardFetch and display the Agent Card
grw agent send "Beverly Hills, CA" --streamSend an A2A message with SSE streaming
Deployment
Cloud Build, Docker, and Cloud Run configuration
Push to main
Git push triggers Cloud Build
→
Docker Build
python:3.12-slim + ffmpeg
→
Push to GCR
Container Registry
→
Cloud Run
Auto-scaling, port 8080
Important: Cloud Build's
--set-env-vars flag replaces ALL env vars on deploy. All env vars must be in cloudbuild.yaml.Tech Stack
Every tool and service in the system
Backend
FastAPIWeb framework
PydanticSettings & validation
UvicornASGI server
httpxAsync HTTP client
AI / ML
Gemini 2.5 ProScript generation
Gemini TTSVoice synthesis
ElevenLabsPremium TTS
Google Cloud
Cloud RunContainer hosting
Cloud BuildCI/CD pipeline
Cloud StorageAudio files (GCS)
FirestoreNoSQL database
Firebase AuthOAuth + tokens
Protocols
A2A SDKAgent-to-Agent
AP2Agent Payments
JSON-RPC 2.0A2A transport
Data & Weather
Open-MeteoWeather API (free)
FFmpegAudio processing
TimezoneFinderGeo-to-timezone
Dev & CLI
TyperCLI framework
RichTerminal formatting
pytestTesting (260+ tests)
RuffLinting