Metadata-Version: 2.4
Name: qader-ai
Version: 0.1.0
Summary: Python SDK for Qader AI services
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: openai>=1.0
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: tqdm>=4.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: requests>=2.32.0
Requires-Dist: sentence-transformers>=2.2
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: responses>=0.25; extra == "test"

# Qader AI Library

A Python library for interacting with Qader AI services and AI processing utilities.

---

# Features

- Python SDK for Qader AI
- Predict API
- Chat API
- Usage API
- Subscription API
- API Key Authentication
- Custom Exceptions
- AI Processing Utilities
- Duplicate Cleaning
- Configurable Settings

---

# Requirements

- Python 3.9+
- requests
- pydantic
- pydantic-settings
- openai
- pandas
- numpy
- tqdm
- scikit-learn
- sentence-transformers
- pytest (for testing)
- responses (for testing)

Install the library:

```bash
pip install -e .
```

Install with testing dependencies included:

```bash
pip install -e ".[test]"
```

---

# Prerequisites

This library is a client for the **Qader backend API** — it does not work standalone. Before using it, make sure:

1. The Qader backend is running and reachable (defaults to `http://127.0.0.1:8000`).
2. You have a valid API key. Create one via the backend's `POST /api-keys/create` endpoint (see the backend's `/docs` page for details).
3. That API key has an active subscription and remaining usage, otherwise calls will raise `SubscriptionExpiredError` or `UsageLimitExceededError`.

---

# Project Structure

```
Qader-AI-Library/
│
├── src/
│   └── qader_ai/
│       ├── __init__.py
│       ├── sdk.py
│       ├── config.py
│       ├── exceptions.py
│       ├── clients.py
│       ├── duplicate_cleaner.py
│       ├── ai_processing/
│       │   ├── __init__.py
│       │   ├── ...
│       │
│       └── enums/
│           ├── __init__.py
│           ├── ...
│
├── tests/
│   ├── test_sdk_unit.py          # mocked, no backend needed
│   └── test_sdk_integration.py   # requires the backend running
│
├── README.md
├── pyproject.toml
└── requirements.txt
```

---

# Installation

Clone the repository

```bash
git clone <repository-url>
```

Move to the project

```bash
cd Qader-AI-Library
```

Install the package

```bash
pip install -e .
```

---

# Configuration

Configuration is managed through `config.py`, using environment variables (or a `.env` file in the project root).

Available SDK settings:

| Setting | Default | Description |
|---|---|---|
| `base_url` | `http://127.0.0.1:8000` | The Qader backend's base URL |
| `timeout` | `30` | Request timeout in seconds |

Example `.env` file:

```
base_url=http://127.0.0.1:8000
timeout=30
```

Additional AI processing settings are also available inside the same configuration file.

---

# Quick Start

```python
from qader_ai import QaderAI

client = QaderAI(
    api_key="YOUR_API_KEY"
)
```

---

# Predict

```python
result = client.predict(
    question="What is Artificial Intelligence?"
)

print(result)
```

---

# Chat

```python
result = client.chat(
    message="Hello!"
)

print(result)
```

---

# Usage

```python
result = client.usage(
    api_key_id=1
)

print(result)
```

---

# Subscription

```python
result = client.subscription(
    user_id=1
)

print(result)
```

---

# Exception Handling

The library provides the following exceptions:

- `QaderAIError` — base exception for all library errors
- `InvalidAPIKeyError` — raised when the API key is missing, invalid, or inactive (HTTP 401)
- `SubscriptionExpiredError` — raised when the subscription is expired or inactive (HTTP 403)
- `NotFoundError` — raised when a requested usage or subscription record doesn't exist (HTTP 404)
- `ValidationError` — raised when the request data is invalid (HTTP 422)
- `UsageLimitExceededError` — raised when the API key has hit its usage limit (HTTP 429)
- `RateLimitExceededError` — raised when too many requests are sent in a short time window (HTTP 429)
- `ServerError` — raised for backend server errors (HTTP 500+)

Example:

```python
from qader_ai.exceptions import InvalidAPIKeyError

try:
    client.predict("Hello")
except InvalidAPIKeyError:
    print("Invalid API Key")
```

---

# Running Tests

Unit tests (mocked, no backend required):

```bash
pytest tests/test_sdk_unit.py -v
```

Integration tests (requires the Qader backend running locally):

```bash
pytest tests/test_sdk_integration.py -v
```

Run everything:

```bash
pytest -v
```

---

# License

This project is intended for educational and internal use.
