forgesight-langfuse 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+forgesight_langfuse/__init__.py,sha256=dYv94RTIlLkv8_j3rsRjeKuVW3YpFzSIw5Ylyo256Ro,281
+forgesight_langfuse/exporter.py,sha256=feKec4_FCNifhMoYzHhai78-tI1uFyI_SPTZMu7OIns,4199
+forgesight_langfuse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forgesight_langfuse-0.1.0.dist-info/METADATA,sha256=nAOAivZQEwC0vyoSNA_47_49qfNIW0e8aOgYOK1YLOk,2396
+forgesight_langfuse-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+forgesight_langfuse-0.1.0.dist-info/entry_points.txt,sha256=0_LafV4GTGCVN2HrpR7qDWsV8QMCxe_3NMZlHI6Icas,80
+forgesight_langfuse-0.1.0.dist-info/RECORD,,

forgesight_langfuse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

forgesight_langfuse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[forgesight.exporters]
+langfuse = forgesight_langfuse.exporter:LangfuseExporter