g8e 1.4.1__tar.gz

g8e-1.4.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: g8e
+Version: 1.4.1
+Summary: g8e Protocol Constants and Models
+Author: Lateralus Labs, LLC
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/g8e-ai/g8e
+Project-URL: Repository, https://github.com/g8e-ai/g8e
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: protobuf>=4.0.0
+
+# g8e
+
+Python protocol library for the g8e zero-trust execution platform. Provides protocol constants, dynamic enums, and Pydantic models for building g8e-compatible clients and services.
+
+## Installation
+
+Requires Python 3.10 or later. Dependencies are `pydantic>=2.0.0` and `protobuf>=4.0.0`.
+
+```bash
+pip install g8e
+```
+
+## Usage
+
+### Constants
+
+The `g8e.constants` module loads JSON protocol constants from `protocol/constants/` at import time. It exports dicts for events, status, collections, headers, channels, pubsub, intents, prompts, timestamps, document IDs, platform configuration, agents, network, API paths, key-value keys, and sender identifiers. The module also exports the `ComponentName` `StrEnum` and individual HTTP header string constants for session, context, and g8e-specific headers.
+
+Set the `G8E_PROTOCOL_DIR` environment variable to override the default protocol directory resolution. The loader checks this variable first, then falls back to the relative path from the package, then to `/app/protocol/constants` for containerized environments.
+
+### Enums
+
+The `g8e.enums` module dynamically generates `StrEnum` and `IntEnum` classes from the `STATUS` and `EVENTS` protocol constants. Enum member names use SCREAMING_SNAKE_CASE; values preserve the raw protocol wire format. Integer-valued categories produce `IntEnum`; all others produce `StrEnum`. Access enums by PascalCase name via attribute lookup, for example `g8e.enums.OperatorToolName` or `g8e.enums.EventType`.
+
+### Models
+
+The `g8e.models` package provides Pydantic v2 models for protocol data structures. All models extend `G8eBaseModel`, which configures `populate_by_name` and `extra="ignore"`, and defaults `exclude_none` on serialization. The `UTCDatetime` annotated type serializes datetimes to ISO 8601 with a `Z` suffix.
+
+- **`g8e/models/base.py`**: `G8eBaseModel`, `UTCDatetime`, and re-exports of Pydantic `Field`, `ConfigDict`, `field_validator`, `model_validator`.
+- **`g8e/models/context.py`**: `RequestContext` and `BoundOperator`. `RequestContext` validates session identity for `CLIENT` source components, requiring either `web_session_id` or `cli_session_id` and a `user_id`.
+- **`g8e/models/events.py`**: SSE wire models (`SessionEventWire`, `BackgroundEventWire`) and AI event payload models for chat processing, tool lifecycle, citations, errors, thinking, turn completion, retry, and triage clarification.
+- **`g8e/models/internal_api.py`**: `ChatMessageRequest`, `ChatStartedResponse`, and `ResourceCreationRequest` for internal API interactions.
+- **`g8e/models/settings.py`**: `G8eeUserSettings`, `PlatformSettings`, and nested settings models for LLM providers, search, eval judge, command validation, and batch execution.
+
+### Examples
+
+Working examples are in `protocol/python/examples/`. Run `constants_example.py` for constants and headers usage, or `models_example.py` for model instantiation, serialization, and validation.
+
+## Components
+
+- **`g8e/constants.py`**: Runtime loader for JSON protocol constants from `protocol/constants/`. Exports dict constants, `ComponentName` enum, and HTTP header string constants.
+- **`g8e/enums.py`**: Dynamic `StrEnum` and `IntEnum` generation from `STATUS` and `EVENTS` protocol constants.
+- **`g8e/models/`**: Pydantic v2 models for protocol data structures, SSE events, internal API requests, and user settings.
+
+## Protocol Versioning
+
+This package follows semantic versioning. Major version changes indicate breaking protocol changes. Minor version changes add new protocol features. Patch version changes include bug fixes and non-breaking enhancements.
+
+## License
+
+Apache License 2.0. See `protocol/LICENSE` for details.
+
+## Contributing
+
+Protocol changes require coordination across all g8e components. Submit protocol change proposals via GitHub issues with clear justification and impact analysis.
+
+## Support
+
+For protocol questions and support, open a GitHub issue or visit https://github.com/g8e-ai/g8e

g8e-1.4.1/README.md

