tradeodds 0.1.0__tar.gz

tradeodds-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+dist-ssr/
+
+# Environment variables (NEVER commit)
+.env
+.env.local
+.env.*.local
+backend/.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+backend/venv/
+*.egg-info/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+.claude/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+
+# Lock files (using npm)
+bun.lockb
+
+# Content engine output
+backend/scripts/output/
+
+# GuessTheMove dedup ledger (local state)
+video/props/.guess_ledger.json
+
+# YouTube OAuth credentials (NEVER commit)
+backend/scripts/client_secret.json
+backend/scripts/youtube_token.json
+video/props/.youtube_uploads.json
+
+# TikTok OAuth credentials (NEVER commit)
+backend/scripts/tiktok_token.json
+video/props/.tiktok_uploads.json
+
+# Agent reports (ephemeral, regenerated nightly)
+backend/scripts/agents/reports/*.json
+
+# Astro content hub (generated at build)
+content/.astro/
+content/dist/
+
+# Misc
+*.tsbuildinfo
+
+# Claude dev handoff docs (internal session prompts, not production code)
+Context/HANDOFF_POST_MIGRATION.md
+Context/HANDOFF_TRADEODDS_MIGRATION.md
+Context/PROMPT_PHASE_11A.md
+Context/SESSION_PROMPT_RECOMMENDATIONS.md
+Context/RECOMMENDATIONS.md
+.vercel
+.env*.local
+.mcp.json

tradeodds-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TradeOdds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tradeodds-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: tradeodds
+Version: 0.1.0
+Summary: Official Python SDK for the TradeOdds REST API — quantitative pattern analysis on ~3,200 symbols.
+Project-URL: Homepage, https://tradeodds.io
+Project-URL: Documentation, https://tradeodds.io/api-docs
+Project-URL: Repository, https://github.com/cpoly/tradeodds
+Project-URL: Issues, https://github.com/cpoly/tradeodds/issues
+Author-email: TradeOdds <support@tradeodds.io>
+License: MIT License
+        
+        Copyright (c) 2026 TradeOdds
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,factor-match,finance,quantitative,sdk,tradeodds,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tradeodds — Python SDK
+
+Official Python client for the [TradeOdds](https://tradeodds.io) REST API. Run quantitative pattern analysis on ~3,200 symbols (US equities, ETFs, major crypto) with one function call.
+
+```bash
+pip install tradeodds
+```
+
+## Quickstart
+
+```python
+from tradeodds import TradeOddsClient
+
+client = TradeOddsClient()  # reads TRADEODDS_API_KEY from env
+
+result = client.analyze(
+    symbol="SPY",
+    forward_period="5d",
+    conditions={"daily_change": True, "vix_level": True, "regime": True},
+    lookback_years="20y",
+)
+
+stats = result["forward_stats"]
+print(f"{result['match_count']} matches | win rate {stats['win_rate']:.0%} | median {stats['median_return']:+.2%}")
+```
+
+Get an API key at <https://tradeodds.io/account>. Free tier ships with the platform — pay-as-you-go pricing kicks in at $0.05/analyze and $0.15/factor-match.
+
+## What's in the box
+
+| Method | Endpoint | Auth | Cost |
+|---|---|---|---|
+| `client.symbols()` | `GET /api/v1/symbols` | none | free |
+| `client.analyze(symbol, ...)` | `POST /api/v1/analyze` | API key | $0.05 |
+| `client.factor_match(...)` | `POST /api/v1/factor-match` | API key | $0.15 |
+
+## Installation
+
+```bash
+pip install tradeodds
+```
+
+Requires Python 3.9+. The only runtime dependency is [`requests`](https://requests.readthedocs.io).
+
+## Configuration
+
+| Source | Variable | Notes |
+|---|---|---|
+| Env | `TRADEODDS_API_KEY` | `sk-to-...` token. Default auth source. |
+| Env | `TRADEODDS_BASE_URL` | Override for staging / self-host. Defaults to production. |
+| Constructor | `TradeOddsClient(api_key=..., base_url=..., timeout=200.0)` | Explicit overrides win over env. |
+
+```python
+from tradeodds import TradeOddsClient
+
+client = TradeOddsClient(api_key="sk-to-abc123...", timeout=60.0)
+```
+
+## API reference
+
+### `client.symbols(active_only=True)`
+
+List every symbol available for analysis.
+
+```python
+universe = client.symbols()
+print(f"{universe['count']} symbols")
+spy = next(s for s in universe["symbols"] if s["symbol"] == "SPY")
+```
+
+### `client.analyze(symbol, **kwargs)`
+
+Returns probability-weighted historical analogs for the symbol's current DNA fingerprint. Auth required. $0.05/call.
+
+| Arg | Type | Default | Notes |
+|---|---|---|---|
+| `symbol` | str | — | Ticker (case-insensitive). |
+| `reference_period` | `1d` `5d` `1m` … | `1d` | How recent the observed window is. |
+| `forward_period` | `1d` `5d` `20d` … | `5d` | Trading days forward to compute outcomes. |
+| `conditions` | `DNAConditions` | `{daily_change: True}` | Toggle factors: `vix_level`, `regime`, `rsi_zone`, `streak`, `macro_risk`, etc. |
+| `lookback_years` | `1y` `5y` `20y` `max` | `max` | History window for matches. |
+| `price_tolerance` | int 0-3 | 0 | Bucket-step tolerance for price. |
+| `vix_tolerance` | int 0-3 | 0 | Bucket-step tolerance for VIX. |
+
+### `client.factor_match(**kwargs)`
+
+Scans all symbols for whose current state matches the supplied conditions. Returns a ranked list with historical forward-return stats. Auth required. $0.15/call.
+
+```python
+result = client.factor_match(
+    conditions={"vix_level": True, "regime": True, "rsi_zone": True},
+    filters={"is_etf": False, "price_min": 10},
+    perf_filter={"metric": "win_5d", "operator": "gt", "threshold": 0.6},
+    min_instances=20,
+)
+```
+
+## Error handling
+
+Errors are typed exceptions that preserve the structured envelope (`code`, `hint`, `request_id`):
+
+```python
+from tradeodds import ApiError, AuthError, NotFoundError, RateLimitError
+
+try:
+    result = client.analyze(symbol="SPY")
+except RateLimitError as exc:
+    print(exc.code, exc.message, exc.hint, exc.request_id)
+except AuthError:
+    print("Set TRADEODDS_API_KEY")
+except NotFoundError:
+    print("Unknown symbol")
+except ApiError as exc:
+    print(f"[{exc.status_code}] {exc.code}: {exc.message}")
+```
+
+| Exception | When |
+|---|---|
+| `AuthError` | 401 — missing or invalid key |
+| `NotFoundError` | 404 — unknown symbol |
+| `ValidationError` | 400 / 422 — bad request body |
+| `RateLimitError` | 429 — daily or per-minute cap |
+| `ServerError` | 5xx and client-side timeouts (504 from server-side timeout) |
+| `ApiError` | base class for all of the above |
+
+Every exception exposes:
+
+- `exc.code` — machine-readable code (e.g. `rate_limit_exceeded`)
+- `exc.message` — human-readable summary
+- `exc.hint` — suggested remediation, when the API provides one
+- `exc.request_id` — server request id for support contact
+- `exc.status_code` — HTTP status
+
+## License
+
+MIT. See `LICENSE`.

tradeodds-0.1.0/README.md

@@ -0,0 +1,136 @@
+# tradeodds — Python SDK
+
+Official Python client for the [TradeOdds](https://tradeodds.io) REST API. Run quantitative pattern analysis on ~3,200 symbols (US equities, ETFs, major crypto) with one function call.
+
+```bash
+pip install tradeodds
+```
+
+## Quickstart
+
+```python
+from tradeodds import TradeOddsClient
+
+client = TradeOddsClient()  # reads TRADEODDS_API_KEY from env
+
+result = client.analyze(
+    symbol="SPY",
+    forward_period="5d",
+    conditions={"daily_change": True, "vix_level": True, "regime": True},
+    lookback_years="20y",
+)
+
+stats = result["forward_stats"]
+print(f"{result['match_count']} matches | win rate {stats['win_rate']:.0%} | median {stats['median_return']:+.2%}")
+```
+
+Get an API key at <https://tradeodds.io/account>. Free tier ships with the platform — pay-as-you-go pricing kicks in at $0.05/analyze and $0.15/factor-match.
+
+## What's in the box
+
+| Method | Endpoint | Auth | Cost |
+|---|---|---|---|
+| `client.symbols()` | `GET /api/v1/symbols` | none | free |
+| `client.analyze(symbol, ...)` | `POST /api/v1/analyze` | API key | $0.05 |
+| `client.factor_match(...)` | `POST /api/v1/factor-match` | API key | $0.15 |
+
+## Installation
+
+```bash
+pip install tradeodds
+```
+
+Requires Python 3.9+. The only runtime dependency is [`requests`](https://requests.readthedocs.io).
+
+## Configuration
+
+| Source | Variable | Notes |
+|---|---|---|
+| Env | `TRADEODDS_API_KEY` | `sk-to-...` token. Default auth source. |
+| Env | `TRADEODDS_BASE_URL` | Override for staging / self-host. Defaults to production. |
+| Constructor | `TradeOddsClient(api_key=..., base_url=..., timeout=200.0)` | Explicit overrides win over env. |
+
+```python
+from tradeodds import TradeOddsClient
+
+client = TradeOddsClient(api_key="sk-to-abc123...", timeout=60.0)
+```
+
+## API reference
+
+### `client.symbols(active_only=True)`
+
+List every symbol available for analysis.
+
+```python
+universe = client.symbols()
+print(f"{universe['count']} symbols")
+spy = next(s for s in universe["symbols"] if s["symbol"] == "SPY")
+```
+
+### `client.analyze(symbol, **kwargs)`
+
+Returns probability-weighted historical analogs for the symbol's current DNA fingerprint. Auth required. $0.05/call.
+
+| Arg | Type | Default | Notes |
+|---|---|---|---|
+| `symbol` | str | — | Ticker (case-insensitive). |
+| `reference_period` | `1d` `5d` `1m` … | `1d` | How recent the observed window is. |
+| `forward_period` | `1d` `5d` `20d` … | `5d` | Trading days forward to compute outcomes. |
+| `conditions` | `DNAConditions` | `{daily_change: True}` | Toggle factors: `vix_level`, `regime`, `rsi_zone`, `streak`, `macro_risk`, etc. |
+| `lookback_years` | `1y` `5y` `20y` `max` | `max` | History window for matches. |
+| `price_tolerance` | int 0-3 | 0 | Bucket-step tolerance for price. |
+| `vix_tolerance` | int 0-3 | 0 | Bucket-step tolerance for VIX. |
+
+### `client.factor_match(**kwargs)`
+
+Scans all symbols for whose current state matches the supplied conditions. Returns a ranked list with historical forward-return stats. Auth required. $0.15/call.
+
+```python
+result = client.factor_match(
+    conditions={"vix_level": True, "regime": True, "rsi_zone": True},
+    filters={"is_etf": False, "price_min": 10},
+    perf_filter={"metric": "win_5d", "operator": "gt", "threshold": 0.6},
+    min_instances=20,
+)
+```
+
+## Error handling
+
+Errors are typed exceptions that preserve the structured envelope (`code`, `hint`, `request_id`):
+
+```python
+from tradeodds import ApiError, AuthError, NotFoundError, RateLimitError
+
+try:
+    result = client.analyze(symbol="SPY")
+except RateLimitError as exc:
+    print(exc.code, exc.message, exc.hint, exc.request_id)
+except AuthError:
+    print("Set TRADEODDS_API_KEY")
+except NotFoundError:
+    print("Unknown symbol")
+except ApiError as exc:
+    print(f"[{exc.status_code}] {exc.code}: {exc.message}")
+```
+
+| Exception | When |
+|---|---|
+| `AuthError` | 401 — missing or invalid key |
+| `NotFoundError` | 404 — unknown symbol |
+| `ValidationError` | 400 / 422 — bad request body |
+| `RateLimitError` | 429 — daily or per-minute cap |
+| `ServerError` | 5xx and client-side timeouts (504 from server-side timeout) |
+| `ApiError` | base class for all of the above |
+
+Every exception exposes:
+
+- `exc.code` — machine-readable code (e.g. `rate_limit_exceeded`)
+- `exc.message` — human-readable summary
+- `exc.hint` — suggested remediation, when the API provides one
+- `exc.request_id` — server request id for support contact
+- `exc.status_code` — HTTP status
+
+## License
+
+MIT. See `LICENSE`.

tradeodds-0.1.0/examples/quickstart.py

@@ -0,0 +1,43 @@
+"""TradeOdds SDK quickstart.
+
+Set TRADEODDS_API_KEY in your environment, then run:
+
+    python examples/quickstart.py
+
+Outputs the historical win rate and median 5-day forward return for SPY when
+VIX is in its current regime — an end-to-end live API call in <30 lines.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from tradeodds import ApiError, TradeOddsClient
+
+
+def main() -> int:
+    if not os.environ.get("TRADEODDS_API_KEY"):
+        print("Set TRADEODDS_API_KEY first. Get a key at https://tradeodds.io/account.")
+        return 1
+
+    with TradeOddsClient() as client:
+        try:
+            result = client.analyze(
+                symbol="SPY",
+                forward_period="5d",
+                conditions={"daily_change": True, "vix_level": True, "regime": True},
+                lookback_years="20y",
+            )
+        except ApiError as exc:
+            print(f"API error [{exc.code}]: {exc.message}")
+            if exc.hint:
+                print(f"hint: {exc.hint}")
+            return 1
+
+    print(json.dumps(result, indent=2, default=str)[:1500])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tradeodds-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tradeodds"
+version = "0.1.0"
+description = "Official Python SDK for the TradeOdds REST API — quantitative pattern analysis on ~3,200 symbols."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "TradeOdds", email = "support@tradeodds.io" }]
+keywords = ["tradeodds", "trading", "quantitative", "finance", "api", "sdk", "factor-match"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.0",
+    "types-requests",
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://tradeodds.io"
+Documentation = "https://tradeodds.io/api-docs"
+Repository = "https://github.com/cpoly/tradeodds"
+Issues = "https://github.com/cpoly/tradeodds/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tradeodds"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "tradeodds/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+]

tradeodds-0.1.0/tradeodds/__init__.py

@@ -0,0 +1,62 @@
+"""TradeOdds — official Python SDK.
+
+Quickstart:
+
+    >>> from tradeodds import TradeOddsClient
+    >>> client = TradeOddsClient()  # reads TRADEODDS_API_KEY
+    >>> result = client.analyze(symbol="SPY", conditions={"vix_level": True})
+    >>> print(f"{result['match_count']} historical matches")
+"""
+from .client import DEFAULT_BASE_URL, TradeOddsClient, __version__
+from .exceptions import (
+    ApiError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    AnalyzeResult,
+    DNAConditions,
+    FactorMatchResult,
+    ForwardPeriod,
+    LookbackYears,
+    PerfFilter,
+    PerfMetric,
+    PerfOperator,
+    ReferencePeriod,
+    ScreenerFilters,
+    Symbol,
+    SymbolListResponse,
+)
+
+# Backwards-compatibility alias — many SDKs expose `Client`.
+Client = TradeOddsClient
+
+__all__ = [
+    "__version__",
+    "Client",
+    "TradeOddsClient",
+    "DEFAULT_BASE_URL",
+    # Exceptions
+    "ApiError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Types
+    "AnalyzeResult",
+    "DNAConditions",
+    "FactorMatchResult",
+    "ForwardPeriod",
+    "LookbackYears",
+    "PerfFilter",
+    "PerfMetric",
+    "PerfOperator",
+    "ReferencePeriod",
+    "ScreenerFilters",
+    "Symbol",
+    "SymbolListResponse",
+]

tradeodds-0.1.0/tradeodds/client.py

@@ -0,0 +1,268 @@
+"""Synchronous HTTP client for the TradeOdds REST API.
+
+Thin wrapper around ``requests``: one method per endpoint, typed inputs,
+typed exceptions on 4xx/5xx with the structured envelope's ``code`` / ``hint``
+/ ``request_id`` preserved as exception attributes.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .exceptions import (
+    ApiError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    AnalyzeResult,
+    DNAConditions,
+    FactorMatchResult,
+    ForwardPeriod,
+    LookbackYears,
+    PerfFilter,
+    ReferencePeriod,
+    ScreenerFilters,
+    SymbolListResponse,
+)
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://tradeodds-production.up.railway.app"
+
+
+def _exception_for_status(status: int) -> type:
+    if status == 401:
+        return AuthError
+    if status == 404:
+        return NotFoundError
+    if status == 429:
+        return RateLimitError
+    if status in (400, 422):
+        return ValidationError
+    if status >= 500:
+        return ServerError
+    return ApiError
+
+
+class TradeOddsClient:
+    """Synchronous client for the TradeOdds public REST API.
+
+    Reads ``TRADEODDS_API_KEY`` from the environment by default. Override with
+    ``api_key=`` / ``base_url=`` / ``timeout=`` constructor args. Pass a custom
+    ``session=requests.Session()`` to share connection pooling or attach
+    retries. ``symbols()`` works without an API key;
+    ``analyze()`` and ``factor_match()`` require one.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 200.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("TRADEODDS_API_KEY")
+        self.base_url = (
+            base_url
+            or os.environ.get("TRADEODDS_BASE_URL")
+            or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    # ── Public methods ──────────────────────────────────────────────
+
+    def symbols(self, *, active_only: bool = True) -> SymbolListResponse:
+        """``GET /api/v1/symbols`` — list every available instrument. No auth required."""
+        return self._request(
+            "GET",
+            "/api/v1/symbols",
+            params={"active_only": str(active_only).lower()},
+            auth_required=False,
+        )
+
+    def analyze(
+        self,
+        symbol: str,
+        *,
+        reference_period: ReferencePeriod = "1d",
+        forward_period: ForwardPeriod = "5d",
+        conditions: Optional[DNAConditions] = None,
+        lookback_years: LookbackYears = "max",
+        price_tolerance: int = 0,
+        vix_tolerance: int = 0,
+    ) -> AnalyzeResult:
+        """``POST /api/v1/analyze`` — historical pattern analysis on one symbol.
+
+        Returns match count, win rate, median forward return, and historical
+        instances. Billed at $0.05/call. Daily cap: 1,000/key. See README for
+        the full conditions vocabulary.
+        """
+        body: Dict[str, Any] = {
+            "symbol": symbol,
+            "reference_period": reference_period,
+            "forward_period": forward_period,
+            "lookback_years": lookback_years,
+            "price_tolerance": price_tolerance,
+            "vix_tolerance": vix_tolerance,
+        }
+        if conditions is not None:
+            body["conditions"] = dict(conditions)
+        return self._request("POST", "/api/v1/analyze", json=body, auth_required=True)
+
+    def factor_match(
+        self,
+        *,
+        forward_periods: Optional[List[ForwardPeriod]] = None,
+        conditions: Optional[DNAConditions] = None,
+        filters: Optional[ScreenerFilters] = None,
+        perf_filter: Optional[PerfFilter] = None,
+        history_range: LookbackYears = "max",
+        min_instances: int = 10,
+        price_tolerance: int = 0,
+        vix_tolerance: int = 0,
+    ) -> FactorMatchResult:
+        """``POST /api/v1/factor-match`` — scan all symbols for current DNA matches.
+
+        Returns a ranked list with historical forward-return stats per symbol.
+        Billed at $0.15/call. Daily cap: 200/key. Server caps at 180s; narrow
+        ``filters`` if you time out.
+        """
+        body: Dict[str, Any] = {
+            "forward_periods": forward_periods or ["1d", "5d", "20d"],
+            "history_range": history_range,
+            "min_instances": min_instances,
+            "price_tolerance": price_tolerance,
+            "vix_tolerance": vix_tolerance,
+        }
+        if conditions is not None:
+            body["conditions"] = dict(conditions)
+        if filters is not None:
+            body["filters"] = dict(filters)
+        if perf_filter is not None:
+            body["perf_filter"] = dict(perf_filter)
+        return self._request(
+            "POST", "/api/v1/factor-match", json=body, auth_required=True
+        )
+
+    # ── Internals ───────────────────────────────────────────────────
+
+    def _headers(self, auth_required: bool) -> Dict[str, str]:
+        headers = {
+            "User-Agent": f"tradeodds-python/{__version__}",
+            "X-Client": "python-sdk",
+            "Accept": "application/json",
+        }
+        if auth_required or self.api_key:
+            if not self.api_key:
+                raise AuthError(
+                    "API key required.",
+                    code="missing_api_key",
+                    hint=(
+                        "Pass api_key=... to TradeOddsClient or set the "
+                        "TRADEODDS_API_KEY environment variable. "
+                        "Get a key at https://tradeodds.io/account."
+                    ),
+                    status_code=401,
+                )
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        auth_required: bool = False,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._session.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                headers=self._headers(auth_required),
+                timeout=self.timeout,
+            )
+        except requests.Timeout as exc:
+            raise ServerError(
+                f"Request to {path} timed out after {self.timeout}s.",
+                code="client_timeout",
+                hint="Increase TradeOddsClient(timeout=...) or narrow your filters.",
+                status_code=None,
+            ) from exc
+        except requests.RequestException as exc:
+            raise ApiError(
+                f"Network error talking to TradeOdds: {exc}",
+                code="network_error",
+                hint="Check your connection and TRADEODDS_BASE_URL.",
+            ) from exc
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError as exc:  # malformed JSON — should never happen
+            raise ServerError(
+                f"Invalid JSON response from {path}: {exc}",
+                code="invalid_response",
+                status_code=resp.status_code,
+            ) from exc
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        """Translate an error response into a typed SDK exception."""
+        request_id = resp.headers.get("X-Request-Id")
+        try:
+            payload = resp.json()
+        except ValueError:
+            payload = {}
+
+        envelope = payload.get("error") if isinstance(payload, dict) else None
+        if isinstance(envelope, dict):
+            code = envelope.get("code") or "api_error"
+            message = envelope.get("message") or resp.reason or "API error."
+            hint = envelope.get("hint")
+            request_id = envelope.get("request_id") or request_id
+        else:
+            # Non-v1 routes still use FastAPI's `{"detail": "..."}` shape.
+            code = "api_error"
+            detail = payload.get("detail") if isinstance(payload, dict) else None
+            message = detail if isinstance(detail, str) else (resp.reason or "API error.")
+            hint = None
+
+        exc_cls = _exception_for_status(resp.status_code)
+        raise exc_cls(
+            message,
+            code=code,
+            hint=hint,
+            request_id=request_id,
+            status_code=resp.status_code,
+        )
+
+    # ── Context-manager support ────────────────────────────────────
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "TradeOddsClient":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+
+__all__ = ["TradeOddsClient", "DEFAULT_BASE_URL", "__version__"]

tradeodds-0.1.0/tradeodds/exceptions.py

@@ -0,0 +1,72 @@
+"""Typed exceptions for the TradeOdds SDK.
+
+All errors raised by `TradeOddsClient` inherit from `ApiError`. The structured
+error envelope returned by the API (`code`, `message`, `hint`, `request_id`)
+is preserved as attributes so callers and LLM agents can branch on the error
+code rather than parsing prose.
+"""
+from typing import Optional
+
+
+class ApiError(Exception):
+    """Base class for all TradeOdds API errors.
+
+    Attributes:
+        code: Machine-readable error code (e.g. ``rate_limit_exceeded``).
+        message: Human-readable error message from the API.
+        hint: Suggested remediation, if the API provided one.
+        request_id: Server-side request id for support contact.
+        status_code: HTTP status code that triggered the error.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "api_error",
+        hint: Optional[str] = None,
+        request_id: Optional[str] = None,
+        status_code: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+        self.request_id = request_id
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(code={self.code!r}, "
+            f"status_code={self.status_code!r}, message={self.message!r})"
+        )
+
+
+class AuthError(ApiError):
+    """Raised on 401 — missing or invalid API key."""
+
+
+class NotFoundError(ApiError):
+    """Raised on 404 — unknown symbol or resource."""
+
+
+class RateLimitError(ApiError):
+    """Raised on 429 — daily or per-minute quota exceeded."""
+
+
+class ValidationError(ApiError):
+    """Raised on 422 / 400 — invalid request body or parameters."""
+
+
+class ServerError(ApiError):
+    """Raised on 5xx — server-side failure or timeout (504)."""
+
+
+__all__ = [
+    "ApiError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+]

tradeodds-0.1.0/tradeodds/types.py

@@ -0,0 +1,112 @@
+"""TypedDict definitions for TradeOdds request/response shapes.
+
+These mirror the Pydantic models in ``backend/app/api/public_api.py``. Using
+TypedDicts (instead of dataclasses) keeps the SDK zero-runtime-cost: requests
+and responses round-trip as plain dicts, but editor / mypy autocomplete still
+works.
+
+For analyze / factor-match responses the server returns a rich nested object
+that varies by tier — those are typed as ``Dict[str, Any]`` here so the SDK
+doesn't drift when the response schema is extended. Inspect ``result.keys()``
+or ``json.dumps(result, indent=2)`` on a real call to discover fields.
+"""
+from typing import Any, Dict, List, Literal, Optional
+
+try:
+    # Python 3.11+: TypedDict supports total=False per-key with NotRequired.
+    from typing import NotRequired, TypedDict
+except ImportError:  # pragma: no cover - Python 3.9 / 3.10
+    from typing_extensions import NotRequired, TypedDict  # type: ignore[assignment]
+
+
+# ── Reference / forward windows ────────────────────────────────────────
+
+ReferencePeriod = Literal["1d", "2d", "3d", "4d", "5d", "1w", "1m"]
+ForwardPeriod = Literal["1d", "2d", "3d", "4d", "5d", "20d", "1w", "1m"]
+LookbackYears = Literal["1y", "3y", "5y", "10y", "20y", "max"]
+PerfMetric = Literal["win_1d", "win_5d", "win_20d", "mean_1d", "mean_5d", "mean_20d"]
+PerfOperator = Literal["gt", "lt"]
+
+
+# ── Symbols ────────────────────────────────────────────────────────────
+
+class Symbol(TypedDict):
+    symbol: str
+    name: Optional[str]
+    sector: Optional[str]
+    is_high_liquidity: bool
+    is_etf: bool
+
+
+class SymbolListResponse(TypedDict):
+    count: int
+    symbols: List[Symbol]
+
+
+# ── Analyze / factor-match request shapes ──────────────────────────────
+
+class DNAConditions(TypedDict, total=False):
+    """DNA filter flags accepted by /analyze and /factor-match.
+
+    Every key is optional — omit or set ``False`` to ignore a factor. ``daily_change``
+    defaults to True server-side. ``magnitude_mode`` only applies when ``magnitude``
+    is True.
+    """
+    daily_change: bool
+    magnitude: bool
+    magnitude_mode: Literal["add", "replace"]
+    vix_level: bool
+    vix_move: bool
+    regime: bool
+    rel_vol: bool
+    rsi_zone: bool
+    rsi_slope: bool
+    structure_precision: bool
+    earnings_prox: bool
+    streak: bool
+    volume_streak: bool
+    earnings_perf: bool
+    overnight_gap: bool
+    analyst_trend: bool
+    month_of_year: bool
+    macro_risk: bool
+
+
+class ScreenerFilters(TypedDict, total=False):
+    is_etf: bool
+    is_crypto: bool
+    is_gold_standard: bool
+    sector: str
+    industry: str
+    symbols: List[str]
+    price_min: float
+    price_max: float
+    volume_min: float
+
+
+class PerfFilter(TypedDict):
+    metric: PerfMetric
+    operator: PerfOperator
+    threshold: float
+
+
+# Response payloads vary by tier and feature flag — keep them open so the SDK
+# doesn't break when the server adds fields.
+AnalyzeResult = Dict[str, Any]
+FactorMatchResult = Dict[str, Any]
+
+
+__all__ = [
+    "ReferencePeriod",
+    "ForwardPeriod",
+    "LookbackYears",
+    "PerfMetric",
+    "PerfOperator",
+    "Symbol",
+    "SymbolListResponse",
+    "DNAConditions",
+    "ScreenerFilters",
+    "PerfFilter",
+    "AnalyzeResult",
+    "FactorMatchResult",
+]