init

.env.example

@@ -0,0 +1,3 @@
+HF_TOKEN=hf_xxxxxxxxxxxxx
+API_BASE_URL=https://router.huggingface.co/v1
+MODEL_NAME=Qwen/Qwen2.5-7B-Instruct

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI - Submission Validation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  PYTHONPATH: ${{ github.workspace }}
+
+jobs:
+  validate:
+    name: Tests & Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          pip install uv
+          uv venv .venv
+          source .venv/bin/activate
+          uv pip install -e .
+          uv pip install pytest pyyaml
+
+      - name: Run unit tests
+        run: |
+          source .venv/bin/activate
+          pytest tests/ -v
+
+      - name: Validate openenv.yaml
+        run: |
+          source .venv/bin/activate
+          python -c "
+          import yaml
+          with open('openenv.yaml') as f: spec = yaml.safe_load(f)
+          assert spec['name'] and spec['version'] and spec['entrypoint']
+          assert len(spec['tasks']) >= 3
+          assert 'observation_space' in spec and 'action_space' in spec
+          print(f'openenv.yaml OK: {spec[\"name\"]} v{spec[\"version\"]}')
+          "
+
+      - name: Validate Pydantic models
+        run: |
+          source .venv/bin/activate
+          python -c "
+          from app.models import (MarketObservation, TradeAction, StepResult,
+              ResetResult, EnvironmentState)
+          assert 'side' in TradeAction.model_fields
+          assert 'quantity' in TradeAction.model_fields
+          for f in ['ticker','date','price','price_history','cash','position','portfolio_value','task_id','step_number','total_steps']:
+              assert f in MarketObservation.model_fields, f'Missing: {f}'
+          print('models OK')
+          "
+
+      - name: Validate endpoints
+        run: |
+          source .venv/bin/activate
+          python -c "
+          from fastapi.testclient import TestClient
+          from app.main import app
+          c = TestClient(app)
+          assert c.post('/reset', json={}).status_code == 200
+          r = c.post('/step', json={'side': 'hold', 'quantity': 0})
+          assert r.status_code == 200 and -1.0 <= r.json()['reward'] <= 1.0
+          assert c.get('/state').status_code == 200
+          print('endpoints OK')
+          "
+
+      - name: Validate tasks
+        run: |
+          source .venv/bin/activate
+          python scripts/validate_tasks.py
+
+      - name: Verify inference.py structure
+        run: |
+          test -f inference.py
+          grep -q "from openai import OpenAI" inference.py
+          grep -q "API_BASE_URL" inference.py
+          grep -q "MODEL_NAME"    inference.py
+          grep -q "HF_TOKEN"      inference.py
+          grep -q '\[START\]'     inference.py
+          grep -q '\[STEP\]'      inference.py
+          grep -q '\[END\]'       inference.py
+
+      - name: Verify inference.py imports
+        run: |
+          source .venv/bin/activate
+          python inference.py --help
+
+  docker-build:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t stocker:ci .
+      - name: Container /reset returns 200
+        run: |
+          docker run -d --name stocker-test -p 7860:7860 stocker:ci
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:7860/health >/dev/null 2>&1; then break; fi
+            sleep 2
+          done
+          CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+            -H "Content-Type: application/json" -d '{}' http://localhost:7860/reset)
+          [ "$CODE" = "200" ] || exit 1
+          docker stop stocker-test && docker rm stocker-test

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.egg-info/
+dist/
+build/
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.log
+.venv/
+results.json

CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+## Project Overview
+**Stocker** — a stock-trading RL environment built on top of OpenEnv. The agent
+sees daily market observations and must produce a `(side, quantity)` trade.
+
+## Stack
+- **Language:** Python 3.10+ (Docker image runs 3.13)
+- **Framework:** FastAPI + Uvicorn
+- **Models:** Pydantic v2 + pydantic-settings
+- **OpenEnv:** `openenv-core>=0.2.0`
+- **Package manager:** `uv`
+- **Tests:** pytest + FastAPI TestClient
+
+## Layout
+```
+.
+├── app/                # FastAPI application
+│   ├── api/            # HTTP routers (health, meta, env, state, frontend)
+│   ├── core/           # environment.py, graders.py, tasks.py
+│   ├── config.py
+│   ├── main.py
+│   └── models.py       # Pydantic schemas
+├── server/app.py       # OpenEnv entry point (server.app:main)
+├── tasks/              # JSON task definitions (loaded at import)
+├── tests/              # pytest suite
+├── scripts/            # helper CLIs
+├── inference.py        # LLM rollout script (root, OpenEnv requirement)
+├── client.py           # Python HTTP client
+├── Dockerfile          # builds via uv
+├── openenv.yaml        # OpenEnv spec
+└── run.sh              # local dev server
+```
+
+## Conventions
+- All Pydantic models live in [app/models.py](app/models.py) — keep them
+  named: `MarketObservation`, `TradeAction`, `RewardResult`, `StepResult`,
+  `ResetResult`, `EnvironmentState`.
+- `StockerEnv` exposes `reset() / step() / state() / load_snapshot()`.
+- `inference.py` MUST keep the `[START] / [STEP] / [END]` stdout format —
+  graders parse it.
+- Tasks are inline in [app/core/tasks.py](app/core/tasks.py) plus optional
+  JSON files in [tasks/](tasks/) (auto-loaded at import).
+- Reward is always clipped to `[-1.0, 1.0]` at the boundary.
+- The server runs on port `7860` (HF Spaces convention).
+
+## Don't
+- Don't introduce a frontend build step — the HTML lives inline in
+  [app/api/frontend.py](app/api/frontend.py).
+- Don't bundle large data files in the Docker image; pull at runtime if
+  needed.
+- Don't break the OpenAI-client pattern in `inference.py` — judges rerun it.

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.13-slim
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+WORKDIR /app
+
+RUN pip install --no-cache-dir uv
+
+COPY pyproject.toml ./
+RUN if [ -f uv.lock ]; then \
+        uv export --no-dev --no-hashes > requirements.txt; \
+    else \
+        uv pip compile pyproject.toml -o requirements.txt; \
+    fi && \
+    pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN adduser --disabled-password --gecos "" appuser && \
+    chown -R appuser:appuser /app
+USER appuser
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health')" || exit 1
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,139 @@
+---
+title: Stocker - OpenEnv
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+app_port: 7860
+base_path: /web
+tags:
+  - openenv
+---
+
+# Stocker - OpenEnv Environment
+
+An RL environment where an AI agent makes stock-trading decisions (buy / sell / hold)
+over a sequence of daily market observations and is rewarded for portfolio P&L.
+
+## Tasks
+
+| Task | Difficulty | Steps | Description |
+|------|-----------|-------|-------------|
+| `task_easy`   | Easy   | 10 | Steady uptrend |
+| `task_medium` | Medium | 10 | Volatile sideways market |
+| `task_hard`   | Hard   | 10 | Bull-then-bear reversal |
+
+## Action Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `side` | `buy \| sell \| hold` | Trade direction |
+| `quantity` | `int (>= 0)` | Number of shares (ignored if `hold`) |
+
+## Observation Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ticker` | `string` | Stock ticker symbol |
+| `date` | `string` | Day label (e.g. `day_3`) |
+| `price` | `float` | Current price |
+| `price_history` | `list[float]` | Prices observed so far |
+| `fundamentals` | `dict` | Static facts about the company |
+| `cash` | `float` | Current cash balance |
+| `position` | `int` | Current number of shares held |
+| `portfolio_value` | `float` | `cash + position * price` |
+| `task_id` | `string` | Active task |
+| `step_number` | `int` | 1-indexed step |
+| `total_steps` | `int` | Total steps in the episode |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `API_BASE_URL` | inference only | LLM endpoint (default: HuggingFace Router) |
+| `MODEL_NAME` | inference only | Model identifier |
+| `HF_TOKEN` | inference only | HuggingFace API key |
+
+The server itself requires no API keys.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install uv
+uv sync
+
+# Run the server
+./run.sh
+# Server: http://localhost:7860
+# Frontend: http://localhost:7860/web
+# Swagger: http://localhost:7860/docs
+
+# Smoke test
+curl http://localhost:7860/health
+curl -X POST http://localhost:7860/reset -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:7860/step  -H "Content-Type: application/json" \
+  -d '{"side": "buy", "quantity": 10}'
+
+# Run inference
+export HF_TOKEN=hf_xxx
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
+python inference.py --task all
+```
+
+## Inference Script
+
+`inference.py` lives in the project root, uses the OpenAI client, and emits
+`[START]`, `[STEP]`, `[END]` log lines required by OpenEnv.
+
+```
+[START] task=<task_name> env=stocker model=<model_name>
+[STEP]  step=<n> action=<side(qty)> reward=<x.xx> done=<true|false> error=<msg|null>
+[END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...>
+```
+
+## Reward
+
+For each step:
+
+```
+reward = (new_portfolio - prev_portfolio) / prev_portfolio - invalid_action_penalty
+```
+
+A small bonus (`+0.05`) is added on the final step if the agent ends the episode
+with at least 1.05× starting capital. Reward is clipped to `[-1.0, 1.0]`.
+
+## Docker
+
+```bash
+docker build -t stocker .
+docker run -p 7860:7860 stocker
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/web` | GET | Interactive frontend |
+| `/health` | GET | Health check |
+| `/meta` | GET | Environment metadata |
+| `/reset` | POST | Reset environment |
+| `/step` | POST | Submit trade action |
+| `/state` | GET / POST | Export / restore state |
+| `/docs` | GET | Swagger UI |
+
+## Validation
+
+```bash
+./validate-submission.sh https://your-space.hf.space .
+python scripts/validate_tasks.py
+```
+
+## TODO (scaffolding hand-off)
+
+- Replace inline `prices` with realistic OHLCV data (CSV or HF datasets).
+- Add more tasks under `tasks/*.json`.
+- Tune the reward shaping (transaction costs, risk penalty, Sharpe ratio).
+- Wire HF Spaces deployment in `.env` + `push-hf.sh`.
+- Add training script (Unsloth / TRL) per OpenEnv submission requirements.

app/api/env.py

@@ -0,0 +1,36 @@
+"""Core RL environment endpoints: reset and step."""
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from app.core.environment import StockerEnv
+from app.models import ResetResult, StepResult, TradeAction
+
+router = APIRouter(tags=["environment"])
+
+current_env = StockerEnv(task_id="task_easy")
+
+
+class ResetRequest(BaseModel):
+    task_id: str = "task_easy"
+
+
+@router.post("/reset", response_model=ResetResult)
+async def reset(body: Optional[ResetRequest] = None) -> ResetResult:
+    global current_env
+    task_id = body.task_id if body else "task_easy"
+    try:
+        current_env = StockerEnv(task_id=task_id)
+        return current_env.reset()
+    except KeyError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/step", response_model=StepResult)
+async def step(action: TradeAction) -> StepResult:
+    try:
+        return current_env.step(action)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))

app/api/frontend.py

@@ -0,0 +1,125 @@
+"""Serves the embedded HTML frontend."""
+
+from fastapi import APIRouter
+from fastapi.responses import HTMLResponse
+
+router = APIRouter(tags=["frontend"])
+
+FRONTEND_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Stocker - OpenEnv</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; background: #0f172a; color: #e2e8f0; padding: 20px; }
+  .container { max-width: 900px; margin: 0 auto; }
+  h1 { color: #38bdf8; }
+  .card { background: #1e293b; border-radius: 12px; padding: 20px; margin-bottom: 16px; border: 1px solid #334155; }
+  label { display: block; color: #94a3b8; font-size: 0.85em; margin: 8px 0 4px; }
+  select, input { width: 100%; padding: 8px; border-radius: 6px; border: 1px solid #475569; background: #0f172a; color: #e2e8f0; }
+  .btn { padding: 10px 20px; border-radius: 8px; border: none; cursor: pointer; font-weight: 600; margin-top: 10px; margin-right: 8px; }
+  .btn-primary { background: #2563eb; color: white; }
+  .btn-success { background: #059669; color: white; }
+  .row { display: flex; gap: 12px; }
+  .row > * { flex: 1; }
+  .log { background: #0f172a; border-radius: 8px; padding: 12px; font-family: monospace; font-size: 0.85em; max-height: 280px; overflow-y: auto; white-space: pre-wrap; color: #94a3b8; }
+  .stat { color: #94a3b8; }
+  .stat strong { color: #e2e8f0; }
+</style>
+</head>
+<body>
+<div class="container">
+  <h1>Stocker</h1>
+  <p>OpenEnv RL environment for stock-trading decisions.</p>
+
+  <div class="card">
+    <div class="row">
+      <div>
+        <label>Task</label>
+        <select id="taskSelect"><option>Loading...</option></select>
+      </div>
+      <div style="display:flex;align-items:flex-end;">
+        <button class="btn btn-primary" onclick="resetEnv()">Start</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="card" id="obsCard" style="display:none;">
+    <p class="stat">Ticker: <strong id="ticker"></strong> | Date: <strong id="date"></strong> | Price: <strong id="price"></strong></p>
+    <p class="stat">Cash: <strong id="cash"></strong> | Position: <strong id="position"></strong> | Portfolio: <strong id="pv"></strong></p>
+    <p class="stat">Step <strong id="step"></strong> of <strong id="total"></strong></p>
+  </div>
+
+  <div class="card" id="actCard" style="display:none;">
+    <div class="row">
+      <div>
+        <label>Side</label>
+        <select id="side"><option>buy</option><option>sell</option><option selected>hold</option></select>
+      </div>
+      <div>
+        <label>Quantity</label>
+        <input type="number" id="qty" min="0" value="0">
+      </div>
+    </div>
+    <button class="btn btn-success" onclick="submit()">Submit</button>
+  </div>
+
+  <div class="card">
+    <div class="log" id="log">Ready.</div>
+  </div>
+</div>
+
+<script>
+function log(m) { const el = document.getElementById('log'); el.textContent += '\\n' + m; el.scrollTop = el.scrollHeight; }
+
+async function loadTasks() {
+  const r = await fetch('/meta');
+  const d = await r.json();
+  const sel = document.getElementById('taskSelect');
+  sel.innerHTML = '';
+  for (const t of d.tasks) {
+    const o = document.createElement('option');
+    o.value = t; o.textContent = t;
+    sel.appendChild(o);
+  }
+}
+loadTasks();
+
+function showObs(o) {
+  document.getElementById('obsCard').style.display = 'block';
+  document.getElementById('actCard').style.display = 'block';
+  document.getElementById('ticker').textContent = o.ticker;
+  document.getElementById('date').textContent = o.date;
+  document.getElementById('price').textContent = o.price.toFixed(2);
+  document.getElementById('cash').textContent = o.cash.toFixed(2);
+  document.getElementById('position').textContent = o.position;
+  document.getElementById('pv').textContent = o.portfolio_value.toFixed(2);
+  document.getElementById('step').textContent = o.step_number;
+  document.getElementById('total').textContent = o.total_steps;
+}
+
+async function resetEnv() {
+  const tid = document.getElementById('taskSelect').value;
+  const r = await fetch('/reset', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify({task_id: tid}) });
+  const d = await r.json();
+  log('--- reset: ' + tid + ' ---');
+  showObs(d.observation);
+}
+
+async function submit() {
+  const a = { side: document.getElementById('side').value, quantity: parseInt(document.getElementById('qty').value || '0') };
+  log('action: ' + JSON.stringify(a));
+  const r = await fetch('/step', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify(a) });
+  const d = await r.json();
+  log('reward: ' + d.reward.toFixed(4) + (d.done ? ' [DONE]' : ''));
+  showObs(d.observation);
+}
+</script>
+</body>
+</html>"""
+
+
+@router.get("/", response_class=HTMLResponse)
+@router.get("/web", response_class=HTMLResponse)
+async def index() -> HTMLResponse:
+    return HTMLResponse(content=FRONTEND_HTML)

app/api/health.py

@@ -0,0 +1,23 @@
+"""Health check endpoint."""
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter(tags=["health"])
+
+
+class HealthResponse(BaseModel):
+    status: str
+    timestamp: str
+    service: str
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health() -> HealthResponse:
+    return HealthResponse(
+        status="healthy",
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        service="stocker",
+    )

app/api/meta.py

@@ -0,0 +1,31 @@
+"""Environment metadata endpoint."""
+
+from fastapi import APIRouter
+
+from app.core.tasks import list_task_ids
+
+router = APIRouter(tags=["meta"])
+
+
+@router.get("/meta")
+async def meta() -> dict:
+    return {
+        "name": "stocker",
+        "version": "0.1.0",
+        "description": "RL environment for stock trading decisions.",
+        "tasks": list_task_ids(),
+        "action_space": {
+            "side": "literal[buy, sell, hold]",
+            "quantity": "int (>=0)",
+        },
+        "observation_space": {
+            "ticker": "string",
+            "date": "string (ISO date)",
+            "price": "float",
+            "price_history": "list[float]",
+            "fundamentals": "dict",
+            "cash": "float",
+            "position": "int",
+            "portfolio_value": "float",
+        },
+    }

app/api/router.py

@@ -0,0 +1,11 @@
+"""Aggregate API router."""
+
+from fastapi import APIRouter
+
+from app.api import health, meta, env, state
+
+api_router = APIRouter()
+api_router.include_router(health.router)
+api_router.include_router(meta.router)
+api_router.include_router(env.router)
+api_router.include_router(state.router)

app/api/state.py

@@ -0,0 +1,30 @@
+"""State export and restore endpoints."""
+
+from fastapi import APIRouter, HTTPException
+
+from app.models import EnvironmentState
+
+router = APIRouter(tags=["state"])
+
+
+@router.get("/state", response_model=EnvironmentState)
+async def get_state() -> EnvironmentState:
+    import app.api.env as env_module
+    try:
+        return env_module.current_env.state()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/state")
+async def restore_state(snapshot: EnvironmentState) -> dict:
+    import app.api.env as env_module
+    from app.core.environment import StockerEnv
+
+    try:
+        new_env = StockerEnv(task_id=snapshot.task_id)
+        new_env.load_snapshot(snapshot)
+        env_module.current_env = new_env
+        return {"status": "restored", "task_id": snapshot.task_id}
+    except KeyError as e:
+        raise HTTPException(status_code=400, detail=str(e))

app/config.py

@@ -0,0 +1,14 @@
+"""Application settings using pydantic-settings."""
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    project_name: str = "stocker"
+    allow_origins: list[str] = ["*"]
+    port: int = 7860
+
+    model_config = {"env_prefix": "STOCKER_", "case_sensitive": False}
+
+
+settings = Settings()

app/core/environment.py

@@ -0,0 +1,208 @@
+"""StockerEnv — the Stocker OpenEnv environment."""
+
+import uuid
+
+from app.core.graders import compute_step_reward, compute_trajectory_bonus
+from app.core.tasks import get_task_definition
+from app.models import (
+    EnvironmentState,
+    MarketObservation,
+    ResetResult,
+    StepResult,
+    TradeAction,
+)
+
+
+class StockerEnv:
+    """Stock-trading RL environment."""
+
+    def __init__(self, task_id: str = "task_easy"):
+        self.task_id = task_id
+        self._task: dict = {}
+        self._prices: list[float] = []
+        self._current_index: int = 0
+        self._done: bool = True
+        self._cash: float = 0.0
+        self._position: int = 0
+        self._action_history: list[dict] = []
+        self._reward_history: list[float] = []
+        self._episode_id: str = ""
+
+    # ------------------------------------------------------------------ reset
+    def reset(self, task_id: str | None = None) -> ResetResult:
+        if task_id is not None:
+            self.task_id = task_id
+
+        self._task = get_task_definition(self.task_id)
+        self._prices = list(self._task["prices"])
+        self._current_index = 0
+        self._done = False
+        self._cash = float(self._task.get("starting_cash", 10000.0))
+        self._position = 0
+        self._action_history = []
+        self._reward_history = []
+        self._episode_id = str(uuid.uuid4())[:8]
+
+        return ResetResult(
+            observation=self._build_observation(0),
+            info={
+                "task_id": self.task_id,
+                "episode_id": self._episode_id,
+                "total_steps": len(self._prices),
+                "description": self._task.get("description", ""),
+                "starting_cash": self._cash,
+            },
+        )
+
+    # ------------------------------------------------------------------- step
+    def step(self, action: TradeAction | dict) -> StepResult:
+        if isinstance(action, dict):
+            try:
+                action = TradeAction.model_validate(action)
+            except Exception as e:
+                return StepResult(
+                    observation=self._build_observation(self._current_index),
+                    reward=0.0,
+                    done=self._done,
+                    info={"error": f"Invalid action: {e}"},
+                )
+
+        if self._done:
+            return StepResult(
+                observation=self._terminal_observation(),
+                reward=0.0,
+                done=True,
+                info={"message": "Episode already finished. Call reset()."},
+            )
+
+        price = self._prices[self._current_index]
+        prev_portfolio = self._cash + self._position * price
+        invalid = self._apply_action(action, price)
+        new_portfolio = self._cash + self._position * price
+
+        result = compute_step_reward(
+            action=action,
+            prev_portfolio=prev_portfolio,
+            new_portfolio=new_portfolio,
+            starting_cash=float(self._task.get("starting_cash", 10000.0)),
+            invalid=invalid,
+        )
+        reward = result.score
+
+        self._action_history.append(action.model_dump())
+        self._reward_history.append(reward)
+
+        self._current_index += 1
+        if self._current_index >= len(self._prices):
+            self._done = True
+            final_price = self._prices[-1]
+            final_portfolio = self._cash + self._position * final_price
+            reward += compute_trajectory_bonus(
+                final_portfolio, float(self._task.get("starting_cash", 10000.0))
+            )
+
+        reward = max(-1.0, min(1.0, reward))
+
+        next_obs = (
+            self._terminal_observation() if self._done
+            else self._build_observation(self._current_index)
+        )
+
+        return StepResult(
+            observation=next_obs,
+            reward=round(reward, 5),
+            done=self._done,
+            info={
+                "trade_feedback": result.feedback,
+                "reward_breakdown": result.breakdown,
+                "portfolio_value": round(new_portfolio, 4),
+                "cash": round(self._cash, 4),
+                "position": self._position,
+            },
+        )
+
+    # ------------------------------------------------------------------ state
+    def state(self) -> EnvironmentState:
+        price = (
+            self._prices[self._current_index]
+            if self._current_index < len(self._prices)
+            else (self._prices[-1] if self._prices else 0.0)
+        )
+        return EnvironmentState(
+            task_id=self.task_id,
+            current_step=self._current_index,
+            total_steps=len(self._prices),
+            done=self._done,
+            cash=round(self._cash, 4),
+            position=self._position,
+            portfolio_value=round(self._cash + self._position * price, 4),
+            action_history=self._action_history,
+            reward_history=self._reward_history,
+        )
+
+    def load_snapshot(self, snapshot: EnvironmentState) -> None:
+        self._task = get_task_definition(snapshot.task_id)
+        self._prices = list(self._task["prices"])
+        self._current_index = snapshot.current_step
+        self._done = snapshot.done
+        self._cash = snapshot.cash
+        self._position = snapshot.position
+        self._action_history = snapshot.action_history
+        self._reward_history = snapshot.reward_history
+
+    # ---------------------------------------------------------------- helpers
+    def _apply_action(self, action: TradeAction, price: float) -> bool:
+        """Apply trade. Returns True if the action was invalid (insufficient
+        cash/position) — the action is then treated as a hold."""
+        if action.side == "hold" or action.quantity <= 0:
+            return False
+
+        if action.side == "buy":
+            cost = action.quantity * price
+            if cost > self._cash:
+                return True
+            self._cash -= cost
+            self._position += action.quantity
+            return False
+
+        if action.side == "sell":
+            if action.quantity > self._position:
+                return True
+            self._cash += action.quantity * price
+            self._position -= action.quantity
+            return False
+
+        return True
+
+    def _build_observation(self, index: int) -> MarketObservation:
+        price = self._prices[index]
+        return MarketObservation(
+            ticker=self._task["ticker"],
+            date=f"day_{index + 1}",
+            price=price,
+            price_history=self._prices[: index + 1],
+            fundamentals=self._task.get("fundamentals", {}),
+            cash=round(self._cash, 4),
+            position=self._position,
+            portfolio_value=round(self._cash + self._position * price, 4),
+            task_id=self.task_id,
+            step_number=index + 1,
+            total_steps=len(self._prices),
+        )
+
+    def _terminal_observation(self) -> MarketObservation:
+        final_price = self._prices[-1] if self._prices else 0.0
+        portfolio = self._cash + self._position * final_price
+        return MarketObservation(
+            ticker=self._task.get("ticker", ""),
+            date="[EPISODE COMPLETE]",
+            price=final_price,
+            price_history=self._prices,
+            fundamentals=self._task.get("fundamentals", {}),
+            cash=round(self._cash, 4),
+            position=self._position,
+            portfolio_value=round(portfolio, 4),
+            task_id=self.task_id,
+            step_number=len(self._prices),
+            total_steps=len(self._prices),
+        )

app/core/graders.py

@@ -0,0 +1,41 @@
+"""Reward and shaping functions for the Stocker environment."""
+
+from app.models import RewardResult, TradeAction
+
+
+def compute_step_reward(
+    action: TradeAction,
+    prev_portfolio: float,
+    new_portfolio: float,
+    starting_cash: float,
+    invalid: bool,
+) -> RewardResult:
+    """Reward = pct change in portfolio value, with a small penalty for invalid actions."""
+    breakdown: dict[str, float] = {}
+
+    pnl_pct = (new_portfolio - prev_portfolio) / max(prev_portfolio, 1e-9)
+    breakdown["pnl_pct"] = round(pnl_pct, 5)
+
+    penalty = 0.0
+    if invalid:
+        penalty = 0.01
+        breakdown["invalid_action_penalty"] = -penalty
+
+    score = pnl_pct - penalty
+
+    side = action.side
+    feedback = f"{side}({action.quantity}) -> portfolio {new_portfolio:.2f}"
+    if invalid:
+        feedback += " [invalid: insufficient cash/position]"
+
+    return RewardResult(score=round(score, 5), breakdown=breakdown, feedback=feedback)
+
+
+def compute_trajectory_bonus(
+    final_portfolio: float, starting_cash: float, threshold: float = 1.05
+) -> float:
+    """Bonus if the agent finishes with >threshold of starting capital."""
+    ratio = final_portfolio / max(starting_cash, 1e-9)
+    if ratio >= threshold:
+        return 0.05
+    return 0.0

app/core/tasks.py

@@ -0,0 +1,88 @@
+"""Trading scenario dataset for the Stocker environment.
+
+Each task is a sequence of daily market observations for a single ticker, with
+a known ground-truth optimal trajectory used only for reward shaping (not
+shown to the agent).
+
+Tasks are loaded from:
+1. Inline definitions below
+2. JSON files in tasks/ directory
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Inline task definitions
+# ---------------------------------------------------------------------------
+
+TASK_EASY = {
+    "task_id": "task_easy",
+    "description": "Steady uptrend: a clearly bullish 10-day sequence.",
+    "ticker": "ACME",
+    "starting_cash": 10000.0,
+    "fundamentals": {"sector": "tech", "pe_ratio": 22.0, "market_cap": 5e9},
+    "prices": [100.0, 101.5, 103.0, 104.2, 106.0, 107.5, 109.0, 110.5, 112.0, 114.0],
+}
+
+TASK_MEDIUM = {
+    "task_id": "task_medium",
+    "description": "Volatile sideways market: noisy mean-reverting prices.",
+    "ticker": "VOLT",
+    "starting_cash": 10000.0,
+    "fundamentals": {"sector": "energy", "pe_ratio": 14.5, "market_cap": 1.2e9},
+    "prices": [50.0, 52.0, 49.5, 51.0, 48.5, 50.5, 52.5, 49.0, 51.5, 50.0],
+}
+
+TASK_HARD = {
+    "task_id": "task_hard",
+    "description": "Bull-then-bear reversal: agent must time the exit.",
+    "ticker": "FLIP",
+    "starting_cash": 10000.0,
+    "fundamentals": {"sector": "biotech", "pe_ratio": 35.0, "market_cap": 800e6},
+    "prices": [40.0, 42.5, 45.0, 47.0, 49.5, 50.0, 47.0, 43.5, 39.0, 35.0],
+}
+
+_INLINE_TASKS = {
+    "task_easy": TASK_EASY,
+    "task_medium": TASK_MEDIUM,
+    "task_hard": TASK_HARD,
+}
+
+_TASKS_DIR = Path(__file__).resolve().parent.parent.parent / "tasks"
+
+
+def _load_tasks_from_dir(tasks_dir: Path) -> dict[str, dict]:
+    loaded: dict[str, dict] = {}
+    if not tasks_dir.is_dir():
+        return loaded
+    for json_file in sorted(tasks_dir.glob("*.json")):
+        try:
+            with open(json_file) as f:
+                task = json.load(f)
+            task_id = task.get("task_id", json_file.stem)
+            loaded[task_id] = task
+            logger.debug("Loaded task '%s' from %s", task_id, json_file.name)
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.warning("Failed to load task from %s: %s", json_file, e)
+    return loaded
+
+
+TASKS_BY_ID: dict[str, dict] = {}
+TASKS_BY_ID.update(_INLINE_TASKS)
+TASKS_BY_ID.update(_load_tasks_from_dir(_TASKS_DIR))
+
+
+def get_task_definition(task_id: str) -> dict:
+    if task_id not in TASKS_BY_ID:
+        raise KeyError(
+            f"Unknown task_id: {task_id}. Available: {list(TASKS_BY_ID.keys())}"
+        )
+    return TASKS_BY_ID[task_id]
+
+
+def list_task_ids() -> list[str]:
+    return list(TASKS_BY_ID.keys())

app/main.py

@@ -0,0 +1,71 @@
+"""FastAPI application factory and setup."""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+import traceback
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.api.router import api_router
+from app.api.frontend import router as frontend_router
+from app.config import settings
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(levelname)s:\t%(name)s - %(message)s",
+    handlers=[logging.StreamHandler(sys.stderr)],
+)
+logger = logging.getLogger(__name__)
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="Stocker - OpenEnv",
+        version="0.1.0",
+        description="RL environment where an AI agent makes stock-trading decisions.",
+        openapi_url="/openapi.json",
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    @app.exception_handler(Exception)
+    async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        logger.error("Unhandled exception: %s", exc)
+        logger.error(traceback.format_exc())
+        return JSONResponse(status_code=500, content={"detail": str(exc)})
+
+    @app.middleware("http")
+    async def log_requests(request: Request, call_next):
+        start = time.time()
+        response = await call_next(request)
+        logger.info(
+            "%s %s - %s - %.3fs",
+            request.method, request.url.path, response.status_code, time.time() - start,
+        )
+        return response
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.allow_origins,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        allow_credentials=True,
+    )
+
+    app.include_router(api_router)
+    app.include_router(frontend_router)
+    return app
+
+
+app = create_app()
+
+
+def run() -> None:
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=settings.port)

app/models.py

@@ -0,0 +1,58 @@
+"""Pydantic data models for the Stocker OpenEnv environment."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class MarketObservation(BaseModel):
+    """What the agent sees: market state plus its current portfolio."""
+    ticker: str
+    date: str
+    price: float
+    price_history: list[float]
+    fundamentals: dict
+    cash: float
+    position: int
+    portfolio_value: float
+    task_id: str
+    step_number: int
+    total_steps: int
+
+
+class TradeAction(BaseModel):
+    """What the agent does: buy / sell / hold a quantity of shares."""
+    side: Literal["buy", "sell", "hold"]
+    quantity: int = Field(ge=0, default=0)
+
+
+class RewardResult(BaseModel):
+    """Internal reward computation result."""
+    score: float
+    breakdown: dict[str, float]
+    feedback: str
+
+
+class EnvironmentState(BaseModel):
+    """Snapshot of environment state."""
+    task_id: str
+    current_step: int
+    total_steps: int
+    done: bool
+    cash: float
+    position: int
+    portfolio_value: float
+    action_history: list[dict]
+    reward_history: list[float]
+
+
+class StepResult(BaseModel):
+    observation: MarketObservation
+    reward: float
+    done: bool
+    info: dict
+
+
+class ResetResult(BaseModel):
+    observation: MarketObservation
+    info: dict

client.py

@@ -0,0 +1,36 @@
+"""HTTP client for the Stocker OpenEnv environment."""
+
+import requests
+
+
+class StockerClient:
+    def __init__(self, base_url: str = "http://localhost:7860"):
+        self.base_url = base_url.rstrip("/")
+
+    def reset(self, task_id: str = "task_easy") -> dict:
+        r = requests.post(f"{self.base_url}/reset", json={"task_id": task_id})
+        r.raise_for_status()
+        return r.json()
+
+    def step(self, side: str, quantity: int = 0) -> dict:
+        r = requests.post(
+            f"{self.base_url}/step",
+            json={"side": side, "quantity": quantity},
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def get_state(self) -> dict:
+        r = requests.get(f"{self.base_url}/state")
+        r.raise_for_status()
+        return r.json()
+
+    def restore_state(self, state: dict) -> dict:
+        r = requests.post(f"{self.base_url}/state", json=state)
+        r.raise_for_status()
+        return r.json()
+
+    def health(self) -> dict:
+        r = requests.get(f"{self.base_url}/health")
+        r.raise_for_status()
+        return r.json()

inference.py

@@ -0,0 +1,254 @@
+"""
+Inference Script — Stocker OpenEnv
+==================================
+MANDATORY
+- Environment variables:
+    API_BASE_URL   The API endpoint for the LLM (default: HuggingFace Router)
+    MODEL_NAME     The model identifier (default: Qwen/Qwen2.5-7B-Instruct)
+    HF_TOKEN       Your HuggingFace / API key
+    API_KEY        Alternative to HF_TOKEN
+
+- Place inference.py in the project root. Uses OpenAI Client for LLM calls.
+
+STDOUT FORMAT
+    [START] task=<task_name> env=<benchmark> model=<model_name>
+    [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+    [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import textwrap
+from typing import Optional
+
+from openai import OpenAI
+
+from app.core.environment import StockerEnv
+from app.core.tasks import list_task_ids
+
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY") or os.getenv("OPENAI_API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+MODEL_NAME = os.getenv("MODEL_NAME") or "Qwen/Qwen2.5-7B-Instruct"
+BENCHMARK = "stocker"
+
+MAX_STEPS = 50
+TEMPERATURE = 0.2
+MAX_TOKENS = 200
+SUCCESS_SCORE_THRESHOLD = 0.0  # any non-negative net P&L counts as success
+
+SYSTEM_PROMPT = textwrap.dedent("""\
+    You are a disciplined stock trader. At each step you observe the current
+    price, recent price history, your cash, and your share position. You must
+    decide: buy, sell, or hold — and if buying or selling, how many shares.
+
+    Rules:
+    - You cannot buy more than your cash allows.
+    - You cannot sell more shares than you own.
+    - Aim to maximize the final portfolio value.
+
+    Respond with ONLY a valid JSON object (no markdown, no extra text):
+    {"side": "buy|sell|hold", "quantity": <int>}""")
+
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.4f} done={str(done).lower()} "
+        f"error={error if error else 'null'}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, score: float, rewards: list[float]) -> None:
+    rewards_str = ",".join(f"{r:.4f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} score={score:.4f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+def build_user_prompt(observation: dict) -> str:
+    return f"""Trade decision for {observation['ticker']} on {observation['date']}.
+
+Current price: {observation['price']:.2f}
+Recent prices: {observation['price_history']}
+Fundamentals: {observation['fundamentals']}
+Cash: {observation['cash']:.2f}
+Position: {observation['position']} shares
+Portfolio value: {observation['portfolio_value']:.2f}
+Step {observation['step_number']} of {observation['total_steps']}"""
+
+
+def parse_response(text: str) -> dict:
+    try:
+        cleaned = re.sub(r"```(?:json)?\s*", "", text).strip().rstrip("`")
+        start = cleaned.find("{")
+        if start >= 0:
+            depth = 0
+            for i in range(start, len(cleaned)):
+                if cleaned[i] == "{":
+                    depth += 1
+                elif cleaned[i] == "}":
+                    depth -= 1
+                if depth == 0:
+                    parsed = json.loads(cleaned[start : i + 1])
+                    side = str(parsed.get("side", "hold")).lower()
+                    if side not in ("buy", "sell", "hold"):
+                        side = "hold"
+                    qty = int(parsed.get("quantity", 0))
+                    return {"side": side, "quantity": max(0, qty)}
+    except (json.JSONDecodeError, ValueError, TypeError):
+        pass
+
+    side_match = re.search(r"side[\"']?\s*[:=]\s*[\"']?(buy|sell|hold)", text, re.I)
+    qty_match = re.search(r"quantity[\"']?\s*[:=]\s*[\"']?(-?\d+)", text, re.I)
+    if side_match:
+        return {
+            "side": side_match.group(1).lower(),
+            "quantity": max(0, int(qty_match.group(1))) if qty_match else 0,
+        }
+
+    return {"side": "hold", "quantity": 0}
+
+
+def run_episode(
+    client: OpenAI, model: str, task_id: str, use_json_mode: bool = True
+) -> dict:
+    env = StockerEnv(task_id=task_id)
+    reset_result = env.reset()
+    obs = reset_result.observation.model_dump()
+
+    rewards: list[float] = []
+    step_details: list[dict] = []
+    steps_taken = 0
+
+    log_start(task=task_id, env=BENCHMARK, model=model)
+
+    try:
+        for step in range(1, MAX_STEPS + 1):
+            messages = [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": build_user_prompt(obs)},
+            ]
+            error: Optional[str] = None
+
+            try:
+                kwargs = {
+                    "model": model,
+                    "messages": messages,
+                    "temperature": TEMPERATURE,
+                    "max_tokens": MAX_TOKENS,
+                }
+                if use_json_mode:
+                    kwargs["response_format"] = {"type": "json_object"}
+                response = client.chat.completions.create(**kwargs)
+                llm_text = (response.choices[0].message.content or "").strip()
+            except Exception as e:
+                err = str(e)
+                if use_json_mode and ("response_format" in err or "json" in err.lower()):
+                    use_json_mode = False
+                    try:
+                        response = client.chat.completions.create(
+                            model=model, messages=messages,
+                            temperature=TEMPERATURE, max_tokens=MAX_TOKENS,
+                        )
+                        llm_text = (response.choices[0].message.content or "").strip()
+                    except Exception as e2:
+                        error = str(e2)
+                        llm_text = '{"side": "hold", "quantity": 0}'
+                else:
+                    error = err
+                    llm_text = '{"side": "hold", "quantity": 0}'
+
+            action_dict = parse_response(llm_text)
+            step_result = env.step(action_dict)
+
+            reward = step_result.reward
+            done = step_result.done
+            rewards.append(reward)
+            steps_taken = step
+
+            action_str = f"{action_dict['side']}({action_dict['quantity']})"
+            log_step(step, action_str, reward, done, error)
+
+            step_details.append({
+                "step": step,
+                "side": action_dict["side"],
+                "quantity": action_dict["quantity"],
+                "reward": reward,
+                "info": step_result.info,
+                "done": done,
+            })
+
+            if done:
+                break
+            obs = step_result.observation.model_dump()
+
+        score = sum(rewards)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+    finally:
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+    return {
+        "task_id": task_id,
+        "score": round(score, 4),
+        "total_reward": round(sum(rewards), 4),
+        "steps": steps_taken,
+        "success": success,
+        "step_details": step_details,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run LLM inference on Stocker")
+    parser.add_argument("--task", default="all", help="Task name or 'all'")
+    parser.add_argument("--model", default=None, help=f"Model (default: {MODEL_NAME})")
+    parser.add_argument("--output", default=None, help="Path to write JSON results")
+    parser.add_argument(
+        "--no-json-mode", action="store_true",
+        help="Disable JSON response mode for models that don't support it",
+    )
+    args = parser.parse_args()
+
+    if not API_KEY:
+        print("ERROR: No API key. Set HF_TOKEN, API_KEY, or OPENAI_API_KEY.")
+        raise SystemExit(1)
+
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    model = args.model or MODEL_NAME
+
+    tasks = list_task_ids() if args.task == "all" else [args.task]
+
+    results = []
+    for task_id in tasks:
+        results.append(run_episode(client, model, task_id, use_json_mode=not args.no_json_mode))
+
+    print(f"\n{'='*56}", file=sys.stderr)
+    print(f"{'Task':<18} {'Score':>10} {'Reward':>10} {'Steps':>6} {'Pass':>6}", file=sys.stderr)
+    for r in results:
+        print(
+            f"{r['task_id']:<18} {r['score']:>10.4f} {r['total_reward']:>10.4f} "
+            f"{r['steps']:>6} {'yes' if r['success'] else 'no':>6}",
+            file=sys.stderr,
+        )
+
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump({
+                "model": model,
+                "api_base_url": API_BASE_URL,
+                "benchmark": BENCHMARK,
+                "tasks": results,
+                "total_score": round(sum(r["score"] for r in results) / max(len(results), 1), 4),
+            }, f, indent=2)
+        print(f"\nResults written to {args.output}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

openenv.yaml

@@ -0,0 +1,36 @@
+name: stocker
+version: 0.1.0
+description: >
+  An RL environment where an AI agent makes stock-trading decisions
+  (buy / sell / hold) over a sequence of market observations and is
+  rewarded for portfolio profit and risk-adjusted return.
+
+tasks:
+  - task_easy
+  - task_medium
+  - task_hard
+
+observation_space:
+  ticker: str
+  date: str
+  price: float
+  price_history: "list[float]"
+  fundamentals: dict
+  cash: float
+  position: int
+  portfolio_value: float
+  task_id: str
+  step_number: int
+  total_steps: int
+
+action_space:
+  side: "literal[buy, sell, hold]"
+  quantity: int
+
+entrypoint: app.core.environment:StockerEnv
+
+tags:
+  - openenv
+  - finance
+  - trading
+  - rl

push-hf.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Push the project to a HuggingFace Space.
+#
+# Expects the following in .env (see .env.example):
+#   HF_USERNAME    your HF username/org
+#   HF_TOKEN       a write-scope token
+#   HF_SPACE       the space name (e.g. Stocker)
+set -euo pipefail
+
+if [ -f .env ]; then
+  # shellcheck disable=SC1091
+  source .env
+fi
+
+: "${HF_USERNAME:?Set HF_USERNAME in .env}"
+: "${HF_TOKEN:?Set HF_TOKEN in .env}"
+: "${HF_SPACE:?Set HF_SPACE in .env}"
+
+git push "https://${HF_USERNAME}:${HF_TOKEN}@huggingface.co/spaces/${HF_USERNAME}/${HF_SPACE}" main

pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "openenv-stocker"
+version = "0.1.0"
+description = "Stocker — a stock trading RL environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.6.0",
+    "openai>=1.0.0",
+    "openenv-core>=0.2.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.uv]
+package = false

run.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload --reload-dir app

scripts/validate_tasks.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Validate every Stocker task definition."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from app.core.tasks import TASKS_BY_ID  # noqa: E402
+
+
+def validate() -> int:
+    errors: list[str] = []
+
+    for task_id, task in sorted(TASKS_BY_ID.items()):
+        for field in ("ticker", "starting_cash", "prices"):
+            if field not in task:
+                errors.append(f"{task_id}: missing '{field}'")
+
+        prices = task.get("prices", [])
+        if len(prices) < 3:
+            errors.append(f"{task_id}: needs >=3 prices, got {len(prices)}")
+        if any(p <= 0 for p in prices):
+            errors.append(f"{task_id}: non-positive price found")
+
+        cash = task.get("starting_cash", 0)
+        if cash <= 0:
+            errors.append(f"{task_id}: starting_cash must be > 0")
+
+        print(f"{task_id:<18} ticker={task.get('ticker'):<6} "
+              f"steps={len(prices)} cash={cash}")
+
+    if errors:
+        print("\nERRORS:")
+        for e in errors:
+            print(" -", e)
+        return 1
+    print(f"\nAll {len(TASKS_BY_ID)} tasks valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(validate())

server/app.py

@@ -0,0 +1,19 @@
+"""Server entry point and ASGI application export.
+
+The actual application lives in app/main.py. This module preserves
+`server.app:app` as an ASGI target and adds a callable `main()`
+entry point required by OpenEnv validation.
+"""
+
+from app.main import app, run  # noqa: F401
+
+__all__ = ["app", "main"]
+
+
+def main() -> None:
+    """CLI/server entry point required by OpenEnv validation."""
+    run()
+
+
+if __name__ == "__main__":
+    main()

tests/test_api.py

@@ -0,0 +1,36 @@
+"""HTTP-level smoke tests for the FastAPI app."""
+
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_health():
+    r = client.get("/health")
+    assert r.status_code == 200
+    assert r.json()["status"] == "healthy"
+
+
+def test_meta_lists_tasks():
+    r = client.get("/meta")
+    assert r.status_code == 200
+    assert len(r.json()["tasks"]) >= 3
+
+
+def test_reset_and_step():
+    r = client.post("/reset", json={})
+    assert r.status_code == 200
+    assert "observation" in r.json()
+
+    r = client.post("/step", json={"side": "hold", "quantity": 0})
+    assert r.status_code == 200
+    assert -1.0 <= r.json()["reward"] <= 1.0
+
+
+def test_state_roundtrip():
+    client.post("/reset", json={"task_id": "task_easy"})
+    s = client.get("/state").json()
+    r = client.post("/state", json=s)
+    assert r.status_code == 200

tests/test_environment.py

@@ -0,0 +1,36 @@
+"""Smoke tests for StockerEnv."""
+
+from app.core.environment import StockerEnv
+from app.core.tasks import list_task_ids
+
+
+def test_env_reset_and_step_each_task():
+    for task_id in list_task_ids():
+        env = StockerEnv(task_id=task_id)
+        reset = env.reset()
+        assert reset.observation.task_id == task_id
+        assert reset.observation.step_number == 1
+
+        result = env.step({"side": "hold", "quantity": 0})
+        assert -1.0 <= result.reward <= 1.0
+        assert result.observation.step_number >= 2 or result.done
+
+
+def test_env_buy_then_hold_runs_to_completion():
+    env = StockerEnv(task_id="task_easy")
+    env.reset()
+    env.step({"side": "buy", "quantity": 10})
+    done = False
+    steps = 0
+    while not done and steps < 50:
+        r = env.step({"side": "hold", "quantity": 0})
+        done = r.done
+        steps += 1
+    assert done
+
+
+def test_invalid_buy_does_not_change_position():
+    env = StockerEnv(task_id="task_easy")
+    env.reset()
+    r = env.step({"side": "buy", "quantity": 10**9})
+    assert r.info["position"] == 0

validate-submission.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Validate that the HF Space is live, the Docker image builds, and openenv validate passes.
+#
+# Usage: ./validate-submission.sh <ping_url> [repo_dir]
+
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BOLD='\033[1m'; NC='\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; BOLD=''; NC=''
+fi
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  exit 1
+fi
+
+REPO_DIR="$(cd "$REPO_DIR" && pwd)"
+PING_URL="${PING_URL%/}"
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS+1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() { printf "\n${RED}${BOLD}Stopped at %s.${NC}\n" "$1"; exit 1; }
+
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  Stocker Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+
+log "${BOLD}Step 1/3:${NC} Pinging HF Space ($PING_URL/reset) ..."
+HTTP_CODE=$(curl -s -o /tmp/stocker_resp -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 || echo "000")
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live"
+else
+  fail "HF Space returned $HTTP_CODE"
+  hint "Check the Space is running at $PING_URL"
+  stop_at "Step 1"
+fi
+
+log "${BOLD}Step 2/3:${NC} docker build ..."
+if ! command -v docker &>/dev/null; then
+  fail "docker not found"; stop_at "Step 2"
+fi
+if ! docker build "$REPO_DIR" >/tmp/stocker_build.log 2>&1; then
+  fail "docker build failed"
+  tail -20 /tmp/stocker_build.log
+  stop_at "Step 2"
+fi
+pass "docker build succeeded"
+
+log "${BOLD}Step 3/3:${NC} openenv validate ..."
+if ! command -v openenv &>/dev/null; then
+  fail "openenv not found"; hint "pip install openenv-core"; stop_at "Step 3"
+fi
+if ! ( cd "$REPO_DIR" && openenv validate ); then
+  fail "openenv validate failed"; stop_at "Step 3"
+fi
+pass "openenv validate"
+
+printf "\n${GREEN}${BOLD}All 3/3 checks passed.${NC}\n"