observo-ai 0.1.2__tar.gz

observo_ai-0.1.2/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: observo-ai
+Version: 0.1.2
+Summary: Python SDK for the Observo AI Observability & Evaluation Platform
+Author-email: Observo <sdk@observo.dev>
+License: MIT
+Project-URL: Homepage, https://observo.dev
+Project-URL: Documentation, https://docs.observo.dev
+Project-URL: Repository, https://github.com/yourusername/observo-platform
+Project-URL: Bug Tracker, https://github.com/yourusername/observo-platform/issues
+Keywords: llm,observability,ai,monitoring,evaluation,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"

observo_ai-0.1.2/observo/__init__.py

@@ -0,0 +1,239 @@
+"""
+Observo SDK — Public API
+
+Install:  pip install observo-ai
+Docs:     https://docs.observo.dev
+
+Usage:
+    import observo
+
+    # 1. Initialize once (e.g. in app startup)
+    observo.init(api_key="obs_live_...", environment="production")
+
+    # 2a. Decorator — automatic tracing (zero code change)
+    @observo.trace
+    def ask_llm(prompt: str) -> str:
+        return my_llm.generate(prompt)
+
+    # 2b. Decorator with metadata
+    @observo.trace(model="gpt-4o", provider="openai")
+    async def ask_gpt(prompt: str) -> str:
+        return await openai_client.chat(prompt)
+
+    # 2c. Context manager — manual control
+    with observo.span("rag_pipeline") as span:
+        context = retrieve_docs(question)
+        answer = llm.generate(question)
+        span.set_input(question)
+        span.set_output(answer)
+        span.set_ground_truth("Expected answer")  # optional
+        span.set_metadata(model="gemini-1.5-flash")
+
+    # 2d. Manual logging
+    observo.log(
+        input="What is Python?",
+        output="Python is a programming language.",
+        model="gpt-4o",
+        provider="openai",
+        latency_ms=320,
+    )
+"""
+
+from __future__ import annotations
+
+import atexit
+import warnings
+from typing import Any, Optional
+
+from . import _state
+from .client import ObservoClient
+from .context import ObservoSpan
+from .decorators import trace
+from .types import ObservoConfig, TraceData
+
+__version__ = "0.1.0"
+__all__ = ["init", "trace", "span", "log", "flush", "shutdown", "__version__"]
+
+
+def init(
+    api_key: Optional[str] = None,
+    *,
+    api_url: Optional[str] = None,
+    environment: Optional[str] = None,
+    flush_interval_sec: float = 1.0,
+    max_buffer_size: int = 1000,
+    max_batch_size: int = 100,
+    timeout_sec: float = 5.0,
+    max_retries: int = 3,
+    debug: bool = False,
+    auto_patch: bool = True,
+) -> None:
+    """
+    Initialize the Observo SDK.
+    Call this once at application startup before any @trace decorators fire.
+
+    Args:
+        api_key:            Your Observo API key (starts with obs_live_...)
+        api_url:            Observo API base URL (default: localhost for dev)
+        environment:        Deployment environment tag (production/staging/development)
+        flush_interval_sec: How often to batch-send traces (default: 1s)
+        max_buffer_size:    Max traces to hold in memory if API is down (default: 1000)
+        max_batch_size:     Max traces per HTTP request (default: 100)
+        timeout_sec:        HTTP request timeout (default: 5s)
+        max_retries:        Retry attempts on failure (default: 3)
+        debug:              Log SDK internals to stdout (default: False)
+        auto_patch:         Enable auto-instrumentation (default: True)
+
+    Example:
+        observo.init(
+            api_key="obs_live_ab12_xxxxxxxxxxxxx",
+            api_url="https://observo-demo.onrender.com",
+            environment="production",
+            auto_patch=True, # New: Zero-config auto instrumentation
+        )
+    """
+    import os
+    
+    # 1. Resolve configuration from args or environment
+    resolved_api_key = api_key or os.environ.get("OBSERVO_API_KEY")
+    env_url = os.environ.get("OBSERVO_API_URL", "http://localhost:8080")
+    resolved_api_url = api_url or env_url
+    
+    # Strip trailing /v1 if present to prevent double-prefixing in client.py
+    resolved_api_url = resolved_api_url.rstrip("/")
+    if resolved_api_url.endswith("/v1"):
+        resolved_api_url = resolved_api_url[:-3]
+
+    resolved_env = environment or os.environ.get("OBSERVO_ENV", "production")
+
+    if not resolved_api_key:
+        raise ValueError("observo.init() requires an api_key. Provide it as an argument or via OBSERVO_API_KEY environment variable.")
+
+    if not resolved_api_key.startswith("obs_"):
+        warnings.warn(
+            "API key does not start with 'obs_' — double-check your key.",
+            stacklevel=2,
+        )
+
+    config = ObservoConfig(
+        api_key=resolved_api_key,
+        api_url=resolved_api_url.rstrip("/"),
+        environment=resolved_env,
+        flush_interval_sec=flush_interval_sec,
+        max_buffer_size=max_buffer_size,
+        max_batch_size=max_batch_size,
+        timeout_sec=timeout_sec,
+        max_retries=max_retries,
+        debug=debug,
+    )
+
+    # Shutdown existing client if re-initializing
+    if _state.client is not None:
+        _state.client.shutdown()
+
+    _state.client = ObservoClient(config)
+
+    # Register automatic shutdown on process exit
+    atexit.register(shutdown)
+
+    # ── Zero-Config Auto-Instrumentation ──
+    if auto_patch:
+        try:
+            from . import auto
+            auto.install()
+        except Exception as e:
+            if debug:
+                print(f"⚠️  Observo: Auto-instrumentation failed: {e}")
+
+
+def span(name: str = "llm_call") -> ObservoSpan:
+    """
+    Create a trace span for manual instrumentation.
+
+    Usage (sync):
+        with observo.span("rag_pipeline") as span:
+            answer = llm.generate(question)
+            span.set_input(question)
+            span.set_output(answer)
+
+    Usage (async):
+        async with observo.span("async_pipeline") as span:
+            answer = await llm.generate(question)
+            span.set_input(question).set_output(answer)
+    """
+    return ObservoSpan(name)
+
+
+def log(
+    input: str,
+    output: str,
+    *,
+    model: Optional[str] = None,
+    provider: Optional[str] = None,
+    environment: Optional[str] = None,
+    latency_ms: Optional[int] = None,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    ground_truth: Optional[str] = None,
+    **metadata: Any,
+) -> None:
+    """
+    Manually log a single LLM trace.
+    Use when you want full control without decorators or context managers.
+
+    Example:
+        observo.log(
+            input="Translate to French: Hello",
+            output="Bonjour",
+            model="gpt-4o",
+            provider="openai",
+            latency_ms=280,
+            ground_truth="Bonjour",
+        )
+    """
+    if _state.client is None:
+        warnings.warn(
+            "observo.log() called before observo.init() — trace dropped.",
+            stacklevel=2,
+        )
+        return
+
+    try:
+        trace_data = TraceData(
+            input=input,
+            output=output,
+            model=model,
+            provider=provider,
+            environment=environment or _state.client._config.environment,
+            latency_ms=latency_ms,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            ground_truth=ground_truth,
+            metadata=dict(metadata),
+        )
+        _state.client.enqueue(trace_data)
+    except Exception:
+        pass  # Never crash the caller
+
+
+def flush() -> None:
+    """
+    Force an immediate flush of all buffered traces.
+    Useful in tests or before shutting down your application.
+
+    Example:
+        observo.flush()  # ensure all traces are sent before exit
+    """
+    if _state.client:
+        _state.client.flush()
+
+
+def shutdown() -> None:
+    """
+    Gracefully shut down the SDK.
+    Flushes remaining traces and stops the background thread.
+    Called automatically on process exit via atexit.
+    """
+    if _state.client:
+        _state.client.shutdown()
+        _state.client = None