@@ -0,0 +1,59 @@
+# g8e
+
+Python protocol library for the g8e zero-trust execution platform. Provides protocol constants, dynamic enums, and Pydantic models for building g8e-compatible clients and services.
+
+## Installation
+
+Requires Python 3.10 or later. Dependencies are `pydantic>=2.0.0` and `protobuf>=4.0.0`.
+
+```bash
+pip install g8e
+```
+
+## Usage
+
+### Constants
+
+The `g8e.constants` module loads JSON protocol constants from `protocol/constants/` at import time. It exports dicts for events, status, collections, headers, channels, pubsub, intents, prompts, timestamps, document IDs, platform configuration, agents, network, API paths, key-value keys, and sender identifiers. The module also exports the `ComponentName` `StrEnum` and individual HTTP header string constants for session, context, and g8e-specific headers.
+
+Set the `G8E_PROTOCOL_DIR` environment variable to override the default protocol directory resolution. The loader checks this variable first, then falls back to the relative path from the package, then to `/app/protocol/constants` for containerized environments.
+
+### Enums
+
+The `g8e.enums` module dynamically generates `StrEnum` and `IntEnum` classes from the `STATUS` and `EVENTS` protocol constants. Enum member names use SCREAMING_SNAKE_CASE; values preserve the raw protocol wire format. Integer-valued categories produce `IntEnum`; all others produce `StrEnum`. Access enums by PascalCase name via attribute lookup, for example `g8e.enums.OperatorToolName` or `g8e.enums.EventType`.
+
+### Models
+
+The `g8e.models` package provides Pydantic v2 models for protocol data structures. All models extend `G8eBaseModel`, which configures `populate_by_name` and `extra="ignore"`, and defaults `exclude_none` on serialization. The `UTCDatetime` annotated type serializes datetimes to ISO 8601 with a `Z` suffix.
+
+- **`g8e/models/base.py`**: `G8eBaseModel`, `UTCDatetime`, and re-exports of Pydantic `Field`, `ConfigDict`, `field_validator`, `model_validator`.
+- **`g8e/models/context.py`**: `RequestContext` and `BoundOperator`. `RequestContext` validates session identity for `CLIENT` source components, requiring either `web_session_id` or `cli_session_id` and a `user_id`.
+- **`g8e/models/events.py`**: SSE wire models (`SessionEventWire`, `BackgroundEventWire`) and AI event payload models for chat processing, tool lifecycle, citations, errors, thinking, turn completion, retry, and triage clarification.
+- **`g8e/models/internal_api.py`**: `ChatMessageRequest`, `ChatStartedResponse`, and `ResourceCreationRequest` for internal API interactions.
+- **`g8e/models/settings.py`**: `G8eeUserSettings`, `PlatformSettings`, and nested settings models for LLM providers, search, eval judge, command validation, and batch execution.
+
+### Examples
+
+Working examples are in `protocol/python/examples/`. Run `constants_example.py` for constants and headers usage, or `models_example.py` for model instantiation, serialization, and validation.
+
+## Components
+
+- **`g8e/constants.py`**: Runtime loader for JSON protocol constants from `protocol/constants/`. Exports dict constants, `ComponentName` enum, and HTTP header string constants.
+- **`g8e/enums.py`**: Dynamic `StrEnum` and `IntEnum` generation from `STATUS` and `EVENTS` protocol constants.
+- **`g8e/models/`**: Pydantic v2 models for protocol data structures, SSE events, internal API requests, and user settings.
+
+## Protocol Versioning
+
+This package follows semantic versioning. Major version changes indicate breaking protocol changes. Minor version changes add new protocol features. Patch version changes include bug fixes and non-breaking enhancements.
+
+## License
+
+Apache License 2.0. See `protocol/LICENSE` for details.
+
+## Contributing
+
+Protocol changes require coordination across all g8e components. Submit protocol change proposals via GitHub issues with clear justification and impact analysis.
+
+## Support
+
+For protocol questions and support, open a GitHub issue or visit https://github.com/g8e-ai/g8e

g8e-1.4.1/g8e/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = "1.4.1"

g8e-1.4.1/g8e/constants.py

