lanternfish 0.3.0__tar.gz

lanternfish-0.3.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: lanternfish
+Version: 0.3.0
+Summary: Lanternfish SDK: trace AI agent runs, decisions and releases with OpenTelemetry.
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/TriTetra/agentlens-sdk/tree/master/lanternfish#readme
+Project-URL: Source, https://github.com/TriTetra/agentlens-sdk
+Keywords: ai-agents,observability,opentelemetry,llm,tracing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api<2,>=1.25.0
+Requires-Dist: opentelemetry-sdk<2,>=1.25.0
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai<1,>=0.40.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.40.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: opentelemetry-instrumentation-google-generativeai<1,>=0.40.0; extra == "gemini"
+Provides-Extra: groq
+Requires-Dist: opentelemetry-instrumentation-groq<1,>=0.40.0; extra == "groq"
+Provides-Extra: langchain
+Requires-Dist: opentelemetry-instrumentation-langchain<1,>=0.40.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: opentelemetry-instrumentation-crewai<1,>=0.40.0; extra == "crewai"
+Provides-Extra: llamaindex
+Requires-Dist: opentelemetry-instrumentation-llamaindex<1,>=0.40.0; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: lanternfish[anthropic,crewai,gemini,groq,langchain,llamaindex,openai]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# Lanternfish Python SDK
+
+Record what your AI agent does: its LLM calls, its own steps, the decisions it makes and the release it runs on.
+Lanternfish compares those runs over time and tells you what changed.
+
+Built on OpenTelemetry. Works next to an existing OpenTelemetry or Logfire setup.
+
+## Install
+
+```bash
+pip install "lanternfish[openai]"
+```
+
+Use the extra for each provider you call: `openai`, `anthropic`, `gemini`, `groq`, `langchain`, `crewai`,
+`llamaindex`, or `all`. Requires Python 3.11+.
+
+## Start
+
+```bash
+export LANTERNFISH_API_KEY="lfsk_..."            # Settings → API keys
+export LANTERNFISH_ENDPOINT="https://your-lanternfish-endpoint"
+```
+
+```python
+import lanternfish
+
+lanternfish.instrument(agent="travel-agent")
+```
+
+From here on, calls to installed providers are recorded. The SDK never picks a destination by itself: without an
+endpoint it stops with an error that says what to set.
+
+## Record your own steps and decisions
+
+```python
+import lanternfish
+
+@lanternfish.trace                                  # records arguments; capture_args=False for private data
+def search_flights(destination: str) -> list[str]:
+    ...
+
+with lanternfish.set_user("user_42", session_id="sess_9"):   # removed again when the block ends
+    with lanternfish.span("book-trip"):
+        options = search_flights("Lisbon")
+        with lanternfish.reasoning(name="pick_flight") as r:
+            r.consider_option("KLM 1724", score=0.8, reason="Arrives before the meeting")
+            r.decide("KLM 1724", confidence=0.8, reason="Arrives before the meeting")
+```
+
+A step that raises is marked failed, with the exception type and message.
+
+## Releases
+
+Every span carries the release it ran on: `release=` if you pass it, otherwise `LANTERNFISH_RELEASE`, otherwise the
+commit your CI or host exposes (`GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, …). To mark the moment a
+release went live, call this from your deploy step:
+
+```python
+lanternfish.record_deployment("v1.8.2", metadata={"commit": "a1b2c3d", "environment": "production"})
+```
+
+## Options
+
+| `instrument()` argument | If omitted | |
+|---|---|---|
+| `api_key` | `LANTERNFISH_API_KEY` | Project API key, sent only in the `x-api-key` header |
+| `endpoint` | `LANTERNFISH_ENDPOINT` | Your Lanternfish API base URL |
+| `agent` | — | Agent name on every run |
+| `release` | `LANTERNFISH_RELEASE` or CI commit | Version of the running code |
+| `environment` | `LANTERNFISH_ENVIRONMENT` | For example `production` |
+| `include` | `[]` | Also record `"http"`, `"sql"`, `"redis"` calls |
+| `capture_content` | `True` | Record prompt and completion text of LLM calls |
+
+## What is recorded
+
+- **LLM calls:** model, tokens, duration, errors and, unless `capture_content=False`, the prompt and completion text.
+- **HTTP** (only with `include=["http"]`): method, host, path and status. Never bodies, headers or query strings.
+- **SQL** (only with `include=["sql"]`): the statement with literals replaced by `?`. Never parameter values.
+
+## Short scripts and serverless
+
+Spans are sent in the background in batches. Call `lanternfish.flush()` before a short script or a serverless handler
+returns; `lanternfish.shutdown()` runs on process exit by itself.
+
+## Troubleshooting
+
+```python
+import logging
+logging.basicConfig(level="INFO")
+```
+
+The `lanternfish` logger names the endpoint, lists the integrations it turned on, and logs every rejected batch with
+the reason (invalid key, plan limit reached, endpoint unreachable). Sending never raises into your code; a temporary
+error is retried once.
+
+## License
+
+MIT

lanternfish-0.3.0/README.md

@@ -0,0 +1,98 @@
+# Lanternfish Python SDK
+
+Record what your AI agent does: its LLM calls, its own steps, the decisions it makes and the release it runs on.
+Lanternfish compares those runs over time and tells you what changed.
+
+Built on OpenTelemetry. Works next to an existing OpenTelemetry or Logfire setup.
+
+## Install
+
+```bash
+pip install "lanternfish[openai]"
+```
+
+Use the extra for each provider you call: `openai`, `anthropic`, `gemini`, `groq`, `langchain`, `crewai`,
+`llamaindex`, or `all`. Requires Python 3.11+.
+
+## Start
+
+```bash
+export LANTERNFISH_API_KEY="lfsk_..."            # Settings → API keys
+export LANTERNFISH_ENDPOINT="https://your-lanternfish-endpoint"
+```
+
+```python
+import lanternfish
+
+lanternfish.instrument(agent="travel-agent")
+```
+
+From here on, calls to installed providers are recorded. The SDK never picks a destination by itself: without an
+endpoint it stops with an error that says what to set.
+
+## Record your own steps and decisions
+
+```python
+import lanternfish
+
+@lanternfish.trace                                  # records arguments; capture_args=False for private data
+def search_flights(destination: str) -> list[str]:
+    ...
+
+with lanternfish.set_user("user_42", session_id="sess_9"):   # removed again when the block ends
+    with lanternfish.span("book-trip"):
+        options = search_flights("Lisbon")
+        with lanternfish.reasoning(name="pick_flight") as r:
+            r.consider_option("KLM 1724", score=0.8, reason="Arrives before the meeting")
+            r.decide("KLM 1724", confidence=0.8, reason="Arrives before the meeting")
+```
+
+A step that raises is marked failed, with the exception type and message.
+
+## Releases
+
+Every span carries the release it ran on: `release=` if you pass it, otherwise `LANTERNFISH_RELEASE`, otherwise the
+commit your CI or host exposes (`GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, …). To mark the moment a
+release went live, call this from your deploy step:
+
+```python
+lanternfish.record_deployment("v1.8.2", metadata={"commit": "a1b2c3d", "environment": "production"})
+```
+
+## Options
+
+| `instrument()` argument | If omitted | |
+|---|---|---|
+| `api_key` | `LANTERNFISH_API_KEY` | Project API key, sent only in the `x-api-key` header |
+| `endpoint` | `LANTERNFISH_ENDPOINT` | Your Lanternfish API base URL |
+| `agent` | — | Agent name on every run |
+| `release` | `LANTERNFISH_RELEASE` or CI commit | Version of the running code |
+| `environment` | `LANTERNFISH_ENVIRONMENT` | For example `production` |
+| `include` | `[]` | Also record `"http"`, `"sql"`, `"redis"` calls |
+| `capture_content` | `True` | Record prompt and completion text of LLM calls |
+
+## What is recorded
+
+- **LLM calls:** model, tokens, duration, errors and, unless `capture_content=False`, the prompt and completion text.
+- **HTTP** (only with `include=["http"]`): method, host, path and status. Never bodies, headers or query strings.
+- **SQL** (only with `include=["sql"]`): the statement with literals replaced by `?`. Never parameter values.
+
+## Short scripts and serverless
+
+Spans are sent in the background in batches. Call `lanternfish.flush()` before a short script or a serverless handler
+returns; `lanternfish.shutdown()` runs on process exit by itself.
+
+## Troubleshooting
+
+```python
+import logging
+logging.basicConfig(level="INFO")
+```
+
+The `lanternfish` logger names the endpoint, lists the integrations it turned on, and logs every rejected batch with
+the reason (invalid key, plan limit reached, endpoint unreachable). Sending never raises into your code; a temporary
+error is retried once.
+
+## License
+
+MIT

