normaai 1.0.0

SDK Python per NormaAI — Normativa italiana via API

normaai

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

pip install normaai

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

Quickstart

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.

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.

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.

sources = client.sources("avvocato")

client.usage() -> dict

Retrieve your current API usage and quota.

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.

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.

License

MIT