feat(instrument): Port LiteLLM provider adapter (M3)

[mmercuri]

Summary

Port of stratix/sdk/python/adapters/llm_providers/litellm_adapter.py (~355 LOC, ateam) into the M3 fan-out at src/layerlens/instrument/adapters/providers/litellm/. Uses the existing providers/openai_adapter.py as the structural template (lifecycle / _emit_* helper usage / ADAPTER_CLASS registry hook), and introduces a subpackage split:

providers/litellm/
├── __init__.py    # Public surface + STRATIX backward-compat alias
├── adapter.py     # LiteLLMAdapter
├── callback.py    # LayerLensLiteLLMCallback (sync + async)
└── routing.py     # detect_provider

LiteLLM is a multi-provider router — a single litellm.completion(...) call is dispatched to one of ~100 providers (OpenAI, Anthropic, Bedrock, Vertex AI, Cohere, Ollama, Together, Groq, HuggingFace, ...). Rather than monkey-patching every provider client, the adapter installs a single callback into litellm.callbacks and lets LiteLLM dispatch it. The routing layer normalises the model string (bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0 → aws_bedrock, gpt-4o → openai, etc.) into the canonical LayerLens provider name so downstream telemetry lines up across every adapter.

Pricing: LiteLLM contributes no new entries to the canonical pricing manifest. The callback calls litellm.completion_cost(...) first (recorded with cost_source: "litellm" when LiteLLM has its own pricing for the model); when LiteLLM cannot price the call it falls through to the canonical PRICING map at providers/_base/pricing.py. The routing layer's normalised provider name carries through to cost.record so Bedrock-routed Anthropic flows through BEDROCK_PRICING, not direct PRICING.

STRATIX* aliased to LayerLens* for backward-compat with ateam users; stratix.* paths translated to layerlens.*. The legacy flat providers/litellm_adapter.py is kept as a thin re-export so existing imports keep working.

Files

• src/layerlens/instrument/adapters/providers/litellm/__init__.py (new, public surface + alias)
• src/layerlens/instrument/adapters/providers/litellm/adapter.py (new, lifecycle)
• src/layerlens/instrument/adapters/providers/litellm/callback.py (new, sync + async callbacks)
• src/layerlens/instrument/adapters/providers/litellm/routing.py (new, detect_provider)
• src/layerlens/instrument/adapters/providers/litellm_adapter.py (now thin re-export)
• src/layerlens/instrument/adapters/providers/__init__.py (PEP 562 lazy __getattr__ for LiteLLMAdapter)
• tests/instrument/adapters/providers/test_litellm.py (new, 38 tests; supersedes test_litellm_adapter.py)
• tests/instrument/adapters/providers/test_litellm_adapter.py (deleted)
• samples/instrument/providers/litellm/{__init__.py,main.py,README.md} (new, mocked-by-default sample)
• docs/adapters/providers-litellm.md (rewritten — subpackage layout + pricing inheritance)

pyproject.toml already carried providers-litellm = ["litellm>=1.40,<2"] from the M1.B port — no version bump needed.

Test plan

• uv run pytest tests/instrument/adapters/providers/test_litellm.py -x — 38/38 pass
• uv run mypy --strict src/layerlens/instrument/adapters/providers/litellm — clean (4 source files)
• uv run ruff check src/.../providers/litellm src/.../providers/__init__.py src/.../providers/litellm_adapter.py tests/.../test_litellm.py — clean
• uv run pytest tests/instrument/adapters/providers/ -x (no live tests) — 137/137 pass (no regression on sibling provider tests)
• uv run pytest tests/instrument/test_lazy_imports.py::test_layerlens_import_does_not_pull_frameworks tests/instrument/test_lazy_imports.py::test_instrument_import_does_not_pull_frameworks tests/instrument/test_default_install.py — 5/5 pass
• python -m samples.instrument.providers.litellm.main — runs offline, emits 12 events across 6 routing scenarios

Routing coverage

Every prefix listed in the M3 PR description gets a parametrised test:

Model string	Provider
gpt-4, gpt-4o, o1-mini, o3-mini	openai
openai/gpt-4o-mini	openai
claude-3-5-sonnet, anthropic/claude-3-5-sonnet	anthropic
azure/my-deployment	azure_openai
bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0	aws_bedrock
vertex_ai/gemini-1.5-pro, gemini-2.0-flash	google_vertex
ollama/llama3	ollama
cohere/command-r	cohere
huggingface/..., together_ai/..., groq/...	matched 1:1
llama-3.1-70b	meta
mistral-large	mistral
empty / unrecognised	unknown

Notes for review

• Test file is test_litellm.py (not _adapter.py) per the task spec; old test removed.
• Async callbacks (async_log_*_event) delegate to the sync handlers — LiteLLM hands the async dispatch the same kwargs/response_obj shape, so no separate logic. The acompletion test exercises this path with an AsyncMock.
• connect() degrades cleanly when litellm is missing (status DEGRADED, no crash) — covered by test_connect_degraded_when_litellm_missing.
• The PEP 562 __getattr__ shim on providers/__init__.py was the simplest way to expose providers.LiteLLMAdapter at the package level without breaking the lazy-import contract; the eager if TYPE_CHECKING: import is for static analysers only.