lanternfish-0.3.0/__init__.py

@@ -0,0 +1,61 @@
+# __init__.py
+# Görev: Lanternfish SDK'nin public API'sini dışa aktarmak
+# Yapmaz: Instrumentation mantığı içermez
+
+from importlib.metadata import PackageNotFoundError, version
+
+from lanternfish.context import UserScope, set_user
+from lanternfish.decorators import span, span_context, trace
+from lanternfish.deployments import record_deployment
+from lanternfish.errors import LanternfishConfigurationError, LanternfishDeploymentError
+from lanternfish.instrument import flush, instrument, shutdown
+from lanternfish.semantic import (
+    confidence_tracking,
+    context_retrieval,
+    decision,
+    memory_access,
+    planning,
+    reasoning,
+    reflection,
+    set_planning_attribute,
+    set_reasoning_attribute,
+    set_reflection_attribute,
+    set_verification_attribute,
+    tool_usage,
+    verification,
+)
+
+# Sürüm tek kaynaktan, pyproject'ten okunur; kaynak ağaçtan çalışırken
+# paket kurulu olmayabilir.
+try:
+    __version__ = version("lanternfish")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+__all__ = [
+    "__version__",
+    "instrument",
+    "flush",
+    "shutdown",
+    "UserScope",
+    "LanternfishConfigurationError",
+    "LanternfishDeploymentError",
+    "record_deployment",
+    "set_user",
+    "trace",
+    "span",
+    "span_context",
+    "planning",
+    "reasoning",
+    "reflection",
+    "verification",
+    "tool_usage",
+    "memory_access",
+    "context_retrieval",
+    "confidence_tracking",
+    "decision",
+    "set_planning_attribute",
+    "set_reasoning_attribute",
+    "set_reflection_attribute",
+    "set_verification_attribute",
+]

