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

  1. 01Installa

  2. 02Connetti una sorgente

    import { createSQAI } from "@thyn-ai/sqai";
    
    const sqai = createSQAI();
    await sqai.connect("./sales.csv",
      { name: "sales" });
  3. 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…
  4. 04Calcola un valore

    const r = await sqai.compute({
      module: "finance", function: "npv",
      args: [0.1, [-1000, 300, 420, 560, 680]],
    });
    r.value505.020148896933
    r.computation_hashb74f67d0…d91bc8

PythonPython ≥ 3.10

  1. 01Installa

  2. 02Connetti una sorgente

    from sqai import SQAI
    
    sqai = SQAI()
    sqai.connect("./sales.csv",
      name="sales")
  3. 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…
  4. 04Calcola un valore

    r = sqai.compute(
      module="finance", function="npv",
      args=[0.1, [-1000, 300, 420, 560, 680]],
    )
    r["value"]505.020148896933
    r["computation_hash"]b74f67d0…d91bc8
computation_hash · TypeScript ≡ Python

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

  1. 01scarica il bundle della piattaforma
  2. 02verifica la firma RS256 + sha256 per artefatto
  3. 03estrae e installa atomicamente
  4. 04avvia il motore residente

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: ok

doctor 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.

  1. $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.

  2. $sqai doctor [--parity] [--json]

    Node, importazione SDK, contratto incorporato, probe del runtime attivo. --parity verifica l'invariante di sola lettura e determinismo.

  3. $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.