# AI Services API: Enums

Directory: `includes/Services/API/Enums/`

This directory contains PHP classes that simulate enumerations (enums). These enums define sets of named constants used throughout the AI Services API to represent fixed sets of possible values for various parameters and properties.

It is CRITICAL that all the available PHP enums and their values defined here are kept in sync with the JavaScript/TypeScript enums in `src/ai/enums/`.

## Purpose

The primary purpose of the code within this directory is to:

- Define enums and their constants to reference throughout the plugin
- Make these available as part of the public API for other plugin developers

## Architecture

The enum implementation follows a simple hierarchical pattern:

1.  **`Contracts/Enum.php`**: This interface defines the basic contract that all enum classes must adhere to. It ensures that every enum provides at least two static methods:
    -   `is_valid_value( string $value ): bool`: Checks if a given string value is a valid member of the enum.
    -   `get_values(): array`: Returns an array of all valid string values for the enum.

2.  **`Abstract_Enum.php`**: This abstract class provides a base implementation for the `Enum` interface.
    -   It implements `is_valid_value()` and `get_values()` by relying on an abstract static method `get_all_values()`.
    -   Concrete enum classes must extend `Abstract_Enum` and implement `get_all_values()` to return an array of their defined constant values.
    -   It includes an internal static caching mechanism (`$value_map`) to store the valid values for each enum class once they are first retrieved, improving performance for subsequent calls.
    -   Public static methods `is_valid_value()` and `get_values()` are declared `final` to ensure consistent behavior across all enums.

3.  **Concrete Enum Classes**: These `final` classes extend `Abstract_Enum` and define the actual sets of constants. Each constant represents a specific value for the enum.
    -   **`AI_Capability.php`**: Defines the different capabilities that an AI model or service can possess.
        -   `CHAT_HISTORY`: Support for maintaining and using conversation history.
        -   `FUNCTION_CALLING`: Ability for the AI to request execution of predefined functions.
        -   `IMAGE_GENERATION`: Capability to generate images.
        -   `MULTIMODAL_INPUT`: Ability to process input that includes multiple types of data (e.g., text and images).
        -   `MULTIMODAL_OUTPUT`: Capability to produce output that includes multiple types of data.
        -   `TEXT_GENERATION`: Capability to generate textual content.
    -   **`Content_Role.php`**: Defines the roles of participants or content segments in a conversation or generative process.
        -   `USER`: Represents content or messages originating from the end-user.
        -   `MODEL`: Represents content or messages generated by the AI model.
        -   `SYSTEM`: Represents instructions or context provided to guide the AI model's behavior, not typically displayed to the user.
    -   **`Modality.php`**: Defines the different types of data modalities that can be used as input or output.
        -   `TEXT`: Represents textual data.
        -   `IMAGE`: Represents image data.
        -   `AUDIO`: Represents audio data.
    -   **`Service_Type.php`**: Defines the different types of AI services based on their operational environment or nature.
        -   `CLOUD`: Indicates a service that operates in the cloud, typically accessed via remote APIs.
        -   `SERVER`: Indicates a service that runs on the server-side infrastructure.
        -   `CLIENT`: Indicates a service that operates on the client-side, potentially within the user's browser or device.

## Technical Decisions

-   **Simulated Enums**: PHP versions prior to 8.1 do not have native enum support. This project uses classes with public constants and static utility methods to simulate this functionality, providing a type-safe way to manage predefined sets of values.
-   **`final` Classes**: Concrete enum classes are declared `final` to prevent them from being extended. This ensures that the set of values for each enum remains fixed and well-defined.
-   **Static Methods**: Enum values and validation logic are accessed via static methods and constants, eliminating the need to instantiate enum objects.
-   **`get_all_values()`**: Each concrete enum must implement the `protected static function get_all_values(): array` method, which returns an array of all its public constant values. This method is used by `Abstract_Enum` to populate its internal value map for validation and retrieval.

This structure provides a clear, consistent, and maintainable way to define and use enumerated types within the plugin's API.