Metadata-Version: 2.4
Name: revenium-middleware-anthropic
Version: 0.2.26
Summary: A Python library that meters Anthropic usage to Revenium.
Author-email: Revenium <info@revenium.io>
License: MIT
Project-URL: Homepage, https://github.com/revenium/revenium-middleware-anthropic-python
Project-URL: Bug Tracker, https://github.com/revenium/revenium-middleware-anthropic-python/issues
Project-URL: Documentation, https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/README.md
Project-URL: Changelog, https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/CHANGELOG.md
Keywords: anthropic,middleware,logging,token-usage,metering,revenium,aws,bedrock,claude
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wrapt
Requires-Dist: anthropic
Requires-Dist: revenium_middleware>=0.3.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: freezegun; extra == "dev"
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.34.0; extra == "bedrock"
Dynamic: license-file

#  Revenium Middleware for Anthropic

[![PyPI version](https://img.shields.io/pypi/v/revenium-middleware-anthropic.svg)](https://pypi.org/project/revenium-middleware-anthropic/)
[![Python Versions](https://img.shields.io/pypi/pyversions/revenium-middleware-anthropic.svg)](https://pypi.org/project/revenium-middleware-anthropic/)
[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A production-ready middleware library for metering and monitoring Anthropic API usage in Python applications. Supports both direct Anthropic API and AWS Bedrock with comprehensive streaming functionality.

## Features

- **Precise Usage Tracking**: Monitor tokens, costs, and request counts for Anthropic chat completions
- **Seamless Integration**: Drop-in middleware that works with minimal code changes
- **AWS Bedrock Support**: Full integration with automatic detection and metering for Anthropic models via AWS Bedrock
- **Complete Streaming Support**: Full streaming functionality for both Anthropic API and AWS Bedrock
- **Hybrid Initialization**: Auto-initialization on import + explicit control for advanced configuration
- **Thread-Safe**: Production-ready with comprehensive thread safety for concurrent applications
- **Flexible Configuration**: Customize metering behavior to suit your application needs

## What's Supported

| Feature | Direct Anthropic API | AWS Bedrock |
|---------|---------------------|-------------|
| **Chat Completion** | Full support | Full support |
| **Streaming** | Full support | Full support |
| **Token Metering** | Automatic | Automatic |
| **Metadata Tracking** | Full support | Full support |
| **Thread Safety** | Production-ready | Production-ready |
| **Auto-initialization** | Zero-config | Zero-config |

**Note**: The middleware only wraps `messages.create` and `messages.stream` endpoints. Other Anthropic SDK features work normally but aren't metered.

## Installation

```bash
# Basic installation
pip install revenium-middleware-anthropic

# With AWS Bedrock support
pip install revenium-middleware-anthropic[bedrock]
```

## Quick Start

Set your environment variables and import the middleware - your Anthropic calls will be metered automatically:

```python
import anthropic
import revenium_middleware_anthropic  # Auto-initializes on import

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=100,
    messages=[{"role": "user", "content": "Please verify you are ready to assist me."}]
)
print(message.content[0].text)
```

**That's it!** The middleware automatically meters all Anthropic API calls. No code changes required.

**For complete examples, see:**
- [`examples/getting_started.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/getting_started.py) - Minimal example with all metadata fields documented
- [`examples/anthropic-advanced.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-advanced.py) - Production-ready with detailed metadata tracking
- [`examples/anthropic-streaming.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-streaming.py) - Streaming support with token tracking
- [`examples/anthropic-bedrock.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-bedrock.py) - Complete AWS Bedrock integration

### Configuration

Set these environment variables before running your application:

```bash
export REVENIUM_METERING_API_KEY="your-api-key"
export REVENIUM_METERING_BASE_URL="https://api.revenium.ai/meter"
export ANTHROPIC_API_KEY="your-anthropic-key"
```

**Optional:** Enable debug logging with `export REVENIUM_LOG_LEVEL=DEBUG`

## AWS Bedrock Integration

The middleware provides complete AWS Bedrock integration with automatic detection and full streaming support.

**Provider Detection:** The middleware automatically chooses between Bedrock and direct Anthropic API based on:
- AWS credentials availability (`aws configure`, IAM roles, environment variables)
- Base URL detection (when `base_url` contains `amazonaws.com`)
- Defaults to direct Anthropic API for safety - Bedrock only used when explicitly configured

**See [`examples/anthropic-bedrock.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-bedrock.py)** for complete working examples covering:
- Basic chat completion via AWS Bedrock
- Metadata tracking with Bedrock
- Streaming support with Bedrock
- Model mapping and configuration

### Bedrock Configuration

#### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `REVENIUM_METERING_API_KEY` | Your Revenium API key | **Required** |
| `REVENIUM_METERING_BASE_URL` | Revenium API endpoint | **Required** |
| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
| `REVENIUM_BEDROCK_DISABLE` | Set to `1` to disable Bedrock support | Not set |

#### AWS Authentication

The middleware uses the standard AWS credential chain:

1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
2. AWS credentials file (`~/.aws/credentials`)
3. IAM roles (for EC2/Lambda/ECS)
4. AWS SSO

**Required AWS permissions:**
- `bedrock:InvokeModel` (for non-streaming requests)
- `bedrock:InvokeModelWithResponseStream` (for streaming requests)

### Supported Models

The middleware automatically maps Anthropic model names to Bedrock model IDs:

| Anthropic Model | Bedrock Model ID |
|----------------|------------------|
| `claude-3-opus-20240229` | `anthropic.claude-3-opus-20240229-v1:0` |
| `claude-3-sonnet-20240229` | `anthropic.claude-3-sonnet-20240229-v1:0` |
| `claude-3-haiku-20240307` | `us.anthropic.claude-3-5-haiku-20241022-v1:0` |
| `claude-3-5-sonnet-20240620` | `anthropic.claude-3-5-sonnet-20240620-v1:0` |
| `claude-3-5-sonnet-20241022` | `anthropic.claude-3-5-sonnet-20241022-v2:0` |
| `claude-3-5-haiku-20241022` | `anthropic.claude-3-5-haiku-20241022-v1:0` |

For other models, the middleware uses the format `anthropic.{model_name}`.

## Streaming Support

The middleware provides complete streaming support for both direct Anthropic API and AWS Bedrock with:
- **Universal Interface**: Same code works with both providers
- **Automatic Detection**: Provider routing happens transparently
- **Complete Token Tracking**: Accurate token counting and metering
- **Thread-Safe**: Production-ready concurrent streaming support
- **Graceful Fallback**: Automatic fallback to direct API if Bedrock fails

**See [`examples/anthropic-streaming.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-streaming.py)** for complete streaming examples with metadata tracking and error handling.

## Metadata Fields

Add business context to track usage by organization, user, task type, or custom fields. Pass a `usage_metadata` dictionary with any of these optional fields:

| Field | Description | Use Case |
|-------|-------------|----------|
| `trace_id` | Unique identifier for session or conversation tracking | Link multiple API calls together for debugging, user session analytics, or distributed tracing across services |
| `task_type` | Type of AI task being performed | Categorize usage by workload (e.g., "chat", "code-generation", "doc-summary") for cost analysis and optimization |
| `subscriber.id` | Unique user identifier | Track individual user consumption for billing, rate limiting, or user analytics |
| `subscriber.email` | User email address | Identify users for support, compliance, or usage reports |
| `subscriber.credential.name` | Authentication credential name | Track which API key or service account made the request |
| `subscriber.credential.value` | Authentication credential value | Associate usage with specific credentials for security auditing |
| `organization_id` | Organization or company identifier | Multi-tenant cost allocation, usage quotas per organization |
| `subscription_id` | Subscription plan identifier | Track usage against subscription limits, identify plan upgrade opportunities |
| `product_id` | Your product or feature identifier | Attribute AI costs to specific features in your application (e.g., "chatbot", "email-assistant") |
| `agent` | AI agent or bot identifier | Distinguish between multiple AI agents or automation workflows in your system |
| `response_quality_score` | Custom quality rating (0.0-1.0) | Track user satisfaction or automated quality metrics for model performance analysis |

**Resources:**
- [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
- [`examples/anthropic-advanced.py`](https://github.com/revenium/revenium-middleware-anthropic-python/blob/HEAD/examples/anthropic-advanced.py) - Working code examples

## Troubleshooting

| Issue | Solution |
|-------|----------|
| **"No module named 'boto3'"** | Install with Bedrock support: `pip install revenium-middleware-anthropic[bedrock]` |
| **Requests go to Anthropic instead of Bedrock** | Verify AWS credentials: `aws sts get-caller-identity` |
| **"AccessDenied" errors** | Ensure AWS credentials have `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions |
| **Model not available** | Check if Claude models are available in your AWS region |
| **Middleware not working** | Verify `REVENIUM_METERING_API_KEY` and `REVENIUM_METERING_BASE_URL` are set |
| **Streaming errors** | Check AWS credentials; middleware automatically falls back to direct API |

**Debug Mode:** Set `REVENIUM_LOG_LEVEL=DEBUG` to see provider detection and routing decisions
**Force Direct API:** Set `REVENIUM_BEDROCK_DISABLE=1` to disable Bedrock detection
**Check Status:** Use `revenium_middleware_anthropic.is_initialized()` to verify setup

## Compatibility

- **Python 3.8+**
- **Anthropic Python SDK** (latest version recommended)
- **AWS Bedrock** (with `boto3>=1.34.0` when using `[bedrock]` extra)
- **Thread-Safe** (production-ready for concurrent applications)

## Logging

Control logging with the `REVENIUM_LOG_LEVEL` environment variable. Available levels:
- `DEBUG`: Detailed debugging information (provider detection, routing decisions)
- `INFO`: General information (default)
- `WARNING`: Warning messages only
- `ERROR`: Error messages only

## Documentation

For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)

## Contributing

See [CONTRIBUTING.md](https://github.com/revenium/revenium-middleware-anthropic-python/blob/main/CONTRIBUTING.md)

## Code of Conduct

See [CODE_OF_CONDUCT.md](https://github.com/revenium/revenium-middleware-anthropic-python/blob/main/CODE_OF_CONDUCT.md)

## Security

See [SECURITY.md](https://github.com/revenium/revenium-middleware-anthropic-python/blob/main/SECURITY.md)

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/revenium/revenium-middleware-anthropic-python/blob/main/LICENSE) file for details.

## Support

For issues, feature requests, or contributions:

- **Website**: [www.revenium.ai](https://www.revenium.ai)
- **GitHub Repository**: [revenium/revenium-middleware-anthropic-python](https://github.com/revenium/revenium-middleware-anthropic-python)
- **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-anthropic-python/issues)
- **Documentation**: [docs.revenium.io](https://docs.revenium.io)
- **Email**: support@revenium.io

---

**Built by Revenium**