lanternfish-0.3.0/configuration.py

@@ -0,0 +1,81 @@
+"""
+SDK yapılandırmasının çözümü.
+
+Görev: Endpoint, API anahtarı, sürüm (release) ve ortam değerlerini argümandan ya da ortam değişkeninden okur ve
+       doğrular. Sürüm verilmezse yaygın CI/hosting değişkenlerinden (Git commit) bulur.
+Yapmaz: Ağa çıkmaz, provider kurmaz, varsayılan bir Cloud adresi seçmez.
+"""
+
+import os
+from urllib.parse import urlsplit
+
+from lanternfish.errors import LanternfishConfigurationError
+
+# Sürümü kendiliğinden bulmak için okunan değişkenler; ilk dolu olan kazanır. Platformların kendi adları.
+RELEASE_ENV_VARS = (
+    "LANTERNFISH_RELEASE",
+    "GIT_COMMIT_SHA",
+    "GITHUB_SHA",
+    "VERCEL_GIT_COMMIT_SHA",
+    "RENDER_GIT_COMMIT",
+    "RAILWAY_GIT_COMMIT_SHA",
+    "HEROKU_SLUG_COMMIT",
+    "SOURCE_COMMIT",
+)
+SHORT_SHA_LENGTH = 12
+
+
+def resolve_endpoint(endpoint: str | None) -> str:
+    """API taban adresini argümandan veya LANTERNFISH_ENDPOINT'ten çözer ve doğrular.
+
+    Raises:
+        LanternfishConfigurationError: Adres yoksa, mutlak http(s) adresi değilse veya sorgu içeriyorsa.
+    """
+    value = (endpoint or os.getenv("LANTERNFISH_ENDPOINT", "")).strip().rstrip("/")
+    if not value:
+        raise LanternfishConfigurationError(
+            "Lanternfish endpoint is required. Pass endpoint=... or set LANTERNFISH_ENDPOINT. "
+            "The SDK never selects a destination automatically."
+        )
+
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise LanternfishConfigurationError("Lanternfish endpoint must be an absolute http:// or https:// URL.")
+    if parsed.query or parsed.fragment:
+        raise LanternfishConfigurationError("Lanternfish endpoint must not contain a query string or fragment.")
+    return value
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    """API anahtarını argümandan veya LANTERNFISH_API_KEY'den çözer.
+
+    Raises:
+        LanternfishConfigurationError: Anahtar yoksa.
+    """
+    value = (api_key or os.getenv("LANTERNFISH_API_KEY", "")).strip()
+    if not value:
+        raise LanternfishConfigurationError(
+            "Lanternfish API key is required. Pass api_key=... or set LANTERNFISH_API_KEY. "
+            "Create one in Settings → API keys."
+        )
+    return value
+
+
+def resolve_release(release: str | None) -> str | None:
+    """Çalışan kodun sürümünü döndürür: argüman, LANTERNFISH_RELEASE ya da CI'ın commit değişkeni.
+
+    Commit SHA'sı ilk 12 karaktere kısaltılır; sürüm adı (ör. "v1.8.2") olduğu gibi kalır.
+    """
+    if release and release.strip():
+        return release.strip()
+    for name in RELEASE_ENV_VARS:
+        value = os.getenv(name, "").strip()
+        if value:
+            return value if name == "LANTERNFISH_RELEASE" else value[:SHORT_SHA_LENGTH]
+    return None
+
+
+def resolve_environment(environment: str | None) -> str | None:
+    """Ortam adını (ör. "production") argümandan veya LANTERNFISH_ENVIRONMENT'tan döndürür."""
+    value = (environment or os.getenv("LANTERNFISH_ENVIRONMENT", "")).strip()
+    return value or None

