README.md

---
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

[![Gradio](https://img.shields.io/badge/Gradio-6.19.0-blue)](https://gradio.app)
[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Space-yellow)](https://huggingface.co/spaces/puravky/skyalpha)

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](https://open-meteo.com) — a free, no-API-key weather service.

### 2. Fetch Markets
Searches [Polymarket's Gamma API](https://gamma-api.polymarket.com) 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](https://openrouter.ai)) — 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](https://openrouter.ai/keys) (free credits on signup)

### Installation

```bash
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
```bash
python main.py
```

### Launch Gradio dashboard
```bash
python main.py --ui
# → http://localhost:7860
```

### Run continuously (every 30 min)
```bash
python main.py --loop
```

---

## 🌐 Deployment (Hugging Face Spaces)

The app is designed to run on [HF Spaces](https://huggingface.co/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](LICENSE) for details.