feat: Mock Data SDK & Contributor Infrastructure

.github/PULL_REQUEST_TEMPLATE/new_tool.md

@@ -30,14 +30,14 @@ about: Submit a new tool for the Venth project
 
 ## Testing
 
-- [ ] Tested against Synth API
-- [ ] Manually tested
-- [ ] Tests added/updated
+- [ ] Tests pass in mock mode (`python -m pytest tools/<tool-name>/tests/ -v`)
+- [ ] Manually tested with mock data
+- [ ] Tests added in `tools/<tool-name>/tests/`
 
 ## Checklist
 
 - [ ] **1-page technical document at `tools/<tool-name>/README.md`**
 - [ ] Tool lives in its own subfolder under `tools/`
-- [ ] Tool is listed in the root README
+- [ ] Tool uses `synth_client.SynthClient` for all Synth API access
 - [ ] Code follows project style guidelines
 - [ ] Self-review completed

.github/workflows/pr_mock_tests.yml

@@ -0,0 +1,71 @@
+name: PR Mock Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  mock-tests:
+    name: Test tools with mock data
+    runs-on: ubuntu-latest
+    # No SYNTH_API_KEY is set — forces mock mode automatically
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install base dependencies
+        run: pip install requests pytest
+
+      - name: Discover and test tools
+        run: |
+          echo "🔍 Discovering tools..."
+          FAILED=0
+          PASSED=0
+
+          for tool_dir in tools/*/; do
+            # Skip the template
+            tool_name=$(basename "$tool_dir")
+            if [ "$tool_name" = "_template" ]; then
+              continue
+            fi
+
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "🔧 Testing tool: $tool_name"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+            # Install tool-specific requirements if they exist
+            if [ -f "$tool_dir/requirements.txt" ]; then
+              echo "📦 Installing requirements..."
+              pip install -r "$tool_dir/requirements.txt" -q
+            fi
+
+            # Run pytest if tests directory exists
+            if [ -d "$tool_dir/tests" ]; then
+              echo "🧪 Running tests..."
+              if python -m pytest "$tool_dir/tests" -v --tb=short; then
+                echo "✅ $tool_name: PASSED"
+                PASSED=$((PASSED + 1))
+              else
+                echo "❌ $tool_name: FAILED"
+                FAILED=$((FAILED + 1))
+              fi
+            else
+              echo "⚠️  No tests/ directory found for $tool_name"
+            fi
+          done
+
+          echo ""
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "📊 Results: $PASSED passed, $FAILED failed"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+          if [ "$FAILED" -gt 0 ]; then
+            exit 1
+          fi

.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment files (NEVER commit API keys)
+.env
+.env.local
+
+# Pytest
+.pytest_cache/
+
+# PR review sandboxes
+.sandbox-pr-*/
+
+# Distribution
+*.egg
+*.whl

README.md

