alysis-code 0.13.0__py3-none-any.whl

alysis_code/llm/streaming.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from .types import LLMError
+
+
+@dataclass(frozen=True)
+class SSEFrame:
+    """A parsed Server-Sent Events frame.
+
+    The parser intentionally keeps this structure provider-neutral so native
+    Responses, Messages, and GenerateContent streaming paths can share it.
+    """
+
+    event: str
+    data: str
+    event_id: str | None = None
+    retry: int | None = None
+
+
+def iter_sse_frames(
+    lines: Iterable[str | bytes],
+    *,
+    done_sentinels: tuple[str, ...] = ("[DONE]",),
+    include_done: bool = False,
+) -> Iterator[SSEFrame]:
+    """Yield SSE frames from an iterable of response lines.
+
+    Handles `event:`, multi-line `data:`, comments, blank-line frame
+    boundaries, optional `id:` / `retry:`, and `[DONE]`-style sentinels.
+    """
+
+    event = "message"
+    event_id: str | None = None
+    retry: int | None = None
+    data_lines: list[str] = []
+
+    def _flush() -> SSEFrame | None:
+        nonlocal event, event_id, retry, data_lines
+        if not data_lines and event == "message" and event_id is None and retry is None:
+            return None
+        frame = SSEFrame(
+            event=event or "message",
+            data="\n".join(data_lines),
+            event_id=event_id,
+            retry=retry,
+        )
+        event = "message"
+        event_id = None
+        retry = None
+        data_lines = []
+        return frame
+
+    for raw_line in lines:
+        if isinstance(raw_line, bytes):
+            line = raw_line.decode("utf-8", errors="replace")
+        else:
+            line = raw_line
+        line = line.rstrip("\r\n")
+        if line == "":
+            frame = _flush()
+            if frame is None:
+                continue
+            if frame.data.strip() in done_sentinels and not include_done:
+                return
+            yield frame
+            continue
+        if line.startswith(":"):
+            continue
+
+        if ":" in line:
+            field, value = line.split(":", 1)
+            if value.startswith(" "):
+                value = value[1:]
+        else:
+            field, value = line, ""
+
+        if field == "event":
+            event = value
+        elif field == "data":
+            data_lines.append(value)
+        elif field == "id":
+            event_id = value
+        elif field == "retry":
+            try:
+                retry = int(value)
+            except ValueError:
+                retry = None
+
+    frame = _flush()
+    if frame is not None:
+        if frame.data.strip() in done_sentinels and not include_done:
+            return
+        yield frame
+
+
+def parse_sse_json_frame(frame: SSEFrame, *, stream_name: str) -> Any:
+    """Parse a frame's JSON payload with a deterministic provider error."""
+
+    try:
+        return json.loads(frame.data)
+    except json.JSONDecodeError as exc:
+        event_suffix = f" event={frame.event!r}" if frame.event else ""
+        raise LLMError(f"{stream_name} emitted malformed JSON{event_suffix}: {exc.msg}") from exc

