aevs 0.1.0__tar.gz

aevs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fetch.AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

aevs-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.1
+Name: aevs
+Version: 0.1.0
+Summary: Agent Execution Verification System — transparent audit SDK for AI agents
+Home-page: https://github.com/fetchai/AEVS-sdk
+License: MIT
+Keywords: ai,agents,verification,audit,langchain,mcp
+Author: Devendra Chauhan
+Author-email: devendra.chauhan@fetch.ai
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Provides-Extra: langchain
+Provides-Extra: mcp
+Requires-Dist: cryptography (>=43.0)
+Requires-Dist: httpx (>=0.27)
+Requires-Dist: langchain-core (>=0.2) ; extra == "langchain"
+Requires-Dist: mcp (>=1.20) ; extra == "mcp"
+Project-URL: Bug Tracker, https://github.com/fetchai/AEVS-sdk/issues
+Project-URL: Changelog, https://github.com/fetchai/AEVS-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/fetchai/AEVS-sdk#readme
+Project-URL: Repository, https://github.com/fetchai/AEVS-sdk
+Project-URL: Source, https://github.com/fetchai/AEVS-sdk
+Description-Content-Type: text/markdown
+
+# AEVS SDK
+
+Agent Execution Verification System — transparent audit SDK for AI agents.
+
+Intercepts tool calls from supported frameworks, builds tamper-evident receipts (HMAC-signed, hash-chained), and sends them to the AEVS backend. Zero changes to your agent code.
+
+## Compatibility
+
+- Python 3.10+
+- Framework adapters:
+  - `aevs[langchain]` for LangChain / LangGraph tool interception
+  - `aevs[mcp]` for MCP tool interception (requires `mcp>=1.20`)
+
+## Installation
+
+```bash
+pip install aevs
+```
+
+With framework extras:
+
+```bash
+pip install aevs[langchain]   # LangChain / LangGraph support
+pip install aevs[mcp]         # MCP tool support
+```
+
+## Quick Start
+
+```python
+import aevs
+
+aevs.configure(api_key="aevs_sk_<key_id>_<hex_secret>")
+aevs.enable()
+
+# Every tool call from this point is intercepted.
+# No changes to tools, agents, or LLM setup.
+```
+
+## API
+
+```python
+aevs.configure(api_key=..., **options)   # Set configuration (required before enable)
+aevs.enable()                            # Auto-detect frameworks and start intercepting
+aevs.enable(frameworks=["langchain"])    # Or specify explicitly
+aevs.disable()                           # Unpatch all frameworks, restore originals
+aevs.flush()                             # Force-send buffered receipts to backend
+aevs.get_session_id()                    # UUID minted at enable(); stamped on every receipt
+aevs.is_healthy()                        # False after sustained buffer write failures
+```
+
+### Configuration Options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *(required)* | SDK key from customer creation (`aevs_sk_<id>_<hex>`) |
+| `agent_id` | `None` | Agent UUID to tag receipts with |
+| `base_url` | `https://api.aevs.fetch.ai/v1` | AEVS backend URL |
+| `signing_timeout_ms` | `2000` | HTTP timeout for receipt submission |
+| `float_handling` | `"decimal_string"` | How floats are serialized (`decimal_string` or `raise`) |
+| `float_precision` | `6` | Decimal places for float serialization |
+| `max_payload_bytes` | `1048576` | Max receipt payload size (1 MB) |
+| `buffer_path` | `~/.aevs/buffer.db` | SQLite buffer file path |
+| `max_buffer_records` | `10000` | Max buffered receipts before eviction |
+| `drain_interval_ms` | `5000` | Background flush interval |
+| `max_reference_entries` | `1000` | Reference ID registry capacity |
+
+### Reference IDs
+
+Every intercepted tool call gets a `reference_id` (UUID v4) embedded in its receipt. The SDK keeps these in a bounded FIFO registry.
+
+```python
+response = await agent.ainvoke({"messages": [("user", query)]})
+refs = aevs.get_reference_ids(clear=True)
+# [{"seq": 1, "tool_name": "search", "reference_id": "abc-...", "run_id": "def-..."}, ...]
+```
+
+Verify any `reference_id` via the public backend endpoint (no auth required):
+
+```
+GET /v1/receipts/verify/{reference_id}
+```
+
+### Reference ID Registry
+
+```python
+aevs.get_reference_id(run_id)       # Lookup by framework run_id
+aevs.get_reference_ids(clear=True)  # Get all entries, then clear
+aevs.clear_reference_ids()          # Drop all entries
+```
+
+### Session IDs
+
+Each `enable()` mints a fresh UUIDv4 **session id**. The id is stamped
+on every receipt produced in that session and participates in the hash
+chain anchor — two SDK processes that share an API key cannot fork the
+chain by construction.
+
+```python
+aevs.enable()
+session = aevs.get_session_id()
+# "5db7d195-f84c-4f90-ae12-d74d001d3f9d"
+
+aevs.disable()
+aevs.get_session_id()
+# None
+```
+
+Useful for log correlation: every receipt carries `session_id`, so
+filtering receipts by session in the AEVS backend isolates a single
+SDK run.
+
+## Data & privacy
+
+AEVS receipts may include **tool inputs and outputs**, which can contain secrets or PII depending
+on what your tools return (e.g. prompts, retrieved documents, API responses).
+
+- Receipts are buffered locally in an encrypted SQLite database (default `~/.aevs/buffer.db`).
+- Receipts are submitted to the AEVS backend over HTTPS by default (`base_url`).
+
+You are responsible for ensuring your tool layer does not emit sensitive data you cannot store or
+transmit. If needed, redact at the tool boundary (before data reaches the agent runtime).
+
+## Threat model / non-goals
+
+- AEVS is **tamper-evident**, not tamper-proof. It helps detect modification/reordering of receipts
+  after the fact; it does not secure a fully compromised host process.
+- The SDK signs requests with a key derived from your API key secret; protect the API key like any
+  other credential.
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [Poetry](https://python-poetry.org/)
+
+### Setup
+
+```bash
+git clone https://github.com/fetchai/AEVS-sdk.git && cd AEVS-sdk
+make install   # poetry install --all-extras
+```
+
+### Common commands
+
+The `Makefile` wraps the everyday workflow. Run `make help` to see the
+full list.
+
+```bash
+make test        # run the test suite
+make test-cov    # tests with coverage (HTML report in ./htmlcov)
+make lint        # ruff check
+make format      # ruff format + auto-fix
+make typecheck   # mypy --strict on src/
+make check       # lint + typecheck + tests (the CI gate)
+make build       # build sdist + wheel into ./dist
+```
+
+You can still call the underlying tools directly:
+
+```bash
+poetry run pytest tests/test_integration.py -v
+poetry run ruff check src/ tests/
+poetry run mypy src/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide — branch
+naming, Conventional Commits, the PR checklist, and release flow.
+
+## Reporting Security Issues
+
+Please **do not** open a public GitHub issue for security problems.
+See [SECURITY.md](SECURITY.md) for the disclosure process.
+
+## Architecture
+
+```
+Agent (LangChain / MCP)
+  │
+  ▼  tool call intercepted
+ReceiptBuilder  ──▶  HMAC sign + hash chain
+  │
+  ▼
+LocalBuffer (SQLite, encrypted at rest)
+  │
+  ▼  background drainer
+AEVSClient  ──▶  POST /v1/receipts  ──▶  AEVS Backend
+```
+
+- **Interception**: Framework-specific patches capture tool inputs/outputs
+- **Signing**: Each receipt is HMAC-signed (HKDF-derived keys) with a hash chain linking sequential calls
+- **Buffering**: Receipts are encrypted and stored locally in SQLite, flushed in the background
+- **Resilience**: Buffer survives process restarts; flush retries on transient failures
+
+## Project Structure
+
+```
+aevs-sdk/
+├── src/aevs/
+│   ├── __init__.py        Public API (configure, enable, disable, flush)
+│   ├── _api.py            Core state management, enable/disable, flush
+│   ├── _drainer.py        Background flush of buffered receipts
+│   ├── _version.py        Package version
+│   ├── config.py          Configuration dataclass + validation
+│   ├── exceptions.py      SDK exception types
+│   ├── adapters/          Framework-specific interceptors
+│   │   ├── base.py        Base adapter interface
+│   │   ├── langchain.py   LangChain / LangGraph interceptor
+│   │   └── mcp.py         MCP tool interceptor
+│   ├── core/
+│   │   ├── buffer.py      Encrypted SQLite local buffer
+│   │   ├── client.py      HTTP client (sync + async)
+│   │   ├── receipt.py     ReceiptBuilder — HMAC, hash chain
+│   │   ├── serializer.py  Canonical JSON serialization
+│   │   ├── signer.py      Request signing (HKDF + HMAC)
+│   │   └── types.py       Typed payload shapes
+│   └── crypto/
+│       ├── chain.py       Hash chain helpers
+│       ├── hkdf.py        HKDF key derivation
+│       └── hmac_auth.py   HMAC authentication
+├── tests/                 Test suite
+├── pyproject.toml         Poetry packaging + tool config
+├── poetry.lock
+├── LICENSE
+└── README.md
+```
+

aevs-0.1.0/README.md

@@ -0,0 +1,228 @@
+# AEVS SDK
+
+Agent Execution Verification System — transparent audit SDK for AI agents.
+
+Intercepts tool calls from supported frameworks, builds tamper-evident receipts (HMAC-signed, hash-chained), and sends them to the AEVS backend. Zero changes to your agent code.
+
+## Compatibility
+
+- Python 3.10+
+- Framework adapters:
+  - `aevs[langchain]` for LangChain / LangGraph tool interception
+  - `aevs[mcp]` for MCP tool interception (requires `mcp>=1.20`)
+
+## Installation
+
+```bash
+pip install aevs
+```
+
+With framework extras:
+
+```bash
+pip install aevs[langchain]   # LangChain / LangGraph support
+pip install aevs[mcp]         # MCP tool support
+```
+
+## Quick Start
+
+```python
+import aevs
+
+aevs.configure(api_key="aevs_sk_<key_id>_<hex_secret>")
+aevs.enable()
+
+# Every tool call from this point is intercepted.
+# No changes to tools, agents, or LLM setup.
+```
+
+## API
+
+```python
+aevs.configure(api_key=..., **options)   # Set configuration (required before enable)
+aevs.enable()                            # Auto-detect frameworks and start intercepting
+aevs.enable(frameworks=["langchain"])    # Or specify explicitly
+aevs.disable()                           # Unpatch all frameworks, restore originals
+aevs.flush()                             # Force-send buffered receipts to backend
+aevs.get_session_id()                    # UUID minted at enable(); stamped on every receipt
+aevs.is_healthy()                        # False after sustained buffer write failures
+```
+
+### Configuration Options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *(required)* | SDK key from customer creation (`aevs_sk_<id>_<hex>`) |
+| `agent_id` | `None` | Agent UUID to tag receipts with |
+| `base_url` | `https://api.aevs.fetch.ai/v1` | AEVS backend URL |
+| `signing_timeout_ms` | `2000` | HTTP timeout for receipt submission |
+| `float_handling` | `"decimal_string"` | How floats are serialized (`decimal_string` or `raise`) |
+| `float_precision` | `6` | Decimal places for float serialization |
+| `max_payload_bytes` | `1048576` | Max receipt payload size (1 MB) |
+| `buffer_path` | `~/.aevs/buffer.db` | SQLite buffer file path |
+| `max_buffer_records` | `10000` | Max buffered receipts before eviction |
+| `drain_interval_ms` | `5000` | Background flush interval |
+| `max_reference_entries` | `1000` | Reference ID registry capacity |
+
+### Reference IDs
+
+Every intercepted tool call gets a `reference_id` (UUID v4) embedded in its receipt. The SDK keeps these in a bounded FIFO registry.
+
+```python
+response = await agent.ainvoke({"messages": [("user", query)]})
+refs = aevs.get_reference_ids(clear=True)
+# [{"seq": 1, "tool_name": "search", "reference_id": "abc-...", "run_id": "def-..."}, ...]
+```
+
+Verify any `reference_id` via the public backend endpoint (no auth required):
+
+```
+GET /v1/receipts/verify/{reference_id}
+```
+
+### Reference ID Registry
+
+```python
+aevs.get_reference_id(run_id)       # Lookup by framework run_id
+aevs.get_reference_ids(clear=True)  # Get all entries, then clear
+aevs.clear_reference_ids()          # Drop all entries
+```
+
+### Session IDs
+
+Each `enable()` mints a fresh UUIDv4 **session id**. The id is stamped
+on every receipt produced in that session and participates in the hash
+chain anchor — two SDK processes that share an API key cannot fork the
+chain by construction.
+
+```python
+aevs.enable()
+session = aevs.get_session_id()
+# "5db7d195-f84c-4f90-ae12-d74d001d3f9d"
+
+aevs.disable()
+aevs.get_session_id()
+# None
+```
+
+Useful for log correlation: every receipt carries `session_id`, so
+filtering receipts by session in the AEVS backend isolates a single
+SDK run.
+
+## Data & privacy
+
+AEVS receipts may include **tool inputs and outputs**, which can contain secrets or PII depending
+on what your tools return (e.g. prompts, retrieved documents, API responses).
+
+- Receipts are buffered locally in an encrypted SQLite database (default `~/.aevs/buffer.db`).
+- Receipts are submitted to the AEVS backend over HTTPS by default (`base_url`).
+
+You are responsible for ensuring your tool layer does not emit sensitive data you cannot store or
+transmit. If needed, redact at the tool boundary (before data reaches the agent runtime).
+
+## Threat model / non-goals
+
+- AEVS is **tamper-evident**, not tamper-proof. It helps detect modification/reordering of receipts
+  after the fact; it does not secure a fully compromised host process.
+- The SDK signs requests with a key derived from your API key secret; protect the API key like any
+  other credential.
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [Poetry](https://python-poetry.org/)
+
+### Setup
+
+```bash
+git clone https://github.com/fetchai/AEVS-sdk.git && cd AEVS-sdk
+make install   # poetry install --all-extras
+```
+
+### Common commands
+
+The `Makefile` wraps the everyday workflow. Run `make help` to see the
+full list.
+
+```bash
+make test        # run the test suite
+make test-cov    # tests with coverage (HTML report in ./htmlcov)
+make lint        # ruff check
+make format      # ruff format + auto-fix
+make typecheck   # mypy --strict on src/
+make check       # lint + typecheck + tests (the CI gate)
+make build       # build sdist + wheel into ./dist
+```
+
+You can still call the underlying tools directly:
+
+```bash
+poetry run pytest tests/test_integration.py -v
+poetry run ruff check src/ tests/
+poetry run mypy src/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide — branch
+naming, Conventional Commits, the PR checklist, and release flow.
+
+## Reporting Security Issues
+
+Please **do not** open a public GitHub issue for security problems.
+See [SECURITY.md](SECURITY.md) for the disclosure process.
+
+## Architecture
+
+```
+Agent (LangChain / MCP)
+  │
+  ▼  tool call intercepted
+ReceiptBuilder  ──▶  HMAC sign + hash chain
+  │
+  ▼
+LocalBuffer (SQLite, encrypted at rest)
+  │
+  ▼  background drainer
+AEVSClient  ──▶  POST /v1/receipts  ──▶  AEVS Backend
+```
+
+- **Interception**: Framework-specific patches capture tool inputs/outputs
+- **Signing**: Each receipt is HMAC-signed (HKDF-derived keys) with a hash chain linking sequential calls
+- **Buffering**: Receipts are encrypted and stored locally in SQLite, flushed in the background
+- **Resilience**: Buffer survives process restarts; flush retries on transient failures
+
+## Project Structure
+
+```
+aevs-sdk/
+├── src/aevs/
+│   ├── __init__.py        Public API (configure, enable, disable, flush)
+│   ├── _api.py            Core state management, enable/disable, flush
+│   ├── _drainer.py        Background flush of buffered receipts
+│   ├── _version.py        Package version
+│   ├── config.py          Configuration dataclass + validation
+│   ├── exceptions.py      SDK exception types
+│   ├── adapters/          Framework-specific interceptors
+│   │   ├── base.py        Base adapter interface
+│   │   ├── langchain.py   LangChain / LangGraph interceptor
+│   │   └── mcp.py         MCP tool interceptor
+│   ├── core/
+│   │   ├── buffer.py      Encrypted SQLite local buffer
+│   │   ├── client.py      HTTP client (sync + async)
+│   │   ├── receipt.py     ReceiptBuilder — HMAC, hash chain
+│   │   ├── serializer.py  Canonical JSON serialization
+│   │   ├── signer.py      Request signing (HKDF + HMAC)
+│   │   └── types.py       Typed payload shapes
+│   └── crypto/
+│       ├── chain.py       Hash chain helpers
+│       ├── hkdf.py        HKDF key derivation
+│       └── hmac_auth.py   HMAC authentication
+├── tests/                 Test suite
+├── pyproject.toml         Poetry packaging + tool config
+├── poetry.lock
+├── LICENSE
+└── README.md
+```

aevs-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[tool.poetry]
+name = "aevs"
+version = "0.1.0"
+description = "Agent Execution Verification System — transparent audit SDK for AI agents"
+readme = "README.md"
+license = "MIT"
+authors = [
+    "Devendra Chauhan <devendra.chauhan@fetch.ai>",
+    "Mehul Gaidhani <mehul.gaidhani@fetch.ai>",
+]
+homepage = "https://github.com/fetchai/AEVS-sdk"
+repository = "https://github.com/fetchai/AEVS-sdk"
+packages = [{include = "aevs", from = "src"}]
+keywords = ["ai", "agents", "verification", "audit", "langchain", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT 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",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/fetchai/AEVS-sdk/issues"
+"Changelog" = "https://github.com/fetchai/AEVS-sdk/blob/main/CHANGELOG.md"
+"Documentation" = "https://github.com/fetchai/AEVS-sdk#readme"
+"Source" = "https://github.com/fetchai/AEVS-sdk"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+httpx = ">=0.27"
+cryptography = ">=43.0"
+mcp = {version = ">=1.20", optional = true}
+langchain-core = {version = ">=0.2", optional = true}
+
+[tool.poetry.extras]
+langchain = ["langchain-core"]
+mcp = ["mcp"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+pytest-asyncio = ">=0.23"
+pytest-cov = ">=5.0"
+ruff = ">=0.4"
+mypy = ">=1.10"
+respx = ">=0.21"
+langchain-core = ">=0.2"
+mcp = ">=1.20"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+# Import `aevs` from ./src so `pytest` matches `PYTHONPATH=src` (avoids stale site-packages).
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

aevs-0.1.0/src/aevs/__init__.py

@@ -0,0 +1,99 @@
+from aevs._version import __version__
+from aevs.config import AEVSConfig, configure, reset_config
+from aevs.exceptions import (
+    AEVSAuthError,
+    AEVSBufferError,
+    AEVSConfigError,
+    AEVSError,
+    AEVSSerializationError,
+)
+
+__all__ = [
+    "__version__",
+    "AEVSAuthError",
+    "AEVSBufferError",
+    "AEVSConfig",
+    "AEVSConfigError",
+    "AEVSError",
+    "AEVSSerializationError",
+    "clear_reference_ids",
+    "configure",
+    "disable",
+    "enable",
+    "flush",
+    "get_reference_id",
+    "get_reference_ids",
+    "get_session_id",
+    "is_healthy",
+    "reset_config",
+]
+
+
+def enable(*, frameworks: list[str] | None = None) -> None:
+    """Detect installed frameworks and patch them to intercept tool calls."""
+    from aevs._api import enable as _enable
+
+    _enable(frameworks=frameworks)
+
+
+def disable() -> None:
+    """Unpatch all frameworks, restore original behavior."""
+    from aevs._api import disable as _disable
+
+    _disable()
+
+
+def flush() -> None:
+    """Force-send all buffered receipts to the backend."""
+    from aevs._api import flush as _flush
+
+    _flush()
+
+
+def is_healthy(*, threshold: int = 3) -> bool:
+    """Return ``False`` when the receipt buffer has had *threshold* or more
+    consecutive write failures — indicating a sustained storage problem.
+
+    Safe to call at any time; never raises.
+    """
+    from aevs._api import is_healthy as _is_healthy
+
+    return _is_healthy(threshold=threshold)
+
+
+def get_reference_id(lookup_id: str) -> str | None:
+    """Return the AEVS reference_id for a run_id or tool_call_id."""
+    from aevs._api import get_reference_id as _get
+
+    return _get(lookup_id)
+
+
+def get_reference_ids(*, clear: bool = False) -> list[dict[str, str | int | None]]:
+    """Return all reference entries recorded since the last clear.
+
+    Pass ``clear=True`` to empty the registry after reading (recommended
+    for per-request web applications).
+    """
+    from aevs._api import get_reference_ids as _get
+
+    return _get(clear=clear)
+
+
+def clear_reference_ids() -> None:
+    """Drop all stored reference entries."""
+    from aevs._api import clear_reference_ids as _clear
+
+    _clear()
+
+
+def get_session_id() -> str | None:
+    """Return the active AEVS session UUID, or ``None`` when disabled.
+
+    A new UUIDv4 is minted on each ``enable()`` (or recovered from the
+    buffer on mid-session crash recovery).  Useful for log correlation —
+    every receipt in the session carries this id and the chain anchor
+    is derived from it.
+    """
+    from aevs._api import get_session_id as _get
+
+    return _get()