Publish a compatibility matrix and support policy #220

Summary

Document, in one place, exactly what the project supports and tests: Python
versions (tested 3.10–3.12 today; target 3.10–3.14 per #113), dependency ranges
(httpx, pydantic), extras and their version envelopes (mcp SDK, otel, yaml/toml,
tiktoken), OS coverage, and how long each is supported — with CI as the
enforcement reference.

Why this matters

Adoption decisions in teams hinge on compatibility confidence: "does this work with
our Python 3.12 + pydantic v2 pin + current mcp SDK?" Today the answer requires
reading pyproject.toml and CI YAML. A published matrix converts that research
into a glance, and the support-policy half ("we test X in CI; Y is best-effort")
sets honest expectations that prevent breakage surprises. This complements #113
(which widens the range) by communicating whatever the range is, and it gives
the stability docs (#145) their compatibility chapter.

Current evidence

• .github/workflows/ci.yml: test matrix covers 3.10–3.12; pyproject.toml declares requires-python = ">=3.10" and extras with ranges (tiktoken>=0.6, etc.).
• Open issue packaging: support Python 3.10–3.14 (inclusive) + library-grade dependency constraints (no forced version pins) #113 targets 3.10–3.14 packaging and library-grade constraints — the matrix would be its public face (referenced, not duplicated).
• No support/compatibility documentation exists in README or docs/.

External context

Compatibility tables and explicit support windows (aligned to upstream Python EOL
schedules) are standard practice for widely adopted libraries.

Proposed implementation

1. Add a "Compatibility" section to README (or docs/compatibility.md linked from
   README): table of Python versions (tested vs supported), core dep ranges,
   extras matrix, platforms exercised in CI.
2. State the policy: what "tested" means (CI matrix), the deprecation approach for
   dropping versions (CHANGELOG + minor release), alignment with [Docs] Publish ROADMAP.md and an API stability / deprecation policy toward 1.0 #145's stability
   policy when it lands.
3. Add a drift guard: a small test or CI step comparing the documented Python
   matrix against ci.yml's actual matrix (parse the workflow file).
4. Update when packaging: support Python 3.10–3.14 (inclusive) + library-grade dependency constraints (no forced version pins) #113 lands (3.13/3.14 rows flip from "planned" to "tested").

AI-agent execution notes

• Inspect first: pyproject.toml (requires-python, deps, extras, classifiers), .github/workflows/ci.yml (matrix), open issue packaging: support Python 3.10–3.14 (inclusive) + library-grade dependency constraints (no forced version pins) #113 text.
• Classifiers in pyproject.toml should agree with the documented matrix — fix mismatches found.
• Edge cases: extras tested only on one Python version (say so honestly).
• Keep wording neutral; promise only what CI demonstrates.

Acceptance criteria

• A compatibility table covering Python, core deps, extras, and platforms exists and matches CI reality.
• The drift guard fails if the documented matrix and CI matrix diverge.
• Trove classifiers agree with the documented versions.

Test plan

The drift guard; classifier consistency check; docs review. Run make ci.

Documentation plan

README/docs page as described; CHANGELOG Added (docs).

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

A published policy is a commitment — scope it to what CI already proves to keep the
cost honest. Maintenance is one row per Python release cycle.

Suggested labels

adoption, documentation, reliability