crupier 0.1.0__py3-none-any.whl

crupier/__init__.py

@@ -0,0 +1,178 @@
+"""Crupier public API."""
+
+from .client import Crupier
+from .autopatch import install
+from .errors import (
+    CrupierBudgetExceededError,
+    CrupierConfigError,
+    CrupierError,
+    CrupierModelUnsupportedError,
+    CrupierPolicyError,
+    CrupierProviderAuthError,
+    CrupierProviderRateLimitError,
+    CrupierProviderUnavailableError,
+    CrupierRouteValidationError,
+    CrupierStructuredOutputError,
+    CrupierToolApprovalRequired,
+    CrupierUpdateRequiresConfirmation,
+)
+from .evals import (
+    CompareDatasetCaseResult,
+    CompareDatasetModelScore,
+    CompareDatasetReport,
+    CompareHistoryReport,
+    CompareRunReport,
+    CompareVariant,
+    CompareVariantResult,
+)
+from .feedback import (
+    HumanDecisionImportResult,
+    HumanFeedbackRecord,
+    HumanFeedbackStore,
+    HumanReviewItem,
+    HumanReviewPacket,
+    build_human_review_packet,
+    build_human_decision_template,
+    import_human_decisions,
+    write_human_decision_template,
+    write_human_review_packet,
+)
+from .models import (
+    CapabilityCard,
+    CostEstimate,
+    CrupierResult,
+    DecisionTrace,
+    FileAsset,
+    FileRepresentation,
+    FileRoutingPlan,
+    ModelRef,
+    PlanningContext,
+    RequestEnvelope,
+    RoutePlan,
+    RouteStep,
+)
+from .orchestrator import DeterministicOrchestrator, ModelOrchestrator, Orchestrator
+from .project_audit import (
+    AdoptionOption,
+    AdoptionHandoffReport,
+    AdoptionPatchReport,
+    AdoptionPatchSuggestion,
+    AuditCheck,
+    CodeComment,
+    CodeCommentReviewSummary,
+    DoctorGate,
+    ProjectAdoptionPlan,
+    ProjectAuditReport,
+    ProjectDoctorReport,
+    ProjectAuditRunner,
+    RouteReview,
+    acknowledge_code_comments,
+    build_adoption_handoff,
+    build_adoption_handoff_from_doctor,
+    build_adoption_patches,
+    build_adoption_plan,
+    build_config_free_adoption_handoff,
+    build_config_free_project_doctor,
+    build_project_doctor,
+    import_code_comment_decisions,
+    read_adoption_signoffs,
+    record_adoption_signoff,
+    summarize_applied_human_feedback,
+    summarize_adoption_signoffs,
+    summarize_code_comment_reviews,
+    write_adoption_package_index,
+    write_code_comment_decision_template,
+    write_code_comments_sarif,
+    write_code_review_comments,
+)
+from .probes import CapabilityProbeRunner, ProbeReport, ProbeResult, ReadinessItem, ReadinessReport
+from .trace_store import StoredTraceRef, TraceStore
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "CapabilityCard",
+    "CapabilityProbeRunner",
+    "CostEstimate",
+    "CompareDatasetCaseResult",
+    "CompareDatasetModelScore",
+    "CompareDatasetReport",
+    "CompareHistoryReport",
+    "CompareRunReport",
+    "CompareVariant",
+    "CompareVariantResult",
+    "Crupier",
+    "CrupierBudgetExceededError",
+    "CrupierConfigError",
+    "CrupierError",
+    "CrupierModelUnsupportedError",
+    "CrupierPolicyError",
+    "CrupierProviderAuthError",
+    "CrupierProviderRateLimitError",
+    "CrupierProviderUnavailableError",
+    "CrupierResult",
+    "CrupierRouteValidationError",
+    "CrupierStructuredOutputError",
+    "CrupierToolApprovalRequired",
+    "CrupierUpdateRequiresConfirmation",
+    "DecisionTrace",
+    "FileAsset",
+    "FileRepresentation",
+    "FileRoutingPlan",
+    "HumanDecisionImportResult",
+    "HumanFeedbackRecord",
+    "HumanFeedbackStore",
+    "HumanReviewItem",
+    "HumanReviewPacket",
+    "build_human_decision_template",
+    "build_human_review_packet",
+    "import_human_decisions",
+    "install",
+    "ModelRef",
+    "PlanningContext",
+    "DeterministicOrchestrator",
+    "ModelOrchestrator",
+    "Orchestrator",
+    "AuditCheck",
+    "AdoptionHandoffReport",
+    "AdoptionOption",
+    "AdoptionPatchReport",
+    "AdoptionPatchSuggestion",
+    "acknowledge_code_comments",
+    "build_adoption_handoff",
+    "build_adoption_handoff_from_doctor",
+    "build_adoption_patches",
+    "build_adoption_plan",
+    "build_config_free_adoption_handoff",
+    "build_config_free_project_doctor",
+    "build_project_doctor",
+    "import_code_comment_decisions",
+    "read_adoption_signoffs",
+    "record_adoption_signoff",
+    "CodeComment",
+    "CodeCommentReviewSummary",
+    "DoctorGate",
+    "ProbeReport",
+    "ProbeResult",
+    "ProjectAuditReport",
+    "ProjectDoctorReport",
+    "ProjectAuditRunner",
+    "ProjectAdoptionPlan",
+    "ReadinessItem",
+    "ReadinessReport",
+    "RequestEnvelope",
+    "RoutePlan",
+    "RouteStep",
+    "RouteReview",
+    "StoredTraceRef",
+    "summarize_applied_human_feedback",
+    "summarize_adoption_signoffs",
+    "summarize_code_comment_reviews",
+    "write_adoption_package_index",
+    "write_code_comment_decision_template",
+    "write_code_comments_sarif",
+    "write_code_review_comments",
+    "TraceStore",
+    "write_human_decision_template",
+    "write_human_review_packet",
+]

