agent-lighthouse 0.3.0__tar.gz

agent_lighthouse-0.3.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: agent-lighthouse
+Version: 0.3.0
+Summary: Multi-Agent Observability SDK for Agent Lighthouse
+Author-email: Agent Lighthouse Contributors <maintainers@agent-lighthouse.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/noogler-aditya/Agent-Lighthouse
+Project-URL: Documentation, https://github.com/noogler-aditya/Agent-Lighthouse#readme
+Project-URL: Repository, https://github.com/noogler-aditya/Agent-Lighthouse
+Keywords: agents,multi-agent,observability,tracing,debugging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.0.1; extra == "langgraph"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: bandit>=1.8.0; extra == "dev"
+
+# Agent Lighthouse SDK (Python)
+
+The official Python client for instrumenting AI agents with Agent Lighthouse.
+
+## Features
+
+- **Automatic Tracing**: Decorators for agents, tools, and LLM calls.
+- **Async Support**: Fully compatible with async/await workflows.
+- **State Management**: Expose internal agent state (memory, context) for real-time inspection.
+- **Token Tracking**: Automatically capture token usage and costs from LLM responses.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install agent-lighthouse
+```
+
+Or install from source in development mode:
+
+```bash
+cd sdk
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Initialize Tracer
+
+```python
+from agent_lighthouse import LighthouseTracer
+
+# Use your API Key (starts with lh_)
+tracer = LighthouseTracer(api_key="lh_...")
+```
+
+### 2. Add Decorators
+
+Wrap your functions with `@trace_agent`, `@trace_tool`, or `@trace_llm`.
+
+```python
+from agent_lighthouse import trace_agent, trace_tool, trace_llm
+
+@trace_tool("Web Search")
+def search_web(query):
+    # ... logic ...
+    return results
+
+@trace_llm("GPT-4", model="gpt-4-turbo", cost_per_1k_prompt=0.01)
+def call_llm(prompt):
+    # ... call OpenAI ...
+    return response
+
+@trace_agent("Researcher")
+def run_research_agent(topic):
+    data = search_web(topic)
+    summary = call_llm(f"Summarize {data}")
+    return summary
+```
+
+### 3. Run It
+
+Just run your script as normal. The SDK will automatically send traces to the backend.
+
+## State Inspection
+
+Allow humans to inspect and modify agent state during execution:
+
+```python
+from agent_lighthouse import get_tracer
+
+@trace_agent("Writer")
+def writer_agent():
+    tracer = get_tracer()
+    
+    # Expose state
+    tracer.update_state(
+        memory={"draft": "Initial draft..."},
+        context={"tone": "Professional"}
+    )
+    
+    # ... execution continues ...
+```
+
+## Zero-Touch Auto-Instrumentation (Magic Import)
+
+No code changes to your LLM calls. Just import once at the top of your script:
+
+```python
+import agent_lighthouse.auto  # auto-instruments OpenAI, Anthropic, requests, and frameworks
+```
+
+This automatically captures:
+- LLM latency
+- Token usage
+- Cost (best-effort pricing)
+
+Content capture is **off by default**. Enable if you explicitly want payloads:
+
+```bash
+export LIGHTHOUSE_CAPTURE_CONTENT=true
+```
+
+## Configuration
+
+You can configure the SDK via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LIGHTHOUSE_API_KEY` | Your machine API key | `None` |
+| `LIGHTHOUSE_BASE_URL` | URL of the backend API | `http://localhost:8000` |
+| `LIGHTHOUSE_AUTO_INSTRUMENT` | Enable auto-instrumentation | `1` |
+| `LIGHTHOUSE_CAPTURE_CONTENT` | Capture request/response payloads | `false` |
+| `LIGHTHOUSE_LLM_HOSTS` | Allowlist extra LLM hosts for requests instrumentation | `""` |
+| `LIGHTHOUSE_PRICING_JSON` | Pricing override JSON string | `""` |
+| `LIGHTHOUSE_PRICING_PATH` | Pricing override JSON file path | `""` |
+| `LIGHTHOUSE_DISABLE_FRAMEWORKS` | Disable framework adapters (csv) | `""` |

agent_lighthouse-0.3.0/README.md

