Guida alle API reference utilizzabili con Script Bridge

Versione verificata

1. Prima distinzione: reference pubblica ≠ operazione disponibile al Bridge

Una API reference GX-TXT può descrivere il contratto pubblico completo del provider, comprese operazioni destinate a CORE, Tcl, GUI o moduli nativi. Lo Script Bridge espone soltanto le operazioni per le quali esiste una binding script-callable registrata dal provider.

Per questo motivo la domanda corretta non è soltanto «esiste FOO_API_v1?», ma:

1. questa API è registrata per lo Script Bridge corrente?
2. la specifica operation che mi serve è registrata?
3. provider, versione e capability corrispondono a ciò che richiede il mio script?
4. quali sono gli argomenti e il result contract documentati dal provider?

2. Le funzioni generiche del Bridge

Il livello generico è stabile e uguale concettualmente per Python e Octave.

3. Metodo corretto per leggere una API reference

3.1 Identifica API ID e versione

Cerca nella reference l'ID versionato, per esempio CANONICAL_DATASET_API_v2. La versione del contratto è indipendente dalla release GX-TXT.

3.2 Cerca la sezione Script Bridge

Molte reference riportano esplicitamente una sezione Octave Script Bridge o equivalente. Quella sezione è particolarmente importante: descrive le operations esposte, la convenzione degli argomenti posizionali e il risultato visto dallo script.

3.3 Non trasformare automaticamente le firme Tcl in chiamate Bridge

Esempio: la Canonical Dataset API v2 documenta numerose funzioni Tcl per handle, hyperslab e binary transport. Nella dev-031 il Bridge espone invece soltanto:

list()
describe(dataset_id)
read_range(dataset_id, variable_ids, zero_based_start, count)

Quindi una funzione Tcl presente nella stessa reference non diventa automaticamente un nome valido per gxtxt_api_call().

3.4 Controlla gli argomenti strutturati

gxtxt_api_describe() include descriptor delle operations con nome, summary, argomenti strutturati, required status e result_contract. Le opzioni scientifiche, enumerazioni, unità e semantiche restano però responsabilità della reference specifica del provider.

3.5 Controlla provider e capability quando la dipendenza è importante

Se lo script dipende non soltanto dall'ID ma da un provider o da capability specifiche, esprimilo nel preflight anziché affidarti a un controllo manuale.

4. Required APIs: rendere esplicito il contratto dello script

La sintassi compatta è:

API_ID
API_ID@version
API_ID@version:provider_id
API_ID@version:provider_id+capability|capability

Esempi:

CANONICAL_DATASET_API_v2@2
PLOT_DATASET_API_v3@3:plot.dataset+plotspec|render

Il controllo avviene prima del corpo scientifico. Questo è preferibile a scoprire a metà calcolo che un'operazione necessaria non è disponibile.

5. Dalla reference alla chiamata: esempio completo

La reference di CANONICAL_DATASET_API_v2 dichiara per il Bridge l'operation read_range con argomenti:

dataset_id, variable_id_cell/list, zero_based_start, count

Python

from gxtxt import (
    gxtxt_api_list, gxtxt_api_describe, gxtxt_api_require,
    gxtxt_api_has_operation, gxtxt_api_call
)

# 1. Runtime discovery
apis = gxtxt_api_list()
desc = gxtxt_api_describe("CANONICAL_DATASET_API_v2")

# 2. Fail before scientific work if the contract is missing
gxtxt_api_require("CANONICAL_DATASET_API_v2@2:canonical_dataset")

# 3. Verify the operation named by the reference
if not gxtxt_api_has_operation("CANONICAL_DATASET_API_v2", "read_range"):
    raise RuntimeError("read_range is unavailable")

# 4. Translate the provider reference literally into positional args
block = gxtxt_api_call(
    "CANONICAL_DATASET_API_v2",
    "read_range",
    ["sample", ["v0001"], 0, 1024],
)

GNU Octave

apis = gxtxt_api_list();
desc = gxtxt_api_describe('CANONICAL_DATASET_API_v2');

gxtxt_api_require('CANONICAL_DATASET_API_v2@2:canonical_dataset');

if (!gxtxt_api_has_operation('CANONICAL_DATASET_API_v2','read_range'))
  error('read_range is unavailable');
endif