@@ -0,0 +1,125 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+# Protocol Constants Loader for Python
+# Provides a single entry point for protocol constants shared across components.
+
+logger = logging.getLogger(__name__)
+
+def _get_protocol_dir() -> Path:
+    """Find the protocol directory."""
+    # 1. Check environment variable
+    if "G8E_PROTOCOL_DIR" in os.environ:
+        return Path(os.environ["G8E_PROTOCOL_DIR"]) / "constants"
+    
+    # 2. Check relative to this file
+    # protocol/python/g8e/constants.py -> protocol/constants
+    rel_path = Path(__file__).parent.parent.parent / "constants"
+    if rel_path.exists():
+        return rel_path
+    
+    # 3. Fallback for containerized environments
+    container_path = Path("/app/protocol/constants")
+    if container_path.exists():
+        return container_path
+    
+    return Path("./protocol/constants")
+
+_PROTOCOL_CONSTANTS_DIR = _get_protocol_dir()
+
+def _load_protocol_json(filename: str) -> dict[str, Any]:
+    path = _PROTOCOL_CONSTANTS_DIR / filename
+    if not path.exists():
+        logger.warning("Protocol JSON %s not found at %s", filename, path)
+        return {}
+
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+# Exported constants
+EVENTS = _load_protocol_json("events.json")
+STATUS = _load_protocol_json("status.json")
+MSG = _load_protocol_json("senders.json")
+COLLECTIONS = _load_protocol_json("collections.json")
+KV = _load_protocol_json("kv_keys.json")
+CHANNELS = _load_protocol_json("channels.json")
+PUBSUB = _load_protocol_json("pubsub.json")
+INTENTS = _load_protocol_json("intents.json")
+PROMPTS = _load_protocol_json("prompts.json")
+TIMESTAMP = _load_protocol_json("timestamp.json")
+HEADERS = _load_protocol_json("headers.json")
+DOCUMENT_IDS = _load_protocol_json("document_ids.json")
+PLATFORM = _load_protocol_json("platform.json")
+AGENTS = _load_protocol_json("agents.json")
+NETWORK = _load_protocol_json("network.json")
+API_PATHS = _load_protocol_json("api_paths.json")
+
+from enum import StrEnum
+
+# Helper to get Component names (formerly ComponentName enum)
+class ComponentName(StrEnum):
+    CLIENT = "client"
+    G8EE = "g8ee"
+    G8EO = "g8eo"
+    OPERATOR = "g8eo" # Alias
+
+# Headers from g8ee/app/constants/headers.py
+HTTP_ACCEL_BUFFERING_HEADER = "X-Accel-Buffering"
+HTTP_ACCEPT_HEADER = "Accept"
+HTTP_ACCEPT_LANGUAGE_HEADER = "Accept-Language"
+HTTP_ACCESS_CONTROL_ALLOW_CREDENTIALS = "Access-Control-Allow-Credentials"
+HTTP_ACCESS_CONTROL_ALLOW_ORIGIN = "Access-Control-Allow-Origin"
+HTTP_ACCESS_CONTROL_REQUEST_HEADERS = "Access-Control-Request-Headers"
+HTTP_ACCESS_CONTROL_REQUEST_METHOD = "Access-Control-Request-Method"
+HTTP_API_KEY_HEADER = "X-API-Key"
+HTTP_AUTHORIZATION_HEADER = "Authorization"
+HTTP_BEARER_PREFIX = "Bearer"
+HTTP_CACHE_CONTROL_HEADER = "Cache-Control"
+HTTP_CONTENT_LANGUAGE_HEADER = "Content-Language"
+HTTP_CONTENT_TYPE_HEADER = "Content-Type"
+HTTP_COOKIE_HEADER = "Cookie"
+HTTP_FORWARDED_FOR_HEADER = "X-Forwarded-For"
+HTTP_LAST_EVENT_ID_HEADER = "Last-Event-ID"
+HTTP_PRAGMA_HEADER = "Pragma"
+HTTP_REQUESTED_WITH_HEADER = "X-Requested-With"
+HTTP_SET_COOKIE_HEADER = "Set-Cookie"
+HTTP_USER_AGENT_HEADER = "User-Agent"
+HTTP_G8E_CLIENT_HEADER = "X-G8E-Client"
+HTTP_G8E_OPERATOR_STATUS_HEADER = "X-G8E-Operator-Status"
+HTTP_G8E_SYSTEM_FINGERPRINT_HEADER = "X-G8E-System-Fingerprint"
+HTTP_G8E_SERVICE_HEADER = "X-G8E-Service"
+
+# Session Headers
+WEB_SESSION_ID_HEADER = "X-G8E-Web-Session-ID"
+CLI_SESSION_ID_HEADER = "X-G8E-CLI-Session-ID"
+OPERATOR_ID_HEADER = "X-G8E-Operator-ID"
+OPERATOR_API_KEY_HEADER = "X-G8E-Operator-API-Key"
+
+# Context Headers
+PROXY_ORGANIZATION_ID_HEADER = "X-Proxy-Organization-Id"
+PROXY_USER_EMAIL_HEADER = "X-Proxy-User-Email"
+PROXY_USER_ID_HEADER = "X-Proxy-User-Id"
+CASE_ID_HEADER = "X-G8E-Case-ID"
+USER_ID_HEADER = "X-G8E-User-ID"
+ORGANIZATION_ID_HEADER = "X-G8E-Organization-ID"
+INVESTIGATION_ID_HEADER = "X-G8E-Investigation-ID"
+TASK_ID_HEADER = "X-G8E-Task-ID"
+BOUND_OPERATORS_HEADER = "X-G8E-Bound-Operators"
+EXECUTION_ID_HEADER = "X-G8E-Request-ID"
+COMPONENT_NAME_HEADER = "X-G8E-Source-Component"

