chore: merge main into v1 (DO NOT SQUASH, lands by fast-forward)

.github/dependabot.yml

@@ -27,6 +27,7 @@ updates:
       - dependency-name: "langchain*"
       - dependency-name: "langgraph"
     open-pull-requests-limit: 1
+    versioning-strategy: increase-if-necessary
     reviewers:
       - "PostHog/team-llm-analytics"
 
@@ -57,6 +58,7 @@ updates:
       - dependency-name: "langchain*"
       - dependency-name: "langgraph"
     open-pull-requests-limit: 1
+    versioning-strategy: increase-if-necessary
     reviewers:
       - "PostHog/team-llm-analytics"
     # Uncomment below to enable auto-merge for minor updates when CI passes

.github/scripts/check_strict_types.sh

@@ -15,6 +15,7 @@ import atexit
 
 import posthog
 from posthog import FeatureFlagEvaluations, FlagValue, Posthog
+from posthog.emails import AsyncEmails, Emails, SendEmailResult
 from posthog.ai.evaluations import (
     AsyncOfflineEvaluations,
     BooleanScorerConfig,
@@ -40,6 +41,16 @@ span.end()
 
 _ = (flag_value, all_flags, enabled, payload, evaluations, active)
 
+emails = Emails("phs_example")
+template_send: SendEmailResult = emails.send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", template_data={"name": "Ada"})
+rendered_send: SendEmailResult = emails.send(to="user@example.com", template_key="password-reset", subject="Reset", html="<p>Reset</p>", from_="Acme <security@example.com>", reply_to=["help@example.com"], capture_engagement=False, max_retries=0)
+_ = (template_send, rendered_send)
+
+
+async def async_email_types() -> None:
+    sent: SendEmailResult = await AsyncEmails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="<p>Hi</p>")
+    _ = sent
+
 
 async def offline_evaluation_types(
     sync_client: OfflineEvaluations, async_client: AsyncOfflineEvaluations
@@ -64,15 +75,26 @@ async def offline_evaluation_types(
     _ = config
 PY
 
-cat > "$tmp/invalid_offline_types.py" <<'PY'
+cat > "$tmp/invalid_types.py" <<'PY'
 # pyright: strict
 from posthog.ai.evaluations import BooleanScorerConfig, CategoricalScorerConfig, NumericPassingRule, NumericScorerConfig, OfflineEvaluations
+from posthog.emails import AsyncEmails, Emails
 
 client = OfflineEvaluations(project_id=123, secret_key="phx_example")
 NumericPassingRule(operator="gt", threshold=0.8)  # expected-type-error
 NumericScorerConfig(unknown_setting=True)  # expected-type-error
 CategoricalScorerConfig(selection_mode="single")  # expected-type-error
 client.scorers.create(name="Bad config", kind="numeric", config=BooleanScorerConfig(true_is_failure=True))  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", template_key="welcome", subject="Hi", html="<p>Hi</p>")  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_key="welcome", html="<p>Hi</p>")  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", cc="team@example.com")  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", capture_engagement=False)  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="<p>Hi</p>", template_data={"name": "Ada"})  # expected-type-error
+Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="<p>Hi</p>", cc="team@example.com")  # expected-type-error
+
+
+async def invalid_async_email() -> None:
+    await AsyncEmails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", subject="Hi")  # expected-type-error
 PY
 
 "$tmp/.venv/bin/python" - <<'PY' > "$tmp/public_api_access.py"
@@ -116,20 +138,20 @@ JSON
 cd "$tmp"
 "$tmp/.venv/bin/python" -m pyright strict_posthog_types.py public_api_access.py
 
