pyfect-dev 0.1.0__py3-none-any.whl

pyfect/ai/anthropic/tool.py

@@ -0,0 +1,570 @@
+"""Anthropic's provider-defined tools (Effect's ``AnthropicTool``).
+
+Each constant is a tool's constructor: call it with the tool's arguments
+to put it in a toolkit. Tools Anthropic runs (code execution, web search,
+web fetch, tool search) need no handler; the client tools (bash, the text
+editor, computer use, memory) do::
+
+    kit = toolkit.make(tool.WebSearch_20250305(max_uses=3), tool.Bash_20250124())
+
+Arguments use Effect's camelCase names (``maxUses``, ``displayWidthPx``)
+as keywords or a mapping. The results of server tools are Anthropic's
+JSON blocks, unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+from pyfect import schema as S
+from pyfect.ai import tool as T
+
+_BLOCK = S.Record(S.String, S.Unknown)
+"""A JSON block Anthropic returns, kept whole."""
+
+# Bash ----------------------------------------------------------------------------------
+
+
+class BashParameters(TypedDict):
+    command: str
+    restart: NotRequired[bool]
+
+
+Bash_20241022 = T.provider_defined(
+    id="anthropic.bash_20241022",
+    custom_name="AnthropicBash",
+    provider_name="bash",
+    requires_handler=True,
+    parameters=S.Struct(BashParameters),
+    success=S.String,
+)
+Bash_20250124 = T.provider_defined(
+    id="anthropic.bash_20250124",
+    custom_name="AnthropicBash",
+    provider_name="bash",
+    requires_handler=True,
+    parameters=S.Struct(BashParameters),
+    success=S.String,
+)
+
+# Code execution ------------------------------------------------------------------------
+
+
+class CodeExecutionProgrammaticToolCall(TypedDict):
+    type: Literal["programmatic-tool-call"]
+    code: str
+
+
+class CodeExecutionBashCommand(TypedDict):
+    type: Literal["bash_code_execution"]
+    command: str
+
+
+class CodeExecutionTextEditorView(TypedDict):
+    type: Literal["text_editor_code_execution"]
+    command: Literal["view"]
+    path: str
+
+
+class CodeExecutionTextEditorCreate(TypedDict):
+    type: Literal["text_editor_code_execution"]
+    command: Literal["create"]
+    path: str
+    file_text: NotRequired[str | None]
+
+
+class CodeExecutionTextEditorStrReplace(TypedDict):
+    type: Literal["text_editor_code_execution"]
+    command: Literal["str_replace"]
+    path: str
+    old_str: str
+    new_str: str
+
+
+class CodeExecution_20250825_Parameters(TypedDict):
+    code: str
+
+
+CodeExecution_20250522 = T.provider_defined(
+    id="anthropic.code_execution_20250522",
+    custom_name="AnthropicCodeExecution",
+    provider_name="code_execution",
+    parameters=S.Union(
+        S.Struct(CodeExecutionProgrammaticToolCall),
+        S.Struct(CodeExecutionBashCommand),
+        S.Struct(CodeExecutionTextEditorView),
+        S.Struct(CodeExecutionTextEditorCreate),
+        S.Struct(CodeExecutionTextEditorStrReplace),
+    ),
+    success=_BLOCK,
+    failure=_BLOCK,
+)
+CodeExecution_20250825 = T.provider_defined(
+    id="anthropic.code_execution_20250825",
+    custom_name="AnthropicCodeExecution",
+    provider_name="code_execution",
+    parameters=S.Struct(CodeExecution_20250825_Parameters),
+    success=_BLOCK,
+    failure=_BLOCK,
+)
+
+# Computer use --------------------------------------------------------------------------
+
+type Coordinate = tuple[int, int]
+type Region = tuple[int, int, int, int]
+
+
+class ComputerUseArgs(TypedDict):
+    displayWidthPx: int
+    displayHeightPx: int
+    displayNumber: NotRequired[int]
+
+
+class ComputerUse_20251124_Args(ComputerUseArgs):
+    enableZoom: NotRequired[bool]
+
+
+class KeyAction(TypedDict):
+    action: Literal["key"]
+    text: str
+
+
+class LeftClickAction(TypedDict):
+    action: Literal["left_click"]
+    coordinate: NotRequired[Coordinate]
+
+
+class MouseMoveAction(TypedDict):
+    action: Literal["mouse_move"]
+    coordinate: Coordinate
+
+
+class ScreenshotAction(TypedDict):
+    action: Literal["screenshot"]
+
+
+class TypeAction(TypedDict):
+    action: Literal["type"]
+    text: str
+
+
+class DoubleClickAction(TypedDict):
+    action: Literal["double_click"]
+    coordinate: NotRequired[Coordinate]
+
+
+class HoldKeyAction(TypedDict):
+    action: Literal["hold_key"]
+    text: str
+    duration: float
+
+
+class LeftClickDragAction(TypedDict):
+    action: Literal["left_click_drag"]
+    start_coordinate: Coordinate
+    coordinate: Coordinate
+
+
+class LeftMouseDownAction(TypedDict):
+    action: Literal["left_mouse_down"]
+    coordinate: NotRequired[Coordinate]
+
+
+class LeftMouseUpAction(TypedDict):
+    action: Literal["left_mouse_up"]
+    coordinate: NotRequired[Coordinate]
+
+
+class MiddleClickAction(TypedDict):
+    action: Literal["middle_click"]
+    coordinate: NotRequired[Coordinate]
+
+
+class RightClickAction(TypedDict):
+    action: Literal["right_click"]
+    coordinate: NotRequired[Coordinate]
+
+
+class ScrollAction(TypedDict):
+    action: Literal["scroll"]
+    coordinate: NotRequired[Coordinate]
+    scroll_direction: Literal["up", "down", "left", "right"]
+    scroll_amount: int
+
+
+class TripleClickAction(TypedDict):
+    action: Literal["triple_click"]
+    coordinate: NotRequired[Coordinate]
+
+
+class WaitAction(TypedDict):
+    action: Literal["wait"]
+    duration: float
+
+
+class ZoomAction(TypedDict):
+    action: Literal["zoom"]
+    region: Region
+
+
+_ACTIONS_20241022 = (
+    S.Struct(KeyAction),
+    S.Struct(LeftClickAction),
+    S.Struct(MouseMoveAction),
+    S.Struct(ScreenshotAction),
+    S.Struct(TypeAction),
+)
+_ACTIONS_20250124 = (
+    *_ACTIONS_20241022,
+    S.Struct(DoubleClickAction),
+    S.Struct(HoldKeyAction),
+    S.Struct(LeftClickDragAction),
+    S.Struct(LeftMouseDownAction),
+    S.Struct(LeftMouseUpAction),
+    S.Struct(MiddleClickAction),
+    S.Struct(RightClickAction),
+    S.Struct(ScrollAction),
+    S.Struct(TripleClickAction),
+    S.Struct(WaitAction),
+)
+
+type ComputerUse_20241022_Action = (
+    KeyAction | LeftClickAction | MouseMoveAction | ScreenshotAction | TypeAction
+)
+type ComputerUse_20250124_Action = (
+    ComputerUse_20241022_Action
+    | DoubleClickAction
+    | HoldKeyAction
+    | LeftClickDragAction
+    | LeftMouseDownAction
+    | LeftMouseUpAction
+    | MiddleClickAction
+    | RightClickAction
+    | ScrollAction
+    | TripleClickAction
+    | WaitAction
+)
+type ComputerUse_20251124_Action = ComputerUse_20250124_Action | ZoomAction
+
+_COMPUTER_20241022: S.Codec[ComputerUse_20241022_Action, Any, Any, Any] = S.Union(
+    *_ACTIONS_20241022
+)
+_COMPUTER_20250124: S.Codec[ComputerUse_20250124_Action, Any, Any, Any] = S.Union(
+    *_ACTIONS_20250124
+)
+_COMPUTER_20251124: S.Codec[ComputerUse_20251124_Action, Any, Any, Any] = S.Union(
+    *_ACTIONS_20250124, S.Struct(ZoomAction)
+)
+
+ComputerUse_20241022 = T.provider_defined(
+    id="anthropic.computer_use_20241022",
+    custom_name="AnthropicComputerUse",
+    provider_name="computer_use",
+    requires_handler=True,
+    args=S.Struct(ComputerUseArgs),
+    parameters=_COMPUTER_20241022,
+    success=S.String,
+)
+ComputerUse_20250124 = T.provider_defined(
+    id="anthropic.computer_20250124",
+    custom_name="AnthropicComputerUse",
+    provider_name="computer",
+    requires_handler=True,
+    args=S.Struct(ComputerUseArgs),
+    parameters=_COMPUTER_20250124,
+    success=S.String,
+)
+ComputerUse_20251124 = T.provider_defined(
+    id="anthropic.computer_20251124",
+    custom_name="AnthropicComputerUse",
+    provider_name="computer",
+    requires_handler=True,
+    args=S.Struct(ComputerUse_20251124_Args),
+    parameters=_COMPUTER_20251124,
+    success=S.String,
+)
+
+# Memory and the text editor ------------------------------------------------------------
+
+type ViewRange = tuple[int, int]
+
+
+class MemoryCreateCommand(TypedDict):
+    command: Literal["create"]
+    path: str
+    file_text: str
+
+
+class MemoryDeleteCommand(TypedDict):
+    command: Literal["delete"]
+    path: str
+
+
+class MemoryInsertCommand(TypedDict):
+    command: Literal["insert"]
+    path: str
+    insert_line: int
+    insert_text: str
+
+
+class MemoryRenameCommand(TypedDict):
+    command: Literal["rename"]
+    old_path: str
+    new_path: str
+
+
+class StrReplaceCommand(TypedDict):
+    command: Literal["str_replace"]
+    path: str
+    old_str: str
+    new_str: str
+
+
+class ViewCommand(TypedDict):
+    command: Literal["view"]
+    path: str
+    view_range: NotRequired[ViewRange]
+
+
+type MemoryCommand = (
+    MemoryCreateCommand
+    | MemoryDeleteCommand
+    | MemoryInsertCommand
+    | MemoryRenameCommand
+    | StrReplaceCommand
+    | ViewCommand
+)
+
+_MEMORY: S.Codec[MemoryCommand, Any, Any, Any] = S.Union(
+    S.Struct(MemoryCreateCommand),
+    S.Struct(MemoryDeleteCommand),
+    S.Struct(MemoryInsertCommand),
+    S.Struct(MemoryRenameCommand),
+    S.Struct(StrReplaceCommand),
+    S.Struct(ViewCommand),
+)
+
+Memory_20250818 = T.provider_defined(
+    id="anthropic.memory_20250818",
+    custom_name="AnthropicMemory",
+    provider_name="memory",
+    requires_handler=True,
+    parameters=_MEMORY,
+    success=S.String,
+)
+
+
+class CreateCommand(TypedDict):
+    command: Literal["create"]
+    path: str
+    file_text: str
+
+
+class InsertCommand(TypedDict):
+    command: Literal["insert"]
+    path: str
+    insert_line: int
+    new_str: str
+
+
+class UndoEditCommand(TypedDict):
+    command: Literal["undo_edit"]
+    path: str
+
+
+class TextEditorArgs(TypedDict):
+    max_characters: NotRequired[int]
+
+
+type StrReplaceBasedEditCommand = ViewCommand | CreateCommand | StrReplaceCommand | InsertCommand
+type StrReplaceEditorCommand = StrReplaceBasedEditCommand | UndoEditCommand
+
+_BASED_EDIT = (
+    S.Struct(ViewCommand),
+    S.Struct(CreateCommand),
+    S.Struct(StrReplaceCommand),
+    S.Struct(InsertCommand),
+)
+_STR_REPLACE_EDITOR: S.Codec[StrReplaceEditorCommand, Any, Any, Any] = S.Union(
+    *_BASED_EDIT, S.Struct(UndoEditCommand)
+)
+_STR_REPLACE_BASED_EDIT: S.Codec[StrReplaceBasedEditCommand, Any, Any, Any] = S.Union(*_BASED_EDIT)
+
+TextEditor_20241022 = T.provider_defined(
+    id="anthropic.text_editor_20241022",
+    custom_name="AnthropicTextEditor",
+    provider_name="str_replace_editor",
+    requires_handler=True,
+    parameters=_STR_REPLACE_EDITOR,
+    success=S.String,
+)
+TextEditor_20250124 = T.provider_defined(
+    id="anthropic.text_editor_20250124",
+    custom_name="AnthropicTextEditor",
+    provider_name="str_replace_editor",
+    requires_handler=True,
+    parameters=_STR_REPLACE_EDITOR,
+    success=S.String,
+)
+TextEditor_20250429 = T.provider_defined(
+    id="anthropic.text_editor_20250429",
+    custom_name="AnthropicTextEditor",
+    provider_name="str_replace_based_edit_tool",
+    requires_handler=True,
+    args=S.Struct(TextEditorArgs),
+    parameters=_STR_REPLACE_BASED_EDIT,
+    success=S.String,
+)
+TextEditor_20250728 = T.provider_defined(
+    id="anthropic.text_editor_20250728",
+    custom_name="AnthropicTextEditor",
+    provider_name="str_replace_based_edit_tool",
+    requires_handler=True,
+    args=S.Struct(TextEditorArgs),
+    parameters=_STR_REPLACE_BASED_EDIT,
+    success=S.String,
+)
+
+# Web search, web fetch and tool search ----------------------------------------------------
+
+
+class WebSearchUserLocation(TypedDict):
+    type: Literal["approximate"]
+    city: NotRequired[str]
+    region: NotRequired[str]
+    country: NotRequired[str]
+    timezone: NotRequired[str]
+
+
+class WebSearch_20250305_Args(TypedDict, total=False):
+    maxUses: int
+    allowedDomains: list[str]
+    blockedDomains: list[str]
+    userLocation: WebSearchUserLocation
+
+
+class QueryParameters(TypedDict):
+    query: str
+
+
+WebSearch_20250305 = T.provider_defined(
+    id="anthropic.web_search_20250305",
+    custom_name="AnthropicWebSearch",
+    provider_name="web_search",
+    args=S.Struct(WebSearch_20250305_Args),
+    parameters=S.Struct(QueryParameters),
+    success=S.Array(_BLOCK),
+    failure=_BLOCK,
+)
+
+
+class WebFetchCitationsConfig(TypedDict):
+    enabled: bool
+
+
+class WebFetch_20250910_Args(TypedDict, total=False):
+    maxUses: int
+    allowedDomains: list[str]
+    blockedDomains: list[str]
+    citations: WebFetchCitationsConfig
+    maxContentTokens: int
+
+
+class WebFetchParameters(TypedDict):
+    url: str
+
+
+WebFetch_20250910 = T.provider_defined(
+    id="anthropic.web_fetch_20250910",
+    custom_name="AnthropicWebFetch",
+    provider_name="web_fetch",
+    args=S.Struct(WebFetch_20250910_Args),
+    parameters=S.Struct(WebFetchParameters),
+    success=_BLOCK,
+    failure=_BLOCK,
+)
+ToolSearchRegex_20251119 = T.provider_defined(
+    id="anthropic.tool_search_tool_regex_20251119",
+    custom_name="AnthropicToolSearchRegex",
+    provider_name="tool_search_tool_regex",
+    parameters=S.Struct(QueryParameters),
+    success=S.Array(_BLOCK),
+    failure=_BLOCK,
+)
+ToolSearchBM25_20251119 = T.provider_defined(
+    id="anthropic.tool_search_tool_bm25_20251119",
+    custom_name="AnthropicToolSearchBM25",
+    provider_name="tool_search_tool_bm25",
+    parameters=S.Struct(QueryParameters),
+    success=S.Array(_BLOCK),
+    failure=_BLOCK,
+)
+
+__all__ = [
+    "BashParameters",
+    "Bash_20241022",
+    "Bash_20250124",
+    "CodeExecutionBashCommand",
+    "CodeExecutionProgrammaticToolCall",
+    "CodeExecutionTextEditorCreate",
+    "CodeExecutionTextEditorStrReplace",
+    "CodeExecutionTextEditorView",
+    "CodeExecution_20250522",
+    "CodeExecution_20250825",
+    "CodeExecution_20250825_Parameters",
+    "ComputerUseArgs",
+    "ComputerUse_20241022",
+    "ComputerUse_20241022_Action",
+    "ComputerUse_20250124",
+    "ComputerUse_20250124_Action",
+    "ComputerUse_20251124",
+    "ComputerUse_20251124_Action",
+    "ComputerUse_20251124_Args",
+    "Coordinate",
+    "CreateCommand",
+    "DoubleClickAction",
+    "HoldKeyAction",
+    "InsertCommand",
+    "KeyAction",
+    "LeftClickAction",
+    "LeftClickDragAction",
+    "LeftMouseDownAction",
+    "LeftMouseUpAction",
+    "MemoryCommand",
+    "MemoryCreateCommand",
+    "MemoryDeleteCommand",
+    "MemoryInsertCommand",
+    "MemoryRenameCommand",
+    "Memory_20250818",
+    "MiddleClickAction",
+    "MouseMoveAction",
+    "QueryParameters",
+    "Region",
+    "RightClickAction",
+    "ScreenshotAction",
+    "ScrollAction",
+    "StrReplaceBasedEditCommand",
+    "StrReplaceCommand",
+    "StrReplaceEditorCommand",
+    "TextEditorArgs",
+    "TextEditor_20241022",
+    "TextEditor_20250124",
+    "TextEditor_20250429",
+    "TextEditor_20250728",
+    "ToolSearchBM25_20251119",
+    "ToolSearchRegex_20251119",
+    "TripleClickAction",
+    "TypeAction",
+    "UndoEditCommand",
+    "ViewCommand",
+    "ViewRange",
+    "WaitAction",
+    "WebFetchCitationsConfig",
+    "WebFetchParameters",
+    "WebFetch_20250910",
+    "WebFetch_20250910_Args",
+    "WebSearchUserLocation",
+    "WebSearch_20250305",
+    "WebSearch_20250305_Args",
+    "ZoomAction",
+]

pyfect/ai/anthropic_structured_output.py

@@ -0,0 +1,138 @@
+"""Schemas as Anthropic structured output (Effect's
+``effect/ai/AnthropicStructuredOutput``).
+
+``to_codec_anthropic(schema)`` gives the JSON Schema to send to Anthropic
+and the codec decoding the model's output back into the schema's values.
+Shapes strict mode cannot express are sent in a provider-safe form the
+codec decodes: a tuple as an object with keys ``"0"``, ``"1"``, ... (its
+rest under ``"__rest__"``), an object with index signatures as an array of
+``[key, value]`` pairs, an optional key as a required nullable one, a
+``one_of`` union as ``anyOf``. Keywords Anthropic does not support are left
+out of the JSON Schema (an unsupported ``format`` becomes part of the
+description) and still checked by the codec. A recursive schema raises.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from pyfect.ai import _structured_output_json as J
+from pyfect.ai._structured_output_codec import StructuredOutputCodec, to_codec
+from pyfect.json_schema import Definitions, JsonSchema
+from pyfect.schema import Codec
+
+__all__ = ["StructuredOutputCodec", "to_codec_anthropic"]
+
+_SUPPORTED = frozenset(
+    {
+        "$ref",
+        "type",
+        "title",
+        "description",
+        "enum",
+        "const",
+        "anyOf",
+        "allOf",
+        "properties",
+        "required",
+        "additionalProperties",
+        "items",
+        "pattern",
+    }
+)
+_FORMATS = frozenset(
+    {"date-time", "time", "date", "duration", "email", "hostname", "uri", "ipv4", "ipv6", "uuid"}
+)
+
+
+def to_codec_anthropic[T, E, RD, RE](
+    schema: Codec[T, E, RD, RE], /
+) -> StructuredOutputCodec[T, RD, RE]:
+    """``schema``'s Anthropic JSON Schema and the codec of its output (see
+    the module); raises ``ValueError`` on a recursive schema."""
+    codec = to_codec(schema)
+    document = J.document(codec)
+    if _has_reference_cycle(document.schema, document.definitions):
+        raise ValueError("AnthropicStructuredOutput: Recursive schemas are not supported")
+    root = _rewrite(J.resolve_root(document))
+    return StructuredOutputCodec(codec, J.with_definitions(root, document.definitions, _rewrite))
+
+
+def _has_reference_cycle(root: JsonSchema, definitions: Definitions) -> bool:
+    visiting: set[int] = set()
+    visited: set[int] = set()
+
+    def visit(schema: JsonSchema) -> bool:
+        if id(schema) in visiting:
+            return True
+        if id(schema) in visited:
+            return False
+        visiting.add(id(schema))
+        cycle = False
+        for node in J.subschemas(schema):
+            ref = node.get("$ref")
+            if isinstance(ref, str):
+                target = root if ref == "#" else J.resolve_reference(ref, definitions)
+                if visit(target):
+                    cycle = True
+                    break
+        visiting.discard(id(schema))
+        visited.add(id(schema))
+        return cycle
+
+    return visit(root)
+
+
+def _rewrite(schema: JsonSchema) -> JsonSchema:
+    return J.walk(schema, _rewrite_node)
+
+
+def _rewrite_node(schema: JsonSchema) -> JsonSchema:
+    normalized = _hoist_all_of_descriptions(schema)
+    out: JsonSchema = {}
+    unsupported_format: str | None = None
+    for key, value in normalized.items():
+        if key == "format":
+            if (
+                isinstance(value, str)
+                and value in _FORMATS
+                and normalized.get("type") in (None, "string")
+            ):
+                out["format"] = value
+            elif isinstance(value, str):
+                unsupported_format = value
+        elif key in _SUPPORTED and (key != "additionalProperties" or value is False):
+            out[key] = value
+    if unsupported_format is not None:
+        J.append_description(out, f"a value with a format of {unsupported_format}")
+    return out
+
+
+def _hoist_all_of_descriptions(schema: JsonSchema) -> JsonSchema:
+    """``allOf`` members' descriptions joined to the schema's, their first
+    ``format`` and ``title`` moved up when the schema has none."""
+    members_in = schema.get("allOf")
+    if not isinstance(members_in, list):
+        return schema
+    out: JsonSchema = {key: value for key, value in schema.items() if key != "allOf"}
+    members: list[JsonSchema] = []
+    for member in cast("list[object]", members_in):
+        if not J.is_json_schema(member):
+            continue
+        rest: JsonSchema = {
+            k: v for k, v in member.items() if k not in ("description", "format", "title")
+        }
+        if schema.get("type") not in (None, "string"):
+            rest.pop("pattern", None)
+        description, format, title = (member.get(k) for k in ("description", "format", "title"))
+        if isinstance(description, str):
+            J.append_description(out, description)
+        if "format" not in out and isinstance(format, str):
+            out["format"] = format
+        if "title" not in out and isinstance(title, str):
+            out["title"] = title
+        if rest:
+            members.append(rest)
+    if members:
+        out["allOf"] = members
+    return out