# Overview

`openai-resptools` is a small Python helper library for OpenAI Responses API tool calling:
- Register Python callables as OpenAI function tools
- Generate OpenAI-compatible JSON schema for tool parameters
- Run a tool-calling loop until the model returns final text

## Key concepts

### ToolRegistry

`ToolRegistry` is an in-memory registry of tools. It can:
- Register tools via `@registry.tool()`
- Auto-register public methods when subclassing `ToolRegistry`
- Emit the `tools=[...]` payload for `client.responses.create(...)`

Source: `../src/openai_resptools/registry.py`

### ToolDef

`ToolDef` is a single tool definition created from a callable:
- Builds a Pydantic args model from the callable signature/type hints
- Validates incoming arguments (dict) against that model
- Executes the callable
- Serializes results to JSON string for `function_call_output`

Source: `../src/openai_resptools/tool.py`

### ToolRunner

`ToolRunner` runs the standard Responses API tool-calling loop:
1. Send `input` and `tools` to `client.responses.create(...)`
2. Append the model output items into the running `input`
3. For each `function_call` item, validate+execute the matching tool
4. Append a `function_call_output` item with the same `call_id`
5. Repeat until the model returns no tool calls, then return final `output_text`

Source: `../src/openai_resptools/runner.py`

## Minimal mental model (Responses API)

This package assumes the Responses API returns output items that can include:
- `type == "function_call"` with fields like `name`, `arguments` (JSON string), and `call_id`

To respond to a tool call, you append an input item:

```json
{
  "type": "function_call_output",
  "call_id": "the-call-id-from-the-model",
  "output": "a JSON string"
}
```

Typing reference: `../src/openai_resptools/types.py`

