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.

25.6 KB
Raw Blame
import re
from collections.abc import Iterable
from functools import cached_property
from typing import Literal, Optional, Union, cast

from pydantic import BaseModel, field_validator

from posthog.schema import (
    ActorsPropertyTaxonomyQuery,
    CachedActorsPropertyTaxonomyQueryResponse,
    CachedEventTaxonomyQueryResponse,
    EventTaxonomyQuery,
)

from posthog.hogql.database.schema.channel_type import DEFAULT_CHANNEL_TYPES

from posthog.clickhouse.query_tagging import Feature, Product, tags_context
from posthog.event_usage import EventSource
from posthog.hogql_queries.ai.actors_property_taxonomy_query_runner import ActorsPropertyTaxonomyQueryRunner
from posthog.hogql_queries.ai.event_taxonomy_query_runner import EventTaxonomyQueryRunner
from posthog.hogql_queries.query_runner import ExecutionMode
from posthog.models import Team, User
from posthog.settings import EE_AVAILABLE
from posthog.taxonomy.property_access import restricted_property_names
from posthog.taxonomy.taxonomy import CORE_FILTER_DEFINITIONS_BY_GROUP, CoreFilterDefinition

from products.actions.backend.facade.api import list_actions
from products.actions.backend.facade.contracts import ActionNotFound
from products.event_definitions.backend.models.property_definition import (
    PropertyDefinition,
    PropertyType,
    effective_project_id_expr,
)

from ee.hogai.chat_agent.taxonomy.entities import resolve_entity_name
from ee.hogai.chat_agent.taxonomy.format import enrich_props_with_descriptions
from ee.hogai.chat_agent.taxonomy.session_properties import session_property_types
from ee.hogai.chat_agent.taxonomy.tools import (
    ask_user_for_help,
    retrieve_action_properties,
    retrieve_action_property_values,
    retrieve_entity_properties,
    retrieve_entity_property_values,
    retrieve_event_properties,
    retrieve_event_property_values,
)
from ee.hogai.chat_agent.taxonomy.virtual_properties import (
    PropertyDefinitionOrVirtual,
    get_virtual_property_definition,
    get_virtual_property_sample_values,
    list_virtual_properties,
    property_is_string_like,
    virtual_group_for_entity,
    virtual_property_no_values_message,
)
from ee.hogai.utils.helpers import sanitize_event_description
from ee.hogai.utils.prompt import format_prompt_string

MaxSupportedQueryKind = Literal["trends", "funnel", "retention", "sql"]


class final_answer(BaseModel):
    """
    Use this tool to finalize the answer to the user's question.
    """

    plan: str
    query_kind: MaxSupportedQueryKind  # query_kind is intentionally AFTER plan so that these tokens are generated after decision explanation

    @field_validator("plan", mode="before")
    def normalize_plan(cls, plan: str) -> str:
        """
        Normalize the generated plan, so the `action` entity becomes `event`.
        """
        return re.sub(
            r"-\s*(entity:)?\s*action(?!\s*id)",
            "- entity: event",
            plan,
            flags=re.IGNORECASE | re.MULTILINE,
        )


TaxonomyAgentToolUnion = Union[
    retrieve_event_properties,
    retrieve_action_properties,
    retrieve_entity_properties,
    retrieve_event_property_values,
    retrieve_action_property_values,
    retrieve_entity_property_values,
    ask_user_for_help,
    final_answer,
]


class TaxonomyAgentTool(BaseModel):
    name: str
    arguments: TaxonomyAgentToolUnion


PROPERTIES_EXAMPLE_PROMPT = """
The data format is as follows:
<Data type>
- $event – description text here
- another_event
</Data type>
...
---
Results:
{{{result}}}
""".strip()