g8e-1.4.1/g8e/enums.py

@@ -0,0 +1,136 @@
+"""Dynamic enum generation from protocol constants.
+
+Generates Python ``StrEnum`` / ``IntEnum`` classes from the ``STATUS`` and
+``EVENTS`` dicts in :mod:`g8e.constants`, so downstream consumers (g8ee,
+evals, CLI) can use typed enums instead of raw string lookups.
+
+Categories whose values are integer-like produce ``IntEnum``; all others
+produce ``StrEnum``.
+
+Enum **member names** are SCREAMING_SNAKE_CASE (derived from the JSON
+``_python_const`` or PascalCase event keys).  Enum **values** preserve
+the raw protocol wire format (e.g. ``"g8e.v1.ai.llm.chat.iteration.thinking.started"``,
+``"user.cancelled"``, ``"G8E-1000"``) so they round-trip exactly to
+Go/protobuf/JVM consumers.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum, IntEnum
+from functools import lru_cache
+
+from g8e.constants import STATUS, EVENTS
+
+
+# Categories that use integer values
+_INT_CATEGORIES: frozenset[str] = frozenset({
+    "citation_layout",
+    "priority",
+    "scrubber_priority",
+    "severity",
+    "slash_tier",
+})
+
+
+def _to_pascal(snake: str) -> str:
+    """Convert snake_case to PascalCase, handling dotted names."""
+    parts = snake.replace(".", "_").split("_")
+    return "".join(p.capitalize() for p in parts)
+
+
+def _pascal_to_screaming_snake(name: str) -> str:
+    """Convert PascalCase to SCREAMING_SNAKE_CASE.
+
+    Handles consecutive capitals: ``AiLLMChat`` -> ``AI_LLM_CHAT``,
+    ``G8eActionType`` -> ``G8E_ACTION_TYPE``.
+    """
+    s = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", name)
+    s = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "_", s)
+    s = re.sub(r"(?<=[a-z])(?=[0-9])", "_", s)
+    return s.upper()
+
+
+@lru_cache(maxsize=None)
+def _build_enum(cat_name: str) -> type:
+    """Build an enum class from a STATUS category."""
+    cat_vals = STATUS["status"][cat_name]
+
+    # Determine base class
+    sample_val = next(iter(cat_vals.values()))["value"]
+    is_int = isinstance(sample_val, (int,)) or (
+        isinstance(sample_val, str) and sample_val.lstrip("-").isdigit()
+    )
+    base = IntEnum if (is_int or cat_name in _INT_CATEGORIES) else StrEnum
+
+    # Build members
+    members: dict[str, str | int] = {}
+    for _key, meta in cat_vals.items():
+        py_name = meta["_python_const"]
+        raw_val = meta["value"]
+        if base is IntEnum:
+            members[py_name] = int(raw_val)
+        else:
+            members[py_name] = str(raw_val)
+
+    cls_name = _to_pascal(cat_name)
+    cls = base(cls_name, members)  # type: ignore[arg-type]
+    return cls
+
+
+@lru_cache(maxsize=None)
+def _build_event_type_enum() -> type:
+    """Build the EventType enum from the EVENTS dict.
+
+    Event keys are PascalCase (e.g. ``AiLLMChatIterationStarted``).
+    Member names are SCREAMING_SNAKE_CASE; values preserve the raw
+    protocol wire format (e.g. ``g8e.v1.ai.llm.chat.iteration.started``).
+    """
+    evts = EVENTS.get("events", {})
+    members: dict[str, str] = {}
+    for key, meta in evts.items():
+        member_name = _pascal_to_screaming_snake(key)
+        members[member_name] = meta["value"]
+
+    return StrEnum("EventType", members)  # type: ignore[arg-type]
+
+
+def _to_snake(pascal: str) -> str:
+    """Convert PascalCase to snake_case, handling consecutive capitals.
+
+    e.g. AISource -> ai_source, G8eActionType -> g8e_action_type,
+         ApprovalErrorType -> approval_error_type
+    """
+    # Insert _ before each uppercase that follows a lowercase or digit,
+    # and before each uppercase that precedes a lowercase
+    s = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", pascal)
+    s = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "_", s)
+    return s.lower()
+
+
+def __getattr__(name: str):
+    """Dynamic attribute access: g8e.enums.OperatorToolName, EventType, etc."""
+    if name == "EventType":
+        return _build_event_type_enum()
+
+    snake = _to_snake(name)
+    if snake in STATUS["status"]:
+        return _build_enum(snake)
+
+    # Try dotted-name conversion (e.g. ApprovalErrorType -> approval.error.type)
+    for cat in STATUS["status"]:
+        pascal = _to_pascal(cat)
+        if pascal == name:
+            return _build_enum(cat)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """List all available enum class names."""
+    names = [_to_pascal(cat) for cat in STATUS["status"]]
+    names.append("EventType")
+    return names
+
+
+__all__ = [_to_pascal(cat) for cat in STATUS["status"]] + ["EventType"]

g8e-1.4.1/g8e/models/__init__.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .base import G8eBaseModel, UTCDatetime, Field, ConfigDict
+from .context import RequestContext, BoundOperator
+from .internal_api import (
+    ResourceCreationRequest,
+    ChatMessageRequest,
+    ChatStartedResponse,
+)
+from .settings import G8eeUserSettings, PlatformSettings
+from .events import (
+    SessionEventWire,
+    BackgroundEventWire,
+    AiProcessingStoppedPayload,
+    AIToolLifecyclePayload,
+    ChatCitationsReadyPayload,
+    ChatErrorPayload,
+    ChatProcessingStartedPayload,
+    ChatResponseChunkPayload,
+    ChatResponseCompletePayload,
+    ChatRetryPayload,
+    ChatThinkingPayload,
+    ChatTurnCompletePayload,
+    TriageClarificationQuestionsPayload,
+)
+
+__all__ = [
+    "G8eBaseModel",
+    "UTCDatetime",
+    "Field",
+    "ConfigDict",
+    "RequestContext",
+    "BoundOperator",
+    "ResourceCreationRequest",
+    "ChatMessageRequest",
+    "ChatStartedResponse",
+    "G8eeUserSettings",
+    "PlatformSettings",
+    "SessionEventWire",
+    "BackgroundEventWire",
+    "AiProcessingStoppedPayload",
+    "AIToolLifecyclePayload",
+    "ChatCitationsReadyPayload",
+    "ChatErrorPayload",
+    "ChatProcessingStartedPayload",
+    "ChatResponseChunkPayload",
+    "ChatResponseCompletePayload",
+    "ChatRetryPayload",
+    "ChatThinkingPayload",
+    "ChatTurnCompletePayload",
+    "TriageClarificationQuestionsPayload",
+]

g8e-1.4.1/g8e/models/base.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datetime import UTC, datetime
+from typing import Any, Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, PlainSerializer, ValidationError, field_validator, model_validator
+
+__all__ = [
+    "ConfigDict",
+    "Field",
+    "G8eBaseModel",
+    "UTCDatetime",
+    "ValidationError",
+    "field_validator",
+    "model_validator",
+]
+
+def _to_iso_z(dt: datetime) -> str:
+    """Serialize a datetime to ISO 8601 with Z suffix (UTC canonical form)."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    else:
+        dt = dt.astimezone(UTC)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S") + (f".{dt.microsecond:06d}" if dt.microsecond else "") + "Z"
+
+UTCDatetime = Annotated[
+    datetime,
+    PlainSerializer(lambda dt: _to_iso_z(dt) if dt else None, return_type=str | None, when_used="json"),
+]
+
+class G8eBaseModel(BaseModel):
+    """Base model for all g8e domain objects in the protocol package."""
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+    )
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        kwargs.setdefault("exclude_none", True)
+        return super().model_dump(**kwargs)
+
+    def model_dump_json(self, **kwargs: Any) -> str:
+        kwargs.setdefault("exclude_none", True)
+        return super().model_dump_json(**kwargs)