alysis_code/llm/temperature_compat.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import re
+
+ANTHROPIC_DEPRECATED_SAMPLING_PARAMETERS = "anthropic_sampling_parameters_deprecated"
+GEMINI_3_DEFAULT_TEMPERATURE = "gemini_3_default_temperature"
+DEEPSEEK_THINKING_TEMPERATURE_UNSUPPORTED = "deepseek_thinking_temperature_unsupported"
+QWEN_QVQ_DEFAULT_TEMPERATURE = "qwen_qvq_default_temperature"
+KIMI_FIXED_TEMPERATURE = "kimi_fixed_temperature"
+
+_CLAUDE_OPUS_VERSION_RE = re.compile(r"claude[-_.]opus[-_.](?P<major>\d+)(?:[-_.](?P<minor>\d+))?")
+_CLAUDE_SONNET_VERSION_RE = re.compile(
+    r"claude[-_.]sonnet[-_.](?P<major>\d+)(?:[-_.](?P<minor>\d+))?"
+)
+_GEMINI_3_RE = re.compile(r"(?:^|[/.:_-])gemini[-_.]?3(?:[-_.]|$)")
+_DEEPSEEK_V4_RE = re.compile(r"(?:^|[/.:_-])deepseek[-_.]v?4(?:[-_.]|$)")
+_QWEN_QVQ_RE = re.compile(r"(?:^|[/.:_-])qvq(?:[-_.]|$)")
+_CURRENT_KIMI_RE = re.compile(r"(?:^|[/.:_-])kimi[-_.]?k(?:3|2[-_.]?(?:6|7))(?:[-_.]|$)")
+
+
+def documented_temperature_omit_reason(
+    model: str,
+    *,
+    provider_key: str | None = None,
+    thinking_enabled: bool | None = None,
+) -> str | None:
+    """Return the documented reason an optional temperature must be omitted.
+
+    The checks deliberately use model-family patterns rather than a closed list of
+    snapshots so provider aliases, gateway-qualified names, and later compatible
+    releases receive the same safe request shape.
+    """
+
+    normalized_model = str(model or "").strip().casefold()
+    if not normalized_model:
+        return None
+
+    opus = _CLAUDE_OPUS_VERSION_RE.search(normalized_model)
+    if opus is not None:
+        major = int(opus.group("major"))
+        minor_text = opus.group("minor")
+        minor = int(minor_text) if minor_text is not None else None
+        # Pre-4.6 snapshot IDs use a date after the major version (for example
+        # claude-opus-4-20250514). Do not mistake that date for a minor release.
+        if major > 4 or (major == 4 and minor is not None and 7 <= minor < 100):
+            return ANTHROPIC_DEPRECATED_SAMPLING_PARAMETERS
+
+    sonnet = _CLAUDE_SONNET_VERSION_RE.search(normalized_model)
+    if sonnet is not None and int(sonnet.group("major")) >= 5:
+        return ANTHROPIC_DEPRECATED_SAMPLING_PARAMETERS
+
+    if _GEMINI_3_RE.search(normalized_model):
+        return GEMINI_3_DEFAULT_TEMPERATURE
+
+    if _QWEN_QVQ_RE.search(normalized_model):
+        return QWEN_QVQ_DEFAULT_TEMPERATURE
+
+    normalized_provider = str(provider_key or "").strip().casefold()
+    if normalized_provider == "moonshot" and _CURRENT_KIMI_RE.search(normalized_model):
+        return KIMI_FIXED_TEMPERATURE
+    if (
+        normalized_provider == "deepseek"
+        and thinking_enabled is not False
+        and _DEEPSEEK_V4_RE.search(normalized_model)
+    ):
+        return DEEPSEEK_THINKING_TEMPERATURE_UNSUPPORTED
+
+    return None
+
+
+__all__ = [
+    "ANTHROPIC_DEPRECATED_SAMPLING_PARAMETERS",
+    "DEEPSEEK_THINKING_TEMPERATURE_UNSUPPORTED",
+    "GEMINI_3_DEFAULT_TEMPERATURE",
+    "KIMI_FIXED_TEMPERATURE",
+    "QWEN_QVQ_DEFAULT_TEMPERATURE",
+    "documented_temperature_omit_reason",
+]

