edenalpha 0.1.0__tar.gz

edenalpha-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+node_modules/
+dist/
+.env
+__pycache__/
+*.pyc
+.venv/
+venv/
+.env.prod
+*.log
+fyersDataSocket.log
+# Local candle parquet cache (egress saver)
+.candle_cache/
+backend/.candle_cache/
+backend/db_migration_dumps/
+backend/scripts/migrate_supabase_db.ps1
+backend/.env.prod.backup.22.06.2026
+backend/ip.env
+# Scratch dir some local test/shell runs create — never part of the repo
+backend/.test-tmp/
+.test-tmp/

edenalpha-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry John Thomas
+
+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.

edenalpha-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: edenalpha
+Version: 0.1.0
+Summary: EdenAlpha SDK — write trading strategies in Python and run them against the EdenAlpha engine (hosted backtesting; one contract shared with paper/live deployments).
+Project-URL: Homepage, https://edenalpha.in
+Author: EdenAlpha
+License: MIT
+License-File: LICENSE
+Keywords: backtesting,nse,quant,strategies,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# edenalpha
+
+Write trading strategies in Python. Run them against the EdenAlpha engine —
+the same engine, fills, charges, and risk controls behind every EdenAlpha
+backtest, paper deployment, and live deployment. This SDK's client and CLI
+currently expose hosted backtesting; deployment happens in the web app.
+
+```python
+# my_strategy.py
+from edenalpha import strategy, Feature
+
+@strategy(features=[Feature(name="rsi", period=14)])
+def decide(ctx):
+    if ctx.position.is_open and ctx.features["rsi_14"] > 55:
+        return "EXIT"
+    if not ctx.position.is_open and ctx.features["rsi_14"] < 30:
+        return "BUY"
+    return "HOLD"
+```
+
+```bash
+pip install edenalpha
+edenalpha login                       # paste an API key from Settings -> API keys
+edenalpha backtest my_strategy.py \
+    --symbol RELIANCE --timeframe 15m \
+    --start 2026-06-01 --end 2026-07-01
+```
+
+## How it works
+
+Your function is the **agent**; EdenAlpha is the **world**. On every bar
+close the engine hands you a `Ctx` — the bar, your declared indicators
+(computed server-side, identical to the web rule builder), your position,
+your cash, and the available bar history — and you answer `BUY`, `SELL`
+(opens a short), `EXIT`, or `HOLD`. Hosted backtests expose the full run
+through the current bar; paper deployments expose a rolling window from
+deployment time. Fills, charges, sizing, stop-losses, and
+square-off stay in the engine, so a backtest here is directly comparable to
+every other EdenAlpha run. The same strategy contract powers paper
+deployments in the EdenAlpha web app (currently operator-gated); this
+package's client and CLI expose **hosted backtesting**.
+
+- **Sizing is server-owned.** You return direction; quantity comes from the
+  run's sizing configuration. A strategy that can't over-size in a backtest
+  can't over-size live.
+- **Broker-agnostic.** Nothing in this contract names a broker; execution
+  routing happens server-side behind your deployment settings.
+- **Typed everywhere.** `Ctx`, `Bar`, `Position`, `Decision` are Pydantic
+  models with full annotations (`py.typed` shipped) — your IDE's
+  autocomplete is the API reference.
+- **Unit-testable.** `@strategy` returns a callable: build a fake `Ctx` and
+  assert on the returned `Decision` in plain pytest, no network involved.
+
+## Python API
+
+```python
+import edenalpha
+
+client = edenalpha.Client()          # auth: EDENALPHA_API_KEY or `edenalpha login`
+outcome = client.backtest(
+    "my_strategy.py",
+    symbol="RELIANCE", timeframe="15m",
+    start="2026-06-01", end="2026-07-01",
+)
+print(outcome.summary.net_return_pct)
+for trade in outcome.trades:
+    print(trade["entry_time"], trade["net_pnl"])
+```
+
+Errors are typed (`AuthenticationError`, `ScopeError`,
+`InsufficientCreditsError`, `RateLimitError`, `StrategyError`) and
+retriable statuses (429/5xx) are retried with backoff automatically.
+
+## Hosted execution
+
+`client.backtest(...)` runs your file on EdenAlpha compute next to the data
+(requires the `backtest:hosted` scope). Hosted strategies are single
+self-contained files with an import allowlist (`numpy`, `pandas`, and the
+computation-flavored stdlib). Inside hosted compute, auth is ambient — the
+runner injects the session; your code never handles keys.
+
+## Declared features
+
+Any indicator from the EdenAlpha catalog (the same one behind the web rule
+builder — Strategies → Reference lists all ~57):
+
+```python
+Feature(name="rsi", period=14)                      # ctx.features["rsi_14"]
+Feature(name="vwap")                                # ctx.features["vwap"]
+Feature(name="sma", period=50, alias="slow_ma")     # ctx.features["slow_ma"]
+Feature(name="macd", params={"fast": 12, "slow": 26, "signal": 9},
+        outputs={"line": "macd", "signal": "macd_sig", "histogram": "macd_hist"})
+```
+
+Raw OHLCV (`open`, `high`, `low`, `close`, `volume`) is always present in
+`ctx.features`. Prefer declared features over hand-rolled ones — they're
+computed by the exact code that will feed your strategy in paper/live, so
+train/serve skew can't happen.
+
+## Requirements & license
+
+Python 3.10+. MIT licensed — the SDK is open; the EdenAlpha engine and
+platform are a separate, server-side service.

