Metadata-Version: 2.4
Name: hyperlake-telemetry
Version: 0.2.2
Summary: Scoped telemetry, artifact, investigation, and semantic-query SDK
Author-email: Hyperlake <vc@hyperlake.cloud>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://hyperlake.cloud
Project-URL: Documentation, https://hyperlake.cloud/docs
Project-URL: Repository, https://github.com/cerebrixos-org/sovereign-telemetry-platform
Keywords: opentelemetry,otlp,openinference,agents,temporal,langflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.2.2
Provides-Extra: temporal
Requires-Dist: temporalio[opentelemetry]>=1.20; extra == "temporal"
Provides-Extra: langflow
Requires-Dist: langflow>=1.6; extra == "langflow"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.30; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30; extra == "otel"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"

# Hyperlake Telemetry SDK for Python

Version 0.2.0 adds shared operations snapshots and redirect refusal.
See [SDK integration and release status](https://github.com/cerebrixos-org/sovereign-telemetry-platform/blob/main/sovereign-telemetry-platform/sdk/README.md).
The 0.1.0 registry package does not contain these additions.

`hyperlake-telemetry` sends standards-compatible OTLP/HTTP JSON, attaches
events and immutable artifacts, manages tenant-editable settings, and performs
scoped event, artifact, video, Run, and evidence-graph investigations. It does not replace the
OpenTelemetry SDK: applications with existing instrumentation should continue
using their normal exporter and use this package only for run context, stable
event identity, evaluations, and artifact attachment.

```bash
pip install hyperlake-telemetry
```

```python
from hyperlake_telemetry import Client, Privacy

client = Client(
    base_url="https://us.hyperlake.cloud",
    protocol_token="write-only-protocol-token",
    tenant_jwt="short-lived-jwks-jwt",
    privacy=Privacy(capture_content=False),
)

with client.run("invoice-agent", goal_id="goal-42") as run:
    with run.span("lookup-account", kind="RETRIEVER"):
        pass
    run.evaluate("groundedness", score=0.97, label="pass")

client.flush()

result = client.semantic_query(
    "Show critical robot video and related faults from the last 2 hours"
)

detection = client.analyze_live_frame(
    "./frame.jpg",
    stream_session_id="camera-session-17",
    frame_id="frame-42",
    device_id="robot-17",
)
```

`analyze_live_frame()` uses the immutable model profile pinned to the JWT's
pipeline. It requires a short-lived JWT with `live:analyze` and `event:ingest`.
The response is a factual object-detection result; the attached live Rule Packs
determine whether it becomes an alert or notification.

The JWT determines tenant and pipeline routing. Explicit routing IDs are
optional with a JWT and are rejected when they conflict with its claims. Local
claim decoding is not signature verification; the regional service verifies
signature, issuer, audience, expiry, permissions, tenant, and pipeline for every
request.
Prompt, response, tool argument, and tool result content is suppressed by
default. Set `capture_content=True` only after applying an approved data policy.

See the repository integration guides for Temporal, Langflow, OpenInference,
Collector, and Alloy examples.

## Reliable semantic queries

`semantic_query()` creates and validates a versioned, bounded query plan before
calling any endpoint. Plans may target event retrieval, artifact/vector search,
and evidence-graph traversal, but cannot contain tenant, pipeline, URL, token,
SQL, or authorization fields. Every response includes the plan hash and scope
provenance.

`DeterministicSemanticPlanner` works without an LLM. `ModelSemanticPlanner`
accepts any callable that returns a JSON-like object; unsafe or invalid model
output falls back to the deterministic plan. A model therefore interprets user
intent but cannot expand authorization or execute arbitrary queries.

Artifact and video retrieval uses configured vector embeddings. Event retrieval
is bounded structured/lexical retrieval, while graph results come from recorded
scoped evidence edges. These signals remain separate and similarity is not
treated as causation.

The client also exposes event listing/search, artifact search/upload/download,
typed telemetry, video playback/timeline, Runs, evidence graphs, tenant config,
protocol-token rotation, and Rule Pack validate/dry-run/publish helpers.