alysis_code/llm/types.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from enum import StrEnum
+from typing import Any
+
+from ..error_text import sanitize_error_text_for_output
+
+
+class LLMError(RuntimeError):
+    """Provider/model error whose public message is safe to persist and display."""
+
+    def __init__(self, message: object = "") -> None:
+        super().__init__(sanitize_error_text_for_output(message))
+
+
+class LLMStreamNoProgressError(LLMError):
+    """A streaming attempt produced no meaningful provider payload in time."""
+
+
+class UsageConfidence(StrEnum):
+    AUTHORITATIVE = "authoritative"
+    REPORTED = "reported"
+    ESTIMATED = "estimated"
+
+
+class UsageSource(StrEnum):
+    PROVIDER_RESPONSE = "provider_response"
+    PROVIDER_COUNT = "provider_count"
+    LOCAL_ESTIMATE = "local_estimate"
+    MIXED = "mixed"
+
+
+class BillingMode(StrEnum):
+    """How the selected route is paid for from the user's perspective."""
+
+    METERED_API = "metered_api"
+    SUBSCRIPTION = "subscription"
+    INCLUDED = "included"
+    LOCAL = "local"
+    UNKNOWN = "unknown"
+
+
+class CostSource(StrEnum):
+    """Provenance of a per-call dollar amount."""
+
+    PROVIDER_REPORTED = "provider_reported"
+    CATALOG_ESTIMATE = "catalog_estimate"
+    SUBSCRIPTION = "subscription"
+    INCLUDED = "included"
+    LOCAL = "local"
+    UNKNOWN = "unknown"
+
+
+class ReasoningOutputKind(StrEnum):
+    """Visibility class for provider-produced reasoning output.
+
+    ``SUMMARY`` is safe, provider-generated explanatory text intended for
+    display. ``PROVIDER_REASONING`` is a provider-visible reasoning channel
+    that may contain a much more detailed chain and must not be rendered by
+    the default chat trace.
+    """
+
+    SUMMARY = "summary"
+    PROVIDER_REASONING = "provider_reasoning"
+
+
+class AssistantResponsePhase(StrEnum):
+    """Provider-declared lifecycle phase for assistant-visible output."""
+
+    COMMENTARY = "commentary"
+    FINAL_ANSWER = "final_answer"
+
+
+@dataclass(frozen=True)
+class ReasoningOutput:
+    """Normalized reasoning material returned alongside an assistant answer."""
+
+    text: str
+    kind: ReasoningOutputKind
+    provider: str | None = None
+
+
+@dataclass(frozen=True)
+class UsageContract:
+    """Protocol-level guarantees after provider usage has been normalized."""
+
+    response_usage_confidence: UsageConfidence = UsageConfidence.REPORTED
+    normalized_output_includes_reasoning: bool = True
+    input_token_count_strategy: str = "none"
+    billing_mode: BillingMode = BillingMode.METERED_API
+
+    @property
+    def response_usage_authoritative(self) -> bool:
+        return self.response_usage_confidence == UsageConfidence.AUTHORITATIVE
+
+    @property
+    def supports_input_token_count(self) -> bool:
+        return self.input_token_count_strategy != "none"
+
+
+@dataclass(frozen=True)
+class InputTokenCount:
+    input_tokens: int
+    source: UsageSource = UsageSource.PROVIDER_COUNT
+    confidence: UsageConfidence = UsageConfidence.AUTHORITATIVE
+    raw_provider_usage: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.input_tokens, bool)
+            or not isinstance(self.input_tokens, int)
+            or self.input_tokens < 0
+        ):
+            raise ValueError("input token count must be a non-negative integer")
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+    provider_metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class LLMUsage:
+    prompt_tokens: int | None
+    completion_tokens: int | None
+    total_tokens: int | None
+    cached_prompt_tokens: int | None = None
+    input_tokens_uncached: int | None = None
+    # True when the uncached figure was computed from other reported counts
+    # rather than sent by the provider, so display can avoid claiming it as
+    # provider-reported.
+    input_tokens_uncached_derived: bool = False
+    cache_read_input_tokens: int | None = None
+    cache_creation_input_tokens: int | None = None
+    cache_creation_5m_input_tokens: int | None = None
+    cache_creation_1h_input_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    provider_cost_usd: float | None = None
+    provider_cost_currency: str | None = None
+    raw_provider_usage: dict[str, Any] | None = None
+    source: UsageSource = UsageSource.PROVIDER_RESPONSE
+    confidence: UsageConfidence = UsageConfidence.REPORTED
+    output_includes_reasoning: bool = True
+    total_includes_reasoning: bool = True
+
+    def normalized(self) -> LLMUsage:
+        """Return the provider-independent invariant used by accounting.
+
+        After normalization, completion/output and total include reasoning,
+        while ``reasoning_tokens`` remains an informational subset.
+        """
+        reasoning = self.reasoning_tokens
+        if reasoning is None or reasoning <= 0:
+            return replace(
+                self,
+                output_includes_reasoning=True,
+                total_includes_reasoning=True,
+            )
+        completion = self.completion_tokens
+        total = self.total_tokens
+        if completion is not None and not self.output_includes_reasoning:
+            completion += reasoning
+        if total is not None and not self.total_includes_reasoning:
+            total += reasoning
+        return replace(
+            self,
+            completion_tokens=completion,
+            total_tokens=total,
+            output_includes_reasoning=True,
+            total_includes_reasoning=True,
+        )
+
+    @property
+    def cache_read_tokens(self) -> int | None:
+        return (
+            self.cache_read_input_tokens
+            if self.cache_read_input_tokens is not None
+            else self.cached_prompt_tokens
+        )
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    content: str
+    tool_calls: list[ToolCall]
+    raw: dict[str, Any]
+    response_model: str | None = None
+    usage: LLMUsage | None = None
+    provider_metadata: dict[str, Any] | None = None
+    reasoning: tuple[ReasoningOutput, ...] = ()
+    assistant_phase: AssistantResponsePhase | None = None