edenalpha-0.1.0/README.md

@@ -0,0 +1,103 @@
+# edenalpha
+
+Write trading strategies in Python. Run them against the EdenAlpha engine —
+the same engine, fills, charges, and risk controls behind every EdenAlpha
+backtest, paper deployment, and live deployment. This SDK's client and CLI
+currently expose hosted backtesting; deployment happens in the web app.
+
+```python
+# my_strategy.py
+from edenalpha import strategy, Feature
+
+@strategy(features=[Feature(name="rsi", period=14)])
+def decide(ctx):
+    if ctx.position.is_open and ctx.features["rsi_14"] > 55:
+        return "EXIT"
+    if not ctx.position.is_open and ctx.features["rsi_14"] < 30:
+        return "BUY"
+    return "HOLD"
+```
+
+```bash
+pip install edenalpha
+edenalpha login                       # paste an API key from Settings -> API keys
+edenalpha backtest my_strategy.py \
+    --symbol RELIANCE --timeframe 15m \
+    --start 2026-06-01 --end 2026-07-01
+```
+
+## How it works
+
+Your function is the **agent**; EdenAlpha is the **world**. On every bar
+close the engine hands you a `Ctx` — the bar, your declared indicators
+(computed server-side, identical to the web rule builder), your position,
+your cash, and the available bar history — and you answer `BUY`, `SELL`
+(opens a short), `EXIT`, or `HOLD`. Hosted backtests expose the full run
+through the current bar; paper deployments expose a rolling window from
+deployment time. Fills, charges, sizing, stop-losses, and
+square-off stay in the engine, so a backtest here is directly comparable to
+every other EdenAlpha run. The same strategy contract powers paper
+deployments in the EdenAlpha web app (currently operator-gated); this
+package's client and CLI expose **hosted backtesting**.
+
+- **Sizing is server-owned.** You return direction; quantity comes from the
+  run's sizing configuration. A strategy that can't over-size in a backtest
+  can't over-size live.
+- **Broker-agnostic.** Nothing in this contract names a broker; execution
+  routing happens server-side behind your deployment settings.
+- **Typed everywhere.** `Ctx`, `Bar`, `Position`, `Decision` are Pydantic
+  models with full annotations (`py.typed` shipped) — your IDE's
+  autocomplete is the API reference.
+- **Unit-testable.** `@strategy` returns a callable: build a fake `Ctx` and
+  assert on the returned `Decision` in plain pytest, no network involved.
+
+## Python API
+
+```python
+import edenalpha
+
+client = edenalpha.Client()          # auth: EDENALPHA_API_KEY or `edenalpha login`
+outcome = client.backtest(
+    "my_strategy.py",
+    symbol="RELIANCE", timeframe="15m",
+    start="2026-06-01", end="2026-07-01",
+)
+print(outcome.summary.net_return_pct)
+for trade in outcome.trades:
+    print(trade["entry_time"], trade["net_pnl"])
+```
+
+Errors are typed (`AuthenticationError`, `ScopeError`,
+`InsufficientCreditsError`, `RateLimitError`, `StrategyError`) and
+retriable statuses (429/5xx) are retried with backoff automatically.
+
+## Hosted execution
+
+`client.backtest(...)` runs your file on EdenAlpha compute next to the data
+(requires the `backtest:hosted` scope). Hosted strategies are single
+self-contained files with an import allowlist (`numpy`, `pandas`, and the
+computation-flavored stdlib). Inside hosted compute, auth is ambient — the
+runner injects the session; your code never handles keys.
+
+## Declared features
+
+Any indicator from the EdenAlpha catalog (the same one behind the web rule
+builder — Strategies → Reference lists all ~57):
+
+```python
+Feature(name="rsi", period=14)                      # ctx.features["rsi_14"]
+Feature(name="vwap")                                # ctx.features["vwap"]
+Feature(name="sma", period=50, alias="slow_ma")     # ctx.features["slow_ma"]
+Feature(name="macd", params={"fast": 12, "slow": 26, "signal": 9},
+        outputs={"line": "macd", "signal": "macd_sig", "histogram": "macd_hist"})
+```
+
+Raw OHLCV (`open`, `high`, `low`, `close`, `volume`) is always present in
+`ctx.features`. Prefer declared features over hand-rolled ones — they're
+computed by the exact code that will feed your strategy in paper/live, so
+train/serve skew can't happen.
+
+## Requirements & license
+
+Python 3.10+. MIT licensed — the SDK is open; the EdenAlpha engine and
+platform are a separate, server-side service.

