Merge remote-tracking branch 'origin/main' into fix/versioned-boolean-local-evaluation

Author: marandaneto

.github/workflows/ci.yml

@@ -155,10 +155,11 @@ jobs:
         # The MCP suite as a named gate per MCP Python SDK major. The v1 leg uses
         # the lockfile's mcp 1.x (also exercised incidentally by the `tests`
         # matrix — this leg exists as an explicit, named signal); the v2 leg
-        # (spec 2026-07-28) swaps in mcp>=2 and drops jlowin fastmcp, which pins
-        # mcp<2. posthog/test/mcp/conftest.py splits collection by major.
+        # (spec 2026-07-28) swaps in mcp>=2 and standalone FastMCP 4, which uses
+        # the v2 registry. posthog/test/mcp/conftest.py splits collection by major.
         name: MCP SDK ${{ matrix.mcp-major }} (Python ${{ matrix.python-version }})
         runs-on: ubuntu-latest
+        timeout-minutes: 20
         strategy:
             matrix:
                 python-version: ['3.10', '3.14']
@@ -189,8 +190,8 @@ jobs:
               if: matrix.mcp-major == 'v2'
               shell: bash
               run: |
-                  uv pip uninstall --python $pythonLocation fastmcp
-                  uv pip install --python $pythonLocation 'mcp>=2,<3'
+                  uv pip uninstall --python "$pythonLocation" fastmcp
+                  uv pip install --python "$pythonLocation" 'mcp>=2,<3' 'fastmcp>=4,<5'
 
             - name: Run MCP tests against SDK ${{ matrix.mcp-major }}
               run: |

.github/workflows/codeql.yml

@@ -30,7 +30,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         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@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
+        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
         with:
           category: '/language:${{matrix.language}}'

.github/workflows/release.yml

@@ -66,7 +66,7 @@ jobs:
     if: always() && needs.check-changesets.outputs.has-changesets == 'true'
     environment: "Release" # This will require an approval from a maintainer, they are notified in Slack above
     permissions:
-      contents: write
+      contents: read
     outputs:
       commit-hash: ${{ steps.commit-release.outputs.commit-hash }}
       new_version: ${{ steps.sampo-release.outputs.new_version }}

AGENTS.md

@@ -7,6 +7,7 @@ Guidance for coding agents working in `posthog-python`.
 - This repository contains the PostHog Python SDK, published as `posthog`.
 - The main runtime package is `posthog/`; tests live under `posthog/test/`.
 - The project uses `uv` for local development. See `CONTRIBUTING.md` for setup.
+- Before adding or changing public API, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): the API shape must be agreed on the issue first. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md.
 - Keep edits targeted and follow existing patterns. Prefer adding or updating tests near the behavior you change.
 
 ## Capture protocol (`capture_mode`)

CONTRIBUTING.md

@@ -48,3 +48,15 @@ posthoganalytics = { path = "../posthog-python-local" }
 ```
 
 This lets you test SDK changes fully locally inside the PostHog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. Re-run `make prep_local` each time you make a change, and then run `uv sync --active` in the PostHog app project.
+
+## Public API changes
+
+Public API is hard to change once it ships, so agree on it before writing the implementation. Our [SDK guidelines](https://posthog.com/handbook/engineering/sdks/guidelines) explain how we design it.
+
+- If you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case first. At this stage, context is more useful to us than code.
+- Wait for a maintainer to agree on the API shape on the issue before implementing it.
+- Check first whether an existing option or hook, such as `before_send`, already covers the use case. We avoid offering two ways to do the same thing.
+- If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.
+- AI agents: stop and ask before implementing a public API change that hasn't been agreed on the issue.
+
+`make public_api_snapshot` regenerates `references/public_api_snapshot.txt`, and CI runs `make public_api_check` to catch an outdated snapshot. A diff in that file means your change touches public API.

examples/example-ai-crewai/uv.lock

@@ -14,12 +14,18 @@ uv sync
 ## Examples
 
 - **callback_handler.py** - PostHog callback handler with tool calling
+- **agent_middleware.py** - LangChain v1 agent middleware with model and tool tracking
 - **otel.py** - OpenTelemetry instrumentation exporting to PostHog
 
 ## Run
 
 ```bash
 source .env
 uv run python callback_handler.py
+uv run python agent_middleware.py
 uv run python otel.py
 ```
+
+Use either `PostHogMiddleware` or `CallbackHandler` for an agent invocation, not
+both, to avoid recording duplicate events. Put `PostHogMiddleware` last in the
+middleware list so it records the final model selection and each retry attempt.

examples/example-ai-dspy/uv.lock

@@ -0,0 +1,34 @@
+"""Track a LangChain v1 agent with PostHog middleware."""
+
+import os
+
+from langchain.agents import create_agent
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import tool
+from langchain_openai import ChatOpenAI
+
+from posthog import Posthog
+from posthog.ai.langchain.middleware import PostHogMiddleware
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the weather for a city."""
+    return f"It is sunny in {city}."
+
+
+client = Posthog(
+    os.environ["POSTHOG_API_KEY"],
+    host=os.environ.get("POSTHOG_HOST", "https://us.i.posthog.com"),
+)
+agent = create_agent(
+    model=ChatOpenAI(model="gpt-4.1-mini"),
+    tools=[get_weather],
+    middleware=[PostHogMiddleware(client, distinct_id="example-user")],
+)
+
+result = agent.invoke(
+    {"messages": [HumanMessage(content="What is the weather in Berlin?")]}
+)
+print(result["messages"][-1].content)
+client.shutdown()