Dynamic venue parameter generation for AI tool definitions in the Data Machine Events plugin.

Overview

The VenueParameterProvider class manages venue-related parameters for AI tools, providing a clean separation between venue data handling and event data processing. It works alongside Venue_Taxonomy (storage) and VenueService (operations) to provide venue parameter definitions when AI should determine venue information.

Venue Parameters

The provider defines the following venue parameters that can be handled by AI tools:

• venue – Venue name
• venueAddress – Street address
• venueCity – City location
• venueState – State/province
• venueZip – Postal/zip code
• venueCountry – Country
• venuePhone – Phone number
• venueWebsite – Website URL
• venueCoordinates – GPS coordinates (latitude,longitude format)
• venueCapacity – Maximum venue capacity

Usage Examples

Get Tool Parameters

use DataMachineEventsCoreVenueParameterProvider;

// Get all venue parameters for AI tools (when no static venue configured)
$venue_params = VenueParameterProvider::getToolParameters($handler_config);

// Returns empty array if static venue is configured
// Returns full parameter array if AI should determine venue

Check Static Venue Configuration

// Check if handler has static venue configured
$has_static = VenueParameterProvider::hasStaticVenue($handler_config);

// Returns true if:
// - Universal Web Scraper has venue configured
// - Venue is a numeric term ID

Extract Venue Data from Parameters

// Extract venue data from AI tool parameters
$venue_data = VenueParameterProvider::extractFromParameters($parameters);

// Returns array keyed by Venue_Taxonomy meta field names:
// [
//     'name' => 'The Blue Note',
//     'address' => '123 Main St',
//     'city' => 'New York',
//     'state' => 'NY',
//     'zip' => '10001',
//     // ...
// ]

Extract from Event Data

// Extract venue metadata from event data array
$venue_metadata = VenueParameterProvider::extractFromEventData($event_data);

// Strip venue fields from event data (modifies array in place)
VenueParameterProvider::stripFromEventData($event_data);

Parameter Mapping

The provider maintains a mapping between tool parameter names and Venue_Taxonomy meta field keys:

private const PARAMETER_TO_META_MAP = [
    'venue' => 'name',
    'venueAddress' => 'address',
    'venueCity' => 'city',
    'venueState' => 'state',
    'venueZip' => 'zip',
    'venueCountry' => 'country',
    'venuePhone' => 'phone',
    'venueWebsite' => 'website',
    'venueCoordinates' => 'coordinates',
    'venueCapacity' => 'capacity'
];

Integration with EventSchemaProvider

Both VenueParameterProvider and EventSchemaProvider use the DynamicToolParametersTrait to filter parameters by engine data at definition time:

// Venue parameters filtered by engine data - excludes params that already have values
$venue_params = VenueParameterProvider::getToolParameters($handler_config, $engine_data);

// Event parameters also filtered by engine data
$event_params = EventSchemaProvider::getCoreToolParameters($engine_data);
$schema_params = EventSchemaProvider::getSchemaToolParameters($engine_data);

// If engine_data contains ['venue' => 'Central Park', 'startDate' => '2025-07-15']
// then 'venue' is excluded from venue_params and 'startDate' is excluded from event_params
// The AI only sees parameters it needs to provide

Architecture Benefits

• Clean Separation: Venue parameters handled independently from event parameters
• Flexible Configuration: Supports both static venue configuration and AI-determined venues
• Consistent Mapping: Single source of truth for venue parameter definitions
• Easy Integration: Works with existing Venue_Taxonomy and VenueService classes
• Maintainable: Centralized venue parameter logic docs/venue-parameter-provider.md