osp-provider-runtime 0.1.0__tar.gz

osp_provider_runtime-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Sync dev dependencies
+        run: uv sync --extra dev
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Mypy
+        run: uv run mypy src tests
+      - name: Pytest
+        run: uv run pytest
+      - name: Build artifacts
+        run: uv run python -m build
+      - name: Validate artifacts
+        run: uv run twine check dist/*

osp_provider_runtime-0.1.0/.github/workflows/release-artifacts.yml

@@ -0,0 +1,32 @@
+name: Release Artifacts
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-attach:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Sync dev dependencies
+        run: uv sync --extra dev
+      - name: Verify quality gates
+        run: |
+          uv run ruff check .
+          uv run mypy src tests
+          uv run pytest
+      - name: Build artifacts
+        run: uv run python -m build
+      - name: Validate artifacts
+        run: uv run twine check dist/*
+      - name: Create GitHub release and upload artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

osp_provider_runtime-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/

osp_provider_runtime-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-02-12
+
+- Initial alpha runtime package.
+- Added thin provider execution runtime and RabbitMQ runner.
+- Added envelope parsing/serialization and explicit ack decision model.
+- Added tests for envelope validation and retry/ack semantics.

osp_provider_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IT-OPS
+
+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.

osp_provider_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: osp-provider-runtime
+Version: 0.1.0
+Summary: Thin runtime harness for OSP providers (RabbitMQ transport + contract execution).
+Author: OSP Team
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: loguru<1,>=0.7
+Requires-Dist: osp-provider-contracts<0.2,>=0.1
+Requires-Dist: pika<2,>=1.3
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: hatch<2,>=1.14; extra == 'dev'
+Requires-Dist: mypy<2,>=1.11; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.6; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# osp-provider-runtime
+
+Thin, boring runtime harness for OSP providers.
+
+This package handles RabbitMQ message plumbing so provider implementations can
+focus on business logic.
+
+## What it does (v0.1)
+
+- Parses a versioned request envelope.
+- Builds provider `RequestContext`/`ProviderRequest` and calls `execute(...)`.
+- Serializes a standard response envelope.
+- Applies explicit ack/requeue/dead-letter decisions.
+- Emits structured logs for delivery decisions.
+
+## What it does not do
+
+- No provider framework.
+- No plugin system.
+- No workflow orchestration.
+
+## Install
+
+```bash
+pip install osp-provider-runtime
+```
+
+## Development
+
+```bash
+env -u VIRTUAL_ENV uv sync --extra dev
+hatch shell
+hatch run check
+hatch run build
+hatch run verify
+```
+
+Note: before `osp-provider-contracts` is published to your index, use `uv` for
+local checks in this monorepo:
+
+```bash
+env -u VIRTUAL_ENV uv run ruff check .
+env -u VIRTUAL_ENV uv run mypy src tests
+env -u VIRTUAL_ENV uv run pytest
+```
+
+Tag and push:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```

osp_provider_runtime-0.1.0/README.md

@@ -0,0 +1,52 @@
+# osp-provider-runtime
+
+Thin, boring runtime harness for OSP providers.
+
+This package handles RabbitMQ message plumbing so provider implementations can
+focus on business logic.
+
+## What it does (v0.1)
+
+- Parses a versioned request envelope.
+- Builds provider `RequestContext`/`ProviderRequest` and calls `execute(...)`.
+- Serializes a standard response envelope.
+- Applies explicit ack/requeue/dead-letter decisions.
+- Emits structured logs for delivery decisions.
+
+## What it does not do
+
+- No provider framework.
+- No plugin system.
+- No workflow orchestration.
+
+## Install
+
+```bash
+pip install osp-provider-runtime
+```
+
+## Development
+
+```bash
+env -u VIRTUAL_ENV uv sync --extra dev
+hatch shell
+hatch run check
+hatch run build
+hatch run verify
+```
+
+Note: before `osp-provider-contracts` is published to your index, use `uv` for
+local checks in this monorepo:
+
+```bash
+env -u VIRTUAL_ENV uv run ruff check .
+env -u VIRTUAL_ENV uv run mypy src tests
+env -u VIRTUAL_ENV uv run pytest
+```
+
+Tag and push:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```

osp_provider_runtime-0.1.0/docs/release.md

@@ -0,0 +1,36 @@
+# Release Guide
+
+Automated on tag `vX.Y.Z`:
+- run lint, type-check, tests
+- build sdist + wheel
+- run `twine check dist/*`
+- attach artifacts to GitHub Release
+
+Manual/gated publish:
+
+```bash
+env -u VIRTUAL_ENV uv sync --extra dev
+hatch shell
+hatch run check
+hatch run build
+hatch run verify
+hatch run publish
+```
+
+Pre-publish note:
+- `osp-provider-runtime` depends on `osp-provider-contracts`.
+- Publish contracts first (or use local `uv` checks in monorepo before publish).
+
+For internal index or other repository:
+
+```bash
+hatch publish -r <repo-name>
+```
+
+Credentials should be stored in `~/.pypirc` (or keyring), not committed.
+
+TestPyPI dry run publish:
+
+```bash
+hatch run publish-test
+```

osp_provider_runtime-0.1.0/docs/runtime-contract.md

@@ -0,0 +1,52 @@
+# Runtime Messaging Contract (v0.1)
+
+Request envelope required fields:
+- `envelope_version` (string)
+- `contract_version` (string)
+- `message_id` (string)
+- `correlation_id` (string)
+- `task_id` (string)
+- `action` (string)
+- `resource_kind` (string)
+- `payload` (object)
+
+Optional fields:
+- `attempt` (int, defaults to 1)
+- `idempotency_key` (string)
+- `provider` (string)
+
+Response envelope:
+- `envelope_version`
+- `contract_version`
+- `message_id`
+- `correlation_id`
+- `task_id`
+- `ok` (bool)
+- `provider` (string)
+- `action` (string)
+- `result` (object, only when `ok=true`)
+- `error` (object, only when `ok=false`)
+
+Error object shape:
+- `code` (string)
+- `detail` (string | null)
+- `retryable` (bool)
+- `extra` (object)
+
+Ack policy:
+- Success: `ack`.
+- `ProviderError(retryable=false)`: `ack`.
+- `ProviderError(retryable=true)`: `requeue` until max attempts; then dead-letter.
+- Unknown exception: treat as retryable transient error with same attempt policy.
+
+Legacy compatibility:
+- Runtime also accepts legacy orchestrator outbox payloads:
+  - `{"id": <int>, "action": <str>, ...}`
+- For legacy input, runtime can emit provider update events to `osp.to_orch`
+  using `status_code=200` on success and `status_code=580` on terminal errors.
+
+Runtime topology behavior:
+- Runtime declares and binds its request queue on startup.
+- Default request exchange: `osp.from_orch` (topic).
+- Default request binding: `<provider_name>.#`.
+- Default updates exchange: `osp.to_orch` (topic).

osp_provider_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "osp-provider-runtime"
+version = "0.1.0"
+description = "Thin runtime harness for OSP providers (RabbitMQ transport + contract execution)."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "OSP Team" }]
+dependencies = [
+  "loguru>=0.7,<1",
+  "osp-provider-contracts>=0.1,<0.2",
+  "pika>=1.3,<2",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "hatch>=1.14,<2",
+  "mypy>=1.11,<2",
+  "pytest>=8.3,<9",
+  "ruff>=0.6,<1",
+  "twine>=6,<7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/osp_provider_runtime"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "pika"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "pika.*"
+ignore_missing_imports = true
+
+[tool.hatch.envs.default]
+python = "3.12"
+installer = "uv"
+path = ".venv"
+features = ["dev"]
+
+[tool.hatch.envs.default.scripts]
+check = [
+  "ruff check .",
+  "mypy src tests",
+  "pytest",
+]
+build = "python -m build"
+verify = "twine check dist/*"
+publish-test = "twine upload -r testpypi dist/*"
+publish = "twine upload dist/*"
+
+[tool.uv.sources]
+osp-provider-contracts = { path = "../osp-provider-contracts", editable = true }

osp_provider_runtime-0.1.0/src/osp_provider_runtime/__init__.py

@@ -0,0 +1,12 @@
+from .app import run_provider, run_provider_with_config
+from .config import RuntimeConfig
+from .runtime import ProviderRuntime
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "ProviderRuntime",
+    "RuntimeConfig",
+    "run_provider",
+    "run_provider_with_config",
+]

osp_provider_runtime-0.1.0/src/osp_provider_runtime/app.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from osp_provider_contracts import Provider
+
+from .config import RuntimeConfig
+from .rabbitmq import RabbitMQRunner
+from .runtime import ProviderRuntime
+
+
+def run_provider(provider: Provider) -> None:
+    run_provider_with_config(provider, RuntimeConfig.from_env())
+
+
+def run_provider_with_config(provider: Provider, config: RuntimeConfig) -> None:
+    runtime = ProviderRuntime(provider=provider, config=config)
+    runner = RabbitMQRunner(config)
+    runner.run(runtime.handle_delivery)

osp_provider_runtime-0.1.0/src/osp_provider_runtime/config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeConfig:
+    rabbitmq_url: str
+    request_queue: str
+    request_exchange: str = "osp.from_orch"
+    request_binding: str | None = None
+    prefetch_count: int = 1
+    max_attempts: int = 5
+    provider_name: str = "unknown-provider"
+    updates_exchange: str = "osp.to_orch"
+    updates_routing_key: str = "unknown-provider"
+    emit_legacy_updates: bool = True
+
+    @classmethod
+    def from_env(cls) -> RuntimeConfig:
+        provider_name = os.getenv("OSP_RUNTIME_PROVIDER_NAME", "unknown-provider")
+        request_binding = os.getenv("OSP_RUNTIME_REQUEST_BINDING") or f"{provider_name}.#"
+        return cls(
+            rabbitmq_url=os.environ["OSP_RUNTIME_RABBITMQ_URL"],
+            request_queue=os.environ["OSP_RUNTIME_REQUEST_QUEUE"],
+            request_exchange=os.getenv("OSP_RUNTIME_REQUEST_EXCHANGE", "osp.from_orch"),
+            request_binding=request_binding,
+            prefetch_count=int(os.getenv("OSP_RUNTIME_PREFETCH_COUNT", "1")),
+            max_attempts=int(os.getenv("OSP_RUNTIME_MAX_ATTEMPTS", "5")),
+            provider_name=provider_name,
+            updates_exchange=os.getenv("OSP_RUNTIME_UPDATES_EXCHANGE", "osp.to_orch"),
+            updates_routing_key=os.getenv("OSP_RUNTIME_UPDATES_ROUTING_KEY", "unknown-provider"),
+            emit_legacy_updates=os.getenv("OSP_RUNTIME_EMIT_LEGACY_UPDATES", "1").lower()
+            in {"1", "true", "yes", "y"},
+        )

osp_provider_runtime-0.1.0/src/osp_provider_runtime/envelope.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RequestEnvelope:
+    envelope_version: str
+    contract_version: str
+    message_id: str
+    correlation_id: str
+    task_id: str
+    action: str
+    resource_kind: str
+    payload: dict[str, Any]
+    attempt: int = 1
+    idempotency_key: str | None = None
+    provider: str | None = None
+    source_format: str = "contract_v1"
+    legacy_task_id: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseEnvelope:
+    envelope_version: str
+    contract_version: str
+    message_id: str
+    correlation_id: str
+    task_id: str
+    ok: bool
+    provider: str
+    action: str
+    result: dict[str, Any] | None = None
+    error: dict[str, Any] | None = None
+
+
+REQUIRED_REQUEST_FIELDS = {
+    "envelope_version",
+    "contract_version",
+    "message_id",
+    "correlation_id",
+    "task_id",
+    "action",
+    "resource_kind",
+    "payload",
+}
+
+
+def parse_request_envelope(raw_body: bytes) -> RequestEnvelope:
+    data = json.loads(raw_body.decode("utf-8"))
+
+    if not isinstance(data, dict):
+        raise ValueError("request envelope must be a JSON object")
+
+    missing = sorted(REQUIRED_REQUEST_FIELDS - set(data.keys()))
+    if not missing:
+        payload = data["payload"]
+        if not isinstance(payload, dict):
+            raise ValueError("payload must be a JSON object")
+
+        attempt = data.get("attempt", 1)
+        if not isinstance(attempt, int) or attempt < 1:
+            raise ValueError("attempt must be an integer >= 1")
+
+        return RequestEnvelope(
+            envelope_version=str(data["envelope_version"]),
+            contract_version=str(data["contract_version"]),
+            message_id=str(data["message_id"]),
+            correlation_id=str(data["correlation_id"]),
+            task_id=str(data["task_id"]),
+            action=str(data["action"]),
+            resource_kind=str(data["resource_kind"]),
+            payload=payload,
+            attempt=attempt,
+            idempotency_key=(str(data["idempotency_key"]) if "idempotency_key" in data else None),
+            provider=(str(data["provider"]) if "provider" in data else None),
+            source_format="contract_v1",
+            legacy_task_id=None,
+        )
+
+    # Legacy orchestrator outbox payload:
+    # {"id": int, "action": str, ...} with provider-specific fields at top level.
+    if "id" not in data or "action" not in data:
+        raise ValueError(f"missing required envelope fields: {missing}")
+    task_id = data.get("id")
+    action = data.get("action")
+    if not isinstance(task_id, int) or not isinstance(action, str) or not action.strip():
+        raise ValueError("legacy message requires id:int and action:str")
+    attempt = data.get("attempt", 1)
+    if not isinstance(attempt, int) or attempt < 1:
+        raise ValueError("attempt must be an integer >= 1")
+    provider = data.get("provider")
+    message_id = str(data.get("message_id") or f"legacy-task-{task_id}")
+    correlation_id = str(data.get("correlation_id") or message_id)
+    return RequestEnvelope(
+        envelope_version="legacy_v1",
+        contract_version="legacy_v1",
+        message_id=message_id,
+        correlation_id=correlation_id,
+        task_id=str(task_id),
+        action=action.strip(),
+        resource_kind=str(data.get("resource_kind") or "task"),
+        payload=data,
+        attempt=attempt,
+        idempotency_key=(str(data["idempotency_key"]) if "idempotency_key" in data else None),
+        provider=(str(provider) if provider is not None else None),
+        source_format="legacy_orchestrator",
+        legacy_task_id=task_id,
+    )
+
+
+def dump_response_envelope(envelope: ResponseEnvelope) -> bytes:
+    return json.dumps(asdict(envelope), separators=(",", ":")).encode("utf-8")

osp_provider_runtime-0.1.0/src/osp_provider_runtime/rabbitmq.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pika  # type: ignore[import-untyped]
+from loguru import logger
+
+from .config import RuntimeConfig
+from .transport import AckAction, Delivery, DeliveryHandler
+
+
+class RabbitMQRunner:
+    def __init__(self, config: RuntimeConfig) -> None:
+        self.config = config
+
+    def run(self, handler: DeliveryHandler) -> None:
+        params = pika.URLParameters(self.config.rabbitmq_url)
+        connection = pika.BlockingConnection(params)
+        channel = connection.channel()
+        channel.basic_qos(prefetch_count=self.config.prefetch_count)
+        channel.exchange_declare(
+            exchange=self.config.request_exchange,
+            exchange_type="topic",
+            durable=True,
+        )
+        channel.exchange_declare(
+            exchange=self.config.updates_exchange,
+            exchange_type="topic",
+            durable=True,
+        )
+        channel.queue_declare(queue=self.config.request_queue, durable=True)
+        if self.config.request_binding:
+            channel.queue_bind(
+                queue=self.config.request_queue,
+                exchange=self.config.request_exchange,
+                routing_key=self.config.request_binding,
+            )
+
+        def _on_message(ch: Any, method: Any, properties: Any, body: bytes) -> None:
+            delivery = Delivery(
+                body=body,
+                reply_to=properties.reply_to,
+                routing_key=getattr(method, "routing_key", None),
+            )
+            result = handler(delivery)
+
+            if result.response_body and result.response_routing_key:
+                channel.basic_publish(
+                    exchange="",
+                    routing_key=result.response_routing_key,
+                    body=result.response_body,
+                    properties=pika.BasicProperties(
+                        content_type="application/json",
+                        correlation_id=result.response_correlation_id,
+                    ),
+                )
+            if result.update_body and result.update_exchange and result.update_routing_key:
+                channel.basic_publish(
+                    exchange=result.update_exchange,
+                    routing_key=result.update_routing_key,
+                    body=result.update_body,
+                    properties=pika.BasicProperties(
+                        content_type="application/json",
+                    ),
+                )
+
+            if result.ack_action == AckAction.ACK:
+                ch.basic_ack(delivery_tag=method.delivery_tag)
+            elif result.ack_action == AckAction.REQUEUE:
+                ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)
+            else:
+                ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
+
+        channel.basic_consume(queue=self.config.request_queue, on_message_callback=_on_message)
+        logger.info(
+            "Starting runtime consumer",
+            queue=self.config.request_queue,
+            exchange=self.config.request_exchange,
+            binding=self.config.request_binding,
+            updates_exchange=self.config.updates_exchange,
+            updates_routing_key=self.config.updates_routing_key,
+        )
+        channel.start_consuming()