Metadata-Version: 2.4
Name: imperio-api
Version: 1.1.0
Summary: Python SDK for Imperio Utilities API — developer tools, Italian validators, FatturaPA, Secret Scanner, PDF processing, AI tools
Home-page: https://github.com/mikrotek/imperio-python-sdk
Author: Imperio Utilities Team
Author-email: support@imperioutils.com
Project-URL: Bug Reports, https://github.com/mikrotek/imperio-python-sdk/issues
Project-URL: Source, https://github.com/mikrotek/imperio-python-sdk
Project-URL: Documentation, https://imperioutils.com/docs
Project-URL: API Documentation, https://imperioutils.com/docs
Project-URL: Homepage, https://imperioutils.com
Keywords: api sdk pdf audio transcription image qr-code processing fattura-pa italian-validators secret-scanner gdpr anonymization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Text Processing
Classifier: Topic :: Communications
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: sphinx>=4.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Imperio API — Python SDK

[![PyPI version](https://badge.fury.io/py/imperio-api.svg)](https://pypi.org/project/imperio-api/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for [Imperio Utilities](https://imperioutils.com) — the developer tools platform for B2B automation.

## Installation

```bash
pip install imperio-api
```

## Quick Start

Get your API key at [imperioutils.com/enterprise](https://imperioutils.com/enterprise).

```python
from imperio import ImperioClient

client = ImperioClient("empire_live_your_key_here")
```

## Features

### Secret Scanner — CI/CD ready

Detect exposed credentials before they hit production.

```python
# Scan source code
result = client.scan_secrets(open("app.py").read(), filename="app.py")
print(result["risk_score"])      # CLEAN | LOW | MEDIUM | HIGH | CRITICAL
print(result["total"])           # number of findings
for f in result["findings"]:
    print(f["severity"], f["type"], f["line"], f["masked_value"])
```

Values are **always masked** in the response — safe to log.

### Italian Validators (batch)

Validate CF, P.IVA, IBAN, CAP in a single call (up to 500 items).

```python
result = client.validate_italian_batch([
    {"type": "cf",   "value": "RSSMRA85T10A562S"},
    {"type": "piva", "value": "12345678901"},
    {"type": "iban", "value": "IT60X0542811101000000123456"},
    {"type": "cap",  "value": "00100"},
])
print(result["valid_count"], "/", result["total"])
```

### FatturaPA Parser

Parse Italian electronic invoices (SDI XML format, versions 1.2 and 1.3).

```python
xml = open("fattura.xml").read()
result = client.parse_fattura_pa(xml)
print(result["cedente_prestatore"])      # seller info
print(result["cessionario_committente"]) # buyer info
for f in result["fatture"]:
    print(f["numero"], f["totale"])
```

### GDPR Anonymization (batch)

Remove PII from text — regex-based, no AI, fully deterministic.

```python
result = client.anonymize_batch(
    texts=["Mario Rossi, via Roma 1, mario@example.com"],
    level="standard"   # or "aggressive"
)
print(result["results"][0]["anonymized"])
# "[NOME] [NOME], [INDIRIZZO], [EMAIL]"
```

### AI Tools

```python
# Extract structured data from invoice text
invoice = client.extract_invoice_ai("Fattura n. 123 del 01/06/2026 ...")

# Analyze a contract for risks and clauses
analysis = client.analyze_contract(contract_text, language="it")

# Summarize long text
summary = client.summarize(text, style="bullets")  # brief | detailed | bullets
```

## GitHub Actions CI/CD

Use the [Secret Scanner template](.github/examples/secret-scanner-ci.yml) to scan every PR automatically:

```yaml
- name: Install Imperio SDK
  run: pip install imperio-api

- name: Scan for secrets
  env:
    IMPERIO_API_KEY: ${{ secrets.IMPERIO_API_KEY }}
  run: python -c "
    from imperio import ImperioClient
    import os, sys
    client = ImperioClient(os.environ['IMPERIO_API_KEY'])
    result = client.scan_secrets(open('app.py').read())
    if result['critical'] > 0: sys.exit(1)
  "
```

## Error Handling

```python
from imperio.exceptions import ImperioError, AuthenticationError, InsufficientCreditsError

try:
    result = client.scan_secrets(code)
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Top up credits at imperioutils.com/billing")
except ImperioError as e:
    print(f"API error {e.status_code}: {e}")
```

## Authentication

All requests use `X-API-Key` header. Keys follow the `empire_live_*` format and are managed at [imperioutils.com/enterprise](https://imperioutils.com/enterprise).

## Links

- [Documentation](https://imperioutils.com/docs)
- [API Reference](https://imperioutils.com/docs)
- [Get API Key](https://imperioutils.com/enterprise)
- [GitHub](https://github.com/mikrotek/imperio-python-sdk)
- [Issues](https://github.com/mikrotek/imperio-python-sdk/issues)
