Metadata-Version: 2.3
Name: zelos-sdk
Version: 0.0.12a2
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Dist: jsonschema >=4.21.1
Requires-Dist: pyarrow >=18.0.0
Requires-Dist: numpy >=1.26 ; extra == 'notebook'
Requires-Dist: pandas >=2.0 ; extra == 'notebook'
Requires-Dist: numpy >=1.26 ; extra == 'analysis'
Requires-Dist: pandas >=2.0 ; extra == 'analysis'
Requires-Dist: pytest >=8.1.0 ; extra == 'test'
Requires-Dist: rich ; extra == 'test'
Provides-Extra: notebook
Provides-Extra: analysis
Provides-Extra: test
Summary: Python SDK for Zelos. Push data into the Zelos app, the agent, or Zelos Cloud.
Author-email: Zelos Cloud <info@zeloscloud.io>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://zeloscloud.io
Project-URL: Documentation, https://docs.zeloscloud.io/latest/sdk/quickstart/
Project-URL: Repository, https://github.com/zeloscloud/zelos
Project-URL: Changelog, https://docs.zeloscloud.io/latest/reference/release-notes/sdk/

# Zelos SDK

Zelos is the data platform for hardware systems. One platform to observe, control, test, and analyze your system in real time, from prototype to production.

Use the Zelos SDK to push data into the Zelos App, Zelos Agent or directly to Zelos Cloud.

# Read data

`connect()` is the one import you need; `zelos_sdk.agent` re-exports the same names.

```python
from zelos_sdk import connect

agent = connect("http://localhost:2300")
frame = agent.query("bus0/BMS_message/cells.*", start="-5m").short_names()

spread = frame["cell_0"] - frame["cell_1"]   # a series in V, on the frame's time axis
spread.abs().max()                           # prints its unit and what it measured
df = frame.ffill().to_pandas()               # a pandas DataFrame, when you want one

agent.check.that("bus0/BMS_message/status.pack_current", "<", 100)
```

A frame and a series answer to pandas' names, and carry units through arithmetic
(`power.to("kW")`, `energy.to("Wh")`). Install `zelos-sdk[notebook]` for the
`pandas` conversions.

# Example: Logging Random Data

Install `uv` and save the file below as `zelos_random.py` and run `uv run zelos_random.py` to start streaming data live.

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [ "zelos-sdk" ]
# ///
import random
import time

import zelos_sdk

zelos_sdk.init()

src = zelos_sdk.TraceSource("example_source")
while True:
    src.log("example/message", {"value": random.randint(0, 10)})
    time.sleep(0.01)
```

# Example: Logging Thermal Zones on Linux

Linux supports reading temperature sensors via sysfs. On a linux system, install `uv` and save the file below as
`temp_linux.py` and run `uv run temp_linux.py` to start streaming data live.

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [ "zelos-sdk" ]
# ///
from pathlib import Path
import time

import zelos_sdk

zelos_sdk.init()

# Find all of our thermal zones from sysfs
thermal_zones = list(Path("/sys/class/thermal").glob("thermal_zone*"))

# Once per second, read the zone info and log it
src = zelos_sdk.TraceSource("linux_thermal")
while True:
    for zone_path in thermal_zones:
        # Read the zone info from sysfs
        zone_type = (zone_path / "type").read_text().strip()
        zone_temp_c = int((zone_path / "temp").read_text().strip()) / 1000.0

        # Log to the zelos sdk
        src.log(zone_path.name, {"type": zone_type, "temp_c": zone_temp_c})

    time.sleep(1)
```

