cohesion-sdk 1.0.0__py3-none-any.whl

cohesion/__init__.py

@@ -0,0 +1,65 @@
+# Copyright 2026 COHESION AUTH LLC
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# SPDX-License-Identifier: Apache-2.0
+"""Official Python SDK for the COHESION Judgment Independence Score API.
+
+The client surface is locked by the v1.1.0 API pilot-readiness spec.
+Import what you need from the top level::
+
+    from cohesion import (
+        Client,
+        wrap_openai,
+        wrap_anthropic,
+        wrap_azure_openai,
+        LangChainCallback,
+    )
+    from cohesion import (
+        CohesionError,
+        AuthenticationError,
+        RateLimitError,
+        ValidationError,
+        ServerError,
+        NetworkError,
+    )
+"""
+
+from ._version import __version__
+from .client import Client
+from .exceptions import (
+    AuthenticationError,
+    CohesionError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .langchain import LangChainCallback
+from .wrappers import (
+    DecisionReport,
+    WrapContext,
+    WrappedCompletion,
+    wrap_anthropic,
+    wrap_azure_openai,
+    wrap_openai,
+)
+
+__all__ = [
+    "__version__",
+    "Client",
+    "CohesionError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+    "NetworkError",
+    "wrap_openai",
+    "wrap_anthropic",
+    "wrap_azure_openai",
+    "LangChainCallback",
+    "WrapContext",
+    "DecisionReport",
+    "WrappedCompletion",
+]

cohesion/_version.py

@@ -0,0 +1,8 @@
+# Copyright 2026 COHESION AUTH LLC
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "1.0.0"

cohesion/cli.py

@@ -0,0 +1,118 @@
+# Copyright 2026 COHESION AUTH LLC
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# SPDX-License-Identifier: Apache-2.0
+"""``cohesion`` command-line entrypoint.
+
+Usage::
+
+    cohesion score --operator-id X --from-file y.json
+    cohesion score --operator-id X --from-file -     # read from stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._version import __version__
+from .client import Client
+from .exceptions import CohesionError
+
+__all__ = ["main", "build_parser"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cohesion",
+        description="COHESION Judgment Independence Score API command-line tool.",
+    )
+    parser.add_argument("--version", action="version", version=f"cohesion-sdk-python {__version__}")
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("COHESION_BASE_URL", "https://api.cohesionauth.com"),
+        help="API base URL. Defaults to $COHESION_BASE_URL or the production host.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    score = sub.add_parser("score", help="Submit a scoring payload.")
+    score.add_argument("--operator-id", required=True, help="Operator identifier.")
+    score.add_argument(
+        "--from-file",
+        required=True,
+        help="Path to a JSON file containing the scoring payload, or '-' for stdin.",
+    )
+    score.add_argument(
+        "--session-id",
+        default=None,
+        help="Override session_id. Default: file contents.",
+    )
+    score.add_argument(
+        "--domain",
+        default=None,
+        help="Override domain. Default: file contents.",
+    )
+    return parser
+
+
+def _read_payload(path: str) -> dict[str, Any]:
+    raw = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise SystemExit("Payload must be a JSON object.")
+    return data
+
+
+def _resolve_api_key() -> str:
+    key = os.environ.get("COHESION_API_KEY")
+    if not key:
+        raise SystemExit(
+            "COHESION_API_KEY environment variable is required. "
+            "Get your key at cohesionauth.com/dashboard/api-keys."
+        )
+    return key
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "score":
+        payload = _read_payload(args.from_file)
+        if args.session_id:
+            payload["session_id"] = args.session_id
+        if args.domain:
+            payload["domain"] = args.domain
+        payload["operator_id"] = args.operator_id
+
+        client = Client(api_key=_resolve_api_key(), base_url=args.base_url)
+        try:
+            response = client.score(**payload)
+        except CohesionError as err:
+            sys.stderr.write(f"error: {err}\n")
+            if err.next_step:
+                sys.stderr.write(f"next_step: {err.next_step}\n")
+            if err.request_id:
+                sys.stderr.write(f"request_id: {err.request_id}\n")
+            return 1
+        finally:
+            client.close()
+        sys.stdout.write(response.model_dump_json(indent=2) + "\n")
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cohesion/client.py

@@ -0,0 +1,349 @@
+# Copyright 2026 COHESION AUTH LLC
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# SPDX-License-Identifier: Apache-2.0
+"""Cohesion client.
+
+Method surface locked by spec §13.1. Retry with full-jitter exponential
+backoff on 429 + 5xx + NetworkError, max 3 attempts by default, honors
+``Retry-After`` (integer seconds or HTTP-date). ``Idempotency-Key``
+auto-generated as UUIDv4 on every POST.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .exceptions import (
+    AuthenticationError,
+    CohesionError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    error_from_response,
+    sanitize_message,
+)
+from .logging import get_logger
+from .models import (
+    AuditEvent,
+    AuditLogResponse,
+    BatchScoreRequest,
+    BatchScoreResponse,
+    ComplianceReport,
+    Interaction,
+    KeyRevocationResponse,
+    KeyRotationResponse,
+    MaintenanceRecommendation,
+    OperatorProfile,
+    OrganizationDashboard,
+    ScoreRequest,
+    ScoreResponse,
+)
+from .retry import DEFAULT_RETRY_POLICY, RetryPolicy, compute_backoff_ms, is_retryable_status
+from .telemetry import maybe_init_telemetry, report_sdk_error
+
+__all__ = ["Client"]
+
+_DEFAULT_BASE_URL = "https://api.cohesionauth.com"
+_OPERATOR_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,256}$")
+
+
+class Client:
+    """Synchronous client for the COHESION scoring API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        logger: logging.Logger | None = None,
+        enable_telemetry: bool = False,
+        *,
+        http_client: httpx.Client | None = None,
+        retry_policy: RetryPolicy | None = None,
+        sleep: Any | None = None,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._user_agent = f"cohesion-sdk-python/{__version__}"
+        self._logger = get_logger(logger)
+        self._retry_policy = (retry_policy or DEFAULT_RETRY_POLICY).__class__(
+            max_retries=max_retries,
+            base_delay_ms=(retry_policy or DEFAULT_RETRY_POLICY).base_delay_ms,
+            max_delay_ms=(retry_policy or DEFAULT_RETRY_POLICY).max_delay_ms,
+            retryable_statuses=(retry_policy or DEFAULT_RETRY_POLICY).retryable_statuses,
+        )
+        self._sleep = sleep if sleep is not None else time.sleep
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client(timeout=timeout)
+
+        if enable_telemetry:
+            maybe_init_telemetry(True)
+
+    # ───── Lifecycle ──────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # ───── Scoring endpoints ──────────────────────────────────────────────
+
+    def score(self, **kwargs: Any) -> ScoreResponse:
+        req = ScoreRequest.model_validate(kwargs)
+        data = self._request("POST", "/v1/score", json_body=req.model_dump())
+        return ScoreResponse.model_validate(data)
+
+    def score_batch(self, interactions: list[Any]) -> BatchScoreResponse:
+        """Score up to 100 interactions in a single call.
+
+        ``interactions`` accepts either:
+          * a full :class:`BatchScoreRequest` payload as a dict (with
+            ``session_id``, ``operator_id``, ``domain``, ``interactions``), or
+          * a list of interaction dicts/:class:`Interaction` objects, in which
+            case the caller must pass ``session_id``, ``operator_id``, and
+            ``domain`` via the corresponding kwargs in a dict wrapper.
+
+        The most common usage passes a dict matching
+        :class:`BatchScoreRequest`.
+        """
+        if isinstance(interactions, dict):
+            req = BatchScoreRequest.model_validate(interactions)
+        elif isinstance(interactions, list):
+            items = [
+                i if isinstance(i, Interaction) else Interaction.model_validate(i)
+                for i in interactions
+            ]
+            if not items:
+                raise ValidationError(
+                    "interactions list must be non-empty",
+                    field="interactions",
+                )
+            req = BatchScoreRequest.model_validate(
+                {
+                    "session_id": "",
+                    "operator_id": "",
+                    "domain": "general",
+                    "interactions": [i.model_dump() for i in items],
+                }
+            )
+        else:
+            raise ValidationError(
+                "interactions must be a dict (BatchScoreRequest) or a list",
+                field="interactions",
+            )
+        data = self._request("POST", "/v1/score/batch", json_body=req.model_dump())
+        return BatchScoreResponse.model_validate(data)
+
+    def operator_profile(self, operator_id: str) -> OperatorProfile:
+        self._validate_operator_id(operator_id)
+        data = self._request("GET", f"/v1/operator/{operator_id}/profile")
+        return OperatorProfile.model_validate(data)
+
+    def organization_dashboard(self) -> OrganizationDashboard:
+        data = self._request("GET", "/v1/organization/dashboard")
+        return OrganizationDashboard.model_validate(data)
+
+    def maintenance_recommend(self, **kwargs: Any) -> MaintenanceRecommendation:
+        operator_id = kwargs.get("operator_id")
+        if not operator_id or not isinstance(operator_id, str):
+            raise ValidationError("operator_id is required", field="operator_id")
+        self._validate_operator_id(operator_id)
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        data = self._request("POST", "/v1/maintenance/recommend", json_body=body)
+        return MaintenanceRecommendation.model_validate(data)
+
+    def compliance_report(self) -> ComplianceReport:
+        data = self._request("GET", "/v1/compliance/report")
+        return ComplianceReport.model_validate(data)
+
+    # ───── Admin endpoints ───────────────────────────────────────────────
+
+    def admin_key_rotate(self) -> KeyRotationResponse:
+        data = self._request("POST", "/v1/admin/key/rotate", json_body={})
+        return KeyRotationResponse.model_validate(data)
+
+    def admin_key_revoke(self) -> KeyRevocationResponse:
+        data = self._request("POST", "/v1/admin/key/revoke", json_body={})
+        return KeyRevocationResponse.model_validate(data)
+
+    def admin_audit_log(
+        self,
+        event_type: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        limit: int = 100,
+    ) -> list[AuditEvent]:
+        if not 1 <= limit <= 500:
+            raise ValidationError(
+                "limit must be between 1 and 500",
+                field="limit",
+            )
+        params: dict[str, Any] = {"limit": limit}
+        if event_type is not None:
+            params["event_type"] = event_type
+        if since is not None:
+            params["since"] = since
+        if until is not None:
+            params["until"] = until
+        data = self._request("GET", "/v1/admin/audit-log", params=params)
+        resp = AuditLogResponse.model_validate(data)
+        return resp.events
+
+    # ───── Internals ─────────────────────────────────────────────────────
+
+    @staticmethod
+    def _validate_operator_id(operator_id: str) -> None:
+        if not isinstance(operator_id, str) or not _OPERATOR_ID_RE.match(operator_id):
+            raise ValidationError(
+                "operator_id must be 1-256 characters, alphanumeric plus - and _",
+                field="operator_id",
+            )
+
+    def _build_headers(self, method: str, idempotency_key: str | None) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "X-API-Key": self._api_key,
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if method == "POST":
+            headers["Content-Type"] = "application/json"
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = self._build_headers(method, idempotency_key)
+
+        last_error: CohesionError | None = None
+
+        # total attempts = max_retries + 1
+        for attempt in range(self._max_retries + 1):
+            try:
+                self._logger.debug("HTTP %s %s", method, path, extra={"attempt": attempt})
+                response = self._http.request(
+                    method,
+                    url,
+                    headers=headers,
+                    params=params,
+                    json=json_body if method == "POST" else None,
+                    timeout=self._timeout,
+                )
+            except httpx.TimeoutException as exc:
+                err = NetworkError(
+                    sanitize_message(f"Request timed out after {self._timeout}s: {exc}"),
+                    next_step=(
+                        "Check connectivity to api.cohesionauth.com and ensure TLS 1.3 "
+                        "egress is permitted from your environment."
+                    ),
+                )
+                last_error = err
+                if attempt < self._max_retries:
+                    delay_ms = compute_backoff_ms(attempt, self._retry_policy)
+                    self._logger.warning(
+                        "Transport timeout. Sleeping %dms.",
+                        delay_ms,
+                        extra={"attempt": attempt},
+                    )
+                    self._sleep(delay_ms / 1000.0)
+                    continue
+                report_sdk_error(err)
+                raise err from exc
+            except httpx.HTTPError as exc:
+                err = NetworkError(
+                    sanitize_message(f"Network error: {exc}"),
+                    next_step=(
+                        "Check connectivity to api.cohesionauth.com and ensure TLS 1.3 "
+                        "egress is permitted from your environment."
+                    ),
+                )
+                last_error = err
+                if attempt < self._max_retries:
+                    delay_ms = compute_backoff_ms(attempt, self._retry_policy)
+                    self._logger.warning(
+                        "Transport error. Sleeping %dms.",
+                        delay_ms,
+                        extra={"attempt": attempt},
+                    )
+                    self._sleep(delay_ms / 1000.0)
+                    continue
+                report_sdk_error(err)
+                raise err from exc
+
+            if 200 <= response.status_code < 300:
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise ServerError(
+                        "Server returned non-JSON response.",
+                        status_code=response.status_code,
+                    ) from exc
+
+            envelope: dict[str, Any] | None
+            try:
+                envelope = response.json()
+                if not isinstance(envelope, dict):
+                    envelope = None
+            except ValueError:
+                envelope = None
+
+            retry_after_header = response.headers.get("Retry-After")
+            err = error_from_response(response.status_code, envelope, retry_after_header)
+            last_error = err
+
+            if attempt < self._max_retries and is_retryable_status(
+                response.status_code, self._retry_policy
+            ):
+                retry_after_ms = err.retry_after * 1000 if isinstance(err, RateLimitError) else None
+                delay_ms = compute_backoff_ms(attempt, self._retry_policy, retry_after_ms)
+                self._logger.warning(
+                    "Retryable %d. Sleeping %dms.",
+                    response.status_code,
+                    delay_ms,
+                    extra={"attempt": attempt, "request_id": err.request_id},
+                )
+                self._sleep(delay_ms / 1000.0)
+                continue
+
+            if isinstance(
+                err,
+                AuthenticationError
+                | RateLimitError
+                | ValidationError
+                | ServerError
+                | CohesionError,
+            ):
+                report_sdk_error(err)
+            raise err
+
+        # Unreachable: loop either returns or raises.
+        assert last_error is not None  # nosec B101 - unreachable safety net, loop invariant guarantees last_error is set
+        raise last_error