constellation-node-sdk 1.0.1__tar.gz → 1.2.0__tar.gz

constellation_node_sdk-1.2.0/LICENSE

@@ -0,0 +1,104 @@
+QUANTUM AI PARTNERS — L9 PROPRIETARY SOFTWARE LICENSE
+Version 1.0 — 2026
+
+Copyright (c) 2026 Quantum AI Partners ("Licensor"). All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Quantum AI Partners. The Software
+is made source-available on this repository for transparency, audit, and
+evaluation purposes only, under the terms below. NO OPEN-SOURCE LICENSE IS
+GRANTED. No prior license grant by Licensor (if any) shall be construed as
+a waiver of these terms.
+
+1. DEFINITIONS
+
+   "Software" means the source code, object code, documentation, domain
+   specs, configuration, and all other files contained in this repository,
+   and any modifications or derivative works thereof.
+
+   "Commercial Use" means any use of the Software, in whole or in part,
+   directly or indirectly, from which any person or entity derives revenue,
+   profit, cost savings, competitive advantage, or other commercial benefit.
+   This includes, without limitation: selling, sublicensing, or hosting the
+   Software or a derivative work; incorporating the Software into a product
+   or service offered to third parties (including as part of a SaaS,
+   managed service, or consulting engagement); and internal use by a
+   for-profit entity in its business operations beyond internal evaluation.
+
+   "You" / "Licensee" means any individual or entity that accesses, clones,
+   copies, or otherwise makes use of the Software.
+
+2. LIMITED GRANT
+
+   Subject to Your compliance with this License, Licensor grants You a
+   limited, non-exclusive, non-transferable, revocable license to view,
+   clone, and use the Software solely for personal, academic, or internal
+   evaluation purposes that do NOT constitute Commercial Use.
+
+3. COMMERCIAL USE REQUIRES A PAID LICENSE
+
+   Any Commercial Use of the Software requires a separate written commercial
+   license agreement with Quantum AI Partners, negotiated in advance, which
+   may include license fees, royalties, or a revenue/profit share. Engaging
+   in Commercial Use without such an agreement is a material breach of this
+   License and constitutes copyright infringement.
+
+   To request a commercial license, contact: eng@l9.dev
+
+4. RESTRICTIONS
+
+   Except as expressly permitted under Section 2, You may NOT, without prior
+   written consent from Licensor:
+
+   a. Copy, reproduce, or redistribute the Software, in source or object
+      form, to any third party;
+   b. Modify, create derivative works of, reverse-engineer, or decompile
+      the Software, except as necessary for permitted evaluation;
+   c. Sublicense, sell, rent, lease, or otherwise transfer any rights in
+      the Software;
+   d. Host, deploy, or offer the Software (or a derivative work) as a
+      hosted or managed service to any third party;
+   e. Remove, obscure, or alter any copyright, trademark, or proprietary
+      notice contained in the Software;
+   f. Use the Software to build, train, or benchmark a directly competing
+      product or service.
+
+5. OWNERSHIP
+
+   The Software is licensed, not sold. Licensor retains all right, title,
+   and interest in and to the Software, including all intellectual property
+   rights therein. No rights are granted to You other than as expressly set
+   forth in this License.
+
+6. TERMINATION
+
+   This License terminates automatically, without notice, if You breach any
+   term of this License. Upon termination, You must cease all use of the
+   Software and destroy all copies in Your possession or control. Sections
+   3, 5, 7, and 8 survive termination.
+
+7. NO WARRANTY
+
+   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.
+
+8. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL LICENSOR 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.
+
+9. GOVERNING LAW
+
+   This License shall be governed by the laws of the jurisdiction in which
+   Quantum AI Partners is organized, without regard to conflict-of-law
+   principles. [Confirm jurisdiction/venue with counsel before relying on
+   this in a dispute.]
+
+---
+NOTE: This template was drafted to match your stated intent (restrict
+copying, require payment for commercial/profit-driven use) but has not been
+reviewed by an attorney. Have counsel review before relying on it in an
+actual dispute or before this repository accepts external contributions.

