Repository navigation
Expand file tree
/
Copy pathtool_surface.py
More file actions
152 lines (118 loc) · 5.46 KB
/
Copy pathtool_surface.py
File metadata and controls
152 lines (118 loc) · 5.46 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
"""How an agent's tools reach the model.
``list_tools()`` returns the tool definitions sent to the model. With programmatic tool calling
(PTC) most tools are not in that list: they are Python functions described inside the code tool.
``ToolSurface`` records every tool the model can reach and how it reaches it, so tool listings
can show what is in context and why. Future exposure kinds (for example tools that are only
discoverable through search) are still programmatic: ``SurfaceTool.deferred`` records that their
definition is not in the code tool's description.
"""
from __future__ import annotations
import json
import math
from dataclasses import dataclass
from enum import StrEnum
from typing import TYPE_CHECKING, Literal, Protocol, runtime_checkable
if TYPE_CHECKING:
from collections.abc import Sequence
from mcp_types import ListToolsResult, Tool
CHARS_PER_TOKEN = 4
"""Rough characters-per-token ratio used for context estimates."""
LARGE_STUB_TOKENS = 500
"""Programmatic function stubs at or above this estimate are flagged as large."""
class ToolExposure(StrEnum):
MODEL = "model"
"""The tool definition is sent to the model with each request."""
PROGRAMMATIC = "programmatic"
"""Callable only from the PTC code tool. Its stub is part of that tool's description unless
``SurfaceTool.deferred``: then it is discoverable through ``search_tools`` instead."""
def estimate_tokens(text: str) -> int:
"""Return a rough token estimate for ``text``."""
return math.ceil(len(text) / CHARS_PER_TOKEN)
def tool_definition_tokens(tool: Tool) -> int:
"""Estimate the context used by a tool definition sent to the model."""
schema = json.dumps(tool.input_schema, separators=(",", ":"), ensure_ascii=False)
return estimate_tokens(f"{tool.name}{tool.description or ''}{schema}")
@dataclass(frozen=True, slots=True)
class SurfaceTool:
tool: Tool
exposure: ToolExposure
context_tokens: int
"""Estimated tokens this tool adds to the model context."""
direct_reason: str | None = None
"""Why a tool stays directly callable while PTC is enabled."""
python_name: str | None = None
signature: str | None = None
stub: str | None = None
deferred: bool = False
"""A programmatic function whose stub is not in the code tool's description; sandbox code
can still call it, and ``search_tools`` or a ``^tool:`` mention reveals its definition."""
stub_tokens: int = 0
"""Estimated tokens of the function's stub, whether upfront or loaded on demand."""
source: str | None = None
"""Source group of a programmatic function: an MCP server name, ``card``, ``agents``,
``local`` or ``builtin``."""
seen: bool = False
"""Whether this deferred function's signature is in the retained conversation."""
@property
def large(self) -> bool:
return (
self.exposure is ToolExposure.PROGRAMMATIC
and not self.deferred
and self.context_tokens >= LARGE_STUB_TOKENS
)
def matches(self, name: str) -> bool:
return name in (self.tool.name, self.python_name)
@dataclass(frozen=True, slots=True)
class ProgrammaticSurface:
"""Settings and model-facing instructions of the PTC code tool."""
tool_name: str
vocabulary: int
tool_format: Literal["json", "freeform"]
instructions: str
type_check: bool
max_duration_seconds: float
max_memory_mb: int
search_active: bool = False
"""Whether some functions are deferred behind ``search_tools``."""
retired: frozenset[str] = frozenset()
"""Python names assigned earlier in the conversation whose tools are gone."""
@dataclass(frozen=True, slots=True)
class ToolSurface:
tools: tuple[SurfaceTool, ...]
programmatic: ProgrammaticSurface | None = None
@classmethod
def direct(cls, tools: Sequence[Tool]) -> ToolSurface:
"""Build the surface of an agent whose tools are all sent to the model."""
return cls(
tools=tuple(
SurfaceTool(
tool=tool,
exposure=ToolExposure.MODEL,
context_tokens=tool_definition_tokens(tool),
)
for tool in tools
)
)
def exposed(self, exposure: ToolExposure) -> list[SurfaceTool]:
return [tool for tool in self.tools if tool.exposure is exposure]
def programmatic_functions(self, *, deferred: bool | None = None) -> list[SurfaceTool]:
"""Programmatic functions, optionally only the upfront (``False``) or deferred ones."""
return [
tool
for tool in self.exposed(ToolExposure.PROGRAMMATIC)
if deferred is None or tool.deferred is deferred
]
def find(self, name: str) -> SurfaceTool | None:
"""Find a tool by its tool name or, for programmatic tools, its Python name."""
return next((tool for tool in self.tools if tool.matches(name)), None)
@runtime_checkable
class ToolSurfaceProvider(Protocol):
"""Optional capability for agents whose callable tools differ from their model tools."""
async def tool_surface(self) -> ToolSurface: ...
class ToolLister(Protocol):
async def list_tools(self) -> ListToolsResult: ...
async def resolve_tool_surface(agent: ToolLister) -> ToolSurface:
"""Return the agent's tool surface, treating plain agents as all-direct."""
if isinstance(agent, ToolSurfaceProvider):
return await agent.tool_surface()
return ToolSurface.direct((await agent.list_tools()).tools)