IInstallazione
La prima prova.
Da una macchina pulita a una risposta con hash e riproducibile in meno di un minuto. Nessun account, nessuna chiave, nessun server. Esegui gli stessi quattro passaggi in entrambi i linguaggi — la prova è lo stesso hash.
TypeScriptNode ≥ 20
01Installa
02Connetti una sorgente
import { createSQAI } from "@thyn-ai/sqai"; const sqai = createSQAI(); await sqai.connect("./sales.csv", { name: "sales" });03Invia una query
const a = await sqai.ask({ metric: "revenue", aggregation: "sum", group_by: "region", source_name: "sales", }); // east 2130.5 · west 1519 · north 1000 // plan_hash f87610d8afeb…04Calcola un valore
const r = await sqai.compute({ module: "finance", function: "npv", args: [0.1, [-1000, 300, 420, 560, 680]], });r.value505.020148896933r.computation_hashb74f67d0…d91bc8
PythonPython ≥ 3.10
01Installa
02Connetti una sorgente
from sqai import SQAI sqai = SQAI() sqai.connect("./sales.csv", name="sales")03Invia una query
a = sqai.ask({ "metric": "revenue", "aggregation": "sum", "group_by": "region", "source_name": "sales", }) # east 2130.5 · west 1519 · north 1000 # plan_hash f87610d8afeb…04Calcola un valore
r = sqai.compute( module="finance", function="npv", args=[0.1, [-1000, 300, 420, 560, 680]], )r["value"]505.020148896933r["computation_hash"]b74f67d0…d91bc8
b74f67d0d7a594aa7ac91f6291612452aa8ccdf603351ebc8d801a6fddd91bc8
Identici. Byte per byte.
Entrambi gli SDK canonicalizzano lo stesso risultato negli stessi byte, quindi l'hash coincide tra i linguaggi — non per caso, per costruzione. Riproduci la chiamata ovunque e deve stampare questa riga.
IIConfigurazione iniziale
Provisioning una volta. Poi è immediato.
Il piano di query viene eseguito in-process non appena l'installazione termina — nessun daemon, nessuna chiave. Il piano di calcolo effettua il provisioning del suo runtime firmato una volta sola, al primo compute(), poi lo mantiene residente.
await sqai.compute(…) // first call, ever~110 s · una volta per macchina
await sqai.compute(…) // every call after0,83–0,93 ms · misurato
Il runtime è già residente — nessun download, nessun avvio a freddo, nessuna configurazione per query.
Il bundle viene memorizzato nella cache per utente, quindi il provisioning avviene una volta per macchina — non una volta per processo.
IIIVerifica
Un comando legge l'intera macchina.
✓ node: v20.11.0
✓ sdk: @thyn-ai/sqai 0.1.4 imports cleanly
✓ contract: 4778 capabilities
sha256:79f1c5a6c7164e7e9e1750e70a5c03292fa87eb52d8148a740c06695924be9a1
• tested-pair: skipped (not in the repo)
• runtime: unavailable (checks skipped)
✓ doctor: okdoctor verifica la versione di Node, l'import dell'SDK, il contratto incorporato e una sonda live del runtime. Su una macchina pulita la riga del runtime riporta unavailable — un'omissione, non un errore. Il piano di query non richiede alcun runtime.
- 4.778 capability sono incluse nel contratto con hash fisso; 4.574 sono esposte agli SDK — in sola lettura, deterministiche.
- Aggiungi --parity per verificare quell'invariante e confrontare i moduli del contratto con il motore in esecuzione.
- Aggiungi --json per stampare esattamente un oggetto JSON — predisposto per la CI.
IVRequisiti
Cosa serve al minuto.
- Node
- 20 o superiore per i pacchetti npm — doctor lo verifica.
- Python
- 3.10 o superiore per il pacchetto PyPI.
- Piano di calcolo
- darwin-arm64 o linux-x64 — il runtime firmato viene predisposto al primo compute().
- Piano di query
- Ovunque giri Node o Python.
- Windows e altri
- Il piano di query funziona integralmente; compute() restituisce un errore strutturato unsupported_platform — mai un crash.
Su un host non supportato, punta il calcolo a un motore remoto con SQAI_ENGINE_URL o SQAI_API_KEY — query e dispatch continuano a funzionare; viene saltato solo il provisioning locale.
VStrumenti dell'operatore
Tre comandi attorno all'SDK.
Connessione, interrogazione e calcolo avvengono tutti in-process attraverso gli SDK. La CLI è ciò che esegui intorno a loro — registra un dispositivo, verifica l'ambiente, gestisce il runtime.
$sqai login [--no-browser]
Accesso dispositivo opzionale (RFC 8628) tramite accounts.thyn.ai. Trasferisce un token firmato — mai i tuoi dati. Gratuito su una macchina.
$sqai doctor [--parity] [--json]
Node, importazione SDK, contratto incorporato, probe del runtime attivo. --parity verifica l'invariante di sola lettura e determinismo.
$sqai runtime <status|install|verify|stop>
Il runtime di calcolo residente: visualizzarlo, installarlo in anticipo, verificare il sha256 fissato, arrestarlo.
Ogni comando accetta --json e stampa esattamente un oggetto JSON. I codici di uscita sono scriptabili: 0 successo · 1 verifica fallita · 2 errore d'uso.
VIAvanti