keystone-agent-tools 0.1.5__py3-none-any.whl

keystone/agent_tools/__init__.py

@@ -0,0 +1,18 @@
+"""The tools a platform agent uses on files, shared by visual-builder and master-agent (FDP-6967).
+
+* :mod:`keystone.agent_tools.files` — the file-artifact client (create / render as background
+  jobs, FDP-7030) and the file tools the model calls (``read_artifact``, ``search_in_artifact``,
+  ``search_across_thread``, ``create_artifact``, ``render_artifact``, ``edit_artifact`` and the
+  ``list`` / ``get_metadata`` / ``publish`` tools they refer to). The names, arguments and the
+  words the model reads are written ONCE, here.
+* :mod:`keystone.agent_tools.kb` — the extended knowledge-base toolset (FR-180, FDP-7133): the six
+  ``kb_*`` tools, their descriptions and the Knowledge Bases block of the system prompt, with rag's
+  agent guide (and default metadata filter) of each KB. visual-builder and pro-code use it as is.
+* :mod:`keystone.agent_tools.attachments` — how the files attached to a turn become content
+  blocks for the model: one token budget per turn, pictures downscaled to the provider limit,
+  what could not be sent noted for the model.
+
+What a service still owns: who the call acts as (its headers), which turn a file belongs to, how
+a file card reaches its chat, and the shape of a tool result in its graph state. A service plugs
+those in through :class:`keystone.agent_tools.files.FileToolHost`.
+"""

keystone/agent_tools/attachments/__init__.py

@@ -0,0 +1,61 @@
+"""How a turn's attachments reach the model (FDP-6967, item 2) — one set of rules for every agent.
+
+    from keystone.agent_tools.attachments import AttachedFile, TurnPictures, document_blocks, image_blocks
+
+See :mod:`keystone.agent_tools.attachments.blocks` for the rules, :mod:`.budget` for the turn budget
+and :mod:`.images` for fitting a picture to the provider's limit.
+"""
+
+from keystone.agent_tools.attachments.audio import AUDIO_HEARD_NOTE, audio_blocks, transcript_blocks
+from keystone.agent_tools.attachments.blocks import (
+    IMAGE_MIMES,
+    AttachedFile,
+    AttachmentLimits,
+    FileBlocks,
+    TurnPictures,
+    aggregate_refused_note,
+    attached_marker,
+    document_blocks,
+    fmt_size,
+    image_blocks,
+    is_document,
+    is_image,
+    named,
+    text_cap_chars,
+)
+from keystone.agent_tools.attachments.budget import (
+    MIN_FLOOR_TOKENS_PER_FILE,
+    STATIC_TURN_ATTACHMENT_BUDGET,
+    cap_bytes_for_share,
+    compute_share_per_file,
+    refuses_content,
+)
+from keystone.agent_tools.attachments.images import DecodeRefused, fit_image, fit_image_async
+
+__all__ = [
+    "AUDIO_HEARD_NOTE",
+    "audio_blocks",
+    "transcript_blocks",
+    "IMAGE_MIMES",
+    "MIN_FLOOR_TOKENS_PER_FILE",
+    "STATIC_TURN_ATTACHMENT_BUDGET",
+    "AttachedFile",
+    "AttachmentLimits",
+    "DecodeRefused",
+    "FileBlocks",
+    "TurnPictures",
+    "aggregate_refused_note",
+    "attached_marker",
+    "cap_bytes_for_share",
+    "compute_share_per_file",
+    "document_blocks",
+    "fit_image",
+    "fit_image_async",
+    "fmt_size",
+    "image_blocks",
+    "is_document",
+    "is_image",
+    "named",
+    "refuses_content",
+    "text_cap_chars",
+]

keystone/agent_tools/attachments/audio.py

