Metadata-Version: 2.4
Name: byte42-fantastico-sdk
Version: 0.6.1
Summary: Client Python per FANTASTICO (Byte42) — porto di @byte-42/fantastico-sdk, nessuna dipendenza runtime.
Author: Byte42 S.r.l.
License-Expression: MIT
Project-URL: Homepage, https://fantastico.cc
Keywords: ai,llm,openai,fantastico,byte42,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# byte42-fantastico-sdk (Python)

Client Python per FANTASTICO — terzo porto dopo `sdk/` (Node/TypeScript) e `sdk-php/`, per
i verticali che non girano su nessuno dei due (es. Django). Nessuna dipendenza runtime,
come gli altri due: solo libreria standard.

## Cosa è stato portato 1:1

- `surface.py` — deduzione della superficie (`runtime`/`edge`) dal prefisso della chiave,
  identica a `sdk/src/surface.ts`.
- `schema_digest.py` — canonicalizzazione + SHA-256 del documento di un tool, verificata
  **byte per byte** contro lo stesso vettore condiviso da `backend/`, `sdk/` e `sdk-php/`
  (`tests/test_schema_digest.py`).
- `auth.py` (`AuthClient`) — conio della runtime key, concessioni sui tool, saldo edge,
  prenotazione budget runtime, listino provider per `max_tokens`. In memoria di processo,
  non per-richiesta: Django (WSGI/ASGI) è un processo persistente come Node, non
  request-scoped come PHP classico, quindi qui non serve lo storage cifrato che
  `sdk-php/` usa per sopravvivere a una singola richiesta.
- `llm.py`, `raw.py` — chiamata diretta al provider (chat orchestrata e `create_raw`
  pass-through, con `max_tool_calls`). **L'SDK non sa chi è il provider**: indirizzo, modello di
  default, campi da fondere nella chat ed endpoint delle decisioni arrivano col conio, insieme alla
  chiave (`ProviderAccess` in `auth.py`). Il modello si sceglie così: quello della chiamata, poi
  `default_model` del client, poi quello indicato dal conio; senza nessuno dei tre la chiamata è
  rifiutata con `MODEL_REQUIRED`.
- `max_tokens.py` — stesso calcolo di `affordableMaxTokens` (headroom 0.8, floor 64,
  comfortable 8192).
- `mcp.py` — esecuzione dei tool del marketplace. Timeout di 180 s, e **un timeout non si
  ripete**: il tool ha lavorato e si è fatto pagare. Si riprova solo quando è certo che non ha
  lavorato (connessione rifiutata, nome non risolto, 429, 503).
- `tool_origin.py` — `tool_origin_map` / `FANTASTICO_TOOL_ORIGIN_MAP`: chiamare un tool per
  una strada interna (es. `https://skills.fantastico.cc=http://127.0.0.1:4002`), con lo stesso
  token e la stessa verifica del documento.
- `activity.py` — `on_event` su `create()`/`resume()` (`thinking`, `tool_start`, `tool_end`,
  con le stesse chiavi di Node) e `write_activity_stream()`, che porta gli eventi in NDJSON
  fino al widget.
- `speech.py` — `ai.audio.speech.create()` e `ai.audio.speech.models()`: voce sintetica sullo
  stesso conto e la stessa runtime key della chat.
- `local_tools.py` (`LocalToolDefinition`, `ClientActionToolDefinition`, `LocalToolRegistry`)
  — tool che girano nel processo dell'integratore (mai nel marketplace), incluso il gate di
  conferma umana; e azioni-client, che il server non esegue mai e consegna così com'è al
  frontend. Esecuzione tramite `concurrent.futures` (sincrono come il resto del pacchetto):
  un batch non-sequenziale gira in parallelo su un pool per-registro (`max_workers`, default
  8 — **un tetto reale di concorrenza**, a differenza di `Promise.all` in Node: un batch più
  grande del pool può bloccarsi se le tool_call dipendono l'una dall'altra per una vera
  concorrenza. Va dimensionato sul batch più grande atteso in un turno).
- `orchestrator.py` — **con** pending/resume: quando una tool_call richiede conferma o è
  un'azione-client in attesa di esito, l'orchestrazione si ferma (`status: "pending"`,
  `PendingCompletion.state` — un dict JSON-safe, va rimandato identico a `resume()`) invece
  di eseguire in automatico.
- `client.py` (`Fantastico`) — `chat.completions.create`/`resume`/`create_raw`, `tools.*`
  (incluso `tools.enabled()`, che elenca i tool abilitati senza coniare), `models.list`,
  `accounts.*` (+ `accounts.keys.*` e `accounts.upgrade()`, solo superficie `runtime`),
  `runtime_keys.*`, `balance()` (solo superficie `edge`), `audio.speech.*`, `decisions.*`,
  `activity_session_id`, `flush_budget()`, `add_tool()`. `create()` accetta anche
  `marketplace_tools` (quali tool del marketplace offrire in quella chiamata) e `local_tools`
  (tool locali solo per quella chiamata).
- `provider_error.py`, `backoff.py` — classificazione strutturata dell'errore del provider
  (`ProviderError`, mai sul testo del messaggio) e ritentativo sugli errori transitori
  (429/503, con `Retry-After`). Solo `authentication`/`payment_required` fanno ri-coniare,
  una chiamata HTTP alla volta — non l'intera orchestrazione, che altrimenti rigiocherebbe
  turni e tool già eseguiti. Vedi CLAUDE.md §9.2 e il CHANGELOG per i dettagli.

