Metadata-Version: 2.4
Name: agent-trace-log
Version: 0.0.2
Summary: LLM API 代理与日志追踪系统 - 透明观察智能体行为
Author: Agent-Trace-Log Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/xiaozhiagi/agent-trace-log
Project-URL: Documentation, https://github.com/xiaozhiagi/agent-trace-log#readme
Project-URL: Repository, https://github.com/xiaozhiagi/agent-trace-log
Project-URL: Issues, https://github.com/xiaozhiagi/agent-trace-log/issues
Keywords: llm,agent,trace,log,proxy,openai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.5.3
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: jinja2>=3.1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

# Agent-Trace-Log - LLM API Logging & Tracing System

An OpenAI-compatible LLM API proxy service focused on **logging and agent behavior observation**.

[中文文档](README_zh.md)

## Why Agent-Trace-Log?

When learning agent frameworks, you might wonder:
- What prompts does the agent send?
- How does it think and make decisions?
- How are messages passed in multi-turn conversations?

Most proxy APIs or official APIs don't provide log viewing functionality. **Agent-Trace-Log makes everything transparent**.

## Features

- ✅ **OpenAI/Anthropic Compatible** - Supports both OpenAI and Anthropic API formats
- ✅ **Streaming Support** - Full SSE streaming response support
- ✅ **Complete Logging** - Request/response automatically recorded to SQLite database
- ✅ **Web Dashboard** - Visual log viewing, prompts, and model calls
- ✅ **Multi-Provider Support** - Configure multiple upstream APIs with flexible switching
- ✅ **API Authentication** - Supports multiple API key authentication
- ✅ **Rate Limiting** - Configurable requests per minute limit
- ✅ **Model Mapping** - Custom model name mapping
- ✅ **Docker Deployment** - Containerized deployment support
- ✅ **pip Installation** - Install directly from PyPI

## Quick Start

### Option 1: Install from PyPI

```bash
# Install from PyPI
pip install agent-trace-log

# Start the service
agent-trace-log web

# Specify port
agent-trace-log web --port 9000
```

### Option 2: Install from Source

```bash
# Clone the project
git clone https://github.com/xiaozhiagi/agent-trace-log.git
cd agent-trace-log

# Install in development mode
pip install -e .

# Start the service
agent-trace-log web

# Development mode (hot reload)
agent-trace-log web --reload

# Or run directly
python agent_trace_log/main.py
```

### Option 3: Docker Deployment

```bash
# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
```

## CLI Commands

```bash
agent-trace-log                 # Show help
agent-trace-log web                # Start service (default 0.0.0.0:8000)
agent-trace-log web --reload       # Development mode, auto-reload on code changes
agent-trace-log web --port 9000    # Specify port
agent-trace-log web --host 127.0.0.1  # Specify host
agent-trace-log version            # Show version
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `BAILOU_API_KEY` | Default upstream API key | - |
| `BAILOU_BASE_URL` | Default upstream API URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `LISTEN_HOST` | Listen address | `0.0.0.0` |
| `LISTEN_PORT` | Listen port | `8000` |
| `API_KEYS` | Service API keys (comma-separated) | Empty |
| `RATE_LIMIT_ENABLED` | Enable rate limiting | `false` |
| `RATE_LIMIT` | Max requests per minute | `60` |
| `MODEL_MAPPING` | Model mapping (JSON format) | `{}` |
| `LOG_LEVEL` | Log level | `INFO` |
| `DATABASE_PATH` | Database file path | `./logs.db` |
| `REQUEST_TIMEOUT` | Request timeout (seconds) | `120` |

### Model Mapping Example

```bash
# Map gpt-3.5 to qwen-turbo, gpt-4 to qwen-max
MODEL_MAPPING='{"gpt-3.5": "qwen-turbo", "gpt-4": "qwen-max"}'
```

## API Usage

### OpenAI Format

```bash
# Chat completion
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Streaming request
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

### Anthropic Format

```bash
curl -X POST http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

> 也支持 `Authorization: Bearer your-api-key` 格式，两种认证方式均可。

### Other Endpoints

```bash
# List models
curl http://localhost:8000/v1/models

# Health check
curl http://localhost:8000/health
```

## Log Query

### Web Interface

Visit `http://localhost:8000/` to open the dashboard. You can view:
- All request logs
- Complete request/response content
- Token consumption statistics
- Model call distribution

### API Endpoints

```bash
# Get log list
curl "http://localhost:8000/api/logs?limit=50&offset=0"

# Filter by model
curl "http://localhost:8000/api/logs?model=qwen-turbo"

# Filter by status
curl "http://localhost:8000/api/logs?status=success"

# Get statistics
curl "http://localhost:8000/api/logs/stats"

# Get single log detail
curl "http://localhost:8000/api/logs/req_xxxxxxxxxxxx"
```

## Project Structure

```
agent-trace-log/
├── agent_trace_log/       # Python package
│   ├── __init__.py      # Package entry point
│   ├── main.py          # FastAPI application
│   ├── cli.py           # CLI entry (agent-trace-log web)
│   ├── config.py        # Configuration management
│   ├── database.py      # Database operations
│   ├── middleware.py    # Middleware (auth, rate limiting)
│   ├── services/
│   │   ├── __init__.py
│   │   ├── proxy.py     # Proxy service
│   │   └── logger.py    # Logging service
│   ├── templates/       # HTML templates
│   │   ├── index.html   # Home dashboard
│   │   ├── logs.html    # Log list
│   │   ├── log_detail.html  # Log detail
│   │   ├── docs.html    # API docs
│   │   ├── usage.html   # Usage guide
│   │   └── health.html  # Health check
│   └── static/          # Static files
│       └── i18n.js      # Internationalization
├── pyproject.toml       # Package configuration
├── requirements.txt     # Python dependencies
├── Dockerfile           # Docker image
├── docker-compose.yml   # Docker Compose config
├── README.md            # English documentation
└── README_zh.md         # Chinese documentation
```

## Security Recommendations

1. **Configure API_KEYS in production** - Prevent unauthorized access
2. **Enable rate limiting** - Prevent API abuse
3. **Use HTTPS** - Recommended with Nginx reverse proxy
4. **Backup database regularly** - `logs.db` contains all request records

## Nginx Reverse Proxy Example

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## License

MIT License