@@ -0,0 +1,118 @@
+# Agent Lighthouse SDK (Python)
+
+The official Python client for instrumenting AI agents with Agent Lighthouse.
+
+## Features
+
+- **Automatic Tracing**: Decorators for agents, tools, and LLM calls.
+- **Async Support**: Fully compatible with async/await workflows.
+- **State Management**: Expose internal agent state (memory, context) for real-time inspection.
+- **Token Tracking**: Automatically capture token usage and costs from LLM responses.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install agent-lighthouse
+```
+
+Or install from source in development mode:
+
+```bash
+cd sdk
+pip install -e .
+```
+
+## Quick Start
+
+### 1. Initialize Tracer
+
+```python
+from agent_lighthouse import LighthouseTracer
+
+# Use your API Key (starts with lh_)
+tracer = LighthouseTracer(api_key="lh_...")
+```
+
+### 2. Add Decorators
+
+Wrap your functions with `@trace_agent`, `@trace_tool`, or `@trace_llm`.
+
+```python
+from agent_lighthouse import trace_agent, trace_tool, trace_llm
+
+@trace_tool("Web Search")
+def search_web(query):
+    # ... logic ...
+    return results
+
+@trace_llm("GPT-4", model="gpt-4-turbo", cost_per_1k_prompt=0.01)
+def call_llm(prompt):
+    # ... call OpenAI ...
+    return response
+
+@trace_agent("Researcher")
+def run_research_agent(topic):
+    data = search_web(topic)
+    summary = call_llm(f"Summarize {data}")
+    return summary
+```
+
+### 3. Run It
+
+Just run your script as normal. The SDK will automatically send traces to the backend.
+
+## State Inspection
+
+Allow humans to inspect and modify agent state during execution:
+
+```python
+from agent_lighthouse import get_tracer
+
+@trace_agent("Writer")
+def writer_agent():
+    tracer = get_tracer()
+    
+    # Expose state
+    tracer.update_state(
+        memory={"draft": "Initial draft..."},
+        context={"tone": "Professional"}
+    )
+    
+    # ... execution continues ...
+```
+
+## Zero-Touch Auto-Instrumentation (Magic Import)
+
+No code changes to your LLM calls. Just import once at the top of your script:
+
+```python
+import agent_lighthouse.auto  # auto-instruments OpenAI, Anthropic, requests, and frameworks
+```
+
+This automatically captures:
+- LLM latency
+- Token usage
+- Cost (best-effort pricing)
+
+Content capture is **off by default**. Enable if you explicitly want payloads:
+
+```bash
+export LIGHTHOUSE_CAPTURE_CONTENT=true
+```
+
+## Configuration
+
+You can configure the SDK via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LIGHTHOUSE_API_KEY` | Your machine API key | `None` |
+| `LIGHTHOUSE_BASE_URL` | URL of the backend API | `http://localhost:8000` |
+| `LIGHTHOUSE_AUTO_INSTRUMENT` | Enable auto-instrumentation | `1` |
+| `LIGHTHOUSE_CAPTURE_CONTENT` | Capture request/response payloads | `false` |
+| `LIGHTHOUSE_LLM_HOSTS` | Allowlist extra LLM hosts for requests instrumentation | `""` |
+| `LIGHTHOUSE_PRICING_JSON` | Pricing override JSON string | `""` |
+| `LIGHTHOUSE_PRICING_PATH` | Pricing override JSON file path | `""` |
+| `LIGHTHOUSE_DISABLE_FRAMEWORKS` | Disable framework adapters (csv) | `""` |

agent_lighthouse-0.3.0/agent_lighthouse/__init__.py

@@ -0,0 +1,50 @@
+"""
+Agent Lighthouse SDK
+Multi-Agent Observability for AI Systems
+
+Features:
+- Framework-agnostic tracing for any multi-agent system
+- Sync + async support
+- Thread-safe span tracking
+- Fail-silent mode (never crashes host application)
+- Automatic output capture
+- OpenAI-style token extraction
+"""
+from .tracer import (
+    LighthouseTracer,
+    get_tracer,
+    reset_global_tracer,
+    trace_agent,
+    trace_tool,
+    trace_llm,
+)
+from .client import LighthouseClient
+
+__version__ = "0.3.0"
+__all__ = [
+    "LighthouseTracer",
+    "LighthouseClient",
+    "get_tracer",
+    "reset_global_tracer",
+    "trace_agent",
+    "trace_tool",
+    "trace_llm",
+    "instrument",
+    "uninstrument",
+    "is_instrumented",
+]
+
+
+def instrument() -> bool:
+    from .auto import instrument as _instrument
+    return _instrument()
+
+
+def uninstrument() -> None:
+    from .auto import uninstrument as _uninstrument
+    return _uninstrument()
+
+
+def is_instrumented() -> bool:
+    from .auto import is_instrumented as _is_instrumented
+    return _is_instrumented()