g8e-1.4.1/g8e/models/context.py

@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .base import G8eBaseModel, Field, model_validator
+from ..constants import ComponentName
+
+class BoundOperator(G8eBaseModel):
+    """Represents a bound Operator in the protocol context."""
+    operator_id: str = Field(..., description="Unique Operator identifier")
+    operator_session_id: str | None = Field(default=None, description="Operator session identifier")
+    bound_web_session_id: str | None = Field(default=None, description="Web session ID this Operator is bound to")
+    status: str | None = Field(default=None, description="Operator status")
+
+class RequestContext(G8eBaseModel):
+    """Request context embedded in request bodies instead of headers.
+    
+    Stabilized protocol version of the RequestContext model.
+    """
+    web_session_id: str | None = Field(
+        default=None,
+        description="Web user session ID"
+    )
+    cli_session_id: str | None = Field(
+        default=None,
+        description="CLI session ID"
+    )
+    user_id: str | None = Field(
+        default=None,
+        description="User identifier"
+    )
+    organization_id: str | None = Field(
+        default=None,
+        description="Organization identifier"
+    )
+    case_id: str | None = Field(
+        default=None,
+        description="Current case ID"
+    )
+    investigation_id: str | None = Field(
+        default=None,
+        description="Current investigation ID"
+    )
+    task_id: str | None = Field(
+        default=None,
+        description="Current task ID"
+    )
+    bound_operators: list[BoundOperator] = Field(
+        default_factory=list,
+        description="List of all bound operators"
+    )
+    execution_id: str | None = Field(
+        default=None,
+        description="Unique execution identifier"
+    )
+    source_component: str = Field(
+        description="Component that created this context"
+    )
+    system_fingerprint: str | None = Field(
+        default=None,
+        description="System fingerprint of the caller"
+    )
+
+    @model_validator(mode="after")
+    def validate_session_identity(self):
+        """Basic validation of session identity."""
+        if self.source_component == ComponentName.CLIENT:
+            if self.web_session_id and self.cli_session_id:
+                raise ValueError("Context cannot have both web_session_id and cli_session_id")
+            
+            if not self.web_session_id and not self.cli_session_id:
+                raise ValueError("Context must have either web_session_id or cli_session_id for CLIENT source")
+            if not self.user_id:
+                raise ValueError("user_id is required for CLIENT source")
+        return self

