Metadata-Version: 2.4
Name: agent-observability
Version: 1.1.4
Summary: Agent observability with cost tracking and compliance audit trails
Home-page: https://github.com/blueskylineassets/agent-observability
Author: Agent Observability Team
Author-email: Agent Observability Team <support@agentobs.io>
License: MIT
Project-URL: Homepage, https://api-production-0c55.up.railway.app
Project-URL: Documentation, https://api-production-0c55.up.railway.app/docs
Project-URL: Repository, https://github.com/blueskylineassets/agent-observability
Project-URL: Pricing, https://api-production-0c55.up.railway.app/pricing.json
Project-URL: OpenAPI, https://api-production-0c55.up.railway.app/openapi.json
Keywords: agent,observability,logging,compliance,audit,ai-agent,langchain,autogpt,crewai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.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: mypy>=1.8.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Agent Observability SDK

Python SDK for the Agent Observability platform - structured logging, cost tracking, and compliance audit trails for AI agents.

---

## Try It Now (30 seconds)

**Step 1: Install**
```bash
pip install agent-observability
```

**Step 2: Run this command**
```bash
python -c "from agent_observability import log_event; log_event('decision', {'source': 'readme_test'})"
```

**You'll see:**
```
============================================================
✅ Agent Observability - Auto-registered!
============================================================

📋 Your API key: ao_live_abc123...
💾 Save to .env: AGENT_OBS_API_KEY=ao_live_abc123...
📖 Docs: https://pypi.org/project/agent-observability/
🤖 Agent ID: your-machine-abc123

============================================================
```

That's it! Your logs are now being collected.

---

## Get Started in Code

```python
from agent_observability import AgentLogger

logger = AgentLogger()  # Auto-registers on first use!
logger.log("decision", {"model": "gpt-4", "action": "summarize"})
```

**No signup. No API keys to copy. No configuration.**

## Quick Log Function (Even Faster)

```python
from agent_observability import log_event

log_event("api_call", {"provider": "openai", "cost_usd": 0.002})
```

## Installation

```bash
pip install agent-observability
```

## Usage

### Basic Logging

```python
from agent_observability import AgentLogger

# Auto-registers if no API key provided
logger = AgentLogger()

# Or use existing API key
logger = AgentLogger(api_key="ao_live_...")

# Log an API call
logger.log("api_call", {
    "provider": "openai",
    "model": "gpt-4",
    "cost_usd": 0.002,
    "latency_ms": 1200,
    "tokens_used": 1500,
})

# Log a decision
logger.log("decision", {
    "decision_reason": "Chose provider A due to cost optimization",
    "alternatives_considered": ["providerB", "providerC"],
})

# Log an error
logger.log("error", {
    "error_message": "Rate limit exceeded",
    "retry_count": 3,
}, severity="error")
```

### Context Manager (Automatic Timing)

```python
with logger.task("generate_image") as task:
    result = call_dalle_api()
    task.log_cost(0.02)
    task.log_metadata({"model": "dall-e-3"})
# Automatically logs timing and handles errors
```

### Batch Logging (Efficient)

```python
with logger.batch() as batch:
    for i in range(1000):
        batch.log("event", {
            "index": i,
            "cost_usd": 0.0001,
        })
# Sends all logs in a single request
```

### Async Mode

```python
# Fire-and-forget logging (non-blocking)
logger = AgentLogger(async_mode=True)
logger.log("api_call", {"latency_ms": 100})  # Returns immediately
```

## Features

- **Zero-Friction Setup**: Auto-registers on first log (v1.1.0+)
- **Automatic Retries**: Exponential backoff with 3 retries
- **Circuit Breaker**: Prevents cascade failures when API is down
- **Local Fallback**: Logs to `~/.agent_observability/fallback.jsonl` when offline
- **Batch Support**: Send up to 1000 logs per request
- **Async Mode**: Non-blocking logging for high-throughput agents

## Pricing

- **Free**: 100K logs/month
- **Cost**: $0.0001/log ($10 per 100K logs)

See [pricing.json](https://api-production-0c55.up.railway.app/pricing.json) for programmatic access.

## Framework Integrations

| Package | Install |
|---------|---------|
| LangChain | `pip install agent-observability-langchain` |
| AutoGPT | `pip install agent-observability-autogpt` |
| CrewAI | `pip install agent-observability-crewai` |
| MCP (Claude) | `npm install -g agent-observability-mcp` |

## API Reference

### AgentLogger

```python
AgentLogger(
    api_key: str = None,             # API key (auto-registers if not provided)
    base_url: str = None,            # API base URL
    default_agent_id: str = None,    # Default agent ID for all logs
    timeout: float = 10.0,           # Request timeout
    max_retries: int = 3,            # Max retry attempts
    fallback_path: str = None,       # Local fallback file path
    async_mode: bool = False,        # Enable async logging
)
```

### log()

```python
logger.log(
    event_type: str,                 # Any string (e.g., api_call, decision, test, custom_event)
    metadata: dict = None,           # Event metadata
    agent_id: str = None,            # Agent identifier
    severity: str = "info",          # debug, info, warning, error, critical
    request_body: str = None,        # Request body (truncated to 10KB)
    response_body: str = None,       # Response body (truncated to 10KB)
    tags: list[str] = None,          # Tags for filtering
    context_id: UUID = None,         # For grouping related logs
    timestamp: datetime = None,      # Custom timestamp
)
```

### log_event()

```python
from agent_observability import log_event

# Quick one-liner - auto-registers if needed
log_event(
    event_type: str,                 # Event type
    metadata: dict = None,           # Event metadata
    **kwargs                         # Additional logger.log() arguments
)
```

## License

MIT License - See [LICENSE](LICENSE) for details.
