AI_Index

Python SDK Wiki — AI Agent Index

This index helps AI agents find the right documentation page without reading the entire wiki. Read this file first, then load only the specific pages relevant to your task.

Page Origin

This wiki contains two types of pages:

• Shared docs (lowercase-hyphenated filenames) — Synced from the canonical source in the backend repo at backend/public/js/tracking/full-stack-docs/ (concepts/ and guides/ subdirs). These cover cross-SDK concepts and are identical across the JS, PHP, and Python SDK wikis. Do not edit them here — edits will be overwritten on the next sync.
• Python-specific docs (CamelCase filenames) — Written for this SDK only: quickstart, installation, configuration, type hints, code examples, diagnostics, extending, testing, async design, migration, roadmap, release process.

Getting Started

Page	When to read
How Convert Works	High-level overview of the Convert platform and SDKs
Architecture Overview	System architecture, module relationships, data flow
Data Model Reference	Entity relationships: Experience, Variation, Feature, Variable, Goal, Audience, Location
Quickstart Overview	Cross-SDK quickstart concepts before diving into Python-specific setup
Requirements & Constraints	SDK limitations, environment requirements, known constraints

Python SDK Reference

Page	When to read
Quickstart	5-minute Python setup and first experiment
Installation	Install via pip, uv, or Poetry — Python 3.9+ required
Initialization	SDK Key vs. direct config, sync init, opt-in RefreshConfig
Configuration	Field-by-field reference for SDKConfig, TransportConfig, TrackingConfig, RefreshConfig
Code Examples	Complete examples for every public method on Core and Context
Type Hints	Frozen dataclasses, Protocols, enums, error hierarchy
Diagnostics	Logging, error codes, diagnose_* methods, support workflows
Extending	Custom Transport, DataStore, EventBus Protocols
Testing	pytest patterns, parity fixtures, mypy, CI gates
Async and Framework Integrations	Phase 3 design intent — AsyncCore, Django/FastAPI/Flask helpers

Migration

Page	When to read
From JavaScript SDK	Concept map, side-by-side examples, refresh-default differences
From Raw REST	Replacing manual httpx calls; bucketing, batching, dedup wins

Core Concepts (Shared)

Page	When to read
Experiences & Variations	A/B test structure, variation assignment, activation
Feature Flags	Feature flag evaluation, variable values, feature status
Bucketing Algorithm	Hash-based visitor assignment, traffic allocation, deterministic bucketing
Rule Evaluation & Targeting	Audience matching, location matching, scheduling rules
Segments	Visitor segmentation logic and custom segments
Data Management	Data access layer, project config, entity lookups
Event System	Event pub/sub, lifecycle hooks, custom events
API Communication & Tracking	HTTP communication, config fetching, event tracking, queue management

How-To Guides (Shared)

Page	When to read
Running Experiences	End-to-end guide: activate experiments, get variations for a visitor
Running Features	Feature flag usage: evaluate flags, get variable values
Tracking Conversions	Goal tracking, conversion events, revenue tracking
Visitor Context & Properties	Visitor identification, custom properties, cross-session persistence
Persistent DataStore	Custom data store integration for visitor state persistence
Troubleshooting	Common cross-SDK issues, debugging techniques

Edge & Integrations (Shared)

Page	When to read
LLM / AI Testing	Server-side A/B testing for LLM prompts and responses via llms.txt

Maintainers

Page	When to read
Roadmap	Phase 1 (MVP shipped), Phase 2 (long-running), Phase 3 (async + frameworks)
Release Process	CI gates, dependency bounds, tag-driven publish to PyPI via OIDC

Module Dependency Map

Core
  ├── creates → Context
  ├── fetches config via → Transport
  ├── owns → TrackingQueue
  ├── fires events via → EventBus
  └── (opt-in) spawns → ConfigRefresher
ConfigRefresher
  ├── refreshes via → Transport
  └── swaps → ConfigSnapshot
Context
  ├── runs experiments via → evaluation.experiences
  ├── runs features via → evaluation.features
  ├── reads/writes via → DataStore
  └── releases via → TrackingQueue
evaluation.experiences / evaluation.features
  ├── buckets via → evaluation.bucketing (MurmurHash3 32-bit, seed 9999)
  └── matches rules via → evaluation.rules
TrackingQueue
  ├── delivers via → Transport
  └── fires events via → EventBus