{constellation_node_sdk-1.0.1 → constellation_node_sdk-1.2.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: constellation-node-sdk
-Version: 1.0.1
+Version: 1.2.0
 Summary: L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory
 License: Proprietary
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn[standard]>=0.32.0
 Requires-Dist: pydantic>=2.9.0
@@ -14,12 +15,15 @@ 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: build>=1.2.0; 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: pytest-cov>=5.0.0; 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"
+Dynamic: license-file
 
 # Constellation Node SDK
 
@@ -58,6 +62,38 @@ For development:
 
 pip install -e ".[dev]"
 Quick start
+Application — calling Gate
+from constellation_node_sdk import GateClient, GateClientConfig
+
+client = GateClient(
+    GateClientConfig(
+        gate_url="https://gate.internal:8000",
+        local_node="erp",
+        timeout_seconds=30.0,
+    )
+)
+
+response = await client.execute(
+    action="converge",
+    payload={"entity": {"id": "org-4711"}},
+    tenant="tenant-a",
+    idempotency_key="erp:enrichment:run-4711",
+    timeout_ms=25_000,
+)
+That is the whole outbound integration. The application supplies business
+inputs; the SDK owns packet construction, the Gate destination, the deadline,
+transport idempotency, signing, HTTP, response validation, and typed failures.
+An application never builds a TransportPacket. See docs/gate-client.md and
+examples/application_client/.
+
+Gate → worker (Constellation.Gate only)
+After Gate resolves a worker, the transport to it is SDK-owned as well, through
+constellation_node_sdk.gate_authority. That surface is deliberately absent from
+the package root and from the gate package: it is not part of an application
+integration, and it accepts only packets carrying Gate's own routing authority,
+so it cannot be used as a node-to-peer client. See
+docs/gate-authority-transport.md.
+
 Worker node
 from constellation_node_sdk import create_node_app, register_handler
 

{constellation_node_sdk-1.0.1 → constellation_node_sdk-1.2.0}/README.md

@@ -35,6 +35,38 @@ For development:
 
 pip install -e ".[dev]"
 Quick start
+Application — calling Gate
+from constellation_node_sdk import GateClient, GateClientConfig
+
+client = GateClient(
+    GateClientConfig(
+        gate_url="https://gate.internal:8000",
+        local_node="erp",
+        timeout_seconds=30.0,
+    )
+)
+
+response = await client.execute(
+    action="converge",
+    payload={"entity": {"id": "org-4711"}},
+    tenant="tenant-a",
+    idempotency_key="erp:enrichment:run-4711",
+    timeout_ms=25_000,
+)
+That is the whole outbound integration. The application supplies business
+inputs; the SDK owns packet construction, the Gate destination, the deadline,
+transport idempotency, signing, HTTP, response validation, and typed failures.
+An application never builds a TransportPacket. See docs/gate-client.md and
+examples/application_client/.
+
+Gate → worker (Constellation.Gate only)
+After Gate resolves a worker, the transport to it is SDK-owned as well, through
+constellation_node_sdk.gate_authority. That surface is deliberately absent from
+the package root and from the gate package: it is not part of an application
+integration, and it accepts only packets carrying Gate's own routing authority,
+so it cannot be used as a node-to-peer client. See
+docs/gate-authority-transport.md.
+
 Worker node
 from constellation_node_sdk import create_node_app, register_handler
 

{constellation_node_sdk-1.0.1 → constellation_node_sdk-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "constellation-node-sdk"
-version = "1.0.1"
+version = "1.2.0"
 description = "L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -23,9 +23,11 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+  "build>=1.2.0",
   "mypy>=1.11.0",
   "pytest>=8.3.0",
   "pytest-asyncio>=0.23.8",
+  "pytest-cov>=5.0.0",
   "ruff>=0.6.0",
   "types-PyYAML>=6.0.12",
   "types-requests",

{constellation_node_sdk-1.0.1 → constellation_node_sdk-1.2.0}/src/constellation_node_sdk/__init__.py

@@ -1,24 +1,43 @@
 from __future__ import annotations
 
 from constellation_node_sdk.gate import (
+    ADMISSION_ACTION,
+    ConsumerAccessReceipt,
+    GateAuthorizationError,
     GateClient,
     GateClientConfig,
+    GateClientError,
+    GateConfigurationError,
+    GateConnectionError,
+    GateHTTPError,
+    GatePolicyError,
     GateRegistrationConfig,
+    GateRegistrationError,
+    GateResponseError,
+    GateSecurityError,
+    GateTimeoutError,
+    NodeRegistration,
+    activate_consumer,
     assert_gate_only_destination,
     assert_local_node_identity,
     assert_node_origin_packet,
+    build_node_registration,
     build_registration_payload,
     get_gate_client_config_from_env,
     get_gate_registration_config_from_env,
     load_node_spec,
     register_from_env,
+    register_node,
     register_with_gate,
     validate_outbound_gate_packet,
 )
 from constellation_node_sdk.runtime import (
     LifecycleHook,
+    NodeParticipation,
     NodeRuntimeConfig,
     NoOpLifecycle,
+    ParticipationState,
+    ParticipationStatus,
     PreflightFailure,
     clear_handlers,
     create_error_transport_packet,
@@ -65,12 +84,29 @@ from constellation_node_sdk.transport import (
 )
 
 __all__ = [
+    "ADMISSION_ACTION",
+    "ConsumerAccessReceipt",
+    "GateAuthorizationError",
+    "NodeParticipation",
+    "ParticipationState",
+    "ParticipationStatus",
+    "activate_consumer",
     "DelegationLink",
     "GateClient",
     "GateClientConfig",
+    "GateClientError",
+    "GateConfigurationError",
+    "GateConnectionError",
+    "GateHTTPError",
+    "GatePolicyError",
     "GateRegistrationConfig",
+    "GateRegistrationError",
+    "GateResponseError",
+    "GateSecurityError",
+    "GateTimeoutError",
     "LifecycleHook",
     "NoOpLifecycle",
+    "NodeRegistration",
     "NodeRuntimeConfig",
     "PreflightFailure",
     "RoutingProvenance",
@@ -93,6 +129,7 @@ __all__ = [
     "assert_gate_only_destination",
     "assert_local_node_identity",
     "assert_node_origin_packet",
+    "build_node_registration",
     "build_registration_payload",
     "canonical_json",
     "clear_handlers",
@@ -111,6 +148,7 @@ __all__ = [
     "recompute_transport_core",
     "register_from_env",
     "register_handler",
+    "register_node",
     "register_with_gate",
     "registered_actions",
     "run_preflight",

constellation_node_sdk-1.2.0/src/constellation_node_sdk/_packet_http.py

@@ -0,0 +1,150 @@
+"""
+Canonical-packet HTTP machinery, shared by both sides of Gate.
+
+There is exactly one implementation of "POST a canonical packet and decode a
+canonical packet back". ``GateClient`` uses it for application → Gate, and the
+Gate-authority dispatch transport uses it for Gate → resolved worker.
+
+A second copy would be the real risk here: two implementations drift, and the
+one that drifts is whichever is exercised less. The two callers differ only in
+which exception types they raise, so the error classes are injected rather than
+the code being duplicated.
+
+This module is private. Nothing here is part of the public SDK surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+_MAX_BODY_CHARS = 2048
+
+
+@dataclass(frozen=True)
+class PacketTransportErrors:
+    """
+    The exception types one caller raises for each transport failure category.
+
+    ``timeout`` and ``http`` are constructed with keyword arguments
+    (``timeout_seconds``, ``status_code`` / ``response_text``); ``connection``
+    and ``response`` take a message alone.
+    """
+
+    # Exception *factories*, not plain classes: the timeout and http types take
+    # keyword arguments, which `type[Exception]` cannot express.
+    timeout: Callable[..., Exception]
+    connection: Callable[..., Exception]
+    http: Callable[..., Exception]
+    response: Callable[..., Exception]
+
+
+def describe_exception(exc: BaseException) -> str:
+    """
+    Render an exception with its type, never relying on ``str(exc)`` alone.
+
+    httpx timeout exceptions frequently stringify to ``""``. A consumer that
+    logged only the message recorded a blank failure reason in production, so
+    the type name is always carried.
+    """
+    detail = str(exc)
+    return f"{type(exc).__name__}: {detail}" if detail else type(exc).__name__
+
+
+async def post_packet_json(
+    *,
+    url: str,
+    json_body: dict[str, Any],
+    timeout_seconds: float,
+    errors: PacketTransportErrors,
+    what: str,
+    client: httpx.AsyncClient | None = None,
+    transport: httpx.AsyncBaseTransport | None = None,
+    headers: dict[str, str] | None = None,
+    params: dict[str, str] | None = None,
+) -> httpx.Response:
+    """
+    Perform exactly one POST and translate every httpx failure into a typed error.
+
+    There is no retry here, on either side of Gate. A failed request is returned
+    to the caller as a typed failure: replaying it is a decision that needs
+    semantic authority and a stable idempotency key, which transport does not
+    have.
+
+    When ``client`` is supplied the request reuses that client's connection
+    pool, and ``timeout_seconds`` is applied per request so a pooled client's
+    own default can never widen this call's deadline.
+    """
+    request_headers = {"Content-Type": "application/json"}
+    if headers:
+        request_headers.update(headers)
+
+    try:
+        if client is not None:
+            return await client.post(
+                url,
+                json=json_body,
+                headers=request_headers,
+                params=params,
+                timeout=timeout_seconds,
+            )
+        async with httpx.AsyncClient(timeout=timeout_seconds, transport=transport) as owned:
+            return await owned.post(
+                url,
+                json=json_body,
+                headers=request_headers,
+                params=params,
+            )
+    except httpx.TimeoutException as exc:
+        # Ordered before TransportError: httpx.TimeoutException subclasses it,
+        # so reversing these collapses "deadline elapsed" into "unreachable".
+        raise errors.timeout(
+            f"{what} did not respond within {timeout_seconds}s ({describe_exception(exc)})",
+            timeout_seconds=timeout_seconds,
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise errors.connection(
+            f"could not reach {what} at {url} ({describe_exception(exc)})"
+        ) from exc
+
+
+def raise_for_status(
+    response: httpx.Response,
+    *,
+    context: str,
+    errors: PacketTransportErrors,
+) -> None:
+    """Translate a non-success status into a typed error carrying the status."""
+    if response.is_success:
+        return
+    raise errors.http(
+        f"{context} returned HTTP {response.status_code}",
+        status_code=response.status_code,
+        response_text=response.text,
+    )
+
+
+def decode_packet_body(
+    response: httpx.Response,
+    *,
+    context: str,
+    errors: PacketTransportErrors,
+) -> dict[str, Any]:
+    """Decode a JSON object body, or raise the caller's response error type."""
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise errors.response(
+            f"{context} was not decodable JSON ({describe_exception(exc)})"
+        ) from exc
+    if not isinstance(body, dict):
+        raise errors.response(f"{context} must be a JSON object, got {type(body).__name__}")
+    return body
+
+
+def truncate_body(text: str | None) -> str | None:
+    """Bound a response body carried on an exception."""
+    return text[:_MAX_BODY_CHARS] if text is not None else None

{constellation_node_sdk-1.0.1 → constellation_node_sdk-1.2.0}/src/constellation_node_sdk/gate/__init__.py

@@ -1,6 +1,12 @@
 from __future__ import annotations
 
-from constellation_node_sdk.gate.client import GateClient
+from constellation_node_sdk.gate.admission import ADMISSION_ACTION, ConsumerAccessReceipt
+from constellation_node_sdk.gate.capabilities import (
+    CapabilityDescriptor,
+    CapabilityListResponse,
+)
+from constellation_node_sdk.gate.capability_client import GateCapabilityClient
+from constellation_node_sdk.gate.client import GateClient, activate_consumer
 from constellation_node_sdk.gate.config import (
     GateClientConfig,
     GateRegistrationConfig,
@@ -8,10 +14,16 @@ from constellation_node_sdk.gate.config import (
     get_gate_registration_config_from_env,
 )
 from constellation_node_sdk.gate.errors import (
+    GateAuthorizationError,
     GateClientError,
+    GateConfigurationError,
+    GateConnectionError,
+    GateHTTPError,
     GatePolicyError,
     GateRegistrationError,
     GateResponseError,
+    GateSecurityError,
+    GateTimeoutError,
 )
 from constellation_node_sdk.gate.policy import (
     assert_gate_only_destination,
@@ -20,28 +32,46 @@ from constellation_node_sdk.gate.policy import (
     validate_outbound_gate_packet,
 )
 from constellation_node_sdk.gate.registration import (
+    NodeRegistration,
+    build_node_registration,
     build_registration_payload,
     load_node_spec,
     register_from_env,
+    register_node,
     register_with_gate,
 )
 
 __all__ = [
+    "ADMISSION_ACTION",
+    "CapabilityDescriptor",
+    "CapabilityListResponse",
+    "ConsumerAccessReceipt",
+    "GateAuthorizationError",
+    "GateCapabilityClient",
     "GateClient",
     "GateClientConfig",
     "GateClientError",
+    "GateConfigurationError",
+    "GateConnectionError",
+    "GateHTTPError",
     "GatePolicyError",
     "GateRegistrationConfig",
     "GateRegistrationError",
     "GateResponseError",
+    "GateSecurityError",
+    "GateTimeoutError",
+    "NodeRegistration",
+    "activate_consumer",
     "assert_gate_only_destination",
     "assert_local_node_identity",
     "assert_node_origin_packet",
+    "build_node_registration",
     "build_registration_payload",
     "get_gate_client_config_from_env",
     "get_gate_registration_config_from_env",
     "load_node_spec",
     "register_from_env",
+    "register_node",
     "register_with_gate",
     "validate_outbound_gate_packet",
 ]

constellation_node_sdk-1.2.0/src/constellation_node_sdk/gate/admission.py

@@ -0,0 +1,81 @@
+"""
+Consumer admission: the client half of "configured -> admitted -> usable".
+
+Gate alone decides whether a signing key is admitted and which actions it may
+invoke (its verifying keyring and per-key action scopes). A consumer used to
+learn that only from a 403 on a real call. :meth:`GateClient.activate` asks Gate
+up front with a signed probe to ``POST /v1/admission`` and returns Gate's answer
+as a typed :class:`ConsumerAccessReceipt`. The SDK never grants anything.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .errors import GateResponseError
+
+#: Reserved action of the admission probe. Gate refuses it on /v1/execute and
+#: refuses any node that tries to register it.
+ADMISSION_ACTION = "gate.admission"
+ADMISSION_PATH = "/v1/admission"
+ADMISSION_SCHEMA = "l9.gate.admission.v1"
+
+
+class ConsumerAccessReceipt(BaseModel):
+    """Gate's answer to an admission probe, as seen by the consumer."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    gate_node: str
+    key_id: str | None
+    source_node: str
+    scope: Literal["restricted", "unrestricted"]
+    scoped_actions: tuple[str, ...] | None = None
+    granted_actions: tuple[str, ...] = Field(default_factory=tuple)
+    routable_actions: tuple[str, ...] = Field(default_factory=tuple)
+    required_actions: tuple[str, ...] = Field(default_factory=tuple)
+
+    @property
+    def missing_actions(self) -> tuple[str, ...]:
+        """Required actions Gate did not grant (empty when fully admitted)."""
+        granted = set(self.granted_actions)
+        return tuple(a for a in self.required_actions if a not in granted)
+
+    @property
+    def admitted(self) -> bool:
+        return not self.missing_actions
+
+    def permits(self, action: str) -> bool:
+        return action.strip().lower() in self.granted_actions
+
+
+def parse_admission_payload(
+    payload: dict[str, Any], *, required_actions: tuple[str, ...]
+) -> ConsumerAccessReceipt:
+    """Validate Gate's admission payload into a receipt, or raise GateResponseError."""
+    if payload.get("schema") != ADMISSION_SCHEMA:
+        raise GateResponseError(
+            f"Gate admission response has schema {payload.get('schema')!r}, "
+            f"expected {ADMISSION_SCHEMA!r}",
+            body=payload,
+        )
+    fields = {k: v for k, v in payload.items() if k != "schema"}
+    try:
+        return ConsumerAccessReceipt.model_validate(
+            {**fields, "required_actions": required_actions}
+        )
+    except ValidationError as exc:
+        raise GateResponseError(
+            f"Gate admission response is malformed: {exc}", body=payload
+        ) from exc
+
+
+__all__ = [
+    "ADMISSION_ACTION",
+    "ADMISSION_PATH",
+    "ADMISSION_SCHEMA",
+    "ConsumerAccessReceipt",
+    "parse_admission_payload",
+]