<?php
namespace Nibiru\Module\Ai\Plugins;

/**
 * Base class for an Agent tool. Extend this to expose any PHP capability
 * to the Nibiru agent runtime.
 *
 * A tool has three things:
 *   - a `name()` — the agent calls it by this name
 *   - a `schema()` — JSON-schema-like description of inputs (drives the
 *     agent's tool-call decoding)
 *   - an `execute($args)` — the actual implementation, returning a string
 *     (or scalar) that the agent will read back as observation.
 *
 * Built-in tools live alongside this file: PdoQuery, HttpGet, ViewAssign,
 * FormBuild, FileRead. You can write your own and pass them in via
 * Agent::withTools([...]).
 */
abstract class Tool
{
    abstract public function name(): string;

    abstract public function description(): string;

    /**
     * @return array<string, array{type:string, description:string, required?:bool}>
     */
    abstract public function schema(): array;

    /**
     * Run the tool. Return a string (or scalar) — the agent will pass
     * this string back into the LLM as a tool observation.
     */
    abstract public function execute(array $args): mixed;

    /**
     * Render the tool definition as the agent's prompt sees it.
     */
    public function asPrompt(): string
    {
        $schema = $this->schema();
        $args = [];
        foreach ($schema as $key => $def) {
            $args[] = "  - $key ({$def['type']}): " . ($def['description'] ?? '');
        }
        return sprintf(
            "Tool: %s\nWhat it does: %s\nArguments:\n%s",
            $this->name(),
            $this->description(),
            implode("\n", $args)
        );
    }
}