capsule-litellm 0.1.0__tar.gz

capsule_litellm-0.1.0/LICENSE

@@ -0,0 +1,32 @@
+Capsule Security Commercial License
+
+Copyright (c) Capsule Security, Inc. All rights reserved.
+
+This software is licensed, not sold, and is made available solely to customers
+of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
+agreement (the "Subscription Agreement") between the customer and Capsule.
+
+Subject to the Subscription Agreement, Capsule grants the customer a
+non-exclusive, non-transferable, non-sublicensable, revocable license to install
+and run this software in connection with the customer's authorized use of the
+Capsule platform, solely for the customer's internal business operations.
+
+Except as expressly permitted by the Subscription Agreement, you may not:
+  (a) copy, modify, or create derivative works of the software;
+  (b) reverse engineer, decompile, or disassemble the software;
+  (c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
+      software to any third party;
+  (d) remove or alter any proprietary notices contained in the software; or
+  (e) use the software except in connection with an active Subscription
+      Agreement.
+
+Without a valid Subscription Agreement with Capsule, no rights are granted to
+use this software. Unauthorized use is prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
+OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
+LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
+AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
+
+For licensing inquiries, contact: sales@capsulesecurity.io

capsule_litellm-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: capsule-litellm
+Version: 0.1.0
+Summary: Capsule plugin for the LiteLLM gateway — forwards completion requests to the Capsule agentsecurity service for centralized policy enforcement and audit.
+Project-URL: Homepage, https://github.com/capsulesecurity
+Project-URL: Documentation, https://docs.capsulesecurity.io/guides/litellm
+Author: Capsule Security
+License: Capsule Security Commercial License
+        
+        Copyright (c) Capsule Security, Inc. All rights reserved.
+        
+        This software is licensed, not sold, and is made available solely to customers
+        of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
+        agreement (the "Subscription Agreement") between the customer and Capsule.
+        
+        Subject to the Subscription Agreement, Capsule grants the customer a
+        non-exclusive, non-transferable, non-sublicensable, revocable license to install
+        and run this software in connection with the customer's authorized use of the
+        Capsule platform, solely for the customer's internal business operations.
+        
+        Except as expressly permitted by the Subscription Agreement, you may not:
+          (a) copy, modify, or create derivative works of the software;
+          (b) reverse engineer, decompile, or disassemble the software;
+          (c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
+              software to any third party;
+          (d) remove or alter any proprietary notices contained in the software; or
+          (e) use the software except in connection with an active Subscription
+              Agreement.
+        
+        Without a valid Subscription Agreement with Capsule, no rights are granted to
+        use this software. Unauthorized use is prohibited.
+        
+        THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
+        OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
+        LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
+        AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
+        
+        For licensing inquiries, contact: sales@capsulesecurity.io
+License-File: LICENSE
+Keywords: agent-security,capsule,litellm,litellm-plugin,llm-gateway,policy,security
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: litellm[proxy]>=1.40
+Description-Content-Type: text/markdown
+
+# capsule-litellm
+
+Capsule plugin for the [LiteLLM](https://docs.litellm.ai) LLM gateway. Forwards completion/chat requests to the Capsule `agentsecurity` service for centralized policy enforcement (pre-call allow/deny) and token/latency audit (post-call telemetry).
+
+## Install
+
+```bash
+pip install capsule-litellm
+```
+
+Install it into the same environment that runs your LiteLLM proxy.
+
+## Configure
+
+Register the callback in your LiteLLM `config.yaml`:
+
+```yaml
+litellm_settings:
+  callbacks: ['capsule_litellm_plugin.capsule_callback']
+```
+
+The callback reads its configuration from environment variables. Set these where the LiteLLM proxy runs:
+
+```bash
+export CAPSULE_LITELLM_ENDPOINT="https://agents.capsule.security/v1/litellm/hooks"
+export CAPSULE_LITELLM_TOKEN="<token from the Capsule portal>"
+```
+
+The `endpoint` and `token` values are issued by Capsule when you install the LiteLLM integration in the portal (**Integrations → LiteLLM**). The token is a JWT scoped to your tenant and environment — treat it as a secret.
+
+### Optional environment variables
+
+| Variable                        | Default | Description                                                                                                       |
+| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `CAPSULE_LITELLM_BLOCK_ON_RISK` | `true`  | Apply server `deny` verdicts inline. Set to `false` to run the plugin in observe-only mode.                       |
+| `CAPSULE_LITELLM_FAIL_OPEN`     | `true`  | Allow the request through if Capsule is unreachable or returns a non-2xx response. Set to `false` to fail closed. |
+| `CAPSULE_LITELLM_TIMEOUT_MS`    | `5000`  | Per-request HTTP timeout in milliseconds.                                                                         |
+
+## How it works
+
+| Hook                      | Type        | Description                                                                                           |
+| ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| `async_pre_call_hook`     | Blocking    | Posts the model + messages to `events/pre` and awaits an allow/deny verdict before the upstream call. |
+| `async_log_success_event` | Observation | Posts model, latency, and token usage to `events/post` after a successful completion.                 |
+| `async_log_failure_event` | Observation | Posts model, latency, and the error to `events/post` when the upstream call fails.                    |
+
+When `block_on_risk` is enabled and Capsule returns `decision: "deny"`, the pre-call hook raises a `403` so LiteLLM rejects the request before it reaches the upstream provider.
+
+## License
+
+Capsule Security Commercial License. See [LICENSE](./LICENSE).

capsule_litellm-0.1.0/README.md

@@ -0,0 +1,51 @@
+# capsule-litellm
+
+Capsule plugin for the [LiteLLM](https://docs.litellm.ai) LLM gateway. Forwards completion/chat requests to the Capsule `agentsecurity` service for centralized policy enforcement (pre-call allow/deny) and token/latency audit (post-call telemetry).
+
+## Install
+
+```bash
+pip install capsule-litellm
+```
+
+Install it into the same environment that runs your LiteLLM proxy.
+
+## Configure
+
+Register the callback in your LiteLLM `config.yaml`:
+
+```yaml
+litellm_settings:
+  callbacks: ['capsule_litellm_plugin.capsule_callback']
+```
+
+The callback reads its configuration from environment variables. Set these where the LiteLLM proxy runs:
+
+```bash
+export CAPSULE_LITELLM_ENDPOINT="https://agents.capsule.security/v1/litellm/hooks"
+export CAPSULE_LITELLM_TOKEN="<token from the Capsule portal>"
+```
+
+The `endpoint` and `token` values are issued by Capsule when you install the LiteLLM integration in the portal (**Integrations → LiteLLM**). The token is a JWT scoped to your tenant and environment — treat it as a secret.
+
+### Optional environment variables
+
+| Variable                        | Default | Description                                                                                                       |
+| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `CAPSULE_LITELLM_BLOCK_ON_RISK` | `true`  | Apply server `deny` verdicts inline. Set to `false` to run the plugin in observe-only mode.                       |
+| `CAPSULE_LITELLM_FAIL_OPEN`     | `true`  | Allow the request through if Capsule is unreachable or returns a non-2xx response. Set to `false` to fail closed. |
+| `CAPSULE_LITELLM_TIMEOUT_MS`    | `5000`  | Per-request HTTP timeout in milliseconds.                                                                         |
+
+## How it works
+
+| Hook                      | Type        | Description                                                                                           |
+| ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| `async_pre_call_hook`     | Blocking    | Posts the model + messages to `events/pre` and awaits an allow/deny verdict before the upstream call. |
+| `async_log_success_event` | Observation | Posts model, latency, and token usage to `events/post` after a successful completion.                 |
+| `async_log_failure_event` | Observation | Posts model, latency, and the error to `events/post` when the upstream call fails.                    |
+
+When `block_on_risk` is enabled and Capsule returns `decision: "deny"`, the pre-call hook raises a `403` so LiteLLM rejects the request before it reaches the upstream provider.
+
+## License
+
+Capsule Security Commercial License. See [LICENSE](./LICENSE).

capsule_litellm-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "capsule-litellm"
+version = "0.1.0"
+description = "Capsule plugin for the LiteLLM gateway — forwards completion requests to the Capsule agentsecurity service for centralized policy enforcement and audit."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Capsule Security" }]
+keywords = [
+    "litellm",
+    "litellm-plugin",
+    "llm-gateway",
+    "capsule",
+    "security",
+    "policy",
+    "agent-security",
+]
+classifiers = [
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+    "httpx>=0.27",
+    "litellm[proxy]>=1.40",
+]
+
+[project.urls]
+Homepage = "https://github.com/capsulesecurity"
+Documentation = "https://docs.capsulesecurity.io/guides/litellm"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/capsule_litellm_plugin"]

capsule_litellm-0.1.0/src/capsule_litellm_plugin/__init__.py

@@ -0,0 +1,21 @@
+"""Capsule plugin for the LiteLLM LLM gateway.
+
+Forwards completion/chat requests to the Capsule agentsecurity service for
+centralized policy enforcement (pre-call allow/deny) and token/latency audit
+(post-call telemetry).
+
+LiteLLM loads this via
+`litellm_settings.callbacks: ["capsule_litellm_plugin.capsule_callback"]`,
+which resolves to the module-level `capsule_callback` instance below.
+"""
+
+from __future__ import annotations
+
+from .callback import CapsuleLiteLlmCallback
+from .config import CapsuleLiteLlmConfig
+
+PLUGIN_VERSION = "0.1.0"
+
+capsule_callback = CapsuleLiteLlmCallback()
+
+__all__ = ["CapsuleLiteLlmCallback", "CapsuleLiteLlmConfig", "capsule_callback", "PLUGIN_VERSION"]

capsule_litellm-0.1.0/src/capsule_litellm_plugin/callback.py

@@ -0,0 +1,213 @@
+"""LiteLLM custom callback that forwards completion requests to Capsule.
+
+`async_pre_call_hook` posts the prompt to Capsule before the upstream model
+call and blocks the request when Capsule returns a deny verdict.
+`async_log_success_event` / `async_log_failure_event` post token and latency
+telemetry once the upstream call settles.
+
+LiteLLM resolves the `capsule_litellm_plugin.capsule_callback` config string to
+the module-level instance created in `__init__`.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime
+from typing import Any
+
+from fastapi import HTTPException
+from litellm.integrations.custom_logger import CustomLogger
+
+from .config import CapsuleLiteLlmConfig
+from .transport import CapsuleResponse, CapsuleTransport
+from .types import LiteLlmChatMessage, LiteLlmPostHookInput, LiteLlmPreHookInput
+
+logger = logging.getLogger("capsule_litellm_plugin")
+
+_PROCESSED_CALL_TYPES = {
+    "completion",
+    "acompletion",
+    "text_completion",
+    "atext_completion",
+    "anthropic_messages",
+    "aresponses",
+}
+
+
+class CapsuleBlockedError(HTTPException):
+    def __init__(self, reason: str) -> None:
+        super().__init__(status_code=403, detail=f"Blocked by Capsule policy: {reason}")
+
+
+class CapsuleLiteLlmCallback(CustomLogger):
+    def __init__(self) -> None:
+        super().__init__()
+        try:
+            self._config: CapsuleLiteLlmConfig | None = CapsuleLiteLlmConfig.from_env()
+            self._transport: CapsuleTransport | None = CapsuleTransport(self._config)
+            logger.info(
+                "capsule_litellm_plugin: enabled (block_on_risk=%s, fail_open=%s)",
+                self._config.block_on_risk,
+                self._config.fail_open,
+            )
+        except ValueError as exc:
+            self._config = None
+            self._transport = None
+            logger.warning("capsule_litellm_plugin: disabled — %s", exc)
+
+    async def async_pre_call_hook(self, user_api_key_dict: Any, cache: Any, data: dict, call_type: str):
+        if self._config is None or self._transport is None:
+            return data
+        if call_type not in _PROCESSED_CALL_TYPES and not data.get("messages"):
+            return data
+
+        request_id = str(data.get("litellm_call_id") or uuid.uuid4())
+        payload = LiteLlmPreHookInput(
+            request_id=request_id,
+            model=str(data.get("model") or "unknown"),
+            messages=_extract_messages(data, call_type),
+            user=_optional_str(data.get("user")),
+        ).to_dict()
+
+        try:
+            response = await self._transport.post_pre(payload, request_id)
+        except Exception as exc:
+            return self._on_transport_failure(exc, data)
+
+        if not response.ok:
+            logger.warning("capsule_litellm_plugin: pre-hook returned status %s", response.status)
+            return self._on_transport_failure(None, data)
+
+        if _is_deny(response):
+            reason = _deny_reason(response)
+            logger.info("capsule_litellm_plugin: request %s denied — %s", request_id, reason)
+            if self._config.block_on_risk:
+                raise CapsuleBlockedError(reason)
+        return data
+
+    async def async_log_success_event(self, kwargs: dict, response_obj: Any, start_time: Any, end_time: Any) -> None:
+        await self._record_post(kwargs, response_obj, start_time, end_time, success=True)
+
+    async def async_log_failure_event(self, kwargs: dict, response_obj: Any, start_time: Any, end_time: Any) -> None:
+        # LiteLLM also logs a pre-call block as a failed call, although it never reached the upstream model.
+        if isinstance(kwargs.get("exception"), CapsuleBlockedError):
+            return
+        await self._record_post(kwargs, response_obj, start_time, end_time, success=False)
+
+    async def _record_post(self, kwargs: dict, response_obj: Any, start_time: Any, end_time: Any, *, success: bool) -> None:
+        if self._config is None or self._transport is None:
+            return
+        request_id = str(kwargs.get("litellm_call_id") or uuid.uuid4())
+        usage = _extract_usage(response_obj)
+        exception = kwargs.get("exception") if not success else None
+        payload = LiteLlmPostHookInput(
+            request_id=request_id,
+            model=str(kwargs.get("model") or "unknown"),
+            duration_ms=_duration_ms(start_time, end_time),
+            success=success,
+            prompt_tokens=usage.get("prompt_tokens"),
+            completion_tokens=usage.get("completion_tokens"),
+            total_tokens=usage.get("total_tokens"),
+            error_code=type(exception).__name__ if exception is not None else None,
+            error_message=str(exception) if exception is not None else None,
+        ).to_dict()
+        try:
+            await self._transport.post_post(payload, request_id)
+        except Exception as exc:
+            logger.warning("capsule_litellm_plugin: post-hook delivery failed — %s", exc)
+
+    def _on_transport_failure(self, exc: Exception | None, data: dict) -> dict:
+        if exc is not None:
+            logger.warning("capsule_litellm_plugin: pre-hook request failed — %s", exc)
+        assert self._config is not None
+        if self._config.fail_open:
+            return data
+        raise CapsuleBlockedError("Capsule policy service unavailable")
+
+
+def _extract_messages(data: dict, call_type: str) -> list[LiteLlmChatMessage]:
+    # Anthropic /v1/messages sends the system prompt as top-level `system`, the Responses API as `instructions`.
+    messages = _system_prompt_messages(data.get("system")) + _system_prompt_messages(data.get("instructions"))
+    messages += _conversation_messages(data.get("messages"))
+    if call_type == "aresponses":
+        messages += _conversation_messages(data.get("input"))
+    return messages
+
+
+def _system_prompt_messages(raw: Any) -> list[LiteLlmChatMessage]:
+    content = _flatten_content(raw)
+    return [LiteLlmChatMessage(role="system", content=content)] if content.strip() else []
+
+
+def _conversation_messages(raw: Any) -> list[LiteLlmChatMessage]:
+    if isinstance(raw, str):
+        return [LiteLlmChatMessage(role="user", content=raw)]
+    if not isinstance(raw, list):
+        return []
+    out: list[LiteLlmChatMessage] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        role = item.get("role")
+        if isinstance(role, str):
+            out.append(LiteLlmChatMessage(role=role, content=_flatten_content(item.get("content"))))
+        elif item.get("type") == "function_call_output":
+            out.append(LiteLlmChatMessage(role="tool", content=_flatten_content(item.get("output"))))
+    return out
+
+
+def _flatten_content(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    return "\n".join(text for text in (_part_text(part) for part in content) if text)
+
+
+def _part_text(part: Any) -> str:
+    if isinstance(part, str):
+        return part
+    if not isinstance(part, dict):
+        return ""
+    text = part.get("text")
+    if isinstance(text, str):
+        return text
+    # Anthropic tool_result blocks nest their own content blocks.
+    return _flatten_content(part.get("content"))
+
+
+def _optional_str(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _extract_usage(response_obj: Any) -> dict[str, int]:
+    usage = getattr(response_obj, "usage", None)
+    if usage is None and isinstance(response_obj, dict):
+        usage = response_obj.get("usage")
+    result: dict[str, int] = {}
+    for key in ("prompt_tokens", "completion_tokens", "total_tokens"):
+        value = getattr(usage, key, None)
+        if value is None and isinstance(usage, dict):
+            value = usage.get(key)
+        if isinstance(value, int):
+            result[key] = value
+    return result
+
+
+def _duration_ms(start_time: Any, end_time: Any) -> int:
+    if isinstance(start_time, datetime) and isinstance(end_time, datetime):
+        return max(0, int((end_time - start_time).total_seconds() * 1000))
+    return 0
+
+
+def _is_deny(response: CapsuleResponse) -> bool:
+    return isinstance(response.body, dict) and response.body.get("decision") == "deny"
+
+
+def _deny_reason(response: CapsuleResponse) -> str:
+    if isinstance(response.body, dict):
+        reason = response.body.get("reason")
+        if isinstance(reason, str) and reason:
+            return reason
+    return "policy violation"

capsule_litellm-0.1.0/src/capsule_litellm_plugin/config.py

@@ -0,0 +1,53 @@
+"""Configuration for the Capsule LiteLLM plugin.
+
+All settings are read from environment variables so the callback instance can
+be constructed at LiteLLM import time, before the proxy config block is
+available to the callback.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CapsuleLiteLlmConfig:
+    endpoint: str
+    token: str
+    block_on_risk: bool = True
+    fail_open: bool = True
+    timeout_ms: int = 5000
+
+    @classmethod
+    def from_env(cls) -> "CapsuleLiteLlmConfig":
+        endpoint = os.environ.get("CAPSULE_LITELLM_ENDPOINT")
+        token = os.environ.get("CAPSULE_LITELLM_TOKEN")
+        if not endpoint:
+            raise ValueError("CAPSULE_LITELLM_ENDPOINT is not set")
+        if not token:
+            raise ValueError("CAPSULE_LITELLM_TOKEN is not set")
+        return cls(
+            endpoint=endpoint,
+            token=token,
+            block_on_risk=_env_bool("CAPSULE_LITELLM_BLOCK_ON_RISK", True),
+            fail_open=_env_bool("CAPSULE_LITELLM_FAIL_OPEN", True),
+            timeout_ms=_env_int("CAPSULE_LITELLM_TIMEOUT_MS", 5000),
+        )
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    raw = os.environ.get(key)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_int(key: str, default: int) -> int:
+    raw = os.environ.get(key)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default

capsule_litellm-0.1.0/src/capsule_litellm_plugin/transport.py

@@ -0,0 +1,59 @@
+"""Async HTTP transport for the Capsule LiteLLM plugin.
+
+LiteLLM invokes callback hooks inside its asyncio event loop, so the transport
+uses `httpx.AsyncClient`. Pre-call requests block on Capsule's allow/deny
+verdict; post-call requests are fire-and-forget telemetry. Non-2xx responses
+are surfaced via `CapsuleResponse.ok` rather than raised — the callback's
+dispatch wrapper decides fail-open / fail-closed.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .config import CapsuleLiteLlmConfig
+
+_HOOKS_PATH_SUFFIX = "/v1/litellm/hooks"
+
+
+@dataclass(frozen=True)
+class CapsuleResponse:
+    ok: bool
+    status: int
+    body: Any
+
+
+class CapsuleTransport:
+    def __init__(self, config: CapsuleLiteLlmConfig) -> None:
+        self._config = config
+        base = config.endpoint.rstrip("/")
+        if not base.endswith(_HOOKS_PATH_SUFFIX):
+            base = f"{base}{_HOOKS_PATH_SUFFIX}"
+        self._base = base
+        self._client = httpx.AsyncClient(timeout=config.timeout_ms / 1000.0)
+
+    async def post_pre(self, payload: dict[str, Any], correlation_id: str) -> CapsuleResponse:
+        return await self._post("events/pre", payload, correlation_id)
+
+    async def post_post(self, payload: dict[str, Any], correlation_id: str) -> CapsuleResponse:
+        return await self._post("events/post", payload, correlation_id)
+
+    async def _post(self, path: str, payload: dict[str, Any], correlation_id: str) -> CapsuleResponse:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._config.token}",
+            "X-Correlation-Id": correlation_id,
+        }
+        response = await self._client.post(f"{self._base}/{path}", json=payload, headers=headers)
+        body: Any = None
+        text = response.text
+        if text:
+            try:
+                body = json.loads(text)
+            except json.JSONDecodeError:
+                body = text
+        return CapsuleResponse(ok=response.is_success, status=response.status_code, body=body)

capsule_litellm-0.1.0/src/capsule_litellm_plugin/types.py

@@ -0,0 +1,68 @@
+"""Wire-format payloads for the Capsule LiteLLM plugin.
+
+Mirror the request DTOs the Capsule agentsecurity service accepts at
+`/v1/litellm/hooks/events/{pre,post}`. Keys are camelCase to match the
+NestJS DTOs on the receiving end.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class LiteLlmChatMessage:
+    role: str
+    content: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass(frozen=True)
+class LiteLlmPreHookInput:
+    request_id: str
+    model: str
+    messages: list[LiteLlmChatMessage] = field(default_factory=list)
+    user: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"requestId": self.request_id, "model": self.model}
+        if self.messages:
+            payload["messages"] = [m.to_dict() for m in self.messages]
+        if self.user:
+            payload["user"] = self.user
+        return payload
+
+
+@dataclass(frozen=True)
+class LiteLlmPostHookInput:
+    request_id: str
+    model: str
+    duration_ms: int
+    success: bool
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "requestId": self.request_id,
+            "model": self.model,
+            "durationMs": self.duration_ms,
+            "success": self.success,
+        }
+        if self.prompt_tokens is not None:
+            payload["promptTokens"] = self.prompt_tokens
+        if self.completion_tokens is not None:
+            payload["completionTokens"] = self.completion_tokens
+        if self.total_tokens is not None:
+            payload["totalTokens"] = self.total_tokens
+        if self.error_code:
+            payload["errorCode"] = self.error_code
+        if self.error_message:
+            payload["errorMessage"] = self.error_message
+        return payload