alysis_code/llm/usage_normalization.py

@@ -0,0 +1,222 @@
+"""Normalize usage payloads shared by OpenAI-compatible provider routes.
+
+Compatibility describes the transport envelope, not the provider's usage
+schema.  This module deliberately decodes documented *shapes* instead of
+maintaining a provider-name switch: gateways and first-party endpoints often
+surface the same cache fields, while a single gateway can return several
+upstream schemas.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Mapping
+from typing import Any
+
+from .types import LLMUsage
+
+
+def _non_negative_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        parsed = int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed is None or parsed >= 0 else None
+
+
+def _non_negative_float(value: Any) -> float | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        parsed = float(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed is None or parsed >= 0 else None
+
+
+def _mapping(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _first_int(*values: Any) -> int | None:
+    for value in values:
+        parsed = _non_negative_int(value)
+        if parsed is not None:
+            return parsed
+    return None
+
+
+def _provider_cost_usd(
+    raw: Mapping[str, Any], *, provider_key: str | None
+) -> tuple[float | None, str | None]:
+    """Return only provider amounts whose unit is explicitly USD-compatible.
+
+    Perplexity-style payloads identify ``total_cost`` and may name the
+    currency. OpenRouter documents its numeric ``usage.cost`` as the charged
+    account-credit amount; OpenRouter credits are USD-denominated. A generic
+    numeric ``cost`` is otherwise ambiguous and is intentionally ignored.
+    """
+
+    cost = raw.get("cost")
+    if isinstance(cost, Mapping):
+        currency = str(cost.get("currency") or "USD").strip().upper()
+        if currency != "USD":
+            return None, currency or None
+        total = _non_negative_float(cost.get("total_cost"))
+        if total is None:
+            total = _non_negative_float(cost.get("total"))
+        return total, "USD" if total is not None else None
+
+    normalized_provider = str(provider_key or "").strip().lower()
+    if normalized_provider == "openrouter":
+        amount = _non_negative_float(cost)
+        if amount is not None:
+            return amount, "USD"
+
+    currency = str(raw.get("currency") or "").strip().upper()
+    if currency in {"", "USD"}:
+        amount = _non_negative_float(raw.get("total_cost"))
+        if amount is not None:
+            return amount, "USD"
+    return None, currency or None
+
+
+def parse_compatible_usage(
+    raw: Any,
+    *,
+    provider_key: str | None = None,
+    responses_shape: bool = False,
+) -> LLMUsage | None:
+    """Decode common provider usage variants without inventing absent values."""
+
+    if not isinstance(raw, Mapping):
+        return None
+
+    prompt_details = _mapping(raw.get("prompt_tokens_details"))
+    input_details = _mapping(raw.get("input_tokens_details"))
+    completion_details = _mapping(raw.get("completion_tokens_details"))
+    output_details = _mapping(raw.get("output_tokens_details"))
+    token_group = _mapping(raw.get("tokens"))
+    billed_units = _mapping(raw.get("billed_units"))
+
+    if responses_shape:
+        prompt = _first_int(
+            raw.get("input_tokens"), raw.get("prompt_tokens"), token_group.get("input_tokens")
+        )
+        completion = _first_int(
+            raw.get("output_tokens"),
+            raw.get("completion_tokens"),
+            token_group.get("output_tokens"),
+        )
+    else:
+        prompt = _first_int(
+            raw.get("prompt_tokens"), raw.get("input_tokens"), token_group.get("input_tokens")
+        )
+        completion = _first_int(
+            raw.get("completion_tokens"),
+            raw.get("output_tokens"),
+            token_group.get("output_tokens"),
+        )
+
+    cache_read = _first_int(
+        prompt_details.get("cached_tokens"),
+        input_details.get("cached_tokens"),
+        prompt_details.get("cache_read_input_tokens"),
+        input_details.get("cache_read_input_tokens"),
+        raw.get("cache_read_input_tokens"),
+        raw.get("cached_prompt_tokens"),
+        raw.get("cached_tokens"),
+        raw.get("prompt_cache_hit_tokens"),
+        raw.get("cached_prompt_text_tokens"),
+    )
+    cache_write = _first_int(
+        prompt_details.get("cache_write_tokens"),
+        input_details.get("cache_write_tokens"),
+        prompt_details.get("cache_creation_input_tokens"),
+        input_details.get("cache_creation_input_tokens"),
+        raw.get("cache_creation_input_tokens"),
+        raw.get("cache_write_tokens"),
+    )
+    cache_creation = _mapping(raw.get("cache_creation"))
+    cache_creation_5m = _first_int(
+        cache_creation.get("ephemeral_5m_input_tokens"),
+        prompt_details.get("cache_creation_5m_input_tokens"),
+        input_details.get("cache_creation_5m_input_tokens"),
+    )
+    cache_creation_1h = _first_int(
+        cache_creation.get("ephemeral_1h_input_tokens"),
+        prompt_details.get("cache_creation_1h_input_tokens"),
+        input_details.get("cache_creation_1h_input_tokens"),
+    )
+    if cache_write is None:
+        write_parts = [
+            value for value in (cache_creation_5m, cache_creation_1h) if value is not None
+        ]
+        if write_parts:
+            cache_write = sum(write_parts)
+
+    cache_miss = _first_int(
+        raw.get("prompt_cache_miss_tokens"),
+        raw.get("input_tokens_uncached"),
+        raw.get("uncached_prompt_tokens"),
+        prompt_details.get("uncached_tokens"),
+        input_details.get("uncached_tokens"),
+    )
+    cache_miss_derived = False
+    if prompt is None and cache_read is not None and cache_miss is not None:
+        prompt = cache_read + cache_miss + (cache_write or 0)
+    if (
+        cache_miss is None
+        and prompt is not None
+        and (cache_read is not None or cache_write is not None)
+    ):
+        # Implied by the counts the provider did send — usable, but not itself
+        # a reported figure.
+        cache_miss = max(0, prompt - (cache_read or 0) - (cache_write or 0))
+        cache_miss_derived = True
+
+    reasoning = _first_int(
+        output_details.get("reasoning_tokens"),
+        completion_details.get("reasoning_tokens"),
+        raw.get("reasoning_tokens"),
+    )
+    total = _first_int(raw.get("total_tokens"))
+    provider_cost_usd, provider_cost_currency = _provider_cost_usd(raw, provider_key=provider_key)
+
+    # Cohere's native schema distinguishes context tokens from billed units.
+    # Preserve the provider's context counts above and retain billed units only
+    # in raw_provider_usage; substituting them would corrupt context accounting.
+    has_billed_units = bool(billed_units)
+    if (
+        prompt is None
+        and completion is None
+        and total is None
+        and cache_read is None
+        and cache_write is None
+        and reasoning is None
+        and provider_cost_usd is None
+        and not has_billed_units
+    ):
+        return None
+
+    return LLMUsage(
+        prompt_tokens=prompt,
+        completion_tokens=completion,
+        total_tokens=total,
+        cached_prompt_tokens=cache_read,
+        input_tokens_uncached=cache_miss,
+        input_tokens_uncached_derived=cache_miss_derived,
+        cache_read_input_tokens=cache_read,
+        cache_creation_input_tokens=cache_write,
+        cache_creation_5m_input_tokens=cache_creation_5m,
+        cache_creation_1h_input_tokens=cache_creation_1h,
+        reasoning_tokens=reasoning,
+        provider_cost_usd=provider_cost_usd,
+        provider_cost_currency=provider_cost_currency,
+        raw_provider_usage=copy.deepcopy(dict(raw)),
+    )
+
+
+__all__ = ["parse_compatible_usage"]