everalgo-core 0.1.0__py3-none-any.whl

everalgo/_tokenize.py

@@ -0,0 +1,45 @@
+"""Shared tokenizer utilities using OpenAI ``o200k_base`` encoding (GPT-4o / o-series).
+
+Module-private — internal shared implementation; not part of the public ``everalgo.*`` API.
+"""
+
+from __future__ import annotations
+
+import tiktoken
+
+_ENCODING_NAME = "o200k_base"
+_tokenizer_cache: tiktoken.Encoding | None = None
+
+
+def _get_tokenizer() -> tiktoken.Encoding:
+    """Return the shared ``o200k_base`` encoding, initialising on first call."""
+    global _tokenizer_cache
+    if _tokenizer_cache is None:
+        _tokenizer_cache = tiktoken.get_encoding(_ENCODING_NAME)
+    return _tokenizer_cache
+
+
+def count_tokens(text: str) -> int:
+    """Count tokens in ``text`` under ``o200k_base``. Empty string returns 0."""
+    if not text:
+        return 0
+    return len(_get_tokenizer().encode(text))
+
+
+def force_split(text: str, *, max_tokens: int) -> list[str]:
+    """Split ``text`` into chunks of at most ``max_tokens`` tokens (no semantic awareness).
+
+    Returns ``[]`` for empty input, ``[text]`` when the whole string already fits.
+
+    Raises:
+        ValueError: If ``max_tokens <= 0``.
+    """
+    if max_tokens <= 0:
+        raise ValueError(f"max_tokens must be positive, got {max_tokens}")
+    if not text:
+        return []
+    tokenizer = _get_tokenizer()
+    token_ids = tokenizer.encode(text)
+    if len(token_ids) <= max_tokens:
+        return [text]
+    return [tokenizer.decode(token_ids[i : i + max_tokens]) for i in range(0, len(token_ids), max_tokens)]

everalgo/config.py

@@ -0,0 +1,4 @@
+"""Global configuration for the EverAlgo algorithm library.
+
+See ``AGENTS.md`` §5 (Code Style) for the LLM injection contract.
+"""

everalgo/llm/__init__.py

