integrations/langfuse/v0.1.0

# Release Notes for langfuse-memanto v0.1.0

First release of `langfuse-memanto` — the Langfuse integration for Memanto. Langfuse records what went wrong; Memanto remembers the lesson. This package connects them, turning failing spans into durable memories your agents can recall instead of re-learning the same failure on every run. It ships as an OpenTelemetry span processor that attaches alongside Langfuse's own, so no instrumentation changes are needed, and it shares its grouping rules and sync ledger with `memanto migrate langfuse` — the live and batch paths write identical memories and never duplicate each other.

## New Features
- **Live span capture** (`langfuse_memanto/handler.py`)
  - `attach(agent_id="my-agent")` after `Langfuse()` — one line, no decorators, no call-site changes.
  - Registers a second `SpanProcessor` on the tracer provider Langfuse already configured; never calls the Langfuse API.
  - No dependency on the `langfuse` package itself — only the `opentelemetry-sdk` it already brings.
- **One memory per error signature**
  - Observations group by operation name plus a message with volatile parts (ids, numbers, emails, IPs, paths, quoted strings) normalized away, so a retry storm collapses to a single memory.
  - Confidence rises with recurrence: `min(0.95, 0.60 + 0.15 × log₁₀(occurrences))`.
  - Entirely rule-based — no LLM calls, no token cost.
- **Zero-setup onboarding**
  - Works from a bare `MOORCHEH_API_KEY`; the target agent is created and activated on the first write.
  - Opt out with `auto_create_agent=False` or `MEMANTO_LANGFUSE_AUTO_CREATE_AGENT=false`.
- **Capture rules in code or shared from the CLI**
  - `attach(capture=[...], latency_ms=..., cost_usd=..., score_fail=[...], score_pass=[...], group_by=...)`.
  - Anything omitted falls back to the per-project profile in `~/.memanto/migrate/langfuse/config.json` written by `memanto migrate langfuse --save`, so a team can manage rules centrally.
  - Invalid settings raise at `attach()` rather than silently capturing nothing.
- **Shared sync ledger** (`memanto>=0.2.14`)
  - Writes are recorded in `~/.memanto/migrate/langfuse/state.json`, scoped by Langfuse project *and* destination agent, so a later `memanto migrate langfuse` sees them as already stored.
  - Project identity is derived from `LANGFUSE_API_KEY` or `LANGFUSE_PUBLIC_KEY`, matching how the CLI resolves it.
- **Operational surface**
  - `flush()`, `stats()`, `shutdown()`, plus an `atexit` hook and OpenTelemetry's `force_flush()`.
  - Startup warnings name any configured mode that cannot fire live, instead of capturing nothing quietly.

## Improvements
- **Application safety** (`langfuse_memanto/handler.py`)
  - Nothing runs on the hot path: `on_end` maps and buffers; grouping and network I/O happen on a daemon thread.
  - Every entry point swallows its own exceptions — a memory that fails to write can never break the traced application.
  - Buffer is bounded; drops during a storm are counted in `stats()["dropped"]`.
- **Failed writes are retried, not discarded**
  - A batch that fails is retained and retried; reconciliation makes the retry idempotent. Abandoned after 4 consecutive failures so a dead backend cannot grow memory.
- **Concurrency-safe ledger writes**
  - `flush()` is serialized, so the background worker and an application calling `flush()`/`shutdown()` cannot overwrite each other's recorded signatures.
- **Span mapping pinned to the SDK's own constants** (`langfuse_memanto/span_mapper.py`)
  - Attribute names are read from `langfuse.LangfuseOtelSpanAttributes` when available, with verified literals as a fallback; nanosecond OTel timestamps are converted to the ISO form the shared rules expect.
- **Clear failure on an incompatible core** (`langfuse_memanto/__init__.py`)
  - Importing against a `memanto` older than 0.2.14 raises an `ImportError` naming the required version, rather than a `ModuleNotFoundError` from Memanto internals at `attach()` time.

## Known Limits
- `low-score` and `success` cannot be captured live — Langfuse attaches scores *after* a trace ends. Use `memanto migrate langfuse` for those.
- `costly` only fires live if your application sets `cost_details` on the observation; Langfuse otherwise computes cost server-side after ingestion.
- Percentile budgets need a population to calibrate against and are ignored live; give `slow` an absolute `latency_ms`.

## Requirements
- Python **3.10+**, `memanto>=0.2.14`, and `langfuse>=3` in your application (verified against **3.15.0** and **4.14.3**).

## Tests
- 47 tests covering span mapping, signature grouping, capture-rule precedence, agent auto-provisioning, buffer bounds, retry-on-failure, concurrent flushes, and application-safety guarantees — run against both `langfuse` 3.x and 4.x. Integration tests now gate the release workflow before build and publish.

## Full Changelog
Full Changelog: https://github.com/moorcheh-ai/memanto/commits/integrations/langfuse/v0.1.0