SportMonks API Agent

# Functional and Technical Specification for the SportMonks Agent(s) ## 1. Introduction The SportMonks Agent(s) is an autonomous component (or a set of agents) designed to receive user input in natural language and transform that query into the parameters needed to construct the URL for invoking the SportMonks API. This system is built to facilitate real-time access to sports data (such as fixtures, teams, players, statistics, etc.) by semantically converting user queries into correctly structured API requests. The development is envisioned to allow for the creation and integration of multiple agents that work together to enhance the overall functionality and performance. ## 2. Agent Objective The primary objective of the SportMonks Agent(s) is to: - Receive natural language queries from the user. - Transform these queries into specific parameters required for constructing URLs that make API calls to SportMonks. - Manage authentication, filters, includes, and other parameters needed to access the requested information. - Perform quality validations on both the transformation of input and the response received from the API using configurable validation loops. - Return processed and structured information from the API to the user, applying necessary transformations from numeric identifiers to textual representations. ## 3. Key Functionalities ### 3.1. Natural Language Processing and Query Transformation - **Input-to-Parameter Conversion:** Convert the user's query into structured data by identifying the primary entity (e.g., "Teams," "Fixtures," "Standings," etc.) and the secondary parameters (dates, IDs, country filters, etc.) that refine the search. - **Parameter Identification Validation Loop:** Implement a quality control mechanism to validate that the identified parameters are correct. This process should repeat up to a configurable maximum number of attempts (default: 4 attempts) if the transformation quality does not meet established criteria. Each iteration should log and notify any ambiguity or error to allow re-transformation of the input. ### 3.2. Selection of the Appropriate Endpoint - Evaluate the query to choose the SportMonks API endpoint that best fits the requested information. - The selection is based on the identified primary entity and any additional parameters that refine the search. ### 3.3. URL Construction and Validation - **URL Construction:** Generate the complete URL by combining: - **Base URL:** `[login to view URL]` - **Endpoint:** Selected based on the identified entity. - **Pre-Authentication Filters:** Parameters applied before the token (if necessary). - **Authentication:** Inclusion of the API token using the parameter `?api_token=YOUR_API_TOKEN`. - **Post-Authentication Filters:** Additional parameters such as `&include=lineups,standings` or other specific filters. - **Fields:** Specification of additional fields to include in the response. **Example URL Structure:** ``` [login to view URL]{endpoint}?filter_before=value1&api_token=YOUR_API_TOKEN&filter_after=value2&field=fieldValue ``` Where: - `{endpoint}` is the chosen endpoint based on the entity (e.g., `teams` or `fixtures`). - `filter_before` are filters applied before the token. - `api_token` is the authentication token. - `filter_after` are additional parameters appended after authentication. - `field` represents specific fields requested in the response. - **URL Validation:** Ensure that the constructed URL follows the required format and that all components are properly concatenated and encoded. ### 3.4. API Request Execution and Response Validation - **Execution:** Perform the API call using the tool developed (in Python) by the assigned team, which will handle connection management, error handling, and logging. - **Response Validation Loop:** Implement a process to validate the API response against the original query. If the response does not meet expectations, the agent should reconstruct the URL and retry the request, repeating the process up to a configurable maximum number of attempts (default: 3 attempts). ### 3.5. Transformation of Numeric Parameters - **Conversion of Names to IDs:** Since the API uses certain numeric identifiers, when a user's query contains a name, the agent must search for and transform that name into the corresponding numeric ID using designated search endpoints. - **Reversion in the Response:** Upon returning the final response to the user, verify and transform numeric parameters back into their textual equivalents to ensure the information is comprehensible. ## 4. Tools and Technologies - **Development Language:** The agent(s) will be developed in **Python**. - **SportMonks API:** A real-time sports data source providing information on fixtures, teams, players, statistics, etc. - **OpenAI Swarms Framework:** Utilized for generating and coordinating intelligent agents. - **Specific Tool:** The tool for URL construction and API request execution will be developed by the assigned team, using the module `configs.tools.sport_monks`. ## 5. Architecture and Workflow 1. **Reception and Transformation of the Query:** The agent(s) receive the user's natural language query and transform it into structured parameters by identifying the primary entity and secondary parameters. - A validation loop for parameter identification will run until the maximum configurable number of attempts (default: 4) is reached if quality criteria are not met. 2. **Endpoint Selection:** Based on the identified entity, the agent(s) select the appropriate SportMonks API endpoint. 3. **URL Construction:** The complete URL is constructed following the structure: ``` [login to view URL]{endpoint}?filter_before=value1&api_token=YOUR_API_TOKEN&filter_after=value2&field=fieldValue ``` - Pre- and post-authentication filters are validated and concatenated properly. 4. **Conversion of Names to Identifiers:** When the query includes names instead of IDs, the agent(s) perform a lookup to convert these names to their corresponding numeric identifiers for use in the URL. 5. **API Request Execution and Response Validation:** The agent(s) execute the API call and validate the response. If the response does not align with the original query, the URL is reconstructed, and the request is retried up to the maximum configurable number of attempts (default: 3). 6. **Response Transformation:** The final response is processed to convert numeric parameters back to textual representations before being presented to the user. 7. **Delivery of Results:** The validated and transformed final response is then provided to the user. ## 6. Validation Configuration - **Maximum Attempts for Parameter Validation:** The number of attempts for validating the parameter identification is configurable (default: 4 attempts). - **Maximum Attempts for Response Validation:** The number of retry attempts for validating the API response is configurable (default: 3 attempts). ## 7. Developer Checklist (Definition of Done) - [ ] **Input Reception and Transformation:** - Correct identification of the primary entity and secondary parameters. - Implementation of a parameter validation loop with a configurable maximum number of attempts. - [ ] **Endpoint Selection:** - The agent(s) must select the correct endpoint based on the identified entity. - Clear documentation of the selection logic is provided. - [ ] **URL Construction:** - Correct combination of the Base URL, Endpoint, pre-authentication filters, Authentication, and post-authentication filters. - The URL format is validated. - [ ] **Name-to-ID Conversion and Reversion:** - Implementation of the lookup and conversion from names to numeric IDs. - Transformation of the API response to display textual values instead of numeric IDs. - [ ] **API Request Execution and Response Validation:** - The tool for executing the API request functions correctly. - Implementation of a response validation loop with a configurable maximum number of attempts. - [ ] **Logging and Error Handling:** - Proper logging of operations, errors, and retry attempts. - Clear error messages are generated in case of failures. - [ ] **Documentation** - Comprehensive documentation of the architecture, workflow, and configurations. ## 8. Delivery The work will be delivered ready to operate in a local environment, documentation, and deployment instructions. ## 9. Development Objective The development of the SportMonks Agent(s) aims to provide an automated, robust, and high-quality solution for integrating real-time sports data. The agent(s) transform natural language queries into precise API calls to SportMonks, managing validations and parameter conversions to deliver clear and understandable results to the user. This development will be carried out in Python using the OpenAI Swarms framework, and the corresponding tool will be developed by the assigned team.