lanternfish-0.3.0/context.py

@@ -0,0 +1,67 @@
+"""
+Son kullanıcı kimliği.
+
+Görev: Agent'ı kullanan son kullanıcının kimliğini, oturumunu ve etiketlerini bağlama koyar; bundan sonra açılan her
+       span bu bilgiyi taşır. `with` ile kullanılırsa blok bitince eski bağlama döner.
+Yapmaz: Span açmaz veya göndermez; değeri span'e damgalamak span_processor.py'nin işidir.
+"""
+
+from types import TracebackType
+
+from opentelemetry import context
+
+from lanternfish.span_processor import SESSION_ID_KEY, TAGS_KEY, USER_ID_KEY
+
+
+class UserScope:
+    """`set_user()` sonucunun kapsamı: `with` bloğundan çıkınca kimliği bağlamdan kaldırır."""
+
+    def __init__(self, token: object) -> None:
+        """Kapsamı, bağlama eklenen değerin geri alma anahtarıyla kurar."""
+        self._token = token
+        self._closed = False
+
+    def __enter__(self) -> "UserScope":
+        """Kimlik zaten bağlamda; bloğa olduğu gibi girer."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Bloktan çıkarken kimliği bağlamdan kaldırır."""
+        self.close()
+
+    def close(self) -> None:
+        """Kimliği bağlamdan kaldırır; ikinci çağrı etkisizdir."""
+        if not self._closed:
+            context.detach(self._token)  # type: ignore[arg-type]
+            self._closed = True
+
+
+def set_user(user_id: str, session_id: str | None = None, tags: dict[str, str] | None = None) -> UserScope:
+    """Bundan sonra açılan span'lere son kullanıcı kimliğini ekler.
+
+    Web sunucusunda istek başına `with` ile kullanın; böylece kimlik bir sonraki isteğe taşınmaz::
+
+        with lanternfish.set_user("user_42", session_id="sess_9"):
+            run_agent(question)
+
+    Args:
+        user_id: Son kullanıcının kimliği.
+        session_id: Sohbet veya oturum kimliği.
+        tags: Run'ı süzmek için düz etiketler.
+
+    Returns:
+        `with` ile kullanılabilen ya da `close()` ile kapatılabilen kapsam.
+    """
+    ctx = context.get_current()
+    if user_id:
+        ctx = context.set_value(USER_ID_KEY, user_id, ctx)
+    if session_id:
+        ctx = context.set_value(SESSION_ID_KEY, session_id, ctx)
+    if tags:
+        ctx = context.set_value(TAGS_KEY, tags, ctx)
+    return UserScope(context.attach(ctx))

