Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

35.0 KB
Raw Blame
"""
ViewSet for AI observability proxy

Endpoints:
- GET /api/llm_proxy/models
- POST /api/llm_proxy/completion
- POST /api/llm_proxy/decision
"""

import json
import uuid
from collections.abc import Callable, Generator
from contextlib import closing
from time import perf_counter
from typing import Any

from django.core.cache import cache
from django.db import models
from django.http.response import HttpResponseBase
from django.utils import timezone

import structlog
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
from rest_framework import serializers, viewsets
from rest_framework.decorators import action
from rest_framework.permissions import BasePermission, IsAuthenticated
from rest_framework.request import Request
from rest_framework.response import Response

from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.monitoring import monitor
from posthog.api.streaming import sse_streaming_response
from posthog.auth import SessionAuthentication
from posthog.event_usage import groups, report_user_action
from posthog.llm.system_one import (
    MAX_CHOICE_OPTIONS,
    MAX_SCORE_LEVELS,
    Answer,
    ChoiceAnswer,
    ChoiceQuestion,
    NoulAnswer,
    NoulQuestion,
    Question,
    ScoreAnswer,
    ScoreQuestion,
)
from posthog.rate_limit import (
    LLMProxyBurstRateThrottle,
    LLMProxyBYOKBurstRateThrottle,
    LLMProxyBYOKDailyRateThrottle,
    LLMProxyBYOKSustainedRateThrottle,
    LLMProxyDailyRateThrottle,
    LLMProxySustainedRateThrottle,
)
from posthog.renderers import SafeJSONRenderer, ServerSentEventRenderer
from posthog.settings import SERVER_GATEWAY_INTERFACE

from products.access_control.backend.facade.user_access_control import AccessControlLevel, UserAccessControl
from products.ai_observability.backend.api.datasets import JSONObjectField
from products.ai_observability.backend.api.metrics import (
    LLMA_PROXY_BYOK_EMPTY_MODEL_LISTS,
    LLMA_PROXY_BYOK_REQUESTS,
    llma_track_latency,
)
from products.ai_observability.backend.llm import (
    PLAYGROUND_MODEL_IDS,
    SUPPORTED_MODELS_WITH_THINKING,
    Client,
    CompletionRequest,
    ModelInfo,
    OutputSchema,
    get_playground_models,
    supports_reasoning_level,
)
from products.ai_observability.backend.llm.decisions import DecisionClient
from products.ai_observability.backend.llm.errors import (
    LLMError,
    ProviderConfigurationError,
    ProviderHostUnresolvedError,
    UnsupportedProviderError,
)
from products.ai_observability.backend.llm.providers.openai import OpenAIConfig
from products.ai_observability.backend.llm.providers.openrouter import decision_model_ids, non_chat_model_ids
from products.ai_observability.backend.models.provider_keys import (
    LLMProvider,
    LLMProviderKey,
    llm_completion_provider_choices,
)

from ee.hogai.utils.asgi import SyncIterableToAsync

logger = structlog.get_logger(__name__)

MODELS_CACHE_TIMEOUT_SECONDS = 60


def models_cache_key(provider_key_id: str | uuid.UUID) -> str:
    return f"llma:proxy:models:{provider_key_id}"


PROVIDER_DISPLAY_NAMES: dict[str, str] = {
    "system_one": "System One",
    "openai": "OpenAI",
    "anthropic": "Anthropic",
    "gemini": "Gemini",
    "openrouter": "OpenRouter",
    "fireworks": "Fireworks",
    "azure_openai": "Azure OpenAI",
    "minimax": "MiniMax",
    "openai_compatible": "OpenAI-compatible",
}


class LLMProxyResponseFormatType(models.TextChoices):
    JSON_SCHEMA = "json_schema", "JSON schema"


class LLMProxyJSONSchemaSerializer(serializers.Serializer):
    name = serializers.CharField(
        default="response", help_text="Schema name, sent to providers that require one (OpenAI)."
    )
    schema = JSONObjectField(help_text="JSON schema the reply must match. Sent to the provider unchanged.")
    strict = serializers.BooleanField(
        default=True, help_text="Enforce the schema exactly, where the provider has a strictness switch."
    )


class LLMProxyResponseFormatSerializer(serializers.Serializer):
    type = serializers.ChoiceField(
        choices=LLMProxyResponseFormatType.choices, help_text="Only `json_schema` is supported."
    )
    json_schema = LLMProxyJSONSchemaSerializer(help_text="The schema and its options, in the OpenAI shape.")


