feat: AI lane config and size-aware batching

[eli-r-ph]

💡 Motivation and Context

The AI lane (capture_ai, /i/v1/ai/events) shared the analytics lane's queue size and timeout, sent uncompressed with no way to change it, and used an 8 MiB guard on the whole serialized event. The endpoint applies its 8 MiB ceiling to properties alone, so the SDK refused some events the endpoint accepts. Batches also appended an event before checking the byte limit, so a request could carry about 13 MiB.

New Client keyword arguments (AI lane only):

• capture_ai_compression: default none. POSTHOG_CAPTURE_COMPRESSION does not apply, so analytics compression never changes AI uploads.
• capture_ai_max_queue_size: default 1000.
• capture_ai_timeout: default 30s.
• capture_ai_max_event_bytes: default 8 MiB plus 64 KiB of envelope headroom. It can only be lowered.

These follow posthog-go's v1 defaults (CaptureAICompression, CaptureAIMaxQueueSize, CaptureAIBatchUploadTimeout, and the aiMaxEventBytes + aiEnvelopeHeadroom guard). Invalid values raise ValueError at construction. The 5 MiB AI batch target stays a constant.

Behavior changes:

• Batching checks the byte limit before appending, on both lanes. An event that does not fit goes back to the head of the queue for the next batch. An event larger than the target goes alone, as in go. Keeping the event in the queue, not in the consumer, means stop, discard and fork already account for it.
• sync_mode applies the lane's size guard and timeout. The AI lane's capture_ai_timeout and size guard now apply to sync sends. This also adds the 900 KiB guard to sync analytics sends, which matches AsyncPosthog.capture_immediate.
• flush() and shutdown signal every lane to drain before waiting on any of them. Before, the AI lane kept its normal batching cadence while the client waited on the analytics lane. The flush budget did not change.

sdk-specs / cross-SDK:

• posthog-go and posthog-rs keep the AI per-event cap as a constant. Go's aiLaneConfig comment says Python does too, which this PR changes. Only the lower-only event cap is public; the batch target stays constant.
• Module-level config (posthog.<knob> = ...) does not get the new knobs, same as capture_compression.

💚 How did you test it?

• Consumer: a parameterized test covers check-before-append, return to the queue head, an oversize event going alone, and task accounting.
• AI lane:
  • config defaults and configured values
  • POSTHOG_CAPTURE_COMPRESSION isolation
  • invalid config
  • size guard at the properties ceiling, over the guard, and over a lowered cap
  • the sync-mode guard
  • per-lane timeout and compression in sync mode
  • flush() draining the AI lane while an analytics upload is blocked
• Break-on-purpose: each new behavior was removed in turn: append-then-check, tail requeue, the drain overlap, the headroom, the sync timeout, env isolation and the sync guard. The matching test failed every time.
• I ran ruff, mypy (baseline), the full pytest suite, the adapter tests, python -W error -c "import posthog", the public API snapshot and uv lock --check.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file

Covered by the existing capture-v1-major changeset; the migration guide lands later in this stack.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written with Cursor (Claude Opus) under the direction of the assignee.

Agreed before implementation:

• public AI compression, queue and timeout knobs
• only the event cap public (lower-only), with the batch target kept constant

Agent calls worth review:

• applying the size guard to sync-mode analytics sends
• requeueing to the head of the queue instead of carrying the event in the consumer
• the drain overlap
• integer-only validation for the byte and queue knobs

[github-actions]

posthog-python Compliance Report

Date: 2026-10-07T17:48:29.214405+00:00
Duration: 246790ms

✅ All Tests Passed!

116/116 tests passed

---

Capture_V1 Tests

✅ 95/95 tests passed

View Details