crupier/__main__.py

@@ -0,0 +1,6 @@
+"""Run Crupier as ``python -m crupier``."""
+
+from .cli import main
+
+
+raise SystemExit(main())

crupier/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Provider adapters."""
+
+from .base import AdapterResponse, EmbeddingResponse, ProviderAdapter, ProviderModel
+from .factory import build_default_adapters
+from .openrouter import OpenRouterAdapter
+
+__all__ = [
+    "AdapterResponse",
+    "EmbeddingResponse",
+    "OpenRouterAdapter",
+    "ProviderAdapter",
+    "ProviderModel",
+    "build_default_adapters",
+]

crupier/adapters/anthropic.py

@@ -0,0 +1,267 @@
+"""Anthropic Claude Messages API adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crupier.config import ProviderSettings
+from crupier.errors import (
+    CrupierProviderAuthError,
+    CrupierProviderRateLimitError,
+    CrupierProviderUnavailableError,
+)
+from crupier.models import RequestEnvelope
+from crupier.multimodal import native_image_payloads
+
+from .base import AdapterResponse, ProviderModel
+from .common import (
+    build_prompt,
+    extract_anthropic_text,
+    object_to_dict,
+    provider_timeout_seconds,
+    request_timeout_seconds,
+    require_api_key,
+)
+
+
+class AnthropicAdapter:
+    provider = "anthropic"
+
+    def __init__(self, settings: ProviderSettings):
+        self.settings = settings
+        self._client: Any = None
+
+    def generate(self, *, model: str, prompt: str, request: RequestEnvelope) -> AdapterResponse:
+        client = self._client or self._build_client()
+        self._client = client
+        max_tokens = int(request.constraints.get("max_output_tokens", request.constraints.get("max_tokens", 1024)))
+        content: Any = prompt or build_prompt(request)
+        image_payloads = []
+        if request.files:
+            image_payloads = native_image_payloads(request.files)
+            content = [{"type": "text", "text": content}]
+            content.extend(
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": image["mime_type"],
+                        "data": image["base64"],
+                    },
+                }
+                for image in image_payloads
+            )
+        payload: dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": content}],
+        }
+        if "temperature" in request.constraints:
+            payload["temperature"] = request.constraints["temperature"]
+        timeout = request_timeout_seconds(request)
+        if timeout is not None:
+            payload["timeout"] = timeout
+
+        message, removed_params = self._messages_create_with_param_repair(client, payload)
+
+        text = extract_anthropic_text(message)
+        usage = object_to_dict(getattr(message, "usage", None))
+        return AdapterResponse(
+            text=text,
+            raw=message,
+            usage=usage,
+            metadata={
+                "provider": self.provider,
+                "model": model,
+                "api": "messages.create",
+                "removed_params": removed_params,
+                "multimodal_images": len(image_payloads),
+            },
+        )
+
+    def list_models(self) -> list[ProviderModel]:
+        client = self._client or self._build_client()
+        self._client = client
+        try:
+            response = client.models.list()
+        except AttributeError as exc:
+            raise CrupierProviderUnavailableError(
+                "Installed anthropic SDK does not expose client.models.list(); upgrade the optional dependency."
+            ) from exc
+        except Exception as exc:  # noqa: BLE001
+            self._raise_mapped_error(exc)
+
+        data = getattr(response, "data", response)
+        models: list[ProviderModel] = []
+        for item in data:
+            model_id = item.get("id") if isinstance(item, dict) else getattr(item, "id", None)
+            if not model_id:
+                continue
+            name = item.get("display_name") if isinstance(item, dict) else getattr(item, "display_name", None)
+            metadata = item if isinstance(item, dict) else object_to_dict(item)
+            models.append(ProviderModel(id=str(model_id), provider=self.provider, name=name, metadata=metadata))
+        return sorted(models, key=lambda model: model.id)
+
+    def probe_capability(self, *, model: str, probe: str, request: RequestEnvelope) -> AdapterResponse:
+        if probe == "structured_output":
+            return self._probe_tool_schema(model=model, request=request, capability="structured_output")
+        if probe == "tool_call":
+            return self._probe_tool_schema(model=model, request=request, capability="tool_call")
+        if probe == "streaming":
+            return self._probe_streaming(model=model, request=request)
+        raise NotImplementedError(f"Anthropic adapter has no native probe registered for {probe!r}.")
+
+    def _probe_tool_schema(self, *, model: str, request: RequestEnvelope, capability: str) -> AdapterResponse:
+        client = self._client or self._build_client()
+        self._client = client
+        tool_name = "crupier_probe_tool"
+        payload = {
+            "model": model,
+            "max_tokens": int(request.constraints.get("max_output_tokens", 128)),
+            "messages": [{"role": "user", "content": "Use the crupier_probe_tool with ok=true and probe='crupier'."}],
+            "tools": [
+                {
+                    "name": tool_name,
+                    "description": "Report that the capability probe succeeded.",
+                    "input_schema": _probe_schema(),
+                }
+            ],
+            "tool_choice": {"type": "tool", "name": tool_name},
+        }
+        timeout = request_timeout_seconds(request)
+        if timeout is not None:
+            payload["timeout"] = timeout
+        try:
+            message = client.messages.create(**payload)
+        except Exception as exc:  # noqa: BLE001
+            self._raise_mapped_error(exc)
+        ok = _anthropic_has_tool_use(message, tool_name)
+        return AdapterResponse(
+            text="",
+            raw=message,
+            usage=object_to_dict(getattr(message, "usage", None)),
+            metadata={
+                "provider": self.provider,
+                "model": model,
+                "api": "messages.create",
+                "native_probe": True,
+                "capability": capability,
+                "ok": ok,
+                "probe_status": "verified" if ok else "failed",
+                "tool_name": tool_name,
+            },
+        )
+
+    def _probe_streaming(self, *, model: str, request: RequestEnvelope) -> AdapterResponse:
+        client = self._client or self._build_client()
+        self._client = client
+        try:
+            payload: dict[str, Any] = {
+                "model": model,
+                "max_tokens": 16,
+                "messages": [{"role": "user", "content": 'Reply with exactly: "stream-ok"'}],
+                "stream": True,
+            }
+            timeout = request_timeout_seconds(request)
+            if timeout is not None:
+                payload["timeout"] = timeout
+            stream = client.messages.create(**payload)
+            event_count = 0
+            text_seen = False
+            for event in stream:
+                event_count += 1
+                if _event_has_text(event):
+                    text_seen = True
+                if event_count >= 20 and text_seen:
+                    break
+        except Exception as exc:  # noqa: BLE001
+            self._raise_mapped_error(exc)
+        ok = event_count > 0
+        return AdapterResponse(
+            text="",
+            raw=None,
+            metadata={
+                "provider": self.provider,
+                "model": model,
+                "api": "messages.create",
+                "native_probe": True,
+                "ok": ok,
+                "probe_status": "verified" if ok else "failed",
+                "event_count": event_count,
+                "text_event_seen": text_seen,
+            },
+        )
+
+    def _build_client(self) -> Any:
+        api_key = require_api_key(self.settings, "ANTHROPIC_API_KEY", provider=self.provider)
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:
+            raise CrupierProviderUnavailableError(
+                "Anthropic adapter requires the optional dependency: pip install 'crupier[anthropic]'.",
+                retryable=False,
+            ) from exc
+        kwargs: dict[str, Any] = {"api_key": api_key}
+        if self.settings.host:
+            kwargs["base_url"] = self.settings.host
+        timeout = provider_timeout_seconds(self.settings)
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return Anthropic(**kwargs)
+
+    def _messages_create_with_param_repair(self, client: Any, payload: dict[str, Any]) -> tuple[Any, list[str]]:
+        try:
+            return client.messages.create(**payload), []
+        except Exception as exc:  # noqa: BLE001 - provider SDK exceptions vary by version
+            if "temperature" in payload and _is_temperature_deprecated(exc):
+                repaired = dict(payload)
+                repaired.pop("temperature", None)
+                try:
+                    return client.messages.create(**repaired), ["temperature"]
+                except Exception as repaired_exc:  # noqa: BLE001
+                    self._raise_mapped_error(repaired_exc)
+            self._raise_mapped_error(exc)
+
+    def _raise_mapped_error(self, exc: Exception) -> None:
+        name = exc.__class__.__name__.lower()
+        if "auth" in name or "permission" in name:
+            raise CrupierProviderAuthError(str(exc), provider=self.provider, env_key=self.settings.env_key) from exc
+        if "ratelimit" in name or "rate_limit" in name:
+            raise CrupierProviderRateLimitError(str(exc)) from exc
+        raise CrupierProviderUnavailableError(f"Anthropic request failed: {exc}") from exc
+
+
+def _is_temperature_deprecated(exc: Exception) -> bool:
+    text = str(exc).lower()
+    return "temperature" in text and "deprecated" in text
+
+
+def _probe_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "ok": {"type": "boolean"},
+            "probe": {"type": "string"},
+        },
+        "required": ["ok", "probe"],
+        "additionalProperties": False,
+    }
+
+
+def _anthropic_has_tool_use(message: Any, tool_name: str) -> bool:
+    content = message.get("content", []) if isinstance(message, dict) else getattr(message, "content", [])
+    for block in content or []:
+        block_type = block.get("type") if isinstance(block, dict) else getattr(block, "type", None)
+        name = block.get("name") if isinstance(block, dict) else getattr(block, "name", None)
+        if block_type == "tool_use" and name == tool_name:
+            return True
+    return False
+
+
+def _event_has_text(event: Any) -> bool:
+    if isinstance(event, dict):
+        return bool(event.get("delta") or event.get("text") or event.get("content_block"))
+    for attr in ["delta", "text", "content_block"]:
+        if getattr(event, attr, None):
+            return True
+    return False

