Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

16.7 KB
Raw Blame
from textwrap import dedent
from types import SimpleNamespace
from typing import Any

from pydantic import BaseModel, Field
from rest_framework.exceptions import ValidationError

from posthog.schema import FeatureFlagGroupType

from posthog.exceptions_capture import capture_exception
from posthog.scopes import APIScopeObject
from posthog.sync import database_sync_to_async

from products.access_control.backend.facade.user_access_control import AccessControlLevel
from products.feature_flags.backend.facade.api import create_flag
from products.feature_flags.backend.models.evaluation_context import TeamDefaultEvaluationContext
from products.feature_flags.backend.models.feature_flag import FeatureFlag

from ee.hogai.tool import MaxTool


class MultivariateVariant(BaseModel):
    """Schema for a multivariate flag variant."""

    key: str = Field(description="Variant key (e.g., 'control', 'test', 'variant_a')")
    name: str | None = Field(default=None, description="Optional human-readable variant name")
    rollout_percentage: int = Field(ge=0, le=100, description="Percentage of users assigned to this variant (0-100)")


class FeatureFlagCreationSchema(BaseModel):
    """Structured schema for AI-powered feature flag creation using PostHog's native types."""

    key: str = Field(
        description="Unique flag key in kebab-case (e.g., 'new-dashboard', 'dark-mode'). "
        "Must only contain letters, numbers, underscores, and hyphens. Pattern: ^[a-zA-Z0-9_-]+$"
    )
    name: str = Field(description="Human-readable flag name")
    description: str | None = Field(default=None, description="Optional description of what the flag controls")
    active: bool = Field(default=True, description="Whether the flag is active")
    group_type: str | None = Field(
        default=None,
        description="Group type name for group-based targeting (e.g., 'organization', 'company')",
    )
    groups: list[FeatureFlagGroupType] = Field(
        default_factory=list,
        description="Feature flag groups containing properties and rollout percentage. "
        "Uses PostHog's native FeatureFlagGroupType schema.",
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Tags for organizing and categorizing the flag. Some projects require at least one "
        "tag on every new flag, and reject a create that carries none.",
    )
    variants: list[MultivariateVariant] | None = Field(
        default=None,
        description="Multivariate variants for A/B testing. If provided, creates a multivariate flag. "
        "Variant rollout percentages should sum to 100. "
        "Common example: [{'key': 'control', 'name': 'Control', 'rollout_percentage': 50}, "
        "{'key': 'test', 'name': 'Test', 'rollout_percentage': 50}]",
    )
    evaluation_contexts: list[str] | None = Field(
        default=None,
        description="Evaluation context names (e.g. 'production', 'staging') that control where this flag "
        "evaluates at runtime. Some projects require at least one evaluation context on every new flag. "
        "If omitted, the project's default evaluation contexts are applied automatically when configured. "
        "An explicit empty list skips the defaults.",
    )


FEATURE_FLAG_CREATION_TOOL_DESCRIPTION = dedent("""
    Use this tool to create feature flags with optional property-based targeting and multivariate variants.

    # When to use
    - The user wants to create a new feature flag
    - The user wants to roll out a feature to a percentage of users
    - The user wants to target specific users by properties (email, country, etc.)
    - The user wants a multivariate flag to back an A/B test (to create and run the actual experiment, follow up with the `create_experiment` tool)

    # Flag Types

    ## Simple Boolean Flags
    - Roll out to all users (100% rollout)
    - Roll out to a percentage of users (e.g., 10% rollout)

    ## Property-Based Targeting
    - Target users by person properties (email, country, etc.)
    - Target groups by group properties (plan, employee_count, etc.)
    - Combine property filters with rollout percentages

    ## Multivariate Flags (A/B Tests)
    - Create flags with multiple variants (control, test, etc.)
    - Specify rollout percentages for each variant (must sum to 100)
    - Can be combined with property targeting for segmented experiments
    """).strip()


