forgesight-langfuse 0.1.0__tar.gz

forgesight_langfuse-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_langfuse-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: forgesight-langfuse
+Version: 0.1.0
+Summary: ForgeSight Langfuse exporter — OTLP ingest with native langfuse.* observation mapping.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,forgesight,langfuse,llm,observability,otlp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Requires-Dist: forgesight-otel
+Description-Content-Type: text/markdown
+
+# forgesight-langfuse
+
+The Langfuse exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Ships ForgeSight records to Langfuse over its OTLP ingest endpoint
+(`/api/public/otel`, Basic auth), enriched with the native **`langfuse.*`**
+attributes so LLM calls render as **generation** observations, tools as **tool**
+observations, and the run's `user`/`session`/`tags` lift to the trace.
+
+```bash
+pip install forgesight-langfuse
+```
+
+```python
+import forgesight
+from forgesight_langfuse import LangfuseExporter
+
+forgesight.configure(exporters=[
+    LangfuseExporter(public_key="pk-lf-...", secret_key="sk-lf-...",
+                     host="https://cloud.langfuse.com"),
+])
+```
+
+Or by name: `exporters: [{name: langfuse, config: {public_key: …, secret_key: …}}]`.
+
+## Two paths
+
+- **First-party (this package):** native `langfuse.*` observation mapping + the SDK's
+  computed cost (`forgesight.usage.cost_usd`) ingested.
+- **OTLP-native (no package):** point `forgesight-otel` at
+  `https://cloud.langfuse.com/api/public/otel` with `Authorization: Basic base64(pk:sk)`.
+
+Prompt/response content is captured only with `capture_content=True` (off by default).
+
+## License
+
+Apache-2.0

forgesight_langfuse-0.1.0/README.md

@@ -0,0 +1,36 @@
+# forgesight-langfuse
+
+The Langfuse exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Ships ForgeSight records to Langfuse over its OTLP ingest endpoint
+(`/api/public/otel`, Basic auth), enriched with the native **`langfuse.*`**
+attributes so LLM calls render as **generation** observations, tools as **tool**
+observations, and the run's `user`/`session`/`tags` lift to the trace.
+
+```bash
+pip install forgesight-langfuse
+```
+
+```python
+import forgesight
+from forgesight_langfuse import LangfuseExporter
+
+forgesight.configure(exporters=[
+    LangfuseExporter(public_key="pk-lf-...", secret_key="sk-lf-...",
+                     host="https://cloud.langfuse.com"),
+])
+```
+
+Or by name: `exporters: [{name: langfuse, config: {public_key: …, secret_key: …}}]`.
+
+## Two paths
+
+- **First-party (this package):** native `langfuse.*` observation mapping + the SDK's
+  computed cost (`forgesight.usage.cost_usd`) ingested.
+- **OTLP-native (no package):** point `forgesight-otel` at
+  `https://cloud.langfuse.com/api/public/otel` with `Authorization: Basic base64(pk:sk)`.
+
+Prompt/response content is captured only with `capture_content=True` (off by default).
+
+## License
+
+Apache-2.0

forgesight_langfuse-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "forgesight-langfuse"
+version = "0.1.0"
+description = "ForgeSight Langfuse exporter — OTLP ingest with native langfuse.* observation mapping."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "langfuse", "llm", "ai-agents", "forgesight", "otlp"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "forgesight-otel"]
+
+[project.entry-points."forgesight.exporters"]
+langfuse = "forgesight_langfuse.exporter:LangfuseExporter"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_langfuse"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }
+forgesight-otel = { workspace = true }

forgesight_langfuse-0.1.0/src/forgesight_langfuse/__init__.py

@@ -0,0 +1,9 @@
+"""ForgeSight Langfuse exporter — OTLP ingest with native langfuse.* observation mapping."""
+
+from __future__ import annotations
+
+from .exporter import LangfuseExporter, basic_auth_header
+
+__version__ = "0.1.0"
+
+__all__ = ["LangfuseExporter", "__version__", "basic_auth_header"]

forgesight_langfuse-0.1.0/src/forgesight_langfuse/exporter.py