**Una chiave viva PER CONTO, non per client** (0.3.0): il conio nomina il tenant passato in
`user=`/`accounts.*`, quindi la sua spesa va sul suo conto e non su quello del proprietario
del progetto — vedi il CHANGELOG per il difetto che questo corregge.

## Cosa NON è stato portato (scelta dichiarata, non una svista)

- **Lo shim deprecato `usage.record`**: era compatibilità per client Node scritti contro
  una versione precedente dell'SDK, prima che quella rotta venisse rimossa col ledger
  (CLAUDE.md §16.8). Non ha senso portare un compat-shim per un comportamento che questo
  client non ha mai avuto.
- **`FantasticoActions`/`browser-actions.ts`**: è un helper che gira nel **browser**
  (esegue le `clientActions` consegnate dal server), concettualmente frontend — non
  appartiene a un SDK backend, Node compreso lo espone solo perché lì backend e frontend
  condividono il linguaggio. Se un host Python ne ha bisogno lato client, va scritto in JS
  nel widget, non in questo pacchetto.

## Dove si comporta diversamente da Node (per costruzione)

- **Sincrono.** Ogni chiamata blocca il thread che la fa; un solo conio alla volta per conto,
  quindi due thread dello stesso worker che chiedono insieme la chiave di un conto ne
  ottengono una sola.
- **Timeout HTTP espliciti**: 30 s verso il Cloud e verso il documento di un tool, 90 s verso
  il provider, `mcp_timeout_s` (180 s) verso l'esecuzione di un tool. `urllib` senza timeout
  aspetterebbe per sempre.
- **Eventi dei tool locali in parallelo**: `tool_end` arriva nell'ordine di sottomissione, non
  in quello di completamento. La durata resta quella vera.
- **Lo stato di una pausa non è intercambiabile** con quello di Node (`budget_s` contro
  `budgetMs`): uno stato si riprende con l'SDK che l'ha prodotto.

## Saldo del conto

`ai.balance()` (chiave di conto) restituisce `remainingUsd` e `lowBalance`, che servono ad
**autorizzare** — quanto si può ancora impegnare in chiavi nuove — e, con un Cloud aggiornato,
`reservedUnspentUsd`, `totalRemainingUsd` e `lowTotalBalance`. Il numero da **mostrare** al
cliente è `totalRemainingUsd`: una chiave a blocchi impegna $5 alla prima chiamata anche se la
chiamata ne costa tre centesimi, e `remainingUsd` da solo direbbe che li ha spesi. Se i campi
mancano, non inventare un totale sommando il blocco di una chiave in memoria.

## Installazione

Pubblicato su PyPI come `byte42-fantastico-sdk`, licenza MIT:

```bash
pip install byte42-fantastico-sdk
```

In `requirements.txt`, a versione esatta:

```
byte42-fantastico-sdk==0.6.1
```

Le versioni fino alla 0.5.0 sono uscite solo sul registry privato di Byte42: chi è fermo lì
continua a installarle da quello (`PIP_EXTRA_INDEX_URL`), finché non passa a una versione
pubblica e può togliere l'indice extra.

Pubblicazione **a mano**, come per gli altri pacchetti (dal 2026-10-18 la pipeline non pubblica
più niente): `npm run publish -- sdk-python` dalla radice, con `PYPI_TOKEN` nell'ambiente (API
token di pypi.org dell'account aziendale). Lo script controlla che la versione non sia già su
PyPI, costruisce e carica in un container `python:3.12-slim` (`twine check --strict` prima del
caricamento) e verifica che PyPI la mostri. Con `PYPI_TEST=1` va su test.pypi.org.

Per lavorare sul pacchetto stesso dentro questo monorepo, installazione locale:

```bash
pip install -e /percorso/a/fantastico/sdk-python
```

### Test

```bash
npm run test:python          # dalla radice del monorepo: pytest su Python 3.9, in container
pip install -e ".[dev]" && pytest    # oppure qui, sull'interprete che hai
```

Il container gira sul **pavimento** che `requires-python` promette (3.9), che è l'unico modo per
accorgersi qui di aver usato una sintassi più recente invece che sulla macchina di chi installa —
stessa ragione per cui i test del client PHP girano su PHP 8.0. L'extra `dev` è `pytest` e
nient'altro: il pacchetto non ha dipendenze di runtime e non ne acquista installandolo.

## Uso rapido

```python
from fantastico_sdk import Fantastico

ai = Fantastico(
    api_key="ck-fant-prod-…",  # chiave di conto: superficie /api/edge
    base_url="https://fantastico.cc/api",
)
result = ai.chat.completions.create(messages=[{"role": "user", "content": "Ciao"}])
print(result.message, result.usage["cost_usd"])
```

Con una **project key** (`sk-fant-…`) il client parla `/api/runtime/*` e sblocca
`accounts.*`/`runtime_keys.list(user_key=...)`/il parametro `user` su `create()`; con una
**chiave di conto** (`ck-fant-…`) parla `/api/edge/*`, `balance()` e nessun `user` — è
dedotto dalla credenziale (CLAUDE.md §18.1). Chiamare un metodo dalla superficie sbagliata
solleva `FantasticoError(code="SURFACE_UNSUPPORTED")` invece di un 401 muto.

## Integrazione Django

Vedi `examples/django_genioai/`: Django gioca il ruolo di "container [2]" (CLAUDE.md §4,
§9) — tiene la chiave di conto lato server ed espone un endpoint same-origin che il
widget `@byte42/genioai-chat-widget` chiama, senza che la credenziale FANTASTICO
raggiunga mai il browser.

## Test

```bash
python3 -m unittest discover -s tests
```