class CreateFeatureFlagToolArgs(BaseModel):
    feature_flag: FeatureFlagCreationSchema = Field(
        description=dedent("""
        The complete feature flag configuration to create.

        # Required Fields
        - **key**: Unique flag key in kebab-case (e.g., 'new-dashboard', 'dark-mode')
          Must only contain letters, numbers, underscores, and hyphens
        - **name**: Human-readable flag name (e.g., 'New Dashboard Feature')

        # Optional Fields
        - **description**: Description of what the flag controls
        - **active**: Whether the flag is active (default: true)
        - **group_type**: Group type name for group-based targeting (e.g., 'organization')
        - **groups**: Array of targeting groups (see Groups Structure below)
        - **tags**: Array of tag strings for organizing flags
        - **variants**: Array of variants for A/B testing (see Variants Structure below)
        - **evaluation_contexts**: Array of evaluation context names (e.g. ['production', 'staging'])
          controlling where the flag evaluates at runtime. Some projects require at least one on every
          new flag; omit this field entirely to apply the project's configured defaults when set
          (an explicit empty list skips the defaults).

        # Groups Structure
        Each group defines targeting criteria with AND logic within the group:
        - **properties**: Array of property filters (empty array [] for no property filtering)
        - **rollout_percentage**: Percentage of matching users to target (0-100, or null for 100%)

        Property filter structure:
        ```json
        {
            "key": "email",
            "value": "@company.com",
            "operator": "icontains",
            "type": "person"
        }
        ```

        Operators: "exact", "is_not", "icontains", "not_icontains", "gt", "lt", "gte", "lte", "is_set", "is_not_set"
        Types: "person" for user properties, "group" for group properties (requires group_type_index)

        # Variants Structure (for A/B tests)
        - **key**: Variant identifier (e.g., 'control', 'test')
        - **name**: Human-readable variant name (optional)
        - **rollout_percentage**: Percentage for this variant (all variants must sum to 100)

        # Examples

        ## Simple 50% Rollout
        ```json
        {
            "key": "new-feature",
            "name": "New Feature",
            "groups": [{"properties": [], "rollout_percentage": 50}]
        }
        ```

        ## Property-Based Targeting
        ```json
        {
            "key": "beta-feature",
            "name": "Beta Feature",
            "groups": [{
                "properties": [{
                    "key": "email",
                    "value": "@company.com",
                    "operator": "icontains",
                    "type": "person"
                }],
                "rollout_percentage": null
            }]
        }
        ```

        ## A/B Test with 2 Variants
        ```json
        {
            "key": "checkout-test",
            "name": "Checkout Flow A/B Test",
            "variants": [
                {"key": "control", "name": "Current Flow", "rollout_percentage": 50},
                {"key": "test", "name": "New Flow", "rollout_percentage": 50}
            ],
            "groups": [{"properties": [], "rollout_percentage": null}]
        }
        ```

        ## Group-Based Flag (Organizations)
        ```json
        {
            "key": "enterprise-feature",
            "name": "Enterprise Feature",
            "group_type": "organization",
            "groups": [{
                "properties": [{
                    "key": "plan",
                    "value": "enterprise",
                    "operator": "exact",
                    "type": "group",
                    "group_type_index": 0
                }],
                "rollout_percentage": null
            }]
        }
        ```

        # Critical Rules
        - Keys must match pattern ^[a-zA-Z0-9_-]+$ (no spaces or special characters)
        - For A/B tests, variant rollout_percentages MUST sum to 100
        - Always include at least one group (even if properties is empty)
        - For group-based flags, set group_type and include group_type_index in property filters
        """).strip()
    )


