# normaai

[![PyPI version](https://img.shields.io/pypi/v/normaai.svg)](https://pypi.org/project/normaai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

> Query Italian laws, regulations, and legal precedents from Python. Zero dependencies.

NormaAI provides a comprehensive, AI-powered knowledge base covering Italian legislation across five professional verticals. This SDK gives you clean, Pythonic access to the full NormaAI API with no third-party dependencies.

## Installation

```bash
pip install normaai
```

**Requirements:** Python 3.8+ | Zero external dependencies (uses `urllib` from the standard library).

## Quickstart

```python
from normaai import NormaAI

client = NormaAI(api_key="nai_your_api_key")

result = client.query(
    "Quali sono i termini per il licenziamento per giusta causa?",
    vertical_id="lavoro",
)

print(result["answer"])
for source in result["sources"]:
    print(f"  - {source['title']} (similarity: {source['similarity']:.2f})")
```

## API Reference

### `NormaAI(api_key, base_url=None)`

Create a new client instance.

| Parameter  | Type            | Required | Description                          |
|------------|-----------------|----------|--------------------------------------|
| `api_key`  | `str`           | Yes      | Your NormaAI API key (`nai_...`)     |
| `base_url` | `str` or `None` | No       | Custom API base URL (for self-hosted)|

### `client.query(question, vertical_id) -> dict`

Send a natural-language question and receive an AI-generated answer grounded in Italian legal sources.

```python
result = client.query("Come si calcola il TFR?", vertical_id="commercialista")
```

**Parameters:**

| Name          | Type  | Required | Description                              |
|---------------|-------|----------|------------------------------------------|
| `question`    | `str` | Yes      | Natural-language question in Italian      |
| `vertical_id` | `str` | Yes     | One of the available vertical identifiers |

**Returns:** `dict` with keys `answer`, `sources`, `tokens_used`, `vertical_id`, `query_id`.

### `client.verticals() -> list[dict]`

List all available verticals.

```python
verticals = client.verticals()
for v in verticals:
    print(f"{v['id']}: {v['name']} ({v['doc_count']} documents)")
```

### `client.sources(vertical_id) -> list[dict]`

List indexed sources for a specific vertical.

```python
sources = client.sources("avvocato")
```

### `client.usage() -> dict`

Retrieve your current API usage and quota.

```python
usage = client.usage()
print(f"{usage['queries_used']} / {usage['queries_limit']} queries used")
```

Returns a dict with keys `queries_used`, `queries_limit`, `period_start`, `period_end`, `plan`.

## Available Verticals

| Vertical ID      | Target Professionals          | Coverage                           |
|-------------------|-------------------------------|------------------------------------|
| `lavoro`          | Labour Consultants            | Employment law, payroll, contracts |
| `commercialista`  | Chartered Accountants         | Tax, corporate, accounting         |
| `avvocato`        | Lawyers                       | Civil, criminal, procedural law    |
| `ingegnere`       | Engineers / Surveyors         | Building codes, safety, permits    |
| `finanziario`     | Financial Advisors            | MiFID II, CONSOB, banking          |

## Error Handling

All methods raise `NormaAIError` on failure.

```python
from normaai import NormaAI, NormaAIError

client = NormaAI(api_key="nai_your_api_key")

try:
    result = client.query("Domanda esempio", vertical_id="lavoro")
except NormaAIError as e:
    print(f"API error {e.status}: {e.message}")
    # e.status  — HTTP status code
    # e.code    — Machine-readable error code (e.g. "rate_limit_exceeded")
    # e.message — Human-readable description
```

## Documentation

Full API documentation, guides, and tutorials are available at [docs.normaai.it](https://docs.normaai.it).

## License

MIT
