Metadata-Version: 2.4
Name: qufas
Version: 0.1.0
Summary: Official Qufas Python Platform SDK for models, usage, billing, and API key management.
Author: Qufas AI
License-Expression: MIT
Project-URL: Homepage, https://qufas.ai
Project-URL: Documentation, https://qufas.ai/docs
Project-URL: Source, https://github.com/qufas-ai/qufas-python
Keywords: qufas,ai,sdk,api,models,billing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Qufas Python SDK

Official Python SDK for managing Qufas AI Platform.

The Qufas Python SDK is a platform management SDK. It is designed for account
and developer workflows such as listing models, reading usage, checking billing
balance, and listing API key metadata.

For chat completions and model inference, use the official OpenAI SDK with the
Qufas OpenAI-compatible endpoint:

```python
from openai import OpenAI

client = OpenAI(
    api_key="qf_sk_xxxxx",
    base_url="https://api.qufas.ai/v1",
)
```

## Installation

```bash
pip install qufas
```

## Quick Start

```python
from qufas import Qufas

client = Qufas(
    api_key="qf_sk_xxxxx"
)

client.models.list()
client.usage.list()
client.billing.balance()
client.api_keys.list()
```

You can also load the API key from an environment variable:

```bash
export QUFAS_API_KEY="qf_sk_xxxxx"
```

```python
from qufas import Qufas

client = Qufas()
print(client.billing.balance())
```

## Platform APIs

### Models

List models available to the authenticated Qufas API key.

```python
models = client.models.list()

for model in models["data"]:
    print(model["id"])
```

### Usage

List recent usage records for the authenticated account.

```python
usage = client.usage.list(limit=25)

print(usage["totals"]["total_tokens"])
print(usage["totals"]["cost"])
```

### Billing

Read the current prepaid balance.

```python
balance = client.billing.balance()

print(balance["balance"], balance["currency"])
```

### API Keys

List API key metadata. Full API key values are never returned.

```python
keys = client.api_keys.list()

for key in keys["data"]:
    print(key["id"], key["prefix"], key["status"])
```

`client.api_keys.create()` and `client.api_keys.delete()` are included for
forward compatibility with the public API surface. They may return
`501 not_implemented` until Qufas enables public API key creation and deletion.

## Chat Completions

Qufas AI is OpenAI-compatible. Use the official OpenAI SDK for model inference.

```python
from openai import OpenAI

client = OpenAI(
    api_key="qf_sk_xxxxx",
    base_url="https://api.qufas.ai/v1",
)

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {
            "role": "user",
            "content": "Write a haiku about artificial intelligence.",
        }
    ],
)

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

The Qufas Python SDK intentionally does not duplicate chat completion methods.
This keeps the primary developer experience compatible with existing OpenAI SDK
applications.

## Configuration

```python
from qufas import Qufas

client = Qufas(
    api_key="qf_sk_xxxxx",
    base_url="https://api.qufas.ai",
    timeout=30.0,
)
```

| Option | Description |
| --- | --- |
| `api_key` | Qufas API key. If omitted, `QUFAS_API_KEY` is used. |
| `base_url` | Qufas API origin. Defaults to `https://api.qufas.ai`. |
| `timeout` | Request timeout in seconds. Defaults to `30.0`. |

## Error Handling

```python
from qufas import Qufas, QufasAPIError, QufasAuthenticationError

client = Qufas(api_key="qf_sk_xxxxx")

try:
    print(client.billing.balance())
except QufasAuthenticationError:
    print("Invalid or inactive API key.")
except QufasAPIError as error:
    print(error.status_code, error.error_code, str(error))
```

Exception classes:

- `QufasError`
- `QufasAPIError`
- `QufasAuthenticationError`
- `QufasRateLimitError`
- `QufasServerError`
- `QufasConnectionError`

## Development

```bash
cd qufas-python
python -m pip install -e .
python -m unittest discover -s tests
```

## License

MIT
