CLAUDE

CLAUDE.md — Python SDK Wiki

This directory is the published, public wiki for the Python SDK. It contains two categories of pages.

Shared Docs vs Python-Specific Docs

• Shared docs (lowercase-hyphenated filenames, e.g. rule-evaluation.md, data-management.md, segments.md, bucketing-algorithm.md, and everything listed under "Core Concepts (Shared)" / "How-To Guides (Shared)" in AI_Index.md) — Do not edit these files here. They are synced automatically from a canonical source in a private backend repo (path within that repo: public/js/tracking/full-stack-docs/, with concepts/ and guides/ subdirs). The same files also appear in the JavaScript and PHP SDK wikis. Any edit made here will be overwritten on the next sync.

  Caveat at initial commit: the python-sdk has not yet been added to the backend's sync-to-wikis.yml job, so the shared docs in this wiki are a manual one-time copy. Until the workflow targets convertcom/python-sdk, shared-doc updates will not flow in automatically. Even so, the rule stands: edit the canonical source in the backend repo, not this wiki.

• Python-specific docs (CamelCase filenames, e.g. Quickstart.md, Installation.md, Initialization.md, Configuration.md, CodeExamples.md, TypeHints.md, Diagnostics.md, Extending.md, AsyncAndFrameworks.md, MigrationFromJavascript.md, MigrationFromRest.md, ReleaseProcess.md) — These are Python-only and are edited directly in this wiki.

Decision Rule Before Editing Anything

1. Check the filename.
   • Lowercase-hyphenated → shared → edit the canonical source in the backend repo (public/js/tracking/full-stack-docs/) instead.
   • CamelCase → Python-specific → edit here.
2. AI_Index.md and this CLAUDE.md are wiki-specific and edited here.

Writing Rules for Shared Docs (Public Audience)

This wiki is public. The JavaScript and PHP SDK wikis are also public. The backend wiki and the backend repo are private. When editing any shared doc at its canonical source (in the backend repo, under public/js/tracking/full-stack-docs/):

1. Never reference the private backend wiki or any private repo. No links to backend.wiki/*, no "see the backend wiki for details." If the content is needed, inline it; otherwise omit.
2. Never reference internal backend filesystem paths (backend/public/..., backend/apiDoc/..., backend/src/..., etc.) — readers don't have that tree. Use package names (convert_sdk.evaluation, convert_sdk.tracking, convert_sdk.ports) and class/method names. For public specs, link to a known-valid URL (e.g. https://api.convert.com/doc/v2/...).
3. Never invent URLs. Guessed GitHub wiki URLs (https://github.com/<org>/<repo>/wiki/<page>) are a particularly common failure — org, repo, slug, and casing are all likely wrong. If you don't know the URL is correct, don't write it. Prefer relative links within the shared docs (e.g. [RuleManager](rule-evaluation)); the sync pipeline rewrites them to each wiki's URL.
4. Prefer package-level references over file paths and line numbers. convert_sdk.evaluation.bucketing.get_bucket_value ages better than src/convert_sdk/evaluation/bucketing.py:120-145.

The canonical source directory has its own CLAUDE.md restating these rules for anyone editing in place.

Writing Rules for Python-Specific Docs

When editing a CamelCase page in this wiki:

1. Snake-case in code, CamelCase in page names. Public Python symbols are snake_case (run_experience, track_conversion, is_ready); wiki page filenames are CamelCase (Quickstart, CodeExamples).
2. Same-wiki links use bare page names. [Initialization](Initialization) resolves correctly within the wiki without an absolute URL. Use absolute URLs only when crossing to the JS or PHP SDK wiki.
3. Prefer importing from the top-level package. from convert_sdk import Core, SDKConfig is the public surface. Reach into convert_sdk.config, convert_sdk.domain.*, or convert_sdk.ports.* only when documenting a stable internal type that custom adapters need (e.g., ContextState, ConfigSnapshot, RefreshConfig).
4. Phase-3 features are design intent, not API. AsyncCore, convert-sdk-django, convert-sdk-fastapi, convert-sdk-flask are not importable today. Treat them as planned shape, not instructions. The MVP is sync-first and that surface is permanent.
5. No file-path/line-number references. Use module names and identifiers — they survive refactors. If a reader genuinely needs the source, they'll grep or open the GitHub repo.