ori-sdk-python

Python SDK for building integrations with the Ori runtime, Gateway consumers, and community skill tooling.

Table of contents

• Overview
• Design principles
• Scope
• Technologies
• Project setup
• Using the SDK
  • Read runtime health
  • Validate skill packages
  • Author skill packages with decorators
  • Describe deployments
  • Build gateway messages
  • Build runtime telemetry
  • Verify firmware telemetry
  • Sign artifacts and manifests
• Verification checklist
  • Tests
  • Code quality
  • Repository checks
• Contract compatibility
• Contributing
  • Contribution rules
  • Recommended contribution workflow
• Security and distribution
• Project links
• Status
• License

Overview

Ori is made up of several applications that exchange structured health, gateway, skill, telemetry, and firmware data. ori-sdk-python provides shared Python models and helpers so those applications interpret the same contracts in the same way.

This SDK mirrors the contracts defined in ori-specs without depending on ori-runtime internals. It provides typed models, validation, and helper utilities for Ori consumers while leaving runtime policy and action authority to the runtime itself.

The SDK is a library rather than a standalone application. It includes a read-only Unix socket client for runtime health but does not provide networking, hardware control, database access, or local skill execution.

Design principles

The SDK is designed around a few core principles:

• Mirror runtime and ori-specs contracts rather than redefine them.
• Keep public APIs fully typed and immutable where practical.
• Avoid dependencies on ori-runtime internals.
• Provide reusable models and helpers without implementing runtime policy.
• Keep networking and hardware control outside the SDK, except for the read-only runtime health client.

Scope

The 0.1.x release includes:

• • Typed runtime-health models and synchronous/asynchronous local health-socket clients.
• Read-only health diagnostic helpers.
• Deployment-aware configuration models for CLI and Gateway consumers.
• Immutable skill package models and validation.
• Decorator-based skill-package authoring through the same v1 normaliser.
• Gateway topics, payload models, response correlation, and request lifecycle helpers.
• Runtime telemetry models, canonical JSON serialization, and HMAC helpers.
• Ed25519 signing and verification helpers for artifacts and skill manifests.
• Firmware Layer 1 capability, telemetry, heartbeat, fault, and freshness models.

The following are intentionally out of scope:

• Runtime policy enforcement.
• Hardware control.
• Local skill execution.
• MQTT or HTTP clients.
• Database persistence.

Technologies

Technology	Purpose
Python 3.11 and 3.12	Supported and CI-tested Python versions
Dataclasses	Typed, mostly immutable SDK models
PyYAML	Safe loading and validation of skill-package documents
cryptography	Ed25519 signing and signature verification
Unix domain sockets	Read-only communication with the local runtime health socket
asyncio	Asynchronous runtime health requests
pytest	Unit and integration testing
mypy	Static type checking
Ruff	Linting and formatting
pre-commit	Local quality and repository policy checks
GitHub Actions	Continuous integration

Runtime dependencies are limited to cryptography and PyYAML.

Development dependencies are managed through pyproject.toml and pinned in requirements-dev.txt.

Project setup

1. Clone the repository

Before contributing or experimenting with the SDK, clone the repository and set up a local development environment.

git clone <repository-url>
cd ori-sdk-python

2. Create a virtual environment

python -m venv .venv

3. Activate the environment

For macOS / Linux

source .venv/bin/activate

For command prompt

.venv\Scripts\activate.bat

for Windows powerShell

.venv\Scripts\Activate.ps1

4. Install the project and its dependencies

pip install -e ".[dev]"

5. Install the pre-commit hooks

pre-commit install

Requirements

• Python 3.11 or 3.12
• pip

Using the SDK

ori-sdk-python is a Python library rather than a standalone application. It does not provide a server or daemon to start. Instead, import the SDK into your own applications and tools.

• Read Runtime Health

  The SDK provides typed health models and read-only diagnostic helpers. Health clients support synchronous and asynchronous local socket access. These helpers summarize runtime state but do not grant authority or make action decisions.

  from ori_sdk import (
      RuntimeHealthClient,
      runtime_posture_summary,
      sensor_freshness_delta,
  )
  
  response = RuntimeHealthClient().get_health()
  if response.ok and response.health is not None:
      posture = runtime_posture_summary(response.health)
      freshness = sensor_freshness_delta(response.health)

• Validate skill packages

  The SDK provides immutable skill-package models and validation helpers aligned with the Ori skill-package contract. Validation checks package structure and metadata consistency.

  from pathlib import Path
  from ori_sdk import SkillYamlNormaliser
  
  package = SkillYamlNormaliser.load_and_validate(
      Path("skills/my-skill/skill.yaml")
      )
      print(package.name, package.triggers[0].action_tier)

