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.

4.5 KB
Raw Blame
from collections.abc import Iterable, Mapping, Sequence
from typing import Optional

# nosemgrep: python.lang.security.use-defused-xml.use-defused-xml (XML generation only, no parsing - no XXE risk)
from xml.etree import ElementTree as ET

import yaml

from posthog.taxonomy.taxonomy import CORE_FILTER_DEFINITIONS_BY_GROUP, is_hidden_from_assistant


def format_property_values(
    property_name: str,
    sample_values: Sequence[str | int | float],
    sample_count: Optional[int] = 0,
    format_as_string: bool = False,
) -> str:
    if len(sample_values) == 0 or sample_count == 0:
        data = {
            "property": property_name,
            "values": [],
            "message": f"The property does not have any values in the taxonomy.",
        }
        return yaml.dump(data, default_flow_style=False, sort_keys=False)

    # Format values for YAML
    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))

    if sample_count is None:
        formatted_sample_values.append("and many more distinct values")
    elif sample_count > len(sample_values):
        remaining = sample_count - len(sample_values)
        formatted_sample_values.append(f"and {remaining} more distinct values")
    data = {"property": property_name, "values": formatted_sample_values}
    return yaml.dump(data, default_flow_style=False, sort_keys=False)


def format_properties_xml(children: list[tuple[str, str | None, str | None]]):
    root = ET.Element("properties")
    property_type_to_tag = {}

    for name, property_type, description in children:
        # Do not include properties that are ambiguous.
        if property_type is None:
            continue
        if property_type not in property_type_to_tag:
            property_type_to_tag[property_type] = ET.SubElement(root, property_type)

        type_tag = property_type_to_tag[property_type]
        prop = ET.SubElement(type_tag, "prop")
        ET.SubElement(prop, "name").text = name
        if description:
            ET.SubElement(prop, "description").text = description

    return ET.tostring(root, encoding="unicode")


def format_properties_yaml(children: list[tuple[str, str | None, str | None]]):
    properties_by_type: dict = {}

    for name, property_type, description in children:
        # Do not include properties that are ambiguous.
        if property_type is None:
            continue

        if property_type not in properties_by_type:
            properties_by_type[property_type] = []

        prop_dict = {"name": name}
        if description:
            prop_dict["description"] = description

        properties_by_type[property_type].append(prop_dict)

    result = {"properties": properties_by_type}
    return yaml.dump(result, default_flow_style=False, sort_keys=False)


def enrich_props_with_descriptions(
    entity: str,
    props: Iterable[tuple[str, str | None]],
    stored_descriptions: Mapping[str, str] | None = None,
):
    """Attach a description to each property.

    The built-in core taxonomy wins. For custom properties it has never heard of, fall back to the
    user-authored description stored on the property definition (passed in already sanitized). This
    only enriches properties the caller already discovered via ClickHouse — it never sources the
    property list itself from Postgres.
    """
    enriched_props = []
    mapping = {
        "session": CORE_FILTER_DEFINITIONS_BY_GROUP["session_properties"],
        "person": CORE_FILTER_DEFINITIONS_BY_GROUP["person_properties"],
        "event": CORE_FILTER_DEFINITIONS_BY_GROUP["event_properties"],
    }
    # Entities other than the well-known ones are group types.
    entity_definitions = mapping.get(entity, CORE_FILTER_DEFINITIONS_BY_GROUP["groups"])
    stored_descriptions = stored_descriptions or {}
    for prop_name, prop_type in props:
        description = None
        if entity_definition := entity_definitions.get(prop_name):
            if is_hidden_from_assistant(entity_definition):
                continue
            description = entity_definition.get("description_llm") or entity_definition.get("description")
        else:
            description = stored_descriptions.get(prop_name)
        enriched_props.append((prop_name, prop_type, description))
    return enriched_props