@@ -0,0 +1,105 @@
+"""``LangfuseExporter`` — ForgeSight records → Langfuse via OTLP + ``langfuse.*`` attrs.
+
+Wraps ``forgesight-otel``'s ``OTelExporter`` pointed at Langfuse's OTLP ingest endpoint
+(``/api/public/otel``, HTTP, Basic auth) and enriches each record with the native
+``langfuse.*`` attributes Langfuse reads (observation type; trace name / user / session /
+tags). LLM calls land as ``generation`` observations, tools as ``tool`` observations,
+steps as ``span`` — with the SDK's computed ``forgesight.usage.cost_usd`` ingested.
+
+Content (prompts/completions) is captured only when ``capture_content`` is on (P7).
+``export`` never raises (P6). Runs on the pipeline worker, never the hot path.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence
+from dataclasses import replace
+from types import MappingProxyType
+
+from opentelemetry.sdk.trace.export import SpanExporter
+
+from forgesight_api import ExportResult, Kind, Record
+from forgesight_otel import OTelExporter
+
+_REGION_HOSTS = {
+    "us": "https://us.cloud.langfuse.com",
+    "eu": "https://cloud.langfuse.com",
+}
+_OBSERVATION_TYPE = {
+    Kind.AGENT: "agent",
+    Kind.WORKFLOW: "chain",
+    Kind.STEP: "span",
+    Kind.LLM: "generation",
+    Kind.TOOL: "tool",
+    Kind.MCP: "tool",
+}
+# business-metadata keys lifted to trace-level langfuse attributes (on the root span)
+_TRACE_LIFTS = {
+    "user_id": "langfuse.user.id",
+    "session_id": "langfuse.session.id",
+    "tags": "langfuse.trace.tags",
+}
+
+LANGFUSE_OBSERVATION_TYPE = "langfuse.observation.type"
+LANGFUSE_TRACE_NAME = "langfuse.trace.name"
+
+
+def basic_auth_header(public_key: str, secret_key: str) -> str:
+    """Return the ``Basic base64(pk:sk)`` value Langfuse's OTLP endpoint expects."""
+    token = base64.b64encode(f"{public_key}:{secret_key}".encode()).decode("ascii")
+    return f"Basic {token}"
+
+
+def otlp_traces_endpoint(host: str) -> str:
+    """Langfuse's OTLP/HTTP traces URL: the ``/v1/traces`` signal under ``/api/public/otel``.
+    The signal path is required — posting to the bare ``/api/public/otel`` base 404s."""
+    return f"{host.rstrip('/')}/api/public/otel/v1/traces"
+
+
+class LangfuseExporter:
+    """Export records to Langfuse over OTLP with native ``langfuse.*`` enrichment."""
+
+    def __init__(
+        self,
+        *,
+        public_key: str,
+        secret_key: str,
+        host: str | None = None,
+        region: str | None = None,
+        capture_content: bool = False,
+        span_exporter: SpanExporter | None = None,
+    ) -> None:
+        if not public_key or not secret_key:
+            raise ValueError("LangfuseExporter requires public_key and secret_key")
+        resolved_host = host or _REGION_HOSTS.get((region or "").lower(), _REGION_HOSTS["eu"])
+        self._host = resolved_host.rstrip("/")
+        self._otel = OTelExporter(
+            endpoint=otlp_traces_endpoint(self._host),
+            protocol="http/protobuf",
+            service_name="forgesight",
+            capture_content=capture_content,
+            headers={"Authorization": basic_auth_header(public_key, secret_key)},
+            span_exporter=span_exporter,
+        )
+
+    # --- TelemetryExporter Protocol --------------------------------------
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        return self._otel.export([self._enrich(r) for r in records])
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return self._otel.force_flush(timeout_millis)
+
+    def shutdown(self, timeout_millis: int = 30_000) -> None:
+        self._otel.shutdown(timeout_millis)
+
+    # --- internals --------------------------------------------------------
+    def _enrich(self, record: Record) -> Record:
+        attrs: dict[str, object] = dict(record.attributes)
+        attrs[LANGFUSE_OBSERVATION_TYPE] = _OBSERVATION_TYPE[record.kind]
+        if record.parent_span_id is None and record.kind in (Kind.AGENT, Kind.WORKFLOW):
+            attrs[LANGFUSE_TRACE_NAME] = record.name
+            for meta_key, lf_key in _TRACE_LIFTS.items():
+                if meta_key in attrs:
+                    attrs[lf_key] = attrs[meta_key]
+        return replace(record, attributes=MappingProxyType(attrs))

forgesight_langfuse-0.1.0/tests/test_exporter.py

