Phase 2/3: Gradio Server backend, CRT frontend, engine, agents, mentor, tests, CI/CD

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Lint with ruff
+        run: |
+          pip install ruff
+          ruff check . --exclude scripts/probe_*.py,scripts/test_*.py
+
+      - name: Run unit tests
+        run: |
+          pip install pytest
+          pytest tests/ -v --ignore=tests/e2e --ignore=tests/playwright
+
+      - name: Validate dataset exists
+        run: |
+          python -c "from pathlib import Path; assert Path('data/retro-alpha-final.jsonl').exists(), 'Final dataset missing'"
+
+  deploy-check:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Verify Space readiness
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          pip install huggingface_hub
+          python -c "from huggingface_hub import HfApi; api = HfApi(token='$HF_TOKEN'); print('HF authenticated')"

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install build dependencies for llama.cpp
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    cmake \
+    git \
+    libopenblas-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python deps
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Pre-create models directory
+RUN mkdir -p /app/models
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

agents.py

@@ -0,0 +1,134 @@
+"""
+Agent inference using a local llama.cpp GGUF model.
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Dict, List
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+ASSETS = ["cash", "fd", "gov_bonds", "nifty_50", "nifty_it", "real_estate", "crypto", "gold"]
+PERSONAS = ["whale", "retail", "permabull"]
+
+# Default model path; override via MODEL_PATH env var
+MODEL_PATH = os.getenv("MODEL_PATH", "models/retro-alpha-nemotron-q4_k_m.gguf")
+
+_llm = None
+
+
+def get_llm():
+    global _llm
+    if _llm is None:
+        try:
+            from llama_cpp import Llama
+            if not Path(MODEL_PATH).exists():
+                raise FileNotFoundError(f"Model not found: {MODEL_PATH}")
+            _llm = Llama(
+                model_path=MODEL_PATH,
+                n_ctx=2048,
+                n_threads=int(os.getenv("LLAMA_THREADS", "4")),
+                verbose=False,
+            )
+        except Exception as e:
+            print(f"Warning: could not load LLM: {e}. Using mock mode.")
+            _llm = "mock"
+    return _llm
+
+
+def clean_text(text: str) -> str:
+    text = text.strip()
+    while "<think>" in text and "</think>" in text:
+        s = text.find("<think>")
+        e = text.find("</think>") + len("</think>")
+        text = text[:s] + text[e:]
+    return text.strip()
+
+
+def generate(prompt: str, system: str = "", max_tokens: int = 256, temperature: float = 0.7) -> str:
+    llm = get_llm()
+    if llm == "mock":
+        return mock_generate(prompt, system)
+
+    messages = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt})
+
+    response = llm.create_chat_completion(
+        messages=messages,
+        max_tokens=max_tokens,
+        temperature=temperature,
+    )
+    return clean_text(response["choices"][0]["message"]["content"])
+
+
+def mock_generate(prompt: str, system: str = "") -> str:
+    """Deterministic fallback when no model is loaded."""
+    if "agent" in prompt.lower() and "whale" in prompt.lower():
+        return "agent: whale\naction: buy gov_bonds 0.10\nreason: safety first\nsentiment: cautious"
+    if "agent" in prompt.lower() and "retail" in prompt.lower():
+        return "agent: retail\naction: sell nifty_it 0.10\nreason: panic selling\nsentiment: panic"
+    if "agent" in prompt.lower():
+        return "agent: permabull\naction: buy crypto 0.10\nreason: buy the dip\nsentiment: bullish"
+    if "headline" in prompt.lower():
+        return "headline: RBI holds rates steady\nimpact: cash:0 fd:0 gov_bonds:0 nifty_50:0 nifty_it:0 real_estate:0 crypto:0 gold:0\nduration: 1"
+    if "roast" in prompt.lower():
+        return "roast: diversify more\nsharpe_ratio: 0.5\nlesson: Sharpe ratio measures risk-adjusted return\nsuggestion: add bonds"
+    return "error: format only"
+
+
+def parse_agent_response(response: str, persona: str) -> Dict:
+    response = clean_text(response)
+    try:
+        agent = re.search(r"agent:\s*(\w+)", response).group(1).lower()
+        action_match = re.search(r"action:\s*(buy|sell|hold)\s+(\w+)\s+([\d.%]+)", response)
+        reason = re.search(r"reason:\s*(.+)", response).group(1).strip()
+        sentiment = re.search(r"sentiment:\s*(\w+)", response).group(1).lower()
+        return {
+            "agent": agent or persona,
+            "actions": [{"asset": action_match.group(2), "action": action_match.group(1), "amount_pct": float(action_match.group(3)), "reason": reason}],
+            "sentiment": sentiment,
+        }
+    except Exception as e:
+        return {"agent": persona, "actions": [{"asset": "cash", "action": "hold", "amount_pct": 0.0, "reason": f"parse error: {e}"}], "sentiment": "neutral"}
+
+
+def parse_news_response(response: str) -> Dict:
+    response = clean_text(response)
+    try:
+        headline = re.search(r"headline:\s*(.+)", response).group(1).strip()
+        impact_match = re.search(r"impact:\s*(.+?)(?:\nduration:|$)", response, re.DOTALL)
+        duration = int(re.search(r"duration:\s*(\d+)", response).group(1))
+        impact = {}
+        for token in impact_match.group(1).strip().split():
+            if ":" in token:
+                k, v = token.split(":")
+                impact[k] = float(v)
+        for a in ASSETS:
+            impact.setdefault(a, 0.0)
+        return {"headline": headline, "impact": impact, "duration_months": duration}
+    except Exception as e:
+        return {"headline": "Markets mixed", "impact": {a: 0.0 for a in ASSETS}, "duration_months": 1, "error": str(e)}
+
+
+def decide_agent(persona: str, state: Dict) -> Dict:
+    system = f"You are an NPC behavior designer for an educational Indian stock-market video game. Output the {persona}'s decision in exact format:\nagent: <persona>\naction: <buy|sell|hold> <asset> <amount_pct>\nreason: <short reason>\nsentiment: <bullish|bearish|neutral|panic|cautious>"
+    prompt = f"Market state: {json.dumps(state)}\nPersona: {persona}"
+    response = generate(prompt, system=system, max_tokens=200)
+    return parse_agent_response(response, persona)
+
+
+def generate_news(regime: str) -> Dict:
+    system = "You are a scenario writer for an Indian stock-market simulation game. Output exact format:\nheadline: <short headline>\nimpact: cash:<n> fd:<n> gov_bonds:<n> nifty_50:<n> nifty_it:<n> real_estate:<n> crypto:<n> gold:<n>\nduration: <months>"
+    prompt = f"Generate a fictional Indian financial headline for regime: {regime.replace('_', ' ').title()}."
+    response = generate(prompt, system=system, max_tokens=200)
+    return parse_news_response(response)
+
+
+def all_agents_decide(state: Dict) -> List[Dict]:
+    return [decide_agent(p, state) for p in PERSONAS]

app.py

@@ -0,0 +1,89 @@
+"""
+Retro Alpha — Gradio Server backend.
+Serves a custom CRT terminal frontend and exposes game API endpoints.
+"""
+
+import random
+from pathlib import Path
+
+from fastapi.responses import HTMLResponse
+from gradio import Server
+
+import agents
+import engine
+import mentor
+
+app = Server()
+ROOT = Path(__file__).resolve().parent
+STATIC_DIR = ROOT / "static"
+
+# In-memory game state (single-player)
+_game_state = engine.new_game()
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    with open(STATIC_DIR / "index.html", "r", encoding="utf-8") as f:
+        return f.read()
+
+
+@app.api(name="state")
+def get_state() -> dict:
+    return {
+        "month": _game_state.month,
+        "year": _game_state.year,
+        "prices": _game_state.prices,
+        "portfolio": _game_state.portfolio,
+        "cash": _game_state.cash_balance,
+        "total_value": _game_state.total_value(),
+        "news": _game_state.news,
+        "agent_actions": _game_state.agent_actions,
+        "game_over": _game_state.game_over,
+        "won": _game_state.won,
+    }
+
+
+@app.api(name="trade")
+def make_trade(asset: str, action: str, amount_pct: float) -> dict:
+    if _game_state.game_over:
+        return {"error": "Game over"}
+    if asset not in engine.ASSETS:
+        return {"error": "Invalid asset"}
+    engine.execute_player_trade(_game_state, asset, action, amount_pct)
+    return get_state()
+
+
+@app.api(name="advance")
+def advance_turn() -> dict:
+    if _game_state.game_over:
+        return get_state()
+
+    # Generate news
+    regime = random.choice(engine.REGIMES)  # noqa: F821
+    news = agents.generate_news(regime)
+
+    # Agents decide
+    state_snapshot = get_state()
+    agent_actions = agents.all_agents_decide(state_snapshot)
+
+    # Advance
+    engine.advance_month(_game_state, news, agent_actions)
+    return get_state()
+
+
+@app.api(name="mentor")
+def get_mentor_review() -> dict:
+    summary = engine.year_end_summary(_game_state)
+    review = mentor.generate_review(summary)
+    return {"summary": summary, "review": review}
+
+
+@app.api(name="reset")
+def reset_game() -> dict:
+    global _game_state
+    _game_state = engine.new_game()
+    return get_state()
+
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

engine.py

@@ -0,0 +1,159 @@
+"""
+Retro Alpha market simulation engine.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+
+ASSETS = ["cash", "fd", "gov_bonds", "nifty_50", "nifty_it", "real_estate", "crypto", "gold"]
+
+REGIMES = [
+    "bull_market", "bear_market", "market_crash", "recovery", "high_inflation",
+    "rate_hike", "rate_cut", "election_year", "monsoon_shock", "fii_exit",
+    "tech_boom", "real_estate_boom", "crypto_frenzy", "gold_rush", "stagnation"
+]
+
+# Annualized expected returns and volatilities (calibrated for simulation)
+ASSET_PARAMS = {
+    "cash":      {"mean": 0.00, "vol": 0.01},
+    "fd":        {"mean": 0.065, "vol": 0.005},
+    "gov_bonds": {"mean": 0.07, "vol": 0.06},
+    "nifty_50":  {"mean": 0.12, "vol": 0.16},
+    "nifty_it":  {"mean": 0.15, "vol": 0.28},
+    "real_estate":{"mean": 0.10, "vol": 0.18},
+    "crypto":    {"mean": 0.20, "vol": 0.65},
+    "gold":      {"mean": 0.08, "vol": 0.14},
+}
+
+CORRELATION = 0.3
+
+
+@dataclass
+class GameState:
+    month: int = 0
+    year: int = 1
+    prices: Dict[str, float] = field(default_factory=lambda: {a: 1.0 for a in ASSETS})
+    portfolio: Dict[str, float] = field(default_factory=lambda: {a: 0.0 for a in ASSETS})
+    cash_balance: float = 1_000_000.0
+    news: Dict = field(default_factory=dict)
+    agent_actions: List[Dict] = field(default_factory=list)
+    ledger: List[Dict] = field(default_factory=list)
+    game_over: bool = False
+    won: bool = False
+
+    def total_value(self) -> float:
+        return self.cash_balance + sum(self.portfolio[a] * self.prices[a] for a in ASSETS)
+
+
+def new_game(starting_cash: float = 1_000_000.0) -> GameState:
+    state = GameState(cash_balance=starting_cash)
+    state.portfolio = {a: 0.0 for a in ASSETS}
+    return state
+
+
+def price_shock(state: GameState, impact: Dict[str, float]):
+    """Apply a news-driven price shock."""
+    for asset in ASSETS:
+        if asset in impact:
+            state.prices[asset] *= (1 + impact[asset])
+
+
+def random_walk(state: GameState):
+    """Apply monthly random price drift correlated across assets."""
+    n = len(ASSETS)
+    corr_matrix = np.full((n, n), CORRELATION) + np.eye(n) * (1 - CORRELATION)
+    shocks = np.random.multivariate_normal(np.zeros(n), corr_matrix)
+    for i, asset in enumerate(ASSETS):
+        params = ASSET_PARAMS[asset]
+        monthly_mean = params["mean"] / 12
+        monthly_vol = params["vol"] / np.sqrt(12)
+        ret = monthly_mean + monthly_vol * shocks[i]
+        state.prices[asset] *= (1 + ret)
+
+
+def apply_agent_trades(state: GameState, agent_actions: List[Dict]):
+    """Apply agent trades to prices via order-flow pressure."""
+    pressure = {a: 0.0 for a in ASSETS}
+    for action in agent_actions:
+        for item in action.get("actions", []):
+            asset = item["asset"]
+            amt = item["amount_pct"] * (1 if item["action"] == "buy" else -1)
+            pressure[asset] += amt
+    for asset in ASSETS:
+        # Agent flow moves price by up to 3%
+        state.prices[asset] *= (1 + pressure[asset] * 0.03)
+
+
+def execute_player_trade(state: GameState, asset: str, action: str, amount_pct: float):
+    """Execute a player trade. amount_pct is relative to total portfolio value."""
+    total = state.total_value()
+    trade_value = total * amount_pct
+
+    if action == "buy":
+        if state.cash_balance < trade_value:
+            trade_value = state.cash_balance
+        shares = trade_value / state.prices[asset]
+        state.cash_balance -= trade_value
+        state.portfolio[asset] += shares
+    elif action == "sell":
+        current_value = state.portfolio[asset] * state.prices[asset]
+        sell_value = min(trade_value, current_value)
+        shares = sell_value / state.prices[asset]
+        state.portfolio[asset] -= shares
+        state.cash_balance += sell_value
+
+    state.ledger.append({
+        "month": state.month,
+        "year": state.year,
+        "asset": asset,
+        "action": action,
+        "amount_pct": amount_pct,
+        "value": trade_value,
+    })
+
+
+def advance_month(state: GameState, news: Dict, agent_actions: List[Dict]):
+    """Advance the simulation by one month."""
+    state.month += 1
+    if state.month > 12:
+        state.month = 1
+        state.year += 1
+
+    state.news = news
+    state.agent_actions = agent_actions
+
+    if news.get("impact"):
+        price_shock(state, news["impact"])
+
+    apply_agent_trades(state, agent_actions)
+    random_walk(state)
+
+    if state.year > 10:
+        state.game_over = True
+        state.won = state.total_value() >= 1_000_000
+
+
+def year_end_summary(state: GameState) -> Dict:
+    """Compute year-end stats for the mentor."""
+    year_ledger = [t for t in state.ledger if t["year"] == state.year]
+    values = [state.total_value()]  # simplified
+    returns = np.diff(values) / values[:-1] if len(values) > 1 else [0.0]
+    sharpe = (np.mean(returns) / (np.std(returns) + 1e-9)) * np.sqrt(12)
+
+    total = state.total_value()
+    allocations = {}
+    for asset in ASSETS:
+        val = state.portfolio[asset] * state.prices[asset]
+        allocations[asset] = round(val / total, 3) if total > 0 else 0.0
+
+    return {
+        "year": state.year,
+        "starting_value": 1_000_000,
+        "ending_value": total,
+        "max_drawdown": -0.25,  # placeholder
+        "sharpe_ratio": round(sharpe, 2),
+        "allocations": allocations,
+        "ledger": year_ledger,
+    }

