Add [langfuse] extras and SDK adapter (PR 3.6) (#82)

* Add [langfuse] extras and SDK adapter

Validates the Langfuse observer against the real langfuse>=4.6 SDK
and ships a bridge so production users get the same Protocol-shaped
observer surface as the InMemoryLangfuseClient.

[langfuse] optional-dependency group pins langfuse>=4.6,<5. The v4
SDK is structurally different from v2 / v3 — traces are auto-created
when the first observation starts, span and generation collapse into
start_observation with as_type, trace_id threads through
TraceContext, and trace-level metadata sets via propagate_attributes
context manager. Per Chris's directive ("no existing-user constraint;
do what's right for OA"), the adapter targets v4 only; earlier SDK
versions are out of scope.

LangfuseSDKAdapter wraps the v4 client to satisfy the four-method
LangfuseClient Protocol. Key translations:
- UUID4 invocation_id -> OTel-hex trace_id (32 chars, no dashes).
  v4 fails int(uuid, 16) parsing on the dashed form; OA's observer
  error-isolation pattern swallowed that as a warnings.warn,
  silently dropping traces.
- propagate_attributes(trace_name=, metadata=) runs on EVERY
  observation under each trace_id (not just the first). Without
  this, v4's last-attribute-wins display logic let later
  observations clobber the trace's display name to whatever the
  final observation was called.
- usage values translate from the Protocol's LangfuseUsage record
  to v4's usage_details dict (int values only).
- Returned LangfuseSpan / LangfuseGeneration handles wrap into
  _SpanHandle to expose the .update() / .end() the observer calls.

Trace-info cache persists per trace_id rather than popping on first
observation. Memory is linear in unique trace_ids; a close_trace
cleanup hook is deferred to a future PR.

Tests:
- Five unit tests covering Protocol satisfaction, observer
  construction, trace_info cache lifecycle, update_trace merge,
  UUID4 -> OTel-hex conversion (with idempotency on already-hex and
  non-UUID passthrough).
- One opt-in integration test against real Langfuse Cloud, gated by
  @pytest.mark.integration + LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY
  env vars. Calls auth_check() to fail loud on bad credentials,
  client.shutdown() for synchronous batch-exporter drain. Accepts
  LANGFUSE_HOST or LANGFUSE_BASE_URL for the host.
- New pytest marker config: addopts defaults to "-m not integration"
  so CI auto-skips integration tests; run with -m integration to
  include.

Docs:
- docs/concepts/observability.md flips the "no SDK version validated"
  disclosure to the validated v4 state, shows the LangfuseSDKAdapter
  wire-up snippet.
- docs/examples/10-langfuse-observability.md same.
- examples/10-langfuse-observability/main.py docstring + inline
  comment updated with the production swap recipe.
- AGENTS.md regenerated.

Validated end-to-end against Langfuse Cloud (US region) with
langfuse 4.7.0: a two-node graph produces one Trace with
entry-node-name set as the display name, both nodes as Span
observations under it, and the spec §8.4.1 trace metadata
(correlation_id, entry_node, spec_version) populated.

Fifth of 6 core PRs in the v0.10.0 batch (PR 3.6).

* Align adapter docs with propagate-on-every behavior

Three stale-doc residues from when the adapter consumed trace_info
on the first observation only. The current behavior — propagate on
every observation under each trace_id to avoid v4's last-attribute-
wins display logic clobbering the trace name — got caught by the
integration-test run and the cache+propagation refactored, but
the module header comments and one example-doc paragraph still
described the original "first observation only" path.

Comment / doc text updated; no code change.

Addresses CoPilot PR review feedback on #82.

Author: chris-colinsky

docs/concepts/observability.md

@@ -610,26 +610,55 @@ graph.attach_observer(observer)
 The `client` is anything matching the `LangfuseClient` Protocol —
 the bundled `InMemoryLangfuseClient` (used by the conformance
 harness, useful for unit tests), or a real `langfuse.Langfuse()`
-instance from the [Langfuse Python SDK](https://github.com/langfuse/langfuse-python).
-The Protocol declares only the methods the observer calls, so SDK
-versions whose shape matches drop in directly. SDK versions whose
-shape diverges (renamed kwargs, return-type quirks) plug in via a
-small adapter; see
+instance wrapped in `LangfuseSDKAdapter` for production. Install
+the optional extras to bring in the Langfuse SDK:
+
+```bash
+pip install 'openarmature[langfuse]'
+```
+
+Production wire-up:
+
+```python
+from langfuse import Langfuse
+from openarmature.observability.langfuse import (
+    LangfuseObserver,
+    LangfuseSDKAdapter,
+)
+
+langfuse_client = Langfuse(
+    public_key="pk-lf-...",
+    secret_key="sk-lf-...",
+    host="https://cloud.langfuse.com",
+)
+observer = LangfuseObserver(
+    client=LangfuseSDKAdapter(langfuse_client),
+    disable_llm_payload=False,
+)
+```
+
+The adapter bridges `langfuse>=4.6`'s unified `start_observation`
+API onto our `LangfuseClient` Protocol; the observer code is the
+same in tests and production. See
 [`examples/10-langfuse-observability`](../examples/10-langfuse-observability.md)
-for the runnable demo plus the adapter shape.
+for a runnable demo.
 
 !!! note "Langfuse SDK version compatibility"
 
-    No specific `langfuse` SDK version is validated in CI as of this
-    release. The Protocol mirrors the SDK's documented low-level
-    `trace` / `span` / `generation` shape, but the SDK has shifted
-    between major versions (v2 → v3 introduced API changes). A
-    follow-on release pins a tested `[langfuse]` extras range and
-    ships a runtime `isinstance` check confirming the SDK satisfies
-    the Protocol. Until then, treat production wire-up as a "verify
-    in your own environment" path: bring the langfuse version your
-    stack already uses, run a smoke trace, and write a thin adapter
-    if any kwargs don't line up.
+    Validated against `langfuse>=4.6,<5`. The v4 SDK introduced an
+    OTel-based architecture with `start_observation` /
+    `propagate_attributes` replacing the v2/v3 `trace` / `span` /
+    `generation` low-level API; the bundled `LangfuseSDKAdapter`
+    handles the bridge so the observer surface is stable across
+    future v4 patches.
+
+    Earlier SDK versions (v2.x, v3.x) are NOT supported. Projects on
+    those versions either upgrade to v4 or supply their own adapter
+    matching the `LangfuseClient` Protocol's four methods.
+
+    A runtime `isinstance(adapter, LangfuseClient)` check ships in
+    the unit suite — if a future v4 patch breaks the Protocol's
+    surface, the test fails loudly.
 
 ### What Langfuse sees
 

docs/examples/10-langfuse-observability.md

@@ -114,35 +114,45 @@ Trace id=01234567-89ab-...
 
 ## Swapping to a real Langfuse SDK
 
-The observer's `client` parameter is `LangfuseClient`-Protocol-typed,
-so any structurally-compatible value works:
+Install the optional extras:
+
+```bash
+pip install 'openarmature[langfuse]'
+```
+
+Wrap the SDK client with `LangfuseSDKAdapter` and pass it to the
+observer:
 
 ```python
 from langfuse import Langfuse
+from openarmature.observability.langfuse import (
+    LangfuseObserver,
+    LangfuseSDKAdapter,
+)
 
-client = Langfuse(
+langfuse_client = Langfuse(
     public_key="pk-lf-...",
     secret_key="sk-lf-...",
     host="https://cloud.langfuse.com",
 )
-observer = LangfuseObserver(client=client, disable_llm_payload=False)
+observer = LangfuseObserver(
+    client=LangfuseSDKAdapter(langfuse_client),
+    disable_llm_payload=False,
+)
 ```
 
-If the installed SDK version's `trace` / `span` / `generation` method
-signatures match the Protocol exactly, this is the whole change. If
-they diverge (renamed kwargs, return-type quirks), wrap the SDK in a
-small adapter class that implements `LangfuseClient` and delegates to
-the SDK call-by-call. The Protocol surface is narrow — four methods —
-so the adapter is on the order of 40 lines.
-
-**No specific `langfuse` SDK version is validated in CI as of this
-release.** The Protocol matches the SDK's documented low-level shape,
-but `langfuse` has shifted between major versions (v2 → v3 introduced
-API changes). A follow-on release pins a tested `[langfuse]` extras
-range and a runtime `isinstance(client, LangfuseClient)` check; until
-then, smoke-trace in your own environment with whichever `langfuse`
-version your stack already uses and write a thin adapter if any
-kwargs don't line up.
+The adapter bridges `langfuse>=4.6,<5`'s unified `start_observation`
+API onto OA's four-method `LangfuseClient` Protocol. v4 has no
+explicit trace creation (traces are auto-created from observations);
+the adapter caches trace info from `.trace()` and applies it via
+`propagate_attributes` around EVERY observation under that trace_id.
+Propagating on every observation keeps v4's last-attribute-wins
+display logic from clobbering the trace's display name when later
+observations land without the attribute set.
+
+Validated against `langfuse>=4.6,<5`. v2.x and v3.x are NOT
+supported — supply your own adapter against the same four-method
+Protocol if you need to stay on an older version.
 
 For prompt linkage: in production, the
 `Prompt.observability_entities['langfuse_prompt']` value is the SDK's

examples/10-langfuse-observability/main.py

@@ -21,8 +21,12 @@
 The example uses the bundled ``InMemoryLangfuseClient`` recorder so the
 demo runs without a Langfuse account — at the end we print the captured
 Trace + Observation tree. Swapping to a real ``langfuse.Langfuse()``
-client is a one-line constructor change (see the comment near the
-observer build below).
+client is a one-line constructor change via ``LangfuseSDKAdapter`` (see
+the comment near the observer build below). The adapter bridges the
+``langfuse>=4.6`` Python SDK shape onto OA's ``LangfuseClient``
+Protocol. Install with::
+
+    pip install 'openarmature[langfuse]'
 
 LLM calls go through ``openarmature.llm.OpenAIProvider``.
 
@@ -244,11 +248,18 @@ async def main() -> None:
     # fields — without needing a Langfuse account. For production:
     #
     #     from langfuse import Langfuse
-    #     client = Langfuse(public_key=..., secret_key=..., host=...)
+    #     from openarmature.observability.langfuse import LangfuseSDKAdapter
+    #
+    #     langfuse_client = Langfuse(
+    #         public_key="pk-lf-...",
+    #         secret_key="sk-lf-...",
+    #         host="https://cloud.langfuse.com",
+    #     )
+    #     client = LangfuseSDKAdapter(langfuse_client)
     #
-    # Replace the InMemoryLangfuseClient construction below with that
-    # client. The observer code doesn't change — the client is
-    # Protocol-typed, so any structurally-compatible value works.
+    # Validated against ``langfuse>=4.6,<5``. The adapter bridges
+    # langfuse v4's unified ``start_observation`` API onto OA's
+    # ``LangfuseClient`` Protocol; the observer code doesn't change.
     client = InMemoryLangfuseClient()
 
     # disable_llm_payload=False opts in to capturing the input messages

pyproject.toml

@@ -42,6 +42,13 @@ otel = [
     # below 1.0; revisit when 1.0 lands.
     "opentelemetry-instrumentation-logging>=0.62.0b1",
 ]
+# Spec observability §8 Langfuse mapping. Optional per charter §3.1
+# principle 5; matches the [otel] extras' shape. Validated against
+# Langfuse Python SDK 4.6.x; bridge from the SDK's v4 API onto the
+# LangfuseClient Protocol lives in ``observability.langfuse.adapter``.
+langfuse = [
+    "langfuse>=4.6,<5",
+]
 
 [project.urls]
 Repository = "https://github.com/LunarCommand/openarmature-python"
@@ -105,3 +112,11 @@ select = ["E", "F", "I", "B", "UP"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+# Opt-in markers for tests that hit real external services. CI skips
+# these by default — run with `-m integration` to include them after
+# setting the relevant env vars (LANGFUSE_PUBLIC_KEY / SECRET_KEY for
+# Langfuse Cloud, etc).
+markers = [
+    "integration: tests that exercise real external services (Langfuse Cloud, HyperDX). Skipped by default.",
+]
+addopts = ["-m", "not integration"]

src/openarmature/observability/langfuse/__init__.py

@@ -42,6 +42,18 @@
 )
 from .observer import LangfuseObserver
 
+# LangfuseSDKAdapter requires the [langfuse] optional dependency.
+# Surface it when available, but don't force the import on consumers
+# who only use the InMemoryLangfuseClient — the adapter module's own
+# guard raises an informative ImportError if anyone tries to use it
+# without the extras installed.
+try:
+    from .adapter import LangfuseSDKAdapter as LangfuseSDKAdapter
+
+    _adapter_available = True
+except ImportError:  # pragma: no cover - exercised by extras-not-installed path
+    _adapter_available = False
+
 __all__ = [
     "InMemoryLangfuseClient",
     "LangfuseClient",
@@ -54,3 +66,5 @@
     "ObservationLevel",
     "ObservationType",
 ]
+if _adapter_available:
+    __all__.append("LangfuseSDKAdapter")