Metadata-Version: 2.4
Name: modelcost-sdk
Version: 0.3.0
Summary: Python SDK for the ModelCost API — track, govern, and optimize AI model spending.
Project-URL: Homepage, https://modelcost.ai
Project-URL: Documentation, https://modelcost.ai/docs
Author-email: ModelCost <support@modelcost.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,budget,cost,governance,llm,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# ModelCost Python SDK

Python SDK for the ModelCost API. Track, govern, and optimize your AI model spending in real time.

## Installation

```bash
pip install modelcost
```

For development:

```bash
pip install modelcost[dev]
```

## Quick Start

```python
import modelcost

# Initialize the SDK
modelcost.init(api_key="mc_your_api_key", org_id="org_123")

# Wrap your OpenAI client for automatic tracking
import openai
client = openai.OpenAI()
wrapped = modelcost.wrap(client)

# All calls are now tracked automatically
response = wrapped.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

# Or track costs manually
modelcost.track_cost(
    provider="openai",
    model="gpt-4o",
    input_tokens=150,
    output_tokens=50,
    feature="chatbot",
)

# Check budget before expensive operations
budget = modelcost.check_budget(feature="chatbot", estimated_cost=0.50)
if not budget.allowed:
    print(f"Budget exceeded: {budget.reason}")

# Scan text for PII before sending to models
result = modelcost.scan_pii("Contact me at test@example.com")
if result.detected:
    print(f"PII found: {result.entities}")

# Get current usage summary
usage = modelcost.get_usage()

# Flush any buffered events and shut down
modelcost.shutdown()
```

## Configuration

You can configure the SDK via environment variables:

| Variable | Description |
|---|---|
| `MODELCOST_API_KEY` | Your API key (must start with `mc_`) |
| `MODELCOST_ORG_ID` | Your organization ID |
| `MODELCOST_ENV` | Environment name (default: `production`) |
| `MODELCOST_BASE_URL` | API base URL (default: `https://api.modelcost.ai`) |

## License

MIT
