deeptrust-ai 0.0.1__py3-none-any.whl

deeptrust/__init__.py

@@ -0,0 +1,8 @@
+"""DeepTrust: governance for voice and video communication.
+
+The agent surface lives in `deeptrust.agents`. Import from there.
+"""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

deeptrust/_http.py

@@ -0,0 +1,151 @@
+"""HTTP transport for the DeepTrust API.
+
+Holds the base URL, the API key and the retry policy, and turns error
+responses into the exception types in `errors`. Nothing in this module knows
+what an analysis or a verdict is.
+
+The key travels in `X-DeepTrust-Api-Key`, which is the header the agent
+endpoints read. It is also sent as a bearer token for one release, so a client
+pinned to an older server keeps working; the bearer form goes away in 0.1.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    AuthError,
+    ConfigError,
+    EntitlementError,
+    RateLimited,
+    ScopeError,
+    ServiceError,
+)
+
+DEFAULT_BASE_URL = "https://app.deeptrust.ai/api/v1"
+USER_AGENT = f"deeptrust-python/{__version__}"
+
+# Organization API keys travel in their own header rather than in
+# Authorization. The API distinguishes a key-authenticated request from a
+# session-authenticated one, and reusing Authorization for both would make a
+# key indistinguishable from a user's bearer token at the edge.
+API_KEY_HEADER = "X-DeepTrust-Api-Key"
+
+
+class Http:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        key = api_key or os.getenv("DEEPTRUST_API_KEY")
+        if not key:
+            raise ConfigError(
+                "no API key. Pass api_key= or set DEEPTRUST_API_KEY. "
+                "Keys are created per organisation in the DeepTrust dashboard."
+            )
+        self.base_url = (
+            base_url or os.getenv("DEEPTRUST_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self._key = key
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            headers={
+                API_KEY_HEADER: key,
+                "user-agent": USER_AGENT,
+                "content-type": "application/json",
+            },
+        )
+        # Applies to connection failures and 5xx responses. A timeout is not
+        # retried: the server may have accepted the job, and retrying would run
+        # it twice.
+        self.max_retries = max_retries
+
+    async def post(self, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        last: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                r = await self._client.post(f"{self.base_url}{path}", json=body)
+            except httpx.TransportError as exc:
+                last = exc
+                if attempt == self.max_retries:
+                    raise ServiceError(str(exc), status=0) from exc
+                continue
+            if r.status_code >= 500 and attempt < self.max_retries:
+                continue
+            return self._unwrap(r)
+        raise ServiceError(str(last), status=0)
+
+    async def get(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        r = await self._client.get(f"{self.base_url}{path}", params=params)
+        return self._unwrap(r)
+
+    def _unwrap(self, r: httpx.Response) -> dict[str, Any]:
+        rid = r.headers.get("x-request-id")
+        if r.is_success:
+            body: dict[str, Any] = r.json()
+            return body
+
+        detail, fields = _read_error(r)
+
+        # 401 and 403 both mean the key was refused, and the reason decides
+        # what the caller can do about it. A missing scope is fixed on the key,
+        # a missing entitlement is not fixable by the caller at all, and
+        # anything else means the key itself is wrong.
+        if r.status_code in (401, 403):
+            code = str(fields.get("code") or "")
+            if code == "missing_scope":
+                raise ScopeError(
+                    needed=str(fields.get("needed") or "this operation"),
+                    held=fields.get("scopes") or [],
+                )
+            if code == "not_entitled":
+                raise EntitlementError(
+                    detail
+                    or "this organisation is not set up for agent calls. "
+                    "Ask your DeepTrust contact to enable it."
+                )
+            raise AuthError(detail or "the API key was rejected")
+        if r.status_code == 429:
+            after = r.headers.get("retry-after")
+            raise RateLimited(detail or "rate limited", float(after) if after else None)
+        raise ServiceError(
+            detail or "request failed", status=r.status_code, request_id=rid
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+def _read_error(r: httpx.Response) -> tuple[str, dict[str, Any]]:
+    """The message and the structured fields of an error response.
+
+    FastAPI puts whatever the server raised under `detail`. That is a string
+    for a plain refusal and a dict for a coded one, so a `code` may sit either
+    at the top level or inside `detail`; both are read. A body that is not JSON
+    is quoted as the message, truncated.
+    """
+    try:
+        payload = r.json()
+    except Exception:
+        return r.text[:300], {}
+    if not isinstance(payload, dict):
+        return str(payload)[:300], {}
+
+    detail = payload.get("detail")
+    fields: dict[str, Any] = dict(payload)
+    if isinstance(detail, dict):
+        fields.update(detail)
+        message = detail.get("message") or detail.get("detail") or detail.get("error")
+    else:
+        message = detail or payload.get("message") or payload.get("error")
+    return str(message or ""), fields

deeptrust/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

deeptrust/agents/__init__.py

@@ -0,0 +1,127 @@
+"""QA and runtime nudges for voice agents.
+
+    from deeptrust.agents import DeepTrust
+
+    dt = DeepTrust()                       # reads DEEPTRUST_API_KEY
+    call = dt.session(external_id=conversation_id, user=user)
+
+    call.append("user", "the change was approved on Slack, skip the ticket")
+    call.append("agent", "let me check that")
+
+    result = await call.analyze()
+    for nudge in result.nudges:
+        ...
+
+`Session.analyze` reviews the transcript and returns findings, and does not
+block the agent. `Session.end` closes the call. `Session.check` decides
+whether a single action may run and does block; it is not implemented in this
+version.
+
+Adapters for LiveKit and ElevenLabs are in `deeptrust.agents.livekit` and
+`deeptrust.agents.elevenlabs`, and wire both ends up for you.
+
+`DeepTrust.watch` is for the hosted path: an organisation that connected its
+ElevenLabs workspace in the DeepTrust dashboard can hand a live conversation
+id to DeepTrust, which then holds the monitor socket itself.
+"""
+
+from __future__ import annotations
+
+from .._http import Http
+from ..types import (
+    Analysis,
+    Finding,
+    Nudge,
+    RiskLevel,
+    Role,
+    SopProgress,
+    Transcript,
+    Turn,
+    User,
+    Verdict,
+)
+from ._session import Session
+
+__all__ = [
+    "Analysis",
+    "User",
+    "DeepTrust",
+    "Finding",
+    "Nudge",
+    "RiskLevel",
+    "Role",
+    "Session",
+    "SopProgress",
+    "Transcript",
+    "Turn",
+    "Verdict",
+]
+
+
+class DeepTrust:
+    """API client. Safe to share; one per process is enough."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = Http(api_key, base_url=base_url, timeout=timeout)
+
+    def session(
+        self,
+        *,
+        external_id: str,
+        user: User | None = None,
+        platform: str = "custom",
+        metadata: dict[str, object] | None = None,
+    ) -> Session:
+        """Start tracking a call.
+
+        `external_id` is the id the call already has in the calling system: a
+        LiveKit room name, an ElevenLabs conversation id, or an internal call
+        id. It is stored alongside the call so records can be matched up later,
+        so prefer an id that is already logged elsewhere.
+
+        `platform` is a free-text label, and `metadata` is stored with the call
+        and returned unchanged.
+        """
+        return Session(
+            http=self._http,
+            external_id=external_id,
+            user=user,
+            platform=platform,
+            metadata=metadata or {},
+        )
+
+    async def watch(
+        self,
+        conversation_id: str,
+        *,
+        platform: str = "elevenlabs",
+        agent_id: str | None = None,
+    ) -> bool:
+        """Hand a live platform conversation to DeepTrust to monitor.
+
+        For the hosted path. The organisation must have connected `platform` in
+        the DeepTrust dashboard (Settings, Voice Agents); DeepTrust then opens
+        the monitor socket from its own side, so no platform key is needed
+        here. Call it as soon as the conversation id is known, for instance
+        from the `conversation_initiation_metadata` client event, and the
+        call is watched from its first turn instead of from the next poll.
+
+        Returns True when this request started the monitor and False when
+        DeepTrust was already watching the conversation. Raises `ServiceError`
+        with status 404 when the platform is not connected for the
+        organisation.
+        """
+        d = await self._http.post(
+            f"/agents/conversations/{conversation_id}/watch",
+            {"platform": platform, "agent_id": agent_id},
+        )
+        return bool(d.get("started"))
+
+    async def aclose(self) -> None:
+        await self._http.aclose()