class TaxonomyAgentToolkit:
    _team: Team
    _user: User

    def __init__(self, team: Team, user: User, event_source: EventSource = EventSource.POSTHOG_AI):
        self._team = team
        self._user = user
        self._event_source = event_source

    def _restricted_property_names(self, property_type: PropertyDefinition.Type) -> set[str]:
        return restricted_property_names(self._team, self._user, property_type)

    @cached_property
    def _groups(self) -> list[dict]:
        from posthog.models.group_type_mapping import get_group_types_for_project

        return get_group_types_for_project(self._team.project_id)

    @cached_property
    def _entity_names(self) -> list[str]:
        """
        The schemas use `group_type_index` for groups complicating things for the agent. Instead, we use groups' names,
        so the generation step will handle their indexes. Tools would need to support multiple arguments, or we would need
        to create various tools for different group types. Since we don't use function calling here, we want to limit the
        number of tools because non-function calling models can't handle many tools.
        """
        entities = [
            "person",
            "session",
            *[g["group_type"] for g in self._groups],
        ]
        return entities

    def _entity_not_found_message(self, entity: str) -> str:
        return f"The entity {entity} does not exist in the taxonomy. You must use one of the following: {', '.join(self._entity_names)}."

    def _generate_properties_output(self, props: list[tuple[str, str | None, str | None]]) -> str:
        """
        Generate the output format for properties. Can be overridden by subclasses.
        Default implementation uses YAML-like format with bullet points.
        """
        property_type_to_props: dict[str, list[tuple[str, str | None]]] = {}

        for name, property_type, description in props:
            # Do not include properties that are ambiguous.
            if property_type is None:
                continue
            if property_type not in property_type_to_props:
                property_type_to_props[property_type] = []

            property_type_to_props[property_type].append((name, description))

        output_parts = []
        for property_type, prop_list in property_type_to_props.items():
            output_parts.append(f"<{property_type}>")
            for name, description in prop_list:
                if description:
                    output_parts.append(f"- {name} – {description.replace('\n', ' ')}")
                else:
                    output_parts.append(f"- {name}")
            output_parts.append(f"</{property_type}>")

        return "\n".join(output_parts)

    def _enrich_props_with_descriptions(
        self,
        entity: str,
        props: Iterable[tuple[str, str | None]],
        stored_descriptions: dict[str, str] | None = None,
    ):
        return enrich_props_with_descriptions(entity, props, stored_descriptions)

    def _get_stored_property_descriptions(
        self,
        property_type: PropertyDefinition.Type,
        names: list[str],
        group_type_index: int | None = None,
    ) -> dict[str, str]:
        """Map property name -> sanitized user-authored description from the team's property definitions.

        Only the enterprise `PropertyDefinition` model carries a `description` field, so this is a
        no-op on non-EE builds. Descriptions live only in Postgres and never influence which
        properties are surfaced — the list still comes from ClickHouse / stored definitions. Runs a
        single batched query.
        """
        if not EE_AVAILABLE or not names:
            return {}

        from ee.models.property_definition import (
            EnterprisePropertyDefinition,  # noqa: PLC0415 — EE-only model, keep off the OSS import path
        )

        qs = (
            EnterprisePropertyDefinition.objects.alias(effective_project_id=effective_project_id_expr())
            .filter(effective_project_id=self._team.project_id, type=property_type, name__in=names)
            .exclude(description__isnull=True)
            .exclude(description="")
        )
        if group_type_index is not None:
            qs = qs.filter(group_type_index=group_type_index)
        return {
            name: sanitize_event_description(description)
            for name, description in qs.values_list("name", "description")
            if description
        }

    def retrieve_entity_properties(self, entity: str, max_properties: int = 500) -> str:
        """
        Retrieve properties for an entitiy like person, session, or one of the groups.
        """

        resolved = resolve_entity_name(entity, self._entity_names)
        if resolved is None:
            return self._entity_not_found_message(entity)
        entity = resolved

        truncated = False
        if entity == "person":
            restricted = self._restricted_property_names(PropertyDefinition.Type.PERSON)
            stored_props, truncated = self._stored_property_page(
                PropertyDefinition.Type.PERSON, restricted, max_properties
            )
            stored_props += list_virtual_properties(
                "person_properties", exclude={name for name, _ in stored_props} | restricted
            )
            stored_descriptions = self._get_stored_property_descriptions(
                PropertyDefinition.Type.PERSON, [name for name, _ in stored_props]
            )
            props = self._enrich_props_with_descriptions("person", stored_props, stored_descriptions)
        elif entity == "session":
            # Session properties are not in the DB.
            props = self._enrich_props_with_descriptions("session", list(session_property_types().items()))

        else:
            group_type_index = next((g["group_type_index"] for g in self._groups if g["group_type"] == entity), None)
            if group_type_index is None:
                return f"Group {entity} does not exist in the taxonomy."
            restricted = self._restricted_property_names(PropertyDefinition.Type.GROUP)
            stored_props, truncated = self._stored_property_page(
                PropertyDefinition.Type.GROUP, restricted, max_properties, group_type_index=group_type_index
            )
            stored_props += list_virtual_properties("groups", exclude={name for name, _ in stored_props} | restricted)
            stored_descriptions = self._get_stored_property_descriptions(
                PropertyDefinition.Type.GROUP,
                [name for name, _ in stored_props],
                group_type_index=group_type_index,
            )
            props = self._enrich_props_with_descriptions(entity, stored_props, stored_descriptions)

        if not props:
            return f"Properties do not exist in the taxonomy for the entity {entity}."

        result = format_prompt_string(PROPERTIES_EXAMPLE_PROMPT, result=self._generate_properties_output(props))
        if truncated:
            result += (
                f"\n\nThis list stops at {max_properties} properties and {entity} has more. "
                "Ask for a property by name before you treat it as missing."
            )
        return result

    def _stored_property_page(
        self,
        property_type: PropertyDefinition.Type,
        restricted: set[str],
        max_properties: int,
        group_type_index: int | None = None,
    ) -> tuple[list[tuple[str, str | None]], bool]:
        """
        Read one page of stored definitions, and report whether more were left behind.

        Reads one row past the page to detect the overflow. A COUNT would answer the same
        question by walking the team's whole definition range, which is the cost the page
        limit is here to avoid.
        """
        qs = PropertyDefinition.objects.filter(team=self._team, type=property_type)
        if group_type_index is not None:
            qs = qs.filter(group_type_index=group_type_index)
        rows = list(qs.values_list("name", "property_type")[: max_properties + 1])
        return [row for row in rows[:max_properties] if row[0] not in restricted], len(rows) > max_properties

    def _retrieve_event_or_action_taxonomy(self, event_name_or_action_id: str | int):
        is_event = isinstance(event_name_or_action_id, str)
        if is_event:
            query = EventTaxonomyQuery(event=event_name_or_action_id, maxPropertyValues=25)
            verbose_name = f"event {event_name_or_action_id}"
        else:
            query = EventTaxonomyQuery(actionId=event_name_or_action_id, maxPropertyValues=25)
            verbose_name = f"action with ID {event_name_or_action_id}"
        runner = EventTaxonomyQueryRunner(query, self._team, user=self._user)
        with tags_context(
            product=Product.MAX_AI,
            feature=Feature.POSTHOG_AI,
            team_id=self._team.pk,
            org_id=self._team.organization_id,
        ):
            response = runner.run(
                ExecutionMode.RECENT_CACHE_CALCULATE_ASYNC_IF_STALE_AND_BLOCKING_ON_MISS,
                user=self._user,
                analytics_props={"source": self._event_source},
            )
        return response, verbose_name

    def _fetch_event_property_types(self, names: list[str]) -> dict[str, str | None]:
        """
        Fetch the stored type for each event property name.

        Filters on COALESCE(project_id, team_id) rather than team_id: no index on this table
        contains (team_id, name), so a plain team_id predicate makes Postgres walk the team's
        entire index range — multi-second to statement-timeout on teams with millions of
        property definitions. The coalesce expression matches the posthog_propdef_proj_uniq
        index (COALESCE(project_id, team_id), name, type, ...), turning the lookup into one
        index seek per name. It is also the same project-level scoping the taxonomy REST API
        applies to this table.

        That index also keys on COALESCE(group_type_index, -1), which this filter leaves open.
        Event definitions never carry a group type index, so each (project, name) resolves to
        one row and the dict build below cannot drop a value.
        """
        return dict(
            PropertyDefinition.objects.alias(effective_project_id=effective_project_id_expr())
            .filter(
                effective_project_id=self._team.project_id,
                type=PropertyDefinition.Type.EVENT,
                name__in=names,
            )
            .values_list("name", "property_type")
        )

    def retrieve_event_or_action_properties(self, event_name_or_action_id: str | int) -> str:
        """
        Retrieve properties for an event.
        """
        try:
            response, verbose_name = self._retrieve_event_or_action_taxonomy(event_name_or_action_id)
        except ActionNotFound:
            project_actions = list_actions(project_id=self._team.project_id)
            if not project_actions:
                return "No actions exist in the project."
            return f"Action {event_name_or_action_id} does not exist in the taxonomy. Verify that the action ID is correct and try again."

        if not isinstance(response, CachedEventTaxonomyQueryResponse):
            return "Properties have not been found."
        if not response.results:
            return f"Properties do not exist in the taxonomy for the {verbose_name}."

        # Intersect properties with their types.
        restricted = self._restricted_property_names(PropertyDefinition.Type.EVENT)
        property_to_type = {
            name: property_type
            for name, property_type in self._fetch_event_property_types(
                [item.property for item in response.results]
            ).items()
            if name not in restricted
        }
        props: list[tuple[str, str | None]] = [
            (item.property, property_to_type.get(item.property))
            for item in response.results
            # Exclude properties that exist in the taxonomy, but don't have a type.
            if item.property in property_to_type
        ]
        # Virtual properties are computed at query time, so they never appear in stored event data.
        props += list_virtual_properties("event_properties", exclude=property_to_type.keys() | restricted)

        if not props:
            return f"Properties do not exist in the taxonomy for the {verbose_name}."

        stored_descriptions = self._get_stored_property_descriptions(
            PropertyDefinition.Type.EVENT, [name for name, _ in props]
        )
        return format_prompt_string(
            PROPERTIES_EXAMPLE_PROMPT,
            result=self._generate_properties_output(
                self._enrich_props_with_descriptions("event", props, stored_descriptions)
            ),
        )

    def _format_property_values(
        self, sample_values: list, sample_count: Optional[int] = 0, format_as_string: bool = False
    ) -> str:
        if len(sample_values) == 0 or sample_count == 0:
            return f"The property does not have any values in the taxonomy."

        # Add quotes to the String type, so the LLM can easily infer a type.
        # Strings like "true" or "10" are interpreted as booleans or numbers without quotes, so the schema generation fails.
        # Remove the floating point the value is an integer.
        formatted_sample_values: list[str] = []
        for value in sample_values:
            if format_as_string:
                formatted_sample_values.append(f'"{value}"')
            elif isinstance(value, float) and value.is_integer():
                formatted_sample_values.append(str(int(value)))
            else:
                formatted_sample_values.append(str(value))
        prop_values = ", ".join(formatted_sample_values)

        # If there wasn't an exact match with the user's search, we provide a hint that LLM can use an arbitrary value.
        if sample_count is None:
            return f"{prop_values} and many more distinct values."
        elif sample_count > len(sample_values):
            diff = sample_count - len(sample_values)
            return f"{prop_values} and {diff} more distinct value{'' if diff == 1 else 's'}."

        return prop_values

    def _format_virtual_property_values(self, property_name: str, property_definition: CoreFilterDefinition) -> str:
        sample_values, sample_count = get_virtual_property_sample_values(property_definition)
        if not sample_values:
            return virtual_property_no_values_message(property_name)
        return self._format_property_values(
            sample_values, sample_count, format_as_string=property_is_string_like(property_definition)
        )

    def retrieve_event_or_action_property_values(self, event_name_or_action_id: str | int, property_name: str) -> str:
        # Restricted properties are indistinguishable from non-existent ones, so we don't leak their values.
        if property_name in self._restricted_property_names(PropertyDefinition.Type.EVENT):
            return f"The property {property_name} does not exist in the taxonomy."
        virtual_definition = get_virtual_property_definition("event_properties", property_name)
        property_definition: PropertyDefinitionOrVirtual
        try:
            property_definition = PropertyDefinition.objects.alias(
                effective_project_id=effective_project_id_expr()
            ).get(effective_project_id=self._team.project_id, name=property_name, type=PropertyDefinition.Type.EVENT)
        except PropertyDefinition.DoesNotExist:
            if virtual_definition is None:
                return f"The property {property_name} does not exist in the taxonomy."
            property_definition = virtual_definition

        response, verbose_name = self._retrieve_event_or_action_taxonomy(event_name_or_action_id)
        if not isinstance(response, CachedEventTaxonomyQueryResponse):
            return f"The {verbose_name} does not exist in the taxonomy."

        prop = next((item for item in response.results or [] if item.property == property_name), None)
        if not prop:
            # Virtual properties never appear in stored event data, so fall back to taxonomy examples.
            if virtual_definition is not None:
                return self._format_virtual_property_values(property_name, virtual_definition)
            if not response.results:
                return f"Property values for {property_name} do not exist in the taxonomy for the {verbose_name}."
            return f"The property {property_name} does not exist in the taxonomy for the {verbose_name}."

        return self._format_property_values(
            prop.sample_values,
            prop.sample_count,
            format_as_string=property_is_string_like(property_definition),
        )

    def _retrieve_session_properties(self, property_name: str) -> str:
        """
        Sessions properties example property values are hardcoded.
        """
        if property_name not in CORE_FILTER_DEFINITIONS_BY_GROUP["session_properties"]:
            return f"The property {property_name} does not exist in the taxonomy."

        sample_values: list[str | int | float]
        if property_name == "$channel_type":
            sample_values = cast(list[str | int | float], DEFAULT_CHANNEL_TYPES.copy())
            sample_count = len(sample_values)
            is_str = True
        elif "examples" in CORE_FILTER_DEFINITIONS_BY_GROUP["session_properties"][property_name]:
            sample_values = CORE_FILTER_DEFINITIONS_BY_GROUP["session_properties"][property_name]["examples"]
            sample_count = None
            is_str = session_property_types().get(property_name) == PropertyType.String
        else:
            return f"Property values for {property_name} do not exist in the taxonomy for the session entity."

        return self._format_property_values(sample_values, sample_count, format_as_string=is_str)

    def retrieve_entity_property_values(self, entity: str, property_name: str) -> str:
        resolved = resolve_entity_name(entity, self._entity_names)
        if resolved is None:
            return self._entity_not_found_message(entity)
        entity = resolved

        if entity == "session":
            return self._retrieve_session_properties(property_name)

        # Restricted properties are indistinguishable from non-existent ones, so we don't leak their values.
        restricted_type = PropertyDefinition.Type.PERSON if entity == "person" else PropertyDefinition.Type.GROUP
        if property_name in self._restricted_property_names(restricted_type):
            return f"The property {property_name} does not exist in the taxonomy for the entity {entity}."

        if entity == "person":
            query = ActorsPropertyTaxonomyQuery(properties=[property_name], maxPropertyValues=25)
        elif entity == "event":
            query = ActorsPropertyTaxonomyQuery(properties=[property_name], maxPropertyValues=50)
        else:
            group_index = next((g["group_type_index"] for g in self._groups if g["group_type"] == entity), None)
            if group_index is None:
                return f"The entity {entity} does not exist in the taxonomy."
            query = ActorsPropertyTaxonomyQuery(
                groupTypeIndex=group_index, properties=[property_name], maxPropertyValues=25
            )

        virtual_definition = get_virtual_property_definition(virtual_group_for_entity(entity), property_name)
        property_definition: PropertyDefinitionOrVirtual
        try:
            if query.groupTypeIndex is not None:
                prop_type = PropertyDefinition.Type.GROUP
                group_type_index = query.groupTypeIndex
            elif entity == "event":
                prop_type = PropertyDefinition.Type.EVENT
                group_type_index = None
            else:
                prop_type = PropertyDefinition.Type.PERSON
                group_type_index = None
            property_definition = PropertyDefinition.objects.alias(
                effective_project_id=effective_project_id_expr()
            ).get(
                effective_project_id=self._team.project_id,
                name=property_name,
                type=prop_type,
                group_type_index=group_type_index,
            )
        except PropertyDefinition.DoesNotExist:
            if virtual_definition is None:
                return f"The property {property_name} does not exist in the taxonomy for the entity {entity}."
            property_definition = virtual_definition

        with tags_context(
            product=Product.MAX_AI,
            feature=Feature.POSTHOG_AI,
            team_id=self._team.pk,
            org_id=self._team.organization_id,
        ):
            response = ActorsPropertyTaxonomyQueryRunner(query, self._team, user=self._user).run(
                ExecutionMode.RECENT_CACHE_CALCULATE_ASYNC_IF_STALE_AND_BLOCKING_ON_MISS,
                user=self._user,
                analytics_props={"source": self._event_source},
            )

        if not isinstance(response, CachedActorsPropertyTaxonomyQueryResponse):
            return f"The entity {entity} does not exist in the taxonomy."

        if not response.results:
            if virtual_definition is not None:
                return self._format_virtual_property_values(property_name, virtual_definition)
            return f"Property values for {property_name} do not exist in the taxonomy for the entity {entity}."

        # TRICKY. Remove when the toolkit supports multiple results.
        if isinstance(response.results, list):
            unpacked_results = response.results[0]
        else:
            unpacked_results = response.results

        # Virtual properties never appear in stored actor data, so fall back to taxonomy examples.
        if not unpacked_results.sample_values and virtual_definition is not None:
            return self._format_virtual_property_values(property_name, virtual_definition)

        return self._format_property_values(
            unpacked_results.sample_values,
            unpacked_results.sample_count,
            format_as_string=property_is_string_like(property_definition),
        )

    def handle_incorrect_response(self, response: BaseModel) -> str:
        """
        No-op tool. Take a parsing error and return a response that the LLM can use to correct itself.
        Used to control a number of retries.
        """
        return response.model_dump_json()