Metadata-Version: 2.4
Name: agent-observability
Version: 1.1.0
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.

## Quick Start (One Line)

```bash
pip install agent-observability && python -c "from agent_observability import AgentLogger; AgentLogger(api_key='ao_live_...').log('test', {})"
```

## Installation

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

## Usage

### Basic Logging

```python
from agent_observability import AgentLogger

# Initialize with API key
logger = AgentLogger(api_key="ao_live_...")
# Or set AGENT_OBS_API_KEY environment variable

# 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(api_key="...", async_mode=True)
logger.log("api_call", {"latency_ms": 100})  # Returns immediately
```

## Features

- **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://agentobs.io/pricing.json) for programmatic access.

## Integrations

- **LangChain**: Built-in tool integration
- **AutoGPT**: Plugin available
- **CrewAI**: Native support
- **Generic Python**: Works with any agent

## API Reference

### AgentLogger

```python
AgentLogger(
    api_key: str,                    # API key (or AGENT_OBS_API_KEY env var)
    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,                 # api_call, decision, transaction, error, state_change
    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
)
```

## License

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

