Metadata-Version: 2.4
Name: astra-ai-sdk
Version: 0.4.1
Summary: Serve Astra-compressed models anywhere - hosted or local ONNX serving with built-in telemetry that feeds the Astra dashboard
Author: Astra
License: MIT License
        
        Copyright (c) 2026 Astra
        
        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.
        
Project-URL: Homepage, https://github.com/AstraFoundation/Astra-Back
Project-URL: Documentation, https://github.com/AstraFoundation/Astra-Back#readme
Project-URL: Changelog, https://github.com/AstraFoundation/Astra-Back/blob/main/clients/python/CHANGELOG.md
Keywords: onnx,model-compression,inference,telemetry,mlops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: serve
Requires-Dist: onnxruntime>=1.18; extra == "serve"
Requires-Dist: numpy>=1.26; extra == "serve"
Provides-Extra: system
Requires-Dist: psutil>=5.9; extra == "system"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py>=12; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: numpy>=1.26; extra == "dev"
Requires-Dist: onnx>=1.16; extra == "dev"
Requires-Dist: onnxruntime>=1.18; extra == "dev"
Dynamic: license-file

# astra-ai-sdk

Serve **Astra-compressed models** on your own hardware — Astra never runs your
model server-side — and keep the Astra dashboard monitoring them while they run.

```bash
pip install 'astra-ai-sdk[serve]'         # on-device ONNX serving (onnxruntime, numpy)
pip install 'astra-ai-sdk[serve,system]'  # + precise CPU/RSS metrics (psutil)
```

Exports: `AstraRunner`, `AstraRunnerError`, `pull_artifact`, `AstraTelemetryReporter`,
`AstraApiError`.

## On-device serving (the whole product)

`AstraRunner.from_deployment` pulls the deployed, compressed artifact once
(sha256-cached under `~/.cache/astra`) and serves it with onnxruntime **inside
your own process** — no server to stand up, no hosted inference:

```python
from astra_sdk import AstraRunner

# base_url defaults to the hosted Astra origin (override with ASTRA_BASE_URL).
runner = AstraRunner.from_deployment("dep_ab12cd34ef", "astra_sk_live_...")
out = runner.run({"input": my_numpy_array})   # bare ndarray per input name
print(out["latencyMs"], out["outputs"], out["preMs"], out["postMs"])
runner.close()                                 # final telemetry flush
```

`run()` returns `{latencyMs, outputs, preMs, postMs, raw}`.

### Run a file you already have

Downloaded the artifact (SDK Hub → **Download Artifact**) or have an `.onnx` on
disk? Skip the deployment — serve the file directly:

```python
from astra_sdk import AstraRunner

runner = AstraRunner.from_file("compressed.onnx")
out = runner.run({"input": my_numpy_array})
runner.close()
```

Telemetry is off for a bare file; pass `deployment_id=` + `api_key=` to still
report local runs to that deployment.

## Closed-loop telemetry (offline-durable)

Every on-device inference is measured and shipped back to Astra through a
**durable closed loop** that can never block or break your serving path:

- buffers events in memory and **spools them to disk when offline**;
- **flushes** the buffered batches automatically on reconnect;
- **deletes each batch only after the server acks it**, with per-batch
  idempotency so a retry is never double-counted.

| Stream | Cadence | Fields |
|---|---|---|
| **Request events** | per inference | timestamp, latency breakdown (preprocess / inference / postprocess ms), success / error code, batch size, region tag, input shape signature |
| **System snapshots** | ~30 s | CPU %, RSS MB, throughput req/min, dropped-event count, SDK / Python / onnxruntime versions, OS, arch, execution provider, hostname |
| **Window stats** | ~60 s or 200 requests | per-input tensor mean/std/min/max/NaN%, output class distribution (top-10), 16-bin confidence histogram, mean entropy, mean top-1 confidence |

Window stats power the dashboard's **prediction drift** (PSI vs the
deployment's reference distribution) and **input distribution shift** alerts.

Opt out any time: `AstraRunner.from_deployment(..., report_telemetry=False)`
or `ASTRA_SDK_TELEMETRY=0`. Disable the on-disk spool with `ASTRA_SDK_SPOOL=0`
(telemetry then buffers in memory only).

## CLI

```bash
astra pull                  # pull the compressed artifact
astra serve --port 8765     # on-device HTTP endpoint: POST /infer
astra bench -n 200          # on-device p50/p95, reported as telemetry
```

Options can come from `ASTRA_BASE_URL`, `ASTRA_DEPLOYMENT_ID`, `ASTRA_API_KEY`
(or `--deployment` / `--api-key` / `--base-url` flags).
