Metadata-Version: 2.4
Name: g8e
Version: 2.1.2
Summary: g8e Protocol Constants and Models
Author: Lateralus Labs, LLC
License: BUSL-1.1
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 :: Other/Proprietary 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
Requires-Dist: PyNaCl>=1.5.0
Provides-Extra: dev
Requires-Dist: grpcio-tools==1.83.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"

# g8e

Python protocol library for the g8e zero-trust execution platform. Provides generated protobuf messages and type stubs, protocol constants, dynamic enums, Pydantic models, and canonical receipt verification for building g8e-compatible clients and services.

## Installation

Requires Python 3.10 or later. Runtime dependencies are `pydantic>=2.0.0`, `protobuf>=4.0.0`, and `PyNaCl>=1.5.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. An empty value is treated as unset so a stray `G8E_PROTOCOL_DIR=` line in `.env` cannot shadow the bundled constants. The loader checks this variable first, then the bundled `g8e/_data/` directory included in PyPI installs (the production/container path). There are no dev-mode fallbacks — developers running from a source checkout must set `G8E_PROTOCOL_DIR` explicitly or install the package so the bundled `_data/` is present. If no constants file is found at the resolved path, `_load_protocol_json` raises `ProtocolConstantsError` at import time rather than returning an empty dict and letting downstream code fail with an opaque `KeyError`.

#### Accessor Functions

The module provides typed accessor functions that resolve constant keys to their wire values:

- **`collection(name)`**: collection wire value (e.g. `collection("cases")`)
- **`channel(name)`**: channel wire value
- **`intent(name)`**: intent wire value
- **`prompt(name)`**: prompt section wire value
- **`kv_key(name, **kwargs)`**: formatted KV key with placeholder substitution (e.g. `kv_key("SessionWeb", **{"session.type": "web", "session.id": "abc"})`)
- **`kv_session_type(name)`**: session type wire value

The `kv_key()` function uses regex substitution to handle dotted placeholder names like `{session.type}` in KV key templates.

### 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`.

In addition to STATUS-derived enums, the module generates enums from other constant categories:

- **`g8e.enums.Channel`**: from `channels.json`
- **`g8e.enums.Intent`**: from `intents.json`
- **`g8e.enums.Prompt`**: from `prompts.json`
- **`g8e.enums.Collection`**: from `collections.json`
- **`g8e.enums.KVKey`**: from `kv_keys.json`

### 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`, and `ValidationError`.
- **`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`) with factory methods `from_session_event()` and `from_background_event()` for construction from event type + data. AI event payload models for chat processing, processing stopped, response chunks, response completion, tool lifecycle, citations, errors, thinking, turn completion, retry, and triage clarification.
- **`g8e/models/internal_api.py`**: `ChatMessageRequest`, `ChatStartedResponse`, and `ResourceCreationRequest` for internal API interactions. `ChatMessageRequest` inherits from `LLMOverrides`, which provides 12 optional LLM provider/model/endpoint override fields.
- **`g8e/models/settings.py`**: `G8eeUserSettings`, `PlatformSettings`, and nested settings models for LLM providers, search, eval judge, command validation, and batch execution.
- **`g8e/models/governance.py`**: `GovernanceEnvelope`, `GovernanceMetadata`, `GovernanceL1`, `GovernanceL2`, `GovernanceL2Vote`, `GovernanceL3`, `GovernanceL3Proof`, and `compute_transaction_hash()`. The `GovernanceEnvelope` model mirrors the canonical wire format for all mutations. `compute_transaction_hash()` produces a deterministic SHA-256 over pipe-delimited canonical fields.

### Generated Protobuf Messages

The `g8e.common.v1`, `g8e.operator.v1`, and `g8e.pubsub.v1` packages contain generated `_pb2.py` runtime modules and matching `_pb2.pyi` type stubs. They expose the same canonical messages as the Go protocol, including `ActionReceipt`, `DeterministicStageEvidence`, `ReceiptPersistenceAttestation`, and `CommitmentAttestation`. The generated files are committed and checked against their `.proto` sources in CI.

### Receipt Verification

The `g8e.receipts` module provides strict protojson parsing and canonical cross-language verification:

- `parse_action_receipt()` parses a mapping into the generated `ActionReceipt` and rejects unknown fields.
- `action_receipt_to_dict()` serializes with canonical protobuf field and enum names.
- `canonicalize_action_receipt()` reproduces the exact bytes signed by the Go actuator, including the deterministic stage evidence hash.
- `verify_action_receipt_signature()` verifies the Ed25519 receipt signature using a raw, hexadecimal, or SPKI PEM public key.
- `canonicalize_receipt_persistence_attestation()` and `verify_receipt_persistence_attestation()` verify the final signed durable-persistence binding.

The verification helpers establish signature validity against the public key supplied by the caller. They do not establish an attested trust path for that key; consumers obtain the actuator public key through a trusted out-of-band channel.

### 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, HTTP header string constants, and accessor functions (`collection()`, `channel()`, `intent()`, `prompt()`, `kv_key()`, `kv_session_type()`).
- **`g8e/enums.py`**: Dynamic `StrEnum` and `IntEnum` generation from `STATUS`, `EVENTS`, and other constant categories (channels, intents, prompts, collections, kv_keys).
- **`g8e/common/v1/`, `g8e/operator/v1/`, `g8e/pubsub/v1/`**: Generated protobuf runtime modules and PEP 561-compatible `.pyi` stubs.
- **`g8e/models/`**: Pydantic v2 models for protocol data structures, SSE events, internal API requests, user settings, and governance envelopes.
- **`g8e/receipts.py`**: Canonical receipt parsing, serialization, Ed25519 signature verification, and persistence-attestation verification.

## 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

Business Source License 1.1 (BSL 1.1). Converts to Apache 2.0 on 2030-08-18. 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
