constellation-node-sdk 1.0.1__tar.gz

constellation_node_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: constellation-node-sdk
+Version: 1.0.1
+Summary: L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory
+License: Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: prometheus-client>=0.21.0
+Requires-Dist: python-json-logger>=3.2.0
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.8; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+
+# Constellation Node SDK
+
+`constellation-node-sdk` is the canonical Python SDK for Constellation worker and orchestrator nodes.
+
+It defines the packet-native transport contract used by the Constellation system:
+
+- `TransportPacket` is the single canonical wire format
+- all node-originated follow-up work goes back through **Gate**
+- hop trace is append-only and tamper-evident
+- transport integrity, lineage, provenance, and delegation are first-class protocol concepts
+
+## What this SDK provides
+
+- canonical `TransportPacket` models and helpers
+- transport hashing, signing, verification, and validation
+- Gate-only outbound client
+- reusable node runtime with `/v1/execute` and `/v1/health`
+- orchestrator helpers for workflow composition through Gate
+- tests and examples for worker and orchestrator nodes
+
+## Architectural rules
+
+1. Nodes **must not** know peer node URLs.
+2. Nodes **must only** send follow-up work to `GATE_URL`.
+3. Gate is the sole routing authority.
+4. `TransportPacket` is the only supported transport format.
+5. Semantic packet changes create child packets via `derive()`.
+6. Observational movement appends hop trace entries without changing `transport_hash`.
+
+## Install
+
+```bash
+pip install -e .
+For development:
+
+pip install -e ".[dev]"
+Quick start
+Worker node
+from constellation_node_sdk import create_node_app, register_handler
+
+@register_handler("score")
+async def handle_score(_tenant: str, payload: dict) -> dict:
+    return {
+        "status": "completed",
+        "score": 91,
+        "entity_id": payload["entity_id"],
+    }
+
+app = create_node_app(
+    service_name="score-node",
+    version="1.0.0",
+)
+Orchestrator node
+from constellation_node_sdk import create_node_app, register_handler
+from constellation_node_sdk.gate import GateClient, get_gate_client_config_from_env
+from constellation_node_sdk.orchestrator.step_executor import StepExecutor
+
+gate_client = GateClient(get_gate_client_config_from_env())
+step_executor = StepExecutor(gate_client=gate_client, source_node="orchestrator")
+
+@register_handler("full_pipeline")
+async def handle_full_pipeline(_tenant: str, payload: dict, packet):
+    enrich = await step_executor.execute_step(
+        parent=packet,
+        action="enrich",
+        payload={"entity_id": payload["entity_id"]},
+    )
+    score = await step_executor.execute_step(
+        parent=packet,
+        action="score",
+        payload={**payload, **enrich.payload},
+    )
+    return {
+        "status": "completed",
+        "entity_id": payload["entity_id"],
+        "enrich": enrich.payload,
+        "score": score.payload,
+    }
+
+app = create_node_app(
+    service_name="orchestrator",
+    version="1.0.0",
+)
+Environment
+See .env.example for runtime configuration.
+
+Repo structure
+src/constellation_node_sdk/transport/ — transport contract and hashing
+
+src/constellation_node_sdk/security/ — signing, verification, validation
+
+src/constellation_node_sdk/gate/ — Gate-only client and registration
+
+src/constellation_node_sdk/runtime/ — reusable node runtime
+
+src/constellation_node_sdk/orchestrator/ — workflow composition helpers
+
+contracts/ — formal contract specs
+
+examples/ — runnable worker and orchestrator examples
+
+tests/ — unit and integration coverage
+
+Status
+This repo is intended to be:
+
+packet-native
+
+Gate-routed
+
+composable
+
+production-oriented
+
+strict about protocol correctness
+
+
+```markdown

constellation_node_sdk-1.0.1/README.md

