Metadata-Version: 2.4
Name: helixobs
Version: 0.3.2
Summary: Entity-centric observability client for scientific instrument pipelines
Author-email: HelixObs <hello@helixobs.io>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/HelixObs/client-python
Project-URL: Repository, https://github.com/HelixObs/client-python
Project-URL: Issues, https://github.com/HelixObs/client-python/issues
Keywords: observability,opentelemetry,science,astronomy,otel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-sdk>=1.24
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.24
Requires-Dist: opentelemetry-semantic-conventions>=0.45b0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Provides-Extra: e2e
Requires-Dist: pytest>=8.0; extra == "e2e"
Requires-Dist: psycopg2-binary>=2.9; extra == "e2e"
Dynamic: license-file

# helixobs — Python client

Entity-centric observability for scientific instrument pipelines.

Track domain entities (raw observations, intermediate products, derived results) across disjoint asynchronous pipeline stages. The library attaches provenance links between entities so you can trace any scientific result back to the raw data that produced it.

Built on [OpenTelemetry](https://opentelemetry.io/). Signals are standard OTLP — the HelixObs gateway adds entity intelligence on top.

## Installation

```bash
pip install helixobs
```

Requires Python 3.11+.

## Quick start

```python
from helixobs import setup
import logging

log = logging.getLogger("my.pipeline")

# One call wires both traces and logs with matching service name
tel = setup(
    "my-instrument.pipeline",
    instrument_id="MY_INSTRUMENT",
    endpoint="gateway:4317",
    otlp=True,               # ship logs via OTLP to the collector (port 4319)
)

# Track an entity through a pipeline stage
with tel.create("detector", id=product_id, parents=[frame_id]) as token:
    result = process(item)
    log.info("item processed")           # helix_entity_id injected automatically
    if result.score > 0.95:
        token.add_event("helix.event.detection_confirmed", {"score": result.score})
# complete() called on exit; error() called on unhandled exception
```

**Two OTLP endpoints:**

| Endpoint | Default port | Purpose |
|---|---|---|
| HelixObs Gateway | `4317` | OTLP traces — entity spans |
| OTel Collector | `4319` | OTLP logs — structured log shipping |

Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://<host>:4319` for log shipping, or pass `log_endpoint` to `setup()`.

See [USER_GUIDE.md](USER_GUIDE.md) for the full API reference, integration patterns, structured logging, and data model.

## Development

```bash
pip install -e ".[dev]"
pytest
```