@@ -0,0 +1,104 @@
+"""An audio clip attached to a turn, as blocks: its transcript, or why it could not be heard (FDP-6967).
+
+The words are visual-builder's (``services/agent_version/attachments.py``), which master-agent had
+copied; now one copy. :func:`audio_blocks` calls the shared speech-to-text client
+(:mod:`keystone.agent_tools.transcription`) — a host passes its identity headers, the agent's STT
+model, and how to reach the clip (bytes, a spool, or a presigned URL for a long one).
+"""
+
+# Feature: FR-130 | Tracking: FDP-3032, FDP-6967
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from keystone.agent_tools.attachments.blocks import AttachedFile, AttachmentLimits, FileBlocks, text_cap_chars
+from keystone.agent_tools.transcription import Transcript, TranscriptionFailed
+
+__all__ = ["AUDIO_HEARD_NOTE", "audio_blocks", "transcript_blocks"]
+
+_logger = logging.getLogger("keystone.agent_tools.attachments")
+
+#: Once per turn that carries a heard clip: without it models answered "I can't listen to audio, but
+#: I can read the transcript you attached" — the block read to them as a transcript the USER pasted.
+AUDIO_HEARD_NOTE = (
+    "[system-note: the audio above is what the user said, heard through speech-to-text. "
+    "Answer from what was said; do not say you cannot listen to audio.]"
+)
+
+
+def transcript_blocks(name: str | None, result: Transcript | str, *, cap_chars: int) -> list[dict[str, Any]]:
+    """What the model reads for one clip: its transcript, or (``result`` a str) why it was not heard."""
+    label = name or "audio"
+    if isinstance(result, str):
+        return [
+            {
+                "type": "text",
+                "text": (
+                    f"[system-note: the user attached the audio file {label}, but it could not be "
+                    f"transcribed ({result}). Tell the user you could not hear it and ask them to "
+                    "send it again or type the message.]"
+                ),
+            }
+        ]
+    text = result.text
+    if not text:
+        return [
+            {
+                "type": "text",
+                "text": f"[system-note: the audio file {label} was transcribed, but no speech was found in it.]",
+            }
+        ]
+    length = f", {result.duration_seconds:.0f} s" if result.duration_seconds else ""
+    note = ""
+    if cap_chars > 0 and len(text) > cap_chars:
+        text = text[:cap_chars]
+        note = " Only the start is shown: the conversation has no room for the rest."
+    # Worded as audio the agent HEARD, not a transcript the user supplied (see AUDIO_HEARD_NOTE).
+    return [
+        {
+            "type": "text",
+            "text": (
+                f"[The user sent an audio clip ({label}{length}). What was said, transcribed "
+                f"automatically (a word may be misheard):{note}]\n{text}"
+            ),
+        }
+    ]
+
+
+async def audio_blocks(
+    transcriber: Any,
+    file: AttachedFile,
+    *,
+    model: str,
+    headers: dict[str, str],
+    share_tokens: int,
+    limits: AttachmentLimits = AttachmentLimits(),  # noqa: B008 - frozen, shared default
+    content: bytes | None = None,
+    open_content: Any = None,
+    audio_url: Any = None,
+) -> FileBlocks:
+    """One clip through the shared STT client. ``status``: ``shown`` when heard (speech or not),
+    ``unreadable`` when it could not be transcribed — never raises."""
+    try:
+        heard = await transcriber.transcribe(
+            filename=file.name,
+            mime=file.base_mime,
+            model=model,
+            headers=headers,
+            size=file.size,
+            content=content,
+            open_content=open_content,
+            audio_url=audio_url,
+        )
+    except TranscriptionFailed as exc:
+        _logger.warning("audio attachment not transcribed artifact_id=%s error=%s", file.artifact_id, exc)
+        reason = (
+            "it is over the size limit"
+            if exc.code == "AUDIO_TOO_LARGE"
+            else "the speech-to-text service could not process it"
+        )
+        return FileBlocks(transcript_blocks(file.name, reason, cap_chars=0), "unreadable")
+    cap = text_cap_chars(share_tokens, limits)
+    return FileBlocks(transcript_blocks(file.name, heard, cap_chars=cap), "shown")

keystone/agent_tools/attachments/blocks.py

