README

OpenAPI reader tool for the adachsoft/ai-tool-call ecosystem.

This library exposes an AI tool that can read an OpenAPI 3 specification and provide high‑level information about available endpoints, detailed endpoint descriptions, schemas and simple search capabilities. Local specification files are always accessed through a filesystem sandbox defined by configuration.

Installation

composer require adachsoft/open-api-reader-tool

This will also install its runtime dependencies:

• adachsoft/open-api-reader – low‑level OpenAPI 3 parser
• adachsoft/ai-tool-call – SPI for tool definition and execution
• guzzlehttp/guzzle – HTTP client for fetching remote OpenAPI documents
• adachsoft/sandbox-contracts – filesystem sandbox contracts used to scope file access

Configuration

The tool is created via OpenApiToolFactory and expects a configuration map (ConfigMap) that contains at least the base_path key:

use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use AdachSoft\OpenApiReaderTool\OpenApiToolFactory;

$factory = new OpenApiToolFactory();

$config = new ConfigMap([
    'base_path' => __DIR__ . '/specs', // sandbox root for local OpenAPI files
]);

$tool = $factory->create($config);

The base_path value is used to build a sandbox (SandboxPath) coming from adachsoft/sandbox-contracts. Every local file path passed to the tool is resolved within this sandbox; attempts to escape it (e.g. using ..) are rejected.

Tool definition

The exported tool is named openapi_reader and exposes one required parameter action plus a set of optional parameters depending on the chosen action.

Parameters

• spec_path_or_url (string, optional)
  • Path to a local OpenAPI file inside the sandbox base_path, or an absolute URL to an OpenAPI document.
• action (string, required)
  • One of:
    • list_endpoints – list endpoints in a paginated way
    • endpoint_details – show details for a specific endpoint
    • schema – fetch a schema definition from components
    • search – perform a simple text search over endpoints
• page (integer, optional)
  • Page number for list_endpoints (default is 1).
• limit (integer, optional)
  • Page size for list_endpoints (default is 10, maximum is 100).
• path (string, optional)
  • OpenAPI path of the endpoint (e.g. /users/{id}), used with endpoint_details.
• method (string, optional)
  • HTTP method of the endpoint (e.g. GET, POST), used with endpoint_details.
• schema_name (string, optional)
  • Name of the schema in OpenAPI components, used with schema.
• query (string, optional)
  • Free‑text search query, used with search.

Basic usage example

The exact integration depends on how you wire tools in your AI orchestration. Below is a minimal, framework‑agnostic example of a single tool call:

use AdachSoft\AiToolCall\SPI\Collection\KeyValueMap;
use AdachSoft\AiToolCall\SPI\Dto\ToolCallRequestDto;
use AdachSoft\OpenApiReaderTool\OpenApiTool;
use AdachSoft\OpenApiReaderTool\OpenApiToolFactory;

$factory = new OpenApiToolFactory();
$tool = $factory->create(new ConfigMap([
    'base_path' => __DIR__ . '/specs',
]));

$request = new ToolCallRequestDto(
    'openapi_reader',
    new KeyValueMap([
        'spec_path_or_url' => 'openapi.yaml',
        'action' => 'list_endpoints',
        'page' => 1,
        'limit' => 10,
    ]),
);

$result = $tool->callTool($request);

// $result->result is a KeyValueMap with key "data" holding the returned array
$endpoints = $result->result->get('data');

Security and sandboxing

All local file accesses are performed relative to the configured base_path using adachsoft/sandbox-contracts. This means:

• the tool cannot read files outside the sandbox root,
• invalid or escaping paths result in clear InvalidToolCallException errors,
• remote documents are fetched only via HTTP(S) using Guzzle.

License

This library is released under the MIT License.