@@ -0,0 +1,64 @@
+"""LLM facade — chat-style abstraction over OpenAI-compatible providers.
+
+Public surface, grouped by role:
+
+- protocol:    LLMClient
+- data:        ChatMessage, ChatResponse, ContentPart, ImageUrlInner, ImageUrlPart, TextPart, Usage, LLMConfig
+- helpers:     image_url_part_from_bytes
+- errors:      LLMError
+- factory:     build_client
+- format/parse: Lang, format_message_timestamp, format_natural_language_time, parse_llm_json_object
+
+LLM binding is instance-only: every operator accepts ``llm: LLMClient`` at construction time.
+There is no global default, no scoped context-var override, and no per-call resolution layer.
+This matches the industry convention used by openai-python, anthropic-sdk-python, LangChain,
+Instructor, and scikit-learn (5/7 dominant SDKs bind the client at construction time only).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from everalgo.llm._filters import SensitiveHeadersFilter
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.errors import LLMError
+from everalgo.llm.factory import build_client
+from everalgo.llm.format import Lang, format_message_timestamp, format_natural_language_time
+from everalgo.llm.parse import parse_llm_json_object
+from everalgo.llm.protocols import LLMClient
+from everalgo.llm.types import (
+    ChatMessage,
+    ChatResponse,
+    ContentPart,
+    ImageUrlInner,
+    ImageUrlPart,
+    TextPart,
+    Usage,
+    image_url_part_from_bytes,
+)
+
+# Library logging setup (ADR-013). NullHandler suppresses "No handlers" noise
+# under Python's library-logging contract; SensitiveHeadersFilter redacts
+# authorization-style values from `record.args` mappings, default-on.
+_logger = logging.getLogger(__name__)
+_logger.addHandler(logging.NullHandler())
+_logger.addFilter(SensitiveHeadersFilter())
+
+__all__ = [
+    "ChatMessage",
+    "ChatResponse",
+    "ContentPart",
+    "ImageUrlInner",
+    "ImageUrlPart",
+    "LLMClient",
+    "LLMConfig",
+    "LLMError",
+    "Lang",
+    "TextPart",
+    "Usage",
+    "build_client",
+    "format_message_timestamp",
+    "format_natural_language_time",
+    "image_url_part_from_bytes",
+    "parse_llm_json_object",
+]  # fmt: skip

everalgo/llm/_filters.py

@@ -0,0 +1,39 @@
+"""Logging filters for ``everalgo.llm`` — redacts sensitive header values."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Final
+
+__all__ = ["SensitiveHeadersFilter"]
+
+
+_REDACTED: Final[str] = "<redacted>"
+
+# Matches header / parameter names that conventionally carry credentials.
+# Case-insensitive; covers Authorization, Api-Key / api_key, X-Api-Key,
+# Bearer tokens. Keep narrow — false positives leak data; false negatives
+# leak credentials.
+_SENSITIVE_KEY_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"(authorization|api[-_]?key|x-api-key|bearer)",
+    re.IGNORECASE,
+)
+
+
+class SensitiveHeadersFilter(logging.Filter):
+    """Redact sensitive header values in ``LogRecord.args`` mappings.
+
+    Default-attached to ``everalgo.llm``; ``filter()`` always returns ``True`` — it mutates payload, never
+    drops records. Only mapping-shaped ``record.args`` are scanned; tuple / ``None`` args pass through.
+    Does not scan request/response bodies (body PII is out of scope for a header filter).
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Redact sensitive entries from ``record.args`` in place; always returns ``True``."""
+        if isinstance(record.args, dict):
+            record.args = {
+                key: (_REDACTED if _SENSITIVE_KEY_PATTERN.search(str(key)) else value)
+                for key, value in record.args.items()
+            }
+        return True

everalgo/llm/config.py

@@ -0,0 +1,21 @@
+"""LLM client configuration."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr
+
+
+class LLMConfig(BaseModel):
+    """OpenAI-compatible LLM client configuration.
+
+    ``api_key`` uses ``SecretStr`` so repr / serialization never leaks the raw key; call
+    ``config.api_key.get_secret_value()`` explicitly when passing it to an SDK.
+    """
+
+    model: str
+    api_key: SecretStr
+    base_url: str
+    temperature: float = 0.0
+    max_tokens: int | None = None
+    timeout: float = 60.0
+    extra: dict[str, Any] = Field(default_factory=dict)

everalgo/llm/errors.py

@@ -0,0 +1,5 @@
+"""LLM-layer error types — minimal single-base set."""
+
+
+class LLMError(Exception):
+    """Raised on any LLM call failure. Inspect ``__cause__`` (PEP 3134) for the original SDK exception."""

everalgo/llm/factory.py

@@ -0,0 +1,15 @@
+"""Factory for building an LLM client from configuration."""
+
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.protocols import LLMClient
+
+
+def build_client(config: LLMConfig) -> LLMClient:
+    """Build an OpenAI-compatible LLM client.
+
+    ``OpenAICompatClient`` is imported lazily so that ``import everalgo.llm`` remains cheap for callers
+    that only need the Protocol / Config / Error types. Do not hoist this to a top-level import.
+    """
+    from everalgo.llm.providers.openai_compat import OpenAICompatClient
+
+    return OpenAICompatClient(config)

everalgo/llm/format.py

@@ -0,0 +1,43 @@
+"""Time-formatting helpers for LLM prompt rendering.
+
+Two flavours:
+- ``format_message_timestamp`` — ISO 8601 UTC anchor for inline conversation-line
+  prefixes (e.g. ``[2023-11-14T22:13:20Z] Alice: ...``). Language-agnostic.
+- ``format_natural_language_time`` — human-readable label for LLM time-of-day
+  reasoning (e.g. ``Conversation start time:`` / ``TIME:``). Supports EN + ZH;
+  callers pick via ``lang`` (default ``"en"`` matches the current EverAlgo
+  default-EN prompt policy).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+__all__ = ["Lang", "format_message_timestamp", "format_natural_language_time"]
+
+Lang = Literal["en", "zh"]
+
+
+def format_message_timestamp(timestamp_ms: int) -> str:
+    """ISO 8601 UTC for conversation-line prefixes (e.g. ``2023-11-14T22:13:20Z``).
+
+    Language-agnostic. Used wherever an LLM prompt needs a machine-readable
+    time anchor in front of a message body.
+    """
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def format_natural_language_time(timestamp_ms: int, *, lang: Lang = "en") -> str:
+    """Human-readable timestamp for LLM time-of-day reasoning labels.
+
+    EN: ``November 14, 2023 (Tuesday) at 10:13 PM UTC``
+    ZH: ``2023 年 11 月 14 日 (星期二) 下午 10:13 UTC`` (uses CJK parentheses in the actual output)
+    """
+    dt = datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC)
+    if lang == "zh":
+        weekday = ["星期一", "星期二", "星期三", "星期四", "星期五", "星期六", "星期日"][dt.weekday()]
+        hour_12 = dt.hour % 12 or 12
+        ampm = "下午" if dt.hour >= 12 else "上午"
+        return f"{dt.year} 年 {dt.month} 月 {dt.day} 日（{weekday}）{ampm} {hour_12}:{dt.minute:02d} UTC"  # noqa: RUF001
+    return dt.strftime("%B %-d, %Y (%A) at %-I:%M %p UTC")

