docs: add AI provider integration examples (#466)

* feat: Add AI provider integration examples

Add self-contained examples for each AI provider supported by posthog.ai:
- Anthropic (chat, streaming, extended thinking)
- OpenAI (Chat Completions, Responses, streaming, embeddings, transcription, image generation)
- Google Gemini (chat, streaming, image generation)
- LangChain (callback handler, OTEL)
- LiteLLM (chat, streaming)
- Pydantic AI (agent with OTEL)
- OpenAI Agents SDK (multi-agent, single agent, guardrails, custom spans)

Each example directory is self-contained with its own requirements.txt,
.env.example, and README. Files are designed to be copy-pasted by users
as starting points for their own integrations.

* style: apply ruff formatting to AI examples

* fix: add __init__.py to example directories for mypy

Mypy reports duplicate module names when multiple example directories
contain files with the same name (e.g. chat.py). Adding __init__.py
makes each directory a proper package so mypy can disambiguate them.

* fix: exclude examples from mypy and sync baseline

Example directory names contain hyphens (e.g. example-ai-anthropic)
which aren't valid Python package names, so __init__.py doesn't help.
Exclude them from mypy instead and sync the baseline.

* fix: fix image gen, transcription, and gemini logging in examples

- Use images.generate API instead of responses API for image generation
- Gracefully skip transcription when audio file is missing
- Use privacy mode for Gemini image gen to avoid huge event payloads
- Suppress Gemini SDK base64 logging

* fix: add missing run commands to example READMEs

* Add comment about incomplete tool-calling loop in examples

Author: richardsolomou

examples/example-ai-anthropic/.env.example

@@ -0,0 +1,3 @@
+POSTHOG_API_KEY=phc_your_project_api_key
+POSTHOG_HOST=https://us.i.posthog.com
+ANTHROPIC_API_KEY=sk-ant-your_api_key

examples/example-ai-anthropic/README.md

@@ -0,0 +1,26 @@
+# Anthropic + PostHog AI Examples
+
+Track Anthropic Claude API calls with PostHog.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+# Fill in your API keys in .env
+```
+
+## Examples
+
+- **chat.py** - Basic chat with tool calling
+- **streaming.py** - Streaming responses
+- **extended_thinking.py** - Claude's extended thinking feature
+
+## Run
+
+```bash
+source .env
+python chat.py
+python streaming.py
+python extended_thinking.py
+```

examples/example-ai-anthropic/chat.py

@@ -0,0 +1,57 @@
+"""Anthropic chat with tool calling, tracked by PostHog."""
+
+import os
+import json
+import urllib.request
+from posthog import Posthog
+from posthog.ai.anthropic import Anthropic
+
+posthog = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"], posthog_client=posthog)
+
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get current weather for a location",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "latitude": {"type": "number"},
+                "longitude": {"type": "number"},
+                "location_name": {"type": "string"},
+            },
+            "required": ["latitude", "longitude", "location_name"],
+        },
+    }
+]
+
+
+def get_weather(latitude: float, longitude: float, location_name: str) -> str:
+    url = f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,relative_humidity_2m,wind_speed_10m"
+    with urllib.request.urlopen(url) as resp:
+        data = json.loads(resp.read())
+    current = data["current"]
+    return f"Weather in {location_name}: {current['temperature_2m']}°C, humidity {current['relative_humidity_2m']}%, wind {current['wind_speed_10m']} km/h"
+
+
+message = client.messages.create(
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=1024,
+    posthog_distinct_id="example-user",
+    tools=tools,
+    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
+)
+
+# Handle tool use if the model requests it.
+# In production, send tool results back to the model for a final response.
+for block in message.content:
+    if block.type == "text":
+        print(block.text)
+    elif block.type == "tool_use":
+        result = get_weather(**block.input)
+        print(result)
+
+posthog.shutdown()

examples/example-ai-anthropic/extended_thinking.py

@@ -0,0 +1,35 @@
+"""Anthropic extended thinking, tracked by PostHog.
+
+Extended thinking lets Claude show its reasoning process before responding.
+"""
+
+import os
+from posthog import Posthog
+from posthog.ai.anthropic import Anthropic
+
+posthog = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"], posthog_client=posthog)
+
+message = client.messages.create(
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=16000,
+    posthog_distinct_id="example-user",
+    thinking={"type": "enabled", "budget_tokens": 10000},
+    messages=[
+        {
+            "role": "user",
+            "content": "What is the probability of rolling at least one six in four rolls of a fair die?",
+        }
+    ],
+)
+
+for block in message.content:
+    if block.type == "thinking":
+        print(f"Thinking: {block.thinking}\n")
+    elif block.type == "text":
+        print(f"Answer: {block.text}")
+
+posthog.shutdown()

examples/example-ai-anthropic/requirements.txt

@@ -0,0 +1,2 @@
+posthog>=6.6.1
+anthropic

examples/example-ai-anthropic/streaming.py

@@ -0,0 +1,27 @@
+"""Anthropic streaming chat, tracked by PostHog."""
+
+import os
+from posthog import Posthog
+from posthog.ai.anthropic import Anthropic
+
+posthog = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"], posthog_client=posthog)
+
+stream = client.messages.create(
+    model="claude-sonnet-4-5-20250929",
+    max_tokens=1024,
+    posthog_distinct_id="example-user",
+    messages=[{"role": "user", "content": "Write a haiku about observability."}],
+    stream=True,
+)
+
+for event in stream:
+    if hasattr(event, "type"):
+        if event.type == "content_block_delta" and hasattr(event.delta, "text"):
+            print(event.delta.text, end="", flush=True)
+
+print()
+posthog.shutdown()

examples/example-ai-gemini/.env.example

@@ -0,0 +1,3 @@
+POSTHOG_API_KEY=phc_your_project_api_key
+POSTHOG_HOST=https://us.i.posthog.com
+GEMINI_API_KEY=your_gemini_api_key

examples/example-ai-gemini/README.md

@@ -0,0 +1,26 @@
+# Google Gemini + PostHog AI Examples
+
+Track Google Gemini API calls with PostHog.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+# Fill in your API keys in .env
+```
+
+## Examples
+
+- **chat.py** - Chat with tool calling
+- **streaming.py** - Streaming responses
+- **image_generation.py** - Image generation
+
+## Run
+
+```bash
+source .env
+python chat.py
+python streaming.py
+python image_generation.py
+```

examples/example-ai-gemini/chat.py

@@ -0,0 +1,65 @@
+"""Google Gemini chat with tool calling, tracked by PostHog."""
+
+import os
+import json
+import urllib.request
+from google.genai import types
+from posthog import Posthog
+from posthog.ai.gemini import Client
+
+posthog = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+client = Client(api_key=os.environ["GEMINI_API_KEY"], posthog_client=posthog)
+
+tool_declarations = [
+    {
+        "name": "get_weather",
+        "description": "Get current weather for a location",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "latitude": {"type": "number"},
+                "longitude": {"type": "number"},
+                "location_name": {"type": "string"},
+            },
+            "required": ["latitude", "longitude", "location_name"],
+        },
+    }
+]
+
+
+def get_weather(latitude: float, longitude: float, location_name: str) -> str:
+    url = f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,relative_humidity_2m,wind_speed_10m"
+    with urllib.request.urlopen(url) as resp:
+        data = json.loads(resp.read())
+    current = data["current"]
+    return f"Weather in {location_name}: {current['temperature_2m']}°C, humidity {current['relative_humidity_2m']}%, wind {current['wind_speed_10m']} km/h"
+
+
+config = types.GenerateContentConfig(
+    tools=[types.Tool(function_declarations=tool_declarations)]
+)
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash",
+    posthog_distinct_id="example-user",
+    contents=[{"role": "user", "parts": [{"text": "What's the weather in London?"}]}],
+    config=config,
+)
+
+# In production, send tool results back to the model for a final response.
+for candidate in response.candidates:
+    for part in candidate.content.parts:
+        if hasattr(part, "function_call") and part.function_call:
+            result = get_weather(
+                latitude=part.function_call.args["latitude"],
+                longitude=part.function_call.args["longitude"],
+                location_name=part.function_call.args["location_name"],
+            )
+            print(result)
+        elif hasattr(part, "text"):
+            print(part.text)
+
+posthog.shutdown()

examples/example-ai-gemini/image_generation.py

@@ -0,0 +1,34 @@
+"""Google Gemini image generation, tracked by PostHog."""
+
+import logging
+import os
+
+from posthog import Posthog
+from posthog.ai.gemini import Client
+
+# Suppress verbose Gemini SDK logging of base64 image data
+logging.getLogger("google.genai").setLevel(logging.WARNING)
+
+posthog = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+client = Client(api_key=os.environ["GEMINI_API_KEY"], posthog_client=posthog)
+
+response = client.models.generate_content(
+    model="gemini-2.5-flash-image",
+    posthog_distinct_id="example-user",
+    posthog_privacy_mode=True,  # Redact base64 image data from the PostHog event
+    contents=[{"role": "user", "parts": [{"text": "Generate a pixel art hedgehog"}]}],
+)
+
+for candidate in response.candidates:
+    for part in candidate.content.parts:
+        if hasattr(part, "inline_data") and part.inline_data:
+            print(
+                f"Generated image: {part.inline_data.mime_type}, {len(part.inline_data.data)} bytes"
+            )
+        elif hasattr(part, "text"):
+            print(part.text)
+
+posthog.shutdown()