feat: experimentation surface — track_event, track_exposure_event, get_experiment_flag

[gagantrivedi]

Summary

Adds an experimentation-events surface to the SDK and rewires the underlying processor end-to-end. Wire schema agreed in Flagsmith/flagsmith-analytics-pipeline#9.

New public API on Flagsmith:

• track_event(event, identifier=None, value=None, traits=None, metadata=None, timestamp=None) — record arbitrary product events (e.g. "purchase").
• track_exposure_event(feature_name, identifier=None, value=None, traits=None, metadata=None, timestamp=None) — record that an identity was exposed to a flag/variant. Internally emits an event with the reserved name $flag_exposure.
• get_experiment_flag(feature_name, identifier, traits=None) -> Flag | DefaultFlag — resolves an identity flag and fires track_exposure_event (skipped when the resolved flag is a DefaultFlag).

Opt-in via constructor:

Flagsmith(
    environment_key="...",
    enable_events=True,                          # gate
    event_processor_config=EventProcessorConfig( # optional tuning (URL override, buffer/flush)
        events_api_url="https://my-self-host/",
    ),
)

• Default events_api_url: https://events.api.flagsmith.com/ (verified live).
• event_processor_config without enable_events=True raises ValueError (no silent no-ops).
• Without enable_events=True, any of the three new methods raise ValueError.

Wire payload (POST {events_api_url}/v1/events):

{
  "events": [
    {
      "event": "purchase",                    // or "$flag_exposure" for exposures
      "feature_name": null,                   // populated only for $flag_exposure
      "identifier": "user_42",
      "value": 99.5,
      "traits": {"plan": "premium"},
      "metadata": {"sdk_version": "...", ...},
      "timestamp": 1748462400000
    }
  ]
}

Auth: X-Environment-Key header (Redis-validated server-side).

Internals:

• New EventProcessor (renamed from PipelineAnalyticsProcessor) with batched async flush via FuturesSession. Defaults: 1000-item buffer, 10s timer. Re-queues on failure.
• EventProcessorConfig (renamed from PipelineAnalyticsConfig) — fields: events_api_url (default = cloud), max_buffer_items=1000, flush_interval_seconds=10.0.
• _initialise_analytics split into two narrow methods: _initialise_analytics (legacy AnalyticsProcessor only) and _initialise_events (new EventProcessor only).
• Removed record_evaluation_event and its per-flag autocapture in Flags.get_flag — flag-evaluation events are no longer auto-emitted; opt back in via an OpenFeature after hook at the provider layer if desired.
• Removed now-dead _pipeline_analytics_processor / _identity_identifier / _traits fields on Flags and their constructor kwargs.

Breaking changes

• PipelineAnalyticsProcessor → EventProcessor; PipelineAnalyticsConfig → EventProcessorConfig.
• Flagsmith(pipeline_analytics_config=…) → Flagsmith(enable_events=True, event_processor_config=…).
• EventProcessorConfig.analytics_server_url → events_api_url.
• EventProcessor.record_custom_event → track_event; signature reshaped (event, identifier, value, traits, metadata, timestamp).
• EventProcessor.record_evaluation_event removed.
• Wire payload reshaped: event_id → event, evaluated_at → timestamp, identity_identifier → identifier; event_type, enabled, and top-level body environment_key dropped; feature_name added as a top-level field. Endpoint changed from /v1/analytics/batch to /v1/events.
• Flag-evaluation autocapture is no longer emitted by this client.

Test plan

• poetry run pytest — 99 passed locally.
• Verified https://events.api.flagsmith.com/health returns {"status":"healthy"}.
• Verified POST https://events.api.flagsmith.com/v1/events with a bogus env key returns 403 Unknown environment key (auth + route wired).
• CI green.
• Manual smoke against staging: Flagsmith(environment_key=…, enable_events=True).track_event("purchase", identifier="user_1", value=99.5) → event lands in pipeline.
• Manual smoke: get_experiment_flag(feature_name=…, identifier=…) returns the Flag, emits exactly one $flag_exposure event, and skips emission for DefaultFlag.

[Zaimwa9]

Looks good to me, agreed on the schema knowing it's open. One question around complete flag evaluations.
I'm open to drop it entirely personally.

Otherwise approvable as of, just need to port it to openfeature as you mentioned

[Copilot]

Pull request overview

Adds the new experimentation events surface to the SDK, replacing the prior pipeline analytics API with explicit custom-event and flag-exposure tracking.

Changes:

• Introduces EventProcessor / EventProcessorConfig and the new /v1/events payload shape.
• Adds Flagsmith.track_event, track_exposure_event, and get_experiment_flag.
• Removes automatic per-flag pipeline evaluation event capture and updates tests/fixtures for the new events API.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
flagsmith/analytics.py	Replaces pipeline analytics processor/config with event processor/config and new event payload/flush endpoint.
flagsmith/flagsmith.py	Wires event processor construction and adds the new public event/experiment methods.
flagsmith/models.py	Removes pipeline analytics state and automatic evaluation-event recording from Flags.
flagsmith/__init__.py	Re-exports EventProcessorConfig instead of PipelineAnalyticsConfig.
tests/conftest.py	Renames analytics fixtures to event processor fixtures.
tests/test_event_processor.py	Adds coverage for buffering, flushing, failure requeue, and lifecycle behavior of the new processor.
tests/test_flagsmith.py	Updates client-level tests for event gating, delegation, and experiment exposure tracking.
tests/test_pipeline_analytics.py	Deletes tests for the removed pipeline analytics behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Zaimwa9]

Couple of minor comments (except the timestamp). Server-side it looks less important but still wondering whether we shouldn't deduplicate (at least in the same buffer) the exposure events.
That might be just a client issue (deal with re-rendering etc).

[Zaimwa9]

Thanks 👍