g8e-1.4.1/g8e/models/events.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any
+from .base import G8eBaseModel, UTCDatetime
+
+class _SSEEventBody(G8eBaseModel):
+    type: str
+    data: dict[str, Any]
+
+class SessionEventWire(G8eBaseModel):
+    web_session_id: str | None = None
+    cli_session_id: str | None = None
+    user_id: str
+    event: _SSEEventBody
+
+class BackgroundEventWire(G8eBaseModel):
+    user_id: str
+    event: _SSEEventBody
+
+# AI SSE event payloads (Wire shapes)
+class AiProcessingStoppedPayload(G8eBaseModel):
+    reason: str
+    timestamp: UTCDatetime
+
+class AIToolLifecyclePayload(G8eBaseModel):
+    tool_name: str
+    display_label: str | None = None
+    display_icon: str | None = None
+    display_detail: str | None = None
+    category: str | None = None
+    execution_id: str
+    status: str
+    query: str | None = None
+    content: str | None = None
+    results: list[dict[str, Any]] | None = None
+    error: str | None = None
+    port: str | None = None
+    host: str | None = None
+    is_open: bool | None = None
+    timestamp: str | None = None
+
+class ChatCitationsReadyPayload(G8eBaseModel):
+    grounding_metadata: dict[str, Any]
+    timestamp: str | None = None
+
+class ChatErrorPayload(G8eBaseModel):
+    error: str
+    timestamp: str | None = None
+
+class ChatProcessingStartedPayload(G8eBaseModel):
+    agent_mode: str
+    timestamp: str | None = None
+
+class ChatResponseChunkPayload(G8eBaseModel):
+    content: str
+    timestamp: str | None = None
+
+class ChatResponseCompletePayload(G8eBaseModel):
+    content: str
+    finish_reason: str
+    has_citations: bool
+    grounding_metadata: dict[str, Any]
+    token_usage: dict[str, Any]
+    agent_mode: str
+    timestamp: str | None = None
+
+class ChatRetryPayload(G8eBaseModel):
+    attempt: int
+    max_attempts: int
+    timestamp: str | None = None
+
+class ChatThinkingPayload(G8eBaseModel):
+    thinking: str | None
+    action_type: str
+    timestamp: str | None = None
+
+class ChatTurnCompletePayload(G8eBaseModel):
+    turn: int
+    timestamp: str | None = None
+
+class TriageClarificationQuestionsPayload(G8eBaseModel):
+    questions: list[str]
+    complexity: str
+    complexity_confidence: str
+    intent: str
+    intent_confidence: str
+    intent_summary: str
+    request_posture: str
+    posture_confidence: str

g8e-1.4.1/g8e/models/internal_api.py