• Author skill packages with decorators

  The decorator API provides a Python authoring surface for the same skills-package/v1 document produced by YAML. Decorated functions are metadata declarations only: the SDK does not execute them, inspect their source, or package their code.

  from ori_sdk import Agent, SensorRequirement
  
  agent = Agent(
      name="energy-guard",
      version="1.0.0",
      author="ori",
      sensors_required=(SensorRequirement(type="current_clamp"),),
  )
  
  
  @agent.action(tier="A")
  def alert_operator() -> None:
      pass
  
  
  @agent.when(
      "value > 20",
      tier="A",
      actions=("alert_operator",),
      escalate_to="gateway",
      prompt="Current draw is {value}{unit}.",
  )
  def high_usage() -> None:
      pass
  
  
  package = agent.compile()

  The exported action(agent, ...) and when(agent, ...) functions provide the same behavior when module-level decorators are preferable.

  Conditions must be explicit strings; callable and lambda source is never serialized. Every trigger requires tier. Physical Tier B declarations must select approval or reasoning_policy="post_action", Tier C requires an explicit safe_default_action, and Tier D is always rule-only with no prompt. Agent.compile() delegates final validation to SkillYamlNormaliser, so the decorator API cannot bypass YAML-equivalent safety checks. Cloud reasoning is represented by escalate_to="gateway"; the legacy cloud value is rejected.

• Describe deployments

  The SDK provides typed deployment models that describe deployment capabilities and constraints. These summaries help CLI and Gateway consumers understand the deployment class.

  from ori_sdk import DeviceConfig, DeploymentType
  
  config = DeviceConfig(DeploymentType.EDGE_NODE, device_id="site-a-edge-01")
  print(config.constraints.max_action_tier)  # "D"

  Deployment type	Physical actuation supported	Maximum action tier
  edge_node	conditional	D
  phone	unsupported	B
  pi	conditional	D
  server	unsupported	None

• Build gateway messages

  Gateway models represent logical messages after transport handling. They do not implement transport security, open MQTT connections, or grant mutation or physical-action authority.

  from ori_sdk import RuntimeExportRequest, export_request_topic
  
  request = RuntimeExportRequest(
      request_id="report-2026-07",
      export_type="sensor_history",
      device_id="site-a-edge-01",
      since_ms=1717000000000,
      until_ms=1717600000000,
      limit=500,
      params={"sensor_id": "current-main", "bucket_ms": 3600000},
  )
  
  print(export_request_topic(request.device_id), request.to_dict())

  GatewaySession adds deterministic retry and timeout state around an already-validated request. Correlation is a non-raising routing predicate; use the existing family-specific validators afterward to enforce the full response contract.

  from ori_sdk import (
      ActiveSessionRegistry,
      GatewayRetryPolicy,
      GatewaySession,
  )
  
  session = GatewaySession(
      request,
      GatewayRetryPolicy(timeout_ms=10_000, max_retries=1),
  )
  sessions = ActiveSessionRegistry()
  sessions.register(session)
  
  # After the current attempt times out, this preserves request_id and
  # starts a fresh per-attempt deadline.
  retried = sessions.retry(session.request_id)

  Reasoning and Tier C sessions use the timeout carried by their request envelope. Runtime export requests have no timeout field, so export sessions use GatewayRetryPolicy.timeout_ms. The registry is thread-safe for synchronous callers and does not perform MQTT I/O, payload parsing, or response validation. GatewaySession.ensure_active() raises the typed timeout error, while next_attempt() and ActiveSessionRegistry.retry() raise the typed exhaustion error after the retry policy is spent.

• Build runtime telemetry

  The SDK validates the telemetry payload, serializes it into canonical JSON bytes, and computes the HMAC signature. It does not load credentials, build HTTP headers, choose an endpoint, or send telemetry.

  from ori_sdk import (
      RuntimeTelemetryBatch,
      canonical_telemetry_bytes,
      telemetry_hmac_sha256,
  )
  
  batch = RuntimeTelemetryBatch.from_dict(payload)
  body = canonical_telemetry_bytes(batch)
  signature_hex = telemetry_hmac_sha256(api_key, timestamp_ms, body)

• Verify firmware telemetry

  Firmware helpers verify signed capability manifests, measurements, heartbeats, and fault events. Applications are responsible for storing freshness state and replay protection. Verification does not persist data, grant physical-action authority, or enable Tier C/D actions.

  from ori_sdk import (
      FirmwareProvisioningAnchor,
      SignedFirmwareCapabilityManifest,
      canonical_firmware_json_bytes,
      verify_firmware_manifest,
  )
  
  anchor = FirmwareProvisioningAnchor.from_dict(anchor_payload)
  message = SignedFirmwareCapabilityManifest.from_dict(manifest_payload)
  manifest_hash = verify_firmware_manifest(message, anchor)
  signed_bytes = canonical_firmware_json_bytes(message.manifest)

