Skip to content

fix(chat-tools): canonical JSON Schema across inc/Api/Chat/Tools/ #1923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chubes4 merged 1 commit into from
May 10, 2026
Merged

fix(chat-tools): canonical JSON Schema across inc/Api/Chat/Tools/ #1923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions inc/Api/Chat/Tools/AddPipelineStep.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,16 +43,18 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => 'Add a step to a pipeline. Automatically syncs to all flows on that pipeline.',
'parameters' => array(
'pipeline_id' => array(
'type' => 'integer',
'required' => true,
'description' => 'Pipeline ID to add the step to',
),
'step_type' => array(
'type' => 'string',
'required' => true,
'description' => "Type of step: {$types_list}",
'type' => 'object',
'properties' => array(
'pipeline_id' => array(
'type' => 'integer',
'description' => 'Pipeline ID to add the step to',
),
'step_type' => array(
'type' => 'string',
'description' => "Type of step: {$types_list}",
),
),
'required' => array( 'pipeline_id', 'step_type' ),
),
);
}
Expand Down
20 changes: 11 additions & 9 deletions inc/Api/Chat/Tools/ApiQuery.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,17 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => $this->buildApiDocumentation(),
'parameters' => array(
'endpoint' => array(
'type' => 'string',
'required' => false,
'description' => 'Single mode: REST API endpoint path (e.g., /datamachine/v1/handlers)',
),
'requests' => array(
'type' => 'array',
'required' => false,
'description' => 'Batch mode: Array of {endpoint, key?}. Results keyed by endpoint or custom key.',
'type' => 'object',
'properties' => array(
'endpoint' => array(
'type' => 'string',
'description' => 'Single mode: REST API endpoint path (e.g., /datamachine/v1/handlers)',
),
'requests' => array(
'type' => 'array',
'items' => array( 'type' => 'object' ),
'description' => 'Batch mode: Array of {endpoint, key?}. Results keyed by endpoint or custom key.',
),
),
),
);
Expand Down
39 changes: 20 additions & 19 deletions inc/Api/Chat/Tools/AssignTaxonomyTerm.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,26 +30,27 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => 'Assign a taxonomy term to one or more posts. Can append to existing terms or replace them.',
'parameters' => array(
'term' => array(
'type' => 'string',
'required' => true,
'description' => 'Term to assign - ID, name, or slug',
),
'taxonomy' => array(
'type' => 'string',
'required' => true,
'description' => 'Taxonomy slug (venue, artist, category, post_tag, etc.)',
),
'post_ids' => array(
'type' => 'array',
'required' => true,
'description' => 'Array of post IDs to assign the term to',
),
'append' => array(
'type' => 'boolean',
'required' => false,
'description' => 'true = add to existing terms, false = replace existing terms (default: true)',
'type' => 'object',
'properties' => array(
'term' => array(
'type' => 'string',
'description' => 'Term to assign - ID, name, or slug',
),
'taxonomy' => array(
'type' => 'string',
'description' => 'Taxonomy slug (venue, artist, category, post_tag, etc.)',
),
'post_ids' => array(
'type' => 'array',
'items' => array( 'type' => 'integer' ),
'description' => 'Array of post IDs to assign the term to',
),
'append' => array(
'type' => 'boolean',
'description' => 'true = add to existing terms, false = replace existing terms (default: true)',
),
),
'required' => array( 'term', 'taxonomy', 'post_ids' ),
),
);
}
Expand Down
31 changes: 16 additions & 15 deletions inc/Api/Chat/Tools/AuthenticateHandler.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,22 +38,23 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => $this->buildDescription(),
'parameters' => array(
'action' => array(
'type' => 'string',
'required' => true,
'enum' => array( 'list', 'status', 'configure', 'get_oauth_url', 'disconnect' ),
'description' => 'Action to perform: list (all statuses), status (specific handler), configure (save credentials), get_oauth_url (for OAuth), disconnect (clear auth)',
),
'handler_slug' => array(
'type' => 'string',
'required' => false,
'description' => 'Handler identifier (required for all actions except list)',
),
'credentials' => array(
'type' => 'object',
'required' => false,
'description' => 'Credentials object for configure action. For OAuth: {client_id, client_secret}. For simple auth: handler-specific fields.',
'type' => 'object',
'properties' => array(
'action' => array(
'type' => 'string',
'enum' => array( 'list', 'status', 'configure', 'get_oauth_url', 'disconnect' ),
'description' => 'Action to perform: list (all statuses), status (specific handler), configure (save credentials), get_oauth_url (for OAuth), disconnect (clear auth)',
),
'handler_slug' => array(
'type' => 'string',
'description' => 'Handler identifier (required for all actions except list)',
),
'credentials' => array(
'type' => 'object',
'description' => 'Credentials object for configure action. For OAuth: {client_id, client_secret}. For simple auth: handler-specific fields.',
),
),
'required' => array( 'action' ),
),
);
}
Expand Down
130 changes: 61 additions & 69 deletions inc/Api/Chat/Tools/ConfigureFlowSteps.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,75 +56,67 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => $description,
'parameters' => array(
'flow_step_id' => array(
'type' => 'string',
'required' => false,
'description' => 'Single flow step ID (format: {pipeline_step_id}_{flow_id})',
),
'flow_step_ids' => array(
'type' => 'array',
'required' => false,
'description' => 'Array of flow step IDs for batch updates on specific steps',
),
'pipeline_id' => array(
'type' => 'integer',
'required' => false,
'description' => 'Pipeline scope. REQUIRES either handler_slug (filter) or all_flows=true',
),
'all_flows' => array(
'type' => 'boolean',
'required' => false,
'description' => 'When true with pipeline_id, applies to ALL flows in pipeline. Explicit opt-in required for bulk operations.',
),
'step_type' => array(
'type' => 'string',
'required' => false,
'description' => 'Filter by step type (fetch, publish, upsert, ai)',
),
'handler_slug' => array(
'type' => 'string',
'required' => false,
'description' => 'Handler slug to set (single mode) OR filter by existing handler (bulk mode). Works with or without pipeline_id scope.',
),
'target_handler_slug' => array(
'type' => 'string',
'required' => false,
'description' => 'Handler to switch TO. When provided, handler_slug filters existing handlers (bulk) and target_handler_slug sets the new handler.',
),
'field_map' => array(
'type' => 'object',
'required' => false,
'description' => 'Field mappings when switching handlers, e.g. {"endpoint_url": "source_url"}. Fields with matching names auto-map by default.',
),
'handler_config' => array(
'type' => 'object',
'required' => false,
'description' => 'Handler-specific configuration to merge into existing config',
),
'flow_configs' => array(
'type' => 'array',
'required' => false,
'description' => 'Per-flow configurations for bulk mode. Array of {flow_id: int, handler_config: object}. Merged with shared handler_config (per-flow takes precedence).',
),
'user_message' => array(
'type' => 'string',
'required' => false,
'description' => 'User message/prompt for AI steps',
),
'updates' => array(
'type' => 'array',
'required' => false,
'description' => 'Cross-pipeline mode: configure multiple flows with different settings. Each item: {flow_id, step_configs (keyed by step_type: {handler_slug?, handler_config?, user_message?})}',
),
'shared_config' => array(
'type' => 'object',
'required' => false,
'description' => 'Shared step config for cross-pipeline mode (keyed by step_type). Per-flow step_configs override these.',
),
'validate_only' => array(
'type' => 'boolean',
'required' => false,
'description' => 'Dry-run mode: validate configuration without executing. Returns what would be updated.',
'type' => 'object',
'properties' => array(
'flow_step_id' => array(
'type' => 'string',
'description' => 'Single flow step ID (format: {pipeline_step_id}_{flow_id})',
),
'flow_step_ids' => array(
'type' => 'array',
'items' => array( 'type' => 'string' ),
'description' => 'Array of flow step IDs for batch updates on specific steps',
),
'pipeline_id' => array(
'type' => 'integer',
'description' => 'Pipeline scope. REQUIRES either handler_slug (filter) or all_flows=true',
),
'all_flows' => array(
'type' => 'boolean',
'description' => 'When true with pipeline_id, applies to ALL flows in pipeline. Explicit opt-in required for bulk operations.',
),
'step_type' => array(
'type' => 'string',
'description' => 'Filter by step type (fetch, publish, upsert, ai)',
),
'handler_slug' => array(
'type' => 'string',
'description' => 'Handler slug to set (single mode) OR filter by existing handler (bulk mode). Works with or without pipeline_id scope.',
),
'target_handler_slug' => array(
'type' => 'string',
'description' => 'Handler to switch TO. When provided, handler_slug filters existing handlers (bulk) and target_handler_slug sets the new handler.',
),
'field_map' => array(
'type' => 'object',
'description' => 'Field mappings when switching handlers, e.g. {"endpoint_url": "source_url"}. Fields with matching names auto-map by default.',
),
'handler_config' => array(
'type' => 'object',
'description' => 'Handler-specific configuration to merge into existing config',
),
'flow_configs' => array(
'type' => 'array',
'items' => array( 'type' => 'object' ),
'description' => 'Per-flow configurations for bulk mode. Array of {flow_id: int, handler_config: object}. Merged with shared handler_config (per-flow takes precedence).',
),
'user_message' => array(
'type' => 'string',
'description' => 'User message/prompt for AI steps',
),
'updates' => array(
'type' => 'array',
'items' => array( 'type' => 'object' ),
'description' => 'Cross-pipeline mode: configure multiple flows with different settings. Each item: {flow_id, step_configs (keyed by step_type: {handler_slug?, handler_config?, user_message?})}',
),
'shared_config' => array(
'type' => 'object',
'description' => 'Shared step config for cross-pipeline mode (keyed by step_type). Per-flow step_configs override these.',
),
'validate_only' => array(
'type' => 'boolean',
'description' => 'Dry-run mode: validate configuration without executing. Returns what would be updated.',
),
),
),
);
Expand Down
40 changes: 21 additions & 19 deletions inc/Api/Chat/Tools/ConfigurePipelineStep.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,26 +35,28 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => 'Configure pipeline-level AI step settings: system prompt and tool policy. Model/provider are managed via the mode_models site setting, not per-pipeline. For flow-level settings (handler, handler_config, user_message), use configure_flow_steps instead.',
'parameters' => array(
'pipeline_step_id' => array(
'type' => 'string',
'required' => true,
'description' => 'Pipeline step ID to configure (e.g., "123_uuid4")',
),
'system_prompt' => array(
'type' => 'string',
'required' => false,
'description' => 'System prompt for the AI step - defines the AI persona and instructions',
),
'disabled_tools' => array(
'type' => 'array',
'required' => false,
'description' => 'Array of tool slugs to disable for this AI step',
),
'tool_categories' => array(
'type' => 'array',
'required' => false,
'description' => 'Array of ability categories allowed for this AI step',
'type' => 'object',
'properties' => array(
'pipeline_step_id' => array(
'type' => 'string',
'description' => 'Pipeline step ID to configure (e.g., "123_uuid4")',
),
'system_prompt' => array(
'type' => 'string',
'description' => 'System prompt for the AI step - defines the AI persona and instructions',
),
'disabled_tools' => array(
'type' => 'array',
'items' => array( 'type' => 'string' ),
'description' => 'Array of tool slugs to disable for this AI step',
),
'tool_categories' => array(
'type' => 'array',
'items' => array( 'type' => 'string' ),
'description' => 'Array of ability categories allowed for this AI step',
),
),
'required' => array( 'pipeline_step_id' ),
),
);
}
Expand Down
47 changes: 23 additions & 24 deletions inc/Api/Chat/Tools/CopyFlow.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,31 +36,30 @@ public function getToolDefinition(): array {
'method' => 'handle_tool_call',
'description' => 'Copy a flow to the same or different pipeline. Cross-pipeline requires compatible step structures. Copies handlers, messages, and schedule.',
'parameters' => array(
'source_flow_id' => array(
'type' => 'integer',
'required' => true,
'description' => 'Flow ID to copy',
),
'target_pipeline_id' => array(
'type' => 'integer',
'required' => true,
'description' => 'Destination pipeline ID',
),
'flow_name' => array(
'type' => 'string',
'required' => true,
'description' => 'New flow name',
),
'scheduling_config' => array(
'type' => 'object',
'required' => false,
'description' => 'Override schedule (defaults to source). Format: {interval: value}. Valid intervals:' . "\n" . SchedulingDocumentation::getIntervalsJson(),
),
'step_config_overrides' => array(
'type' => 'object',
'required' => false,
'description' => 'Override steps by step_type or execution_order: {handler_slug?, handler_config?, user_message?}',
'type' => 'object',
'properties' => array(
'source_flow_id' => array(
'type' => 'integer',
'description' => 'Flow ID to copy',
),
'target_pipeline_id' => array(
'type' => 'integer',
'description' => 'Destination pipeline ID',
),
'flow_name' => array(
'type' => 'string',
'description' => 'New flow name',
),
'scheduling_config' => array(
'type' => 'object',
'description' => 'Override schedule (defaults to source). Format: {interval: value}. Valid intervals:' . "\n" . SchedulingDocumentation::getIntervalsJson(),
),
'step_config_overrides' => array(
'type' => 'object',
'description' => 'Override steps by step_type or execution_order: {handler_slug?, handler_config?, user_message?}',
),
),
'required' => array( 'source_flow_id', 'target_pipeline_id', 'flow_name' ),
),
);
}
Expand Down
Loading
Loading