lanternfish-0.3.0/decorators.py

@@ -0,0 +1,222 @@
+# decorators.py
+# Gorev: @trace ve @span decorator + span() context manager ile manual instrumentation
+# Yapmaz: TracerProvider veya exporter olusturmaz; instrument() ile aktif provider kullanilir
+#
+# Kullanim:
+#   @trace                           -> span adi = fn adi, parametreler otomatik yakalanir
+#   @trace(name="x")                 -> custom span adi
+#   @span                            -> span adi = fn adi, parametreler yakalanmaz
+#   @span("x") / @span(name="x")    -> custom span adi, decorator
+#   with span("x") as s:            -> context manager, manuel attribute
+#   with span_context("x") as s:    -> span_context alias'i
+
+import functools
+import inspect
+from contextlib import contextmanager
+from typing import Any, Callable, Generator
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import StatusCode
+
+
+# ── @trace ────────────────────────────────────────────────────────────────────
+
+def trace(func: Callable | None = None, *, name: str | None = None, capture_args: bool = True) -> Any:
+    """Custom fonksiyonlari OpenTelemetry span olarak izler.
+
+    Parametreler otomatik olarak manual.param.<isim> attribute'i olur.
+    Exception durumunda span status ERROR olarak isaretlenir.
+
+    Iki kullanim sekli:
+      @trace                       -> span adi fonksiyon adindan alinir
+      @trace(name="custom_name")   -> span adi manuel verilir
+
+    Args:
+        func: Direkt decorator olarak kullanildiginda gelen fonksiyon.
+        name: Opsiyonel custom span adi.
+        capture_args: False ise parametre degerleri span'e yazilmaz (kisisel veri tasiyan fonksiyonlar icin).
+    """
+    def decorator(fn: Callable) -> Callable:
+        span_name = name or fn.__name__
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                tracer = otel_trace.get_tracer("lanternfish.manual")
+                with tracer.start_as_current_span(span_name) as s:
+                    if capture_args:
+                        _add_params(s, fn, args, kwargs)
+                    try:
+                        result = await fn(*args, **kwargs)
+                        s.set_status(StatusCode.OK)
+                        return result
+                    except Exception as exc:
+                        s.set_status(StatusCode.ERROR, str(exc))
+                        s.record_exception(exc)
+                        raise
+            return async_wrapper
+        else:
+            @functools.wraps(fn)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                tracer = otel_trace.get_tracer("lanternfish.manual")
+                with tracer.start_as_current_span(span_name) as s:
+                    if capture_args:
+                        _add_params(s, fn, args, kwargs)
+                    try:
+                        result = fn(*args, **kwargs)
+                        s.set_status(StatusCode.OK)
+                        return result
+                    except Exception as exc:
+                        s.set_status(StatusCode.ERROR, str(exc))
+                        s.record_exception(exc)
+                        raise
+            return sync_wrapper
+
+    if func is None:
+        return decorator
+    return decorator(func)
+
+
+# ── @span / span() context manager ────────────────────────────────────────────
+
+class _SpanProxy:
+    """span("name") cagrisi icin dual-use proxy.
+
+    Hem @span("name") decorator hem with span("name") as s: context manager
+    olarak kullanilabilir. Parametreler otomatik yakalanmaz; caller s.set_attribute()
+    ile manuel ekler.
+    """
+
+    def __init__(self, span_name: str) -> None:
+        self._span_name = span_name
+        self._cm: Any = None
+
+    def __call__(self, fn: Callable) -> Callable:
+        """@span("name") seklinde decorator olarak kullanildiginda."""
+        return _make_span_wrapper(fn, self._span_name)
+
+    def __enter__(self) -> Any:
+        """with span("name") as s: seklinde context manager olarak kullanildiginda."""
+        tracer = otel_trace.get_tracer("lanternfish.manual")
+        self._cm = tracer.start_as_current_span(self._span_name)
+        s = self._cm.__enter__()
+        self._span_ref = s
+        return s
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        if exc_val is not None:
+            self._span_ref.set_status(StatusCode.ERROR, str(exc_val))
+            self._span_ref.record_exception(exc_val)
+        else:
+            self._span_ref.set_status(StatusCode.OK)
+        return self._cm.__exit__(exc_type, exc_val, exc_tb)
+
+    # async context manager destegi
+    async def __aenter__(self) -> Any:
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        return self.__exit__(exc_type, exc_val, exc_tb)
+
+
+def span(func_or_name: Callable | str | None = None, *, name: str | None = None) -> Any:
+    """Kod blogunu veya fonksiyonu izler. Hafif versiyon (@trace'in aksine parametre yakalamaz).
+
+    Uc kullanim sekli:
+      @span                            -> decorator, span adi = fn adi
+      @span("custom") / @span(name=..) -> decorator, custom span adi
+      with span("name") as s:          -> context manager, s.set_attribute() ile manuel attr
+
+    Args:
+        func_or_name: Fonksiyon (@span direkt), string (span adi) veya None.
+        name: Keyword-only custom span adi.
+    """
+    # Durum 1: @span (parametresiz, direkt fonksiyon uzerinde)
+    if callable(func_or_name):
+        return _make_span_wrapper(func_or_name, func_or_name.__name__)
+
+    # Durum 2: span("name") veya span(name="name") -> _SpanProxy doner
+    actual_name: str = (
+        func_or_name if isinstance(func_or_name, str)
+        else name or "span"
+    )
+    return _SpanProxy(actual_name)
+
+
+@contextmanager
+def span_context(name: str) -> Generator[Any, None, None]:
+    """Context manager olarak span olusturur.
+
+    Kullanim:
+        with span_context("operation") as s:
+            s.set_attribute("key", "value")
+
+    Args:
+        name: Span adi.
+
+    Yields:
+        Aktif OpenTelemetry span.
+    """
+    tracer = otel_trace.get_tracer("lanternfish.manual")
+    with tracer.start_as_current_span(name) as s:
+        try:
+            yield s
+            s.set_status(StatusCode.OK)
+        except Exception as exc:
+            s.set_status(StatusCode.ERROR, str(exc))
+            s.record_exception(exc)
+            raise
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+def _make_span_wrapper(fn: Callable, span_name: str) -> Callable:
+    """Sync veya async fonksiyon icin span wrapper olusturur (parametresiz)."""
+    if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = otel_trace.get_tracer("lanternfish.manual")
+            with tracer.start_as_current_span(span_name) as s:
+                try:
+                    result = await fn(*args, **kwargs)
+                    s.set_status(StatusCode.OK)
+                    return result
+                except Exception as exc:
+                    s.set_status(StatusCode.ERROR, str(exc))
+                    s.record_exception(exc)
+                    raise
+        return async_wrapper
+    else:
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = otel_trace.get_tracer("lanternfish.manual")
+            with tracer.start_as_current_span(span_name) as s:
+                try:
+                    result = fn(*args, **kwargs)
+                    s.set_status(StatusCode.OK)
+                    return result
+                except Exception as exc:
+                    s.set_status(StatusCode.ERROR, str(exc))
+                    s.record_exception(exc)
+                    raise
+        return sync_wrapper
+
+
+def _add_params(s: Any, fn: Callable, args: tuple, kwargs: dict) -> None:
+    """Fonksiyon parametrelerini span attribute olarak ekler (trace icin).
+
+    self ve cls atlanir. 500 karakteri asan degerler kisaltilir.
+    """
+    try:
+        sig = inspect.signature(fn)
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        for param_name, param_value in bound.arguments.items():
+            if param_name in ("self", "cls"):
+                continue
+            value_str = str(param_value)
+            if len(value_str) > 500:
+                value_str = value_str[:500] + "... [truncated]"
+            s.set_attribute(f"manual.param.{param_name}", value_str)
+    except Exception:
+        pass