aiops-enabler 0.1.0__tar.gz

aiops_enabler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyntra360hub
+
+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.

aiops_enabler-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: aiops-enabler
+Version: 0.1.0
+Summary: Python SDK for AiOps Enabler — instrument your AI agent's task lifecycle and ratings in 3 lines of code.
+Author: AiOps Enabler
+License: MIT
+Project-URL: Homepage, https://aiopsenabler.com
+Project-URL: Repository, https://github.com/cyntra360hub/aiops-enabler-sdk
+Project-URL: Issues, https://github.com/cyntra360hub/aiops-enabler-sdk/issues
+Keywords: aiops,agents,observability,ratings,instrumentation
+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 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
+Requires-Dist: pytest-cov<7.0,>=6.0; extra == "dev"
+Dynamic: license-file
+
+# aiops-enabler
+
+[![PyPI](https://img.shields.io/pypi/v/aiops-enabler.svg)](https://pypi.org/project/aiops-enabler/)
+
+Python SDK for [AiOps Enabler](https://aiopsenabler.com) — *where AI agents
+prove their worth*. Wraps the signed events (task-lifecycle instrumentation)
+and ratings HTTP APIs behind a tiny, ergonomic client.
+
+This is the public source for the SDK only. The AiOps Enabler platform
+itself lives in a separate, private repository — the SDK is split out here
+specifically so it can be a normal, publicly installable PyPI package with
+its own public source, issues, and CI, independent of the platform's own
+release cycle.
+
+## Install
+
+```bash
+pip install aiops-enabler
+```
+
+For local development against a clone of this repo:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Instrument your agent's task lifecycle in 3 lines of code:
+
+```python
+from aiops_enabler import AiOpsClient
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+client.task_started(task_id="abc123")
+client.task_completed(task_id="abc123", outcome="success", duration_ms=1420, category="incident-response")
+```
+
+`agent_key_id`/`agent_secret` are the API key pair issued when you register
+your agent (`POST /api/v1/agents`) or rotate its key
+(`POST /api/v1/agents/{slug}/api-keys/rotate`) — shown exactly once at
+issuance time.
+
+Every call is HMAC-signed automatically; you never need to touch signing
+headers yourself.
+
+### Recording an outcome
+
+`outcome` is one of `"success"`, `"failure"`, or `"escalated"` (escalated =
+handed off to a human, not auto-resolved — see how this feeds
+`auto_resolution_rate` on your agent's public profile).
+
+```python
+client.task_completed(
+    task_id="abc123",
+    outcome="success",
+    duration_ms=1420,
+    category="incident-response",   # optional, freeform
+    external_ref="datadog:incident:98765",  # optional, Phase 2 reconciliation prep
+)
+```
+
+On the first event your agent ever sends, its profile's verification level
+automatically upgrades from "self-reported" to **"instrumented ✓"**. Once
+enough completed tasks have been recorded, the platform's async worker
+computes tasks handled, success %, auto-resolution %, median/95th-percentile
+duration, and a 30-day trend — all visible on your agent's public profile.
+
+### Recording a rating
+
+```python
+client.rate(
+    rating="up",  # or "down"
+    end_user_anonymous_id="some-opaque-id-you-control",
+    comment="Resolved my incident in under a minute!",   # optional
+    task_reference="abc123",                              # optional
+)
+```
+
+### Configuration
+
+```python
+client = AiOpsClient(
+    agent_key_id="ak_...",
+    agent_secret="...",
+    base_url="https://api.aiopsenabler.com",  # default; override for staging/local dev
+    timeout=10.0,                              # seconds
+)
+```
+
+Use as a context manager to close the underlying connection pool
+deterministically:
+
+```python
+with AiOpsClient(agent_key_id="ak_...", agent_secret="...") as client:
+    client.task_started(task_id="abc123")
+```
+
+### Error handling
+
+Any non-2xx response raises `aiops_enabler.AiOpsError`, carrying
+`.status_code` and `.detail`:
+
+```python
+from aiops_enabler import AiOpsClient, AiOpsError
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+try:
+    client.task_started(task_id="abc123")
+except AiOpsError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## How signing works
+
+Every request is signed with the exact scheme the AiOps Enabler backend
+verifies (see [the API guide](https://aiopsenabler.com/api-guide.md) for
+the full spec and a signed test vector you can check any implementation
+against, including this one):
+
+- Headers: `X-Agent-Key-Id`, `X-Agent-Timestamp` (Unix seconds), `X-Agent-Signature`
+  (lowercase hex HMAC-SHA256).
+- Signed message: `f"{timestamp}.".encode() + raw_request_body_bytes`.
+- HMAC key: the SHA-256 hex digest of your agent secret.
+
+See `src/aiops_enabler/signing.py` for the implementation.
+`tests/test_signing_parity.py` additionally imports the platform backend's
+real verifier function directly and confirms an SDK-signed message
+verifies successfully against it — that check only runs when this repo
+is checked out as a sibling of the (private) platform repo, and skips
+cleanly otherwise; the test vector in the API guide is the
+publicly-verifiable equivalent for anyone without access to the backend.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## Releasing
+
+Tag a commit `vX.Y.Z` matching `pyproject.toml`'s `version` and push the
+tag — `.github/workflows/publish.yml` builds and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no
+long-lived API token stored in this repo).

aiops_enabler-0.1.0/README.md

@@ -0,0 +1,148 @@
+# aiops-enabler
+
+[![PyPI](https://img.shields.io/pypi/v/aiops-enabler.svg)](https://pypi.org/project/aiops-enabler/)
+
+Python SDK for [AiOps Enabler](https://aiopsenabler.com) — *where AI agents
+prove their worth*. Wraps the signed events (task-lifecycle instrumentation)
+and ratings HTTP APIs behind a tiny, ergonomic client.
+
+This is the public source for the SDK only. The AiOps Enabler platform
+itself lives in a separate, private repository — the SDK is split out here
+specifically so it can be a normal, publicly installable PyPI package with
+its own public source, issues, and CI, independent of the platform's own
+release cycle.
+
+## Install
+
+```bash
+pip install aiops-enabler
+```
+
+For local development against a clone of this repo:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Instrument your agent's task lifecycle in 3 lines of code:
+
+```python
+from aiops_enabler import AiOpsClient
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+client.task_started(task_id="abc123")
+client.task_completed(task_id="abc123", outcome="success", duration_ms=1420, category="incident-response")
+```
+
+`agent_key_id`/`agent_secret` are the API key pair issued when you register
+your agent (`POST /api/v1/agents`) or rotate its key
+(`POST /api/v1/agents/{slug}/api-keys/rotate`) — shown exactly once at
+issuance time.
+
+Every call is HMAC-signed automatically; you never need to touch signing
+headers yourself.
+
+### Recording an outcome
+
+`outcome` is one of `"success"`, `"failure"`, or `"escalated"` (escalated =
+handed off to a human, not auto-resolved — see how this feeds
+`auto_resolution_rate` on your agent's public profile).
+
+```python
+client.task_completed(
+    task_id="abc123",
+    outcome="success",
+    duration_ms=1420,
+    category="incident-response",   # optional, freeform
+    external_ref="datadog:incident:98765",  # optional, Phase 2 reconciliation prep
+)
+```
+
+On the first event your agent ever sends, its profile's verification level
+automatically upgrades from "self-reported" to **"instrumented ✓"**. Once
+enough completed tasks have been recorded, the platform's async worker
+computes tasks handled, success %, auto-resolution %, median/95th-percentile
+duration, and a 30-day trend — all visible on your agent's public profile.
+
+### Recording a rating
+
+```python
+client.rate(
+    rating="up",  # or "down"
+    end_user_anonymous_id="some-opaque-id-you-control",
+    comment="Resolved my incident in under a minute!",   # optional
+    task_reference="abc123",                              # optional
+)
+```
+
+### Configuration
+
+```python
+client = AiOpsClient(
+    agent_key_id="ak_...",
+    agent_secret="...",
+    base_url="https://api.aiopsenabler.com",  # default; override for staging/local dev
+    timeout=10.0,                              # seconds
+)
+```
+
+Use as a context manager to close the underlying connection pool
+deterministically:
+
+```python
+with AiOpsClient(agent_key_id="ak_...", agent_secret="...") as client:
+    client.task_started(task_id="abc123")
+```
+
+### Error handling
+
+Any non-2xx response raises `aiops_enabler.AiOpsError`, carrying
+`.status_code` and `.detail`:
+
+```python
+from aiops_enabler import AiOpsClient, AiOpsError
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+try:
+    client.task_started(task_id="abc123")
+except AiOpsError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## How signing works
+
+Every request is signed with the exact scheme the AiOps Enabler backend
+verifies (see [the API guide](https://aiopsenabler.com/api-guide.md) for
+the full spec and a signed test vector you can check any implementation
+against, including this one):
+
+- Headers: `X-Agent-Key-Id`, `X-Agent-Timestamp` (Unix seconds), `X-Agent-Signature`
+  (lowercase hex HMAC-SHA256).
+- Signed message: `f"{timestamp}.".encode() + raw_request_body_bytes`.
+- HMAC key: the SHA-256 hex digest of your agent secret.
+
+See `src/aiops_enabler/signing.py` for the implementation.
+`tests/test_signing_parity.py` additionally imports the platform backend's
+real verifier function directly and confirms an SDK-signed message
+verifies successfully against it — that check only runs when this repo
+is checked out as a sibling of the (private) platform repo, and skips
+cleanly otherwise; the test vector in the API guide is the
+publicly-verifiable equivalent for anyone without access to the backend.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## Releasing
+
+Tag a commit `vX.Y.Z` matching `pyproject.toml`'s `version` and push the
+tag — `.github/workflows/publish.yml` builds and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no
+long-lived API token stored in this repo).

aiops_enabler-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "aiops-enabler"
+version = "0.1.0"
+description = "Python SDK for AiOps Enabler — instrument your AI agent's task lifecycle and ratings in 3 lines of code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AiOps Enabler" }]
+keywords = ["aiops", "agents", "observability", "ratings", "instrumentation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+# Deliberately one dependency: `httpx` (sync client) — the "3 lines of
+# code" promise (CLAUDE.md F4) means the SDK itself should be as close to
+# zero-friction to install as possible. `requests` was the other option
+# considered; httpx was chosen because the AiOps Enabler backend it talks
+# to is also httpx-based, standardizing on one HTTP library across both.
+dependencies = [
+    "httpx>=0.27,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3,<9.0",
+    "pytest-cov>=6.0,<7.0",
+]
+
+# Published on PyPI as `aiops-enabler` — `pip install aiops-enabler`.
+# This repo is the public source; the platform itself
+# (github.com/cyntra360hub/aiops-enabler) is a separate, private repo —
+# see this repo's README for why the SDK lives here instead.
+[project.urls]
+Homepage = "https://aiopsenabler.com"
+Repository = "https://github.com/cyntra360hub/aiops-enabler-sdk"
+Issues = "https://github.com/cyntra360hub/aiops-enabler-sdk/issues"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiops_enabler = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["src/aiops_enabler"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiops_enabler"]
+
+[tool.mypy]
+# mypy itself only supports checking against 3.10+ targets even though
+# this package's own `requires-python` floor is 3.9 (the code uses no
+# 3.10+-only runtime features — `from __future__ import annotations` makes
+# every `X | None` / `dict[str, str]` annotation a deferred string, valid
+# back to 3.9 — this setting only controls which stdlib typeshed stubs
+# mypy checks against).
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+# `tests/test_signing_parity.py` inserts `/backend` onto `sys.path` at
+# runtime to import the backend's real `app.modules.agents.hmac_auth` for
+# a cross-package parity check (see that file's docstring) — mypy has no
+# static visibility into that path, so `app.*` is unresolvable at
+# check-time here even though it resolves fine at test-run-time.
+module = "app.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# No `tests/__init__.py` (pytest rootdir-relative test discovery, matching
+# the backend's own test layout), so mypy sees these as top-level modules
+# named `test_client`/`test_signing_parity`, not `tests.test_*`.
+module = ["test_client", "test_signing_parity"]
+disallow_untyped_defs = false
+warn_return_any = false

aiops_enabler-0.1.0/setup.cfg

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

aiops_enabler-0.1.0/src/aiops_enabler/__init__.py

@@ -0,0 +1,21 @@
+"""aiops-enabler — Python SDK for AiOps Enabler.
+
+Wraps the events (``POST /api/v1/events``, F4) and ratings
+(``POST /api/v1/ratings``, F3) HTTP APIs behind a tiny, ergonomic client::
+
+    from aiops_enabler import AiOpsClient
+
+    client = AiOpsClient(agent_key_id="...", agent_secret="...")
+    client.task_started(task_id="abc123")
+    client.task_completed(task_id="abc123", outcome="success", duration_ms=1420)
+
+See ``aiops_enabler.signing`` for the HMAC request-signing scheme, which
+mirrors the backend's ``app.modules.agents.hmac_auth`` module
+byte-for-byte (parity verified in this package's own test suite,
+``tests/test_signing_parity.py``, against the backend's real verifier).
+"""
+
+from aiops_enabler.client import AiOpsClient, AiOpsError
+
+__all__ = ["AiOpsClient", "AiOpsError"]
+__version__ = "0.1.0"

aiops_enabler-0.1.0/src/aiops_enabler/client.py

@@ -0,0 +1,180 @@
+"""``AiOpsClient`` — a tiny, ergonomic wrapper around the AiOps Enabler
+events (F4) + ratings (F3) HTTP APIs.
+
+CLAUDE.md F4: "ship a tiny Python SDK ... wrapping the events + rating
+endpoints in 3 lines of code"::
+
+    from aiops_enabler import AiOpsClient
+
+    client = AiOpsClient(agent_key_id="...", agent_secret="...")
+    client.task_started(task_id="abc123")
+    client.task_completed(task_id="abc123", outcome="success", duration_ms=1420)
+"""
+
+from __future__ import annotations
+
+import json
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from aiops_enabler.signing import sign_request
+
+EventOutcome = Literal["success", "failure", "escalated"]
+RatingValue = Literal["up", "down"]
+
+# The backend's real production base URL (CLAUDE.md's locked domain,
+# `aiopsenabler.com`) — overridable via `base_url=` for staging/local dev
+# (e.g. `http://localhost:8000`).
+DEFAULT_BASE_URL = "https://api.aiopsenabler.com"
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+class AiOpsError(Exception):
+    """Raised for any non-2xx response from the AiOps Enabler API. Carries
+    the HTTP status code and the raw response body/text for debugging —
+    deliberately not a per-status-code exception hierarchy (CLAUDE.md's
+    "boring, proven choices" — callers that need to branch on status can
+    read `.status_code`)."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"AiOps Enabler API error {status_code}: {detail}")
+
+
+class AiOpsClient:
+    """Signed client for an agent's own ``POST /api/v1/events`` and
+    ``POST /api/v1/ratings`` calls — the agent's own backend holds the API
+    secret and calls these directly (never from browser/client-side code;
+    see the backend's ``app.modules.events.router`` docstring for why
+    there is no unsigned/public path for events).
+
+    One ``httpx.Client`` is created and reused for the lifetime of this
+    object (standard connection-pooling practice). Use as a context
+    manager (``with AiOpsClient(...) as client:``) to close it
+    deterministically, or call ``.close()`` yourself — both are optional
+    for short-lived scripts.
+    """
+
+    def __init__(
+        self,
+        *,
+        agent_key_id: str,
+        agent_secret: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._key_id = agent_key_id
+        self._secret = agent_secret
+        # `transport=` is exposed (not just an internal test hook) so a
+        # real caller can also inject e.g. a custom proxy/retry transport
+        # without subclassing; the SDK's own test suite uses it with
+        # `httpx.MockTransport` to mock the HTTP layer without a live
+        # backend (see `tests/test_client.py`).
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"), timeout=timeout, transport=transport
+        )
+
+    def __enter__(self) -> AiOpsClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # --- Signed POST helper -------------------------------------------
+
+    def _post_signed(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        # A stable, compact JSON encoding: the signature covers the exact
+        # bytes sent, so it doesn't matter which valid JSON encoding is
+        # used as long as it's applied consistently — `separators=(",", ":")`
+        # just keeps the wire payload small.
+        body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        headers = sign_request(key_id=self._key_id, secret=self._secret, body=body)
+        response = self._http.post(path, content=body, headers=headers)
+        if response.status_code >= 400:
+            raise AiOpsError(response.status_code, response.text)
+        if not response.content:
+            return {}
+        result: dict[str, Any] = response.json()
+        return result
+
+    # --- Events (F4: Level 2 instrumentation) -----------------------------
+
+    def task_started(self, *, task_id: str) -> dict[str, Any]:
+        """Record that a task started. Call once per task at the start of
+        its lifecycle; pair with a later `task_completed()` call using the
+        same `task_id`."""
+        return self._post_signed(
+            "/api/v1/events", {"event_type": "task_started", "task_id": task_id}
+        )
+
+    def task_completed(
+        self,
+        *,
+        task_id: str,
+        outcome: EventOutcome,
+        duration_ms: int,
+        category: str | None = None,
+        external_ref: str | None = None,
+    ) -> dict[str, Any]:
+        """Record that a task completed. `task_id` should match the value
+        passed to the corresponding `task_started()` call (though the
+        backend does not hard-require a prior `task_started` for the same
+        `task_id` — see `app.modules.events.service.get_prior_task_started`
+        in the backend for that documented leniency decision)."""
+        payload: dict[str, Any] = {
+            "event_type": "task_completed",
+            "task_id": task_id,
+            "outcome": outcome,
+            "duration_ms": duration_ms,
+        }
+        if category is not None:
+            payload["category"] = category
+        if external_ref is not None:
+            payload["external_ref"] = external_ref
+        return self._post_signed("/api/v1/events", payload)
+
+    # --- Heartbeat (P2: liveness) ------------------------------------------
+
+    def heartbeat(self) -> dict[str, Any]:
+        """Record a liveness ping — call on a schedule (recommend every
+        30-60 minutes). No payload: a heartbeat carries no data beyond "I
+        am alive right now." Returns the platform's resolved
+        `last_heartbeat_at`/`liveness_state`. P2 is a gated-lane feature
+        (PRODUCT_ROADMAP_2.md) that ships with its flag off by default —
+        this call 404s (raising `AiOpsError` with `status_code == 404`)
+        until the platform operator has enabled it."""
+        return self._post_signed("/api/v1/heartbeat", {})
+
+    # --- Ratings (F3) -----------------------------------------------------
+
+    def rate(
+        self,
+        *,
+        rating: RatingValue,
+        end_user_anonymous_id: str,
+        comment: str | None = None,
+        task_reference: str | None = None,
+    ) -> dict[str, Any]:
+        """Record an end-user rating (thumbs up/down) on behalf of this
+        agent — convenience wrapper around `POST /api/v1/ratings`."""
+        payload: dict[str, Any] = {
+            "rating": rating,
+            "end_user_anonymous_id": end_user_anonymous_id,
+        }
+        if comment is not None:
+            payload["comment"] = comment
+        if task_reference is not None:
+            payload["task_reference"] = task_reference
+        return self._post_signed("/api/v1/ratings", payload)

aiops_enabler-0.1.0/src/aiops_enabler/signing.py

@@ -0,0 +1,70 @@
+"""HMAC-SHA256 request signing — must byte-for-byte match
+`app.modules.agents.hmac_auth` in the backend (this SDK lives in the same
+monorepo, `/backend`, as the API it's a client for).
+
+Signing scheme (mirrored exactly — see the backend module's docstring,
+`backend/app/modules/agents/hmac_auth.py`, for the canonical source of
+truth; also documented in the monorepo's DECISIONS.md):
+
+- Headers: ``X-Agent-Key-Id``, ``X-Agent-Timestamp`` (Unix seconds, as a
+  string), ``X-Agent-Signature`` (lowercase hex HMAC-SHA256).
+- Signed message: ``f"{timestamp}.".encode() + raw_request_body_bytes``.
+- HMAC key: ``bytes.fromhex(secret_hash)``, where ``secret_hash`` is the
+  SHA-256 hex digest of the agent's raw secret
+  (``sha256(secret).hexdigest()``) — deterministic, so the backend (which
+  only ever stores this digest, never the raw secret after issuance) and
+  this SDK (which only ever has the raw secret) independently arrive at
+  the same HMAC key without transmitting either the raw secret or the
+  digest itself over the wire.
+
+Parity with the backend is verified in ``tests/test_signing_parity.py`` by
+importing the backend's actual ``app.modules.agents.hmac_auth.verify_signature``
+function directly (a monorepo-local import — that module has zero
+third-party dependencies, so this doesn't require installing the backend's
+FastAPI/SQLAlchemy stack) and asserting a message signed by this module
+verifies successfully against it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+KEY_ID_HEADER = "X-Agent-Key-Id"
+TIMESTAMP_HEADER = "X-Agent-Timestamp"
+SIGNATURE_HEADER = "X-Agent-Signature"
+
+
+def secret_hash(secret: str) -> str:
+    """The hex-encoded SHA-256 digest of the raw agent secret — used
+    directly as the HMAC key, matching ``AgentApiKey.secret_hash`` on the
+    backend (see module docstring)."""
+    return hashlib.sha256(secret.encode("utf-8")).hexdigest()
+
+
+def compute_signature(*, secret: str, timestamp: str, body: bytes) -> str:
+    """Return the hex HMAC-SHA256 signature for ``body`` signed at
+    ``timestamp``, using the raw agent ``secret``.
+
+    Unlike the backend's ``hmac_auth.compute_signature`` (which takes an
+    already-hashed ``secret_hash``, since the backend never has the raw
+    secret after issuance), this takes the raw ``secret`` directly — the
+    SDK caller has it, hashes it internally via `secret_hash`, and the two
+    resulting HMAC keys are identical.
+    """
+    key = bytes.fromhex(secret_hash(secret))
+    message = f"{timestamp}.".encode() + body
+    return hmac.new(key, message, hashlib.sha256).hexdigest()
+
+
+def sign_request(*, key_id: str, secret: str, body: bytes) -> dict[str, str]:
+    """Build the full set of signed-request headers for ``body``."""
+    timestamp = str(int(time.time()))
+    signature = compute_signature(secret=secret, timestamp=timestamp, body=body)
+    return {
+        KEY_ID_HEADER: key_id,
+        TIMESTAMP_HEADER: timestamp,
+        SIGNATURE_HEADER: signature,
+        "Content-Type": "application/json",
+    }

aiops_enabler-0.1.0/src/aiops_enabler.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: aiops-enabler
+Version: 0.1.0
+Summary: Python SDK for AiOps Enabler — instrument your AI agent's task lifecycle and ratings in 3 lines of code.
+Author: AiOps Enabler
+License: MIT
+Project-URL: Homepage, https://aiopsenabler.com
+Project-URL: Repository, https://github.com/cyntra360hub/aiops-enabler-sdk
+Project-URL: Issues, https://github.com/cyntra360hub/aiops-enabler-sdk/issues
+Keywords: aiops,agents,observability,ratings,instrumentation
+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 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
+Requires-Dist: pytest-cov<7.0,>=6.0; extra == "dev"
+Dynamic: license-file
+
+# aiops-enabler
+
+[![PyPI](https://img.shields.io/pypi/v/aiops-enabler.svg)](https://pypi.org/project/aiops-enabler/)
+
+Python SDK for [AiOps Enabler](https://aiopsenabler.com) — *where AI agents
+prove their worth*. Wraps the signed events (task-lifecycle instrumentation)
+and ratings HTTP APIs behind a tiny, ergonomic client.
+
+This is the public source for the SDK only. The AiOps Enabler platform
+itself lives in a separate, private repository — the SDK is split out here
+specifically so it can be a normal, publicly installable PyPI package with
+its own public source, issues, and CI, independent of the platform's own
+release cycle.
+
+## Install
+
+```bash
+pip install aiops-enabler
+```
+
+For local development against a clone of this repo:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Instrument your agent's task lifecycle in 3 lines of code:
+
+```python
+from aiops_enabler import AiOpsClient
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+client.task_started(task_id="abc123")
+client.task_completed(task_id="abc123", outcome="success", duration_ms=1420, category="incident-response")
+```
+
+`agent_key_id`/`agent_secret` are the API key pair issued when you register
+your agent (`POST /api/v1/agents`) or rotate its key
+(`POST /api/v1/agents/{slug}/api-keys/rotate`) — shown exactly once at
+issuance time.
+
+Every call is HMAC-signed automatically; you never need to touch signing
+headers yourself.
+
+### Recording an outcome
+
+`outcome` is one of `"success"`, `"failure"`, or `"escalated"` (escalated =
+handed off to a human, not auto-resolved — see how this feeds
+`auto_resolution_rate` on your agent's public profile).
+
+```python
+client.task_completed(
+    task_id="abc123",
+    outcome="success",
+    duration_ms=1420,
+    category="incident-response",   # optional, freeform
+    external_ref="datadog:incident:98765",  # optional, Phase 2 reconciliation prep
+)
+```
+
+On the first event your agent ever sends, its profile's verification level
+automatically upgrades from "self-reported" to **"instrumented ✓"**. Once
+enough completed tasks have been recorded, the platform's async worker
+computes tasks handled, success %, auto-resolution %, median/95th-percentile
+duration, and a 30-day trend — all visible on your agent's public profile.
+
+### Recording a rating
+
+```python
+client.rate(
+    rating="up",  # or "down"
+    end_user_anonymous_id="some-opaque-id-you-control",
+    comment="Resolved my incident in under a minute!",   # optional
+    task_reference="abc123",                              # optional
+)
+```
+
+### Configuration
+
+```python
+client = AiOpsClient(
+    agent_key_id="ak_...",
+    agent_secret="...",
+    base_url="https://api.aiopsenabler.com",  # default; override for staging/local dev
+    timeout=10.0,                              # seconds
+)
+```
+
+Use as a context manager to close the underlying connection pool
+deterministically:
+
+```python
+with AiOpsClient(agent_key_id="ak_...", agent_secret="...") as client:
+    client.task_started(task_id="abc123")
+```
+
+### Error handling
+
+Any non-2xx response raises `aiops_enabler.AiOpsError`, carrying
+`.status_code` and `.detail`:
+
+```python
+from aiops_enabler import AiOpsClient, AiOpsError
+
+client = AiOpsClient(agent_key_id="ak_...", agent_secret="...")
+try:
+    client.task_started(task_id="abc123")
+except AiOpsError as exc:
+    print(exc.status_code, exc.detail)
+```
+
+## How signing works
+
+Every request is signed with the exact scheme the AiOps Enabler backend
+verifies (see [the API guide](https://aiopsenabler.com/api-guide.md) for
+the full spec and a signed test vector you can check any implementation
+against, including this one):
+
+- Headers: `X-Agent-Key-Id`, `X-Agent-Timestamp` (Unix seconds), `X-Agent-Signature`
+  (lowercase hex HMAC-SHA256).
+- Signed message: `f"{timestamp}.".encode() + raw_request_body_bytes`.
+- HMAC key: the SHA-256 hex digest of your agent secret.
+
+See `src/aiops_enabler/signing.py` for the implementation.
+`tests/test_signing_parity.py` additionally imports the platform backend's
+real verifier function directly and confirms an SDK-signed message
+verifies successfully against it — that check only runs when this repo
+is checked out as a sibling of the (private) platform repo, and skips
+cleanly otherwise; the test vector in the API guide is the
+publicly-verifiable equivalent for anyone without access to the backend.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+## Releasing
+
+Tag a commit `vX.Y.Z` matching `pyproject.toml`'s `version` and push the
+tag — `.github/workflows/publish.yml` builds and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no
+long-lived API token stored in this repo).

aiops_enabler-0.1.0/src/aiops_enabler.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/aiops_enabler/__init__.py
+src/aiops_enabler/client.py
+src/aiops_enabler/py.typed
+src/aiops_enabler/signing.py
+src/aiops_enabler.egg-info/PKG-INFO
+src/aiops_enabler.egg-info/SOURCES.txt
+src/aiops_enabler.egg-info/dependency_links.txt
+src/aiops_enabler.egg-info/requires.txt
+src/aiops_enabler.egg-info/top_level.txt
+tests/test_client.py
+tests/test_signing_parity.py

aiops_enabler-0.1.0/src/aiops_enabler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aiops_enabler-0.1.0/src/aiops_enabler.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx<1.0,>=0.27
+
+[dev]
+pytest<9.0,>=8.3
+pytest-cov<7.0,>=6.0

aiops_enabler-0.1.0/src/aiops_enabler.egg-info/top_level.txt

@@ -0,0 +1 @@
+aiops_enabler

aiops_enabler-0.1.0/tests/test_client.py

@@ -0,0 +1,253 @@
+"""Unit tests for `AiOpsClient`. The HTTP layer is fully mocked via
+`httpx.MockTransport` — no live backend required (per the M5 task brief:
+"unit tests mocking the HTTP layer")."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+
+import httpx
+import pytest
+
+from aiops_enabler import AiOpsClient, AiOpsError
+from aiops_enabler.signing import KEY_ID_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER
+
+Handler = Callable[[httpx.Request], httpx.Response]
+
+
+def _client(handler: Handler) -> AiOpsClient:
+    return AiOpsClient(
+        agent_key_id="ak_test",
+        agent_secret="s3cr3t-agent-secret",
+        base_url="https://example.test",
+        transport=httpx.MockTransport(handler),
+    )
+
+
+def test_task_started_posts_signed_request_to_events_endpoint() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={"id": "evt-1", "event_type": "task_started"})
+
+    with _client(handler) as client:
+        result = client.task_started(task_id="abc123")
+
+    request = captured["request"]
+    assert request.method == "POST"
+    assert request.url.path == "/api/v1/events"
+    assert request.headers[KEY_ID_HEADER] == "ak_test"
+    assert TIMESTAMP_HEADER in request.headers
+    assert SIGNATURE_HEADER in request.headers
+    assert request.headers["Content-Type"] == "application/json"
+
+    body = json.loads(request.content)
+    assert body == {"event_type": "task_started", "task_id": "abc123"}
+    assert result == {"id": "evt-1", "event_type": "task_started"}
+
+
+def test_task_completed_includes_all_provided_fields() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={"id": "evt-2"})
+
+    with _client(handler) as client:
+        client.task_completed(
+            task_id="abc123",
+            outcome="success",
+            duration_ms=1420,
+            category="incident-response",
+            external_ref="datadog:incident:1",
+        )
+
+    body = json.loads(captured["request"].content)
+    assert body == {
+        "event_type": "task_completed",
+        "task_id": "abc123",
+        "outcome": "success",
+        "duration_ms": 1420,
+        "category": "incident-response",
+        "external_ref": "datadog:incident:1",
+    }
+
+
+def test_task_completed_omits_optional_fields_when_not_provided() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={})
+
+    with _client(handler) as client:
+        client.task_completed(task_id="abc123", outcome="failure", duration_ms=500)
+
+    body = json.loads(captured["request"].content)
+    assert body == {
+        "event_type": "task_completed",
+        "task_id": "abc123",
+        "outcome": "failure",
+        "duration_ms": 500,
+    }
+    assert "category" not in body
+    assert "external_ref" not in body
+
+
+def test_heartbeat_posts_signed_empty_request_to_heartbeat_endpoint() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(
+            201, json={"last_heartbeat_at": "2026-07-14T12:00:00Z", "liveness_state": "active"}
+        )
+
+    with _client(handler) as client:
+        result = client.heartbeat()
+
+    request = captured["request"]
+    assert request.method == "POST"
+    assert request.url.path == "/api/v1/heartbeat"
+    assert request.headers[KEY_ID_HEADER] == "ak_test"
+    assert TIMESTAMP_HEADER in request.headers
+    assert SIGNATURE_HEADER in request.headers
+    assert json.loads(request.content) == {}
+    assert result == {"last_heartbeat_at": "2026-07-14T12:00:00Z", "liveness_state": "active"}
+
+
+def test_heartbeat_404_while_gated_flag_is_off_raises_aiops_error() -> None:
+    """P2 ships flag-off by default (PRODUCT_ROADMAP_2.md, gated lane) —
+    the SDK surfaces that the same way as any other API error, not a
+    special case, so a caller can catch `AiOpsError` and check
+    `status_code == 404` if it wants to distinguish "not enabled yet"
+    from a genuine outage."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"detail": "Not found"})
+
+    with _client(handler) as client, pytest.raises(AiOpsError) as exc_info:
+        client.heartbeat()
+
+    assert exc_info.value.status_code == 404
+
+
+def test_rate_posts_signed_request_to_ratings_endpoint() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={"id": "rating-1", "rating": 1})
+
+    with _client(handler) as client:
+        result = client.rate(rating="up", end_user_anonymous_id="euid-1", comment="great job")
+
+    request = captured["request"]
+    assert request.url.path == "/api/v1/ratings"
+    body = json.loads(request.content)
+    assert body == {"rating": "up", "end_user_anonymous_id": "euid-1", "comment": "great job"}
+    assert result == {"id": "rating-1", "rating": 1}
+
+
+def test_rate_includes_task_reference_when_provided() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={})
+
+    with _client(handler) as client:
+        client.rate(rating="up", end_user_anonymous_id="euid-3", task_reference="task-abc")
+
+    body = json.loads(captured["request"].content)
+    assert body == {
+        "rating": "up",
+        "end_user_anonymous_id": "euid-3",
+        "task_reference": "task-abc",
+    }
+
+
+def test_empty_response_body_returns_empty_dict() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(204)
+
+    with _client(handler) as client:
+        result = client.task_started(task_id="abc123")
+
+    assert result == {}
+
+
+def test_rate_omits_optional_fields_when_not_provided() -> None:
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={})
+
+    with _client(handler) as client:
+        client.rate(rating="down", end_user_anonymous_id="euid-2")
+
+    body = json.loads(captured["request"].content)
+    assert body == {"rating": "down", "end_user_anonymous_id": "euid-2"}
+
+
+def test_error_response_raises_aiops_error_with_status_and_detail() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, text="Invalid request signature")
+
+    with _client(handler) as client, pytest.raises(AiOpsError) as exc_info:
+        client.task_started(task_id="abc123")
+
+    assert exc_info.value.status_code == 401
+    assert "Invalid request signature" in exc_info.value.detail
+
+
+def test_rate_limit_error_response_raises_aiops_error() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, text="Rate limit exceeded", headers={"Retry-After": "30"})
+
+    with _client(handler) as client, pytest.raises(AiOpsError) as exc_info:
+        client.task_started(task_id="abc123")
+
+    assert exc_info.value.status_code == 429
+
+
+def test_context_manager_closes_underlying_http_client() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(201, json={})
+
+    with _client(handler) as client:
+        client.task_started(task_id="abc123")
+        assert not client._http.is_closed
+
+    assert client._http.is_closed
+
+
+def test_close_can_be_called_directly_without_context_manager() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(201, json={})
+
+    client = _client(handler)
+    client.task_started(task_id="abc123")
+    client.close()
+    assert client._http.is_closed
+
+
+def test_timestamp_header_is_close_to_current_unix_time() -> None:
+    import time
+
+    captured: dict[str, httpx.Request] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["request"] = request
+        return httpx.Response(201, json={})
+
+    before = int(time.time())
+    with _client(handler) as client:
+        client.task_started(task_id="abc123")
+    after = int(time.time())
+
+    ts = int(captured["request"].headers[TIMESTAMP_HEADER])
+    assert before <= ts <= after

aiops_enabler-0.1.0/tests/test_signing_parity.py

@@ -0,0 +1,129 @@
+"""Cross-package parity test: a message signed by this SDK's
+`aiops_enabler.signing` module must verify successfully against the
+backend's ACTUAL verifier function
+(`app.modules.agents.hmac_auth.verify_signature`), imported directly from
+`/backend` in this monorepo — not a hand-reimplementation merely guessed to
+match. This is the strongest form of parity check available: it exercises
+the real production verifier the backend's `require_agent_api_key`
+dependency calls on every signed request, not a copy of its logic.
+
+This works without installing the backend's FastAPI/SQLAlchemy/etc.
+dependency set because `app.modules.agents.hmac_auth` (and every package
+`__init__.py` on the import path to it: `app`, `app.modules`,
+`app.modules.agents`) has zero third-party imports — stdlib
+`hashlib`/`hmac`/`datetime` only. Only `sys.path` needs to include
+`/backend` for the import to resolve.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+from aiops_enabler.signing import compute_signature, secret_hash
+
+_BACKEND_DIR = Path(__file__).resolve().parents[3] / "backend"
+_HMAC_AUTH_PATH = _BACKEND_DIR / "app" / "modules" / "agents" / "hmac_auth.py"
+
+
+def _import_backend_hmac_auth() -> ModuleType:
+    if not _HMAC_AUTH_PATH.exists():
+        pytest.skip(
+            f"backend not found at {_BACKEND_DIR!s} (expected monorepo layout with "
+            "sdk/python and backend as siblings) — skipping the cross-package parity "
+            "check; see this module's docstring for hand-verification notes."
+        )
+    if str(_BACKEND_DIR) not in sys.path:
+        sys.path.insert(0, str(_BACKEND_DIR))
+    from app.modules.agents import hmac_auth
+
+    return hmac_auth
+
+
+def test_sdk_signature_matches_backend_compute_signature_byte_for_byte() -> None:
+    backend_hmac_auth = _import_backend_hmac_auth()
+
+    secret = "test-agent-secret-value"
+    timestamp = str(int(datetime.now(timezone.utc).timestamp()))
+    body = b'{"event_type":"task_started","task_id":"abc123"}'
+
+    sdk_signature = compute_signature(secret=secret, timestamp=timestamp, body=body)
+    backend_signature = backend_hmac_auth.compute_signature(
+        secret_hash=secret_hash(secret), timestamp=timestamp, body=body
+    )
+
+    assert sdk_signature == backend_signature
+
+
+def test_sdk_signed_message_verifies_against_the_backends_real_verifier() -> None:
+    """The strongest parity check: feed a message signed by the SDK
+    straight into the backend's real `verify_signature` (the exact
+    function `require_agent_api_key` calls in production) and assert it
+    accepts it."""
+    backend_hmac_auth = _import_backend_hmac_auth()
+
+    secret = "another-test-secret"  # nosec B105 - test fixture literal
+    timestamp = str(int(datetime.now(timezone.utc).timestamp()))
+    body = (
+        b'{"event_type":"task_completed","task_id":"abc123","outcome":"success","duration_ms":1420}'
+    )
+
+    signature = compute_signature(secret=secret, timestamp=timestamp, body=body)
+
+    assert backend_hmac_auth.verify_signature(
+        secret_hash=secret_hash(secret),
+        timestamp=timestamp,
+        body=body,
+        signature=signature,
+    )
+
+
+def test_tampered_body_fails_the_backends_real_verifier() -> None:
+    backend_hmac_auth = _import_backend_hmac_auth()
+
+    secret = "yet-another-secret"  # nosec B105 - test fixture literal
+    timestamp = str(int(datetime.now(timezone.utc).timestamp()))
+    signed_body = b'{"task_id":"abc123"}'
+    tampered_body = b'{"task_id":"xyz999"}'
+
+    signature = compute_signature(secret=secret, timestamp=timestamp, body=signed_body)
+
+    assert not backend_hmac_auth.verify_signature(
+        secret_hash=secret_hash(secret),
+        timestamp=timestamp,
+        body=tampered_body,
+        signature=signature,
+    )
+
+
+def test_stale_timestamp_fails_the_backends_real_verifier() -> None:
+    backend_hmac_auth = _import_backend_hmac_auth()
+
+    secret = "stale-timestamp-secret"  # nosec B105 - test fixture literal
+    # 10 minutes ago — outside the backend's default 300s freshness window.
+    stale_timestamp = str(int(datetime.now(timezone.utc).timestamp()) - 600)
+    body = b'{"task_id":"abc123"}'
+
+    signature = compute_signature(secret=secret, timestamp=stale_timestamp, body=body)
+
+    assert not backend_hmac_auth.verify_signature(
+        secret_hash=secret_hash(secret),
+        timestamp=stale_timestamp,
+        body=body,
+        signature=signature,
+    )
+
+
+def test_secret_hash_matches_backends_agent_api_key_secret_hash_scheme() -> None:
+    """`app.models.agent_api_key.AgentApiKey.secret_hash` is documented as
+    `sha256(raw_secret).hexdigest()` — confirm the SDK's `secret_hash()`
+    helper derives the identical value a real issued key's stored hash
+    would be, independent of the HMAC signing path above."""
+    import hashlib
+
+    secret = "issued-agent-secret-abc"  # nosec B105 - test fixture literal
+    assert secret_hash(secret) == hashlib.sha256(secret.encode("utf-8")).hexdigest()