@@ -0,0 +1,47 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any
+from .base import G8eBaseModel, Field
+from .context import RequestContext
+
+class ResourceCreationRequest(G8eBaseModel):
+    """Typed request to create new case and investigation resources."""
+    create_case: bool = Field(default=False)
+    case_title: str | None = Field(default=None)
+
+class ChatMessageRequest(G8eBaseModel):
+    """Request model for chat messages."""
+    context: RequestContext = Field(...)
+    message: str = Field(...)
+    attachments: list[dict[str, Any]] | None = Field(default_factory=list)
+    sentinel_mode: bool = Field(default=True)
+    resource_creation: ResourceCreationRequest | None = Field(default=None)
+    llm_primary_provider: str | None = Field(default=None)
+    llm_assistant_provider: str | None = Field(default=None)
+    llm_lite_provider: str | None = Field(default=None)
+    llm_primary_model: str | None = Field(default=None)
+    llm_assistant_model: str | None = Field(default=None)
+    llm_lite_model: str | None = Field(default=None)
+    llm_primary_api_key: str | None = Field(default=None)
+    llm_primary_endpoint: str | None = Field(default=None)
+    llm_assistant_api_key: str | None = Field(default=None)
+    llm_assistant_endpoint: str | None = Field(default=None)
+    llm_lite_api_key: str | None = Field(default=None)
+    llm_lite_endpoint: str | None = Field(default=None)
+
+class ChatStartedResponse(G8eBaseModel):
+    """Response for POST /chat."""
+    success: bool
+    case_id: str
+    investigation_id: str

g8e-1.4.1/g8e/models/settings.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .base import G8eBaseModel, Field, ConfigDict
+
+class SearchSettings(G8eBaseModel):
+    """Unified search configuration."""
+    enabled: bool = Field(False)
+    project_id: str | None = Field(None)
+    engine_id: str | None = Field(None)
+    location: str = Field("global")
+    api_key: str | None = Field(None)
+
+class EvalJudgeSettings(G8eBaseModel):
+    """Evaluation judge configuration."""
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+    )
+    model: str | None = Field(None, alias="eval_judge_model")
+    max_output_tokens: int = Field(4096, alias="eval_judge_max_tokens")
+
+class CommandValidationSettings(G8eBaseModel):
+    """Operator command safety and validation configuration."""
+    enable_whitelisting: bool = Field(False)
+    whitelisted_commands: str = Field("")
+    enable_blacklisting: bool = Field(True)
+
+class BatchExecutionSettings(G8eBaseModel):
+    """Batch execution configuration for Operator tools."""
+    max_concurrency: int = Field(10, ge=1, le=64)
+    fail_fast: bool = Field(False)
+
+class LLMSettings(G8eBaseModel):
+    """LLM provider configuration."""
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+    )
+    primary_provider: str | None = Field(default=None, alias="llm_primary_provider")
+    assistant_provider: str | None = Field(default=None, alias="llm_assistant_provider")
+    lite_provider: str | None = Field(default=None, alias="llm_lite_provider")
+    primary_model: str | None = Field(default=None, alias="llm_model")
+    assistant_model: str | None = Field(default=None, alias="llm_assistant_model")
+    lite_model: str | None = Field(default=None, alias="llm_lite_model")
+    primary_api_key: str | None = Field(default=None)
+    primary_endpoint: str | None = Field(default=None)
+    assistant_api_key: str | None = Field(default=None)
+    assistant_endpoint: str | None = Field(default=None)
+    lite_api_key: str | None = Field(default=None)
+    lite_endpoint: str | None = Field(default=None)
+
+class PlatformSettings(G8eBaseModel):
+    """Platform governance and feature configuration."""
+    governance_enabled: bool = Field(True)
+    l1_doctrine_enabled: bool = Field(True)
+    l2_consensus_enabled: bool = Field(True)
+    l3_notary_enabled: bool = Field(True)
+    audit_enabled: bool = Field(True)
+    sentinel_enabled: bool = Field(True)
+
+class G8eeUserSettings(G8eBaseModel):
+    """Per-user settings for g8ee Engine."""
+    llm: LLMSettings
+    search: SearchSettings = Field(default_factory=SearchSettings)
+    eval_judge: EvalJudgeSettings = Field(default_factory=EvalJudgeSettings)
+    command_validation: CommandValidationSettings = Field(default_factory=CommandValidationSettings)
+    batch_execution: BatchExecutionSettings = Field(default_factory=BatchExecutionSettings)

