Metadata-Version: 2.4
Name: alelyon-sdk
Version: 0.1.0
Summary: Python client for the Alelyon API — certified market data served next to its capture certificate.
Author: Alelyon
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/TLace03/Alelyon-Dev-Tools
Project-URL: Repository, https://github.com/TLace03/Alelyon-Dev-Tools
Project-URL: Issues, https://github.com/TLace03/Alelyon-Dev-Tools/issues
Project-URL: Changelog, https://github.com/TLace03/Alelyon-Dev-Tools/blob/main/CHANGELOG.md
Keywords: alelyon,api-client,sdk,market-data,certified-data,openapi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Provides-Extra: stream
Requires-Dist: pyzmq>=25; extra == "stream"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pyzmq>=25; extra == "dev"
Dynamic: license-file

# alelyon-sdk

Python client for the Alelyon read-only v1 HTTP API.

```bash
pip install alelyon-sdk              # HTTP client (httpx only)
pip install "alelyon-sdk[stream]"    # adds EngineStream (pyzmq)
```

## There is no public Alelyon server

This is a client. It ships no server and there is no public endpoint to point it at. It
is useful if you run, or have access to, an Alelyon deployment. The default base URL is
`http://127.0.0.1:8710` because that is where a local deployment listens.

With no deployment you can still exercise every request the client builds, offline,
through a mock transport — see [`examples/offline_demo.py`](../../examples/offline_demo.py).

## Use

```python
from alelyon_sdk import AlelyonClient

with AlelyonClient("http://127.0.0.1:8710", api_key="…") as c:
    c.health()

    bars = c.bars("AAPL", lookback_days=90)
    print(bars["bars"]["data"][-1])          # frames use pandas split orientation
    print(bars["certificate"]["columns"]["close"]["delta_max"])   # price error bound

    c.quote("SPY")
    c.quotes(["AAPL", "MSFT"], include_certs=True)
    c.fred("DGS10")
    c.rates(); c.vol("SPY"); c.rotation(); c.crash(); c.breadth()
    c.analyst("MSFT")
    c.screener(["AAPL", "MSFT"])        # a LIST of tiles
    c.answer("3-month correlation of SPY and TLT")
    c.certify(program='show corr(price("SPY"), price("TLT"))')
    c.engine_status()
```

Certificates are the point of the API, and the top-level `delta_max` is a scope-wide
maximum across every column — for bars, volume dominates it by orders of magnitude. Use
`certificate["columns"]["close"]` to bound a price. See
[docs/certificates.md](../../docs/certificates.md).

## Errors

Every call either returns decoded JSON or raises `ApiError`, which carries `.status_code`
and the server's `.detail`. Nothing from `httpx` leaks through except genuine transport
failures.

| Status | Meaning |
| --- | --- |
| 401 | Invalid or missing API key |
| 403 | Open mode refusing a non-loopback client |
| 404 | No data for the requested scope |
| 422 | Malformed request |
| 503 | An upstream engine or LLM author is unavailable — *not* "the answer is zero" |

Redirects are followed by default. See [docs/errors.md](../../docs/errors.md).

## Streaming

```python
from alelyon_sdk import EngineStream

with EngineStream("127.0.0.1", 5555) as es:
    for msg in es.messages(types={"health", "pnl"}, timeout_s=30):
        print(msg["type"], msg["data"])
```

A pure subscriber — connecting cannot influence the engine. `messages()` returns after
`timeout_s` with nothing yielded; the clock runs on messages passing your filter, so a
busy engine publishing only types you did not ask for still ends the loop. See
[docs/streaming.md](../../docs/streaming.md).

## Verifying certified results

`c.certify(...)` returns a signed envelope. Checking it needs no server and no trust in
the issuer — that is [`alelyon-verify`](../alelyon-verify).

## Other languages

Generate a client from [`spec/openapi.json`](../../spec/openapi.json). See
[docs/codegen.md](../../docs/codegen.md).

## Licence

Apache-2.0.