mentor.py

@@ -0,0 +1,36 @@
+"""Sharpe Ratio Mentor — year-end review generator."""
+
+import json
+import re
+
+from agents import generate
+
+
+def parse_mentor_response(response: str) -> dict:
+    response = response.strip()
+    try:
+        roast = re.search(r"roast:\s*(.+)", response).group(1).strip()
+        sharpe = float(re.search(r"sharpe_ratio:\s*([-\d.]+)", response).group(1))
+        lesson = re.search(r"lesson:\s*(.+)", response).group(1).strip()
+        suggestion = re.search(r"suggestion:\s*(.+)", response).group(1).strip()
+        return {"roast": roast, "sharpe_ratio": sharpe, "lesson": lesson, "suggestion": suggestion}
+    except Exception as e:
+        return {
+            "roast": "Could not parse review.",
+            "sharpe_ratio": 0.0,
+            "lesson": f"Parse error: {e}",
+            "suggestion": "Try again next year.",
+        }
+
+
+def generate_review(summary: dict) -> dict:
+    system = "You are a sarcastic but caring Indian finance professor in a video game. Output a year-end review in exact format:\nroast: <witty roast, under 60 chars>\nsharpe_ratio: <number>\nlesson: <explain Sharpe ratio simply, under 100 chars>\nsuggestion: <one concrete tip, under 60 chars>"
+    prompt = (
+        f"Starting value: ₹{summary['starting_value']:,}. "
+        f"Ending value: ₹{summary['ending_value']:,.0f}. "
+        f"Max drawdown: {summary['max_drawdown']*100:.0f}%. "
+        f"Allocation: {json.dumps(summary['allocations'])}. "
+        f"Sharpe ratio: {summary['sharpe_ratio']}."
+    )
+    response = generate(prompt, system=system, max_tokens=250)
+    return parse_mentor_response(response)

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+pythonpath = .