@@ -8,20 +8,124 @@ This project is developed using [Gittensor](https://subnetalpha.ai/subnet/gitten
 
 Venth is a collection of developer tools that extend and integrate with the Synth subnet's forecasting capabilities. The project is being built as a submission to the [Synth Hackathon](https://dashboard.synthdata.co/hackathon/).
 
-## Project Structure
+## Getting Started
+
+**You do NOT need a Synth API key to build a tool.** The repo includes mock data from every Synth endpoint and a client wrapper that automatically loads it when no API key is present.
+
+### 1. Fork & Clone
 
+```bash
+git clone https://github.com/YOUR_USERNAME/venth.git
+cd venth
 ```
-tools/
-  tool-name/       # Each tool lives in its own subfolder
-    README.md      # 1-page technical document (required)
-    ...
+
+### 2. Install Dependencies
+
+```bash
+pip install -r requirements.txt
 ```
 
-## Tools
+### 3. Start Building
+
+```python
+from synth_client import SynthClient
+
+client = SynthClient()  # auto-detects mock mode (no API key needed)
+
+# Get price forecast percentiles for BTC
+forecast = client.get_prediction_percentiles("BTC", horizon="24h")
+print(forecast["current_price"])
+print(forecast["forecast_future"]["percentiles"])
+
+# Get volatility for ETH
+vol = client.get_volatility("ETH")
+print(vol["forecast_future"]["average_volatility"])
+
+# Get option pricing for SPY
+options = client.get_option_pricing("SPY")
+print(options["call_options"])
+```
+
+When no `SYNTH_API_KEY` environment variable is set, the client automatically loads data from the `mock_data/` directory. When an API key is present, it hits the real Synth API.
+
+### 4. Copy the Template
+
+```bash
+cp -r tools/_template tools/my-tool
+```
+
+Edit `tools/my-tool/main.py` and `tools/my-tool/README.md` with your tool's logic and documentation.
+
+## Supported Assets
+
+| Asset | Symbol |
+|---|---|
+| Bitcoin | `BTC` |
+| Ethereum | `ETH` |
+| Solana | `SOL` |
+| Gold | `XAU` |
+| S&P 500 | `SPY` |
+| NVIDIA | `NVDA` |
+| Tesla | `TSLA` |
+| Apple | `AAPL` |
+| Alphabet | `GOOGL` |
+
+## Available Endpoints
+
+The `SynthClient` wraps all Synth API endpoints:
+
+| Method | Description | Assets | Horizons |
+|---|---|---|---|
+| `get_prediction_percentiles(asset, horizon)` | Probabilistic price forecasts with percentile distributions | All 9 | `24h`, `1h`\* |
+| `get_volatility(asset, horizon)` | Forecasted & realized volatility metrics | All 9 | `24h`, `1h`\* |
+| `get_option_pricing(asset)` | Theoretical call/put option prices | All except XAU | — |
+| `get_liquidation(asset)` | Liquidation probability at various price changes | All 9 | — |
+| `get_lp_bounds(asset)` | Optimal LP ranges with impermanent loss estimates | All 9 | — |
+| `get_lp_probabilities(asset)` | Price level probabilities for LP decisions | All 9 | — |
+| `get_polymarket_daily()` | Daily up/down: Synth vs Polymarket (BTC) | BTC only | — |
+| `get_polymarket_hourly()` | Hourly up/down: Synth vs Polymarket (BTC) | BTC only | — |
+| `get_polymarket_range()` | Price range comparison: Synth vs Polymarket | BTC only | — |
+| `get_leaderboard(asset, days, limit)` | Top-performing miner rankings | All 9 | — |
+
+\* The `1h` horizon is only available for **crypto assets** (BTC, ETH, SOL) and **XAU**. Equities (SPY, NVDA, TSLA, AAPL, GOOGL) only support the `24h` horizon.
+
+## Project Structure
+
+```
+venth/
+├── synth_client/             # Dual-mode SDK wrapper (mock + live)
+│   ├── __init__.py
+│   └── client.py
+├── mock_data/                # Real API responses for offline development
+│   ├── prediction_percentiles/
+│   ├── volatility/
+│   ├── option_pricing/
+│   ├── liquidation/
+│   ├── lp_bounds/
+│   ├── lp_probabilities/
+│   ├── polymarket/
+│   └── leaderboard/
+├── tools/
+│   ├── _template/            # Starter kit — copy this to begin
+│   │   ├── README.md
+│   │   ├── main.py
+│   │   ├── requirements.txt
+│   │   └── tests/
+│   └── your-tool/            # Your tool goes here
+├── tests/                    # Root test suite for synth_client
+├── scripts/                  # Utilities (mock data generator)
+└── .github/workflows/        # CI: automated mock tests on every PR
+```
 
-Each tool is a self-contained subfolder under `tools/`. New tools must include a 1-page technical document as `README.md` within their subfolder.
+## PR Lifecycle
 
-_Coming soon_ — tools will be listed here as they are developed.
+1. **Fork** the repository
+2. **Build** your tool using mock data (no API key needed)
+3. **Test** locally: `python -m pytest tools/your-tool/tests/ -v`
+4. **Push** and open a pull request
+5. **CI runs** — automated mock tests verify your tool doesn't crash
+6. **Maintainer reviews** — pulls your PR locally & tests with the real API
+7. **Merge** 🎉
 
 ## Contributing
 
@@ -35,9 +139,11 @@ To contribute:
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/your-feature`)
-3. Add your tool as a new subfolder under `tools/` (e.g. `tools/my-tool/`)
-4. Include a 1-page technical document as `tools/my-tool/README.md`
-5. Commit your changes and open a pull request using the [New Tool template](../../.github/PULL_REQUEST_TEMPLATE/new_tool.md)
+3. Copy the template: `cp -r tools/_template tools/my-tool`
+4. Build your tool using the `SynthClient`
+5. Include a 1-page technical document as `tools/my-tool/README.md`
+6. Add tests in `tools/my-tool/tests/`
+7. Commit your changes and open a pull request
 
 ## Links