everalgo/llm/parse.py

@@ -0,0 +1,61 @@
+"""Robust LLM JSON-object parsing.
+
+Used wherever an LLM returns a string that should decode to a JSON object. Handles the common
+LLM output quirks (markdown fence wrapping, prose preamble around the JSON, etc.) on top of
+OpenAI JSON mode's happy path.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, cast
+
+__all__ = ["parse_llm_json_object"]
+
+
+def parse_llm_json_object(raw: str) -> dict[str, Any]:
+    """Parse ``raw`` as a JSON object via three strategies in order.
+
+    Tries each strategy until one succeeds:
+
+    1. `` ```json ... ``` `` fenced block
+    2. Direct ``json.loads`` on the full string (the JSON-mode happy path)
+    3. Outermost ``{ ... }`` substring (rescues prose-wrapped JSON)
+
+    Args:
+        raw: Raw string returned by the LLM.
+
+    Returns:
+        The parsed dict.
+
+    Raises:
+        ValueError: If all three strategies fail or the result is not a JSON object.
+    """
+    fence_match = re.search(r"```json\s*(.*?)\s*```", raw, re.DOTALL)
+    if fence_match:
+        try:
+            parsed = json.loads(fence_match.group(1))
+            if isinstance(parsed, dict):
+                return cast("dict[str, Any]", parsed)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    try:
+        parsed = json.loads(raw.strip())
+        if isinstance(parsed, dict):
+            return cast("dict[str, Any]", parsed)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    start = raw.find("{")
+    end = raw.rfind("}")
+    if start != -1 and end > start:
+        try:
+            parsed = json.loads(raw[start : end + 1])
+            if isinstance(parsed, dict):
+                return cast("dict[str, Any]", parsed)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+    raise ValueError("Failed to parse LLM response as a JSON object")

everalgo/llm/protocols.py

@@ -0,0 +1,28 @@
+"""LLM client Protocol — the structural contract every provider satisfies."""
+
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+from everalgo.llm.types import ChatMessage, ChatResponse
+
+
+@runtime_checkable
+class LLMClient(Protocol):
+    """Async LLM client structural contract (PEP 544). Structural conformance suffices — no subclassing needed."""
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        *,
+        model: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        response_format: Mapping[str, Any] | None = None,
+        **extra: Any,
+    ) -> ChatResponse:
+        """Send a chat request and return the structured response.
+
+        Raises:
+            LLMError: On any provider-side failure; original SDK exception attached as ``__cause__``.
+        """
+        ...

everalgo/llm/providers/__init__.py

@@ -0,0 +1,7 @@
+"""Concrete LLM provider adapters (openai_compat / anthropic / bedrock / vllm).
+
+Providers live *inside* the ``llm`` package — not as a top-level distribution —
+to mirror litellm / instructor / dspy / llama-index conventions.
+"""
+
+__all__: list[str] = []

everalgo/llm/providers/openai_compat.py

@@ -0,0 +1,91 @@
+"""OpenAI-compatible provider — wraps openai.AsyncOpenAI."""
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import openai
+
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.errors import LLMError
+from everalgo.llm.types import ChatMessage, ChatResponse, Usage
+
+
+class OpenAICompatClient:
+    """Thin async wrapper over ``openai.AsyncOpenAI``.
+
+    Converts between EverAlgo types and the openai SDK shapes. No retry, rate-limit, or key-rotation logic —
+    those are caller concerns.
+    """
+
+    def __init__(self, config: LLMConfig) -> None:
+        self._config = config
+        self._client = openai.AsyncOpenAI(
+            api_key=config.api_key.get_secret_value(),
+            base_url=config.base_url,
+            timeout=config.timeout,
+        )
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        *,
+        model: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        response_format: Mapping[str, Any] | None = None,
+        **extra: Any,
+    ) -> ChatResponse:
+        """Implement ``LLMClient.chat`` — see protocols.py for contract."""
+        request_kwargs: dict[str, Any] = {
+            "model": model or self._config.model,
+            "messages": [m.model_dump() for m in messages],
+            "temperature": (temperature if temperature is not None else self._config.temperature),
+        }
+        max_tokens_val = max_tokens if max_tokens is not None else self._config.max_tokens
+        if max_tokens_val is not None:
+            request_kwargs["max_tokens"] = max_tokens_val
+        if response_format is not None:
+            request_kwargs["response_format"] = dict(response_format)
+        request_kwargs.update(self._config.extra)
+        request_kwargs.update(extra)
+
+        try:
+            completion = await self._client.chat.completions.create(**request_kwargs)
+        except openai.OpenAIError as exc:
+            raise LLMError(str(exc)) from exc
+
+        # Some OpenAI-compatible upstreams (notably OpenRouter when the upstream
+        # model rejects the payload) return a 200 with ``choices=None`` or an
+        # empty list rather than a structured HTTP error. Surface as LLMError
+        # rather than crashing with ``NoneType`` subscript.
+        if not completion.choices:
+            raise LLMError(
+                f"upstream returned no choices (model={completion.model!r}); "
+                f"likely an upstream rejection or content filter"
+            )
+        choice = completion.choices[0]
+        usage: Usage | None = None
+        if completion.usage is not None:
+            usage = Usage(
+                prompt_tokens=completion.usage.prompt_tokens,
+                completion_tokens=completion.usage.completion_tokens,
+            )
+
+        finish_reason = _normalise_finish_reason(choice.finish_reason)
+
+        return ChatResponse(
+            content=choice.message.content or "",
+            model=completion.model,
+            usage=usage,
+            finish_reason=finish_reason,
+            raw=None,
+        )
+
+
+def _normalise_finish_reason(
+    value: str | None,
+) -> Literal["stop", "length", "content_filter"] | None:
+    """Collapse provider finish reasons to EverAlgo's 3-value Literal; unknown values map to ``None``."""
+    if value in ("stop", "length", "content_filter"):
+        return value  # type: ignore[return-value]
+    return None