class LLMProxyCompletionSerializer(serializers.Serializer):
    system = serializers.CharField(allow_blank=True)
    messages = serializers.ListField(child=serializers.DictField())
    model = serializers.CharField()
    provider = serializers.ChoiceField(choices=llm_completion_provider_choices())
    thinking = serializers.BooleanField(default=False, required=False)
    temperature = serializers.FloatField(required=False)
    top_p = serializers.FloatField(required=False)
    seed = serializers.IntegerField(required=False)
    max_tokens = serializers.IntegerField(required=False)
    tools = serializers.JSONField(required=False)
    reasoning_level = serializers.ChoiceField(
        choices=["minimal", "low", "medium", "high"], required=False, allow_null=True
    )
    response_format = LLMProxyResponseFormatSerializer(
        required=False, allow_null=True, help_text="Ask the model for JSON that matches a schema."
    )
    provider_key_id = serializers.UUIDField(required=False, allow_null=True)


class LLMProxyModelInfoSerializer(serializers.Serializer):
    id = serializers.CharField(help_text="Provider-specific model identifier.")
    name = serializers.CharField(help_text="Model display name.")
    provider = serializers.CharField(help_text="Provider display name.")
    description = serializers.CharField(allow_blank=True, help_text="Description of the model.")
    is_recommended = serializers.BooleanField(help_text="Whether the provider recommends this model.")
    supports_decisions = serializers.BooleanField(
        default=False, help_text="Whether this model supports decision questions."
    )
    supports_chat = serializers.BooleanField(
        default=True, help_text="Whether this model supports chat completions with written reasoning."
    )
    supports_reasoning = serializers.BooleanField(
        default=False, help_text="Whether an evaluation judge can set a reasoning level for this model."
    )


MAX_DECISION_QUESTIONS = 20
MAX_DECISION_STATE_CHARS = 200_000
MAX_DECISION_INSTRUCTIONS_CHARS = 4_000
MAX_DECISION_OPTION_CHARS = 500


class LLMProxyDecisionQuestionType(models.TextChoices):
    NOUL = "noul", "Yes or no"
    CHOICE = "choice", "Multiple choice"
    SCORE = "score", "Rating scale"


class LLMProxyDecisionAnswerType(models.TextChoices):
    NOUL = "noul", "Yes or no"
    CHOICE = "choice", "Multiple choice"
    SCORE = "score", "Rating scale"
    REFUSAL = "refusal", "Refusal"


class LLMProxyDecisionOptionSerializer(serializers.Serializer):
    name = serializers.CharField(
        max_length=MAX_DECISION_OPTION_CHARS,
        help_text="The option name for a multiple choice question, or the level label for a rating question.",
    )
    description = serializers.CharField(
        max_length=MAX_DECISION_OPTION_CHARS,
        required=False,
        allow_blank=True,
        help_text="What a multiple choice option means. Ignored for a rating question.",
    )


class LLMProxyDecisionQuestionSerializer(serializers.Serializer):
    type = serializers.ChoiceField(
        choices=LLMProxyDecisionQuestionType.choices,
        help_text="The answer to produce: a yes/no probability, one of the options, or a level on the scale.",
    )
    instructions = serializers.CharField(
        max_length=MAX_DECISION_INSTRUCTIONS_CHARS,
        help_text="The question to ask about the state, phrased for the model.",
    )
    options = LLMProxyDecisionOptionSerializer(
        many=True,
        required=False,
        help_text=(
            f"The options of a multiple choice question (1 to {MAX_CHOICE_OPTIONS}), or the levels of a rating "
            f"question from lowest to highest (2 to {MAX_SCORE_LEVELS}). Omitted for a yes/no question."
        ),
    )

    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
        options = attrs.get("options") or []
        names = [option["name"] for option in options]
        if len(set(names)) != len(names):
            raise serializers.ValidationError({"options": "Give each option a different name."})
        match attrs["type"]:
            case LLMProxyDecisionQuestionType.CHOICE if not 1 <= len(options) <= MAX_CHOICE_OPTIONS:
                raise serializers.ValidationError(
                    {"options": f"A multiple choice question needs 1 to {MAX_CHOICE_OPTIONS} options."}
                )
            case LLMProxyDecisionQuestionType.SCORE if not 2 <= len(options) <= MAX_SCORE_LEVELS:
                raise serializers.ValidationError(
                    {"options": f"A rating question needs 2 to {MAX_SCORE_LEVELS} levels."}
                )
        return attrs