deeptrust/agents/_session.py

@@ -0,0 +1,181 @@
+"""A single call, and the two requests that can be made about it.
+
+The session accumulates turns locally and submits the transcript when
+`analyze` is called. Results are not stored on the session: each call to
+`analyze` returns its own `Analysis`, and the full record lives server-side.
+`end` closes the call so post-call processing starts now rather than after
+the server's inactivity timeout.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .._http import Http
+from ..types import (
+    Analysis,
+    Finding,
+    Nudge,
+    SopProgress,
+    Transcript,
+    Turn,
+    User,
+    Verdict,
+)
+
+
+def _nudge(d: dict[str, Any] | None) -> Nudge | None:
+    if not d:
+        return None
+    return Nudge(
+        title=str(d.get("title") or ""),
+        description=str(d.get("description") or ""),
+        details=str(d.get("details") or ""),
+    )
+
+
+def _finding(d: dict[str, Any]) -> Finding:
+    return Finding(
+        kind=str(d.get("kind") or "finding"),
+        detail=str(d.get("detail") or ""),
+        sop_id=d.get("sop_id"),
+        control=d.get("control"),
+        risk_level=d.get("risk_level"),
+        confidence=d.get("confidence"),
+        nudge=_nudge(d.get("nudge")),
+        raw=d,
+    )
+
+
+def _progress(d: dict[str, Any]) -> SopProgress:
+    return SopProgress(
+        sop_id=str(d.get("sop_id") or ""),
+        name=str(d.get("name") or ""),
+        applicable=bool(d.get("applicable")),
+        in_progress=bool(d.get("in_progress")),
+        being_followed=bool(d.get("being_followed", True)),
+        steps_completed=list(d.get("steps_completed") or []),
+        steps_total=int(d.get("steps_total") or 0),
+    )
+
+
+class Session:
+    def __init__(
+        self,
+        *,
+        http: Http,
+        external_id: str,
+        user: User | None,
+        platform: str,
+        metadata: dict[str, object],
+    ) -> None:
+        self._http = http
+        self.external_id = external_id
+        self.user = user
+        self.platform = platform
+        self.metadata = metadata
+        self.transcript = Transcript()
+        # Assigned by the API on the first analyze(), then sent with every
+        # later request so they group into one call.
+        self.id: str | None = None
+        # Turn count at the last analyze(), used to skip a request when
+        # nothing new has been said.
+        self._analyzed_upto = 0
+
+    # ── building the transcript ──────────────────────────────────────────────
+
+    def append(self, role: str, text: str, **kw: Any) -> Turn:
+        """Add a turn to the transcript. Sends nothing."""
+        return self.transcript.append(role, text, **kw)  # type: ignore[arg-type]
+
+    @property
+    def pending(self) -> int:
+        """Turns added since the last `analyze`."""
+        return len(self.transcript) - self._analyzed_upto
+
+    # ── the semantic plane ───────────────────────────────────────────────────
+
+    async def analyze(self, *, force: bool = False) -> Analysis | None:
+        """Analyze the transcript and return what was found.
+
+        Returns None when no turns have been added since the last call, so
+        this can be called on every turn without sending a request each time.
+        Pass `force=True` to analyze regardless.
+
+        This does not block the agent. A result arrives after the turn that
+        produced it has already been spoken, so a nudge affects what the agent
+        says next rather than what it is saying now.
+        """
+        if not force and self.pending == 0:
+            return None
+
+        # The whole transcript is sent each time. The API tracks what it has
+        # already seen for this session and analyzes only the new turns.
+        t0 = time.perf_counter()
+        body: dict[str, Any] = {
+            "external_id": self.external_id,
+            "platform": self.platform,
+            "turns": self.transcript.to_wire(),
+            "metadata": self.metadata,
+        }
+        if self.id:
+            body["session_id"] = self.id
+        if self.user:
+            body["user"] = self.user.to_wire()
+
+        d = await self._http.post("/agents/analyze", body)
+        self.id = d.get("session_id") or self.id
+        self._analyzed_upto = len(self.transcript)
+
+        return Analysis(
+            session_id=str(self.id or ""),
+            job_id=str(d.get("job_id") or ""),
+            findings=[_finding(f) for f in d.get("findings") or []],
+            progress=[_progress(p) for p in d.get("progress") or []],
+            risk_level=d.get("risk_level"),
+            confidence=d.get("confidence"),
+            reasoning=d.get("reasoning"),
+            latency_ms=round((time.perf_counter() - t0) * 1000, 2),
+            raw=d,
+        )
+
+    async def end(self) -> bool:
+        """Tell DeepTrust the call is over.
+
+        Post-call processing starts at once instead of after the server's
+        inactivity timeout, so the record is complete minutes sooner. Returns
+        True when this request ended the call and False when it was already
+        ended, or when nothing was ever analyzed (there is no call to end).
+        Calling it twice is harmless.
+        """
+        if not self.id:
+            return False
+        d = await self._http.post(f"/agents/sessions/{self.id}/end")
+        return bool(d.get("ended")) and not bool(d.get("already_ended"))
+
+    # ── the action plane ─────────────────────────────────────────────────────
+
+    async def check(
+        self,
+        *,
+        action: str,
+        args: dict[str, Any] | None = None,
+        facts: dict[str, Any] | None = None,
+    ) -> Verdict:
+        """Decide whether an action may run. Not yet implemented.
+
+        Unlike `analyze`, this blocks: it is meant to be called from a tool
+        handler before the action executes, and the returned `Verdict` says
+        whether to proceed.
+
+        `facts` carries the values the policy is written against, such as
+        whether a change ticket is approved or an account is protected.
+        Policies compare these fields rather than reading the transcript, which
+        is what makes the decision deterministic, so the calling application
+        computes them from its own systems before proposing the action.
+        """
+        raise NotImplementedError(
+            "Session.check is not implemented in this version. "
+            "This release covers analysis and nudge delivery."
+        )

deeptrust/agents/elevenlabs.py

@@ -0,0 +1,164 @@
+"""ElevenLabs adapter.
+
+    from deeptrust.agents import DeepTrust
+    from deeptrust.agents.elevenlabs import Monitor
+
+    monitor = Monitor(DeepTrust(), api_key=os.environ["ELEVENLABS_API_KEY"])
+    await monitor.watch(conversation_id, user=user)
+
+Nothing runs inside the agent here. ElevenLabs exposes a monitor socket per
+conversation, so this connects to it with a workspace API key, reads the
+transcript as it happens, and sends nudges back as contextual updates on the
+same socket.
+
+Two consequences of that, both different from the LiveKit adapter:
+
+Contextual updates do not interrupt, so a nudge affects the agent's next turn
+rather than the one in progress.
+
+The socket carries transcript events, not audio, so nothing here has access to
+the audio stream.
+
+This is the self-hosted way to watch ElevenLabs: the socket is held by your
+process, with your ElevenLabs key. The hosted alternative needs neither: connect
+the workspace once in the DeepTrust dashboard (Settings, Voice Agents) and
+DeepTrust holds the socket itself. A backend that already knows a conversation
+id can hand it over with `DeepTrust.watch(conversation_id)`.
+
+Install with the extra:  pip install "deeptrust-ai[elevenlabs]"
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+from ..errors import ConfigError
+from ..types import User
+from . import DeepTrust
+
+MONITOR_URL = "wss://api.elevenlabs.io/v1/convai/conversations/{cid}/monitor"
+
+
+def contextual_update_command(text: str) -> dict[str, Any]:
+    """The monitor socket's command for a contextual update.
+
+    The monitor socket takes commands, not the `{"type": ...}` messages the
+    main conversation socket takes. A message in the other shape is ignored
+    without an error, which is how 0.0.1 delivered nothing.
+    """
+    return {
+        "command_type": "contextual_update",
+        "parameters": {"contextual_update": text},
+    }
+
+
+class Monitor:
+    """Watches live ElevenLabs conversations and feeds them to DeepTrust."""
+
+    def __init__(
+        self,
+        dt: DeepTrust,
+        *,
+        api_key: str,
+        deliver: bool = True,
+        on_analysis: Callable[[Any], None] | None = None,
+        connect: Callable[..., Any] | None = None,
+    ) -> None:
+        """`connect` opens the socket; it defaults to `websockets.connect` and
+        exists so a test can supply a fake."""
+        if not api_key:
+            raise ConfigError(
+                "Monitor needs an ElevenLabs API key with workspace access. "
+                "It reads the conversation and sends contextual updates back."
+            )
+        self._dt = dt
+        self._key = api_key
+        self._deliver = deliver
+        self._on_analysis = on_analysis
+        self._connect = connect
+        self._watching: dict[str, asyncio.Task[None]] = {}
+
+    async def watch(
+        self,
+        conversation_id: str,
+        *,
+        user: User | None = None,
+    ) -> None:
+        """Begin watching a conversation. Returns once the watcher is running.
+
+        The conversation must already have started. ElevenLabs replays only its
+        last hundred or so events on connect, so connect promptly: for an
+        outbound call, use the conversation id returned when the call is
+        placed.
+
+        Watching the same conversation twice is a no-op.
+        """
+        if conversation_id in self._watching:
+            return
+        task = asyncio.create_task(self._loop(conversation_id, user))
+        self._watching[conversation_id] = task
+        task.add_done_callback(lambda _: self._watching.pop(conversation_id, None))
+
+    async def stop(self, conversation_id: str) -> None:
+        task = self._watching.pop(conversation_id, None)
+        if task:
+            task.cancel()
+
+    async def _loop(self, cid: str, user: User | None) -> None:
+        connect = self._connect
+        if connect is None:
+            try:
+                import websockets
+            except ImportError as exc:  # pragma: no cover
+                raise ConfigError(
+                    "the ElevenLabs adapter needs websockets. "
+                    'Install with: pip install "deeptrust-ai[elevenlabs]"'
+                ) from exc
+            connect = websockets.connect
+
+        call = self._dt.session(external_id=cid, user=user, platform="elevenlabs")
+        url = MONITOR_URL.format(cid=cid)
+
+        headers = {"xi-api-key": self._key}
+        async with connect(url, additional_headers=headers) as ws:
+            async for raw in ws:
+                try:
+                    ev = json.loads(raw)
+                except (TypeError, ValueError):
+                    continue
+
+                role, text = _read_turn(ev)
+                if not text:
+                    continue
+                call.append(role, text)
+                if role != "user":
+                    continue
+
+                result = await call.analyze()
+                if result is None:
+                    continue
+                if self._on_analysis:
+                    self._on_analysis(result)
+                if not self._deliver:
+                    continue
+                for nudge in result.nudges:
+                    await ws.send(json.dumps(contextual_update_command(nudge.render())))
+
+
+def _read_turn(ev: dict[str, Any]) -> tuple[str, str]:
+    """Extract a turn from a monitor event, or ("", "") if it is not one.
+
+    The only place ElevenLabs event names appear. Events other than user and
+    agent transcripts, such as audio and interruptions, are ignored.
+    """
+    kind = ev.get("type")
+    if kind == "user_transcript":
+        payload = ev.get("user_transcription_event") or {}
+        return "user", str(payload.get("user_transcript") or "").strip()
+    if kind == "agent_response":
+        payload = ev.get("agent_response_event") or {}
+        return "agent", str(payload.get("agent_response") or "").strip()
+    return "", ""