coding-client 1.21.2__py3-none-any.whl

coding_client/llm/__init__.py

@@ -0,0 +1,54 @@
+"""Shared LLM client for coding-* services.
+
+Public API:
+    BaseLLMAgent: Abstract base class wrapping pydantic-ai + inference-router.
+    LLMSettings: pydantic-settings model for env vars.
+    llm_request_context: contextmanager attaching X-Tenant-Id / X-Job-Id /
+        X-License-Id / X-Schema-Id headers to LLM-plane HTTP requests.
+    last_inference_id / last_failover_chain_id: helpers to read the
+        inference-router metadata captured from the most recent _call_llm.
+    AgentRouting + AGENT_ROUTING_REGISTRY: routing-rule registry used by
+        scripts/register_routing_rules.py to bootstrap model-registry.
+    Response models:
+        TestFailureAnalysisResponse, CodeQualityAnalysisResponse,
+        PerformanceAnalysisResponse, plus their nested item types.
+    LLMEmptyResponseError: raised when the LLM plane returns nothing usable.
+"""
+
+from __future__ import annotations
+
+from coding_client.exceptions.pydantic_ai_exceptions import LLMEmptyResponseError
+from coding_client.llm.base_agent import (
+    BaseLLMAgent,
+    close_llm_clients,
+    last_failover_chain_id,
+    last_inference_id,
+)
+from coding_client.llm.context import llm_request_context
+from coding_client.llm.responses import (
+    Bottleneck,
+    CodeQualityAnalysisResponse,
+    PerformanceAnalysisResponse,
+    QualityIssue,
+    TestFailureAnalysisResponse,
+)
+from coding_client.llm.routing import AGENT_ROUTING_REGISTRY, AgentRouting
+from coding_client.llm.settings import LLMSettings, get_llm_settings
+
+__all__ = [
+    "AGENT_ROUTING_REGISTRY",
+    "AgentRouting",
+    "BaseLLMAgent",
+    "Bottleneck",
+    "CodeQualityAnalysisResponse",
+    "LLMEmptyResponseError",
+    "LLMSettings",
+    "PerformanceAnalysisResponse",
+    "QualityIssue",
+    "TestFailureAnalysisResponse",
+    "close_llm_clients",
+    "get_llm_settings",
+    "last_failover_chain_id",
+    "last_inference_id",
+    "llm_request_context",
+]

coding_client/llm/base_agent.py