class LLMProxyDecisionSerializer(serializers.Serializer):
    provider_key_id = serializers.UUIDField(help_text="The team's System One provider key that answers the questions.")
    state = serializers.CharField(
        max_length=MAX_DECISION_STATE_CHARS,
        trim_whitespace=False,
        help_text="The text the questions are about, for example a conversation. Sent unchanged.",
    )
    questions = serializers.DictField(
        child=LLMProxyDecisionQuestionSerializer(),
        help_text=(
            f"The questions to ask, keyed by an id of your choice, at most {MAX_DECISION_QUESTIONS}. "
            "Answers come back under the same ids."
        ),
    )

    def validate_questions(self, questions: dict[str, Any]) -> dict[str, Any]:
        if not 1 <= len(questions) <= MAX_DECISION_QUESTIONS:
            raise serializers.ValidationError(f"Ask between 1 and {MAX_DECISION_QUESTIONS} questions.")
        return questions


class LLMProxyDecisionAnswerSerializer(serializers.Serializer):
    type = serializers.ChoiceField(
        choices=LLMProxyDecisionAnswerType.choices,
        help_text="The question type answered, or `refusal` when the model declined to answer.",
    )
    probability = serializers.FloatField(allow_null=True, help_text="For a yes/no question, the probability of yes.")
    choice = serializers.CharField(allow_null=True, help_text="For a multiple choice question, the option chosen.")
    score = serializers.FloatField(
        allow_null=True, help_text="For a rating question, the expected level as a fractional index into the levels."
    )
    confidence = serializers.FloatField(
        allow_null=True, help_text="For multiple choice and rating questions, how sure the model is, from 0 to 1."
    )
    probabilities = serializers.DictField(
        child=serializers.FloatField(),
        allow_null=True,
        help_text="For multiple choice and rating questions, the probability of each option or level index.",
    )


class LLMProxyDecisionResponseSerializer(serializers.Serializer):
    model = serializers.CharField(help_text="The versioned model that answered.")
    answers = serializers.DictField(
        child=LLMProxyDecisionAnswerSerializer(), help_text="One answer per question, under the ids the request used."
    )
    input_tokens = serializers.IntegerField(allow_null=True, help_text="Tokens the model read, if reported.")
    output_tokens = serializers.IntegerField(allow_null=True, help_text="Tokens the model wrote, if reported.")


class LLMProxyErrorSerializer(serializers.Serializer):
    error = serializers.CharField(help_text="What went wrong and what to change.")


def build_decision_question(question: dict[str, Any]) -> Question:
    options = question.get("options") or []
    match question["type"]:
        case LLMProxyDecisionQuestionType.CHOICE:
            return ChoiceQuestion(
                instructions=question["instructions"],
                criteria={option["name"]: option.get("description") or None for option in options},
            )
        case LLMProxyDecisionQuestionType.SCORE:
            return ScoreQuestion(instructions=question["instructions"], criteria=[option["name"] for option in options])
        case _:
            return NoulQuestion(instructions=question["instructions"])


def serialize_decision_answer(answer: Answer) -> dict[str, Any]:
    body: dict[str, Any] = {
        "type": LLMProxyDecisionAnswerType.REFUSAL,
        "probability": None,
        "choice": None,
        "score": None,
        "confidence": None,
        "probabilities": None,
    }
    match answer:
        case NoulAnswer():
            body.update(type=LLMProxyDecisionAnswerType.NOUL, probability=answer.probability)
        case ChoiceAnswer():
            body.update(
                type=LLMProxyDecisionAnswerType.CHOICE,
                choice=answer.choice,
                confidence=answer.confidence,
                probabilities=dict(answer.probabilities),
            )
        case ScoreAnswer():
            body.update(
                type=LLMProxyDecisionAnswerType.SCORE,
                score=answer.score,
                confidence=answer.confidence,
                probabilities=dict(answer.probabilities),
            )
    return body


