Metadata-Version: 2.4
Name: agentlensx
Version: 0.1.0
Summary: AI-powered observability SDK for AI agents
Author: AgentLens Team
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AgentLens Python SDK

Official Python SDK (`agentlensx`) for integrating AgentLens observability, deterministic anomaly detection, and AI root-cause investigation into AI agents.

- 🌐 **Live Cloud Dashboard**: [https://agent-lens-kappa.vercel.app](https://agent-lens-kappa.vercel.app)
- ⚡ **Production API**: [https://agentlens-backend-ofqg.onrender.com](https://agentlens-backend-ofqg.onrender.com)

---

## Installation

### From PyPI:
```bash
pip install agentlensx
```

### From GitHub (Direct):
```bash
pip install git+https://github.com/Siva-2517/AgentLens.git#subdirectory=sdk
```

### From Local Source:
```bash
cd sdk
pip install -e .
```

### Development Installation:
```bash
pip install -e ".[dev]"
```

---

## Quick Start

```python
import os
from agentlensx import AgentLens, EventType

# Initialize the SDK (Live Cloud or Local)
lens = AgentLens(
    api_url="https://agentlens-backend-ofqg.onrender.com",  # Or http://localhost:8000
    api_key=os.getenv("AGENTLENS_API_KEY", "al_live_your_key_here"),
    project_name="my-ai-agent",
)

# Use context manager for automatic trace management
with lens.trace("customer-support-agent") as trace_id:
    # Your agent code here
    user_input = "How do I reset my password?"
    
    # Log LLM calls
    lens.create_event(
        EventType.LLM_CALL,
        data={
            "model": "gpt-4",
            "prompt": user_input,
        }
    )
    
    # Agent processes...
    response = "To reset your password, visit..."
    
    lens.create_event(
        EventType.LLM_RESPONSE,
        data={"response": response}
    )
    
    # Log tool calls
    lens.create_event(
        EventType.TOOL_CALL,
        data={
            "tool": "search_knowledge_base",
            "query": "password reset",
        }
    )
    
    lens.create_event(
        EventType.TOOL_RESPONSE,
        data={"results": ["article_1", "article_2"]}
    )

# Trace automatically ends and events are flushed
```

## Features

### Event Types

The SDK supports the following event types:

- `AGENT_START` - Agent execution begins
- `LLM_CALL` - LLM API call initiated
- `LLM_RESPONSE` - LLM response received
- `TOOL_CALL` - Tool/function call initiated
- `TOOL_RESPONSE` - Tool response received
- `STATE_CHANGE` - Agent state changed
- `RETRY` - Operation retry attempted
- `ERROR` - Error occurred
- `AGENT_END` - Agent execution completed

### Automatic Trace Management

Use the context manager for automatic trace lifecycle:

```python
with lens.trace("agent-name") as trace_id:
    # AGENT_START event created automatically
    # Your code here
    pass
    # AGENT_END event created automatically
    # Events flushed automatically
```

### Manual Trace Management

For more control:

```python
trace = lens.create_trace("manual-trace")

lens.create_event(
    EventType.LLM_CALL,
    trace_id=trace.trace_id,
    data={"model": "gpt-4"}
)

lens.end_trace(trace.trace_id, status="completed")
lens.flush()
```

### Error Handling

Errors are automatically captured:

```python
with lens.trace("agent-with-error"):
    try:
        # Your code
        risky_operation()
    except Exception as e:
        lens.create_event(
            EventType.ERROR,
            data={
                "error_type": type(e).__name__,
                "error_message": str(e),
            }
        )
        raise
# Trace status automatically set to "failed"
```

### Configuration

```python
from agentlensx import AgentLens, AgentLensConfig

config = AgentLensConfig(
    api_url="http://localhost:8000",
    api_key="your_api_key",  # Optional
    project_name="my-project",
    enabled=True,  # Set to False to disable telemetry
    batch_size=100,  # Events before auto-flush
    timeout=5,  # HTTP timeout in seconds
)

lens = AgentLens(**config.model_dump())
```

### Disable Telemetry

```python
# Disable for testing or local development
lens = AgentLens(enabled=False)
```

### Nested Events

Track parent-child relationships:

```python
with lens.trace("main-agent"):
    parent_event = lens.create_event(
        EventType.TOOL_CALL,
        data={"tool": "orchestrator"}
    )
    
    # Child event
    lens.create_event(
        EventType.LLM_CALL,
        parent_event_id=parent_event.event_id,
        data={"model": "gpt-4"}
    )
```

## API Reference

### AgentLens

Main client class for the SDK.

**Methods:**

- `create_trace(name, trace_id=None, metadata=None)` - Create a new trace
- `end_trace(trace_id, status="completed")` - End a trace
- `create_event(event_type, data=None, trace_id=None, parent_event_id=None, metadata=None)` - Create an event
- `trace(name, trace_id=None, metadata=None)` - Context manager for tracing
- `flush()` - Manually flush pending events
- `close()` - Close client and flush events

### Event Types

All available event types are in the `EventType` enum:

```python
from agentlensx import EventType

EventType.AGENT_START
EventType.LLM_CALL
EventType.LLM_RESPONSE
EventType.TOOL_CALL
EventType.TOOL_RESPONSE
EventType.STATE_CHANGE
EventType.RETRY
EventType.ERROR
EventType.AGENT_END
```

## Testing

Run tests:

```bash
pytest
```

Run with coverage:

```bash
pytest --cov=agentlensx --cov-report=html
```

## Architecture

The SDK is designed to be lightweight and non-intrusive:

1. **Client** (`AgentLens`) - Main interface for creating traces and events
2. **Types** - Pydantic models for traces and events
3. **Context** - Thread-safe context management for traces
4. **Exporter** - HTTP client for sending data to AgentLens API
5. **Config** - Configuration management

## Requirements

- Python 3.11+
- httpx
- pydantic

## Development

Install development dependencies:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

Format code:

```bash
black agentlensx tests
```

Lint:

```bash
ruff check agentlensx tests
```

## License

Distributed under the [MIT License](LICENSE). Copyright (c) 2026 Siva.