everalgo/llm/types.py

@@ -0,0 +1,117 @@
+"""LLM wire types — chat-style messages, response, token usage.
+
+These are the on-the-wire data contracts a caller sees when invoking ``LLMClient.chat``. They mirror the
+OpenAI Chat Completions API closely so the openai_compat provider can pass through values with minimal
+translation.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TextPart(BaseModel):
+    """Text segment inside a multimodal ``content`` array.
+
+    Serialises to ``{"type": "text", "text": "..."}`` — the OpenAI / OpenRouter wire form.
+    """
+
+    type: Literal["text"] = "text"
+    text: str
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class ImageUrlInner(BaseModel):
+    """Inner object of an ``image_url`` content part."""
+
+    url: str
+    detail: Literal["low", "high", "auto"] | None = None
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class ImageUrlPart(BaseModel):
+    """File-by-data-URI content part.
+
+    Serialises to ``{"type": "image_url", "image_url": {"url": "...", "detail": ...}}``. Named "image_url" for
+    OpenAI / OpenRouter wire compatibility, but the data URI may carry any MIME the upstream model accepts
+    (``application/pdf``, ``audio/wav``, ``image/png`` ...); OpenRouter + Gemini routes all of them through
+    this single part type.
+    """
+
+    type: Literal["image_url"] = "image_url"
+    image_url: ImageUrlInner
+
+    model_config = ConfigDict(extra="ignore")
+
+
+ContentPart = Annotated[TextPart | ImageUrlPart, Field(discriminator="type")]
+"""Discriminated union of content parts. Add new arms as providers gain native types."""
+
+
+def image_url_part_from_bytes(data: bytes, mime: str) -> ImageUrlPart:
+    """Build an ``ImageUrlPart`` from raw bytes by base64-encoding into a data URI.
+
+    Parameters
+    ----------
+    data : bytes
+        Raw file payload (image / pdf / audio bytes).
+    mime : str
+        MIME type, e.g. ``image/png`` / ``application/pdf`` / ``audio/wav``.
+    """
+    b64 = base64.b64encode(data).decode("ascii")
+    return ImageUrlPart(image_url=ImageUrlInner(url=f"data:{mime};base64,{b64}"))
+
+
+class ChatMessage(BaseModel):
+    """Single chat-style message turn.
+
+    ``content`` accepts either a plain ``str`` (text-only turn, the common case) or a ``list[ContentPart]``
+    for multimodal turns (text + image / pdf / audio data URIs). When serialised the OpenAI / OpenRouter wire
+    form falls out automatically:
+
+    - ``{"role": "user", "content": "hi"}`` — text
+    - ``{"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image_url", "image_url": {"url": "data:..."}}]}`` — multimodal
+
+    The ``role`` set is intentionally narrow (3 values). ``tool`` is out of EPISODE scope; adding it later is
+    a SemVer minor bump (extending a Literal is a backward-compatible structural widening).
+    """
+
+    role: Literal["system", "user", "assistant"]
+    content: str | list[ContentPart]
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class Usage(BaseModel):
+    """Token usage from a single LLM call.
+
+    Both fields are ``int | None`` because some self-hosted / OpenAI-compatible backends do not return
+    ``usage`` in the response. ``None`` semantically distinguishes "missing data" from "zero tokens used".
+    """
+
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+
+
+class ChatResponse(BaseModel):
+    """Structured response from a single LLM chat call."""
+
+    content: str
+    model: str
+    usage: Usage | None = None
+    finish_reason: Literal["stop", "length", "content_filter"] | None = None
+    raw: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Provider-specific original response payload. Populated only when "
+            "the provider implementation explicitly opts in (e.g. debug mode). "
+            "Production callers should rely on the structured "
+            "``content`` / ``usage`` / ``finish_reason`` fields and not "
+            "depend on ``raw`` being non-None."
+        ),
+    )

everalgo/prompts/__init__.py

@@ -0,0 +1,15 @@
+"""Prompt utilities shared across the library.
+
+Per AGENTS.md §5 (Code Style): concrete prompt strings live next to their algorithm in each subpackage at
+``<subpkg>/prompts/{en,zh}/<name>.py`` as module-level constants — not in this directory. This package only
+ships the cross-cutting helpers (rendering, validation) every operator reuses.
+"""
+
+import logging
+
+from everalgo.prompts.render import render_prompt
+
+__all__ = ["render_prompt"]
+
+# Library logging setup (ADR-013): NullHandler on each subpackage logger.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

everalgo/prompts/render.py

@@ -0,0 +1,40 @@
+"""Render a prompt template with caller-provided fields, falling back to a default.
+
+Uses ``str.replace`` to substitute ``{key}`` placeholders so the template body can contain
+literal ``{`` / ``}`` (e.g. JSON examples) without escaping.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def render_prompt(default: str, prompt: str | None, /, **fields: Any) -> str:
+    """Render ``prompt`` with ``fields``; if ``prompt`` is None, use ``default``.
+
+    Substitutes each ``{key}`` placeholder in the template with ``str(value)``. Template bodies
+    may freely contain literal braces (e.g. JSON examples) — only the exact ``{key}`` substring
+    is replaced.
+
+    Args:
+        default: Module-level prompt constant shipped with the operator.
+        prompt: Caller override; if ``None``, falls back to ``default``.
+        **fields: Each key=value renders ``{key}`` → ``str(value)``. Missing placeholders are left
+            in the output verbatim (no KeyError) so a typo'd template degrades gracefully rather
+            than crashing the LLM call.
+
+    Returns:
+        Rendered prompt string.
+
+    Examples:
+        >>> render_prompt("Hello, {name}!", None, name="world")
+        'Hello, world!'
+        >>> render_prompt("Hello, {name}!", "Hi {name}", name="world")
+        'Hi world'
+        >>> render_prompt('Output JSON like {"key": "value"} for {name}', None, name="Alice")
+        'Output JSON like {"key": "value"} for Alice'
+    """
+    template = prompt or default
+    for key, value in fields.items():
+        template = template.replace("{" + key + "}", str(value))
+    return template

