Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

5.4 KB
Raw Blame
"""Round values and provider-message replay shared by scheduler adapters.

These helpers do not execute rounds, invoke tools, or emit stream events.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any

from deeptutor.services.llm import finish_was_truncated as _finish_was_truncated
from deeptutor.services.session.provider_response_state import normalize_provider_response_state


def _reasoning_budget_exhausted(result: "LLMCallResult", max_tokens: int) -> bool:
    """Detect a round that spent its output budget without taking action."""
    if result.tool_calls or result.visible_text.strip():
        return False
    has_reasoning = bool(result.reasoning_chars or result.reasoning_content) or any(
        isinstance(item, dict) and item.get("type") == "reasoning"
        for item in result.response_output_items
    )
    if not has_reasoning:
        return False
    # Content filtering is a terminal provider decision, not a reasoning
    # budget failure. In particular, do not let the token-count fallback below
    # turn a filtered response that happens to reach the cap into a retry loop.
    if str(result.finish_reason or "").strip().lower() == "content_filter":
        return False
    if _finish_was_truncated(result.finish_reason):
        return True
    completion_tokens = result.usage.get("completion_tokens")
    if completion_tokens is None or completion_tokens < max(1, int(max_tokens)):
        return False
    # Some gateways omit the terminal reason and report an incomplete
    # reasoning response with a zero/absent reasoning-token detail.  Once the
    # canonical completion counter reaches this round's request cap, the
    # zero-visible-output shape is enough to identify the exhausted round.
    return True


def _join_answer_parts(parts: list[str], final_text: str) -> str:
    """Build the canonical answer returned by RESULT across continuations."""
    return "".join([*parts, final_text])


@dataclass(slots=True)
class AgentLoopState:
    """Turn-level counters shared across the loop's rounds."""

    rounds: int = 0
    exploration_rounds: int = 0
    settlement_rounds: int = 0
    tool_steps: int = 0
    reasoning_budget_recoveries: int = 0
    sources: list[dict[str, Any]] = field(default_factory=list)


@dataclass(slots=True)
class LLMCallResult:
    text: str
    visible_text: str = ""
    response_output_items: list[dict[str, Any]] = field(default_factory=list)
    reasoning_content: str = ""
    tool_calls: list[dict[str, Any]] = field(default_factory=list)
    # Anthropic's signed thinking blocks, replayed verbatim on the next round.
    thinking_blocks: list[dict[str, Any]] = field(default_factory=list)
    usage: dict[str, int] = field(default_factory=dict)
    output_chars: int = 0
    reasoning_chars: int = 0
    content_chars: int = 0
    tool_call_chars: int = 0
    finish_reason: str = ""
    # Completion metadata describes the round; it never revokes public text.
    # Deferred metadata is reserved for unpublished structured protocol output.
    completion_metadata: dict[str, Any] | None = None
    deferred_chunk_metadata: dict[str, Any] | None = None
    deferred_completion_metadata: dict[str, Any] | None = None


@dataclass(slots=True)
class LoopOutcome:
    """Result of running the turn's loop.

    ``final_text`` is the user-facing answer (the finish round's text, or a
    terminator tool's content). ``completed`` is False only when the turn
    halted on an unresolved ``ask_user`` pause — the pending question is then
    the turn's final artefact.
    """

    final_text: str = ""
    completed: bool = False
    provider_response_state: dict[str, Any] | None = None


def _provider_response_state(
    response_output_items: list[dict[str, Any]],
    reasoning_content: str,
    thinking_blocks: list[dict[str, Any]] | None = None,
) -> dict[str, Any] | None:
    state: dict[str, Any] = {}
    if response_output_items:
        state["responses_output_items"] = response_output_items
    if reasoning_content:
        state["reasoning_content"] = reasoning_content
    if thinking_blocks:
        state["thinking_blocks"] = thinking_blocks
    return normalize_provider_response_state(state)


def _assistant_round_message(result: LLMCallResult) -> dict[str, Any]:
    message: dict[str, Any] = {"role": "assistant", "content": result.text}
    state = _provider_response_state(
        result.response_output_items,
        result.reasoning_content,
        result.thinking_blocks,
    )
    if state is not None:
        message["_provider_response_state"] = state
    if result.thinking_blocks:
        # Replayed on the message itself as well as in the private state: the
        # provider reads this field directly when the round is still in this
        # turn's working set, and rebuilds it from the state for history.
        message["thinking_blocks"] = result.thinking_blocks
    if result.reasoning_content:
        # Some chat-completions reasoning models require this field on the
        # immediately following round. Historical turns rebuild it from the
        # private provider state instead.
        message["reasoning_content"] = result.reasoning_content
    return message


def _has_replayable_assistant_state(result: LLMCallResult) -> bool:
    """Whether a tool-less round still has provider state to replay."""
    return bool(
        result.text
        or result.reasoning_content
        or result.response_output_items
        or result.thinking_blocks
    )