-if "$tmp/.venv/bin/python" -m pyright --outputjson invalid_offline_types.py > invalid_types.json; then
-    echo "Invalid offline evaluation configurations unexpectedly passed type checking."
+if "$tmp/.venv/bin/python" -m pyright --outputjson invalid_types.py > invalid_types.json; then
+    echo "Invalid offline evaluation configurations and email sends unexpectedly passed type checking."
     exit 1
 fi
 "$tmp/.venv/bin/python" - <<'PY'
 import json
 from pathlib import Path
 
 expected = {
-    index for index, line in enumerate(Path("invalid_offline_types.py").read_text().splitlines())
+    index for index, line in enumerate(Path("invalid_types.py").read_text().splitlines())
     if "expected-type-error" in line
 }
 diagnostics = json.loads(Path("invalid_types.json").read_text())["generalDiagnostics"]
 actual = {item["range"]["start"]["line"] for item in diagnostics if item["severity"] == "error"}
 assert actual == expected, diagnostics
-print("Offline evaluation configuration types reject invalid inputs.")
+print("Offline evaluation configuration and email send types reject invalid inputs.")
 PY

.github/workflows/benchmark-report.yml

@@ -0,0 +1,21 @@
+name: Python SDK benchmark report
+
+on:
+    workflow_run:
+        workflows: ['Python SDK benchmarks']
+        types: [completed]
+
+permissions: {}
+
+jobs:
+    report:
+        permissions:
+            contents: read
+            actions: read
+            pull-requests: write
+        uses: PostHog/.github/.github/workflows/sdk-benchmark-report.yml@3322f26f21f088ad5e5960d65a916971e309ac0b # SDK benchmark workflow (PostHog/.github PR #84)
+        with:
+            workflow-path: .github/workflows/benchmarks.yml
+            artifact-name: python-benchmark-results
+            report-key: posthog-python
+            sdk: posthog-python

.github/workflows/benchmarks.yml

@@ -0,0 +1,143 @@
+name: Python SDK benchmarks
+
+on: [pull_request]
+
+permissions: {}
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+jobs:
+    benchmark:
+        runs-on: ubuntu-24.04
+        timeout-minutes: 10
+        strategy:
+            fail-fast: false
+            matrix:
+                shard: [flags-single, flags-scaling, flags-memory, capture]
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  ref: ${{ github.event.pull_request.head.sha }}
+                  fetch-depth: 0
+                  persist-credentials: false
+
+            - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+              with:
+                  python-version: '3.12.12'
+
+            - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+              with:
+                  version: '0.13.4'
+                  enable-cache: true
+
+            - name: Prepare pinned baseline
+              env:
+                  TARGET_SHA: ${{ github.event.pull_request.base.sha }}
+                  HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+              run: |
+                  set -euo pipefail
+                  export BASE_WORKTREE="$RUNNER_TEMP/python-benchmark-base"
+                  export RESULTS="$RUNNER_TEMP/python-benchmark-results"
+                  printf 'BASE_WORKTREE=%s\nRESULTS=%s\n' "$BASE_WORKTREE" "$RESULTS" >> "$GITHUB_ENV"
+                  BASE_SHA=$(git merge-base "$TARGET_SHA" "$HEAD_SHA")
+                  git worktree add --detach "$BASE_WORKTREE" "$BASE_SHA"
+                  mkdir -p "$RESULTS"
+                  python -c 'import json, os, pathlib, sys; pathlib.Path(os.environ["RESULTS"], "revisions.json").write_text(json.dumps({"target":os.environ["TARGET_SHA"], "head":os.environ["HEAD_SHA"], "base":sys.argv[1]}, indent=2))' "$BASE_SHA"
+
+            - name: Install isolated head and baseline wheels
+              run: |
+                  python benchmarks/prepare.py .
+                  python benchmarks/prepare.py "$BASE_WORKTREE"
+
+            - name: Test measurement controls and fixtures
+              run: .venv-benchmark/bin/python -B benchmarks/test_benchmarks.py
+
+            - name: Measure paired base and head
+              id: measure
+              timeout-minutes: 8
+              run: |
+                  .venv-benchmark/bin/python -B benchmarks/run.py \
+                    --base "$BASE_WORKTREE" \
+                    --head "$GITHUB_WORKSPACE" \
+                    --output "$RESULTS" \
+                    --repetitions 6 \
+                    --shard "${{ matrix.shard }}"
+
+            - name: Upload raw shard results
+              if: always()
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: benchmark-shard-${{ matrix.shard }}
+                  path: |
+                      ${{ runner.temp }}/python-benchmark-results/base.json
+                      ${{ runner.temp }}/python-benchmark-results/head.json
+                      ${{ runner.temp }}/python-benchmark-results/revisions.json
+                  if-no-files-found: warn
+                  retention-days: 14
+
+    collect:
+        needs: benchmark
+        if: ${{ !cancelled() }}
+        runs-on: ubuntu-24.04
+        timeout-minutes: 5
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  ref: ${{ github.event.pull_request.head.sha }}
+                  persist-credentials: false
+
+            - name: Download shard results
+              uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+              with:
+                  pattern: benchmark-shard-*
+                  path: ${{ runner.temp }}/python-benchmark-shards
+                  merge-multiple: false
+
+            - name: Collect and render benchmark comparison
+              uses: PostHog/.github/.github/actions/benchmark-report@3322f26f21f088ad5e5960d65a916971e309ac0b # SDK benchmark reporting (PostHog/.github PR #84)
+              with:
+                  mode: collect
+                  source-status: ${{ needs.benchmark.result }}
+                  shard-manifest: benchmarks/shards.json
+                  shard-directory: ${{ runner.temp }}/python-benchmark-shards
+                  output-directory: ${{ runner.temp }}/python-benchmark-report
+
+            - name: Upload rendered comparison
+              if: always()
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: python-benchmark-report
+                  path: |
+                      ${{ runner.temp }}/python-benchmark-report/report.md
+                      ${{ runner.temp }}/python-benchmark-report/comparison.json
+                  if-no-files-found: ignore
+                  retention-days: 14
+
+            - name: Upload raw benchmark results
+              if: always()
+              id: results
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: python-benchmark-results
+                  path: |
+                      ${{ runner.temp }}/python-benchmark-report/bundle.json
+                      ${{ runner.temp }}/python-benchmark-report/revisions.json
+                  if-no-files-found: warn
+                  retention-days: 14
+
+            - name: Link results
+              if: always()
+              env:
+                  ARTIFACT_URL: ${{ steps.results.outputs.artifact-url }}
+              run: |
+                  printf '## Python SDK benchmark data\n\n' >> "$GITHUB_STEP_SUMMARY"
+                  if [[ -n "$ARTIFACT_URL" ]]; then
+                    printf '[Download paired measurements and execution metadata](%s)\n\n' "$ARTIFACT_URL" >> "$GITHUB_STEP_SUMMARY"
+                  fi
+                  printf 'Measurements are informational. Check workload statuses before comparing values.\n' >> "$GITHUB_STEP_SUMMARY"

