: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
from typing import Any
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnableConfig
from posthog.schema import MaxBillingContext, SpendHistoryItem, UsageHistoryItem
from posthog.clickhouse.client import sync_execute
from posthog.models import Team, User
from posthog.sync import database_sync_to_async
from ee.billing.billing_types import USAGE_TYPE_OPTIONS
from ee.hogai.context.context import AssistantContextManager
from ee.hogai.tool import MaxSubtool
from ee.hogai.tool_errors import MaxToolFatalError
from ee.hogai.utils.types import AssistantState
from .prompts import BILLING_CONTEXT_PROMPT, BILLING_CONTEXT_UNAVAILABLE_PROMPT
class ReadBillingTool(MaxSubtool):
def __init__(
self,
*,
team: Team,
user: User,
state: AssistantState,
config: RunnableConfig,
context_manager: AssistantContextManager,
):
super().__init__(team=team, user=user, state=state, config=config, context_manager=context_manager)
self._teams_map: dict[int, str] = {}
async def execute(self) -> str:
billing_context = self._context_manager.get_billing_context()
if not billing_context:
return BILLING_CONTEXT_UNAVAILABLE_PROMPT
formatted_billing_context = await self._format_billing_context(billing_context)
return formatted_billing_context
@database_sync_to_async(thread_sensitive=False)
def _format_billing_context(self, billing_context: MaxBillingContext) -> str:
"""Format billing context into a readable prompt section."""
# Convert billing context to a format suitable for the mustache template
template_data: dict[str, Any] = {
"subscription_level": (
billing_context.subscription_level.value if billing_context.subscription_level else "free"
),
"billing_plan": billing_context.billing_plan,
"has_active_subscription": billing_context.has_active_subscription,
"organization_teams_count": len(self._get_teams_map().keys()),
"current_team_name": self._team.name,
"current_team_id": self._team.id,
}
# Add startup program info
if billing_context.startup_program_label:
template_data["startup_program_label"] = billing_context.startup_program_label
if billing_context.startup_program_label_previous:
template_data["startup_program_label_previous"] = billing_context.startup_program_label_previous
if not billing_context.startup_program_label and not billing_context.startup_program_label_previous:
template_data["startup_program_label"] = "None"
# Add billing period info
if billing_context.billing_period:
template_data["billing_period"] = {
"current_period_start": billing_context.billing_period.current_period_start,
"current_period_end": billing_context.billing_period.current_period_end,
"interval": billing_context.billing_period.interval,
}
# Add cost information
if billing_context.total_current_amount_usd:
template_data["total_current_amount_usd"] = billing_context.total_current_amount_usd
if billing_context.projected_total_amount_usd:
template_data["total_projected_amount_usd"] = billing_context.projected_total_amount_usd
if billing_context.projected_total_amount_usd_after_discount:
template_data["total_projected_amount_usd_after_discount"] = (
billing_context.projected_total_amount_usd_after_discount
)
if billing_context.projected_total_amount_usd_with_limit:
template_data["total_projected_amount_usd_with_limit"] = (
billing_context.projected_total_amount_usd_with_limit
)
if billing_context.projected_total_amount_usd_with_limit_after_discount:
template_data["total_projected_amount_usd_with_limit_after_discount"] = (
billing_context.projected_total_amount_usd_with_limit_after_discount
)
# Add products information
if billing_context.products:
template_data["products"] = []
for product in billing_context.products:
product_data: dict[str, Any] = {
"name": product.name,
"type": product.type,
"description": product.description,
"current_usage": int(product.current_usage) if product.current_usage else None,
"usage_limit": int(product.usage_limit) if product.usage_limit else None,
"percentage_usage": product.percentage_usage,
"has_exceeded_limit": product.has_exceeded_limit,
"custom_limit_usd": product.custom_limit_usd,
"next_period_custom_limit_usd": product.next_period_custom_limit_usd,
"docs_url": product.docs_url,
"projected_amount_usd": product.projected_amount_usd,
"projected_amount_usd_with_limit": product.projected_amount_usd_with_limit,
"addons": [],
}
# Add a flag to check if this product has addons
if product.addons:
product_data["has_addons"] = True
product_data["product_name"] = product.name
for addon in product.addons:
addon_data = {
"name": addon.name,
"type": addon.type,
"description": addon.description,
"current_usage": int(addon.current_usage) if addon.current_usage else None,
"usage_limit": int(addon.usage_limit) if addon.usage_limit else None,
"docs_url": addon.docs_url,
"projected_amount_usd": addon.projected_amount_usd,
}
product_data["addons"].append(addon_data)
template_data["products"].append(product_data)
# Add trial information
if billing_context.trial:
template_data["trial"] = {
"is_active": billing_context.trial.is_active,
"expires_at": billing_context.trial.expires_at,
"target": billing_context.trial.target,
}
if billing_context.usage_history:
# Format usage history as a table with breakdown by date
usage_table = self._format_history_table(billing_context.usage_history)
template_data["usage_history_table"] = usage_table
if billing_context.spend_history:
# Format spend history as a table with breakdown by date
spend_table = self._format_history_table(billing_context.spend_history)
template_data["spend_history_table"] = spend_table
# Add settings
template_data["settings"] = {
"autocapture_on": billing_context.settings.autocapture_on,
"active_destinations": billing_context.settings.active_destinations,
}
# Add top events by usage
top_events = self._get_top_events_by_usage()
if top_events:
template_data["top_events"] = top_events
template = PromptTemplate.from_template(BILLING_CONTEXT_PROMPT, template_format="mustache")
return template.format_prompt(**template_data).to_string()
def _get_teams_map(self) -> dict[int, str]:
if self._teams_map:
return self._teams_map
self._teams_map = {team.id: f"{team.name} (ID: {team.id})" for team in self._team.organization.teams.all()}
return self._teams_map
def _format_history_table(self, usage_history: list[UsageHistoryItem] | list[SpendHistoryItem]) -> str:
"""Format multiple breakdowns as breakdown table."""
if not usage_history:
return "No data available"
# Group history items by team based on breakdown_value format
tables = []
team_items: dict[str, list] = {}
other_items = []
valid_team_ids = {str(team_id) for team_id in self._get_teams_map().keys()}
for item in usage_history:
team_id_found = None
# Extract team ID from breakdown_value by finding which value is a team ID
if item.breakdown_value and isinstance(item.breakdown_value, list):
for value in item.breakdown_value:
if str(value) in valid_team_ids:
team_id_found = str(value)
break
if team_id_found:
if team_id_found not in team_items:
team_items[team_id_found] = []
team_items[team_id_found].append(item)
else:
other_items.append(item)
# Always create aggregated table first (Overall all projects)
aggregated_items = self._create_aggregated_items(team_items, other_items)
if aggregated_items:
aggregated_table = self._format_single_team_table(aggregated_items, "Overall (all projects)")
tables.append(aggregated_table)
# Create tables for each team if breakdowns are available
for team_id, items in team_items.items():
team_name = self._get_teams_map().get(int(team_id), None)
table = self._format_single_team_table(items, team_name or f"Project ID: {team_id}")
tables.append(table)
return "\n\n".join(tables)
def _create_aggregated_items(self, team_items: dict[str, list], other_items: list) -> list:
"""Create aggregated items by summing values across all teams and non-team breakdowns."""
if not team_items and not other_items:
return []
# Collect all items to aggregate
all_items = []
for items in team_items.values():
all_items.extend(items)
all_items.extend(other_items)
if not all_items:
return []
# Group items by product type (extracted from label or breakdown_value)
product_to_items: dict[str, list] = {}
for item in all_items:
product_type = self._extract_product_type(item)
if product_type not in product_to_items:
product_to_items[product_type] = []
product_to_items[product_type].append(item)
# Create aggregated items for each product type
aggregated_items = []
for product_type, items in product_to_items.items():
# Get all unique dates across all items with this product type
all_dates = set()
for item in items:
all_dates.update(item.dates)
sorted_dates = sorted(all_dates)
# Sum values for each date
aggregated_data = []
for date in sorted_dates:
total_value = 0
for item in items:
date_to_value = dict(zip(item.dates, item.data))
total_value += date_to_value.get(date, 0)
aggregated_data.append(total_value)
# Create the aggregated item (using the first item as template)
first_item = items[0]
# Use a clean label for the aggregated item
clean_label = self._get_clean_product_label(product_type)
if isinstance(first_item, UsageHistoryItem):
aggregated_item: UsageHistoryItem | SpendHistoryItem = UsageHistoryItem(
id=1, # Use a dummy ID for aggregated items
label=clean_label,
dates=sorted_dates,
data=aggregated_data,
breakdown_type=None,
breakdown_value=None,
)
elif isinstance(first_item, SpendHistoryItem):
aggregated_item = SpendHistoryItem(
id=1, # Use a dummy ID for aggregated items
label=clean_label,
dates=sorted_dates,
data=aggregated_data,
breakdown_type=None,
breakdown_value=None,
)
else:
raise MaxToolFatalError(
f"Unexpected billing history item type: Received {type(first_item).__name__} but expected either "
f"UsageHistoryItem or SpendHistoryItem."
)
aggregated_items.append(aggregated_item)
return aggregated_items
def _extract_product_type(self, item) -> str:
"""Extract product type from item label or breakdown_value."""
valid_usage_types = {usage_type["value"] for usage_type in USAGE_TYPE_OPTIONS}
# First try breakdown_value format: find the value that matches known usage types
if item.breakdown_value and isinstance(item.breakdown_value, list):
for value in item.breakdown_value:
if str(value) in valid_usage_types:
return str(value)
# Then check if the label itself is a known usage type
if item.label in valid_usage_types:
return item.label
# Fall back to full label (for custom or unknown types)
return item.label
def _get_clean_product_label(self, product_type: str) -> str:
"""Convert product type to a clean label for display."""
# Try to find matching label from known usage types
for usage_type in USAGE_TYPE_OPTIONS:
if usage_type["value"] == product_type:
return usage_type["label"]
# Fall back to formatting the product_type
return product_type.replace("_", " ").capitalize()
def _format_single_team_table(self, items: list[UsageHistoryItem] | list[SpendHistoryItem], title: str) -> str:
"""Format a single table for a team or overall data."""
if not items:
return f"### {title}\nNo data available"
# Get all unique dates across all items
all_dates = set()
for item in items:
all_dates.update(item.dates)
sorted_dates = sorted(all_dates)
# Build table header
table_lines = [f"### {title}"]
if not sorted_dates:
return f"### {title}\nNo data available"
# Create header row
header = "| Data Type | " + " | ".join(sorted_dates) + " |"
separator = "|" + "|".join([" --- "] * (len(sorted_dates) + 1)) + "|"
table_lines.extend([header, separator])
# Add data rows
for item in items:
# Create a mapping from date to value
date_to_value = dict(zip(item.dates, item.data))
# Build row with values aligned to dates
row_values = []
for date in sorted_dates:
value = date_to_value.get(date, 0)
formatted_value = f"{float(value):,.2f}"
row_values.append(formatted_value)
# For team-specific tables, extract clean product type
product_type = self._extract_product_type(item)
clean_label = self._get_clean_product_label(product_type)
row = f"| {clean_label} | " + " | ".join(row_values) + " |"
table_lines.append(row)
return "\n".join(table_lines)
def _get_top_events_by_usage(self) -> list[dict[str, Any]]:
"""Get top 20 events by usage over the last 30 days for the current team."""
try:
query = """
SELECT
event,
count() as count
FROM events
WHERE
team_id = %(team_id)s
AND timestamp >= now() - INTERVAL 30 DAY
GROUP BY
event
ORDER BY
count DESC
LIMIT 20
"""
results = sync_execute(query, {"team_id": self._team.id})
if isinstance(results, list):
return [
{"event": row[0], "count": int(row[1]), "formatted_count": f"{int(row[1]):,}"} for row in results
]
return []
except Exception:
# If query fails, return empty list
return []