clientx 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
clientx/_tools.py ADDED
@@ -0,0 +1,440 @@
1
+ """Describe a client's endpoints as tools a model can call.
2
+
3
+ ``list_tools(client)`` returns one ``Tool`` per endpoint on the client and the
4
+ resources mounted on it: a name, a description, a JSON Schema of its arguments
5
+ and of its result, hints from its HTTP method, its tags, and ``call()`` or
6
+ ``acall()``.
7
+ Nothing here depends on an AI library, so an adapter for MCP or another
8
+ framework can build on it.
9
+
10
+ - Names: the attribute path from the client, joined with ``_``, so
11
+ ``api.users.create`` is ``users_create``. An endpoint's second name in its
12
+ class is left out: it's the same endpoint.
13
+ - Left out: an endpoint that streams (``-> Iterator[...]`` or
14
+ ``stream=True``), returns the raw ``Response``, or has an argument with no
15
+ JSON form, such as a binary file. A model can't use them well.
16
+ - Descriptions: the docstring, up to its first section (``Args:``,
17
+ ``Returns:``...), or else the method and path. An argument's description is
18
+ its helper's ``description=``, or else its entry in the docstring's
19
+ ``Args:``.
20
+ - Schemas: arguments are named as in the method, not by their helpers'
21
+ aliases. Pydantic's ``title`` on each property is left out, and a model or
22
+ ``type`` alias is written in place rather than behind a ``$ref``, unless it
23
+ refers to itself.
24
+ - Calls: a model's arguments are validated as Pydantic validates a call,
25
+ leniently, so ``"7"`` fits an ``int``. Only the arguments the model gave are
26
+ passed, so a default stays a default, as ``Send(exclude_unset=True)`` and a
27
+ JSON field's ``None`` need. The result is JSON-ready data.
28
+ - Errors: a failed call raises ``ToolError``, with a message written for a
29
+ model and the original error as its cause. HTTP errors name the method and
30
+ path template, never the host or query string, which can hold credentials.
31
+ """
32
+
33
+ from __future__ import annotations
34
+
35
+ import inspect
36
+ import re
37
+ from collections.abc import Callable, Generator, Mapping, Sequence
38
+ from contextlib import contextmanager
39
+ from dataclasses import dataclass, field
40
+ from types import NoneType
41
+ from typing import TYPE_CHECKING, Any, cast
42
+
43
+ import httpx2
44
+ from pydantic import ConfigDict, PydanticSchemaGenerationError, TypeAdapter, ValidationError
45
+ from pydantic.errors import PydanticInvalidForJsonSchema
46
+
47
+ from clientx._registry import endpoint_for
48
+ from clientx.exceptions import ArgumentError, ToolError
49
+
50
+ if TYPE_CHECKING:
51
+ from clientx._client import AsyncClientX, ClientX
52
+ from clientx._endpoint import Endpoint
53
+ from clientx._signature import ParameterInfo
54
+
55
+
56
+ # --- Entry point --------------------------------------------------------------
57
+ def list_tools(client: ClientX | AsyncClientX) -> list[Tool]:
58
+ """Return a tool for each endpoint a model can call, resources' included.
59
+
60
+ Every endpoint on the client and the resources mounted on it is a tool,
61
+ named by its attribute path (``users_create``), except one a model can't
62
+ use well:
63
+
64
+ - one that streams, annotated ``-> Iterator[...]`` or with
65
+ ``stream=True``;
66
+ - one that returns the raw ``Response``: annotate what the API returns
67
+ instead, such as a model or ``dict[str, Any]``;
68
+ - one with an argument that has no JSON form, such as a binary file.
69
+
70
+ An endpoint's second name in its class is listed once.
71
+ """
72
+ tools: list[Tool] = []
73
+ _collect(client, "", tools, set())
74
+ return tools
75
+
76
+
77
+ def _collect(owner: object, prefix: str, tools: list[Tool], seen: set[int]) -> None:
78
+ """Add a tool for each endpoint on ``owner``, then on its resources.
79
+
80
+ ``seen`` holds each endpoint met so far, by ``id``, so an endpoint's second
81
+ name is left out.
82
+ """
83
+ for name, value in _members(type(owner)).items():
84
+ endpoint = endpoint_for(value)
85
+ if endpoint is not None and id(endpoint) not in seen:
86
+ seen.add(id(endpoint))
87
+ tool = _tool(prefix + name, endpoint, getattr(owner, name))
88
+ if tool is not None:
89
+ tools.append(tool)
90
+ elif hasattr(type(value), "__clientx_prefix__"): # A mounted resource.
91
+ _collect(getattr(owner, name), f"{prefix}{name}_", tools, seen)
92
+
93
+
94
+ def _members(cls: type) -> dict[str, object]:
95
+ """Return the attributes ``cls`` and its parents define, in class order."""
96
+ members: dict[str, object] = {}
97
+ for class_ in reversed(cls.__mro__):
98
+ members.update(vars(class_))
99
+ return members
100
+
101
+
102
+ # --- Tools --------------------------------------------------------------------
103
+ @dataclass(frozen=True, kw_only=True)
104
+ class Tool:
105
+ """An endpoint described for a model, and called with a model's arguments.
106
+
107
+ Attributes:
108
+ name: The attribute path from the client, joined with ``_``.
109
+ description: What the endpoint does, from its docstring.
110
+ input_schema: The JSON Schema of the arguments: an object with one
111
+ property per parameter, named as in the method.
112
+ output_schema: The JSON Schema of the result, or ``None`` for an
113
+ endpoint annotated ``-> None``.
114
+ read_only: The endpoint only reads: ``GET``, ``HEAD`` or ``OPTIONS``.
115
+ destructive: It can change or delete what's there: ``PUT``,
116
+ ``PATCH`` or ``DELETE``.
117
+ idempotent: Calling it twice has the effect of calling it once:
118
+ ``GET``, ``HEAD``, ``OPTIONS``, ``PUT`` or ``DELETE``.
119
+ tags: The endpoint's tags, its resource's first, to choose which tools
120
+ to register by.
121
+ is_async: It's an ``async def`` endpoint, called with ``acall()``.
122
+ """
123
+
124
+ name: str
125
+ description: str
126
+ input_schema: dict[str, Any]
127
+ output_schema: dict[str, Any] | None
128
+ read_only: bool
129
+ destructive: bool
130
+ idempotent: bool
131
+ tags: tuple[str, ...]
132
+ is_async: bool
133
+ _call: _Call = field(repr=False, compare=False)
134
+
135
+ def call(self, arguments: Mapping[str, Any] | None = None) -> Any:
136
+ """Call the endpoint with a model's arguments; return JSON-ready data.
137
+
138
+ Raises:
139
+ ToolError: If the arguments don't fit, the request can't be sent or
140
+ fails, or the response doesn't fit the endpoint's annotation.
141
+ TypeError: If the endpoint is ``async def``: use ``acall()``.
142
+ """
143
+ if self.is_async:
144
+ raise TypeError(f"Tool {self.name!r} is an async def endpoint: call it with acall().")
145
+ args, kwargs = self._call.arguments(self.name, arguments)
146
+ with self._call.errors(self.name):
147
+ result = self._call.function(*args, **kwargs)
148
+ return self._call.dump(result)
149
+
150
+ async def acall(self, arguments: Mapping[str, Any] | None = None) -> Any:
151
+ """Call the ``async def`` endpoint with a model's arguments.
152
+
153
+ Raises:
154
+ ToolError: As for ``call()``.
155
+ TypeError: If the endpoint is a plain ``def``: use ``call()``.
156
+ """
157
+ if not self.is_async:
158
+ raise TypeError(f"Tool {self.name!r} is a def endpoint: call it with call().")
159
+ args, kwargs = self._call.arguments(self.name, arguments)
160
+ with self._call.errors(self.name):
161
+ result = await self._call.function(*args, **kwargs)
162
+ return self._call.dump(result)
163
+
164
+
165
+ @dataclass(frozen=True)
166
+ class _Call:
167
+ """What a tool needs to call its endpoint and report on it."""
168
+
169
+ function: Callable[..., Any]
170
+ adapter: TypeAdapter[dict[str, Any]]
171
+ output: TypeAdapter[Any] | None
172
+ positional: tuple[ParameterInfo, ...]
173
+ request: str # The method and path template, for messages: "POST /users".
174
+
175
+ def arguments(self, name: str, arguments: Mapping[str, Any] | None) -> tuple[list[Any], dict[str, Any]]:
176
+ """Return the validated arguments the model gave, to call with.
177
+
178
+ A positional-only parameter is passed by position, so one the model
179
+ left out before one it gave gets its default.
180
+
181
+ Raises:
182
+ ToolError: If the arguments don't fit the endpoint's parameters.
183
+ """
184
+ given = dict(arguments or {})
185
+ try:
186
+ validated = self.adapter.validate_python(given)
187
+ except ValidationError as error:
188
+ raise ToolError(
189
+ f"The arguments don't fit {name}: {_problems(error, values=True)}. Nothing was sent.", tool=name
190
+ ) from error
191
+ last = max((index for index, parameter in enumerate(self.positional) if parameter.name in given), default=-1)
192
+ args = [validated.get(parameter.name, parameter.default) for parameter in self.positional[: last + 1]]
193
+ positional_names = {parameter.name for parameter in self.positional}
194
+ kwargs = {key: value for key, value in validated.items() if key in given and key not in positional_names}
195
+ return args, kwargs
196
+
197
+ @contextmanager
198
+ def errors(self, name: str) -> Generator[None]:
199
+ """Raise ``ToolError`` for what can go wrong in a call, with its cause.
200
+
201
+ An HTTP error shows the API's own answer, truncated, as it often says
202
+ what to fix.
203
+ """
204
+ try:
205
+ yield
206
+ except ArgumentError as error:
207
+ raise ToolError(f"{name} couldn't send its request: {error}", tool=name) from error
208
+ except httpx2.HTTPStatusError as error:
209
+ response = error.response
210
+ message = f"{name}: the API answered {response.status_code} {response.reason_phrase} to {self.request}"
211
+ body = response.text.strip()
212
+ raise ToolError(f"{message}: {_truncated(body)}" if body else f"{message}.", tool=name) from error
213
+ except httpx2.RequestError as error:
214
+ raise ToolError(
215
+ f"{name}: the request to {self.request} failed before the API answered ({type(error).__name__}).",
216
+ tool=name,
217
+ ) from error
218
+ except ValidationError as error:
219
+ raise ToolError(
220
+ f"{name}: the API's answer to {self.request} doesn't fit the endpoint's return annotation: "
221
+ f"{_problems(error, values=False)}.",
222
+ tool=name,
223
+ ) from error
224
+
225
+ def dump(self, result: Any) -> Any:
226
+ """Return the endpoint's result as JSON-ready data."""
227
+ return None if self.output is None else self.output.dump_python(result, mode="json")
228
+
229
+
230
+ # --- Building a tool ----------------------------------------------------------
231
+ # What each HTTP method implies, for the hints. POST is in none of them: it
232
+ # usually adds something, so it's neither read-only nor idempotent, and not
233
+ # destructive either, which is for replacing or removing what's there.
234
+ _READ_ONLY = frozenset({"GET", "HEAD", "OPTIONS"})
235
+ _IDEMPOTENT = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
236
+ _DESTRUCTIVE = frozenset({"PUT", "PATCH", "DELETE"})
237
+
238
+
239
+ def _tool(name: str, endpoint: Endpoint, function: Callable[..., Any]) -> Tool | None:
240
+ """Return the tool for an endpoint, or ``None`` if a model can't use it."""
241
+ returns = endpoint.signature.returns
242
+ if endpoint.stream or returns.base_type is httpx2.Response:
243
+ return None
244
+ parameters = endpoint.signature.parameters[1:]
245
+ try:
246
+ adapter = _arguments_adapter(parameters)
247
+ input_schema = _compact(adapter.json_schema(by_alias=False))
248
+ returns_nothing = returns.base_type is None or returns.base_type is NoneType
249
+ output = None if returns_nothing else TypeAdapter[Any](returns.annotation)
250
+ output_schema = None if output is None else _compact(output.json_schema(mode="serialization"))
251
+ except (PydanticSchemaGenerationError, PydanticInvalidForJsonSchema):
252
+ return None
253
+ doc = inspect.cleandoc(endpoint.signature.doc or "")
254
+ argument_docs = _argument_docs(doc)
255
+ for parameter_name, schema in input_schema.get("properties", {}).items():
256
+ if "description" not in schema and parameter_name in argument_docs:
257
+ schema["description"] = argument_docs[parameter_name]
258
+ request = f"{endpoint.method} {endpoint.raw_path or '/'}"
259
+ positional = tuple(p for p in parameters if p.kind is inspect.Parameter.POSITIONAL_ONLY)
260
+ return Tool(
261
+ name=name,
262
+ description=_description(doc) or request,
263
+ input_schema=input_schema,
264
+ output_schema=output_schema,
265
+ read_only=endpoint.method in _READ_ONLY,
266
+ destructive=endpoint.method in _DESTRUCTIVE,
267
+ idempotent=endpoint.method in _IDEMPOTENT,
268
+ tags=tuple(endpoint.tags),
269
+ is_async=endpoint.signature.is_async,
270
+ _call=_Call(function, adapter, output, positional, request),
271
+ )
272
+
273
+
274
+ # Validates arguments by parameter name: a helper's alias is the name sent to
275
+ # the API, not the one a caller uses.
276
+ _BY_NAME = ConfigDict(validate_by_name=True, validate_by_alias=False)
277
+
278
+
279
+ def _arguments_adapter(parameters: Sequence[ParameterInfo]) -> TypeAdapter[dict[str, Any]]:
280
+ """Return a validator of a model's arguments for these parameters.
281
+
282
+ It validates a call to a stand-in with the endpoint's parameters, all
283
+ keyword-only so a mapping fills them, and returns the arguments: the
284
+ endpoint is called separately, so a response that doesn't fit isn't taken
285
+ for arguments that don't.
286
+ """
287
+
288
+ def arguments(**values: Any) -> dict[str, Any]:
289
+ return values
290
+
291
+ arguments.__signature__ = inspect.Signature( # pyright: ignore[reportFunctionMemberAccess]
292
+ [
293
+ inspect.Parameter(p.name, inspect.Parameter.KEYWORD_ONLY, default=p.default, annotation=p.annotation)
294
+ for p in parameters
295
+ ]
296
+ )
297
+ arguments.__annotations__ = {p.name: p.annotation for p in parameters}
298
+ # Pydantic validates a call to a function, which its types don't allow.
299
+ return TypeAdapter[dict[str, Any]](cast("Any", arguments), config=_BY_NAME)
300
+
301
+
302
+ # --- Error messages -----------------------------------------------------------
303
+ # How much of an error response's body a message shows.
304
+ _BODY_LIMIT = 2000
305
+
306
+
307
+ def _truncated(text: str) -> str:
308
+ if len(text) <= _BODY_LIMIT:
309
+ return text
310
+ return f"{text[:_BODY_LIMIT]}... ({len(text) - _BODY_LIMIT} more characters)"
311
+
312
+
313
+ def _problems(error: ValidationError, *, values: bool) -> str:
314
+ """Return each of Pydantic's errors as ``where: what``, without its URL.
315
+
316
+ With ``values``, a value that's there but doesn't fit is shown too, short:
317
+ it's the model's own argument. A response's values aren't.
318
+ """
319
+ problems: list[str] = []
320
+ for problem in error.errors(include_url=False, include_context=False):
321
+ where = ".".join(str(part) for part in problem["loc"]) or "the arguments"
322
+ # A missing argument is reported as keyword-only, as the stand-in's are.
323
+ if problem["type"].startswith("missing"):
324
+ problems.append(f"{where}: is required")
325
+ continue
326
+ text = f"{where}: {problem['msg']}"
327
+ if values:
328
+ text += f" (got {problem['input']!r:.80})"
329
+ problems.append(text)
330
+ return "; ".join(problems)
331
+
332
+
333
+ # --- Descriptions -------------------------------------------------------------
334
+ # A Google-style section header, which ends a docstring's description.
335
+ _SECTION = re.compile(
336
+ r"(Args|Arguments|Attributes|Example|Examples|Note|Notes|Raises|Returns|See Also|Warning|Warnings|Yields):"
337
+ )
338
+ # An argument's entry in ``Args:``: "name: text", or "name (type): text".
339
+ _ENTRY = re.compile(r"\*{0,2}(?P<name>\w+)(?:\s*\([^)]*\))?:\s*(?P<text>.*)")
340
+
341
+
342
+ def _description(doc: str) -> str:
343
+ """Return a docstring up to its first section, such as ``Args:``."""
344
+ lines = doc.splitlines()
345
+ end = next((index for index, line in enumerate(lines) if _SECTION.fullmatch(line.strip())), len(lines))
346
+ return "\n".join(lines[:end]).strip()
347
+
348
+
349
+ def _argument_docs(doc: str) -> dict[str, str]:
350
+ """Return each argument's description from a docstring's ``Args:``.
351
+
352
+ An entry's continuation lines, indented further, are joined to it.
353
+ """
354
+ lines = doc.splitlines()
355
+ start = next((index + 1 for index, line in enumerate(lines) if line.strip() in {"Args:", "Arguments:"}), None)
356
+ if start is None:
357
+ return {}
358
+ docs: dict[str, str] = {}
359
+ entry_indent: int | None = None
360
+ current: str | None = None
361
+ for line in lines[start:]:
362
+ if not line.strip():
363
+ continue
364
+ indent = len(line) - len(line.lstrip())
365
+ if indent == 0:
366
+ break
367
+ entry_indent = indent if entry_indent is None else entry_indent
368
+ if indent == entry_indent:
369
+ match = _ENTRY.fullmatch(line.strip())
370
+ if match is None:
371
+ current = None
372
+ continue
373
+ name: str = match["name"]
374
+ docs[name], current = match["text"], name
375
+ elif current is not None:
376
+ docs[current] = f"{docs[current]} {line.strip()}".strip()
377
+ return docs
378
+
379
+
380
+ # --- Compact schemas ----------------------------------------------------------
381
+ # Keys whose value maps names to schemas, not a schema itself.
382
+ _SCHEMA_MAPS = frozenset({"$defs", "patternProperties", "properties"})
383
+ # Keys whose value is data, not a schema, so it's kept as it is.
384
+ _DATA = frozenset({"const", "default", "enum", "examples"})
385
+
386
+
387
+ def _compact(schema: dict[str, Any]) -> dict[str, Any]:
388
+ """Return a JSON Schema without titles, with each ``$ref`` written in place.
389
+
390
+ A definition that refers to itself, directly or not, can't be written in
391
+ place, so it stays in ``$defs``, and so do the references to it.
392
+ """
393
+ definitions: dict[str, Any] = schema.get("$defs", {})
394
+ kept: dict[str, Any] = {}
395
+ compact = _inline({k: v for k, v in schema.items() if k != "$defs"}, definitions, frozenset(), kept)
396
+ pending = [name for name in kept if kept[name] is None]
397
+ while pending:
398
+ for name in pending:
399
+ kept[name] = _inline(definitions[name], definitions, frozenset({name}), kept)
400
+ pending = [name for name in kept if kept[name] is None]
401
+ if kept:
402
+ compact["$defs"] = kept
403
+ return compact
404
+
405
+
406
+ def _inline(node: Any, definitions: dict[str, Any], stack: frozenset[str], kept: dict[str, Any]) -> Any:
407
+ """Return ``node`` with titles left out and references written in place.
408
+
409
+ ``stack`` holds the definitions being written in place around ``node``: a
410
+ reference to one of them is kept, and its name added to ``kept``.
411
+ """
412
+ if isinstance(node, list):
413
+ return [_inline(item, definitions, stack, kept) for item in node] # pyright: ignore[reportUnknownVariableType]
414
+ if not isinstance(node, dict):
415
+ return node
416
+ reference = node.get("$ref") # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
417
+ if isinstance(reference, str) and reference.startswith("#/$defs/"):
418
+ name = reference.removeprefix("#/$defs/")
419
+ others = {k: v for k, v in node.items() if k != "$ref"} # pyright: ignore[reportUnknownVariableType]
420
+ if name in stack:
421
+ kept.setdefault(name, None)
422
+ return {"$ref": reference, **_inline(others, definitions, stack, kept)}
423
+ return {
424
+ **_inline(definitions[name], definitions, stack | {name}, kept),
425
+ **_inline(others, definitions, stack, kept),
426
+ }
427
+ compact: dict[str, Any] = {}
428
+ for key, value in node.items(): # pyright: ignore[reportUnknownVariableType]
429
+ if key == "title":
430
+ continue
431
+ if key in _DATA:
432
+ compact[key] = value
433
+ elif key in _SCHEMA_MAPS and isinstance(value, dict):
434
+ compact[key] = {
435
+ sub_name: _inline(sub, definitions, stack, kept)
436
+ for sub_name, sub in value.items() # pyright: ignore[reportUnknownVariableType]
437
+ }
438
+ else:
439
+ compact[key] = _inline(value, definitions, stack, kept)
440
+ return compact