keystone-agent-tools 0.1.5__tar.gz

keystone_agent_tools-0.1.5/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: keystone-agent-tools
+Version: 0.1.5
+Summary: The file tools a platform agent gets (read / search / create / render / edit an artifact through file-artifact), the extended knowledge-base toolset (FR-180), and how a turn's attachments reach the model. One definition for visual-builder and master-agent, so the two cannot drift.
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: langgraph<2,>=1
+Requires-Dist: Pillow<14,>=13
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"

keystone_agent_tools-0.1.5/__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-0.1.5/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-0.1.5/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")