@@ -0,0 +1,195 @@
+"""Base LLM agent for coding-* services.
+
+Wraps pydantic-ai + an OpenAI-compatible endpoint (inference-router in
+production). Subclasses set ``schema_id``, ``response_model``, and provide
+a ``system_prompt`` (or override ``get_system_prompt``); they then call
+``self._call_llm(prompt)`` to get a parsed response model.
+
+The shared ``httpx.AsyncClient`` carries event hooks that:
+1. Inject X-Tenant-Id / X-Job-Id / X-License-Id / X-Schema-Id headers from
+   ``llm_request_context()``.
+2. Capture X-Inference-Id / X-Failover-Chain-Id from the response into a
+   contextvar sink that ``_call_llm`` reads back after the run completes.
+
+This module is import-safe: pydantic-ai / openai are imported lazily so
+just importing the package doesn't pull heavy deps into every consumer.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from contextvars import ContextVar
+from typing import Any, ClassVar
+
+import httpx
+from coding_client.exceptions.pydantic_ai_exceptions import LLMEmptyResponseError
+from coding_client.llm.context import (
+    apply_request_headers,
+    capture_response_metadata,
+    install_response_sink,
+    reset_response_sink,
+)
+from coding_client.llm.settings import LLMSettings, get_llm_settings
+from pydantic import BaseModel
+
+# Module-level singleton, mirrors karma's pattern.
+_llm_http_client: httpx.AsyncClient | None = None
+_last_metadata: ContextVar[dict[str, str]] = ContextVar(
+    "coding_client_last_llm_metadata",
+    default={},
+)
+
+
+def _get_llm_http_client(settings: LLMSettings) -> httpx.AsyncClient:
+    """Get or create the shared httpx client used for all LLM-plane calls."""
+    global _llm_http_client
+    if _llm_http_client is None or _llm_http_client.is_closed:
+        _llm_http_client = httpx.AsyncClient(
+            timeout=settings.llm_api_timeout_seconds,
+            event_hooks={
+                "request": [apply_request_headers],
+                "response": [capture_response_metadata],
+            },
+        )
+    return _llm_http_client
+
+
+async def close_llm_clients() -> None:
+    """Close the shared httpx client. Call from FastAPI lifespan shutdown."""
+    global _llm_http_client
+    if _llm_http_client is not None and not _llm_http_client.is_closed:
+        await _llm_http_client.aclose()
+    _llm_http_client = None
+
+
+def last_inference_id() -> str | None:
+    """Return X-Inference-Id captured during the most recent _call_llm, if any."""
+    return _last_metadata.get({}).get("inference_id")
+
+
+def last_failover_chain_id() -> str | None:
+    """Return X-Failover-Chain-Id captured during the most recent _call_llm, if any."""
+    return _last_metadata.get({}).get("failover_chain_id")
+
+
+class BaseLLMAgent(ABC):
+    """Abstract base class for coding-* LLM agents.
+
+    Subclasses set:
+
+    * ``schema_id``: stable identifier registered in model-registry.
+    * ``response_model``: pydantic model for structured output.
+    * ``system_prompt``: default system prompt (overridable per call).
+    """
+
+    schema_id: ClassVar[str] = ""
+    response_model: ClassVar[type[BaseModel] | None] = None
+    system_prompt: ClassVar[str] = ""
+
+    def __init__(self, settings: LLMSettings | None = None):
+        """Initialize the agent.
+
+        Args:
+            settings: Optional LLMSettings override; defaults to the singleton.
+        """
+        self.settings = settings or get_llm_settings()
+        if not self.schema_id:
+            raise ValueError(f"{type(self).__name__} must set the class attribute 'schema_id'")
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> Any:
+        """Execute the agent's main task. Subclasses implement."""
+        raise NotImplementedError
+
+    def get_system_prompt(self) -> str:
+        """Return the system prompt for this call (overridable)."""
+        return self.system_prompt
+
+    async def _call_llm(
+        self,
+        prompt: str,
+        system_prompt: str | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        """Call the configured LLM plane via pydantic-ai.
+
+        Args:
+            prompt: User prompt to send.
+            system_prompt: Optional override; defaults to ``get_system_prompt()``.
+            response_model: Optional structured-output type; defaults to the
+                class-level ``response_model``.
+
+        Returns:
+            Parsed pydantic instance when a response model is in play,
+            otherwise the raw stripped response text.
+
+        Raises:
+            LLMEmptyResponseError: Underlying pydantic-ai retry budget
+                exhausted, or empty/whitespace text in unstructured mode.
+            httpx.HTTPError: Transport-level failure.
+        """
+        # Lazy imports — keep coding-client importable without pydantic-ai.
+        from openai import AsyncOpenAI
+        from pydantic_ai import Agent
+        from pydantic_ai.exceptions import AgentRunError
+        from pydantic_ai.models.openai import OpenAIChatModel
+        from pydantic_ai.providers.openai import OpenAIProvider
+
+        if system_prompt is None:
+            system_prompt = self.get_system_prompt()
+        if response_model is None:
+            response_model = self.response_model
+
+        http_client = _get_llm_http_client(self.settings)
+
+        # Mutable sink — see context.py for the rationale.
+        sink: dict[str, str] = {}
+        sink_token = install_response_sink(sink)
+
+        openai_client = AsyncOpenAI(
+            base_url=self.settings.llm_api_base_url or None,
+            api_key=self.settings.llm_api_key or "unused",
+            http_client=http_client,
+            max_retries=0,
+        )
+        provider = OpenAIProvider(openai_client=openai_client)
+        model = OpenAIChatModel(self.schema_id, provider=provider)
+
+        output_type: Any = response_model if response_model is not None else str
+        pai_agent = Agent(
+            model,
+            system_prompt=system_prompt,
+            output_type=output_type,
+            retries=1,
+        )
+
+        try:
+            result = await pai_agent.run(prompt)
+        except AgentRunError as exc:
+            _last_metadata.set(dict(sink))
+            raise LLMEmptyResponseError(
+                f"LLM plane returned no usable output for {type(self).__name__}: {exc}",
+                agent_name=type(self).__name__,
+                cause=exc,
+            ) from exc
+        finally:
+            reset_response_sink(sink_token)
+
+        _last_metadata.set(dict(sink))
+
+        if response_model is not None:
+            return result.output
+
+        output = result.output
+        if output is None:
+            raise LLMEmptyResponseError(
+                f"LLM plane returned empty output for {type(self).__name__}",
+                agent_name=type(self).__name__,
+            )
+        text = str(output).strip()
+        if not text:
+            raise LLMEmptyResponseError(
+                f"LLM plane returned whitespace-only output for {type(self).__name__}",
+                agent_name=type(self).__name__,
+            )
+        return text

coding_client/llm/context.py

@@ -0,0 +1,121 @@
+"""Per-request context plumbing for inference-router headers.
+
+Uses contextvars so that nested asyncio tasks (pydantic-ai schedules child
+tasks during a single Agent.run) inherit the routing identity automatically.
+
+Critical: the response-side metadata sink uses a MUTABLE dict pattern. The
+parent installs an empty dict via ``ContextVar.set(...)``; the response
+event hook ``.update()``s that dict in place. This works across child task
+boundaries because asyncio.copy_context shares the reference — whereas a
+``.set()`` inside a child task would be invisible to the parent.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    import httpx
+
+
+_llm_request_context: ContextVar[dict[str, str]] = ContextVar(
+    "coding_client_llm_request_context",
+    default={},
+)
+_llm_response_metadata: ContextVar[dict[str, str] | None] = ContextVar(
+    "coding_client_llm_response_metadata",
+    default=None,
+)
+
+
+@contextmanager
+def llm_request_context(
+    *,
+    tenant_id: str | None = None,
+    job_id: str | None = None,
+    license_id: str | None = None,
+    schema_id: str | None = None,
+) -> Iterator[None]:
+    """Attach request-scoped routing headers for downstream LLM calls.
+
+    Usage::
+
+        with llm_request_context(tenant_id="t1", job_id="j2"):
+            await agent._call_llm(...)
+    """
+    current = dict(_llm_request_context.get({}))
+    updates = {
+        key: value
+        for key, value in {
+            "tenant_id": tenant_id,
+            "job_id": job_id,
+            "license_id": license_id,
+            "schema_id": schema_id,
+        }.items()
+        if value
+    }
+    token = _llm_request_context.set({**current, **updates})
+    try:
+        yield
+    finally:
+        _llm_request_context.reset(token)
+
+
+def _current_request_headers() -> dict[str, str]:
+    """Build inference-router headers from the current contextvar state."""
+    ctx = _llm_request_context.get({})
+    headers: dict[str, str] = {}
+    if value := ctx.get("tenant_id"):
+        headers["X-Tenant-Id"] = value
+    if value := ctx.get("job_id"):
+        headers["X-Job-Id"] = value
+    if value := ctx.get("license_id"):
+        headers["X-License-Id"] = value
+    if value := ctx.get("schema_id"):
+        headers["X-Schema-Id"] = value
+    return headers
+
+
+async def apply_request_headers(request: httpx.Request) -> None:
+    """httpx request event hook: inject routing headers just before send."""
+    for header, value in _current_request_headers().items():
+        request.headers[header] = value
+
+
+async def capture_response_metadata(response: httpx.Response) -> None:
+    """httpx response event hook: write inference-router metadata to sink."""
+    sink = _llm_response_metadata.get()
+    if sink is None:
+        return
+    headers = response.headers
+    for key, candidates in (
+        ("inference_id", ("X-Inference-Id", "inference-id")),
+        ("failover_chain_id", ("X-Failover-Chain-Id", "failover-chain-id")),
+    ):
+        for candidate in candidates:
+            value = headers.get(candidate)
+            if value:
+                sink[key] = value
+                break
+
+
+def install_response_sink(sink: dict[str, str]):
+    """Install a metadata sink for the duration of one LLM call.
+
+    Returns the contextvar token; the caller must reset it in a finally.
+    """
+    return _llm_response_metadata.set(sink)
+
+
+def reset_response_sink(token) -> None:
+    """Reset the response sink contextvar to its prior state."""
+    _llm_response_metadata.reset(token)
+
+
+def current_response_sink() -> dict[str, str] | None:
+    """Return the currently installed response sink, if any (test helper)."""
+    return _llm_response_metadata.get()

coding_client/llm/responses.py

@@ -0,0 +1,102 @@
+"""Pydantic v2 response models for coding-* LLM agents.
+
+All models use ``extra="forbid"`` so pydantic-ai surfaces schema mismatches
+cleanly to inference-router (which then triggers fallback to the next
+provider in the chain).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# Test failure analysis (used by coding-testing).
+# ---------------------------------------------------------------------------
+
+
+class TestFailureAnalysisResponse(BaseModel):
+    """Structured analysis of a single failed test."""
+
+    __test__ = False  # Pytest: don't try to collect — class name starts with "Test".
+
+    model_config = ConfigDict(extra="forbid")
+
+    root_cause: str = Field(..., description="Concise root-cause explanation.")
+    suggested_fix: str = Field(..., description="Concrete, actionable fix.")
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Model confidence in the diagnosis (0..1).",
+    )
+    category: Literal[
+        "assertion",
+        "timeout",
+        "import",
+        "syntax",
+        "environment",
+        "flaky",
+        "other",
+    ] = Field(..., description="Failure category for routing/aggregation.")
+
+
+# ---------------------------------------------------------------------------
+# Code quality analysis (used by coding-ai).
+# ---------------------------------------------------------------------------
+
+
+class QualityIssue(BaseModel):
+    """One code-quality finding."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    severity: Literal["info", "warning", "error", "critical"]
+    category: str = Field(..., description="Issue category, e.g. 'maintainability'.")
+    description: str = Field(..., description="Human-readable issue description.")
+    suggested_refactor: str | None = Field(
+        default=None,
+        description="Optional suggested refactor, when actionable.",
+    )
+
+
+class CodeQualityAnalysisResponse(BaseModel):
+    """Structured code-quality analysis output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    issues: list[QualityIssue] = Field(
+        default_factory=list,
+        description="List of identified quality issues (may be empty).",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Performance analysis (used by coding-containers / coding-ai).
+# ---------------------------------------------------------------------------
+
+
+class Bottleneck(BaseModel):
+    """One performance bottleneck."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    location: str = Field(..., description="File path / function / span identifier.")
+    impact: Literal["low", "medium", "high"]
+    description: str = Field(..., description="Why this is a bottleneck.")
+    suggested_optimisation: str = Field(
+        ...,
+        description="Concrete optimisation suggestion.",
+    )
+
+
+class PerformanceAnalysisResponse(BaseModel):
+    """Structured performance-analysis output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    bottlenecks: list[Bottleneck] = Field(
+        default_factory=list,
+        description="Identified bottlenecks (may be empty).",
+    )

coding_client/llm/routing.py

@@ -0,0 +1,82 @@
+"""Routing-rule registry for coding-* LLM agents.
+
+Each entry maps a stable ``schema_id`` to its pydantic response model and
+optional fallback chain override. ``scripts/register_routing_rules.py``
+iterates this registry on deploy and PUTs each rule into model-registry so
+that inference-router can route + fall back per schema_id.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from coding_client.llm.responses import (
+    CodeQualityAnalysisResponse,
+    PerformanceAnalysisResponse,
+    TestFailureAnalysisResponse,
+)
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class AgentRouting:
+    """Routing config for a single coding-* LLM agent."""
+
+    schema_id: str
+    response_model: type[BaseModel]
+    fallback_chain: list[str] | None = field(default=None)
+    system_prompt: str = field(default="")
+
+
+AGENT_ROUTING_REGISTRY: dict[str, AgentRouting] = {
+    "test_failure_analysis": AgentRouting(
+        schema_id="test_failure_analysis",
+        response_model=TestFailureAnalysisResponse,
+        system_prompt=(
+            "You are a senior test engineer. Diagnose the failed test and "
+            "return a structured root cause, fix, confidence, and category."
+        ),
+    ),
+    "code_quality_analysis": AgentRouting(
+        schema_id="code_quality_analysis",
+        response_model=CodeQualityAnalysisResponse,
+        system_prompt=(
+            "You are a senior code reviewer. Identify quality issues with "
+            "severity, category, description, and an optional refactor."
+        ),
+    ),
+    "performance_analysis": AgentRouting(
+        schema_id="performance_analysis",
+        response_model=PerformanceAnalysisResponse,
+        system_prompt=(
+            "You are a performance engineer. Identify bottlenecks and "
+            "propose concrete optimisations."
+        ),
+    ),
+}
+
+
+def build_routing_rule_payload(
+    routing: AgentRouting,
+    *,
+    default_fallback_chain: list[str],
+) -> dict[str, Any]:
+    """Build the model-registry PUT body for one routing rule.
+
+    Mirrors ``UpdateRoutingRequest`` in model-registry. Endpoint is
+    ``PUT /api/routing/{schema_id}`` — see the bootstrap script.
+    """
+    chain = list(routing.fallback_chain or default_fallback_chain)
+    if not chain:
+        raise ValueError(f"AgentRouting {routing.schema_id} resolved to an empty fallback chain")
+    return {
+        "fallback_chain": chain,
+        "json_schema": routing.response_model.model_json_schema(),
+        "system_prompt": routing.system_prompt,
+    }
+
+
+def build_routing_rule_url(base_url: str, schema_id: str) -> str:
+    """Build the model-registry endpoint URL for one routing rule."""
+    return f"{base_url.rstrip('/')}/api/routing/{schema_id}"

coding_client/llm/settings.py

@@ -0,0 +1,102 @@
+"""LLM client settings.
+
+All env vars are read via pydantic-settings so callers can subclass or
+override per-service. Production deployments inject these via the
+the platform repo Deployment env block / SOPS secrets.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LLMSettings(BaseSettings):
+    """Settings for LLM-plane access.
+
+    Production points ``llm_api_base_url`` at inference-router; dev/bypass
+    can point it at OpenAI, Ollama, LM Studio, or any other OpenAI-compatible
+    endpoint.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=None,
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    llm_api_base_url: str = Field(
+        default="",
+        description=(
+            "OpenAI-compatible base URL. In production: the inference-router "
+            "service URL. Required when llm_mode=='inference_router' and the "
+            "service is actually wired up."
+        ),
+    )
+    llm_api_key: str = Field(
+        default="",
+        description=(
+            "API key for the OpenAI-compatible endpoint. Inference-router "
+            "doesn't consume this; pydantic-ai/openai SDK requires non-empty."
+        ),
+    )
+    llm_mode: Literal["inference_router", "direct"] = Field(
+        default="inference_router",
+        description="Plane mode: inference-router (provider chain) or direct.",
+    )
+    llm_api_timeout_seconds: float = Field(
+        default=300.0,
+        description="httpx timeout for LLM-plane calls (seconds).",
+    )
+    llm_routing_default_fallback_chain: str = Field(
+        # Must name inference-router PROVIDERS, not models. The historical
+        # "gemma,deepseek,claude" default named zero usable pairs: `gemma` is a
+        # MODEL served by the `pgx-local` provider and is not a provider name in
+        # the router catalog at all, and the `claude` provider ships
+        # `enabled: false`. Both were therefore dropped at resolution and the
+        # chain collapsed to the single hop ["deepseek"] — a "fallback chain"
+        # with no fallback. `pgx-local,deepseek` mirrors inference-router's live
+        # `default_chain: [pgx-local, deepseek]` (see the platform repo
+        # clusters/strato/services/inference-router/providers-configmap.yaml):
+        # free local vLLM primary, paid DeepSeek failover while pgx is DEGRADED.
+        default="pgx-local,deepseek",
+        description="Comma-separated default fallback chain for routing rules.",
+    )
+    model_registry_url: str = Field(
+        default="",
+        description=(
+            "Base URL for model-registry — used by routing-rule bootstrap. "
+            "Production injects via env var MODEL_REGISTRY_URL on the Deployment "
+            "(see the platform configuration policy)."
+        ),
+    )
+
+    @field_validator("llm_routing_default_fallback_chain")
+    @classmethod
+    def _strip_csv(cls, value: str) -> str:
+        return value.strip()
+
+    @property
+    def fallback_chain_list(self) -> list[str]:
+        """Parse the CSV fallback chain into a list."""
+        raw = self.llm_routing_default_fallback_chain
+        return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+_settings: LLMSettings | None = None
+
+
+def get_llm_settings() -> LLMSettings:
+    """Get LLMSettings singleton."""
+    global _settings
+    if _settings is None:
+        _settings = LLMSettings()
+    return _settings
+
+
+def reset_llm_settings() -> None:
+    """Reset the cached settings singleton (test helper)."""
+    global _settings
+    _settings = None