agent_lighthouse-0.3.0/agent_lighthouse/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""
+Framework adapters for zero-touch auto-instrumentation.
+"""
+from .langchain import LighthouseLangChainCallbackHandler, register_langchain_callbacks
+from .crewai import register_crewai_hooks
+from .autogen import register_autogen_logging
+
+__all__ = [
+    "LighthouseLangChainCallbackHandler",
+    "register_langchain_callbacks",
+    "register_crewai_hooks",
+    "register_autogen_logging",
+]

agent_lighthouse-0.3.0/agent_lighthouse/adapters/autogen.py

@@ -0,0 +1,113 @@
+"""
+AutoGen adapter via logging handler.
+Best-effort parsing of structured log records.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Optional
+
+from ..tracer import get_tracer
+
+logger = logging.getLogger("agent_lighthouse.adapters.autogen")
+
+_REGISTERED = False
+
+
+class _AutoGenLogHandler(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self._spans: dict[str, tuple[str, float]] = {}
+        self._traces: dict[str, str] = {}
+
+    def _ensure_trace(self, event_id: str, name: str) -> Optional[str]:
+        tracer = get_tracer()
+        trace_id = tracer.trace_id
+        if trace_id:
+            return trace_id
+        existing = self._traces.get(event_id)
+        if existing:
+            return existing
+        trace = tracer.client.create_trace(
+            name=name,
+            framework="autogen",
+            metadata={"event_id": event_id},
+        )
+        trace_id = trace.get("trace_id")
+        if trace_id:
+            self._traces[event_id] = trace_id
+        return trace_id
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            data = record.__dict__
+            event = data.get("event") or data.get("event_name")
+            if not event:
+                return
+
+            event_id = (
+                str(data.get("event_id") or data.get("run_id") or f"{record.created}-{event}")
+            )
+            tracer = get_tracer()
+            kind = data.get("kind") or "internal"
+            name = data.get("name") or data.get("agent_name") or event
+
+            if event.endswith("_start"):
+                trace_id = self._ensure_trace(event_id, f"{name} (autogen)")
+                if not trace_id:
+                    return
+                span = tracer.client.create_span(
+                    trace_id=trace_id,
+                    name=name,
+                    kind=kind,
+                    parent_span_id=tracer.span_id,
+                    input_data=data.get("input_data"),
+                    attributes={"event": event},
+                )
+                span_id = span.get("span_id")
+                if span_id:
+                    self._spans[event_id] = (span_id, time.perf_counter())
+                return
+
+            if event.endswith("_end") or event.endswith("_error"):
+                span_entry = self._spans.pop(event_id, None)
+                trace_id = tracer.trace_id or self._traces.get(event_id)
+                if not span_entry or not trace_id:
+                    return
+                span_id, start = span_entry
+                duration_ms = (time.perf_counter() - start) * 1000
+                status = "error" if event.endswith("_error") else "success"
+                tracer.client.update_span(
+                    trace_id=trace_id,
+                    span_id=span_id,
+                    status=status,
+                    output_data=data.get("output_data"),
+                    error_message=data.get("error_message"),
+                    error_type=data.get("error_type"),
+                    duration_ms=duration_ms,
+                )
+                if event_id in self._traces and tracer.trace_id is None:
+                    tracer.client.complete_trace(
+                        trace_id, "success" if status == "success" else "error"
+                    )
+                    self._traces.pop(event_id, None)
+        except Exception:  # noqa: BLE001
+            logger.debug("AutoGen log handling failed", exc_info=True)
+
+
+def register_autogen_logging() -> bool:
+    global _REGISTERED
+    if _REGISTERED:
+        return True
+    try:
+        import autogen  # type: ignore  # noqa: F401
+    except Exception:  # noqa: BLE001
+        return False
+
+    handler = _AutoGenLogHandler()
+    log = logging.getLogger("autogen")
+    if handler not in log.handlers:
+        log.addHandler(handler)
+    _REGISTERED = True
+    return True

agent_lighthouse-0.3.0/agent_lighthouse/adapters/crewai.py

@@ -0,0 +1,179 @@
+"""
+CrewAI adapter with best-effort feature detection.
+Fail-silent when CrewAI APIs are unavailable.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Optional
+
+from ..tracer import get_tracer
+from ..serialization import _capture_args, _capture_output
+
+logger = logging.getLogger("agent_lighthouse.adapters.crewai")
+
+_REGISTERED = False
+
+
+class _CrewAIEventHandler:
+    def __init__(self, tracer=None):
+        self.tracer = tracer or get_tracer()
+        self._run_spans: dict[str, str] = {}
+        self._run_start: dict[str, float] = {}
+        self._run_traces: dict[str, str] = {}
+
+    def _ensure_trace(self, run_id: str, name: str) -> Optional[str]:
+        trace_id = self.tracer.trace_id
+        if trace_id:
+            return trace_id
+        existing = self._run_traces.get(run_id)
+        if existing:
+            return existing
+        trace = self.tracer.client.create_trace(
+            name=name,
+            framework="crewai",
+            metadata={"run_id": run_id},
+        )
+        trace_id = trace.get("trace_id")
+        if trace_id:
+            self._run_traces[run_id] = trace_id
+        return trace_id
+
+    def _start_span(
+        self,
+        run_id: str,
+        name: str,
+        kind: str,
+        input_data: Optional[dict] = None,
+        attributes: Optional[dict] = None,
+    ) -> None:
+        trace_id = self._ensure_trace(run_id, name)
+        if not trace_id:
+            return
+        parent_span_id = self.tracer.span_id
+        span = self.tracer.client.create_span(
+            trace_id=trace_id,
+            name=name,
+            kind=kind,
+            parent_span_id=parent_span_id,
+            input_data=input_data,
+            attributes=attributes or {},
+        )
+        span_id = span.get("span_id")
+        if span_id:
+            self._run_spans[run_id] = span_id
+            self._run_start[run_id] = time.perf_counter()
+
+    def _end_span(self, run_id: str, status: str, output_data: Optional[dict] = None) -> None:
+        span_id = self._run_spans.pop(run_id, None)
+        start = self._run_start.pop(run_id, None)
+        trace_id = self.tracer.trace_id or self._run_traces.get(run_id)
+        if not trace_id or not span_id:
+            return
+        duration_ms = None
+        if start is not None:
+            duration_ms = (time.perf_counter() - start) * 1000
+        self.tracer.client.update_span(
+            trace_id=trace_id,
+            span_id=span_id,
+            status=status,
+            output_data=output_data,
+            duration_ms=duration_ms,
+        )
+        if run_id in self._run_traces and self.tracer.trace_id is None:
+            self.tracer.client.complete_trace(trace_id, "success" if status == "success" else "error")
+            self._run_traces.pop(run_id, None)
+
+    # Best-effort event handlers (method names depend on CrewAI version)
+    def on_agent_start(self, agent_name: str, run_id: str, **kwargs: Any):
+        self._start_span(
+            run_id=run_id,
+            name=agent_name or "CrewAI Agent",
+            kind="agent",
+            input_data=_capture_args((), kwargs),
+        )
+
+    def on_agent_end(self, output: Any, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "success", _capture_output(output))
+
+    def on_agent_error(self, error: Exception, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "error", {"error": str(error)})
+
+    def on_tool_start(self, tool_name: str, run_id: str, **kwargs: Any):
+        self._start_span(
+            run_id=run_id,
+            name=tool_name or "CrewAI Tool",
+            kind="tool",
+            input_data=_capture_args((), kwargs),
+        )
+
+    def on_tool_end(self, output: Any, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "success", _capture_output(output))
+
+    def on_tool_error(self, error: Exception, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "error", {"error": str(error)})
+
+    def on_task_start(self, task_name: str, run_id: str, **kwargs: Any):
+        self._start_span(
+            run_id=run_id,
+            name=task_name or "CrewAI Task",
+            kind="chain",
+            input_data=_capture_args((), kwargs),
+        )
+
+    def on_task_end(self, output: Any, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "success", _capture_output(output))
+
+    def on_task_error(self, error: Exception, run_id: str, **kwargs: Any):
+        self._end_span(run_id, "error", {"error": str(error)})
+
+
+def register_crewai_hooks() -> bool:
+    """
+    Best-effort registration using available CrewAI telemetry/callback APIs.
+    """
+    global _REGISTERED
+    if _REGISTERED:
+        return True
+
+    try:
+        import crewai  # type: ignore
+    except Exception:  # noqa: BLE001
+        return False
+
+    handler = _CrewAIEventHandler()
+
+    # Telemetry hooks (if available)
+    telemetry = getattr(crewai, "telemetry", None)
+    if telemetry is not None:
+        for attr in ("register_handler", "add_handler", "add_listener", "register"):
+            if hasattr(telemetry, attr):
+                try:
+                    getattr(telemetry, attr)(handler)
+                    _REGISTERED = True
+                    return True
+                except Exception:  # noqa: BLE001
+                    logger.debug("CrewAI telemetry hook registration failed", exc_info=True)
+
+    # Callback manager (if available)
+    callbacks = getattr(crewai, "callbacks", None)
+    if callbacks is not None:
+        manager_cls = getattr(callbacks, "CallbackManager", None)
+        if manager_cls is not None:
+            original_init = manager_cls.__init__
+
+            def patched_init(self, *args, **kwargs):  # type: ignore[no-redef]
+                original_init(self, *args, **kwargs)
+                try:
+                    if hasattr(self, "add_handler"):
+                        self.add_handler(handler)
+                except Exception:  # noqa: BLE001
+                    logger.debug("CrewAI callback registration failed", exc_info=True)
+
+            manager_cls.__init__ = patched_init  # type: ignore[assignment]
+            _REGISTERED = True
+            return True
+
+    logger.debug("CrewAI hooks not registered: unsupported API surface")
+    return False