lanternfish 0.3.0__py3-none-any.whl

lanternfish/__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/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/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/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

lanternfish/deployments.py

@@ -0,0 +1,69 @@
+"""Deployment kaydı — sürümü Lanternfish'e bildirir.
+
+Görev: Bir sürümün ne zaman yayına çıktığını Lanternfish'e kaydeder; Lanternfish bu kaydı olay listesinde gösterir ve
+       "deployment öncesi bir saat" ile karşılaştırma yapar. CI betiğinden `instrument()` çağrılmadan kullanılır.
+Yapmaz: Span üretmez, tekrar denemez; başarısızlığı sessizce yutmaz (CI adımı hatayı görmeli).
+"""
+
+from datetime import datetime
+
+import requests
+
+from lanternfish.configuration import resolve_api_key, resolve_endpoint
+from lanternfish.errors import LanternfishDeploymentError
+
+MetadataValue = str | int | float | bool
+
+
+def record_deployment(
+    version: str,
+    *,
+    deployed_at: datetime | None = None,
+    metadata: dict[str, MetadataValue] | None = None,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    timeout_seconds: int = 10,
+) -> str:
+    """Bir deployment kaydeder ve Lanternfish'in verdiği kimliği döndürür.
+
+    Örnek (CI'da, deploy adımından sonra)::
+
+        import lanternfish
+        lanternfish.record_deployment("v1.4.2", metadata={"commit": "a1b2c3d", "environment": "production"})
+
+    Args:
+        version: Yayına çıkan sürüm (ör. "v1.4.2" veya commit kısaltması).
+        deployed_at: Deployment'ın bittiği zaman; verilmezse Lanternfish isteği aldığı anı kullanır. Saat dilimi verin.
+        metadata: En çok 20 düz etiket (ör. commit, ortam).
+        api_key: Proje API anahtarı; verilmezse LANTERNFISH_API_KEY.
+        endpoint: Lanternfish API adresi; verilmezse LANTERNFISH_ENDPOINT.
+        timeout_seconds: İstek için üst süre.
+
+    Returns:
+        Kaydın kimliği (ör. "dep_…").
+
+    Raises:
+        LanternfishConfigurationError: API anahtarı veya adres yoksa.
+        LanternfishDeploymentError: Lanternfish kaydı kabul etmezse veya ulaşılamazsa.
+    """
+    key = resolve_api_key(api_key)
+    payload: dict[str, object] = {"version": version, "metadata": metadata or {}}
+    if deployed_at is not None:
+        payload["deployed_at"] = deployed_at.isoformat()
+    url = f"{resolve_endpoint(endpoint)}/v1/deployments"
+    try:
+        response = requests.post(url, json=payload, headers={"x-api-key": key}, timeout=timeout_seconds)
+    except requests.RequestException as error:
+        raise LanternfishDeploymentError(f"Lanternfish could not be reached at {url}: {error}") from error
+    if response.status_code != 201:
+        raise LanternfishDeploymentError(_failure_message(response))
+    return str(response.json()["id"])
+
+
+def _failure_message(response: requests.Response) -> str:
+    """Backend'in hata ayrıntısını, yoksa durum kodunu cümleye çevirir."""
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        detail = None
+    return f"Lanternfish rejected the deployment ({response.status_code}): {detail or response.reason}"

lanternfish/errors.py

@@ -0,0 +1,9 @@
+"""Public exceptions raised by the Lanternfish SDK."""
+
+
+class LanternfishConfigurationError(ValueError):
+    """The SDK cannot start because required configuration is missing or invalid."""
+
+
+class LanternfishDeploymentError(RuntimeError):
+    """Lanternfish did not record the deployment (rejected, or unreachable)."""

lanternfish/exporters.py

@@ -0,0 +1,34 @@
+"""
+Gönderim zinciri.
+
+Görev: Damgalayıcıyı ve toplu JSON göndericisini tracer provider'a bağlar.
+Yapmaz: TracerProvider oluşturmaz, enstrümantasyon yapmaz.
+"""
+
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from lanternfish.json_exporter import JSONSpanExporter
+from lanternfish.span_processor import LanternfishContextProcessor
+
+
+def configure_exporter(
+    tracer_provider: TracerProvider,
+    api_key: str,
+    endpoint: str,
+    static_attributes: dict[str, str] | None = None,
+) -> None:
+    """Damgalayıcıyı ve toplu göndericiyi tracer provider'a bağlar.
+
+    Toplu gönderim arka planda yapılır; agent her span için ağı beklemez. Bekleyen span'ler süreç kapanırken veya
+    `lanternfish.flush()` çağrılınca gönderilir.
+
+    Args:
+        tracer_provider: İşlemcilerin ekleneceği provider.
+        api_key: Proje API anahtarı.
+        endpoint: Backend taban adresi.
+        static_attributes: Her span'e yazılacak sabit öznitelikler (agent adı, sürüm, ortam).
+    """
+    # Damgalayıcı önce eklenir: span başlarken çalışması gerekir.
+    tracer_provider.add_span_processor(LanternfishContextProcessor(static_attributes))
+    tracer_provider.add_span_processor(BatchSpanProcessor(JSONSpanExporter(endpoint=endpoint, api_key=api_key)))