@@ -0,0 +1,491 @@
+"""The files attached to a turn, as content blocks for the model (FDP-6967, item 2).
+
+One set of rules for visual-builder and master-agent. The owner's table:
+
+==========================================  =====================================================
+What is in the file                         What the model gets
+==========================================  =====================================================
+text, tables (any document)                 text (Markdown tables), read by file-artifact
+native Office chart (docx / pptx / xlsx)    its data as text (type, title, series, values)
+embedded picture (Office ``media/``)        an image block — SMALL file only, capped
+a PDF page                                  the page rendered as an image — SMALL PDF only
+a large file                                text only, and a note saying pictures were not sent
+a photo / screenshot                        an image block, downscaled to the provider limit
+==========================================  =====================================================
+
+**Budget.** 130,000 tokens per turn split evenly across the files (:mod:`.budget`); a file's share
+caps its text (sent as ``max_chars``, so file-artifact never ships more) and its picture bytes.
+Pictures also have a count: :attr:`AttachmentLimits.images_per_file` and
+:attr:`AttachmentLimits.images_per_turn` (:class:`TurnPictures`). Whatever is left out is said in
+a note, first, so the model never answers from half a file as if it were whole.
+
+**What stays the host's.** Fetching a photo's bytes, transcribing audio, binding a file to a
+thread, the per-service wording around the blocks: this module only makes blocks. Nothing here
+parses a document — file-artifact does, off this process — and the one CPU-bound step (fitting a
+picture) runs in a worker thread.
+
+The numbers marked *mạch B* come from the FDP-6967 dev measurements (2026-10-29): a PDF page is
+≈1.7k tokens either as a document or as a picture; Claude and Nova read every number from a chart
+sent as picture + chart text; a ``document`` block of a DOCX loses its pictures and of a PPTX is
+refused by litellm — hence pictures and text, never a ``document`` block.
+"""
+
+# Feature: FR-78 item 2 | Tracking: FDP-6967
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import dataclasses
+import logging
+from dataclasses import dataclass
+from typing import IO, Any, Literal
+
+from keystone.agent_tools.attachments.budget import (
+    MIN_FLOOR_TOKENS_PER_FILE,
+    STATIC_TURN_ATTACHMENT_BUDGET,
+    cap_bytes_for_share,
+)
+from keystone.agent_tools.attachments.images import MAX_IMAGE_BYTES, DecodeRefused, fit_image_async
+from keystone.agent_tools.files.wire import FileArtifactError
+
+__all__ = [
+    "IMAGE_MIMES",
+    "AttachedFile",
+    "AttachmentLimits",
+    "FileBlocks",
+    "TurnPictures",
+    "aggregate_refused_note",
+    "attached_marker",
+    "document_blocks",
+    "fmt_size",
+    "image_blocks",
+    "is_document",
+    "is_image",
+    "named",
+    "text_cap_chars",
+]
+
+_logger = logging.getLogger("keystone.agent_tools.attachments")
+
+#: Raster types every provider takes as an image block. An SVG is text.
+IMAGE_MIMES = frozenset({"image/png", "image/jpeg", "image/webp", "image/gif"})
+
+_PDF = "application/pdf"
+_DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+_XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+_PPTX = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+#: The documents whose pictures / charts file-artifact can add (``include_images`` / ``include_charts``).
+_RICH = frozenset({_PDF, _DOCX, _XLSX, _PPTX})
+_OFFICE = frozenset({_DOCX, _XLSX, _PPTX})
+#: Read as text by file-artifact besides ``text/*``.
+_TEXTUAL = frozenset(
+    {
+        "application/json",
+        "application/xml",
+        "application/yaml",
+        "application/x-yaml",
+        "image/svg+xml",
+        "application/rtf",
+        "application/msword",
+        "application/vnd.ms-excel",
+        "application/vnd.ms-powerpoint",
+        "application/xhtml+xml",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AttachmentLimits:
+    """The knobs. Defaults are the owner's / mạch B's numbers; a host may pass its own (config)."""
+
+    #: Tokens one turn's attachments may use together.
+    budget_tokens: int = STATIC_TURN_ATTACHMENT_BUDGET
+    #: A file's text never exceeds this many characters, whatever its share (VB's 200 KB).
+    max_text_chars: int = 200_000
+    #: "Small file" (mạch B): up to this size a document's pictures / pages are sent.
+    small_file_bytes: int = 4 * 1024 * 1024
+    #: "Small PDF" (mạch B): at most this many pages; and the text window of every PDF.
+    small_pdf_pages: int = 20
+    #: Pictures from one file, and from the whole turn (mạch B: 10 / 20).
+    images_per_file: int = 10
+    images_per_turn: int = 20
+    #: One picture's raw bytes (Bedrock: 3.75 MB).
+    image_max_bytes: int = MAX_IMAGE_BYTES
+
+    def __post_init__(self) -> None:
+        # A host builds this from its settings at start: a zero or negative knob is a typo there,
+        # refused loudly rather than silently sending nothing.
+        for name in (
+            "budget_tokens",
+            "max_text_chars",
+            "small_file_bytes",
+            "small_pdf_pages",
+            "images_per_file",
+            "images_per_turn",
+            "image_max_bytes",
+        ):
+            if getattr(self, name) <= 0:
+                raise ValueError(f"AttachmentLimits.{name} must be > 0, got {getattr(self, name)!r}")
+
+
+@dataclass(frozen=True, slots=True)
+class AttachedFile:
+    artifact_id: str
+    name: str
+    mime: str
+    size: int = 0
+
+    @property
+    def base_mime(self) -> str:
+        return self.mime.split(";", 1)[0].strip().lower()
+
+
+@dataclass(frozen=True, slots=True)
+class FileBlocks:
+    """One file's blocks. ``status``: ``shown`` (content reached the model), ``named`` (only its name
+    and why — a type nobody reads, a picture over the limits) or ``unreadable`` (a failure)."""
+
+    blocks: list[dict[str, Any]]
+    status: Literal["shown", "named", "unreadable"] = "shown"
+    #: How many pictures this file put in the turn.
+    pictures: int = 0
+
+
+class TurnPictures:
+    """The turn's picture count, shared by every file of the turn.
+
+    A document reserves its pictures BEFORE it is read (:meth:`hold`) and gives back what it did not
+    use once read (:meth:`release`). A host reads a turn's files together, so a photo can ask while
+    a document still holds a reservation it will mostly give back: :meth:`take_waiting` waits for
+    those reads to end instead of reporting the turn full. Without the wait, two small documents
+    (10 reserved each) left a photo attached with them unshown — "this message already carries as
+    many pictures as one turn may" — though they used two pictures (dev, 2026-10-30).
+    """
+
+    def __init__(self, limit: int) -> None:
+        self.left = max(0, limit)
+        #: Pictures reserved by documents still being read.
+        self.held = 0
+        self._changed: asyncio.Event | None = None
+
+    def take(self, wanted: int) -> int:
+        granted = max(0, min(wanted, self.left))
+        self.left -= granted
+        return granted
+
+    def hold(self, wanted: int) -> int:
+        """Reserve up to ``wanted`` pictures for a document about to be read."""
+        granted = self.take(wanted)
+        self.held += granted
+        return granted
+
+    def release(self, held: int, used: int) -> None:
+        """A document's read ended: of the ``held`` pictures it reserved it used ``used``."""
+        self.held -= held
+        self.left += held - min(used, held)
+        if self._changed is not None:
+            self._changed.set()
+            self._changed = None
+
+    async def take_waiting(self, wanted: int) -> int:
+        """:meth:`take`, but while documents still hold pictures, wait for them before saying none."""
+        while True:
+            granted = self.take(wanted)
+            if granted or self.held <= 0:
+                return granted
+            if self._changed is None:
+                self._changed = asyncio.Event()
+            await self._changed.wait()
+
+
+def is_image(mime: str) -> bool:
+    return mime.split(";", 1)[0].strip().lower() in IMAGE_MIMES
+
+
+def is_document(mime: str, name: str = "") -> bool:
+    base = mime.split(";", 1)[0].strip().lower()
+    if base in _RICH or base in _TEXTUAL or (base.startswith("text/")):
+        return True
+    # Browsers send a .docx as a generic type now and then.
+    return base in {"application/octet-stream", "application/zip"} and name.lower().endswith(
+        (".docx", ".xlsx", ".pptx", ".pdf")
+    )
+
+
+def _effective_mime(file: AttachedFile) -> str:
+    base = file.base_mime
+    if base in {"application/octet-stream", "application/zip"}:
+        ext = file.name.lower().rsplit(".", 1)[-1]
+        return {"docx": _DOCX, "xlsx": _XLSX, "pptx": _PPTX, "pdf": _PDF}.get(ext, base)
+    return base
+
+
+def fmt_size(n_bytes: int) -> str:
+    """visual-builder's size label."""
+    if n_bytes < 1024:
+        return f"{n_bytes}B"
+    if n_bytes < 1024 * 1024:
+        return f"{n_bytes / 1024:.1f}KB"
+    return f"{n_bytes / (1024 * 1024):.1f}MB"
+
+
+def attached_marker(file: AttachedFile) -> dict[str, Any]:
+    """``[Attached: artifact_id=<id> (name=..., mime=..., size=...)]`` — the id the file tools take."""
+    return {
+        "type": "text",
+        "text": (
+            f"[Attached: artifact_id={file.artifact_id} (name={file.name or 'unknown'}, "
+            f"mime={file.mime}, size={fmt_size(file.size)})]"
+        ),
+    }
+
+
+def named(file: AttachedFile, why: str) -> dict[str, Any]:
+    """The file named, not shown, with the reason — so the model neither invents it nor denies it."""
+    return {
+        "type": "text",
+        "text": (
+            f"[system-note: the user attached {file.name} ({file.mime}), but its content is not shown: "
+            f"{why}. Say what the file is, and offer what you can do without its content.]"
+        ),
+    }
+
+
+def aggregate_refused_note(n_files: int, share_tokens: int) -> dict[str, Any]:
+    return {
+        "type": "text",
+        "text": (
+            f"[system-note: ARTIFACT_AGGREGATE_TRUNCATED — {n_files} files attached but conversation "
+            f"context is nearly full ({share_tokens} tokens/file share < {MIN_FLOOR_TOKENS_PER_FILE} "
+            "minimum). Content omitted; agent has metadata only. Start a new conversation to attach "
+            "large files.]"
+        ),
+    }
+
+
+def text_cap_chars(share_tokens: int, limits: AttachmentLimits) -> int:
+    """A file's text cap: its share at 4 characters a token, never above the per-file ceiling."""
+    return max(0, min(limits.max_text_chars, cap_bytes_for_share("text/plain", share_tokens)))
+
+
+def _note(text: str) -> dict[str, Any]:
+    return {"type": "text", "text": text}
+
+
+def _image_block(data: bytes, media_type: str) -> dict[str, Any]:
+    return {
+        "type": "image",
+        "source": {"type": "base64", "media_type": media_type, "data": base64.b64encode(data).decode("ascii")},
+    }
+
+
+# ── documents: read by file-artifact ────────────────────────────────────────
+
+
+class _Held:
+    """One document's reservation: given back exactly once, whatever way the read ends."""
+
+    def __init__(self, pictures: TurnPictures, n: int) -> None:
+        self.pictures = pictures
+        self.n = n
+        self._open = True
+
+    def release(self, used: int) -> None:
+        if self._open:
+            self._open = False
+            self.pictures.release(self.n, used)
+
+
+async def document_blocks(
+    client: Any,
+    file: AttachedFile,
+    *,
+    share_tokens: int,
+    n_files: int,
+    pictures: TurnPictures,
+    limits: AttachmentLimits = AttachmentLimits(),  # noqa: B008 - frozen, shared default
+    ocr: dict[str, Any] | None = None,
+) -> FileBlocks:
+    """A document's blocks: notes first, then its text, its charts as text, then its pictures.
+
+    ``client`` is a :class:`~keystone.agent_tools.files.FileArtifactClient` (or a view of one)
+    acting as whoever may read the file. Never raises: a refusal is a note.
+    """
+    mime = _effective_mime(file)
+    rich_type = mime in _RICH
+    # Size 0 means "unknown" (no Content-Length on the fetch): not counted as small.
+    small = 0 < file.size <= limits.small_file_bytes
+    # Reserved BEFORE the read (and the unused part given back after): with several files read
+    # together, the turn's pictures go to the files in the order they were attached. A photo read
+    # alongside waits for this reservation to end (TurnPictures.take_waiting), so it must always end.
+    want_pictures = rich_type and small and pictures.left > 0
+    held = _Held(pictures, pictures.hold(limits.images_per_file) if want_pictures else 0)
+    try:
+        return await _document_blocks_held(
+            client, file, share_tokens=share_tokens, n_files=n_files, held=held, limits=limits, ocr=ocr
+        )
+    finally:
+        held.release(0)  # no-op once the read gave back what it did not use
+
+
+async def _document_blocks_held(
+    client: Any,
+    file: AttachedFile,
+    *,
+    share_tokens: int,
+    n_files: int,
+    held: _Held,
+    limits: AttachmentLimits,
+    ocr: dict[str, Any] | None,
+) -> FileBlocks:
+    mime = _effective_mime(file)
+    cap = text_cap_chars(share_tokens, limits)
+    rich_type = mime in _RICH
+    small = 0 < file.size <= limits.small_file_bytes
+    per_file = held.n
+    kwargs: dict[str, Any] = {"artifact_id": file.artifact_id, "max_chars": max(1, cap)}
+    if mime == _PDF:
+        kwargs["range_spec"] = f"1-{limits.small_pdf_pages}"
+    if rich_type:
+        # Charts are text and cheap; for a PDF this also returns its page count.
+        kwargs["include_charts"] = True
+    if per_file:
+        kwargs["include_images"] = True
+        kwargs["max_images"] = per_file
+        if mime == _PDF:
+            # Pages are rendered only for a small PDF — file-artifact checks the count first.
+            kwargs["pdf_max_pages"] = limits.small_pdf_pages
+    if ocr is not None:
+        kwargs["ocr"] = ocr
+    try:
+        try:
+            result = await client.read_artifact(**kwargs)
+        except Exception as exc:
+            # A file-artifact older than these options refuses them (422, extra="forbid"): read the
+            # plain text window instead, so a rolling deploy never makes a file unreadable.
+            if _status_of(exc) != 422 or set(kwargs) <= {"artifact_id", "range_spec", "ocr"}:
+                raise
+            plain = {k: v for k, v in kwargs.items() if k in {"artifact_id", "range_spec", "ocr"}}
+            result = await client.read_artifact(**plain)
+            if len(result.text) > cap:
+                result = dataclasses.replace(
+                    result, text=result.text[:cap], notes=(*result.notes, f"[Đã cắt: chỉ gửi {cap} ký tự đầu.]")
+                )
+    except FileArtifactError as exc:
+        held.release(0)
+        if exc.status == 415 or exc.code == "FA_UNSUPPORTED_MEDIA_TYPE":
+            return FileBlocks([named(file, f"this assistant cannot read {file.mime} files")], "named")
+        _logger.warning("attachment not read artifact_id=%s code=%s", file.artifact_id, exc.code)
+        return FileBlocks([_unreadable(file)], "unreadable")
+    except Exception as exc:  # a host's own typed errors (visual-builder raises VBError subclasses)
+        held.release(0)
+        status = _status_of(exc)
+        if status == 415:
+            return FileBlocks([named(file, f"this assistant cannot read {file.mime} files")], "named")
+        _logger.warning("attachment not read artifact_id=%s error=%s", file.artifact_id, exc)
+        return FileBlocks([_unreadable(file)], "unreadable")
+
+    notes: list[str] = list(result.notes)
+    page_count = result.meta.get("page_count") if isinstance(result.meta, dict) else None
+    images = list(result.images)
+    if mime == _PDF and isinstance(page_count, int) and page_count > limits.small_pdf_pages:
+        notes.insert(
+            0,
+            f"[Tài liệu PDF có {page_count} trang: chỉ đọc chữ của {limits.small_pdf_pages} trang đầu. "
+            "Trả lời theo phần này và nói rõ khi câu hỏi nằm ở trang sau.]",
+        )
+        if images:
+            images = []  # a long PDF is not "small": text only
+            notes.append("[PDF dài: không gửi ảnh trang.]")
+    if rich_type and not small and file.size:
+        notes.append(
+            f"[File lớn ({fmt_size(file.size)}): chỉ gửi chữ; ảnh và biểu đồ dạng ảnh trong file không được gửi.]"
+        )
+    elif rich_type and small and not per_file:
+        notes.append("[Lượt này đã đủ số ảnh: ảnh trong file này không được gửi.]")
+
+    blocks: list[dict[str, Any]] = [_note(f"[system-note: {file.name} — {n.strip().strip('[]')}]") for n in notes]
+    text = result.text or ""
+    if text.strip():
+        blocks.append(_note(f"[Attached file content: {file.name}]\n{text}"))
+    for chart in result.charts:
+        blocks.append(_note(f"[Biểu đồ trong {file.name}]\n{chart}"))
+
+    granted = min(len(images), per_file)
+    held.release(granted)  # the reserved pictures this file did not use go back
+    sent = 0
+    byte_cap = min(limits.image_max_bytes, cap_bytes_for_share("image/png", share_tokens))
+    for image in images[:granted]:
+        try:
+            raw = base64.b64decode(image["data"], validate=True)
+        except (ValueError, KeyError, TypeError):
+            continue
+        fitted = await _fit(raw, str(image.get("mime") or "image/png"), file.name, byte_cap, n_files)
+        if fitted is None:
+            continue
+        data, media_type, _ = fitted
+        source = image.get("source")
+        blocks.append(_note(f"[Ảnh trong {file.name}{f' ({source})' if source else ''}]"))
+        blocks.append(_image_block(data, media_type))
+        sent += 1
+    if len(images) > granted:
+        blocks.append(_note(f"[system-note: {file.name} — {len(images) - granted} ảnh không gửi vì đã đủ số ảnh.]"))
+    if not text.strip() and not result.charts and not sent:
+        return FileBlocks([*blocks, named(file, "no text could be read from it")], "named", sent)
+    return FileBlocks(blocks, "shown", sent)
+
+
+def _status_of(exc: BaseException) -> int | None:
+    """The HTTP status of a refusal: the lib's ``FileArtifactError`` or a host's typed error."""
+    status = getattr(exc, "status", None)
+    if isinstance(status, int) and status:
+        return status
+    details = getattr(exc, "details", None)
+    found = details.get("status") if isinstance(details, dict) else None
+    return found if isinstance(found, int) else None
+
+
+def _unreadable(file: AttachedFile) -> dict[str, Any]:
+    return _note(
+        f"[system-note: the user attached {file.name} ({file.mime}), but it could not be read right now. "
+        "Say so plainly and offer to have it sent again — do not answer as if nothing was attached.]"
+    )
+
+
+async def _fit(raw: bytes | IO[bytes], mime: str, name: str, byte_cap: int, n_files: int):
+    try:
+        return await fit_image_async(raw, mime, name, byte_cap=byte_cap, n_files=n_files)
+    except DecodeRefused:
+        return None
+
+
+# ── a photo / screenshot: the host fetched its bytes ────────────────────────
+
+
+async def image_blocks(
+    content: bytes | IO[bytes],
+    file: AttachedFile,
+    *,
+    share_tokens: int,
+    n_files: int,
+    pictures: TurnPictures,
+    limits: AttachmentLimits = AttachmentLimits(),  # noqa: B008 - frozen, shared default
+) -> FileBlocks:
+    """A picture the user attached, downscaled to the provider's limit (in a worker thread)."""
+    if await pictures.take_waiting(1) == 0:
+        return FileBlocks([named(file, "this message already carries as many pictures as one turn may")], "named")
+    byte_cap = min(limits.image_max_bytes, cap_bytes_for_share(file.base_mime, share_tokens))
+    try:
+        fitted = await fit_image_async(content, file.base_mime, file.name, byte_cap=byte_cap, n_files=n_files)
+    except DecodeRefused as refused:
+        pictures.left += 1
+        size = f"{refused.width}x{refused.height} px " if refused.width else ""
+        return FileBlocks([named(file, f"the {size}picture is over the safe decode limit")], "named")
+    if fitted is None:
+        pictures.left += 1
+        return FileBlocks([named(file, "it is too large to display here and could not be reduced")], "named")
+    data, media_type, note = fitted
+    blocks = [_note(note)] if note else []
+    blocks.append(_image_block(data, media_type))
+    return FileBlocks(blocks, "shown", 1)