filter_config

@export_module("autogen")
def filter_config(
    config_list: list[dict[str, Any]],
    filter_dict: Optional[dict[str, Union[list[Union[str, None]], set[Union[str, None]]]]],
    exclude: bool = False,
) -> list[dict[str, Any]]:
    """Filter configuration dictionaries based on specified criteria.

    This function filters a list of configuration dictionaries by applying ALL criteria specified in `filter_dict`.
    A configuration is included in the result if it satisfies every key-value constraint in the filter dictionary.
    For each filter key, the configuration's corresponding field value must match at least one of the acceptable
    values (OR logic within each criteria, AND logic between different criteria).

    Args:
        config_list (list of dict): A list of configuration dictionaries to be filtered.

        filter_dict (dict, optional): A dictionary specifying filter criteria where:
            - Keys are field names to check in each configuration dictionary
            - Values are lists/sets of acceptable values for that field
            - A configuration matches if ALL filter keys are satisfied AND for each key,
              the config's field value matches at least one acceptable value
            - If a filter value includes None, configurations missing that field will match
            - If None, no filtering is applied

        exclude (bool, optional): If False (default), return configurations that match the filter.
                                If True, return configurations that do NOT match the filter.

    Returns:
        list of dict: Filtered list of configuration dictionaries.

    Matching Logic:
        - **Between different filter keys**: AND logic (all criteria must be satisfied)
        - **Within each filter key's values**: OR logic (any acceptable value can match)
        - **For list-type config values**: Match if there's any intersection with acceptable values
        - **For scalar config values**: Match if the value is in the list of acceptable values
        - **Missing fields**: Only match if None is included in the acceptable values for that field

    Examples:
        ```python
        configs = [
            {"model": "gpt-3.5-turbo", "api_type": "openai"},
            {"model": "gpt-4", "api_type": "openai"},
            {"model": "gpt-3.5-turbo", "api_type": "azure", "api_version": "2024-02-01"},
            {"model": "gpt-4", "tags": ["premium", "latest"]},
        ]

        # Example 1: Single criterion - matches any model in the list
        filter_dict = {"model": ["gpt-4", "gpt-4o"]}
        result = filter_config(configs, filter_dict)
        # Returns: [{"model": "gpt-4", "api_type": "openai"}, {"model": "gpt-4", "tags": ["premium", "latest"]}]

        # Example 2: Multiple criteria - must satisfy ALL conditions
        filter_dict = {"model": ["gpt-3.5-turbo"], "api_type": ["azure"]}
        result = filter_config(configs, filter_dict)
        # Returns: [{"model": "gpt-3.5-turbo", "api_type": "azure", "api_version": "2024-02-01"}]

        # Example 3: Tag filtering with list intersection
        filter_dict = {"tags": ["premium"]}
        result = filter_config(configs, filter_dict)
        # Returns: [{"model": "gpt-4", "tags": ["premium", "latest"]}]

        # Example 4: Exclude matching configurations
        filter_dict = {"api_type": ["openai"]}
        result = filter_config(configs, filter_dict, exclude=True)
        # Returns configs that do NOT have api_type="openai"
        ```
    Note:
        - If `filter_dict` is empty or None, no filtering is applied and `config_list` is returned as is.
        - If a configuration dictionary in `config_list` does not contain a key specified in `filter_dict`,
          it is considered a non-match and is excluded from the result.

    """
    if inspect.stack()[1].function != "where":
        warnings.warn(
            "filter_config is deprecated and will be removed in a future release. "
            'Please use the "autogen.LLMConfig.from_json(path="OAI_CONFIG_LIST").where(model="gpt-4o")" method instead.',
            DeprecationWarning,
        )

    if filter_dict:
        return [
            item
            for item in config_list
            if all(_satisfies_criteria(item.get(key), values) != exclude for key, values in filter_dict.items())
        ]
    return config_list