trustmodel 3.2.0__tar.gz → 3.3.0__tar.gz

{trustmodel-3.2.0 → trustmodel-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustmodel
-Version: 3.2.0
+Version: 3.3.0
 Summary: Official Python SDK for TrustModel AI evaluation platform
 Project-URL: Homepage, https://trustmodel.ai
 Author-email: TrustModel <info@predixtions.com>
@@ -118,6 +118,7 @@ Evaluate AI models for safety, bias, and performance with a simple, intuitive in
 - [Agentic Trace Evaluation](#agentic-trace-evaluation)
 - [Galileo Integration](#galileo-integration)
 - [MCP Scanner](#mcp-scanner)
+- [AgentCert](#agentcert)
 - [Requirements](#requirements)
 - [Support](#support)
 - [License](#license)
@@ -131,6 +132,7 @@ Evaluate AI models for safety, bias, and performance with a simple, intuitive in
 - 📊 **Comprehensive**: Support for all evaluation types and configurations
 - 🌍 **Framework Agnostic**: Works with any Python framework or standalone scripts
 - 🛰️ **Zero-Config Auto-Capture**: Add two lines (`auto_init`) and every OpenAI / Anthropic / LangChain / CrewAI / etc. call is automatically traced and evaluated
+- 🔖 **AgentCert**: Issue and verify cryptographic certificates for AI agents — `client.agentcert.issue()` / `.verify()` and the `trustmodel certify` CLI
 
 ## Installation
 
@@ -1375,6 +1377,8 @@ JSONL files are also supported (one JSON object per line).
 | `expected_outcome` | No | What should have happened |
 | `actual_outcome` | No | What actually happened |
 | `goal_achieved` | No | Whether the agent achieved its goal |
+| `frameworks` | No | List of compliance framework slugs to evaluate against (e.g., `["owasp-asi", "nist-ai-rmf"]`) |
+| `control_ids` | No | List of control IDs to scope the compliance evaluation. Defaults to all controls of the selected frameworks |
 
 ### File Validation
 
@@ -1416,6 +1420,33 @@ for score in detail.scores:
 }
 ```
 
+### Compliance Frameworks
+
+Pass one or more compliance framework slugs to `frameworks` to evaluate the trace against a regulatory or security standard. Optionally scope the controls with `control_ids` (defaults to all controls of the selected frameworks).
+
+```python
+result = client.agentic.evaluate(
+    file_path="traces/agent_run.json",
+    goal="Resolve customer billing inquiry",
+    name="Support Bot Evaluation",
+    agent_framework="langchain",
+    frameworks=["owasp-asi", "nist-ai-rmf"],
+)
+```
+
+The detail response surfaces a per-framework compliance roll-up once evaluation completes:
+
+```python
+detail = client.agentic.get(result.evaluation_run_id)
+
+if detail.compliance_report_url:
+    print(f"Compliance report: {detail.compliance_report_url}")
+
+for fw in detail.compliance_frameworks:
+    print(f"  {fw.slug}: {fw.overall_status} ({fw.compliance_percentage}%)")
+    print(f"    passed={fw.passed_controls} failed={fw.failed_controls}")
+```
+
 ### Listing Evaluations
 
 ```python
@@ -1712,6 +1743,68 @@ When `edge_url` is not configured and Aurora is the only path, a missing `agent_
 
 Edge currently accepts unauthenticated requests in-cluster. The SDK uses a `RuntimeTransport` abstraction (see `trustmodel.endpoints._runtime_transport`) so future Edge auth — SVID, JWT, mTLS, service tokens — can be added without changing the public `client.guardrails.decide()` signature.
 
+## AgentCert
+
+AgentCert is TrustModel's Certificate Authority for AI agents — the "padlock for the agentic web". A certificate is minted off a completed evaluation run and binds the agent's identity, behavior, and liveness into a cryptographically verifiable, continuously-revalidated credential. Anyone can verify an agent via the public verify endpoint; a cert whose live TrustScore drifts (or which is revoked) stops verifying even though its signature is intact.
+
+Issuing a cert is org-authenticated (any API key); verifying is public.
+
+### Issue and verify (SDK)
+
+```python
+import trustmodel
+
+client = trustmodel.TrustModelClient(api_key="tm-...")
+
+# Mint a cert for an agent off a completed evaluation run.
+cert = client.agentcert.issue(
+    ans_name="helpbot.cisco.com",       # Agent Naming Service binding
+    evaluation_run_id=12345,            # source eval run (must belong to your org)
+    subject_agent_id="helpbot",         # optional
+    validity_days=90,                   # optional (1–825; default 90)
+)
+print(cert.id, cert.serial, cert.status)        # e.g. "...", "TM-2026-...", "active"
+print(cert.validation_level)                    # "DV" (DV / OV / EV)
+print(cert.trust_score_snapshot)                # 87.0  (0–100, same scale as overall_score)
+print(cert.dimension_scores)                    # {"safety": 92.0, "fairness": 85.0, ...}
+# cert.vc_jsonld holds the W3C Verifiable Credential; cert.x509_pem the X.509 PEM.
+
+# Verify an agent (public — no auth required). Accepts an ANS name or agent id.
+result = client.agentcert.verify("helpbot.cisco.com")
+if result.verified:
+    print("trusted — live score:", result.trust_score)
+else:
+    print("not trusted:", result.status, result.revocation_reason)
+```
+
+A **revoked** cert returns a normal result with `verified=False, status="revoked"`. A **missing** cert returns `found=False` (rather than raising), so verification is always a value check.
+
+### Certify (issue + verify in one call)
+
+```python
+cert, verification = client.agentcert.certify(
+    ans_name="helpbot.cisco.com",
+    evaluation_run_id=12345,
+)
+print(cert.serial, "->", "VALID" if verification.verified else "INVALID")
+```
+
+### CLI
+
+Installing the SDK also installs the `trustmodel` command:
+
+```bash
+export TRUSTMODEL_API_KEY=tm-...
+
+# Mint a cert for an agent off an evaluation run, then verify it:
+trustmodel certify helpbot.cisco.com --evaluation-run-id 12345
+
+# Just verify an existing agent's cert (public):
+trustmodel certify helpbot.cisco.com --verify-only
+```
+
+`certify` prints the certificate + verification as JSON and exits non-zero if the agent does not verify, so it drops cleanly into CI gates.
+
 ## Requirements
 
 - Python 3.9 or higher

{trustmodel-3.2.0 → trustmodel-3.3.0}/README.md

@@ -50,6 +50,7 @@ Evaluate AI models for safety, bias, and performance with a simple, intuitive in
 - [Agentic Trace Evaluation](#agentic-trace-evaluation)
 - [Galileo Integration](#galileo-integration)
 - [MCP Scanner](#mcp-scanner)
+- [AgentCert](#agentcert)
 - [Requirements](#requirements)
 - [Support](#support)
 - [License](#license)
@@ -63,6 +64,7 @@ Evaluate AI models for safety, bias, and performance with a simple, intuitive in
 - 📊 **Comprehensive**: Support for all evaluation types and configurations
 - 🌍 **Framework Agnostic**: Works with any Python framework or standalone scripts
 - 🛰️ **Zero-Config Auto-Capture**: Add two lines (`auto_init`) and every OpenAI / Anthropic / LangChain / CrewAI / etc. call is automatically traced and evaluated
+- 🔖 **AgentCert**: Issue and verify cryptographic certificates for AI agents — `client.agentcert.issue()` / `.verify()` and the `trustmodel certify` CLI
 
 ## Installation
 
@@ -1307,6 +1309,8 @@ JSONL files are also supported (one JSON object per line).
 | `expected_outcome` | No | What should have happened |
 | `actual_outcome` | No | What actually happened |
 | `goal_achieved` | No | Whether the agent achieved its goal |
+| `frameworks` | No | List of compliance framework slugs to evaluate against (e.g., `["owasp-asi", "nist-ai-rmf"]`) |
+| `control_ids` | No | List of control IDs to scope the compliance evaluation. Defaults to all controls of the selected frameworks |
 
 ### File Validation
 
@@ -1348,6 +1352,33 @@ for score in detail.scores:
 }
 ```
 
+### Compliance Frameworks
+
+Pass one or more compliance framework slugs to `frameworks` to evaluate the trace against a regulatory or security standard. Optionally scope the controls with `control_ids` (defaults to all controls of the selected frameworks).
+
+```python
+result = client.agentic.evaluate(
+    file_path="traces/agent_run.json",
+    goal="Resolve customer billing inquiry",
+    name="Support Bot Evaluation",
+    agent_framework="langchain",
+    frameworks=["owasp-asi", "nist-ai-rmf"],
+)
+```
+
+The detail response surfaces a per-framework compliance roll-up once evaluation completes:
+
+```python
+detail = client.agentic.get(result.evaluation_run_id)
+
+if detail.compliance_report_url:
+    print(f"Compliance report: {detail.compliance_report_url}")
+
+for fw in detail.compliance_frameworks:
+    print(f"  {fw.slug}: {fw.overall_status} ({fw.compliance_percentage}%)")
+    print(f"    passed={fw.passed_controls} failed={fw.failed_controls}")
+```
+
 ### Listing Evaluations
 
 ```python
@@ -1644,6 +1675,68 @@ When `edge_url` is not configured and Aurora is the only path, a missing `agent_
 
 Edge currently accepts unauthenticated requests in-cluster. The SDK uses a `RuntimeTransport` abstraction (see `trustmodel.endpoints._runtime_transport`) so future Edge auth — SVID, JWT, mTLS, service tokens — can be added without changing the public `client.guardrails.decide()` signature.
 
+## AgentCert
+
+AgentCert is TrustModel's Certificate Authority for AI agents — the "padlock for the agentic web". A certificate is minted off a completed evaluation run and binds the agent's identity, behavior, and liveness into a cryptographically verifiable, continuously-revalidated credential. Anyone can verify an agent via the public verify endpoint; a cert whose live TrustScore drifts (or which is revoked) stops verifying even though its signature is intact.
+
+Issuing a cert is org-authenticated (any API key); verifying is public.
+
+### Issue and verify (SDK)
+
+```python
+import trustmodel
+
+client = trustmodel.TrustModelClient(api_key="tm-...")
+
+# Mint a cert for an agent off a completed evaluation run.
+cert = client.agentcert.issue(
+    ans_name="helpbot.cisco.com",       # Agent Naming Service binding
+    evaluation_run_id=12345,            # source eval run (must belong to your org)
+    subject_agent_id="helpbot",         # optional
+    validity_days=90,                   # optional (1–825; default 90)
+)
+print(cert.id, cert.serial, cert.status)        # e.g. "...", "TM-2026-...", "active"
+print(cert.validation_level)                    # "DV" (DV / OV / EV)
+print(cert.trust_score_snapshot)                # 87.0  (0–100, same scale as overall_score)
+print(cert.dimension_scores)                    # {"safety": 92.0, "fairness": 85.0, ...}
+# cert.vc_jsonld holds the W3C Verifiable Credential; cert.x509_pem the X.509 PEM.
+
+# Verify an agent (public — no auth required). Accepts an ANS name or agent id.
+result = client.agentcert.verify("helpbot.cisco.com")
+if result.verified:
+    print("trusted — live score:", result.trust_score)
+else:
+    print("not trusted:", result.status, result.revocation_reason)
+```
+
+A **revoked** cert returns a normal result with `verified=False, status="revoked"`. A **missing** cert returns `found=False` (rather than raising), so verification is always a value check.
+
+### Certify (issue + verify in one call)
+
+```python
+cert, verification = client.agentcert.certify(
+    ans_name="helpbot.cisco.com",
+    evaluation_run_id=12345,
+)
+print(cert.serial, "->", "VALID" if verification.verified else "INVALID")
+```
+
+### CLI
+
+Installing the SDK also installs the `trustmodel` command:
+
+```bash
+export TRUSTMODEL_API_KEY=tm-...
+
+# Mint a cert for an agent off an evaluation run, then verify it:
+trustmodel certify helpbot.cisco.com --evaluation-run-id 12345
+
+# Just verify an existing agent's cert (public):
+trustmodel certify helpbot.cisco.com --verify-only
+```
+
+`certify` prints the certificate + verification as JSON and exits non-zero if the agent does not verify, so it drops cleanly into CI gates.
+
 ## Requirements
 
 - Python 3.9 or higher

{trustmodel-3.2.0 → trustmodel-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trustmodel"
-version = "3.2.0"
+version = "3.3.0"
 authors = [
     {name = "TrustModel", email = "info@predixtions.com"},
 ]
@@ -39,6 +39,9 @@ dependencies = [
     "importlib-metadata>=4.0.0; python_version<'3.8'",
 ]
 
+[project.scripts]
+trustmodel = "trustmodel.cli:main"
+
 [project.optional-dependencies]
 # Auto-capture AI agent traces and stream them to TrustModel.
 # Install with: pip install "trustmodel[telemetry]"

trustmodel-3.3.0/src/trustmodel/cli.py

@@ -0,0 +1,141 @@
+"""``trustmodel`` command-line interface.
+
+Entry point ``trustmodel`` (wired via ``[project.scripts]`` in
+pyproject.toml). argparse only — no extra dependencies.
+
+Commands:
+
+* ``trustmodel certify <agent>`` — mint a verifiable AgentCert for an agent
+  off a completed evaluation run, then verify it (signature + revocation +
+  live score). Use ``--verify-only`` to skip issuance and just verify.
+
+Auth is an API key (``--api-key`` or ``TRUSTMODEL_API_KEY``) — the issue
+endpoint accepts any org-scoped key; verify is public.
+
+Exit codes: ``0`` issued/verified ok · ``1`` not verified / API error ·
+``2`` missing key or usage error.
+
+TRUS-1228 (EPIC TRUS-1219)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional
+
+from .client import TrustModelClient
+from .exceptions import TrustModelError
+
+API_KEY_ENV_VAR = "TRUSTMODEL_API_KEY"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="trustmodel",
+        description="TrustModel CLI — AI assurance from the command line.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    certify = sub.add_parser(
+        "certify",
+        help="Issue and verify an AgentCert for an AI agent (TRUS-1228).",
+        description=(
+            "Mint a verifiable certificate for an agent off a completed "
+            "evaluation run, then verify it (signature + revocation + live "
+            "score)."
+        ),
+    )
+    certify.add_argument("agent", help="Agent to certify — its ANS name (e.g. helpbot.cisco.com).")
+    certify.add_argument(
+        "--evaluation-run-id",
+        type=int,
+        help="Evaluation run id to mint the cert off (required unless --verify-only).",
+    )
+    certify.add_argument("--subject-agent-id", help="Optional agent identifier to bind.")
+    certify.add_argument("--auditor-slug", help="Optional auditor slug to link the cert to.")
+    certify.add_argument(
+        "--validity-days", type=int, help="Cert lifetime in days (1–825; backend default 90)."
+    )
+    certify.add_argument(
+        "--verify-only", action="store_true", help="Skip issuance; only verify the agent's cert."
+    )
+    certify.add_argument("--api-key", help=f"TrustModel API key. Defaults to ${API_KEY_ENV_VAR}.")
+    certify.add_argument(
+        "--environment",
+        default="production",
+        choices=["local", "qa", "production"],
+        help="API environment (default: production). Ignored if --base-url is set.",
+    )
+    certify.add_argument("--base-url", help="Explicit API root; overrides --environment.")
+    certify.set_defaults(func=_cmd_certify)
+
+    return parser
+
+
+def _make_client(args: argparse.Namespace) -> TrustModelClient:
+    api_key = args.api_key or os.environ.get(API_KEY_ENV_VAR)
+    if not api_key:
+        raise _UsageError(f"no API key. Pass --api-key or set ${API_KEY_ENV_VAR}.")
+    if args.base_url:
+        return TrustModelClient(api_key=api_key, base_url=args.base_url)
+    return TrustModelClient(api_key=api_key, environment=args.environment)
+
+
+class _UsageError(Exception):
+    """Missing creds / bad invocation — maps to exit code 2."""
+
+
+def _cmd_certify(args: argparse.Namespace) -> int:
+    client = _make_client(args)
+    try:
+        if args.verify_only:
+            verification = client.agentcert.verify(args.agent)
+            print(json.dumps(verification.model_dump(), indent=2, default=str))
+            return 0 if verification.verified else 1
+
+        if args.evaluation_run_id is None:
+            raise _UsageError("provide --evaluation-run-id (or use --verify-only).")
+
+        cert, verification = client.agentcert.certify(
+            ans_name=args.agent,
+            evaluation_run_id=args.evaluation_run_id,
+            subject_agent_id=args.subject_agent_id,
+            auditor_slug=args.auditor_slug,
+            validity_days=args.validity_days,
+        )
+        print(
+            json.dumps(
+                {
+                    "certificate": cert.model_dump(),
+                    "verification": verification.model_dump(),
+                },
+                indent=2,
+                default=str,
+            )
+        )
+        return 0 if verification.verified else 1
+    finally:
+        client.close()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 1
+    try:
+        return int(args.func(args))
+    except _UsageError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except TrustModelError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

{trustmodel-3.2.0 → trustmodel-3.3.0}/src/trustmodel/client.py

@@ -7,13 +7,14 @@ from __future__ import annotations
 import json
 import logging
 import os
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Union, cast
 from urllib.parse import urljoin
 
 import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
+from .endpoints.agentcert import AgentCertEndpoint
 from .endpoints.agentic import AgenticEndpoint
 from .endpoints.batch_jobs import BatchJobsEndpoint
 from .endpoints.config import ConfigEndpoint
@@ -135,6 +136,7 @@ class TrustModelClient:
         auth: Optional[OAuthClientCredentials] = None,
         edge_url: Optional[str] = None,
         fail_mode: str = "closed",
+        organization_id: Optional[str] = None,
     ) -> None:
         # api_key and auth are mutually exclusive. Either / both / neither
         # may be combined with edge_url (the at-least-one check happens
@@ -219,6 +221,16 @@ class TrustModelClient:
         if self._api_key is not None:
             self._session.headers["Authorization"] = f"Bearer {self._api_key}"
 
+        # Aurora requires ``X-Organization-ID`` on every request to resolve
+        # the caller's org context (post-TRUS-1395 tenant scoping). Prefer
+        # the explicit constructor arg; fall back to ``TRUSTMODEL_ORGANIZATION_ID``
+        # env var so callers can set it once at process start without
+        # threading it through every construction site.
+        org_id = organization_id or os.environ.get("TRUSTMODEL_ORGANIZATION_ID")
+        self._organization_id: Optional[str] = org_id
+        if org_id:
+            self._session.headers["X-Organization-ID"] = org_id
+
         # Initialize endpoint handlers
         self.models = ModelsEndpoint(self)
         self.evaluations = EvaluationsEndpoint(self)
@@ -231,6 +243,9 @@ class TrustModelClient:
         # Runtime guardrails (P4 / v2.3.0). Edge primary with Aurora
         # fallback — see ``client.guardrails.decide()``.
         self.guardrails = GuardrailsEndpoint(self)
+        # AgentCert (TRUS-1228): issue + verify certificates for AI agents.
+        # issue is org-authenticated (any API key); verify is public.
+        self.agentcert = AgentCertEndpoint(self)
         # MCP Scanner (TRUS-847): CRUD over AGT scan reports produced by
         # trustmodel-mcp-server and persisted by the aurora-gateway
         # `mcp_scanner` app. Not gated behind an extra — pure HTTP, no
@@ -300,7 +315,7 @@ class TrustModelClient:
         endpoint: str,
         data: Optional[Dict[str, Any]] = None,
         params: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
+    ) -> Union[Dict[str, Any], List[Any]]:
         """
         Make an HTTP request to the TrustModel API.
 
@@ -322,9 +337,14 @@ class TrustModelClient:
 
         # For OAuth auth, attach a fresh bearer token per request. The
         # provider returns a cached token and only re-fetches near expiry.
-        headers: Optional[Dict[str, str]] = None
+        headers: Dict[str, str] = {}
         if self._auth is not None:
-            headers = {"Authorization": self._auth.authorization_header()}
+            headers["Authorization"] = self._auth.authorization_header()
+        # TRUS-1556 P4c: force Accept: application/json on every request
+        # so a session-header monkeypatch or middleware can't cause
+        # browsable-HTML content negotiation to win. Session default
+        # already sets this; this is belt-and-suspenders.
+        headers["Accept"] = "application/json"
 
         try:
             response = self._session.request(
@@ -344,7 +364,7 @@ class TrustModelClient:
 
         return self._handle_response(response)
 
-    def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+    def _handle_response(self, response: requests.Response) -> Union[Dict[str, Any], List[Any]]:
         """
         Handle the API response and raise appropriate exceptions for errors.
 
@@ -352,19 +372,73 @@ class TrustModelClient:
             response: The HTTP response object
 
         Returns:
-            Parsed response data
+            Parsed response data. Endpoints that return JSON objects yield a
+            ``dict``; endpoints that return JSON arrays (e.g. paginated list
+            endpoints without an envelope, such as ``/api/agent-evaluation/
+            frameworks/``) yield a ``list``. The previous ``dict(response_data)``
+            coercion silently broke array responses with ``ValueError``.
 
         Raises:
             Various TrustModelError subclasses based on the error type
         """
+        # TRUS-1556 P4c: detect HTML responses (e.g. Django default 404 /
+        # 500 error pages, or a browsable-API renderer picked because the
+        # session ``Accept`` header got stripped by a middleware). Instead
+        # of returning a confusing ``ValueError`` on json.loads, surface a
+        # clear APIError so the caller knows the server sent the wrong
+        # content-type.
+        # ``headers`` may be absent on Mock responses used by tests — guard
+        # every step so this diagnostic never masks the real assertion.
+        raw_headers = getattr(response, "headers", None) or {}
+        try:
+            content_type_raw = (
+                raw_headers.get("Content-Type") if hasattr(raw_headers, "get") else ""
+            )
+        except Exception:
+            content_type_raw = ""
+        content_type = str(content_type_raw or "").lower()
+        if content_type.startswith("text/html") or content_type.startswith("application/xhtml"):
+            raw_text = getattr(response, "text", "") or ""
+            snippet = str(raw_text)[:300] if isinstance(raw_text, (str, bytes)) else ""
+            logger.error(
+                "trustmodel.client.html_response",
+                extra={
+                    "status_code": response.status_code,
+                    "url": getattr(getattr(response, "request", None), "url", ""),
+                    "content_type": content_type,
+                },
+            )
+            raise APIError(
+                (
+                    "Server returned HTML instead of JSON — the SDK cannot "
+                    f"parse this. HTTP {response.status_code}, "
+                    f"Content-Type={content_type!r}. First 300 chars: {snippet!r}"
+                ),
+                status_code=response.status_code,
+                response={"content_type": content_type, "snippet": snippet},
+                error_code="html_response",
+            )
+
         try:
             response_data = response.json()
         except json.JSONDecodeError:
             response_data = {"detail": response.text or "Unknown error"}
 
-        # Handle successful responses
+        # Handle successful responses — pass through the shape the server sent.
         if 200 <= response.status_code < 300:
-            return dict(response_data)
+            if isinstance(response_data, list):
+                return list(response_data)
+            if isinstance(response_data, dict):
+                return dict(response_data)
+            # Primitives (bare bool / int / str) are rare but valid JSON; wrap
+            # in a stable envelope so callers can still `.get(...)` safely.
+            return {"data": response_data}
+
+        # Error paths below assume a dict body (server contract for errors).
+        # A non-dict error body is degenerate — coerce so downstream .get()
+        # calls don't AttributeError before we raise APIError.
+        if not isinstance(response_data, dict):
+            response_data = {"detail": str(response_data)}
 
         # Handle error responses
         error_message = response_data.get("detail", f"HTTP {response.status_code}")
@@ -432,21 +506,31 @@ class TrustModelClient:
             error_code=error_code,
         )
 
+    # ── public HTTP wrappers ──────────────────────────────────────────────
+    #
+    # ``_request`` / ``_handle_response`` return ``Union[Dict, List]`` so
+    # top-level array bodies (fleet listings, decisions feed) survive
+    # deserialization. Every caller of the four wrappers below (see
+    # ``endpoints/*.py``) still assumes a dict — they use ``**client.get(...)``
+    # or ``.get(field)`` chains — so we keep the wrapper signature as
+    # ``Dict[str, Any]`` and cast at this boundary. Endpoints that need
+    # array shapes should call ``_request`` directly (or a future
+    # ``.get_list()`` helper) instead of round-tripping through here.
     def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make a GET request."""
-        return self._request("GET", endpoint, params=params)
+        """Make a GET request. Returns the JSON body as a dict."""
+        return cast(Dict[str, Any], self._request("GET", endpoint, params=params))
 
     def post(self, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make a POST request."""
-        return self._request("POST", endpoint, data=data)
+        """Make a POST request. Returns the JSON body as a dict."""
+        return cast(Dict[str, Any], self._request("POST", endpoint, data=data))
 
     def put(self, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make a PUT request."""
-        return self._request("PUT", endpoint, data=data)
+        """Make a PUT request. Returns the JSON body as a dict."""
+        return cast(Dict[str, Any], self._request("PUT", endpoint, data=data))
 
     def delete(self, endpoint: str) -> Dict[str, Any]:
-        """Make a DELETE request."""
-        return self._request("DELETE", endpoint)
+        """Make a DELETE request. Returns the JSON body as a dict."""
+        return cast(Dict[str, Any], self._request("DELETE", endpoint))
 
     def ping(self) -> bool:
         """