def provider_key_models(provider_key: LLMProviderKey) -> list[ModelInfo]:
    """The models one provider key can run, as the model pickers list them."""
    api_key = provider_key.encrypted_config.get("api_key")
    # Cache per provider key — list_models hits the provider's API, and the model picker
    # can open many times per session. TTL is short enough that newly-added deployments
    # surface within a minute.
    cache_key = models_cache_key(provider_key.id)
    models = cache.get(cache_key)
    if models is None:
        models = Client.list_models(provider_key.provider, api_key, **provider_key.provider_extra_kwargs())
        # Only cache non-empty results — `list_models` swallows transient errors and returns
        # [], so caching that would persist a failure for the full TTL.
        if models:
            cache.set(cache_key, models, timeout=MODELS_CACHE_TIMEOUT_SECONDS)
        else:
            LLMA_PROXY_BYOK_EMPTY_MODEL_LISTS.labels(provider=provider_key.provider).inc()
            logger.info(
                "llma_proxy_byok_empty_model_list",
                provider=provider_key.provider,
                team_id=provider_key.team_id,
                provider_key_id=str(provider_key.id),
            )
    recommended = Client.recommended_models(provider_key.provider)
    provider_display = PROVIDER_DISPLAY_NAMES.get(provider_key.provider, provider_key.provider.title())
    decision_models: frozenset[str] = frozenset()
    non_chat_models: frozenset[str] = frozenset()
    if provider_key.provider == LLMProvider.OPENROUTER:
        decision_models = decision_model_ids() or frozenset()
        non_chat_models = non_chat_model_ids() or frozenset()
        models = list(dict.fromkeys([*models, *sorted(decision_models)]))
    elif provider_key.provider == LLMProvider.OPENAI:
        decision_models = OpenAIConfig.DECISION_MODELS
        models = list(dict.fromkeys([*models, *sorted(decision_models)]))
    return [
        ModelInfo(
            id=m,
            name=m,
            provider=provider_display,
            description="",
            is_recommended=m in recommended,
            supports_decisions=provider_key.provider == LLMProvider.SYSTEM_ONE or m in decision_models,
            supports_chat=provider_key.provider != LLMProvider.SYSTEM_ONE and m not in non_chat_models,
            supports_reasoning=supports_reasoning_level(provider_key.provider, m),
        )
        for m in models
    ]


class PlaygroundAccessPermission(BasePermission):
    """Resource-level RBAC for the playground.

    The playground is stateless, so there is no model for `AccessControlViewSetMixin` to bind to and no
    object-level grants to consider. This viewset also sits on the root router without
    `TeamAndOrgViewSetMixin`, so it never picks up that mixin's `AccessControlPermission` — the check has
    to be wired up by hand. Deliberately no `scope_object` on the viewset: nothing in this permission
    chain reads it, and it would imply personal API key support that `SessionAuthentication` doesn't allow.
    """

    # Listing models is a read; running a completion spends money, so it's a write.
    ACTION_REQUIRED_LEVELS: dict[str, AccessControlLevel] = {
        "models": "viewer",
        "completion": "editor",
        "decision": "editor",
    }

    def has_permission(self, request: Request, view) -> bool:
        user = request.user
        if not user or not user.is_authenticated:
            return False

        # Fail closed so a new @action can't ship ungated
        required_level = self.ACTION_REQUIRED_LEVELS.get(view.action or "")
        if required_level is None:
            self.message = "This playground endpoint isn't available."
            return False

        team = getattr(user, "current_team", None)
        if team is None:
            self.message = "Open a project before using the playground."
            return False

        if UserAccessControl(user=user, team=team).check_access_level_for_resource("llm_playground", required_level):
            return True

        self.message = (
            "You need editor access to the playground to run prompts. Ask a project admin to update your access."
            if required_level == "editor"
            else "You don't have access to the playground. Ask a project admin to update your access."
        )
        return False


