aimu.tools

In-process @tool decorator and cross-process MCPClient.

Decorator

aimu.tools.tool

tool(func: Callable) -> Callable

Mark a Python function as an AIMU tool.

Inspects the signature and docstring at decoration time and attaches an OpenAI-format tool spec to func.__tool_spec__. The function itself is unchanged and remains directly callable.

Each parameter must either have a type hint or a default value. Variadic parameters (*args / **kwargs) are not supported — declare each argument explicitly.

Supported parameter types: str, int, float, bool, list, dict, plus Optional[T] and T | None (which unwrap to the inner type).

A tool may be plain (def fn() -> T), async (async def fn() -> T), a generator (def fn(): yield ...; return T), or an async generator (async def fn(): yield ...). Generator and async-generator tools stream :class:~aimu.models.StreamChunk objects during execution — the agent forwards each yielded chunk through its own stream and treats the final yielded TOOL_CALLING chunk's content["response"] as the canonical tool result. The decorator sets discriminator attributes:

• func.__tool_is_async__ — True for async def or async def + yield.
• func.__tool_is_streaming__ — True for generator functions (sync or async).

Usage::

@tool
def letter_counter(word: str, letter: str) -> int:
    """Count occurrences of a letter in a word."""
    return word.lower().count(letter.lower())

agent = Agent(client, tools=[letter_counter])

aimu.tools.ToolSignatureError

Bases: TypeError

Raised by @tool when a function signature can't be converted to a tool spec.

MCP client

aimu.tools.MCPClient

MCPClient(config: Optional[dict] = None, server: Optional[FastMCP] = None, file: Optional[str] = None)

Synchronous wrapper around an async FastMCP Client.

Uses anyio's start_blocking_portal() to run the FastMCP Client in a background thread with a properly initialized anyio event loop.

Pass exactly one of config, server, or file. Connection errors are re-raised as :class:MCPConnectionError with the original exception chained.

ping

ping() -> list

Verify the connection is alive by listing tools. Returns the tool list.

Raises :class:MCPConnectionError if the connection has been closed or the server is unreachable.

aimu.tools.MCPConnectionError

Bases: RuntimeError

Raised when an :class:MCPClient fails to establish or use a connection.

Built-in tools

The aimu.tools.builtin module ships ready-made @tool functions grouped by domain:

Group	Tools
builtin.web	get_weather, get_webpage, search, wikipedia
builtin.fs	list_directory, read_file
builtin.compute	calculate
builtin.misc	echo, get_current_date_and_time
builtin.ALL_TOOLS	All of the above

aimu.tools.builtin.echo

echo(echo_string: str) -> str

Returns echo_string.

aimu.tools.builtin.get_current_date_and_time

get_current_date_and_time() -> str

Returns the current date and time.

aimu.tools.builtin.get_weather

get_weather(location: str) -> str

Returns the current weather for a given location.

Parameters:

Name	Type	Description	Default
location	str	City name or coordinates (e.g. "London", "48.8566,2.3522").	required

aimu.tools.builtin.calculate

calculate(expression: str) -> str

Evaluates a simple arithmetic expression and returns the result.

aimu.tools.builtin.get_webpage

get_webpage(url: str) -> str

Fetches a web page and returns its visible text content with HTML stripped.

Parameters:

Name	Type	Description	Default
url	str	The URL of the page to retrieve.	required

aimu.tools.builtin.search

search(query: str, num_results: int = 5) -> str

Search the web using a SearXNG instance and return the top results.

Parameters:

Name	Type	Description	Default
query	str	The search query string.	required
num_results	int	Number of results to return (default 5).	5

Set SEARXNG_BASE_URL env var to point to your SearXNG instance (or a .env file) (default: http://localhost:8080).

aimu.tools.builtin.wikipedia

wikipedia(query: str) -> str

Fetches a Wikipedia article summary for the given query.

Parameters:

Name	Type	Description	Default
query	str	Article title or search phrase (e.g. "Albert Einstein", "general relativity").	required

aimu.tools.builtin.list_directory

list_directory(path: str) -> str

Lists files and subdirectories at the given path.

Parameters:

Name	Type	Description	Default
path	str	Directory path to list.	required

aimu.tools.builtin.read_file

read_file(path: str, max_lines: int = 200) -> str

Reads a local file and returns its contents, capped at max_lines lines.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to read.	required
max_lines	int	Maximum number of lines to return (default 200).	200