Metadata-Version: 2.4
Name: edenalpha
Version: 0.1.2
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.