block = gxtxt_api_call(
  'CANONICAL_DATASET_API_v2',
  'read_range',
  {'sample', {'v0001'}, 0, 1024}
);

La traduzione è deliberatamente meccanica: API ID e operation sono stringhe esatte della binding; args resta una lista/tupla Python o una cell array Octave nello stesso ordine documentato.

6. Reference utilizzabili con lo Script Bridge nella dev-031

La tabella seguente non sostituisce le reference specifiche: serve a sapere quali reference vale la pena consultare da uno script e quali operations risultano esposte nella copertura verificata.

7. Percorsi consigliati per tipo di lavoro

8. Callback: quando una reference contiene una funzione da valutare

Alcune operations numeriche accettano funzioni definite dallo script. Non si serializza il codice della funzione: si registra un handle execution-scoped con SCRIPT_CALLBACK_API_v1.

# Python
rhs = gxtxt_callback_register(lambda t, y: -2*y)
result = gxtxt_api_call(
    "NUMERIC_API_v1", "foundation",
    ["ode", "solve", rhs, [0.,1.], [1.], {"reltol":1e-8}]
)
gxtxt_callback_release(rhs)

Lo stesso principio vale in Octave con function handle. La reference numerica specifica definisce shape e semantica del callback; la Callback API definisce lifecycle, errori e limiti del trasporto.

9. Tipi e transport: come interpretare i result contract

Il Bridge trasporta stringhe UTF-8, booleani, interi, float, vettori, matrici, celle/liste, struct/dict, liste di struct e combinazioni annidate. Gli array numerici grandi usano automaticamente un trasporto binario privato.

• oltre 10.000 elementi gli array numerici possono usare il blocco binario float64;
• in Python gli array numerici ritornano come NumPy ndarray se NumPy è installato, altrimenti come liste;
• in Octave il caller riceve normali valori Octave;
• lo script non gestisce file di trasporto né path interni.

Quando una reference parla di «struct», «dictionary», «cell» o «list», interpreta il tipo nel linguaggio client mantenendo la struttura logica, non l'implementazione Tcl del provider.

10. API pubbliche ma host-only

Le seguenti reference possono essere pubbliche e utili per sviluppare moduli o CORE, ma la copertura dev-031 le marca come host-only per gli script:

Notare i casi parziali: PARALLEL_EXECUTION_API_v1 è disponibile per resources, ma non per execute; INTERACTIVE_DOCUMENT_API_v1 è leggibile, ma write è host-only.

11. Interfacce intenzionalmente non script-safe

12. Errori del Bridge

Gli identificatori generici stabili documentati sono:

Un provider error non viene convertito in un risultato vuoto. In Python gli errori arrivano come GXTXTBridgeError; in Octave come errori con identificatore/messaggio.

13. Il Bridge non è una sandbox

Il Bridge limita quali servizi GX-TXT possono essere invocati, ma lo script Python/Octave resta codice del ricercatore eseguito con i permessi locali dell'utente. Non usare questa architettura come confine di sicurezza per codice non fidato.

14. Come aggiornare questa guida a una nuova release GX-TXT

Questa è la parte da ripetere ogni volta che la documentazione viene riallineata a una nuova release.

1. Leggere VERSION.txt della nuova baseline.
2. Leggere integralmente docs/api/SCRIPT_BRIDGE_COVERAGE_v1.json.
3. Confrontare API aggiunte/rimosse, versioni, provider, status e lista operations.
4. Ricontrollare OCTAVE_SCRIPT_BRIDGE_API_v1.md e PYTHON_SCRIPT_CLIENT_v1.md.
5. Per ogni API che cambia, aprire la reference del provider e verificare la sua sezione Script Bridge.
6. Controllare gxtxt_api_describe() su una run reale per almeno le API principali.
7. Aggiornare la matrice di questa pagina e la data di verifica.
8. Rigenerare soltanto lo ZIP differenziale del sito.

15. Riferimenti del framework usati per questa guida

• docs/api/OCTAVE_SCRIPT_BRIDGE_API_v1.md
• docs/api/PYTHON_SCRIPT_CLIENT_v1.md
• docs/api/SCRIPT_BRIDGE_COVERAGE_v1.json
• docs/api/SCRIPT_CALLBACK_API_v1.md
• le reference specifiche delle API elencate nella matrice precedente.