.github/workflows/ci.yml

@@ -87,7 +87,7 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python 3.11
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: 3.11
 
@@ -104,12 +104,12 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python 3.11
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: 3.11
 
             - name: Install uv
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true
@@ -132,12 +132,12 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: ${{ matrix.python-version }}
 
             - name: Install uv
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true
@@ -179,12 +179,12 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: ${{ matrix.python-version }}
 
             - name: Install uv
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true
@@ -244,13 +244,13 @@ jobs:
 
             - name: Set up Python 3.11
               if: steps.changes.outputs.changed == 'true'
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: 3.11
 
             - name: Install uv
               if: steps.changes.outputs.changed == 'true'
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true
@@ -303,7 +303,7 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: ${{ matrix.python-version }}
 
@@ -326,12 +326,12 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python ${{ matrix.python-version }}
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: ${{ matrix.python-version }}
 
             - name: Install uv
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true
@@ -381,12 +381,12 @@ jobs:
                   fetch-depth: 1
 
             - name: Set up Python 3.12
-              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
               with:
                   python-version: 3.12
 
             - name: Install uv
-              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
               with:
                   version: "0.13.4"
                   enable-cache: true

.github/workflows/codeql.yml

@@ -30,7 +30,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/init@1fc58d04a4d4374f921bdac573c3811c240f9c26 # v4.39.2
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -40,6 +40,6 @@ jobs:
           trap-caching: false
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        uses: github/codeql-action/analyze@1fc58d04a4d4374f921bdac573c3811c240f9c26 # v4.39.2
         with:
           category: '/language:${{matrix.language}}'