Metadata-Version: 2.5
Name: adelpha
Version: 0.1.0
Summary: Python library for Adelpha MRI: device telemetry, actuator feedback, and engineering tools.
Project-URL: Homepage, https://github.com/imr-framework/adelpha
Project-URL: Documentation, https://imr-framework.github.io/adelpha/
Project-URL: Repository, https://github.com/imr-framework/adelpha
Project-URL: Issues, https://github.com/imr-framework/adelpha/issues
Author: Adelpha contributors
License: MIT
License-File: LICENSE
Keywords: digital-twin,fem,halbach,mri,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: structlog>=24
Requires-Dist: websockets>=12.0
Provides-Extra: agents
Requires-Dist: google-adk>=2.4.0; extra == 'agents'
Requires-Dist: google-genai>=2.11.0; extra == 'agents'
Provides-Extra: dev
Requires-Dist: fastapi>=0.115.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: pinn
Requires-Dist: onnx>=1.16; extra == 'pinn'
Requires-Dist: onnxruntime<1.21,>=1.17; extra == 'pinn'
Requires-Dist: torch>=2.2; extra == 'pinn'
Provides-Extra: twin
Requires-Dist: fastapi>=0.115.0; extra == 'twin'
Requires-Dist: httpx>=0.28.1; extra == 'twin'
Requires-Dist: matplotlib>=3.9.0; extra == 'twin'
Requires-Dist: pandas>=2.2; extra == 'twin'
Requires-Dist: scipy>=1.11; extra == 'twin'
Requires-Dist: tenacity>=9.1.4; extra == 'twin'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'twin'
Description-Content-Type: text/markdown

# Adelpha

Python library for [Adelpha MRI](https://github.com/imr-framework/adelpha): connect sensors, run control handlers, and call Engineering Studio design functions.

```bash
pip install adelpha
```

```python
from adelpha import telemetry, feedback
```

Adelpha is the WebSocket **server**. Your Raspberry Pi, or a Python process that talks to an Arduino, is the **client**. Arduino never opens a serial session to Adelpha.

## Telemetry (sensors)

```python
import asyncio
import os

from adelpha import telemetry

client = telemetry.connect(
    os.environ["ADELPHA_URL"],
    os.environ["ADELPHA_DEVICE_ID"],
    os.environ["ADELPHA_DEVICE_TOKEN"],
)


async def acquire(device):
    while True:
        await telemetry.publish(
            device,
            temperature=[
                {
                    "sensor_id": 1,
                    "value": 28.4,
                    "unit": "degC",
                    "role": "magnet",
                    "quality": "valid",
                }
            ],
        )
        await asyncio.sleep(1)


asyncio.run(client.run(acquire))
```

`ADELPHA_URL` is `ws://<host>:8765/ws/<device_id>`. Put the token in the environment, never in the URL. Missing sensors use `value: null` with quality `missing` or `invalid`, never zero.

## Feedback (control)

```python
from adelpha import feedback, telemetry

client = telemetry.DeviceClient(
    os.environ["ADELPHA_URL"],
    os.environ["ADELPHA_DEVICE_ID"],
    os.environ["ADELPHA_DEVICE_TOKEN"],
    journal_path="./commands.sqlite3",
)


@feedback.register(
    client,
    "cooling-01",
    "set_enabled",
    argument_schema={
        "type": "object",
        "properties": {"enabled": {"type": "boolean"}},
        "required": ["enabled"],
        "additionalProperties": False,
    },
)
async def cooling(enabled):
    return {"enabled": enabled}
```

Adelpha rejects actuator commands until a hardware scanner profile is selected, `allow_control` is true in `devices.json`, and **Settings → Devices → Physical control** is on. Device-local interlocks remain authoritative.

## Other modules

| Import | Purpose |
| --- | --- |
| `adelpha.twin` | Digital-twin estimators, state, `bootstrap()` |
| `adelpha.magnet` | Halbach array geometry (`design`, `export_cad`) |
| `adelpha.coil` | Gradient-coil request builders (pyCoilGen to run) |
| `adelpha.rfcoil` | Solenoid RF coil request builders |
| `adelpha.shim` | Passive shim request builders |
| `adelpha.fem` | STEP magnetostatics (Gmsh + Elmer to run) |
| `adelpha.domain` | Measurements, units, scanner identity |
| `adelpha.scanners` | Simulated and hardware adapters |
| `adelpha.config` | Profile loading |
| `adelpha.acquisition` | Sensor readers |
| `adelpha.simulation` | Virtual plant models |
| `adelpha.agents` | Agent specialists (`pip install adelpha[agents]`) |
| `adelpha.tools` | Agent tool registry |
| `adelpha.api` | Twin HTTP `create_app` (`pip install adelpha[twin]`) |

Optional extras: `adelpha[twin]`, `adelpha[agents]`, `adelpha[pinn]`.

The imaging console is not part of this package.

## Publish (maintainers)

From the repository root, after tests pass:

```bash
uv build
uv publish
```

Or `python -m build` and `twine upload dist/*`.