Test	Status	Duration
Endpoint And Method.Targets V1 Endpoint	✅	514ms
Endpoint And Method.Does Not Use Legacy Endpoints	✅	509ms
Required Headers.Has Authorization Bearer Header	✅	508ms
Required Headers.Has Content Type Json	✅	508ms
Required Headers.Has Posthog Sdk Info Format	✅	508ms
Required Headers.Has Posthog Attempt Header	✅	508ms
Required Headers.Has Posthog Request Id	✅	508ms
Required Headers.Has Posthog Request Timestamp	✅	507ms
Required Headers.Has User Agent	✅	510ms
Body Format.Body Has Created At And Batch	✅	516ms
Body Format.No Api Key In Body	✅	507ms
Body Format.No Sent At In Body	✅	507ms
Event Format.Event Has Required Root Fields	✅	507ms
Event Format.Event Uuid Is Valid	✅	508ms
Event Format.Event Timestamp Is Rfc3339	✅	508ms
Event Format.Non Utc Event Timestamp Is Converted To Utc	✅	512ms
Event Format.Distinct Id Is String	✅	508ms
Event Format.Distinct Id At Root Not Properties	✅	508ms
Event Format.Custom Properties Preserved	✅	508ms
Event Format.Set Properties Preserved	✅	507ms
Event Format.Set Once Properties Preserved	✅	508ms
Event Format.Groups Properties Preserved	✅	508ms
Event Format.Sdk Generates Uuid If Not Provided	✅	508ms
Event Format.Event Has Required Root Fields Batch	✅	510ms
Event Format.Event Uuid Is Valid Batch	✅	510ms
Event Format.Event Timestamp Is Rfc3339 Batch	✅	510ms
Event Format.Distinct Id Is String Batch	✅	511ms
Event Format.Distinct Id At Root Not Properties Batch	✅	510ms
Event Format.Custom Properties Preserved Batch	✅	510ms
Event Format.Set Properties Preserved Batch	✅	510ms
Event Format.Set Once Properties Preserved Batch	✅	510ms
Event Format.Groups Properties Preserved Batch	✅	511ms
Event Format.Sdk Generates Uuid If Not Provided Batch	✅	510ms
Batch Behavior.Multiple Events In Single Batch	✅	512ms
Batch Behavior.Batch Envelope Smoke	✅	511ms
Batch Behavior.Flush With No Events Sends Nothing	✅	505ms
Batch Behavior.Flush At Triggers Batch	✅	1008ms
Batch Behavior.Created At Reflects Batch Creation Time	✅	508ms
Deduplication.Generates Unique Uuids	✅	513ms
Deduplication.Different Events Same Content Different Uuids	✅	510ms
Deduplication.Preserves Uuid On Retry	✅	6512ms
Deduplication.Preserves Timestamp On Retry	✅	6517ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	6519ms
Deduplication.No Duplicate Events In Batch	✅	514ms
Header Behavior On Retry.Attempt Header Starts At One	✅	508ms
Header Behavior On Retry.Attempt Header Increments On Retry	✅	12524ms
Header Behavior On Retry.Request Id Preserved On Retry	✅	6516ms
Header Behavior On Retry.Different Requests Have Different Request Ids	✅	3016ms
Header Behavior On Retry.Request Timestamp Changes On Retry	✅	6516ms
Response Format Validation.Success Response Has Uuid Keyed Results	✅	509ms
Response Format Validation.Success Response Has Ok For Each Event	✅	510ms
Response Format Validation.Success No Retry After When All Ok	✅	510ms
Response Format Validation.Success Retry After Present When Retry Events	✅	1512ms
Response Format Validation.Success No Retry After When Drop Only	✅	509ms
Response Format Validation.Response Echoes Request Id	✅	507ms
Retry Behavior.Retries On 408	✅	6512ms
Retry Behavior.Retries On 500	✅	6512ms
Retry Behavior.Retries On 503	✅	7519ms
Retry Behavior.Retries On 504	✅	6517ms
Retry Behavior.Retryable Errors Have Retry After	✅	3513ms
Retry Behavior.Respects Retry After On Retryable Error	✅	11521ms
Retry Behavior.Does Not Retry On 400	✅	2511ms
Retry Behavior.Does Not Retry On 401	✅	2510ms
Retry Behavior.Does Not Retry On 402	✅	2511ms
Retry Behavior.Does Not Retry On 413	✅	2510ms
Retry Behavior.Does Not Retry On 415	✅	2511ms
Retry Behavior.Non Retryable Errors Have No Retry After	✅	2511ms
Retry Behavior.Implements Backoff	✅	18532ms
Retry Behavior.Max Retries Respected	✅	18532ms
Partial Batch Handling.Handles 200 Full Success	✅	2511ms
Partial Batch Handling.Handles 200 With All Ok	✅	3514ms
Partial Batch Handling.Does Not Retry Dropped Events	✅	3513ms
Partial Batch Handling.Does Not Retry Limited Events	✅	3524ms
Partial Batch Handling.Prunes Ok Events On Partial Retry	✅	6515ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry	✅	6517ms
Partial Batch Handling.Retries Only Retry Events From Partial	✅	6518ms
Partial Batch Handling.Partial Retry Preserves Uuids	✅	6513ms
Partial Batch Handling.Partial Retry Attempt Header Increments	✅	6516ms
Partial Batch Handling.Partial Retry Request Id Preserved	✅	6519ms
Partial Batch Handling.Respects Retry After On Partial	✅	8518ms
Partial Batch Handling.Unknown Result Treated As Terminal	✅	3513ms
Partial Batch Handling.Mixed Ok Drop Limited No Retry	✅	3513ms
Compression.Sends Gzip Content Encoding	✅	509ms
Compression.No Content Encoding When Disabled	✅	508ms
Compression.Compressed Body Is Decompressible	✅	508ms
Error Handling.Does Not Retry On Unknown 4Xx	✅	2511ms
Event Options.Cookieless Mode Override	✅	509ms
Event Options.Disable Skew Correction Override	✅	508ms
Event Options.Process Person Profile Override	✅	509ms
Event Options.Product Tour Id Override	✅	509ms
Event Options.Unset Options Omitted	✅	510ms
Event Options.Options Override In Batch	✅	511ms
Geoip And Historical Migration.Geoip Disable Injected Into Properties	✅	509ms
Geoip And Historical Migration.Historical Migration Set In Body	✅	509ms
Geoip And Historical Migration.Historical Migration Absent By Default	✅	509ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	10ms
Request Payload.Flags Request Uses V2 Query Param	✅	9ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	9ms
Request Payload.Flags Request Omits Authorization Header	✅	9ms
Request Payload.Token In Flags Body Matches Init	✅	9ms
Request Payload.Groups Round Trip	✅	9ms
Request Payload.Groups Default To Empty Object	✅	9ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	10ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	9ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	9ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	508ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	14ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	9ms
Retry Behavior.Retries Flags On 502	✅	312ms
Retry Behavior.Retries Flags On 504	✅	313ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	511ms

Feature_Flags_Local_Evaluation Tests

✅ 4/4 tests passed

View Details

Test	Status	Duration
Versioned Boolean Matching.Matching Version Missing	✅	52ms
Versioned Boolean Matching.Matching Version 1	✅	50ms
Versioned Boolean Matching.Matching Version 2	✅	54ms
Versioned Boolean Matching.Version Only Reload 1 2 1 2 Missing	✅	34ms

[eli-r-ph]

@greptileai review