scripts/generate_dataset.py

@@ -10,7 +10,6 @@ import os
 import random
 import time
 from pathlib import Path
-from typing import Any
 
 import aiohttp
 from dotenv import load_dotenv

static/app.js

@@ -0,0 +1,165 @@
+const API = {
+    async call(name, data = {}) {
+        const client = await window.gradioClient || (window.gradioClient = await import('https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js').then(m => m.Client.connect(window.location.origin)));
+        return await client.predict(`/${name}`, data);
+    }
+};
+
+const ASSETS = ['cash', 'fd', 'gov_bonds', 'nifty_50', 'nifty_it', 'real_estate', 'crypto', 'gold'];
+const ASSET_LABELS = {
+    cash: 'Cash (INR)',
+    fd: 'Bank FD',
+    gov_bonds: 'Gov Bonds',
+    nifty_50: 'Nifty 50',
+    nifty_it: 'Nifty IT',
+    real_estate: 'Real Estate',
+    crypto: 'Crypto',
+    gold: 'Gold'
+};
+
+let history = [];
+
+function formatMoney(n) {
+    return '₹' + Math.round(n).toLocaleString('en-IN');
+}
+
+function formatPrice(n) {
+    return n.toFixed(3);
+}
+
+function updateClock() {
+    const now = new Date();
+    document.getElementById('clock').textContent = now.toLocaleTimeString('en-IN');
+}
+setInterval(updateClock, 1000);
+updateClock();
+
+async function fetchState() {
+    const result = await API.call('state');
+    return result.data;
+}
+
+function renderState(state) {
+    document.getElementById('total-value').textContent = formatMoney(state.total_value);
+    document.getElementById('game-time').textContent = `YEAR ${state.year} / MONTH ${state.month}`;
+
+    // Ticker
+    const tickerItems = ASSETS.map(a => `${ASSET_LABELS[a]}: ${formatPrice(state.prices[a])}`).join('   ');
+    document.getElementById('ticker').textContent = tickerItems;
+
+    // News
+    const newsEl = document.getElementById('news-display');
+    if (state.news && state.news.headline) {
+        newsEl.innerHTML = `<strong>${state.news.headline}</strong><br><br>${formatImpact(state.news.impact)}`;
+    }
+
+    // Holdings
+    const tbody = document.querySelector('#holdings-table tbody');
+    tbody.innerHTML = '';
+    ASSETS.forEach(asset => {
+        const price = state.prices[asset];
+        const qty = state.portfolio[asset];
+        const value = qty * price;
+        const row = document.createElement('tr');
+        row.innerHTML = `<td>${ASSET_LABELS[asset]}</td><td>${formatPrice(price)}</td><td>${qty.toFixed(2)}</td><td>${formatMoney(value)}</td>`;
+        tbody.appendChild(row);
+    });
+
+    // Agent log
+    const logEl = document.getElementById('agent-log');
+    logEl.innerHTML = '';
+    (state.agent_actions || []).forEach(action => {
+        const div = document.createElement('div');
+        div.className = `agent-entry agent-${action.agent}`;
+        const acts = (action.actions || []).map(a => `${a.action.toUpperCase()} ${ASSET_LABELS[a.asset]} ${(a.amount_pct * 100).toFixed(0)}%`).join(', ');
+        div.innerHTML = `<strong>${action.agent.toUpperCase()}</strong> [${action.sentiment}]<br>${acts}<br><em>${action.actions[0]?.reason || ''}</em>`;
+        logEl.appendChild(div);
+    });
+
+    // Chart
+    history.push(state.total_value);
+    if (history.length > 50) history.shift();
+    drawChart(history);
+}
+
+function formatImpact(impact) {
+    if (!impact) return '';
+    return ASSETS.map(a => `${ASSET_LABELS[a]}: ${(impact[a] * 100).toFixed(1)}%`).join(' | ');
+}
+
+function drawChart(data) {
+    const canvas = document.getElementById('chart');
+    const ctx = canvas.getContext('2d');
+    const w = canvas.width;
+    const h = canvas.height;
+    ctx.clearRect(0, 0, w, h);
+    if (data.length < 2) return;
+
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    const range = max - min || 1;
+
+    ctx.strokeStyle = '#33ff33';
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    data.forEach((v, i) => {
+        const x = (i / (data.length - 1)) * (w - 20) + 10;
+        const y = h - 10 - ((v - min) / range) * (h - 20);
+        if (i === 0) ctx.moveTo(x, y);
+        else ctx.lineTo(x, y);
+    });
+    ctx.stroke();
+}
+
+async function init() {
+    // Populate asset select
+    const select = document.getElementById('trade-asset');
+    ASSETS.forEach(a => {
+        const opt = document.createElement('option');
+        opt.value = a;
+        opt.textContent = ASSET_LABELS[a];
+        select.appendChild(opt);
+    });
+
+    // Load initial state
+    const state = await fetchState();
+    renderState(state);
+
+    // Event listeners
+    document.getElementById('btn-trade').addEventListener('click', async () => {
+        const asset = document.getElementById('trade-asset').value;
+        const action = document.getElementById('trade-action').value;
+        const amount = parseFloat(document.getElementById('trade-amount').value) / 100;
+        const result = await API.call('trade', { asset, action, amount_pct: amount });
+        renderState(result.data);
+    });
+
+    document.getElementById('btn-advance').addEventListener('click', async () => {
+        const result = await API.call('advance');
+        renderState(result.data);
+        if (result.data.month === 0 || result.data.month === 12) {
+            showMentor();
+        }
+    });
+
+    document.getElementById('btn-reset').addEventListener('click', async () => {
+        history = [];
+        const result = await API.call('reset');
+        renderState(result.data);
+    });
+
+    document.getElementById('btn-close-mentor').addEventListener('click', () => {
+        document.getElementById('mentor-modal').classList.add('hidden');
+    });
+}
+
+async function showMentor() {
+    const result = await API.call('mentor');
+    const review = result.data.review;
+    document.getElementById('mentor-roast').textContent = review.roast;
+    document.getElementById('mentor-lesson').textContent = review.lesson;
+    document.getElementById('mentor-suggestion').textContent = review.suggestion;
+    document.getElementById('mentor-modal').classList.remove('hidden');
+}
+
+init().catch(console.error);

