forked from NuQloud/nc-talk-ai
Pascal Kienast
0739d3da6a
Talk AI is a multi-bot AI assistant manager for Nextcloud Talk: per-bot prompts and models, agentic tool calling (MCP + built-in tools), RAG over Nextcloud files, room-document search, vision and speech-to-text attachments, persistent bot wikis, approval workflows, rate limiting, and multi-provider LLM support (any OpenAI-compatible endpoint). Developed within EDUC - the European Digital UniverCity (https://educalliance.eu), where it runs as the 'EDUC AI' assistant on the alliance-wide Nextcloud portal. This public repository is the upstream point of truth; deployment-specific tools plug in via the tool-provider extension point (docs/TOOL_PROVIDERS.md). License: AGPL-3.0-or-later.
76 lines
2.8 KiB
PHP
76 lines
2.8 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\EducAI\ToolProvider;
|
|
|
|
/**
|
|
* Extension point for agent tools.
|
|
*
|
|
* Implementations contribute additional name-based ("built-in style") tools to
|
|
* the agent loop without the core app knowing about them. Providers are
|
|
* collected via {@see CollectToolProvidersEvent}, so other Nextcloud apps can
|
|
* register their own tools by listening to that event.
|
|
*
|
|
* Tool definitions returned by {@see IToolProvider::getTools()} use the same
|
|
* shape as the core built-in tools:
|
|
*
|
|
* [
|
|
* 'name' => 'my_tool', // unique tool name (snake_case)
|
|
* 'description' => '...', // LLM-facing description
|
|
* 'schema' => [...], // JSON schema for the arguments
|
|
* 'policy' => [...], // execution policy, see ToolExecutionPolicyService
|
|
* 'label' => 'My Tool', // optional human-readable UI label
|
|
* 'summary' => 'One-line UI summary', // optional UI description
|
|
* ]
|
|
*/
|
|
interface IToolProvider {
|
|
/**
|
|
* Return the tool definitions this provider currently offers.
|
|
*
|
|
* May return an empty array when the provider is not configured/enabled.
|
|
* This is called when assembling the tool loadout for a bot and when
|
|
* listing available tools in the UI.
|
|
*
|
|
* @return array<int,array<string,mixed>>
|
|
*/
|
|
public function getTools(): array;
|
|
|
|
/**
|
|
* Whether this provider can execute the given tool name.
|
|
*
|
|
* Should also return true for legacy alias names the provider still
|
|
* accepts, even if they are no longer advertised via getTools().
|
|
*/
|
|
public function providesTool(string $toolName): bool;
|
|
|
|
/**
|
|
* Execute one of this provider's tools.
|
|
*
|
|
* @param array<string,mixed> $arguments Arguments passed by the model
|
|
* @param array<string,mixed> $config Per-bot tool configuration
|
|
* @return array{content:array<int,array{type:string,text:string}>,isError:bool}
|
|
* @throws \Exception If the tool is unknown or execution fails
|
|
*/
|
|
public function executeTool(string $toolName, array $arguments, array $config = []): array;
|
|
|
|
/**
|
|
* Static UI metadata for this provider's tools, keyed by tool name.
|
|
*
|
|
* Unlike getTools() this must not depend on runtime configuration, so the
|
|
* UI can still render labels for tools that are assigned to a bot while
|
|
* the provider is (temporarily) disabled. May include legacy alias names.
|
|
*
|
|
* @return array<string,array{label?:string,summary?:string}>
|
|
*/
|
|
public function getToolMetadata(): array;
|
|
|
|
/**
|
|
* Receive the per-invocation context (bot id, room token, attachments, ...)
|
|
* before tools are executed. Stateless providers can ignore this.
|
|
*
|
|
* @param array<string,mixed>|null $context Null resets the context.
|
|
*/
|
|
public function setInvocationContext(?array $context): void;
|
|
}
|