everalgo/prompts/validator.py

@@ -0,0 +1,62 @@
+"""Prompt validators — fail-fast checks for prompt templates.
+
+Designed to be called at module import time after a prompt constant is defined, so that template typos are
+caught before any LLM call.
+"""
+
+import string
+from collections.abc import Callable, Iterable
+
+
+def check_placeholders(prompt: str, *, required: Iterable[str]) -> None:
+    """Assert that ``prompt`` contains every placeholder in ``required``; attribute/index access collapses to root.
+
+    Raises:
+        ValueError: If any required placeholder is missing; error message also lists any extra placeholders.
+    """
+    found: set[str] = set()
+    for _, field_name, _, _ in string.Formatter().parse(prompt):
+        if not field_name:
+            continue
+        # Reduce ``user.name`` / ``items[0]`` to root identifier.
+        root = field_name.split(".", 1)[0].split("[", 1)[0]
+        if root:
+            found.add(root)
+
+    required_set = set(required)
+    missing = required_set - found
+    if not missing:
+        return
+
+    extras = found - required_set
+    msg = f"Missing required placeholders: {sorted(missing)}"
+    if extras:
+        msg += f" (extra placeholders present: {sorted(extras)})"
+    raise ValueError(msg)
+
+
+def _default_token_estimator(text: str) -> int:
+    """Return a coarse over-estimate (~4 chars/token); intentionally conservative so CJK text never slips through."""
+    return max(1, len(text) // 4 + 1)
+
+
+def check_length(
+    prompt: str,
+    *,
+    max_tokens: int,
+    tokenizer: Callable[[str], int] | None = None,
+) -> None:
+    """Assert that ``prompt`` is at most ``max_tokens`` tokens long.
+
+    Args:
+        prompt: Rendered prompt (post-format).
+        max_tokens: Hard ceiling — typically context window minus response reserve.
+        tokenizer: Token counter; ``None`` falls back to the conservative character-based heuristic.
+
+    Raises:
+        ValueError: If the token count exceeds ``max_tokens``.
+    """
+    counter = tokenizer if tokenizer is not None else _default_token_estimator
+    actual = counter(prompt)
+    if actual > max_tokens:
+        raise ValueError(f"Prompt length {actual} tokens exceeds max_tokens={max_tokens}")