Tool#

class scikitplot.agent.Tool(name, function, description='', parameters=None, effect=ToolEffect.READ, scopes=frozenset({}), cost=1.0, idempotent=None)[source]#

One callable tool and the facts the gate chain decides on.

Parameters:

namestr: 1 to 64 characters, [A-Za-z_][A-Za-z0-9_-]*: the name a planner uses to call it.
functioncallable: Called with the validated arguments as keyword arguments. It must return a JSON value (see plain); anything else is reported as tool_result_not_json.
descriptionstr, default=””: What the tool does, for the planner.
parametersmapping or None, default=None: The JSON Schema of the arguments, in the subset of scikitplot.agent._schema; its root is a closed object. None is a tool without arguments.
effectToolEffect or str, default=”read”: Its kind of effect.
scopesiterable of str, default=(): Scopes a policy must grant before the tool runs ("corpus:read").
costfloat, default=1.0: Budget units one call costs, in the caller’s unit (Budget gate).
idempotentbool or None, default=None: Whether a call may be repeated with the same effect. None is True for a read tool and False otherwise. A call of a non-idempotent tool that was in flight when a run stopped is not repeated at resume (tool_interrupted).

Raises:

TypeError: If a field has the wrong type.
ValueError: If name or a scope is malformed, or cost is negative or not finite.
SchemaError: If parameters is outside the supported subset, or does not fit the function’s signature: a property the function cannot take as a keyword, or a parameter without a default that the schema does not require.

Parameters:

name (str)
function (Callable[[...], Any])
description (str)
parameters (Mapping[str, Any] | None)
effect (ToolEffect)
scopes (frozenset[str])
cost (float)
idempotent (bool | None)

Examples

>>> from scikitplot.agent import Tool
>>> def add(a, b=0):
...     return a + b
>>> tool = Tool(
...     "add",
...     add,
...     parameters={
...         "type": "object",
...         "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
...         "required": ["a"],
...         "additionalProperties": False,
...     },
... )
>>> tool.effect.value, tool.idempotent
('read', True)

cost: float = 1.0#

describe()[source]#

Return what a planner needs to call this tool, as JSON.

Return type:: dict[str, Any]

description: str = ''#

effect: ToolEffect = 'read'[source]#

function: Callable[[...], Any][source]#

idempotent: bool | None = None#

name: str[source]#

parameters: Mapping[str, Any] | None = None#

scopes: frozenset[str] = frozenset({})#