static/index.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Retro Alpha — Agentic Trading Terminal</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Share+Tech+Mono&family=VT323&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <div class="crt-frame">
+        <div class="crt-screen">
+            <div class="scanlines"></div>
+            <div class="flicker"></div>
+            <div class="screen-curve"></div>
+
+            <header class="terminal-header">
+                <div class="logo">
+                    <span class="blink">[</span> RETRO ALPHA <span class="blink">]</span>
+                </div>
+                <div class="status-bar">
+                    <span id="clock">--:--:--</span>
+                    <span class="sep">|</span>
+                    <span>INR TERMINAL</span>
+                    <span class="sep">|</span>
+                    <span id="connection" class="online">ONLINE</span>
+                </div>
+            </header>
+
+            <div class="ticker-wrap">
+                <div class="ticker" id="ticker">
+                    Loading market data...
+                </div>
+            </div>
+
+            <main class="terminal-grid">
+                <section class="panel news-panel">
+                    <h2>:: BREAKING_NEWS</h2>
+                    <div id="news-display" class="news-content">
+                        Awaiting first broadcast...
+                    </div>
+                </section>
+
+                <section class="panel chart-panel">
+                    <h2>:: PORTFOLIO_VALUE</h2>
+                    <div class="big-number" id="total-value">₹0</div>
+                    <div class="sub-line" id="game-time">YEAR 1 / MONTH 0</div>
+                    <canvas id="chart" width="400" height="180"></canvas>
+                </section>
+
+                <section class="panel holdings-panel">
+                    <h2>:: HOLDINGS</h2>
+                    <table id="holdings-table">
+                        <thead>
+                            <tr><th>ASSET</th><th>PRICE</th><th>QTY</th><th>VALUE</th></tr>
+                        </thead>
+                        <tbody></tbody>
+                    </table>
+                </section>
+
+                <section class="panel agents-panel">
+                    <h2>:: AGENT_ACTIVITY</h2>
+                    <div id="agent-log" class="agent-log"></div>
+                </section>
+
+                <section class="panel trade-panel">
+                    <h2>:: ORDER_PAD</h2>
+                    <div class="trade-form">
+                        <label>ACTION</label>
+                        <select id="trade-action">
+                            <option value="buy">BUY</option>
+                            <option value="sell">SELL</option>
+                        </select>
+                        <label>ASSET</label>
+                        <select id="trade-asset"></select>
+                        <label>AMOUNT (%)</label>
+                        <input type="number" id="trade-amount" min="1" max="100" value="10">
+                        <button id="btn-trade" class="btn-primary">EXECUTE</button>
+                        <button id="btn-advance" class="btn-secondary">ADVANCE MONTH</button>
+                        <button id="btn-reset" class="btn-danger">RESET</button>
+                    </div>
+                </section>
+            </main>
+
+            <div id="mentor-modal" class="mentor-modal hidden">
+                <div class="modal-content">
+                    <h2>:: YEAR_END_REVIEW</h2>
+                    <div id="mentor-roast" class="roast"></div>
+                    <div id="mentor-lesson" class="lesson"></div>
+                    <div id="mentor-suggestion" class="suggestion"></div>
+                    <button id="btn-close-mentor" class="btn-primary">CONTINUE</button>
+                </div>
+            </div>
+
+            <footer class="terminal-footer">
+                <span>RETRO_ALPHA v0.9.0</span>
+                <span class="sep">|</span>
+                <span>NEMOTRON-3-NANO-4B LOCAL</span>
+                <span class="sep">|</span>
+                <span>BUILT FOR HF BUILD SMALL HACKATHON</span>
+            </footer>
+        </div>
+    </div>
+    <script src="/static/app.js"></script>
+</body>
+</html>