@@ -0,0 +1,118 @@
+# Constellation Node SDK
+
+`constellation-node-sdk` is the canonical Python SDK for Constellation worker and orchestrator nodes.
+
+It defines the packet-native transport contract used by the Constellation system:
+
+- `TransportPacket` is the single canonical wire format
+- all node-originated follow-up work goes back through **Gate**
+- hop trace is append-only and tamper-evident
+- transport integrity, lineage, provenance, and delegation are first-class protocol concepts
+
+## What this SDK provides
+
+- canonical `TransportPacket` models and helpers
+- transport hashing, signing, verification, and validation
+- Gate-only outbound client
+- reusable node runtime with `/v1/execute` and `/v1/health`
+- orchestrator helpers for workflow composition through Gate
+- tests and examples for worker and orchestrator nodes
+
+## Architectural rules
+
+1. Nodes **must not** know peer node URLs.
+2. Nodes **must only** send follow-up work to `GATE_URL`.
+3. Gate is the sole routing authority.
+4. `TransportPacket` is the only supported transport format.
+5. Semantic packet changes create child packets via `derive()`.
+6. Observational movement appends hop trace entries without changing `transport_hash`.
+
+## Install
+
+```bash
+pip install -e .
+For development:
+
+pip install -e ".[dev]"
+Quick start
+Worker node
+from constellation_node_sdk import create_node_app, register_handler
+
+@register_handler("score")
+async def handle_score(_tenant: str, payload: dict) -> dict:
+    return {
+        "status": "completed",
+        "score": 91,
+        "entity_id": payload["entity_id"],
+    }
+
+app = create_node_app(
+    service_name="score-node",
+    version="1.0.0",
+)
+Orchestrator node
+from constellation_node_sdk import create_node_app, register_handler
+from constellation_node_sdk.gate import GateClient, get_gate_client_config_from_env
+from constellation_node_sdk.orchestrator.step_executor import StepExecutor
+
+gate_client = GateClient(get_gate_client_config_from_env())
+step_executor = StepExecutor(gate_client=gate_client, source_node="orchestrator")
+
+@register_handler("full_pipeline")
+async def handle_full_pipeline(_tenant: str, payload: dict, packet):
+    enrich = await step_executor.execute_step(
+        parent=packet,
+        action="enrich",
+        payload={"entity_id": payload["entity_id"]},
+    )
+    score = await step_executor.execute_step(
+        parent=packet,
+        action="score",
+        payload={**payload, **enrich.payload},
+    )
+    return {
+        "status": "completed",
+        "entity_id": payload["entity_id"],
+        "enrich": enrich.payload,
+        "score": score.payload,
+    }
+
+app = create_node_app(
+    service_name="orchestrator",
+    version="1.0.0",
+)
+Environment
+See .env.example for runtime configuration.
+
+Repo structure
+src/constellation_node_sdk/transport/ — transport contract and hashing
+
+src/constellation_node_sdk/security/ — signing, verification, validation
+
+src/constellation_node_sdk/gate/ — Gate-only client and registration
+
+src/constellation_node_sdk/runtime/ — reusable node runtime
+
+src/constellation_node_sdk/orchestrator/ — workflow composition helpers
+
+contracts/ — formal contract specs
+
+examples/ — runnable worker and orchestrator examples
+
+tests/ — unit and integration coverage
+
+Status
+This repo is intended to be:
+
+packet-native
+
+Gate-routed
+
+composable
+
+production-oriented
+
+strict about protocol correctness
+
+
+```markdown

