Arena¶

@model_validator(mode="after")
def validate_question_or_attachments(self):
    """Ensure the turn carries text, at least one image, or a document.

    Image-only asks are valid vision-model turns (mirrors conversations,
    #136 C) and a document-only ask is a valid "what does this say?" turn
    (#492); a fully empty ask is still rejected.

    Returns:
        The payload with a trimmed question.

    Raises:
        ValueError: If question is empty/whitespace and nothing is attached.
    """
    self.question = self.question.strip()
    if not self.question and not self.images and not self.attachments:
        raise ValueError("Question cannot be empty or whitespace")
    return self

async def query_llm_stream(
    self,
    llm_id: int,
    payload: ArenaQueryPayload,
) -> AsyncGenerator[str, None]:
    """Query an LLM in stateless arena mode and stream response tokens (raw text).

    Raises:
        InvalidInputException: empty question.
        ModelNotFoundException: ``llm_id`` not found (via ``_get_llm``; the
            endpoint also validates eagerly before opening the stream).
        KnowledgeBase*Exception: KB retrieval failure.

    Generation/model-load failures are NOT raised here — the runner yields the
    ``[ERROR_MESSAGE_SYSTEM]`` sentinel inline (unified with conversation).
    """
    if not payload.question.strip() and not payload.images and not payload.attachments:
        raise InvalidInputException("question")

    start_s = time.perf_counter()
    # Local-first policy: log the question content (bounded), never image
    # bytes — only their count and encoded size (mirrors conversations).
    image_note = ""
    if payload.images:
        total_b64_chars = sum(len(url) for url in payload.images)
        image_note = f", images={len(payload.images)} ({total_b64_chars} base64 chars)"
    if payload.attachments:
        image_note += f", attachments={len(payload.attachments)}"
    logger.info(
        f"Arena query started for LLM {llm_id}{image_note}: "
        f"{truncate_for_log(payload.question, 2000)}"
    )
    llm = self._get_llm(llm_id)

    param_size = llm.param_size if getattr(llm, "param_size", None) else 2
    strategy = get_prompting_strategy(param_size)

    # Derive the turn's mode (plain / systematic-KB / agentic-KB) from the
    # model's tool-calling capability (#84). Retrieval is injected so it runs
    # only in systematic mode and keeps arena's raise-on-failure policy.
    # #310: arena panels have no conversation row, so the web toggle follows
    # the GLOBAL user setting directly (kept deliberately simple).
    settings_repo = User_Settings_Repository(self.db)
    web_search_enabled = await run_in_threadpool(settings_repo.get_web_search_enabled)
    # 1.1.2: same reasoning -- an arena panel has no conversation row, so
    # its reasoning effort is the GLOBAL default, read per turn.
    effort_level = await run_in_threadpool(settings_repo.get_default_reasoning_effort)
    effort_plan = await run_in_threadpool(plan_reasoning_effort, llm, effort_level)
    plan = await run_in_threadpool(
        plan_turn,
        llm,
        question=payload.question,
        retrieve=lambda: self._retrieve_kb_excerpts(llm, payload.question, strategy),
        custom_prompt=payload.custom_prompt,
        web_search_enabled=web_search_enabled,
        effort_section=effort_plan.prompt_section,
    )

    # Omitted values resolve to the MODEL's defaults (#388); explicit wins.
    defaults = resolve_sampling_defaults(llm)
    params = GenParams(
        temperature=defaults.temperature
        if payload.temperature is None
        else payload.temperature,
        top_p=defaults.top_p if payload.top_p is None else payload.top_p,
        # Only the FALLBACK output budget (same contract as a conversation):
        # the per-call budget computed from the running window
        # (``src.agents.output_budget``) overrides it whenever the engine
        # reports one, and this value is what an engine that reports none
        # runs with. ``payload.max_new_tokens`` is deliberately not read --
        # the arena panel no longer offers the control, and the field stays
        # accepted only so an older client is not rejected.
        max_tokens=defaults.max_tokens,
    )

    # Safety net (#133/#212): unless the model is positively vision-capable,
    # the runner strips images before inference — tell the user up front
    # instead of silently dropping the attachment.
    supports_vision = await run_in_threadpool(detect_supports_vision, llm.link)

    # Documents attached to this question (#492): the same resolver the
    # conversation uses, so both paths read files exactly once, the same way.
    attachments = await run_in_threadpool(resolve_attachments, payload.attachments)

    response = ""
    if payload.images and supports_vision is not True:
        response += IMAGES_IGNORED_NOTICE
        yield IMAGES_IGNORED_NOTICE
    attachment_notice = build_attachment_notice(attachments)
    if attachment_notice:
        response += attachment_notice
        yield attachment_notice
    # ``aclosing``: whenever THIS generator is closed, the runner is closed
    # with it, inside the guard. Starlette never closes a body iterator
    # itself: a disconnect noticed while ``send()`` is in progress leaves
    # this generator suspended at its yield, and closing it then still
    # depends on its finalization.
    async with contextlib.aclosing(
        self.runner.astream_text(
            llm=llm,
            user_message=self._build_user_message(
                prepend_attachment_block(attachments.block, payload.question), payload.images
            ),
            system_prompt=plan.system_prompt,
            params=params,
            thread_id=None,
            summarize=False,
            kb_context_block=plan.kb_context_block,
            kb_language_line=plan.kb_language_line,
            tools=plan.tools,
            context=plan.context,
            supports_vision=supports_vision,
            effort_plan=effort_plan,
        )
    ) as tokens:
        async for token in tokens:
            response += token
            yield token

    duration_ms = (time.perf_counter() - start_s) * 1000
    logger.info(
        f"Arena query completed for LLM {llm_id} "
        f"(model={getattr(llm, 'name', '?')}): duration_ms={duration_ms:.0f}, "
        f"response_chars={len(response)}, "
        f"preview={truncate_for_log(response, 500)}"
    )