class LLMProxyViewSet(viewsets.ViewSet):
    """
    ViewSet for AI observability proxy.
    Proxies LLM calls from the AI observability playground.
    """

    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated, PlaygroundAccessPermission]
    renderer_classes = [SafeJSONRenderer, ServerSentEventRenderer]

    def get_throttles(self):
        # Don't throttle the models list endpoint - it returns a static list
        # and should always be accessible even if the user hit rate limits on completions
        if self.action == "models":
            return []

        # BYOK requests should not count against shared playground limits.
        # Check the provider key directly from request data to avoid running the
        # full serializer just for throttle selection.
        if self.action in ("completion", "decision"):
            data = getattr(self.request, "data", {})
            provider_key_id = data.get("provider_key_id")
            if provider_key_id:
                try:
                    key = self._get_provider_key(str(provider_key_id), self.request.user, touch_last_used=False)
                    if key:
                        LLMA_PROXY_BYOK_REQUESTS.labels(provider=key.provider).inc()
                        return [
                            LLMProxyBYOKBurstRateThrottle(),
                            LLMProxyBYOKSustainedRateThrottle(),
                            LLMProxyBYOKDailyRateThrottle(),
                        ]
                except ValueError:
                    pass

        return [LLMProxyBurstRateThrottle(), LLMProxySustainedRateThrottle(), LLMProxyDailyRateThrottle()]

    def _get_provider_key(
        self, provider_key_id: str | None, user, *, touch_last_used: bool = True
    ) -> LLMProviderKey | None:
        """
        Fetch provider key by ID.
        Returns LLMProviderKey or None if no key ID provided.
        Raises ValueError if key not found or user doesn't have access.
        """
        if not provider_key_id:
            return None

        team = getattr(user, "current_team", None)
        if not team:
            raise ValueError("No team associated with user")

        try:
            key = LLMProviderKey.objects.get(id=provider_key_id, team=team)
        except LLMProviderKey.DoesNotExist:
            raise ValueError("Provider key not found")

        api_key = key.encrypted_config.get("api_key")
        if not api_key and key.provider != LLMProvider.SYSTEM_ONE:
            raise ValueError("No API key configured for this provider key")

        if touch_last_used:
            key.last_used_at = timezone.now()
            key.save(update_fields=["last_used_at"])

        return key

    def validate_messages(self, messages: list[dict[str, Any]]) -> bool:
        if not messages:
            return False
        for msg in messages:
            if "role" not in msg or "content" not in msg:
                return False
        return True

    def _create_stream_generator(
        self,
        client: Client,
        request_obj: CompletionRequest,
        http_request,
        on_complete: Callable[[float], None] | None = None,
        on_error: Callable[[Exception, float], None] | None = None,
    ) -> Generator[bytes]:
        """Creates a generator that handles client disconnects and encodes responses"""
        started = perf_counter()
        try:
            with closing(client.stream(request_obj)) as stream:
                for chunk in stream:
                    if not http_request.META.get("SERVER_NAME"):  # Client disconnected
                        if on_error:
                            on_error(Exception("Client disconnected"), perf_counter() - started)
                        return
                    yield chunk.to_sse().encode()
        except (ProviderConfigurationError, ProviderHostUnresolvedError) as e:
            if on_error:
                on_error(e, perf_counter() - started)
            yield f"data: {json.dumps({'error': str(e), 'status_code': 400})}\n\n".encode()
        except Exception as e:
            if on_error:
                on_error(e, perf_counter() - started)
            logger.exception("llm_proxy_stream_error", error=str(e))
            yield f"data: {json.dumps({'error': 'An internal error occurred', 'status_code': 500})}\n\n".encode()
        else:
            if on_complete:
                try:
                    on_complete(perf_counter() - started)
                except Exception:
                    logger.exception("llm_proxy_on_complete_callback_error")

    def _create_streaming_response(self, stream: Generator[bytes]) -> HttpResponseBase:
        """Creates a properly configured SSE streaming response"""
        astream = SyncIterableToAsync(stream) if SERVER_GATEWAY_INTERFACE == "ASGI" else stream
        return sse_streaming_response(astream, endpoint="ai_observability_proxy")

    def _handle_completion_request(self, request: Request) -> HttpResponseBase | Response:
        """Handler for completion requests using unified Client"""
        try:
            if not request.user or not request.user.is_authenticated:
                return Response({"error": "You are not authorized to use this feature"}, status=401)

            organization = request.user.organization
            if not organization or not organization.customer_id:
                return Response(
                    {"error": "The playground requires a valid payment method on file to prevent abuse."},
                    status=402,
                )

            data = getattr(self, "_completion_validated_data", None)
            if data is None:
                serializer = LLMProxyCompletionSerializer(data=request.data)
                if not serializer.is_valid():
                    return Response({"error": serializer.errors}, status=400)
                data = serializer.validated_data
            model = data.get("model")
            thinking = data.get("thinking", False)

            # Validate thinking support
            if thinking and model not in SUPPORTED_MODELS_WITH_THINKING:
                return Response({"error": "Thinking is not supported for this model"}, status=400)

            # Validate messages
            messages = data.get("messages")
            if not self.validate_messages(messages):
                return Response({"error": "Invalid messages"}, status=400)

            # Fetch BYOK key if provider_key_id is specified
            provider_key_id = data.get("provider_key_id")
            try:
                provider_key = self._get_provider_key(provider_key_id, request.user)
            except ValueError:
                return Response({"error": "Invalid provider key configuration"}, status=400)

            # Enforce playground model allowlist when using PostHog-funded keys
            if provider_key is None and model not in PLAYGROUND_MODEL_IDS:
                return Response(
                    {
                        "error": f"Model '{model}' is not available on the PostHog-funded playground. Please add your own API key to use this model."
                    },
                    status=403,
                )

            # Provider is always explicit from request
            provider = data.get("provider")

            # Generate tracking parameters for PostHog analytics
            trace_id = str(uuid.uuid4())
            distinct_id = getattr(request.user, "email", "") if request.user and request.user.is_authenticated else ""
            properties = {"ai_product": "playground"}
            group_properties = groups(team=getattr(request.user, "current_team", None))

            # Create Client with analytics context
            client = Client(
                provider_key=provider_key,
                distinct_id=distinct_id,
                trace_id=trace_id,
                properties=properties,
                groups=group_properties,
            )

            # Build completion request
            completion_request = CompletionRequest(
                model=model,
                messages=messages,
                provider=provider,
                system=data.get("system"),
                temperature=data.get("temperature"),
                top_p=data.get("top_p"),
                seed=data.get("seed"),
                max_tokens=data.get("max_tokens"),
                tools=data.get("tools"),
                output_schema=self._build_output_schema(data.get("response_format")),
                thinking=thinking,
                reasoning_level=data.get("reasoning_level"),
            )

            # Track playground completion started
            tracking_properties = self._extract_request_properties(data, model=model)
            tracking_properties["trace_id"] = trace_id

            report_user_action(
                request.user,
                "llma playground completion started",
                tracking_properties,
                team=getattr(request.user, "current_team", None),
                request=request,
            )

            def on_complete(duration_s: float) -> None:
                report_user_action(
                    request.user,
                    "llma playground completion completed",
                    {**tracking_properties, "duration_seconds": duration_s},
                    team=getattr(request.user, "current_team", None),
                    request=request,
                )

            def on_error(error: Exception, duration_s: float) -> None:
                report_user_action(
                    request.user,
                    "llma playground completion stream failed",
                    {
                        **tracking_properties,
                        "duration_seconds": duration_s,
                        "error_type": type(error).__name__,
                        "error_message": str(error),
                    },
                    team=getattr(request.user, "current_team", None),
                    request=request,
                )

            # Create stream
            stream = self._create_stream_generator(client, completion_request, request, on_complete, on_error)

            return self._create_streaming_response(stream)

        except UnsupportedProviderError:
            return Response({"error": "Unsupported provider"}, status=400)

        except (ProviderConfigurationError, ProviderHostUnresolvedError) as e:
            # The key's stored endpoint is unusable or its host does not resolve. The message tells
            # the user what to check, so report it instead of logging an exception and returning a 500.
            return Response({"error": str(e)}, status=400)

        except Exception as e:
            logger.exception("llm_proxy_error", error=str(e))

            # Track playground completion failed
            if request.user and request.user.is_authenticated:
                error_properties: dict[str, Any] = {
                    "error_type": type(e).__name__,
                    "error_message": str(e),
                }

                # Try to extract request parameters to understand failure context
                try:
                    serializer = LLMProxyCompletionSerializer(data=request.data)
                    if serializer.is_valid():
                        request_properties = self._extract_request_properties(serializer.validated_data)
                        error_properties.update(request_properties)
                    else:
                        error_properties["validation_errors"] = serializer.errors
                except Exception:
                    pass

                report_user_action(
                    request.user,
                    "llma playground completion failed",
                    error_properties,
                    team=getattr(request.user, "current_team", None),
                    request=request,
                )

            return Response({"error": "An internal error occurred"}, status=500)

    @staticmethod
    def _build_output_schema(response_format: dict[str, Any] | None) -> OutputSchema | None:
        if not response_format:
            return None
        json_schema = response_format["json_schema"]
        return OutputSchema(schema=json_schema["schema"], name=json_schema["name"], strict=json_schema["strict"])

    def _extract_request_properties(self, validated_data: dict, model: str | None = None) -> dict:
        """Extract common properties from request for event tracking"""
        model_name = model or validated_data.get("model")
        properties = {
            "model": model_name,
            "thinking_enabled": validated_data.get("thinking", False),
            "has_tools": bool(validated_data.get("tools")),
            "has_temperature": validated_data.get("temperature") is not None,
            "has_top_p": validated_data.get("top_p") is not None,
            "has_seed": validated_data.get("seed") is not None,
            "has_max_tokens": validated_data.get("max_tokens") is not None,
            "has_reasoning_level": validated_data.get("reasoning_level") is not None,
            "has_response_format": validated_data.get("response_format") is not None,
            "has_system_prompt": bool(validated_data.get("system")),
        }

        # Add tool count if tools are present
        if validated_data.get("tools"):
            properties["tool_count"] = len(validated_data.get("tools", []))

        # Add message count if messages are present
        messages = validated_data.get("messages")
        if messages:
            properties["message_count"] = len(messages)

        # Get provider from validated data (now mandatory)
        if validated_data.get("provider"):
            properties["provider"] = validated_data["provider"]

        return properties

    @extend_schema(
        parameters=[
            OpenApiParameter(
                "provider_key_id", type=uuid.UUID, description="Team provider key whose models should be listed."
            )
        ],
        responses=LLMProxyModelInfoSerializer(many=True),
    )
    @action(detail=False, methods=["GET"])
    @llma_track_latency("llma_proxy_models")
    @monitor(feature=None, endpoint="llma_proxy_models", method="GET")
    def models(self, request):
        """Return a list of available models across providers.

        If provider_key_id is specified, returns models available for that key.
        Otherwise, returns only playground-eligible models (PostHog pays for these).
        """
        provider_key_id = request.query_params.get("provider_key_id")

        if provider_key_id:
            try:
                provider_key = self._get_provider_key(provider_key_id, request.user, touch_last_used=False)
            except ValueError:
                return Response({"error": "Invalid provider key configuration"}, status=400)

            if provider_key:
                return Response(provider_key_models(provider_key))

        # Default: return only playground-eligible models (PostHog pays for these)
        return Response(get_playground_models())

    @action(detail=False, methods=["POST"])
    @llma_track_latency("llma_proxy_completion")
    @monitor(feature=None, endpoint="llma_proxy_completion", method="POST")
    def completion(self, request, *args, **kwargs):
        return self._handle_completion_request(request)

    @validated_request(
        request_serializer=LLMProxyDecisionSerializer,
        responses={
            200: OpenApiResponse(response=LLMProxyDecisionResponseSerializer, description="One answer per question."),
            400: OpenApiResponse(
                response=LLMProxyErrorSerializer, description="The key or the endpoint rejected the request."
            ),
            402: OpenApiResponse(response=LLMProxyErrorSerializer, description="No payment method on file."),
        },
        summary="Ask a System One model",
        description="Ask the team's System One connection typed questions about a state, from the playground.",
    )
    @action(detail=False, methods=["POST"])
    @llma_track_latency("llma_proxy_decision")
    @monitor(feature=None, endpoint="llma_proxy_decision", method="POST")
    def decision(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
        organization = getattr(request.user, "organization", None)
        if not organization or not organization.customer_id:
            return Response(
                {"error": "The playground requires a valid payment method on file to prevent abuse."}, status=402
            )

        data = request.validated_data
        try:
            provider_key = self._get_provider_key(str(data["provider_key_id"]), request.user)
        except ValueError:
            provider_key = None
        # TypeSafe is not a subprocessor, so this path only reaches the team's own System One connection.
        if provider_key is None or provider_key.provider != LLMProvider.SYSTEM_ONE:
            return Response({"error": "Pick a System One connection to ask questions."}, status=400)

        config = provider_key.encrypted_config
        try:
            result = DecisionClient.evaluate(
                api_key=config.get("api_key", ""),
                base_url=config.get("base_url", ""),
                model=config.get("model", ""),
                state=data["state"],
                questions={
                    question_id: build_decision_question(question)
                    for question_id, question in data["questions"].items()
                },
            )
        except LLMError as error:
            return Response({"error": str(error)}, status=400)

        return Response(
            LLMProxyDecisionResponseSerializer(
                {
                    "model": result.model,
                    "answers": {
                        question_id: serialize_decision_answer(answer) for question_id, answer in result.answers.items()
                    },
                    "input_tokens": result.input_tokens,
                    "output_tokens": result.output_tokens,
                }
            ).data
        )