constellation_node_sdk-1.0.1/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=75.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "constellation-node-sdk"
+version = "1.0.1"
+description = "L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Proprietary" }
+
+dependencies = [
+  "fastapi>=0.115.0",
+  "uvicorn[standard]>=0.32.0",
+  "pydantic>=2.9.0",
+  "httpx>=0.27.0",
+  "cryptography>=43.0.0",
+  "prometheus-client>=0.21.0",
+  "python-json-logger>=3.2.0",
+  "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.11.0",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.23.8",
+  "ruff>=0.6.0",
+  "types-PyYAML>=6.0.12",
+  "types-requests",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "I", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

constellation_node_sdk-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

constellation_node_sdk-1.0.1/src/constellation_node_sdk/__init__.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from constellation_node_sdk.gate import (
+    GateClient,
+    GateClientConfig,
+    GateRegistrationConfig,
+    assert_gate_only_destination,
+    assert_local_node_identity,
+    assert_node_origin_packet,
+    build_registration_payload,
+    get_gate_client_config_from_env,
+    get_gate_registration_config_from_env,
+    load_node_spec,
+    register_from_env,
+    register_with_gate,
+    validate_outbound_gate_packet,
+)
+from constellation_node_sdk.runtime import (
+    LifecycleHook,
+    NodeRuntimeConfig,
+    NoOpLifecycle,
+    PreflightFailure,
+    clear_handlers,
+    create_error_transport_packet,
+    create_node_app,
+    execute_transport_packet,
+    get_handler,
+    get_runtime_config,
+    register_handler,
+    registered_actions,
+    run_preflight,
+)
+from constellation_node_sdk.security import (
+    recompute_transport_core,
+    sign_transport_packet,
+    validate_derived_transport_packet,
+    validate_transport_packet,
+    verify_transport_packet_signature,
+)
+from constellation_node_sdk.transport import (
+    DelegationLink,
+    RoutingProvenance,
+    TenantContext,
+    TransportAddress,
+    TransportAttachment,
+    TransportAuthenticationError,
+    TransportAuthorizationError,
+    TransportError,
+    TransportExpiredError,
+    TransportGovernance,
+    TransportHeader,
+    TransportHop,
+    TransportIntegrityError,
+    TransportLineage,
+    TransportNotYetValidError,
+    TransportPacket,
+    TransportSecurity,
+    TransportValidationError,
+    canonical_json,
+    compute_payload_hash,
+    compute_transport_hash,
+    create_transport_packet,
+    ensure_tenant_context,
+    utc_now,
+)
+
+__all__ = [
+    "DelegationLink",
+    "GateClient",
+    "GateClientConfig",
+    "GateRegistrationConfig",
+    "LifecycleHook",
+    "NoOpLifecycle",
+    "NodeRuntimeConfig",
+    "PreflightFailure",
+    "RoutingProvenance",
+    "TenantContext",
+    "TransportAddress",
+    "TransportAttachment",
+    "TransportAuthenticationError",
+    "TransportAuthorizationError",
+    "TransportError",
+    "TransportExpiredError",
+    "TransportGovernance",
+    "TransportHeader",
+    "TransportHop",
+    "TransportIntegrityError",
+    "TransportLineage",
+    "TransportNotYetValidError",
+    "TransportPacket",
+    "TransportSecurity",
+    "TransportValidationError",
+    "assert_gate_only_destination",
+    "assert_local_node_identity",
+    "assert_node_origin_packet",
+    "build_registration_payload",
+    "canonical_json",
+    "clear_handlers",
+    "compute_payload_hash",
+    "compute_transport_hash",
+    "create_error_transport_packet",
+    "create_node_app",
+    "create_transport_packet",
+    "ensure_tenant_context",
+    "execute_transport_packet",
+    "get_gate_client_config_from_env",
+    "get_gate_registration_config_from_env",
+    "get_handler",
+    "get_runtime_config",
+    "load_node_spec",
+    "recompute_transport_core",
+    "register_from_env",
+    "register_handler",
+    "register_with_gate",
+    "registered_actions",
+    "run_preflight",
+    "sign_transport_packet",
+    "utc_now",
+    "validate_derived_transport_packet",
+    "validate_outbound_gate_packet",
+    "validate_transport_packet",
+    "verify_transport_packet_signature",
+]

constellation_node_sdk-1.0.1/src/constellation_node_sdk/gate/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from constellation_node_sdk.gate.client import GateClient
+from constellation_node_sdk.gate.config import (
+    GateClientConfig,
+    GateRegistrationConfig,
+    get_gate_client_config_from_env,
+    get_gate_registration_config_from_env,
+)
+from constellation_node_sdk.gate.errors import (
+    GateClientError,
+    GatePolicyError,
+    GateRegistrationError,
+    GateResponseError,
+)
+from constellation_node_sdk.gate.policy import (
+    assert_gate_only_destination,
+    assert_local_node_identity,
+    assert_node_origin_packet,
+    validate_outbound_gate_packet,
+)
+from constellation_node_sdk.gate.registration import (
+    build_registration_payload,
+    load_node_spec,
+    register_from_env,
+    register_with_gate,
+)
+
+__all__ = [
+    "GateClient",
+    "GateClientConfig",
+    "GateClientError",
+    "GatePolicyError",
+    "GateRegistrationConfig",
+    "GateRegistrationError",
+    "GateResponseError",
+    "assert_gate_only_destination",
+    "assert_local_node_identity",
+    "assert_node_origin_packet",
+    "build_registration_payload",
+    "get_gate_client_config_from_env",
+    "get_gate_registration_config_from_env",
+    "load_node_spec",
+    "register_from_env",
+    "register_with_gate",
+    "validate_outbound_gate_packet",
+]

constellation_node_sdk-1.0.1/src/constellation_node_sdk/gate/client.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+from constellation_node_sdk.security.signing import sign_transport_packet
+from constellation_node_sdk.security.validation import validate_transport_packet
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .config import GateClientConfig
+from .policy import validate_outbound_gate_packet
+
+
+class GateClient:
+    """
+    Canonical Gate-only transport client for nodes.
+
+    This client is the only allowed outbound inter-node transport surface.
+    It never accepts an arbitrary peer URL.
+    """
+
+    def __init__(self, config: GateClientConfig) -> None:
+        self._config = config
+
+    @property
+    def gate_url(self) -> str:
+        return self._config.gate_url
+
+    def _transport_key_resolver(
+        self,
+    ) -> Callable[[str | None], str | bytes | None] | Mapping[str, str | bytes] | None:
+        if not self._config.verifying_keys and self._config.signing_key is None:
+            return None
+        return self._config.resolve_verifying_key
+
+    def _maybe_sign(self, packet: TransportPacket) -> TransportPacket:
+        if self._config.signing_key is None:
+            return packet
+        if self._config.signing_key_id is None or self._config.signing_algorithm is None:
+            raise ValueError(
+                "signing_key_id and signing_algorithm are required when signing_key is configured"
+            )
+        return sign_transport_packet(
+            packet,
+            key=self._config.signing_key,
+            key_id=self._config.signing_key_id,
+            algorithm=self._config.signing_algorithm,
+        )
+
+    def _validate_outbound(self, packet: TransportPacket) -> None:
+        validate_outbound_gate_packet(
+            packet,
+            local_node=self._config.local_node,
+            gate_node_name=self._config.allowed_gate_destination,
+        )
+        validate_transport_packet(
+            packet,
+            key_resolver=self._transport_key_resolver(),
+            require_signature=self._config.require_signature,
+            dev_mode=not self._config.require_signature,
+            verify_hop_signatures=self._config.verify_hop_signatures,
+        )
+
+    def _validate_inbound_response(self, packet: TransportPacket) -> None:
+        validate_transport_packet(
+            packet,
+            key_resolver=self._transport_key_resolver(),
+            require_signature=self._config.verify_response_signatures,
+            dev_mode=not self._config.verify_response_signatures,
+            verify_hop_signatures=self._config.verify_hop_signatures,
+        )
+
+    async def send_to_gate(self, packet: TransportPacket) -> TransportPacket:
+        """
+        Send a canonical TransportPacket to Gate and decode a canonical TransportPacket response.
+        """
+        self._validate_outbound(packet)
+        signed_packet = self._maybe_sign(packet)
+
+        async with httpx.AsyncClient(timeout=self._config.timeout_seconds) as client:
+            response = await client.post(
+                f"{self._config.gate_url}/v1/execute",
+                json=signed_packet.model_dump_json_dict(),
+                headers={"Content-Type": "application/json"},
+            )
+
+        response.raise_for_status()
+        body = response.json()
+        if not isinstance(body, dict):
+            raise ValueError("Gate response body must be a JSON object")
+
+        response_packet = TransportPacket.model_validate(body)
+        self._validate_inbound_response(response_packet)
+        return response_packet
+
+    async def health(self) -> dict[str, Any]:
+        """
+        Query Gate health endpoint.
+        """
+        async with httpx.AsyncClient(timeout=self._config.timeout_seconds) as client:
+            response = await client.get(f"{self._config.gate_url}/v1/health")
+        response.raise_for_status()
+        body = response.json()
+        if not isinstance(body, dict):
+            raise ValueError("Gate health response must be a JSON object")
+        return body