static/style.css

@@ -0,0 +1,361 @@
+:root {
+    --phosphor: #33ff33;
+    --phosphor-dim: #1a991a;
+    --bg: #050a05;
+    --panel-bg: rgba(10, 25, 10, 0.85);
+    --danger: #ff3333;
+    --warn: #ffcc00;
+    --cyan: #33ffff;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+html, body {
+    margin: 0;
+    padding: 0;
+    height: 100%;
+    background: #111;
+    font-family: 'Share Tech Mono', 'VT323', monospace;
+    color: var(--phosphor);
+    overflow: hidden;
+}
+
+.crt-frame {
+    width: 100vw;
+    height: 100vh;
+    padding: 2vh 2vw;
+    background: radial-gradient(circle at center, #1a1a1a 0%, #000 100%);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.crt-screen {
+    position: relative;
+    width: 96vw;
+    height: 96vh;
+    background: var(--bg);
+    border-radius: 40px / 30px;
+    box-shadow:
+        inset 0 0 80px rgba(0, 0, 0, 0.9),
+        0 0 20px rgba(51, 255, 51, 0.1),
+        inset 0 0 20px rgba(51, 255, 51, 0.05);
+    overflow: hidden;
+    padding: 24px;
+    display: flex;
+    flex-direction: column;
+}
+
+.scanlines {
+    position: absolute;
+    inset: 0;
+    background: repeating-linear-gradient(
+        to bottom,
+        rgba(0, 0, 0, 0) 0px,
+        rgba(0, 0, 0, 0) 2px,
+        rgba(0, 0, 0, 0.25) 3px,
+        rgba(0, 0, 0, 0.25) 4px
+    );
+    pointer-events: none;
+    z-index: 10;
+}
+
+.flicker {
+    position: absolute;
+    inset: 0;
+    background: rgba(51, 255, 51, 0.02);
+    opacity: 0;
+    animation: flicker 0.15s infinite;
+    pointer-events: none;
+    z-index: 11;
+}
+
+.screen-curve {
+    position: absolute;
+    inset: 0;
+    border-radius: 40px / 30px;
+    box-shadow: inset 0 0 120px rgba(0, 0, 0, 0.8);
+    pointer-events: none;
+    z-index: 12;
+}
+
+@keyframes flicker {
+    0% { opacity: 0.02; }
+    50% { opacity: 0.05; }
+    100% { opacity: 0.02; }
+}
+
+.terminal-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    border-bottom: 2px solid var(--phosphor-dim);
+    padding-bottom: 12px;
+    margin-bottom: 12px;
+    text-shadow: 0 0 8px var(--phosphor);
+}
+
+.logo {
+    font-family: 'VT323', monospace;
+    font-size: 2rem;
+    letter-spacing: 2px;
+}
+
+.status-bar {
+    font-size: 0.9rem;
+    color: var(--phosphor-dim);
+}
+
+.sep {
+    margin: 0 8px;
+    color: var(--phosphor-dim);
+}
+
+.online {
+    color: var(--phosphor);
+    animation: pulse 1.5s infinite;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+
+.blink {
+    animation: blink 1s step-end infinite;
+}
+
+@keyframes blink {
+    50% { opacity: 0; }
+}
+
+.ticker-wrap {
+    background: rgba(0, 20, 0, 0.6);
+    border: 1px solid var(--phosphor-dim);
+    padding: 6px 0;
+    overflow: hidden;
+    white-space: nowrap;
+    margin-bottom: 16px;
+}
+
+.ticker {
+    display: inline-block;
+    animation: ticker 30s linear infinite;
+    padding-left: 100%;
+}
+
+@keyframes ticker {
+    0% { transform: translateX(0); }
+    100% { transform: translateX(-100%); }
+}
+
+.terminal-grid {
+    flex: 1;
+    display: grid;
+    grid-template-columns: 1.2fr 1fr 1fr;
+    grid-template-rows: 1fr 1fr;
+    gap: 16px;
+    overflow-y: auto;
+}
+
+.panel {
+    background: var(--panel-bg);
+    border: 1px solid var(--phosphor-dim);
+    padding: 14px;
+    position: relative;
+    overflow: hidden;
+}
+
+.panel::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 2px;
+    background: linear-gradient(90deg, transparent, var(--phosphor), transparent);
+    opacity: 0.5;
+}
+
+.panel h2 {
+    margin: 0 0 12px 0;
+    font-size: 1rem;
+    color: var(--cyan);
+    text-shadow: 0 0 5px var(--cyan);
+    border-bottom: 1px dashed var(--phosphor-dim);
+    padding-bottom: 6px;
+}
+
+.news-panel {
+    grid-row: span 2;
+}
+
+.news-content {
+    font-size: 1.1rem;
+    line-height: 1.5;
+    color: var(--phosphor);
+}
+
+.big-number {
+    font-size: 2.4rem;
+    font-weight: bold;
+    color: var(--phosphor);
+    text-shadow: 0 0 12px var(--phosphor);
+}
+
+.sub-line {
+    font-size: 0.9rem;
+    color: var(--phosphor-dim);
+    margin-bottom: 12px;
+}
+
+#chart {
+    width: 100%;
+    height: 130px;
+    background: rgba(0, 10, 0, 0.5);
+    border: 1px solid var(--phosphor-dim);
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.85rem;
+}
+
+th, td {
+    text-align: left;
+    padding: 4px 6px;
+    border-bottom: 1px solid rgba(51, 255, 51, 0.2);
+}
+
+th {
+    color: var(--cyan);
+}
+
+.agent-log {
+    font-size: 0.85rem;
+    line-height: 1.4;
+    max-height: 100%;
+    overflow-y: auto;
+}
+
+.agent-entry {
+    margin-bottom: 10px;
+    padding-left: 8px;
+    border-left: 2px solid var(--phosphor-dim);
+}
+
+.agent-whale { border-color: #33ff33; }
+.agent-retail { border-color: #ffcc00; }
+.agent-permabull { border-color: #ff3333; }
+
+.trade-form {
+    display: grid;
+    grid-template-columns: 1fr 2fr;
+    gap: 10px;
+    align-items: center;
+}
+
+.trade-form label {
+    font-size: 0.85rem;
+    color: var(--cyan);
+}
+
+.trade-form select,
+.trade-form input {
+    background: rgba(0, 20, 0, 0.8);
+    border: 1px solid var(--phosphor-dim);
+    color: var(--phosphor);
+    padding: 6px;
+    font-family: inherit;
+}
+
+.trade-form button {
+    grid-column: span 2;
+    padding: 10px;
+    background: rgba(0, 40, 0, 0.8);
+    border: 1px solid var(--phosphor);
+    color: var(--phosphor);
+    font-family: inherit;
+    cursor: pointer;
+    text-transform: uppercase;
+    transition: all 0.2s;
+}
+
+.trade-form button:hover {
+    background: var(--phosphor);
+    color: #000;
+    box-shadow: 0 0 15px var(--phosphor);
+}
+
+.btn-danger {
+    border-color: var(--danger) !important;
+    color: var(--danger) !important;
+}
+
+.btn-danger:hover {
+    background: var(--danger) !important;
+    color: #000 !important;
+}
+
+.mentor-modal {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.85);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 100;
+}
+
+.mentor-modal.hidden {
+    display: none;
+}
+
+.modal-content {
+    background: var(--bg);
+    border: 2px solid var(--phosphor);
+    padding: 32px;
+    max-width: 600px;
+    width: 90%;
+    box-shadow: 0 0 40px rgba(51, 255, 51, 0.3);
+}
+
+.roast {
+    font-size: 1.3rem;
+    color: var(--warn);
+    margin-bottom: 16px;
+    text-shadow: 0 0 8px var(--warn);
+}
+
+.lesson {
+    font-size: 1rem;
+    color: var(--phosphor);
+    margin-bottom: 12px;
+    line-height: 1.5;
+}
+
+.suggestion {
+    font-size: 1rem;
+    color: var(--cyan);
+    margin-bottom: 20px;
+}
+
+.terminal-footer {
+    margin-top: 12px;
+    padding-top: 8px;
+    border-top: 1px solid var(--phosphor-dim);
+    font-size: 0.75rem;
+    color: var(--phosphor-dim);
+    text-align: center;
+}
+
+@media (max-width: 900px) {
+    .terminal-grid {
+        grid-template-columns: 1fr;
+        grid-template-rows: auto;
+    }
+    .news-panel { grid-row: span 1; }
+}

tests/test_agents.py

@@ -0,0 +1,24 @@
+"""Unit tests for agent inference helpers."""
+
+import agents
+
+
+def test_parse_agent_response():
+    response = "agent: whale\naction: buy gov_bonds 0.15\nreason: safety\nsentiment: cautious"
+    parsed = agents.parse_agent_response(response, "whale")
+    assert parsed["agent"] == "whale"
+    assert parsed["actions"][0]["asset"] == "gov_bonds"
+    assert parsed["actions"][0]["amount_pct"] == 0.15
+
+
+def test_parse_news_response():
+    response = "headline: RBI hikes\nimpact: cash:0 fd:0.1 gov_bonds:-0.05 nifty_50:-0.05 nifty_it:-0.05 real_estate:-0.05 crypto:-0.05 gold:0.05\nduration: 3"
+    parsed = agents.parse_news_response(response)
+    assert parsed["headline"] == "RBI hikes"
+    assert "cash" in parsed["impact"]
+    assert parsed["duration_months"] == 3
+
+
+def test_mock_generate():
+    result = agents.mock_generate("agent whale", "")
+    assert "agent:" in result

tests/test_engine.py

@@ -0,0 +1,44 @@
+"""Unit tests for the Retro Alpha engine."""
+
+import pytest
+
+import engine
+
+
+def test_new_game():
+    state = engine.new_game()
+    assert state.cash_balance == 1_000_000
+    assert state.total_value() == 1_000_000
+    assert all(state.portfolio[a] == 0.0 for a in engine.ASSETS)
+
+
+def test_trade_buy():
+    state = engine.new_game()
+    engine.execute_player_trade(state, "nifty_50", "buy", 0.5)
+    assert state.cash_balance < 1_000_000
+    assert state.portfolio["nifty_50"] > 0
+    assert len(state.ledger) == 1
+
+
+def test_trade_sell():
+    state = engine.new_game()
+    engine.execute_player_trade(state, "nifty_50", "buy", 0.5)
+    engine.execute_player_trade(state, "nifty_50", "sell", 0.5)
+    assert state.cash_balance > 0
+
+
+def test_advance_month():
+    state = engine.new_game()
+    news = {"headline": "Test", "impact": {a: 0.0 for a in engine.ASSETS}, "duration_months": 1}
+    engine.advance_month(state, news, [])
+    assert state.month == 1
+    assert state.year == 1
+
+
+def test_game_over():
+    state = engine.new_game()
+    state.year = 11
+    state.month = 1
+    news = {"headline": "Test", "impact": {a: 0.0 for a in engine.ASSETS}, "duration_months": 1}
+    engine.advance_month(state, news, [])
+    assert state.game_over