Unified API: Kaapi Backend as a Proxy

backend/app/core/providers.py

@@ -17,6 +17,7 @@ class Provider(str, Enum):
     ANTHROPIC = "anthropic"
     GOOGLE_VERTEX = "google-vertex"
     WEBHOOK_SECRET = "webhook_secret"
+    PROXY = "proxy"
 
 
 @dataclass
@@ -61,6 +62,9 @@ class ProviderConfig:
     Provider.WEBHOOK_SECRET: ProviderConfig(
         required_fields=["webhook_secret"], sensitive_fields=["webhook_secret"]
     ),
+    Provider.PROXY: ProviderConfig(
+        required_fields=["api_key"], sensitive_fields=["api_key"]
+    ),
 }
 
 

backend/app/crud/model_config.py

@@ -117,6 +117,12 @@ def validate_blob_model_or_raise(session: Session, blob: ConfigBlob) -> None:
     completion = blob.completion
     raw_provider = completion.provider
     completion_type = completion.type
+
+    # Proxy forwards the request to the client's own LLM endpoint — no model
+    # lookup, no provider mapping.
+    if completion_type == "proxy":
+        return
+
     if raw_provider is None:
         return
 
@@ -125,7 +131,7 @@ def validate_blob_model_or_raise(session: Session, blob: ConfigBlob) -> None:
 
     provider = _normalize_provider(raw_provider)
 
-    model_name = (completion.params or {}).get("model")
+    model_name = (completion.params or {}).get("model") or None
     if not model_name:
         raise HTTPException(
             status_code=400,

backend/app/models/llm/request.py

@@ -69,6 +69,8 @@ class TextLLMParams(SQLModel):
 
 
 class STTLLMParams(SQLModel):
+    model_config = {"extra": "forbid"}
+
     model: str = DEFAULT_STT_MODEL
     instructions: str | None = None
     input_language: str | None = "auto"
@@ -86,17 +88,35 @@ class STTLLMParams(SQLModel):
 
 
 class TTSLLMParams(SQLModel):
+    model_config = {"extra": "forbid"}
+
     model: str = DEFAULT_TTS_MODEL
     voice: str = DEFAULT_TTS_VOICE
     language: str | None = None
     response_format: Literal["mp3", "wav", "ogg"] | None = "wav"
 
 
-KaapiLLMParams = Union[
-    TextLLMParams,
-    STTLLMParams,
-    TTSLLMParams,
-]
+class ProxyLLMParams(SQLModel):
+    model_config = {"extra": "forbid"}
+
+    client_llm_url: HttpUrl = Field(
+        ...,
+        description=(
+            "HTTPS URL of the client's own LLM endpoint. Kaapi forwards the "
+            "(guardrail-sanitised) input here and applies output guardrails to the response."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _require_https(self):
+        if self.client_llm_url.scheme != "https":
+            raise ValueError(
+                f"client_llm_url must be HTTPS, got scheme: {self.client_llm_url.scheme}"
+            )
+        return self
+
+
+KaapiLLMParams = Union[TextLLMParams, STTLLMParams, TTSLLMParams, ProxyLLMParams]
 
 
 # Input type models for discriminated union
@@ -232,14 +252,16 @@ class NativeCompletionConfig(SQLModel):
     Supports any LLM provider's native API format.
     """
 
-    provider: Literal[
-        "openai-native",
-        "google-native",
-        "sarvamai-native",
-        "elevenlabs-native",
-        "anthropic-native",
-        "google-vertex-native",
-    ] = Field(
+    provider: (
+        Literal[
+            "openai-native",
+            "google-native",
+            "sarvamai-native",
+            "elevenlabs-native",
+            "anthropic-native",
+            "google-vertex-native",
+        ]
+    ) = Field(
         ...,
         description="Native provider type (e.g., openai-native)",
     )
@@ -306,9 +328,39 @@ def validate_params(self):
         return self
 
 
+class ProxyCompletionConfig(SQLModel):
+    """
+    Proxy completion: Kaapi forwards the (guardrail-sanitised) input to the
+    client's own LLM endpoint and applies output guardrails to the response.
+    No upstream provider is dispatched — `provider` is fixed to "proxy" so
+    the discriminated union can route cleanly.
+    """
+
+    provider: Literal["proxy"] = Field(
+        "proxy",
+        description=(
+            "Discriminator value for the proxy variant. Auto-injected when "
+            "type=proxy; clients may omit it."
+        ),
+    )
+    type: Literal["proxy"] = Field(..., description="Must be 'proxy'.")
+    params: dict[str, Any] = Field(
+        ...,
+        description="Proxy params (client_llm_url, ...)",
+    )
+
+    @model_validator(mode="after")
+    def validate_params(self):
+        validated = ProxyLLMParams.model_validate(self.params)
+        # mode="json" coerces HttpUrl → plain str so downstream consumers
+        # (httpx.post, urlparse) get the type they expect from params dict.
+        self.params = validated.model_dump(mode="json", exclude_none=True)
+        return self
+
+
 # Discriminated union for completion configs based on provider field
 CompletionConfig = Annotated[
-    Union[NativeCompletionConfig, KaapiCompletionConfig],
+    Union[NativeCompletionConfig, KaapiCompletionConfig, ProxyCompletionConfig],
     Field(discriminator="provider"),
 ]
 
@@ -326,6 +378,21 @@ class ConfigBlob(SQLModel):
 
     completion: CompletionConfig = Field(..., description="Completion configuration")
 
+    @model_validator(mode="before")
+    @classmethod
+    def _default_proxy_provider(cls, data: Any) -> Any:
+        """For `type=proxy`, provider is meaningless to the caller.
+        Inject provider="proxy" so the CompletionConfig discriminator routes
+        to ProxyCompletionConfig without forcing the client to set it."""
+        if not isinstance(data, dict):
+            return data
+        completion = data.get("completion")
+        if isinstance(completion, dict) and completion.get("type") == "proxy":
+            existing = completion.get("provider")
+            if existing in (None, "proxy"):
+                completion["provider"] = "proxy"
+        return data
+
     # used for llm-chain to provide prompt interpolation
     prompt_template: PromptTemplate | None = Field(
         default=None,