Metadata-Version: 2.4
Name: usefy
Version: 2.1.0
Summary: Official Python SDK for Usefy - AI Cost Control & Budget Management
Author-email: Usefy <support@usefy.ai>
License: MIT
Project-URL: Homepage, https://usefy.ai
Project-URL: Documentation, https://usefy.ai/docs
Project-URL: Repository, https://github.com/sherlocq61/usefy
Project-URL: Changelog, https://github.com/sherlocq61/usefy/blob/main/CHANGELOG.md
Keywords: ai,openai,anthropic,cost-control,budget,llm,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# Usefy Python SDK

Official Python SDK for [Usefy](https://usefy.ai) - AI Cost Control & Budget Management.

## Installation

```bash
pip install usefy
```

Or install from source:
```bash
pip install git+https://github.com/sherlocq61/usefy.git#subdirectory=sdk/python
```

## Quick Start

```python
from usefy import Usefy

# Initialize client
client = Usefy(api_key="us_live_your_key_here")

# Use like OpenAI - model auto-detection included
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response["choices"][0]["message"]["content"])
```

## Features

### OpenAI-Compatible Interface

```python
# GPT-4
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

# Claude (auto-detected)
response = client.chat.completions.create(
    model="claude-3-opus",
    messages=[{"role": "user", "content": "Write a poem"}]
)

# Gemini
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    provider="google",  # Explicit provider
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Fail-Open Mode

For maximum reliability, enable fail-open mode. If Usefy is temporarily unavailable, the SDK will signal that you should fall back to direct provider calls:

```python
client = Usefy(
    api_key="us_live_xxx",
    fail_open=True,
    fail_open_timeout=2.0  # 2 seconds
)

try:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except UsefyTimeoutError:
    if client.is_fail_open_active:
        # Fall back to direct OpenAI call
        import openai
        response = openai.chat.completions.create(...)
```

### Pre-flight Check

Check if a request would be allowed before making it:

```python
check = client.check(
    provider="openai",
    model="gpt-4",
    estimated_tokens=1000
)

if check["allowed"]:
    # Proceed with request
    response = client.chat.completions.create(...)
else:
    print(f"Request would be blocked: {check['reason']}")
```

### Usage Monitoring

```python
usage = client.get_usage()

print(f"Requests: {usage['monthly_requests']['used']}/{usage['monthly_requests']['limit']}")
print(f"Plan: {usage['plan_name']}")
```

## Configuration

### Environment Variables

```bash
export USEFY_API_KEY="us_live_your_key"
```

Then:
```python
client = Usefy()  # API key from env
```

### Full Configuration

```python
from usefy import Usefy, UsefyConfig

config = UsefyConfig(
    api_key="us_live_xxx",
    base_url="https://api.usefy.ai",
    timeout=30.0,
    max_retries=3,
    retry_delay=1.0,
    fail_open=False,
    fail_open_timeout=2.0,
    log_level="WARNING"
)

client = Usefy(config=config)
```

## Supported Providers

| Provider | Models | Auto-Detection |
|----------|--------|----------------|
| OpenAI | gpt-4, gpt-3.5-turbo, o1, etc. | ✅ |
| Anthropic | claude-3-opus, claude-3-sonnet | ✅ |
| Google | gemini-2.0-flash, gemini-pro | ✅ |
| Mistral | mistral-large, mixtral | ✅ |
| Cohere | command-r, command | ✅ |
| DeepSeek | deepseek-chat | ✅ |
| Groq | llama-3.1-70b | ✅ |
| Together | various | Manual |
| xAI | grok-2 | ✅ |

## Error Handling

```python
from usefy import (
    Usefy,
    UsefyError,
    UsefyAuthError,
    UsefyBudgetExceeded,
    UsefyRateLimited
)

try:
    response = client.chat.completions.create(...)
except UsefyAuthError:
    print("Invalid API key")
except UsefyBudgetExceeded as e:
    print(f"Budget exceeded: {e.budget_info}")
except UsefyRateLimited as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except UsefyError as e:
    print(f"Error: {e.message}")
```

## License

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

## Support

- Documentation: https://usefy.ai/docs
- Email: support@usefy.ai
- Issues: https://github.com/sherlocq61/usefy/issues