crupier/adapters/base.py

@@ -0,0 +1,83 @@
+"""Provider adapter contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Protocol
+
+from crupier.models import RequestEnvelope
+
+
+@dataclass(slots=True)
+class AdapterResponse:
+    text: str
+    raw: Any = None
+    usage: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class EmbeddingResponse:
+    embeddings: list[list[float]]
+    raw: Any = None
+    usage: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ProviderModel:
+    id: str
+    provider: str
+    name: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def model_ref(self) -> str:
+        return f"{self.provider}:{self.id}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "provider": self.provider,
+            "model_ref": self.model_ref,
+            "name": self.name,
+            "metadata": _jsonable(self.metadata),
+        }
+
+
+class ProviderAdapter(Protocol):
+    provider: str
+
+    def generate(self, *, model: str, prompt: str, request: RequestEnvelope) -> AdapterResponse:
+        """Generate text for a normalized prompt."""
+
+    def list_models(self) -> list[ProviderModel]:
+        """List models available to the configured account/provider."""
+
+    def probe_capability(self, *, model: str, probe: str, request: RequestEnvelope) -> AdapterResponse:
+        """Run a provider-native capability probe when supported."""
+
+    def embed(self, *, model: str, input: Any) -> EmbeddingResponse:
+        """Create embeddings when the provider/model supports it."""
+
+
+def _jsonable(value: Any) -> Any:
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, datetime | date):
+        return value.isoformat()
+    if isinstance(value, Mapping):
+        return {str(key): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, set):
+        return sorted((_jsonable(item) for item in value), key=repr)
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        return [_jsonable(item) for item in value]
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return _jsonable(model_dump())
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict):
+        return _jsonable(to_dict())
+    return repr(value)

crupier/adapters/common.py

@@ -0,0 +1,130 @@
+"""Shared adapter helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from crupier.config import ProviderSettings
+from crupier.errors import CrupierProviderAuthError
+from crupier.models import RequestEnvelope
+
+
+def env_value(settings: ProviderSettings, default_env_key: str, *, provider: str) -> str | None:
+    env_key = settings.env_key or default_env_key
+    value = os.environ.get(env_key)
+    if not value:
+        return None
+    return value
+
+
+def require_api_key(settings: ProviderSettings, default_env_key: str, *, provider: str) -> str:
+    env_key = settings.env_key or default_env_key
+    value = os.environ.get(env_key)
+    if not value:
+        raise CrupierProviderAuthError(
+            f"Missing API key for provider {provider!r}.",
+            provider=provider,
+            env_key=env_key,
+            hint=f"Set {env_key} or update [providers.{provider}].env_key in crupier.toml.",
+        )
+    return value
+
+
+def provider_timeout_seconds(settings: ProviderSettings, *, default: float | None = None) -> float | None:
+    value = settings.options.get("timeout_seconds", settings.options.get("timeout", default))
+    return _positive_float(value)
+
+
+def request_timeout_seconds(request: RequestEnvelope, *, default: float | None = None) -> float | None:
+    value = request.constraints.get("timeout_seconds", request.constraints.get("timeout", default))
+    return _positive_float(value)
+
+
+def _positive_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None
+
+
+def build_prompt(request: RequestEnvelope, *, extra: str | None = None) -> str:
+    parts = [f"Task:\n{request.task}"]
+    if request.messages:
+        parts.append("Messages:\n" + _format_input(request.messages))
+    if request.input is not None:
+        parts.append("Input:\n" + _format_input(request.input))
+    file_context = request.metadata.get("extracted_file_context") if request.metadata else None
+    if isinstance(file_context, dict) and file_context.get("body"):
+        parts.append("File context:\n" + str(file_context["body"]))
+    if extra:
+        parts.append(extra)
+    return "\n\n".join(parts)
+
+
+def _format_input(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
+    except TypeError:
+        return repr(value)
+
+
+def extract_openai_text(response: Any) -> str:
+    output_text = getattr(response, "output_text", None)
+    if output_text:
+        return str(output_text)
+    if isinstance(response, dict):
+        if response.get("output_text"):
+            return str(response["output_text"])
+        output = response.get("output", [])
+    else:
+        output = getattr(response, "output", [])
+    chunks: list[str] = []
+    for item in output or []:
+        content = item.get("content", []) if isinstance(item, dict) else getattr(item, "content", [])
+        for block in content or []:
+            if isinstance(block, dict):
+                text = block.get("text") or block.get("output_text")
+            else:
+                text = getattr(block, "text", None)
+            if text:
+                chunks.append(str(text))
+    return "".join(chunks)
+
+
+def extract_anthropic_text(message: Any) -> str:
+    content = message.get("content", []) if isinstance(message, dict) else getattr(message, "content", [])
+    chunks: list[str] = []
+    for block in content or []:
+        if isinstance(block, dict):
+            if block.get("type") == "text" and block.get("text"):
+                chunks.append(str(block["text"]))
+        else:
+            text = getattr(block, "text", None)
+            if text:
+                chunks.append(str(text))
+    return "".join(chunks)
+
+
+def object_to_dict(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump()
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict):
+        return to_dict()
+    attrs = {}
+    for name in ["input_tokens", "output_tokens", "total_tokens"]:
+        if hasattr(value, name):
+            attrs[name] = getattr(value, name)
+    return attrs