class CreateFeatureFlagTool(MaxTool):
    name: str = "create_feature_flag"
    description: str = FEATURE_FLAG_CREATION_TOOL_DESCRIPTION
    args_schema: type[BaseModel] = CreateFeatureFlagToolArgs

    def get_required_resource_access(
        self,
    ) -> list[tuple[APIScopeObject, AccessControlLevel]]:
        """
        Creating a feature flag requires editor-level access to feature flags.
        This check runs before the tool executes.
        """

        return [("feature_flag", "editor")]

    async def _arun_impl(self, feature_flag: FeatureFlagCreationSchema) -> tuple[str, dict[str, Any]]:
        """Create feature flag"""
        try:
            flag_schema = feature_flag

            aggregation_group_type_index = None
            group_type_display_name = None
            if flag_schema.group_type:

                @database_sync_to_async
                def get_group_mapping() -> dict | None:
                    from posthog.models.group_type_mapping import get_group_types_for_project

                    target = flag_schema.group_type.lower() if flag_schema.group_type else None
                    for m in get_group_types_for_project(self._team.project_id):
                        if m["group_type"] == target:
                            return m
                    return None

                group_mapping = await get_group_mapping()
                if not group_mapping:
                    return (
                        f"Group type '{flag_schema.group_type}' does not exist for this project",
                        {"error": "group_type_not_found"},
                    )

                aggregation_group_type_index = group_mapping["group_type_index"]
                group_type_display_name = group_mapping["name_plural"] or flag_schema.group_type

            filters: dict[str, Any] = {}
            if aggregation_group_type_index is not None:
                filters["aggregation_group_type_index"] = aggregation_group_type_index
            filters["groups"] = [group.model_dump(exclude_none=True) for group in flag_schema.groups]
            if flag_schema.variants:
                filters["multivariate"] = {
                    "variants": [variant.model_dump(exclude_none=True) for variant in flag_schema.variants]
                }

            serializer_data: dict[str, Any] = {
                "key": flag_schema.key,
                "name": flag_schema.name,
                "active": flag_schema.active,
                "filters": filters,
                "tags": flag_schema.tags,
            }

            # Unspecified (None) falls back to the project defaults; an explicit empty list is left as-is.
            evaluation_contexts = flag_schema.evaluation_contexts
            if evaluation_contexts is None:
                evaluation_contexts = await self._get_default_evaluation_contexts()
            if evaluation_contexts:
                serializer_data["evaluation_contexts"] = evaluation_contexts

            # Mock request following established patterns
            mock_request = SimpleNamespace(
                user=self._user,
                method="POST",
                successful_authenticator=None,
                is_posthog_ai=True,
                session={},
                data=serializer_data,
                META={},
                headers={},
            )
            team = self._team

            @database_sync_to_async
            def create_flag_through_facade() -> FeatureFlag:
                return create_flag(serializer_data, team=team, user=self._user, request=mock_request)

            flag = await create_flag_through_facade()

            flag_url = f"/project/{self._team.project_id}/feature-flags/{flag.id}"
            targeting_info = self._format_targeting_info(flag_schema, group_type_display_name)
            contexts_info = (
                f" with evaluation contexts: {', '.join(evaluation_contexts)}" if evaluation_contexts else ""
            )

            return (
                f"Successfully created feature flag '{flag_schema.name}' (key: {flag_schema.key}){targeting_info}{contexts_info}. View at {flag_url}",
                {
                    "flag_id": flag.id,
                    "flag_key": flag_schema.key,
                    "flag_name": flag_schema.name,
                    "url": flag_url,
                    "evaluation_contexts": evaluation_contexts,
                },
            )

        except ValidationError as e:
            errors = e.detail if hasattr(e, "detail") else str(e)

            if isinstance(errors, dict) and "key" in errors:
                key_errors = errors["key"]
                if any("already" in str(err).lower() for err in key_errors):

                    @database_sync_to_async
                    def get_existing_flag() -> FeatureFlag | None:
                        return FeatureFlag.objects.filter(team=self._team, key=flag_schema.key).first()

                    existing = await get_existing_flag()
                    if existing:
                        flag_url = f"/project/{self._team.project_id}/feature-flags/{existing.id}"
                        return (
                            f"A feature flag with key '{flag_schema.key}' already exists. You can view it at {flag_url}",
                            {"flag_id": existing.id},
                        )

            if isinstance(errors, dict):
                error_messages = []
                for field, field_errors in errors.items():
                    for error in field_errors if isinstance(field_errors, list) else [field_errors]:
                        error_messages.append(f"{field}: {error}")
                return (
                    f"Failed to create feature flag: {'; '.join(error_messages)}",
                    {"error": "validation_error", "details": errors},
                )

            return f"Failed to create feature flag: {errors}", {"error": "validation_error"}
        except ValueError as e:
            return f"Failed to create feature flag: {str(e)}", {"error": str(e)}
        except Exception as e:
            capture_exception(e, {"team_id": self._team.id, "user_id": self._user.id})
            return f"Failed to create feature flag: {str(e)}", {"error": str(e)}

    @database_sync_to_async
    def _get_default_evaluation_contexts(self) -> list[str]:
        """Return the project's default evaluation context names, if defaults are enabled."""
        if not self._team.default_evaluation_contexts_enabled:
            return []

        return list(
            TeamDefaultEvaluationContext.objects.filter(team=self._team)
            .select_related("evaluation_context")
            .values_list("evaluation_context__name", flat=True)
        )

    def _format_targeting_info(self, schema: FeatureFlagCreationSchema, group_display_name: str | None) -> str:
        """Format targeting information for success message."""
        parts = []

        # Add multivariate info first if present
        if schema.variants:
            variant_count = len(schema.variants)
            if variant_count == 2:
                parts.append("A/B test with 2 variants")
            else:
                parts.append(f"multivariate with {variant_count} variants")

        # Count total property filters across all groups
        total_properties = sum(len(group.properties or []) for group in schema.groups)
        if total_properties > 0:
            parts.append(f"{total_properties} property filter(s)")

        if group_display_name:
            parts.append(f"targeting {group_display_name}")

        # Check if any group has a rollout percentage
        rollout_percentages = [
            group.rollout_percentage for group in schema.groups if group.rollout_percentage is not None
        ]
        if rollout_percentages:
            # If there's just one group with a percentage, show it
            if len(rollout_percentages) == 1:
                pct = rollout_percentages[0]
                # Format as int if it's a whole number, otherwise as float
                pct_str = f"{int(pct)}" if pct == int(pct) else f"{pct}"
                parts.append(f"{pct_str}% rollout")
            else:
                parts.append("multiple rollout rules")

        if parts:
            return " with " + ", ".join(parts)
        return ""