observo_ai-0.1.2/observo/_buffer.py

@@ -0,0 +1,57 @@
+"""
+Observo SDK — In-Memory Trace Buffer
+Thread-safe queue that holds traces when the API is temporarily unreachable.
+
+NFR: Durability — traces are never lost due to temporary API outages.
+The buffer holds up to max_buffer_size traces in memory.
+When the API recovers, the background flusher drains the buffer.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import List
+
+from .types import TraceData
+
+
+class TraceBuffer:
+    """
+    Thread-safe FIFO buffer for traces.
+
+    - Acts as a safety net when the Observo API is temporarily unreachable
+    - maxlen ensures memory usage is bounded (oldest traces dropped if full)
+    - Lock ensures thread safety across the decorator thread + flush thread
+    """
+
+    def __init__(self, max_size: int = 1000) -> None:
+        self._buffer: deque[TraceData] = deque(maxlen=max_size)
+        self._lock = threading.Lock()
+
+    def add(self, trace: TraceData) -> None:
+        """Add a trace to the buffer. Thread-safe."""
+        with self._lock:
+            self._buffer.append(trace)
+
+    def drain(self, batch_size: int = 100) -> List[TraceData]:
+        """
+        Remove and return up to batch_size traces from the front.
+        Thread-safe. Returns empty list if buffer is empty.
+        """
+        with self._lock:
+            batch: List[TraceData] = []
+            for _ in range(min(batch_size, len(self._buffer))):
+                batch.append(self._buffer.popleft())
+            return batch
+
+    def size(self) -> int:
+        """Current number of traces in the buffer."""
+        return len(self._buffer)
+
+    def is_empty(self) -> bool:
+        return len(self._buffer) == 0
+
+    def clear(self) -> None:
+        with self._lock:
+            self._buffer.clear()

observo_ai-0.1.2/observo/_state.py

@@ -0,0 +1,19 @@
+"""
+Observo SDK — Global State
+Holds the singleton client instance created by observo.init().
+Kept in a separate module to avoid circular imports.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import ObservoClient
+
+from contextvars import ContextVar
+
+# The singleton client — None until observo.init() is called
+client: "ObservoClient | None" = None
+
+# Context variable to prevent double-logging during auto-instrumentation
+is_tracing: ContextVar[bool] = ContextVar("is_tracing", default=False)