@@ -0,0 +1,107 @@
+"""Tests for the Langfuse exporter: auth, observation mapping, trace lift, conformance."""
+
+from __future__ import annotations
+
+import base64
+
+import pytest
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from forgesight_core import configure, reset_runtime, telemetry
+from forgesight_core.testing.conformance import run_exporter_conformance
+from forgesight_langfuse import LangfuseExporter, basic_auth_header
+from forgesight_langfuse.exporter import otlp_traces_endpoint
+
+
+def _exporter(sink: InMemorySpanExporter, **kw: object) -> LangfuseExporter:
+    return LangfuseExporter(
+        public_key="pk-lf-test", secret_key="sk-lf-test", span_exporter=sink, **kw
+    )
+
+
+def test_basic_auth_header() -> None:
+    header = basic_auth_header("pk-lf-1", "sk-lf-2")
+    assert header.startswith("Basic ")
+    decoded = base64.b64decode(header.split(" ", 1)[1]).decode()
+    assert decoded == "pk-lf-1:sk-lf-2"
+
+
+def test_requires_keys() -> None:
+    with pytest.raises(ValueError, match="public_key and secret_key"):
+        LangfuseExporter(public_key="", secret_key="sk")
+
+
+def test_region_resolves_host() -> None:
+    exporter = LangfuseExporter(public_key="pk", secret_key="sk", region="us")
+    assert exporter._host == "https://us.cloud.langfuse.com"
+    explicit = LangfuseExporter(public_key="pk", secret_key="sk", host="https://self/")
+    assert explicit._host == "https://self"
+
+
+def test_conformance() -> None:
+    run_exporter_conformance(
+        lambda: LangfuseExporter(
+            public_key="pk-lf", secret_key="sk-lf", span_exporter=InMemorySpanExporter()
+        )
+    )
+
+
+def test_observation_types_and_trace_lift() -> None:
+    sink = InMemorySpanExporter()
+    configure(exporters=[_exporter(sink)], sync_export=True)
+    try:
+        with telemetry.agent_run("classifier") as run:
+            run.set_metadata(user_id="u-1", session_id="s-1")
+            with run.step("react-1"), run.llm_call("anthropic", "claude-sonnet-4-5") as call:
+                call.record_usage(input=10, output=5)
+            with run.tool_call("search"):
+                pass
+        spans = {s.name: s for s in sink.get_finished_spans()}
+        by_attr = {
+            s.attributes["langfuse.observation.type"]: s  # type: ignore[index]
+            for s in sink.get_finished_spans()
+            if s.attributes
+        }
+        assert "generation" in by_attr  # the LLM call
+        assert "tool" in by_attr  # the tool call
+        assert "agent" in by_attr  # the run
+        agent_span = next(s for s in sink.get_finished_spans() if s.name.startswith("invoke_agent"))
+        assert agent_span.attributes is not None
+        assert agent_span.attributes["langfuse.trace.name"] == "classifier"
+        assert agent_span.attributes["langfuse.user.id"] == "u-1"
+        assert agent_span.attributes["langfuse.session.id"] == "s-1"
+        assert spans  # sanity
+    finally:
+        reset_runtime()
+
+
+def test_cost_is_ingested_as_extension_attr() -> None:
+    sink = InMemorySpanExporter()
+    configure(exporters=[_exporter(sink)], sync_export=True)
+    try:
+        with (
+            telemetry.agent_run("c") as run,
+            run.llm_call("anthropic", "claude-sonnet-4-5") as call,
+        ):
+            call.record_usage(input=1000, output=500)
+        gen = next(
+            s
+            for s in sink.get_finished_spans()
+            if s.attributes and s.attributes.get("langfuse.observation.type") == "generation"
+        )
+        assert gen.attributes is not None
+        assert gen.attributes["forgesight.usage.cost_usd"] is not None  # SDK cost ingested
+    finally:
+        reset_runtime()
+
+
+def test_otlp_traces_endpoint_has_signal_path() -> None:
+    # Langfuse's OTLP/HTTP ingest needs the /v1/traces signal path; the bare base 404s.
+    assert (
+        otlp_traces_endpoint("https://us.cloud.langfuse.com")
+        == "https://us.cloud.langfuse.com/api/public/otel/v1/traces"
+    )
+    assert (
+        otlp_traces_endpoint("https://self-hosted.example/")
+        == "https://self-hosted.example/api/public/otel/v1/traces"
+    )