g8e-1.4.1/g8e.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: g8e
+Version: 1.4.1
+Summary: g8e Protocol Constants and Models
+Author: Lateralus Labs, LLC
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/g8e-ai/g8e
+Project-URL: Repository, https://github.com/g8e-ai/g8e
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: protobuf>=4.0.0
+
+# g8e
+
+Python protocol library for the g8e zero-trust execution platform. Provides protocol constants, dynamic enums, and Pydantic models for building g8e-compatible clients and services.
+
+## Installation
+
+Requires Python 3.10 or later. Dependencies are `pydantic>=2.0.0` and `protobuf>=4.0.0`.
+
+```bash
+pip install g8e
+```
+
+## Usage
+
+### Constants
+
+The `g8e.constants` module loads JSON protocol constants from `protocol/constants/` at import time. It exports dicts for events, status, collections, headers, channels, pubsub, intents, prompts, timestamps, document IDs, platform configuration, agents, network, API paths, key-value keys, and sender identifiers. The module also exports the `ComponentName` `StrEnum` and individual HTTP header string constants for session, context, and g8e-specific headers.
+
+Set the `G8E_PROTOCOL_DIR` environment variable to override the default protocol directory resolution. The loader checks this variable first, then falls back to the relative path from the package, then to `/app/protocol/constants` for containerized environments.
+
+### Enums
+
+The `g8e.enums` module dynamically generates `StrEnum` and `IntEnum` classes from the `STATUS` and `EVENTS` protocol constants. Enum member names use SCREAMING_SNAKE_CASE; values preserve the raw protocol wire format. Integer-valued categories produce `IntEnum`; all others produce `StrEnum`. Access enums by PascalCase name via attribute lookup, for example `g8e.enums.OperatorToolName` or `g8e.enums.EventType`.
+
+### Models
+
+The `g8e.models` package provides Pydantic v2 models for protocol data structures. All models extend `G8eBaseModel`, which configures `populate_by_name` and `extra="ignore"`, and defaults `exclude_none` on serialization. The `UTCDatetime` annotated type serializes datetimes to ISO 8601 with a `Z` suffix.
+
+- **`g8e/models/base.py`**: `G8eBaseModel`, `UTCDatetime`, and re-exports of Pydantic `Field`, `ConfigDict`, `field_validator`, `model_validator`.
+- **`g8e/models/context.py`**: `RequestContext` and `BoundOperator`. `RequestContext` validates session identity for `CLIENT` source components, requiring either `web_session_id` or `cli_session_id` and a `user_id`.
+- **`g8e/models/events.py`**: SSE wire models (`SessionEventWire`, `BackgroundEventWire`) and AI event payload models for chat processing, tool lifecycle, citations, errors, thinking, turn completion, retry, and triage clarification.
+- **`g8e/models/internal_api.py`**: `ChatMessageRequest`, `ChatStartedResponse`, and `ResourceCreationRequest` for internal API interactions.
+- **`g8e/models/settings.py`**: `G8eeUserSettings`, `PlatformSettings`, and nested settings models for LLM providers, search, eval judge, command validation, and batch execution.
+
+### Examples
+
+Working examples are in `protocol/python/examples/`. Run `constants_example.py` for constants and headers usage, or `models_example.py` for model instantiation, serialization, and validation.
+
+## Components
+
+- **`g8e/constants.py`**: Runtime loader for JSON protocol constants from `protocol/constants/`. Exports dict constants, `ComponentName` enum, and HTTP header string constants.
+- **`g8e/enums.py`**: Dynamic `StrEnum` and `IntEnum` generation from `STATUS` and `EVENTS` protocol constants.
+- **`g8e/models/`**: Pydantic v2 models for protocol data structures, SSE events, internal API requests, and user settings.
+
+## Protocol Versioning
+
+This package follows semantic versioning. Major version changes indicate breaking protocol changes. Minor version changes add new protocol features. Patch version changes include bug fixes and non-breaking enhancements.
+
+## License
+
+Apache License 2.0. See `protocol/LICENSE` for details.
+
+## Contributing
+
+Protocol changes require coordination across all g8e components. Submit protocol change proposals via GitHub issues with clear justification and impact analysis.
+
+## Support
+
+For protocol questions and support, open a GitHub issue or visit https://github.com/g8e-ai/g8e

g8e-1.4.1/g8e.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+g8e/__init__.py
+g8e/constants.py
+g8e/enums.py
+g8e.egg-info/PKG-INFO
+g8e.egg-info/SOURCES.txt
+g8e.egg-info/dependency_links.txt
+g8e.egg-info/requires.txt
+g8e.egg-info/top_level.txt
+g8e/models/__init__.py
+g8e/models/base.py
+g8e/models/context.py
+g8e/models/events.py
+g8e/models/internal_api.py
+g8e/models/settings.py

g8e-1.4.1/g8e.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

g8e-1.4.1/g8e.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pydantic>=2.0.0
+protobuf>=4.0.0

g8e-1.4.1/g8e.egg-info/top_level.txt

@@ -0,0 +1 @@
+g8e

g8e-1.4.1/pyproject.toml

@@ -0,0 +1,54 @@
+# Copyright (c) 2026 Lateralus Labs, LLC.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "g8e"
+version = "1.4.1"
+description = "g8e Protocol Constants and Models"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "Lateralus Labs, LLC"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+    "pydantic>=2.0.0",
+    "protobuf>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/g8e-ai/g8e"
+Repository = "https://github.com/g8e-ai/g8e"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["g8e*"]
+
+[tool.setuptools.package-data]
+g8e = ["*.json", "**/*.json"]

g8e-1.4.1/setup.cfg

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