orchestrata_ultimate.cxp

Reference › orchestrata_ultimate › cxp › init

The public facade of the Cross-agent eXchange Protocol package (Spec 004). It defines no classes of its own and re-exports the package's public surface from its modules, so callers can import from orchestrata_ultimate.cxp: the constants, exceptions, interfaces and types; the serializers (json_serializer, binary_serializer, serializer); validator, headers, payload and priority; the trackers in delivery_status and work_status; router, dispatcher and prolog_bridge; threads; the adapters (postman_adapter, session_adapter); and the version modules. The transport modules (transport and below) are imported from their own modules. See cxp.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

No public API: the module defines no classes, functions or constants.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/cxp/__init__.py

"""
Cross-agent eXchange Protocol (CXP) Implementation.

CXP is the structured communication protocol used by Volks
for agent-to-agent communication in Orchestrata.

Module structure:
  Core:
    (packet vocabulary — CXPPacket, enums, results, compat — moved to
     Layer 0: orchestrata_ultimate.core.packet; import it from there)
    types.py           - Extended types (ThreadMetadata, RoutingResult, VOLK_ALIASES)
    constants.py       - Protocol constants and limits
    exceptions.py      - CXP exception hierarchy
    interfaces.py      - Protocol interfaces (IPacket, ISerializer, etc.)

  Header/Payload:
    headers.py         - Header extraction and validation
    payload.py         - Payload handling (JSON/binary)

  State Machines:
    delivery_status.py - Delivery state machine tracking
    work_status.py     - Work state machine tracking

  Serialization:
    json_serializer.py   - JSON serialization
    binary_serializer.py - Binary (MessagePack) serialization
    serializer.py        - Legacy serializer (wraps CXPPacket.to_dict/from_dict)

  Validation:
    validator.py       - Rule-based validation
    schema.py          - JSON schema definitions

  Threading:
    threads.py         - Thread management
    thread_store.py    - Thread persistence

  Versioning:
    version.py         - Protocol versioning
    version_compat.py  - Version compatibility checking

  Priority:
    priority.py        - Priority ordering and policies

  Integration:
    prolog_bridge.py   - Prolog integration (cxp_packet/12)
    postman_adapter.py - Postman queue adapter
    session_adapter.py - Session context adapter
    router.py          - CXP packet routing
    dispatcher.py      - CXP packet dispatching

  Legacy:
    handler.py         - Legacy handler (superseded by router+dispatcher)
"""

from orchestrata_ultimate.cxp.binary_serializer import BinarySerializer

# Constants
from orchestrata_ultimate.cxp.constants import (
    DEFAULT_RETRY_DELAY_SECONDS,
    MAX_DELIVERY_ATTEMPTS,
    PAYLOAD_MAX_BYTES,
    PERF_BINARY_SERIALIZE_MS,
    PERF_HEADER_EXTRACT_MS,
    PERF_JSON_SERIALIZE_MS,
    PERF_THREAD_LOOKUP_MS,
    PERF_VALIDATION_MS,
    PRIORITY_MAX,
    PRIORITY_MIN,
    PROTOCOL_NAME,
    PROTOCOL_VERSION,
    SEMVER_PATTERN,
    SEMVER_REGEX,
    SUBJECT_MAX_LENGTH,
    THREAD_MAX_MESSAGES,
    TTL_DEFAULT_SECONDS,
    TTL_MAX_SECONDS,
    TTL_MIN_SECONDS,
    UUID_PATTERN,
    UUID_REGEX,
    VOLK_ALIAS_PATTERN,
    VOLK_ALIAS_REGEX,
)

# State Machines
from orchestrata_ultimate.cxp.delivery_status import (
    DeliveryTracker,
    validate_delivery_transition,
)
from orchestrata_ultimate.cxp.dispatcher import CXPDispatcher

# Exceptions
from orchestrata_ultimate.cxp.exceptions import (
    CXPError,
    DeliveryError,
    DeliveryTimeoutError,
    DeserializationError,
    FieldValidationError,
    InvalidPacketError,
    MaxRetriesExceededError,
    NoRouteError,
    PrologBridgeError,
    RoutingError,
    SchemaValidationError,
    SerializationError,
    StateTransitionError,
    ThreadClosedError,
    ThreadError,
    ThreadNotFoundError,
)
from orchestrata_ultimate.cxp.exceptions import ValidationError as CXPValidationError

# Legacy components
from orchestrata_ultimate.cxp.handler import CXPHandler

# Header/Payload
from orchestrata_ultimate.cxp.headers import (
    HeaderManager,
    extract_headers,
    validate_subject,
    validate_uuid,
    validate_volk_alias,
)

# Interfaces
from orchestrata_ultimate.cxp.interfaces import (
    IDeliveryTracker,
    IPacket,
    IPrologBridge,
    ISerializer,
    IThreadManager,
    IValidator,
)

# Serialization
from orchestrata_ultimate.cxp.json_serializer import JSONSerializer

