Metadata-Version: 2.4
Name: agent-lighthouse
Version: 0.3.1
Summary: Multi-Agent Observability SDK for Agent Lighthouse
Author-email: Aditya Kumar <adityacode2112@gmail.com>
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) | `""` |
