"""Basic experiment example: bucket a visitor into a variation.

Run it::

python examples/basic_experience.py

Initializes from direct config (offline), creates a visitor-scoped context, and

evaluates an experience. ``run_experience`` returns a typed ``ExperienceResult``

when the visitor qualifies and buckets into a variation, or ``None`` for a normal

miss — it never raises for normal outcomes.

Framework-agnostic: plain Python, no web framework required.

"""

from __future__ import annotations

from typing import Any, Dict, Optional

from convert_sdk import Core, SDKConfig

try: # Runnable both as a script (python examples/x.py) and as a package import.

from examples._sample_config import SAMPLE_CONFIG

except ModuleNotFoundError: # pragma: no cover - script-invocation fallback

import sys

from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from examples._sample_config import SAMPLE_CONFIG

def run(visitor_id: str = "visitor-001") -> Optional[Dict[str, Any]]:

"""Evaluate the sample experiment for ``visitor_id``.

Returns a small summary dict for the bucketed variation, or ``None`` for a

normal miss.

"""

core = Core(SDKConfig(data=SAMPLE_CONFIG)).initialize()

context = core.create_context(visitor_id)

result = context.run_experience("checkout-experiment")

core.close()

if result is None:

return None

return {

"experience_key": result.experience_key,

"variation_key": result.variation_key,

"variation_id": result.variation_id,

}

if __name__ == "__main__":

summary = run()

if summary is None:

print("Visitor did not bucket into a variation (normal miss).")

else:

print("Experience:", summary["experience_key"])

print("Bucketed variation:", summary["variation_key"])