agentrust-py 0.0.3__py3-none-any.whl

agentrust_sdk/queue_replay.py

@@ -0,0 +1,204 @@
+"""
+queue_replay.py — Replay-on-reconnect helper for AgentTrust SDK.
+
+After each successful validate() call, maybe_drain_on_success() checks
+whether there are pending records in the local queue DB and, if so,
+drains up to 50 of them in a daemon background thread.
+
+A module-level cooldown (_DRAIN_COOLDOWN = 60 s) prevents spawning a
+drain thread more than once per minute regardless of how many successful
+validate() calls arrive in quick succession.
+"""
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Cooldown state
+# ---------------------------------------------------------------------------
+
+_last_drain_attempt: float = 0.0
+_DRAIN_COOLDOWN: float = 60.0
+_drain_lock = threading.Lock()
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+_MAX_DRAIN_ITEMS = 50
+
+
+def maybe_drain_on_success(
+    gateway_url: str,
+    headers: dict,
+    queue_db: Path,
+) -> None:
+    """Call this after each successful validate() response.
+
+    If the queue DB has pending rows *and* the cooldown has elapsed, a
+    daemon thread is spawned to drain up to _MAX_DRAIN_ITEMS records.
+    Returns immediately (non-blocking).
+
+    Args:
+        gateway_url: Full base URL of the AgentTrust gateway
+                     (e.g. ``"https://gateway.agentrust.ai"``).
+        headers:     HTTP headers to use for replay requests
+                     (should include ``X-AgentTrust-Token`` etc.).
+        queue_db:    :class:`pathlib.Path` to the SQLite queue database.
+    """
+    global _last_drain_attempt
+
+    # Fast path — no DB file at all.
+    if not queue_db.exists():
+        return
+
+    now = time.monotonic()
+
+    with _drain_lock:
+        if now - _last_drain_attempt < _DRAIN_COOLDOWN:
+            return  # Still within cooldown window; skip.
+
+        # Check whether the DB actually has pending rows before committing
+        # to spawning a thread.
+        pending = _pending_count(queue_db)
+        if pending == 0:
+            return
+
+        _last_drain_attempt = now  # Claim the slot inside the lock.
+
+    logger.debug(
+        "[AgentTrust] replay-on-reconnect: %d pending record(s) found; "
+        "spawning background drain (max %d).",
+        pending,
+        _MAX_DRAIN_ITEMS,
+    )
+
+    t = threading.Thread(
+        target=_drain_worker,
+        args=(gateway_url, headers, queue_db),
+        daemon=True,
+        name="agentrust-queue-drain",
+    )
+    t.start()
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _pending_count(queue_db: Path) -> int:
+    """Return the number of rows in the queue table, or 0 on any error."""
+    try:
+        con = sqlite3.connect(str(queue_db))
+        try:
+            row = con.execute("SELECT COUNT(*) FROM queue").fetchone()
+            return int(row[0]) if row else 0
+        finally:
+            con.close()
+    except Exception as exc:
+        logger.debug("[AgentTrust] queue_replay: could not count queue rows: %s", exc)
+        return 0
+
+
+def _drain_worker(
+    gateway_url: str,
+    headers: dict,
+    queue_db: Path,
+) -> None:
+    """Background thread: drain up to _MAX_DRAIN_ITEMS from the queue.
+
+    Imports drain_queue() from client at call-time to avoid circular
+    imports at module load.  All exceptions are caught and logged.
+    """
+    try:
+        from agentrust_sdk.client import drain_queue  # local import avoids circular dep
+
+        sent, failed = _drain_limited(
+            gateway_url=gateway_url,
+            headers=headers,
+            queue_db=queue_db,
+            limit=_MAX_DRAIN_ITEMS,
+        )
+        logger.info(
+            "[AgentTrust] replay-on-reconnect complete: sent=%d failed=%d",
+            sent,
+            failed,
+        )
+    except Exception as exc:
+        logger.error(
+            "[AgentTrust] replay-on-reconnect background thread raised: %s",
+            exc,
+            exc_info=True,
+        )
+
+
+def _drain_limited(
+    gateway_url: str,
+    headers: dict,
+    queue_db: Path,
+    limit: int,
+) -> tuple[int, int]:
+    """Replay up to *limit* records from queue_db against gateway_url.
+
+    This is a self-contained implementation that mirrors the logic in
+    ``drain_queue()`` but accepts explicit gateway_url / headers and
+    caps the number of rows processed so that a very large backlog does
+    not block the daemon thread indefinitely.
+    """
+    import json
+
+    import httpx
+
+    from .config import SDK_CONFIG  # for _VALIDATE_PATH equivalent
+
+    _VALIDATE_PATH = "/v1/runtime/validate"
+    _url = gateway_url.rstrip("/")
+
+    if not queue_db.exists():
+        return 0, 0
+
+    try:
+        con = sqlite3.connect(str(queue_db))
+    except Exception as exc:
+        logger.error("[AgentTrust] replay-on-reconnect: cannot open queue DB: %s", exc)
+        return 0, 0
+
+    try:
+        rows = con.execute(
+            "SELECT id, payload FROM queue ORDER BY id LIMIT ?", (limit,)
+        ).fetchall()
+    except Exception as exc:
+        logger.error("[AgentTrust] replay-on-reconnect: cannot read queue DB: %s", exc)
+        con.close()
+        return 0, 0
+
+    sent = 0
+    failed = 0
+    timeout = SDK_CONFIG.timeout_sec
+
+    for row_id, raw in rows:
+        try:
+            payload = json.loads(raw)
+            with httpx.Client(base_url=_url, headers=headers, timeout=timeout) as http:
+                resp = http.post(_VALIDATE_PATH, json=payload)
+                resp.raise_for_status()
+            con.execute("DELETE FROM queue WHERE id = ?", (row_id,))
+            con.commit()
+            sent += 1
+        except Exception as exc:
+            logger.warning(
+                "[AgentTrust] replay-on-reconnect: record %d failed: %s",
+                row_id,
+                exc,
+            )
+            failed += 1
+
+    con.close()
+    return sent, failed