observo_ai-0.1.2/observo/auto.py

@@ -0,0 +1,119 @@
+import sys
+import os
+import logging
+import functools
+import importlib
+from typing import Any, Callable, Optional
+
+# Set up a silent logger for auto-instrumentation
+logger = logging.getLogger("observo.auto")
+
+# Guard flag to prevent duplicate install() runs
+_installed = False
+_message_printed = False
+
+def _get_dashboard_url():
+    """Returns the local or production dashboard URL."""
+    base = os.environ.get("OBSERVO_DASHBOARD_URL", "http://localhost:3000")
+    project_id = os.environ.get("OBSERVO_PROJECT_ID", "default")
+    return f"{base}/traces"
+
+def _print_wow_message():
+    """Prints a single, clean startup banner to the developer's console."""
+    global _message_printed
+    if _message_printed:
+        return
+    _message_printed = True
+
+    url = _get_dashboard_url()
+    PURPLE = "\033[95m"
+    CYAN = "\033[96m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    END = "\033[0m"
+
+    print(f"\n{PURPLE}{BOLD}🚀 Observo:{END} {CYAN}Auto-tracing active.{END}")
+    print(f"   {DIM}Dashboard:{END} {BOLD}{url}{END}\n")
+
+def _wrap_llm_method(original_method: Callable, provider: str) -> Callable:
+    """
+    Wraps an LLM call method (like create) to automatically trace it.
+    """
+    from .decorators import trace
+    
+    # Pre-configure the trace with provider info
+    return trace(provider=provider)(original_method)
+
+def patch_openai():
+    """Detects and patches OpenAI client methods."""
+    try:
+        import openai
+        # Modern OpenAI SDK (v1+)
+        try:
+            from openai.resources.chat.completions import Completions, AsyncCompletions
+            
+            # Patch Sync
+            if not hasattr(Completions.create, "__observo_patched__"):
+                original = Completions.create
+                Completions.create = _wrap_llm_method(original, "OpenAI")
+                Completions.create.__observo_patched__ = True
+
+            # Patch Async
+            if not hasattr(AsyncCompletions.create, "__observo_patched__"):
+                original = AsyncCompletions.create
+                AsyncCompletions.create = _wrap_llm_method(original, "OpenAI")
+                AsyncCompletions.create.__observo_patched__ = True
+                
+        except (ImportError, AttributeError):
+            pass # Likely an older version of OpenAI or different structure
+            
+    except ImportError:
+        pass # OpenAI not used
+
+def patch_groq():
+    """Detects and patches Groq client methods."""
+    try:
+        import groq
+        from groq.resources.chat.completions import Completions, AsyncCompletions
+        
+        if not hasattr(Completions.create, "__observo_patched__"):
+            original = Completions.create
+            Completions.create = _wrap_llm_method(original, "Groq")
+            Completions.create.__observo_patched__ = True
+
+        if not hasattr(AsyncCompletions.create, "__observo_patched__"):
+            original = AsyncCompletions.create
+            AsyncCompletions.create = _wrap_llm_method(original, "Groq")
+            AsyncCompletions.create.__observo_patched__ = True
+
+    except ImportError:
+        pass # Groq not used
+
+def install():
+    """Entry point to start auto-instrumentation. Fail-safe. Only runs once."""
+    global _installed
+    if _installed:
+        return
+    _installed = True
+
+    try:
+        # 1. Initialize the Client (Background Sender) if not already done
+        from . import _state, init
+        if _state.client is None:
+            init(debug=os.environ.get("OBSERVO_DEBUG") == "true", auto_patch=False)
+
+        # 2. Apply patches
+        patched = []
+        patch_openai()
+        patch_groq()
+
+        # 3. Print the startup banner (once)
+        if os.environ.get("OBSERVO_SILENT") != "true":
+            _print_wow_message()
+
+    except Exception as e:
+        # Fail silently to ensure the user's app never crashes
+        logger.warning(f"Observo: Auto-instrumentation failed (silent): {e}")
+
+# If imported via 'import observo.auto', it runs immediately
+install()

observo_ai-0.1.2/observo/cli.py

@@ -0,0 +1,61 @@
+import sys
+import os
+import runpy
+import argparse
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="observo-run",
+        description="Observo Zero-Touch Instrumentation: Run your AI app with automatic tracing."
+    )
+    parser.add_argument("script", help="The python script to run (e.g., main.py)")
+    parser.add_argument("args", nargs=argparse.REMAINDER, help="Arguments for your script")
+
+    if len(sys.argv) < 2:
+        parser.print_help()
+        sys.exit(1)
+
+    args = parser.parse_args()
+
+    # 1. Activate Auto-Instrumentation
+    try:
+        try:
+            import dotenv
+            dotenv.load_dotenv()
+        except ImportError:
+            pass  # python-dotenv not installed, proceed without it
+            
+        import observo.auto
+    except Exception as e:
+        print(f"⚠️  [Observo] Auto-instrumentation failed to start: {e}")
+
+    # 2. Prepare the environment for the user's script
+    script_path = args.script
+    
+    # Handle redundant 'python' argument if user still types it
+    if (script_path == "python" or script_path == "python3") and args.args:
+        script_path = args.args[0]
+        args.args = args.args[1:]
+
+    if not os.path.exists(script_path):
+        print(f"❌ [Observo] Script not found: {script_path}")
+        sys.exit(1)
+
+    # Update sys.argv so the user's script thinks it was run normally
+    sys.argv = [script_path] + args.args
+
+    # 3. RUN the user's script
+    print(f"✨ [Observo] Running {script_path}...")
+    print("─" * 40)
+    
+    try:
+        # run_path executes the script as if it were the main module
+        runpy.run_path(script_path, run_name="__main__")
+    except SystemExit as e:
+        sys.exit(e.code)
+    except Exception as e:
+        print(f"\n❌ [Observo] App crashed during execution:")
+        raise e
+
+if __name__ == "__main__":
+    main()