# Core packet and enums: moved to Layer 0 (K6). Import CXPPacket, the
# packet enums, transition tables, and result dataclasses from
# orchestrata_ultimate.core.packet — this facade no longer re-exports them.
# Payload
from orchestrata_ultimate.cxp.payload import (
    BINARY_MAX_BYTES,
    JSON_MAX_BYTES,
    PayloadManager,
)
from orchestrata_ultimate.cxp.postman_adapter import PostmanAdapter

# Priority
from orchestrata_ultimate.cxp.priority import (
    DEFAULT_PRIORITIES,
    PRIORITY_NAMES,
    PriorityManager,
)

# Integration
from orchestrata_ultimate.cxp.prolog_bridge import PrologBridge
from orchestrata_ultimate.cxp.router import CXPRouter

# Validation
from orchestrata_ultimate.cxp.schema import CXP_PACKET_SCHEMA, SchemaRegistry
from orchestrata_ultimate.cxp.serializer import CXPSerializer
from orchestrata_ultimate.cxp.session_adapter import SessionAdapter
from orchestrata_ultimate.cxp.thread_store import ThreadStore

# Threading
from orchestrata_ultimate.cxp.threads import ThreadManager

# Types
from orchestrata_ultimate.cxp.types import (
    VOLK_ALIASES,
    VOLK_ROLES,
    RoutingDecision,
    RoutingResult,
    ThreadMetadata,
    ThreadStatus,
)
from orchestrata_ultimate.cxp.validator import CXPValidator

# Versioning
from orchestrata_ultimate.cxp.version import (
    CURRENT_VERSION,
    ProtocolVersion,
    parse_version,
)
from orchestrata_ultimate.cxp.version_compat import CompatibilityResult, VersionChecker
from orchestrata_ultimate.cxp.work_status import WorkTracker, validate_work_transition

__all__ = [
    # Legacy
    "CXPHandler",
    "CXPSerializer",
    "CXPValidator",
    # Types
    "ThreadMetadata",
    "ThreadStatus",
    "RoutingResult",
    "RoutingDecision",
    "VOLK_ALIASES",
    "VOLK_ROLES",
    # Constants
    "PROTOCOL_VERSION",
    "PROTOCOL_NAME",
    "UUID_PATTERN",
    "UUID_REGEX",
    "SEMVER_PATTERN",
    "SEMVER_REGEX",
    "VOLK_ALIAS_PATTERN",
    "VOLK_ALIAS_REGEX",
    "SUBJECT_MAX_LENGTH",
    "PAYLOAD_MAX_BYTES",
    "THREAD_MAX_MESSAGES",
    "PRIORITY_MIN",
    "PRIORITY_MAX",
    "TTL_DEFAULT_SECONDS",
    "TTL_MIN_SECONDS",
    "TTL_MAX_SECONDS",
    "MAX_DELIVERY_ATTEMPTS",
    "DEFAULT_RETRY_DELAY_SECONDS",
    "PERF_HEADER_EXTRACT_MS",
    "PERF_JSON_SERIALIZE_MS",
    "PERF_BINARY_SERIALIZE_MS",
    "PERF_VALIDATION_MS",
    "PERF_THREAD_LOOKUP_MS",
    # Exceptions
    "CXPError",
    "InvalidPacketError",
    "SerializationError",
    "DeserializationError",
    "CXPValidationError",
    "FieldValidationError",
    "SchemaValidationError",
    "DeliveryError",
    "DeliveryTimeoutError",
    "MaxRetriesExceededError",
    "RoutingError",
    "NoRouteError",
    "ThreadError",
    "ThreadNotFoundError",
    "ThreadClosedError",
    "StateTransitionError",
    "PrologBridgeError",
    # Interfaces
    "IPacket",
    "ISerializer",
    "IValidator",
    "IThreadManager",
    "IDeliveryTracker",
    "IPrologBridge",
    # Header/Payload
    "HeaderManager",
    "extract_headers",
    "validate_volk_alias",
    "validate_uuid",
    "validate_subject",
    "PayloadManager",
    "JSON_MAX_BYTES",
    "BINARY_MAX_BYTES",
    # State Machines
    "DeliveryTracker",
    "validate_delivery_transition",
    "WorkTracker",
    "validate_work_transition",
    # Serialization
    "JSONSerializer",
    "BinarySerializer",
    # Validation
    "SchemaRegistry",
    "CXP_PACKET_SCHEMA",
    # Threading
    "ThreadManager",
    "ThreadStore",
    # Priority
    "PriorityManager",
    "PRIORITY_NAMES",
    "DEFAULT_PRIORITIES",
    # Versioning
    "ProtocolVersion",
    "CURRENT_VERSION",
    "parse_version",
    "CompatibilityResult",
    "VersionChecker",
    # Integration
    "PrologBridge",
    "PostmanAdapter",
    "SessionAdapter",
    "CXPRouter",
    "CXPDispatcher",
]