agentrust_sdk/tiers.py

@@ -0,0 +1,180 @@
+"""
+Tier and capability definitions for AgentTrust SDK.
+
+Every capability maps to a minimum tier. The SDK reads the tier from the
+API key JWT and silently skips (never blocks) capabilities above the tier.
+
+Tier order (ascending):  oss → free → developer → team → enterprise
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Tier(str, Enum):
+    OSS = "oss"
+    FREE = "free"
+    DEVELOPER = "developer"
+    TEAM = "team"
+    ENTERPRISE = "enterprise"
+
+    def __ge__(self, other: "Tier") -> bool:
+        return _TIER_ORDER[self] >= _TIER_ORDER[other]
+
+    def __gt__(self, other: "Tier") -> bool:
+        return _TIER_ORDER[self] > _TIER_ORDER[other]
+
+    def __le__(self, other: "Tier") -> bool:
+        return _TIER_ORDER[self] <= _TIER_ORDER[other]
+
+    def __lt__(self, other: "Tier") -> bool:
+        return _TIER_ORDER[self] < _TIER_ORDER[other]
+
+
+_TIER_ORDER: dict[Tier, int] = {
+    Tier.OSS: 0,
+    Tier.FREE: 1,
+    Tier.DEVELOPER: 2,
+    Tier.TEAM: 3,
+    Tier.ENTERPRISE: 4,
+}
+
+
+class Capability(str, Enum):
+    # ── Validation ──────────────────────────────────────────────────────────
+    SCHEMA_VALIDATION = "schema_validation"           # OSS
+    EVIDENCE_VALIDATION = "evidence_validation"       # Free
+    TOOL_TRUST_CHECK = "tool_trust_check"             # Free
+    CONTRADICTION_DETECTION = "contradiction_detection"  # Free
+    CONSISTENCY_CHECK = "consistency_check"           # Free
+
+    # ── Confidence & Risk ───────────────────────────────────────────────────
+    CONFIDENCE_ENGINE = "confidence_engine"           # Developer
+    RISK_SCORING = "risk_scoring"                     # Developer
+    HISTORICAL_RELIABILITY = "historical_reliability" # Developer
+    LLM_JUDGE_OLLAMA = "llm_judge_ollama"             # Enterprise
+    LLM_JUDGE_CLAUDE = "llm_judge_claude"             # Enterprise
+
+    # ── Decision & Policy ───────────────────────────────────────────────────
+    AUTO_DECISION = "auto_decision"                   # Free
+    BUILTIN_POLICY_PACKS = "builtin_policy_packs"     # Developer
+    CUSTOM_POLICIES = "custom_policies"               # Team
+    POLICY_VERSIONING = "policy_versioning"           # Team
+    POLICY_SYNC = "policy_sync"                       # Team
+
+    # ── Audit & Observability ───────────────────────────────────────────────
+    LOCAL_AUDIT = "local_audit"                       # Free
+    CENTRAL_AUDIT = "central_audit"                   # Team
+    HASH_CHAIN_AUDIT = "hash_chain_audit"             # Enterprise
+    ANALYTICS = "analytics"                           # Team
+    SOC2_EXPORT = "soc2_export"                       # Enterprise
+
+    # ── Operations & Collaboration ──────────────────────────────────────────
+    REVIEW_QUEUE = "review_queue"                     # Team
+    ALERT_ENGINE = "alert_engine"                     # Team
+    WEBHOOKS = "webhooks"                             # Team
+    TEAM_MANAGEMENT = "team_management"               # Team
+    SSO_SAML = "sso_saml"                             # Enterprise
+
+    # ── Multi-Agent & Trust ─────────────────────────────────────────────────
+    TRUST_CHAIN = "trust_chain"                       # Enterprise
+    RATE_LIMITER = "rate_limiter"                     # Enterprise
+
+    # ── SDK & Integrations ──────────────────────────────────────────────────
+    LANGGRAPH_ADAPTER = "langgraph_adapter"           # Team
+    CREWAI_ADAPTER = "crewai_adapter"                 # Team
+    MCP_ADAPTER = "mcp_adapter"                       # Developer
+    AUTOGEN_ADAPTER = "autogen_adapter"               # Team
+    CLAUDE_AGENTS_ADAPTER = "claude_agents_adapter"   # Team
+    OPENAI_AGENTS_ADAPTER = "openai_agents_adapter"   # Team
+    CLI_FULL = "cli_full"                             # Developer
+    SELF_HOSTED = "self_hosted"                       # Enterprise
+
+
+# Maps each capability to the minimum tier required
+CAPABILITY_MIN_TIER: dict[Capability, Tier] = {
+    # Validation
+    Capability.SCHEMA_VALIDATION: Tier.OSS,
+    Capability.EVIDENCE_VALIDATION: Tier.FREE,
+    Capability.TOOL_TRUST_CHECK: Tier.FREE,
+    Capability.CONTRADICTION_DETECTION: Tier.FREE,
+    Capability.CONSISTENCY_CHECK: Tier.FREE,
+
+    # Confidence & Risk
+    Capability.CONFIDENCE_ENGINE: Tier.DEVELOPER,
+    Capability.RISK_SCORING: Tier.DEVELOPER,
+    Capability.HISTORICAL_RELIABILITY: Tier.DEVELOPER,
+    Capability.LLM_JUDGE_OLLAMA: Tier.ENTERPRISE,
+    Capability.LLM_JUDGE_CLAUDE: Tier.ENTERPRISE,
+
+    # Decision & Policy
+    Capability.AUTO_DECISION: Tier.FREE,
+    Capability.BUILTIN_POLICY_PACKS: Tier.DEVELOPER,
+    Capability.CUSTOM_POLICIES: Tier.TEAM,
+    Capability.POLICY_VERSIONING: Tier.TEAM,
+    Capability.POLICY_SYNC: Tier.TEAM,
+
+    # Audit
+    Capability.LOCAL_AUDIT: Tier.FREE,
+    Capability.CENTRAL_AUDIT: Tier.TEAM,
+    Capability.HASH_CHAIN_AUDIT: Tier.ENTERPRISE,
+    Capability.ANALYTICS: Tier.TEAM,
+    Capability.SOC2_EXPORT: Tier.ENTERPRISE,
+
+    # Operations
+    Capability.REVIEW_QUEUE: Tier.TEAM,
+    Capability.ALERT_ENGINE: Tier.TEAM,
+    Capability.WEBHOOKS: Tier.TEAM,
+    Capability.TEAM_MANAGEMENT: Tier.TEAM,
+    Capability.SSO_SAML: Tier.ENTERPRISE,
+
+    # Multi-agent
+    Capability.TRUST_CHAIN: Tier.ENTERPRISE,
+    Capability.RATE_LIMITER: Tier.ENTERPRISE,
+
+    # SDK
+    Capability.LANGGRAPH_ADAPTER: Tier.TEAM,
+    Capability.CREWAI_ADAPTER: Tier.TEAM,
+    Capability.MCP_ADAPTER: Tier.DEVELOPER,
+    Capability.AUTOGEN_ADAPTER: Tier.TEAM,
+    Capability.CLAUDE_AGENTS_ADAPTER: Tier.TEAM,
+    Capability.OPENAI_AGENTS_ADAPTER: Tier.TEAM,
+    Capability.CLI_FULL: Tier.DEVELOPER,
+    Capability.SELF_HOSTED: Tier.ENTERPRISE,
+}
+
+
+def is_allowed(capability: Capability, tier: Tier) -> bool:
+    """Return True if the given tier can use this capability."""
+    min_tier = CAPABILITY_MIN_TIER.get(capability, Tier.ENTERPRISE)
+    return tier >= min_tier
+
+
+def allowed_capabilities(tier: Tier) -> list[Capability]:
+    """Return all capabilities available on a given tier."""
+    return [cap for cap, min_t in CAPABILITY_MIN_TIER.items() if tier >= min_t]
+
+
+# Human-readable upgrade messages
+UPGRADE_MESSAGES: dict[Capability, str] = {
+    Capability.CONFIDENCE_ENGINE: "Confidence scoring requires Developer tier ($29/mo). Upgrade: agentrust upgrade",
+    Capability.RISK_SCORING: "Risk scoring requires Developer tier ($29/mo). Upgrade: agentrust upgrade",
+    Capability.BUILTIN_POLICY_PACKS: "Policy packs require Developer tier ($29/mo). Upgrade: agentrust upgrade",
+    Capability.CUSTOM_POLICIES: "Custom policies require Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.POLICY_SYNC: "Policy sync requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.CENTRAL_AUDIT: "Central audit requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.ANALYTICS: "Analytics require Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.REVIEW_QUEUE: "Review queue requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.ALERT_ENGINE: "Alert engine requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.LANGGRAPH_ADAPTER: "LangGraph adapter requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.CREWAI_ADAPTER: "CrewAI adapter requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.MCP_ADAPTER: "MCP adapter requires Developer tier ($29/mo). Upgrade: agentrust upgrade",
+    Capability.AUTOGEN_ADAPTER: "AutoGen adapter requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.CLAUDE_AGENTS_ADAPTER: "Claude Agents adapter requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.OPENAI_AGENTS_ADAPTER: "OpenAI Agents adapter requires Team tier ($149/mo). Upgrade: agentrust upgrade",
+    Capability.TRUST_CHAIN: "Trust chain requires Enterprise tier. Contact: sales@agentrust.io",
+    Capability.LLM_JUDGE_CLAUDE: "LLM Judge requires Enterprise tier. Contact: sales@agentrust.io",
+    Capability.SSO_SAML: "SSO/SAML requires Enterprise tier. Contact: sales@agentrust.io",
+    Capability.SELF_HOSTED: "Self-hosted control plane requires Enterprise tier. Contact: sales@agentrust.io",
+    Capability.SOC2_EXPORT: "SOC2 audit export requires Enterprise tier. Contact: sales@agentrust.io",
+}

agentrust_sdk/version_negotiation.py

@@ -0,0 +1,290 @@
+"""
+AgentTrust SDK — version negotiation.
+
+Handles SDK/gateway version compatibility checks and header-based negotiation.
+
+Supported gateway versions for forward-compatibility checks:
+    SUPPORTED_GATEWAY_VERSIONS
+
+Typical usage
+-------------
+    from .version_negotiation import check_response_version
+    check_response_version(response.headers, SDK_CONFIG.sdk_version)
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from .config import SDK_CONFIG
+
+# ---------------------------------------------------------------------------
+# Module-level constants
+# ---------------------------------------------------------------------------
+
+SUPPORTED_GATEWAY_VERSIONS: list[str] = ["0.0.1a1", "0.0.2", "0.1.0"]
+
+_HEADER_MIN_SDK = "X-AgentTrust-Min-SDK-Version"
+_HEADER_GATEWAY = "X-AgentTrust-Gateway-Version"
+
+# Matches "1.2.3", "0.0.1a1", "1.2.3b4", "0.1.0rc2", etc.
+_SEMVER_RE = re.compile(
+    r"^(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:[a-zA-Z].*)?$"
+)
+
+
+# ---------------------------------------------------------------------------
+# Exception
+# ---------------------------------------------------------------------------
+
+
+class VersionNegotiationError(Exception):
+    """Raised when SDK and gateway versions are incompatible.
+
+    Attributes
+    ----------
+    sdk_ver       : SDK version string reported by this library.
+    gateway_ver   : Gateway version string extracted from the response headers
+                    (may be None if the gateway did not advertise one).
+    min_required  : Minimum SDK version the gateway requires.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        sdk_ver: str,
+        gateway_ver: Optional[str],
+        min_required: str,
+    ) -> None:
+        super().__init__(message)
+        self.sdk_ver = sdk_ver
+        self.gateway_ver = gateway_ver
+        self.min_required = min_required
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"VersionNegotiationError({str(self)!r}, "
+            f"sdk_ver={self.sdk_ver!r}, "
+            f"gateway_ver={self.gateway_ver!r}, "
+            f"min_required={self.min_required!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Core helpers
+# ---------------------------------------------------------------------------
+
+
+def parse_semver(v: str) -> tuple[int, int, int]:
+    """Parse a version string into a (major, minor, patch) integer tuple.
+
+    Pre-release labels (``a1``, ``b2``, ``rc3``, …) and build metadata
+    attached to the patch segment are stripped before comparison so that
+    ``"0.0.1a1"`` and ``"0.0.1"`` compare as equal by numeric precedence.
+
+    Parameters
+    ----------
+    v:
+        A version string such as ``"1.2.3"``, ``"0.0.1a1"``, or ``"1.0.0rc2"``.
+
+    Returns
+    -------
+    tuple[int, int, int]
+        ``(major, minor, patch)`` as integers.
+
+    Raises
+    ------
+    ValueError
+        If *v* cannot be parsed as a semantic version.
+    """
+    v = v.strip()
+    m = _SEMVER_RE.match(v)
+    if not m:
+        raise ValueError(
+            f"Cannot parse {v!r} as a semantic version — "
+            "expected MAJOR.MINOR.PATCH[pre-release]"
+        )
+    return (int(m.group("major")), int(m.group("minor")), int(m.group("patch")))
+
+
+def is_compatible(
+    sdk_version: str,
+    gateway_version: str,
+    min_gateway: str,
+) -> tuple[bool, str]:
+    """Check whether *sdk_version* satisfies the gateway's minimum requirement.
+
+    Compatibility rule (semver precedence, pre-release labels ignored):
+        sdk_version >= min_gateway
+
+    Parameters
+    ----------
+    sdk_version:
+        The version of this SDK (e.g. ``SDK_CONFIG.sdk_version``).
+    gateway_version:
+        The version the gateway reported (used only for diagnostic messages).
+    min_gateway:
+        The minimum SDK version the gateway will accept.
+
+    Returns
+    -------
+    tuple[bool, str]
+        ``(True, "")`` when compatible; ``(False, reason)`` otherwise.
+    """
+    try:
+        sdk_tuple = parse_semver(sdk_version)
+    except ValueError as exc:
+        return False, f"Invalid SDK version {sdk_version!r}: {exc}"
+
+    try:
+        min_tuple = parse_semver(min_gateway)
+    except ValueError as exc:
+        return False, f"Invalid minimum gateway version {min_gateway!r}: {exc}"
+
+    try:
+        parse_semver(gateway_version)
+    except ValueError:
+        # Gateway version is informational only; don't fail on bad value.
+        pass
+
+    if sdk_tuple >= min_tuple:
+        return True, ""
+
+    return False, (
+        f"SDK version {sdk_version} is below the minimum required "
+        f"{min_gateway} (gateway {gateway_version}). "
+        "Please upgrade the agentrust-sdk package."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Header extraction
+# ---------------------------------------------------------------------------
+
+
+def negotiate_header(response_headers: dict) -> Optional[str]:
+    """Extract ``X-AgentTrust-Min-SDK-Version`` from *response_headers*.
+
+    Header lookup is case-insensitive to accommodate both raw ``http.client``
+    responses (which lowercase headers) and ``requests``/``httpx`` mappings
+    (which preserve original casing but expose case-insensitive access only
+    via their own classes — here we normalise manually).
+
+    Parameters
+    ----------
+    response_headers:
+        A plain dict or any mapping of response header names → values.
+
+    Returns
+    -------
+    str or None
+        The header value if present, ``None`` otherwise.
+    """
+    target_lower = _HEADER_MIN_SDK.lower()
+    for key, value in response_headers.items():
+        if key.lower() == target_lower:
+            return str(value).strip()
+    return None
+
+
+def _extract_gateway_version(response_headers: dict) -> Optional[str]:
+    """Extract ``X-AgentTrust-Gateway-Version`` for diagnostic use."""
+    target_lower = _HEADER_GATEWAY.lower()
+    for key, value in response_headers.items():
+        if key.lower() == target_lower:
+            return str(value).strip()
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Primary public entry point
+# ---------------------------------------------------------------------------
+
+
+def check_response_version(
+    resp_headers: dict,
+    sdk_version: str,
+) -> None:
+    """Validate that the current SDK satisfies the gateway's version requirement.
+
+    Reads ``X-AgentTrust-Min-SDK-Version`` from *resp_headers*. If the header
+    is absent no check is performed (the gateway is treated as compatible).
+
+    Parameters
+    ----------
+    resp_headers:
+        Response headers from the gateway (plain dict or mapping).
+    sdk_version:
+        The version of this SDK to validate against the requirement.
+
+    Raises
+    ------
+    VersionNegotiationError
+        When the SDK version is below the gateway's stated minimum.
+    """
+    min_required = negotiate_header(resp_headers)
+    if min_required is None:
+        # Gateway did not advertise a minimum; assume compatible.
+        return
+
+    gateway_ver = _extract_gateway_version(resp_headers)
+
+    ok, reason = is_compatible(
+        sdk_version=sdk_version,
+        gateway_version=gateway_ver or "unknown",
+        min_gateway=min_required,
+    )
+
+    if not ok:
+        raise VersionNegotiationError(
+            reason,
+            sdk_ver=sdk_version,
+            gateway_ver=gateway_ver,
+            min_required=min_required,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Metadata helper
+# ---------------------------------------------------------------------------
+
+
+def get_version_info() -> dict:
+    """Return a dict with full version metadata for this SDK installation.
+
+    Keys
+    ----
+    sdk_version              Current SDK version string.
+    min_gateway_version      Minimum gateway version this SDK requires.
+    supported_gateway_versions
+                             List of gateway versions explicitly tested for
+                             forward-compatibility.
+    sdk_semver               ``(major, minor, patch)`` tuple for the SDK version.
+    min_gateway_semver       ``(major, minor, patch)`` tuple for the minimum
+                             gateway version.
+    negotiation_header       The HTTP header name used for version negotiation.
+    gateway_version_header   The HTTP header name used by the gateway to
+                             advertise its own version.
+    """
+    sdk_ver = SDK_CONFIG.sdk_version
+    min_gw = SDK_CONFIG.min_gateway_version
+
+    try:
+        sdk_semver = parse_semver(sdk_ver)
+    except ValueError:
+        sdk_semver = None  # type: ignore[assignment]
+
+    try:
+        min_gw_semver = parse_semver(min_gw)
+    except ValueError:
+        min_gw_semver = None  # type: ignore[assignment]
+
+    return {
+        "sdk_version": sdk_ver,
+        "min_gateway_version": min_gw,
+        "supported_gateway_versions": list(SUPPORTED_GATEWAY_VERSIONS),
+        "sdk_semver": sdk_semver,
+        "min_gateway_semver": min_gw_semver,
+        "negotiation_header": _HEADER_MIN_SDK,
+        "gateway_version_header": _HEADER_GATEWAY,
+    }