feat(examples): add results caching and modernize example runner

.env.example

@@ -3,11 +3,37 @@ POSTHOG_API_KEY=your_posthog_api_key_here
 POSTHOG_HOST=https://app.posthog.com  # or http://localhost:8010 for local development
 POSTHOG_DISTINCT_ID=example-user
 
-# AI Provider API Keys
+# AI Provider API Keys (core)
 ANTHROPIC_API_KEY=your_anthropic_api_key_here
 GEMINI_API_KEY=your_gemini_api_key_here
 OPENAI_API_KEY=your_openai_api_key_here
 
+# AI Provider API Keys (OpenAI-compatible providers)
+# Uncomment the ones you want to use:
+# GROQ_API_KEY=your_groq_api_key_here
+# DEEPSEEK_API_KEY=your_deepseek_api_key_here
+# MISTRAL_API_KEY=your_mistral_api_key_here
+# XAI_API_KEY=your_xai_api_key_here
+# TOGETHER_API_KEY=your_together_api_key_here
+# COHERE_API_KEY=your_cohere_api_key_here
+# HUGGINGFACE_API_KEY=your_huggingface_api_key_here
+# PERPLEXITY_API_KEY=your_perplexity_api_key_here
+# CEREBRAS_API_KEY=your_cerebras_api_key_here
+# FIREWORKS_API_KEY=your_fireworks_api_key_here
+# OPENROUTER_API_KEY=your_openrouter_api_key_here
+# HELICONE_API_KEY=your_helicone_api_key_here
+# PORTKEY_API_KEY=your_portkey_api_key_here
+# VERCEL_AI_GATEWAY_API_KEY=your_vercel_ai_gateway_api_key_here
+
+# Azure OpenAI
+# AZURE_OPENAI_API_KEY=your_azure_api_key_here
+# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
+
+# AWS Bedrock (uses AWS credentials)
+# AWS_REGION=us-east-1
+# AWS_ACCESS_KEY_ID=your_access_key_here
+# AWS_SECRET_ACCESS_KEY=your_secret_key_here
+
 # Local SDK Development (optional)
 # Uncomment and adjust paths to your local PostHog repositories:
 # POSTHOG_PYTHON_PATH=../posthog-python

.gitignore

@@ -24,4 +24,7 @@ __pycache__/
 example.json
 
 # Node.js
-node_modules/
+node_modules/
+
+# Example runner results cache
+.results/

CLAUDE.md

@@ -20,9 +20,9 @@ What remains here:
 make setup                      # install deps via uv
 
 # Run SDK examples from sibling repos
-make examples-list              # list all available examples
-make examples-parallel          # run all in parallel via mprocs
-./run-examples.sh anthropic     # run by name filter
+./run-examples.sh --list            # list all available examples
+./run-examples.sh --parallel        # run all in parallel via phrocs
+./run-examples.sh anthropic         # run by name filter
 
 # Generate demo data
 make demo-data                  # 5 conversations, random providers

Makefile

@@ -1,30 +1,10 @@
-.PHONY: setup examples examples-list examples-all examples-parallel examples-install run-trace-generator run-trace-generator-debug demo-data demo-data-quick demo-data-tools demo-data-negative
+.PHONY: setup run-trace-generator run-trace-generator-debug demo-data demo-data-quick demo-data-tools demo-data-negative
 
 ## Install all dependencies
 setup:
 	@uv sync
 	@pnpm install
 
-## Run the interactive example picker (sources .env, discovers examples from sibling SDK repos)
-examples:
-	@./run-examples.sh
-
-## List all available examples
-examples-list:
-	@./run-examples.sh --list
-
-## Run all examples sequentially
-examples-all:
-	@./run-examples.sh --all
-
-## Run all examples in parallel via mprocs (or filtered: make examples-parallel F=anthropic)
-examples-parallel:
-	@./run-examples.sh --parallel $(F)
-
-## Install dependencies for all examples
-examples-install:
-	@./run-examples.sh --install
-
 ## Run the trace generator (mock trace data, no LLM calls)
 run-trace-generator:
 	@uv run trace-generator/trace_generator.py

README.md

@@ -6,7 +6,10 @@ For copy-paste-able provider integration examples, see the `examples/example-ai-
 
 ## Setup
 
-Requires [uv](https://docs.astral.sh/uv/) and [pnpm](https://pnpm.io/).
+Requires:
+- [uv](https://docs.astral.sh/uv/)
+- [pnpm](https://pnpm.io/)
+- [phrocs](https://github.com/PostHog/posthog/tre/master/tools/phrocs)
 
 ```bash
 cp .env.example .env
@@ -21,18 +24,24 @@ make setup
 Discovers and runs all `example-ai-*` examples from sibling `posthog-python` and `posthog-js` repos.
 
 ```bash
-# List all available examples
-make examples-list
+# List all available examples (with cache status)
+./run-examples.sh --list
 
 # Run a specific example or group by name
 ./run-examples.sh anthropic        # all anthropic examples
 ./run-examples.sh python/openai    # python openai examples only
 
-# Run all examples in parallel via mprocs
-make examples-parallel
+# Run all examples in parallel via phrocs
+./run-examples.sh --parallel
+
+# Run all sequentially
+./run-examples.sh --all
+
+# Force re-run (ignore cache)
+./run-examples.sh --rerun --all
 
 # Install dependencies for all examples
-make examples-install
+./run-examples.sh --install
 ```
 
 ### Demo Data Generator