edenalpha-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edenalpha"
+version = "0.1.0"
+description = "EdenAlpha SDK — write trading strategies in Python and run them against the EdenAlpha engine (hosted backtesting; one contract shared with paper/live deployments)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "EdenAlpha" }]
+keywords = ["trading", "backtesting", "nse", "strategies", "quant"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.5",
+    "httpx>=0.27",
+    "typer>=0.12",
+    "rich>=13.0",
+]
+
+[project.scripts]
+edenalpha = "edenalpha.cli:app"
+
+[project.urls]
+Homepage = "https://edenalpha.in"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edenalpha"]
+
+[tool.hatch.build.targets.sdist]
+# Explicit allowlist — provably nothing beyond the SDK can leak into the sdist.
+only-include = ["src/edenalpha", "README.md", "LICENSE", "pyproject.toml"]

edenalpha-0.1.0/src/edenalpha/__init__.py

@@ -0,0 +1,69 @@
+"""EdenAlpha SDK — write trading strategies in Python, run them against the
+EdenAlpha engine.
+
+Quickstart::
+
+    from edenalpha import strategy, Feature
+
+    @strategy(features=[Feature(name="rsi", period=14)])
+    def decide(ctx):
+        if ctx.position.is_open and ctx.features["rsi_14"] > 55:
+            return "EXIT"
+        if not ctx.position.is_open and ctx.features["rsi_14"] < 30:
+            return "BUY"
+        return "HOLD"
+
+Then::
+
+    $ edenalpha login
+    $ edenalpha backtest my_strategy.py --symbol RELIANCE --timeframe 15m \\
+          --start 2026-06-01 --end 2026-07-01
+"""
+
+from edenalpha._version import __version__
+from edenalpha.client import Client
+from edenalpha.errors import (
+    APIError,
+    AuthenticationError,
+    EdenAlphaError,
+    InsufficientCreditsError,
+    RateLimitError,
+    ScopeError,
+    StrategyError,
+    TransportError,
+)
+from edenalpha.strategy import StrategyDef, load_strategy_file, strategy
+from edenalpha.types import (
+    Action,
+    BacktestOutcome,
+    BacktestSummary,
+    Bar,
+    Ctx,
+    Decision,
+    Feature,
+    Position,
+)
+
+__all__ = [
+    "__version__",
+    "Client",
+    "strategy",
+    "StrategyDef",
+    "load_strategy_file",
+    "Action",
+    "Bar",
+    "Ctx",
+    "Decision",
+    "Feature",
+    "Position",
+    "BacktestOutcome",
+    "BacktestSummary",
+    "EdenAlphaError",
+    "StrategyError",
+    "TransportError",
+    "APIError",
+    "AuthenticationError",
+    "ScopeError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+]

edenalpha-0.1.0/src/edenalpha/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+CONTRACT_VERSION = "1.0"

edenalpha-0.1.0/src/edenalpha/cli.py

@@ -0,0 +1,125 @@
+"""``edenalpha`` command-line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from edenalpha._version import __version__
+from edenalpha.client import Client, save_api_key
+from edenalpha.errors import EdenAlphaError
+
+app = typer.Typer(
+    name="edenalpha",
+    help="EdenAlpha SDK — Python strategies against the EdenAlpha engine.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+
+def _fail(e: Exception) -> None:
+    err_console.print(f"{type(e).__name__}: {e}")
+    raise typer.Exit(1)
+
+
+@app.command()
+def version() -> None:
+    """Print the SDK version."""
+    console.print(f"edenalpha {__version__}")
+
+
+@app.command()
+def login(
+    api_key: str = typer.Option(
+        None, "--key", help="API key (eak_...). Prompted for if omitted.",
+    ),
+) -> None:
+    """Store your API key (~/.edenalpha/credentials.json) and verify it."""
+    if not api_key:
+        api_key = typer.prompt("API key (from Settings -> API keys)", hide_input=True)
+    try:
+        me = Client(api_key=api_key).whoami()
+    except EdenAlphaError as e:
+        _fail(e)
+        return
+    path = save_api_key(api_key)
+    console.print(f"[green]Logged in as[/green] {me['email']}  (scopes: {', '.join(me['scopes'])})")
+    console.print(f"Key saved to {path}")
+
+
+@app.command()
+def whoami() -> None:
+    """Show the account and scopes behind the configured API key."""
+    try:
+        me = Client().whoami()
+    except EdenAlphaError as e:
+        _fail(e)
+        return
+    console.print(f"{me['email']}  (scopes: {', '.join(me['scopes'])})")
+
+
+@app.command()
+def backtest(
+    strategy_file: Path = typer.Argument(..., help="Path to your @strategy Python file."),
+    symbol: str = typer.Option(..., "--symbol", "-s", help="NSE symbol, e.g. RELIANCE."),
+    timeframe: str = typer.Option("15m", "--timeframe", "-t", help="5m | 15m | 1h | 4h | 1d"),
+    start: str = typer.Option(..., "--start", help="Window start, YYYY-MM-DD."),
+    end: str = typer.Option(..., "--end", help="Window end, YYYY-MM-DD."),
+    product: str = typer.Option("intraday", "--product", help="intraday | delivery"),
+    cash: float = typer.Option(100_000, "--cash", help="Initial capital."),
+    trades: bool = typer.Option(False, "--trades", help="Also print the trade list."),
+) -> None:
+    """Run a hosted backtest on EdenAlpha compute and print the results."""
+    try:
+        with console.status("Running on EdenAlpha compute against real historical bars..."):
+            outcome = Client().backtest(
+                strategy_file,
+                symbol=symbol,
+                timeframe=timeframe,
+                start=start,
+                end=end,
+                product=product,
+                initial_cash=cash,
+            )
+    except EdenAlphaError as e:
+        _fail(e)
+        return
+
+    s = outcome.summary
+    pnl_style = "green" if s.net_pnl >= 0 else "red"
+    table = Table(title=f"{s.symbol} {s.timeframe}  {s.start_date} -> {s.end_date}")
+    table.add_column("Metric")
+    table.add_column("Value", justify="right")
+    table.add_row("Net P&L", f"[{pnl_style}]{s.net_pnl:,.2f}[/{pnl_style}]")
+    table.add_row("Return", f"[{pnl_style}]{s.net_return_pct:.2f}%[/{pnl_style}]")
+    table.add_row("Final equity", f"{s.final_equity:,.2f}")
+    table.add_row("Trades", str(s.total_trades))
+    if s.total_trades:
+        table.add_row("Win rate", f"{s.winning_trades / s.total_trades * 100:.0f}%")
+    console.print(table)
+
+    if trades and outcome.trades:
+        t = Table(title="Trades")
+        for col in ("entry_time", "exit_time", "side", "qty", "entry", "exit", "net P&L", "exit type"):
+            t.add_column(col)
+        for tr in outcome.trades:
+            style = "green" if tr.get("net_pnl", 0) >= 0 else "red"
+            t.add_row(
+                str(tr.get("entry_time", ""))[:16], str(tr.get("exit_time", ""))[:16],
+                tr.get("side", ""), str(tr.get("quantity", "")),
+                f"{tr.get('entry_price', 0):,.2f}", f"{tr.get('exit_price', 0):,.2f}",
+                f"[{style}]{tr.get('net_pnl', 0):,.2f}[/{style}]", tr.get("exit_type", ""),
+            )
+        console.print(t)
+
+    for w in outcome.warnings:
+        console.print(f"[yellow]warning:[/yellow] {w}")
+
+
+if __name__ == "__main__":
+    app()

edenalpha-0.1.0/src/edenalpha/client.py

@@ -0,0 +1,195 @@
+"""HTTP client for the EdenAlpha API.
+
+Auth resolution order (first hit wins):
+
+1. ``api_key=`` passed explicitly
+2. ``EDENALPHA_API_KEY`` environment variable
+3. ``~/.edenalpha/credentials.json`` (written by ``edenalpha login``)
+
+Inside EdenAlpha hosted compute none of this matters — the runner injects an
+ambient session and your code never touches auth.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import httpx
+
+from edenalpha._version import __version__
+from edenalpha.errors import (
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    RateLimitError,
+    ScopeError,
+    TransportError,
+)
+from edenalpha.strategy import load_strategy_file
+from edenalpha.types import BacktestOutcome
+
+DEFAULT_BASE_URL = "https://api.edenalpha.in/api"
+CREDENTIALS_PATH = Path.home() / ".edenalpha" / "credentials.json"
+
+_RETRY_STATUSES = {429, 502, 503, 504}
+_MAX_RETRIES = 3
+
+
+def resolve_api_key(explicit: str | None = None) -> str | None:
+    if explicit:
+        return explicit
+    env = os.environ.get("EDENALPHA_API_KEY")
+    if env:
+        return env
+    try:
+        return json.loads(CREDENTIALS_PATH.read_text())["api_key"]
+    except (OSError, KeyError, ValueError):
+        return None
+
+
+def save_api_key(api_key: str) -> Path:
+    CREDENTIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps({"api_key": api_key}, indent=2))
+    try:  # best-effort chmod; a no-op on Windows
+        CREDENTIALS_PATH.chmod(0o600)
+    except OSError:
+        pass
+    return CREDENTIALS_PATH
+
+
+def _raise_for(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        body = response.json()
+        detail = body.get("detail", body)
+    except ValueError:
+        body, detail = response.text, response.text
+    message = detail.get("message") if isinstance(detail, dict) else str(detail)
+    kwargs = {"status_code": response.status_code, "body": body}
+    if response.status_code == 401:
+        raise AuthenticationError(
+            message or "Invalid API key. Run `edenalpha login` or set EDENALPHA_API_KEY.",
+            **kwargs,
+        )
+    if response.status_code == 403:
+        raise ScopeError(message or "API key lacks the required scope.", **kwargs)
+    if response.status_code == 402:
+        raise InsufficientCreditsError(message or "Not enough credits.", **kwargs)
+    if response.status_code == 429:
+        raise RateLimitError(message or "Rate limited.", **kwargs)
+    raise APIError(message or f"API error {response.status_code}", **kwargs)
+
+
+class Client:
+    """Synchronous EdenAlpha client.
+
+    >>> import edenalpha
+    >>> client = edenalpha.Client()          # auth from env / credentials file
+    >>> outcome = client.backtest("my_strategy.py", symbol="RELIANCE",
+    ...                           timeframe="15m",
+    ...                           start="2026-06-01", end="2026-07-01")
+    >>> outcome.summary.net_return_pct
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 600.0,
+    ):
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = (base_url or os.environ.get("EDENALPHA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "User-Agent": f"edenalpha-python/{__version__}",
+                **({"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}),
+            },
+        )
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key. Create one at Settings -> API keys, then run "
+                "`edenalpha login` or set EDENALPHA_API_KEY."
+            )
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = self._http.request(method, path, **kwargs)
+            except httpx.RequestError as e:
+                # Network-level failure (DNS, refused, timeout) — retriable,
+                # surfaced as a typed EdenAlpha error, never a raw httpx one.
+                if attempt < _MAX_RETRIES:
+                    time.sleep(min(2 ** attempt, 8))
+                    continue
+                raise TransportError(
+                    f"Could not reach {self.base_url}: {type(e).__name__}: {e}"
+                ) from e
+            if response.status_code in _RETRY_STATUSES and attempt < _MAX_RETRIES:
+                retry_after = response.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after else min(2 ** attempt, 8)
+                time.sleep(delay)
+                continue
+            _raise_for(response)
+            return response
+        raise APIError("Retries exhausted")  # pragma: no cover — loop always returns/raises
+
+    # -- API surface ------------------------------------------------------
+
+    def whoami(self) -> dict:
+        """Who this API key belongs to, and its scopes."""
+        return self._request("GET", "/code/whoami").json()
+
+    def backtest(
+        self,
+        strategy_file: str | Path,
+        *,
+        symbol: str,
+        timeframe: str,
+        start: str,
+        end: str,
+        product: str = "intraday",
+        initial_cash: float = 100_000,
+        sizing: dict | None = None,
+        risk: dict | None = None,
+        fill_policy: str = "next_open",
+    ) -> BacktestOutcome:
+        """Run ``strategy_file`` on EdenAlpha hosted compute against real
+        historical bars, through the same engine (fills, charges, risk) that
+        powers every other backtest. Requires the ``backtest:hosted`` scope.
+        """
+        code = Path(strategy_file).read_text(encoding="utf-8")
+        load_strategy_file(strategy_file)  # fail fast locally with a clear error
+        payload = {
+            "code": code,
+            "filename": Path(strategy_file).name,
+            "symbol": symbol,
+            "timeframe": timeframe,
+            "start_date": start,
+            "end_date": end,
+            "product": product,
+            "initial_cash": initial_cash,
+            "fill_policy": fill_policy,
+        }
+        if sizing:
+            payload["sizing"] = sizing
+        if risk:
+            payload["risk"] = risk
+        data = self._request("POST", "/code/backtests", json=payload).json()
+        return BacktestOutcome(**data)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

edenalpha-0.1.0/src/edenalpha/errors.py

@@ -0,0 +1,46 @@
+"""Exception taxonomy. Catch :class:`EdenAlphaError` for everything, or the
+specific subclass you can actually handle — the OpenAI/Anthropic convention."""
+
+from __future__ import annotations
+
+
+class EdenAlphaError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class StrategyError(EdenAlphaError):
+    """Your strategy file/function is invalid (bad return value, no
+    @strategy found, duplicate definitions...). The message says exactly
+    what to fix."""
+
+
+class TransportError(EdenAlphaError):
+    """The agent<->engine session broke (protocol violation, closed pipe)."""
+
+
+class APIError(EdenAlphaError):
+    """An API call failed. ``status_code`` and the server's message are
+    attached."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, body: object = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthenticationError(APIError):
+    """No/invalid API key. Create one under Settings -> API keys at
+    https://edenalpha.in, then run ``edenalpha login`` or set
+    ``EDENALPHA_API_KEY``."""
+
+
+class ScopeError(APIError):
+    """Your API key is valid but lacks the scope this call needs."""
+
+
+class InsufficientCreditsError(APIError):
+    """Your account doesn't have enough credits for this operation."""
+
+
+class RateLimitError(APIError):
+    """Too many requests — the SDK already retried with backoff and gave up."""

edenalpha-0.1.0/src/edenalpha/host.py

@@ -0,0 +1,128 @@
+"""Agent host — the child end of the agent<->engine session.
+
+Run as ``python -m edenalpha.host <strategy_file>`` by the EdenAlpha hosted
+runner (or any parent implementing the same protocol). Speaks
+newline-delimited JSON: protocol IN on stdin, protocol OUT on the *original*
+stdout fd. The user's own ``print()`` output is redirected to stderr so it
+can never corrupt the protocol stream — their logs still reach the run log.
+
+Frames (contract v1, see repo code.md):
+
+  parent -> agent:
+    {"type": "init", "symbol", "timeframe", "contract_version"}
+    {"type": "bar",    "bars": [Bar, ...]}          # incremental history
+    {"type": "decide", "seq": n, "ctx": {...}}      # ctx WITHOUT history
+    {"type": "end"}
+  agent -> parent:
+    {"type": "ready",  "contract_version", "sdk", "strategy", "features": [...]}
+    {"type": "action", "seq": n, "action": "BUY|SELL|EXIT|HOLD", "reason": ""}
+    {"type": "fatal",  "error": "..."}              # then exit 1
+
+Replay-safe: duplicate ``seq`` frames are answered from a small action cache
+without re-invoking user code, so stateful strategies survive parent retries.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections import OrderedDict
+from typing import IO
+
+from edenalpha._version import CONTRACT_VERSION, __version__
+from edenalpha.errors import StrategyError, TransportError
+from edenalpha.strategy import StrategyDef, load_strategy_file
+from edenalpha.types import Bar, Ctx, Position
+
+_ACTION_CACHE_SIZE = 64
+
+
+def _write(out: IO[str], frame: dict) -> None:
+    out.write(json.dumps(frame, separators=(",", ":")) + "\n")
+    out.flush()
+
+
+def serve(strategy_def: StrategyDef, stdin: IO[str], proto_out: IO[str]) -> None:
+    history: list[Bar] = []
+    actions: OrderedDict[int, dict] = OrderedDict()
+
+    _write(proto_out, {
+        "type": "ready",
+        "contract_version": CONTRACT_VERSION,
+        "sdk": f"edenalpha/{__version__}",
+        "strategy": {"name": strategy_def.name},
+        "features": strategy_def.feature_specs(),
+    })
+
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        frame = json.loads(line)
+        ftype = frame.get("type")
+
+        if ftype == "end":
+            return
+        if ftype == "init":
+            continue  # informational in v1
+        if ftype == "bar":
+            history.extend(Bar(**b) for b in frame["bars"])
+            continue
+        if ftype == "decide":
+            seq = int(frame["seq"])
+            if seq in actions:  # replay: answer from cache, never re-run user code
+                _write(proto_out, actions[seq])
+                continue
+            raw = frame["ctx"]
+            ctx = Ctx(
+                timestamp=raw["timestamp"],
+                symbol=raw["symbol"],
+                timeframe=raw["timeframe"],
+                bar=Bar(**raw["bar"]),
+                features=raw.get("features") or {},
+                prev_features=raw.get("prev_features") or {},
+                position=Position(**(raw.get("position") or {})),
+                cash=float(raw.get("cash", 0.0)),
+                history=tuple(history),
+            )
+            decision = strategy_def(ctx)
+            reply = {
+                "type": "action",
+                "seq": seq,
+                "action": decision.action,
+                "reason": decision.reason,
+            }
+            actions[seq] = reply
+            while len(actions) > _ACTION_CACHE_SIZE:
+                actions.popitem(last=False)
+            _write(proto_out, reply)
+            continue
+        raise TransportError(f"Unknown frame type from parent: {ftype!r}")
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: python -m edenalpha.host <strategy_file>", file=sys.stderr)
+        return 2
+
+    # Reserve the real stdout for the protocol; user print() goes to stderr.
+    proto_out = os.fdopen(os.dup(sys.stdout.fileno()), "w", encoding="utf-8")
+    sys.stdout = sys.stderr
+
+    try:
+        strategy_def = load_strategy_file(sys.argv[1])
+    except StrategyError as e:
+        _write(proto_out, {"type": "fatal", "error": str(e)})
+        return 1
+
+    try:
+        serve(strategy_def, sys.stdin, proto_out)
+    except Exception as e:  # noqa: BLE001 — report to parent, then fail
+        _write(proto_out, {"type": "fatal", "error": f"{type(e).__name__}: {e}"})
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

edenalpha-0.1.0/src/edenalpha/strategy.py

@@ -0,0 +1,132 @@
+"""The ``@strategy`` decorator — the whole authoring API.
+
+A strategy file is a normal Python module with one decorated function::
+
+    from edenalpha import strategy, Feature
+
+    @strategy(features=[Feature(name="rsi", period=14)])
+    def decide(ctx):
+        if ctx.position.is_open and ctx.features["rsi_14"] > 55:
+            return "EXIT"
+        if not ctx.position.is_open and ctx.features["rsi_14"] < 30:
+            return "BUY"
+        return "HOLD"
+
+Return an :data:`~edenalpha.types.Action` string, a
+:class:`~edenalpha.types.Decision` (to attach a reason), or ``None`` (=HOLD).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable
+
+from edenalpha.errors import StrategyError
+from edenalpha.types import Action, Ctx, Decision, DecisionLike, Feature
+
+_VALID_ACTIONS: set[str] = {"BUY", "SELL", "EXIT", "HOLD"}
+
+
+@dataclass
+class StrategyDef:
+    """What ``@strategy`` produces: your function plus its declarations.
+    Calling it still calls your function, so it stays unit-testable::
+
+        assert my_strategy(fake_ctx).action == "BUY"
+    """
+
+    fn: Callable[[Ctx], DecisionLike]
+    features: list[Feature] = field(default_factory=list)
+    name: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            self.name = getattr(self.fn, "__name__", "strategy")
+
+    def __call__(self, ctx: Ctx) -> Decision:
+        return normalize_decision(self.fn(ctx))
+
+    def feature_specs(self) -> list[dict]:
+        return [f.spec() for f in self.features]
+
+
+def normalize_decision(raw: DecisionLike) -> Decision:
+    """Accept the friendly return forms; reject everything else loudly."""
+    if raw is None:
+        return Decision(action="HOLD")
+    if isinstance(raw, Decision):
+        return raw
+    if isinstance(raw, str):
+        action = raw.strip().upper()
+        if action not in _VALID_ACTIONS:
+            raise StrategyError(
+                f"decide() returned {raw!r} — must be one of "
+                f"{sorted(_VALID_ACTIONS)}, a Decision, or None (=HOLD)."
+            )
+        return Decision(action=action)  # type: ignore[arg-type]
+    raise StrategyError(
+        f"decide() returned {type(raw).__name__} — must be an action string "
+        f"({sorted(_VALID_ACTIONS)}), a Decision, or None (=HOLD)."
+    )
+
+
+def strategy(
+    features: Iterable[Feature | dict] | None = None,
+    *,
+    name: str = "",
+) -> Callable[[Callable[[Ctx], DecisionLike]], StrategyDef]:
+    """Declare a strategy.
+
+    Args:
+        features: indicators to compute server-side (same catalog as the web
+            rule builder — see Strategies -> Reference). Dicts are accepted
+            for copy-paste parity with the web JSON: ``{"name": "rsi",
+            "period": 14}``.
+        name: display name; defaults to the function name.
+    """
+
+    parsed: list[Feature] = []
+    for f in features or []:
+        parsed.append(f if isinstance(f, Feature) else Feature(**f))
+
+    def wrap(fn: Callable[[Ctx], DecisionLike]) -> StrategyDef:
+        return StrategyDef(fn=fn, features=parsed, name=name)
+
+    return wrap
+
+
+def load_strategy_file(path: str | Path) -> StrategyDef:
+    """Import a strategy file and return its single ``@strategy`` definition.
+
+    Raises StrategyError when the file has zero or multiple definitions —
+    ambiguity is never guessed away.
+    """
+    p = Path(path).resolve()
+    if not p.exists():
+        raise StrategyError(f"Strategy file not found: {p}")
+    spec = importlib.util.spec_from_file_location(f"_edenalpha_user_{p.stem}", p)
+    if spec is None or spec.loader is None:
+        raise StrategyError(f"Cannot import {p} as a Python module.")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:  # surface the author's own error, clearly attributed
+        raise StrategyError(f"Error importing {p.name}: {type(e).__name__}: {e}") from e
+
+    defs = [v for v in vars(module).values() if isinstance(v, StrategyDef)]
+    if not defs:
+        raise StrategyError(
+            f"No @strategy function found in {p.name}. Decorate your decide "
+            f"function with @strategy(...) from the edenalpha package."
+        )
+    if len(defs) > 1:
+        names = ", ".join(d.name for d in defs)
+        raise StrategyError(
+            f"{p.name} defines {len(defs)} strategies ({names}) — keep exactly "
+            f"one per file."
+        )
+    return defs[0]

edenalpha-0.1.0/src/edenalpha/types.py

@@ -0,0 +1,148 @@
+"""Typed models the strategy author sees.
+
+Everything a `decide(ctx)` function touches is defined here — IDE
+autocomplete over these types IS the API reference. Broker-agnostic by
+design: nothing in the contract names a broker; orders, fills, and charges
+happen server-side behind the deployment's configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Union
+
+from pydantic import BaseModel, ConfigDict
+
+#: What a strategy may return from ``decide(ctx)``.
+#:
+#: - ``"BUY"``  — open a long position (ignored if already in a position)
+#: - ``"SELL"`` — open a SHORT position (intraday only; ignored if in a position)
+#: - ``"EXIT"`` — close the current position, long or short
+#: - ``"HOLD"`` — do nothing (returning ``None`` means the same)
+Action = Literal["BUY", "SELL", "EXIT", "HOLD"]
+
+#: Anything ``decide`` may return: an Action string, a Decision, or None (=HOLD).
+DecisionLike = Union[Action, "Decision", None]
+
+
+class Bar(BaseModel):
+    """One OHLCV candle."""
+
+    model_config = ConfigDict(frozen=True)
+
+    timestamp: str
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: int
+
+
+class Position(BaseModel):
+    """Your current position in the symbol (server-tracked)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    side: Literal["long", "short", "flat"] = "flat"
+    quantity: int = 0
+    entry_price: float | None = None
+    unrealized_pnl: float = 0.0
+
+    @property
+    def is_open(self) -> bool:
+        return self.side != "flat"
+
+
+class Decision(BaseModel):
+    """An action with an optional human-readable reason (shows up in the
+    trade log). ``quantity`` is intentionally absent — sizing is owned by the
+    run/deployment configuration, not the strategy."""
+
+    model_config = ConfigDict(frozen=True)
+
+    action: Action
+    reason: str = ""
+
+
+class Ctx(BaseModel):
+    """Everything known at this bar close. Passed to your ``decide`` function.
+
+    ``features`` holds your declared indicators by alias (e.g. ``rsi_14``)
+    plus the raw OHLCV fields; ``prev_features`` is the previous bar's values
+    (for cross-style logic). ``history`` is oldest-first through the current
+    bar. Hosted backtests retain the full run; paper deployments retain a
+    rolling window from deployment time. Reading either is local and free.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    timestamp: str
+    symbol: str
+    timeframe: str
+    bar: Bar
+    features: dict[str, float | None]
+    prev_features: dict[str, float | None]
+    position: Position
+    cash: float
+    history: tuple[Bar, ...] = ()
+
+
+class Feature(BaseModel):
+    """A declared indicator, computed server-side by the same engine that
+    powers rules strategies — identical values in backtest, paper, and live.
+
+    Examples::
+
+        Feature(name="rsi", period=14)                    # -> ctx.features["rsi_14"]
+        Feature(name="vwap")                              # -> ctx.features["vwap"]
+        Feature(name="sma", period=50, alias="slow_ma")   # -> ctx.features["slow_ma"]
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    period: int | None = None
+    source: str = "close"
+    alias: str | None = None
+    params: dict[str, float] = {}
+    outputs: dict[str, str] = {}
+
+    def spec(self) -> dict:
+        out: dict = {"name": self.name, "source": self.source}
+        if self.period is not None:
+            out["period"] = self.period
+        if self.alias:
+            out["alias"] = self.alias
+        if self.params:
+            out["params"] = dict(self.params)
+        if self.outputs:
+            out["outputs"] = dict(self.outputs)
+        return out
+
+
+class BacktestSummary(BaseModel):
+    """Headline numbers of a completed backtest run."""
+
+    model_config = ConfigDict(extra="allow")
+
+    symbol: str
+    timeframe: str
+    start_date: str
+    end_date: str
+    initial_cash: float
+    final_equity: float
+    net_pnl: float = 0.0
+    net_return_pct: float = 0.0
+    total_trades: int = 0
+    winning_trades: int = 0
+    losing_trades: int = 0
+
+
+class BacktestOutcome(BaseModel):
+    """Full result payload returned by :meth:`edenalpha.Client.backtest`."""
+
+    model_config = ConfigDict(extra="allow")
+
+    summary: BacktestSummary
+    trades: list[dict] = []
+    equity_curve: list[dict] = []
+    warnings: list[str] = []