README.md

metadata

title: skyAlpha
emoji: 🌤️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
pinned: false

🌤️ skyAlpha — Multi-Agent Weather Prediction & Polymarket Trading System

An autonomous AI agent that analyzes live weather forecasts and Polymarket prediction market odds to execute paper trades across 5 global cities using LLM reasoning, the Kelly Criterion, and a Gradio dashboard.

---

✨ Features

Feature	Description
Live Weather	Real-time forecasts from Open-Meteo (no API key needed)
LLM Analysis	Gemma via OpenRouter compares forecast vs. market probabilities
Kelly Sizing	Optimal position sizing with 25% fractional Kelly and 10% per-trade cap
Hedging	Automatic 20% counter-position hedge on every trade
Demo Mode	Falls back to simulated markets when Polymarket API is unreachable
Dashboard	Real-time Gradio UI with balance, markets, portfolio, and trade history
Zero Risk	Paper trading — no real money involved

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    main.py (Orchestrator)               │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  data/       │  │  agent/      │  │  trading/    │  │
│  │              │  │              │  │              │  │
│  │ weather.py  │─▶│  llm.py     │─▶│ kelly.py    │  │
│  │ Open-Meteo   │  │  OpenRouter  │  │  Kelly Calc  │  │
│  │              │  │  (Gemma)     │  │              │  │
│  │ polymarket   │  │              │  │ paper_trader│  │
│  │ .py          │  │              │  │ .py          │  │
│  │ Gamma API    │  │              │  │  pm-trader   │  │
│  │ + Demo       │  │              │  │  (paper)     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  ui/dashboard.py — Gradio 6 (4 tabs)             │   │
│  │  📊 Dashboard │ 💼 Portfolio │ 📜 History         │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

---

🧠 How It Works

Each agent cycle executes 5 steps:

1. Fetch Weather

Retrieves today's high/low temperatures and conditions for New York, London, Miami, Tokyo, Los Angeles from Open-Meteo — a free, no-API-key weather service.

2. Fetch Markets

Searches Polymarket's Gamma API for active weather prediction markets. If the API is unreachable (timeout, rate limit, or network issue), the system falls back to 5 hardcoded demo markets and shows a yellow warning banner in the UI.

3. LLM Analysis

Sends the weather data and market prices to Google Gemma 4 31B (via OpenRouter) — a free, OpenAI-compatible API. The LLM is prompted to:

• Compare forecast-implied probabilities to market prices
• Identify trades with >3% edge
• Output a structured JSON decision

A robust JSON extractor (_extract_json) handles truncation, markdown fences, and malformed responses.

4. Position Sizing

Uses the Kelly Criterion to calculate optimal bet size:

f* = (b × p - q) / b

where:
  p = model probability
  b = net payout odds
  q = 1 - p (probability of loss)

We apply 25% fractional Kelly and cap at 10% of bankroll per trade for risk management.

5. Paper Trade

Executes the trade via pm-trader CLI (paper mode). Each trade gets an automatic 20% hedge on the opposite side to limit downside. In demo mode, trades are logged and skipped.

---

🛠️ Tech Stack

Layer	Technology
Language	Python 3.11+
LLM	Google Gemma 4 31B via OpenRouter
Weather	Open-Meteo (free, no key)
Market Data	Polymarket Gamma API + hardcoded demo fallback
Paper Trading	pm-trader CLI
UI	Gradio 6
Position Sizing	Kelly Criterion (25% fractional)
Logging	Loguru

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• OpenRouter API key (free credits on signup)

Installation

git clone https://github.com/your-username/skyalpha.git
cd skyalpha

python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env
# Edit .env with your OpenRouter key

Configuration

Variable	Required	Default	Description
OPENROUTER_API_KEY	✅	—	LLM API key
MODEL	❌	google/gemma-4-31b-it:free	OpenRouter model ID
STARTING_BALANCE	❌	10000	Paper trading starting balance
APIFY_API_TOKEN	❌	—	Only needed if using Apify weather source

---

🎯 Usage

Run one cycle

python main.py

Launch Gradio dashboard

python main.py --ui
# → http://localhost:7860

Run continuously (every 30 min)

python main.py --loop

---

🌐 Deployment (Hugging Face Spaces)

The app is designed to run on HF Spaces with zero configuration:

1. Create a new Space at https://huggingface.co/new-space
2. Select Gradio SDK
3. Push the repo
4. Set these Secrets in Space settings:

Secret	Value
OPENROUTER_API_KEY	your key
MODEL	google/gemma-4-31b-it:free
STARTING_BALANCE	10000

The app auto-detects demo mode when Polymarket's Gamma API is unreachable (which it is from HF's network) and shows live weather + simulated markets.

---

📁 Project Structure

skyalpha/
├── agent/
│   └── llm.py              # OpenRouter client + JSON extraction
├── data/
│   ├── weather.py          # Open-Meteo & Apify weather fetchers
│   └── polymarket.py       # Gamma API + demo market fallback
├── trading/
│   ├── kelly.py            # Kelly Criterion sizing + hedging
│   └── paper_trader.py     # pm-trader CLI wrapper
├── ui/
│   └── dashboard.py        # Gradio 6 dashboard (4 tabs)
├── results/                # Per-cycle JSON logs
├── app.py                  # HF Spaces entry point
├── main.py                 # Orchestrator / CLI entry point
├── requirements.txt
├── .env.example
└── README.md

---

🧪 Demo Mode

When Polymarket's Gamma API is unreachable (network restrictions, rate limiting, or timeout), the system:

1. Falls back to 5 hardcoded DEMO_MARKETS with realistic prices
2. Short-circuits subsequent API calls via _GAMMA_FAILED flag (no repeated timeouts)
3. Skips real trade execution — logs intended trades as ⚠️ DEMO — would TRADE market for $AMOUNT
4. Shows a warning banner in the dashboard: "⚠️ Demo Mode — Polymarket API unreachable"
5. Resets to real mode if the API recovers on the next cycle

Demo markets cover all 5 target cities with plausible temperature thresholds and prices.

---

🔒 Error Handling

Scenario	Handling
Gamma API timeout	Falls back to DEMO_MARKETS after 5s
LLM JSON parse failure	Multi-strategy _extract_json() with truncation repair
pm-trader unavailable	Graceful FileNotFoundError catch → demo defaults
Missing API key	Returns parse error with clear log message
Content filter (LLM)	Returns safe default with "Parse error"

---

📈 Roadmap

• Dynamic demo markets — generate thresholds based on actual weather data
• Multi-model ensemble — average predictions from multiple LLMs
• Backtesting engine — replay historical data to validate strategy
• Real Polymarket CLOB — swap paper_trader for real on-chain execution
• Telegram alerts — notify on trade execution and P&L changes
• Historical calibration — EMOS/CRPS for probability calibration

---

📄 License

MIT — see LICENSE for details.