: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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()