• Sign artifacts and manifests

  Artifact signing protects the exact artifact bytes. Use sign_manifest() and verify_manifest_signature() for canonical skill metadata instead. These two signing profiles are intentionally separate and cannot replace one another.

  from ori_sdk import sign_artifact, verify_artifact_signature
  
  metadata = sign_artifact(artifact_bytes, private_key_bytes)
  verify_artifact_signature(artifact_bytes, metadata, public_key_b64)

The examples above demonstrate the SDK's core building blocks. Each helper is designed to mirror an Ori contract without introducing runtime policy, networking, or hardware dependencies.

Verification checklist

Before opening a pull request, run the following checks locally.

Tests

• Run the full test suite

  pytest -q

• Run a single test file

  pytest -q tests/test_device_config.py

• Run a single test

  pytest -q tests/test_device_config.py::test_deployment_type_from_value

Code quality

• Run Ruff for linting

  ruff check .

• Verify formatting

  ruff format --check .

• Run static type checks

  mypy ori_sdk tests

Repository checks

• Run pre-commit hooks

  pre-commit run --all-files

• Run the workflow checker

  This is applicable IF GitHub workflows or .pre-commit-config.yaml were modified

  python scripts/check_workflows.py

These checks mirror the project's continuous integration (CI) pipeline.

Contract compatibility

SDK version	Runtime compatibility	Specification compatibility
0.1.x	ori-runtime v2.0.0+ (health, gateway, telemetry, firmware telemetry, and skill-loader contracts)	ori-specs v1

The SDK mirrors the following contract families:

• runtime-health/v1
• gateway-api/v1
• skills-package/v1

Legacy skill packages using escalate_to: cloud must migrate to escalate_to: gateway. Cloud reasoning is gateway-mediated in the current contract.

Compatibility notes

The SDK maintains compatibility with existing consumers where possible.

Deprecated APIs remain available for existing integrations but should not be used for new development.

• posture_interpretation() is deprecated in favor of the runtime v2 posture model.
• Legacy skill metadata validation helpers remain available for existing skill package integrations.

Contributing

Contributions are welcome. Changes should preserve the SDK's contract compatibility, strict typing, runtime independence, and security requirements.

Before contributing, read:

1. README.md
2. PRINCIPLES.md
3. AGENTS.md
4. SECURITY.md

Contribution rules

Before opening a pull request, ensure that you:

• Add only fields and semantics defined by the relevant Ori contract (ori-specs).
• Do not import ori-runtime internals.
• Keep public APIs fully typed. Avoid public Any types.
• Use typed SDK errors at public API boundaries.
• Do not expose raw socket or parsing errors.
• Preserve gateway request/response correlation IDs throughout the request lifecycle.
• Preserve the separation between diagnostics/reasoning and runtime action authority.
• Preserve skill-package safety guarantees.
• Add appropriate tests for new behavior and fixtures for contract-facing changes.
• Export new public APIs through ori_sdk/__init__.py.
• Workflow changes must pass scripts/check_workflows.py.
• All local verification commands must pass.

Recommended contribution workflow

1. Create a feature branch:

   git switch -c test/health-timeout-coverage

2. Make your changes and complete the Verification checklist.

3. Commit using the required format:

   git commit -m "test(health): cover timeout failures"

   Commit messages must follow:

   type(scope): description

4. Open a pull request that explains:

   • What changed.
   • Why the change is required.
   • Which contract or repository rule applies.
   • How the change was tested.
   • Whether public behavior or compatibility changed.
   • Whether security-sensitive files were modified.

Note:

Common commit types include:

feat	build	fix	revert
docs	chore	test	security
ci	perf	refactor

Contributions that improve reliability, usability, and contract compatibility are welcome.

Security and distribution

ori-sdk-python is distributed as a Python library rather than a standalone application.

Consumers deploying the SDK in production should follow the project's artifact-signing, dependency, and supply-chain requirements documented in AGENTS.md and SECURITY.md.

To report a security vulnerability, use GitHub private vulnerability reporting. Do not open a public issue for undisclosed security concerns.

Project links

• Ori runtime: ori-runtime
• Ori specifications: ori-specs
• Ori skills hub: ori-skills-hub
• Ori cli: ori-cli
• Ori gateway: ori-gateway

Status

This project is currently in its 0.1.x bootstrap stage, focused on establishing stable SDK contracts and shared models for Ori integrations.

The current release provides:

• Runtime-health contract models and local health communication.
• Deployment-aware configuration models for CLI and Gateway consumers.
• Gateway contract models, request lifecycle, and response validation helpers.
• Skill-package models, validation, and signing helpers.
• Runtime telemetry models and canonical serialization helpers.
• Firmware telemetry capability and verification models.

License

Apache-2.0. See LICENSE.