Octave Script Bridge API v1

Octave Script Bridge API v1

SPDX-License-Identifier: GPL-3.0-or-later

OCTAVE_SCRIPT_BRIDGE_API_v1 lets a user-authored GNU Octave .m script discover and call GX-TXT public APIs registered for script use. The analysis.octave_script runner starts and stops the bridge around each user script. Scripts should not call those lifecycle functions themselves.

Stable Octave functions

info = gxtxt_bridge_info();
apis = gxtxt_api_list();
yes = gxtxt_api_has(api_id);
descriptor = gxtxt_api_describe(api_id);
yes = gxtxt_api_has_operation(api_id, operation);
yes = gxtxt_api_require(requirements);
result = gxtxt_api_call(api_id, operation, args);
context = gxtxt_context();

args is a cell array of positional values. Operation names, argument conventions and result conventions belong to the corresponding public API manual. gxtxt_api_describe returns the API ID, version, provider kind and ID, documentation reference, and operation descriptors with name, summary, argument convention and result convention. gxtxt_api_list returns a cell of scalar API descriptor structs and lists only registered script-callable APIs. An unregistered API makes gxtxt_api_has return false and a call fail. Each operation descriptor now includes structured arguments with name, kind and required status, plus result_contract, summary, API version, provider identity, capabilities and script_available. Provider manuals own operation-specific options, enumerations and unit behavior. The current machine-readable coverage/status inventory is SCRIPT_BRIDGE_COVERAGE_v1.json.

if (!gxtxt_api_has('NUMERIC_API_v1'))
  error('This script requires NUMERIC_API_v1');
endif
if (!gxtxt_api_has_operation('NUMERIC_API_v1', 'array_binary'))
  error('The required numerical operation is unavailable');
endif
a = struct('kind', 'vector', 'value', [1; 2; 3]);
b = struct('kind', 'scalar', 'value', 4);
r = gxtxt_api_call('NUMERIC_API_v1', 'array_binary', {'multiply', a, b});

The bridge has no API-specific dispatch table. Each public API provider owns its script binding and its operation metadata. Installing another registered provider makes that API available on the next bridge start without changing bridge code. A provider can be CORE or an installed module. Module bindings are accepted only when their owning module.ini declares the exact public API ID and version. A duplicate, stale, or incomplete binding fails Bridge startup with a diagnostic.

Required API declarations

The Script Workspace required_apis field is checked before the research script runs. It accepts semicolon or comma separated declarations in these forms:

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

The suffixes require exact API version, provider ID, and one or more capabilities. A script may also call gxtxt_api_require with a cell of declarations or scalar structs containing api_id, optional api_version, provider_kind, provider_id, and capabilities. A missing identity or capability raises an explicit error. Validation precedes scientific execution in the standard script runner.

Research workflow services

The Bridge currently binds Canonical Dataset, Variable Schema, Metadata, Selection, Temporal Set, Table Stream, Dataset and completed-file Publication, Unit Registry, NUMERIC_API, Plot Dataset v2/v3, Graph Series inspection, Viewer Provider scene/layer services, Native 3D source identity, Interactive Document reads, Session inspection/commit, Project inspection, progress, parallel resource policy, Scientific Reference Library reads/ranking, public documentation, semantics and module API discovery. PLOT_DATASET_API_v3 is the current plot facade; upsert_plot scopes the provider key to the running script module and returns a persistent Plot reference. The public Viewer Provider creates scientific scenes and layers without native protocol calls.

The test workflows under validation/gxtxt_script_bridge/ show complete Dataset/numeric/publication/plot, Temporal Set/parallel and Viewer scripts. Parallel callback/process command builders and live Native 3D renderer controls remain host-side because they require host-owned command prefixes or a live GUI. The Script Bridge exposes parallel resource limits and the framework still manages the script process cancellation lifecycle.

Values and transport

The bridge transports UTF-8 strings, logical and numeric scalars, numeric vectors and matrices with shape, empty numeric arrays, cells, scalar structs, lists of structs, nested combinations of these values, and opaque UTF-8 tokens. Numeric arrays above 10,000 elements use a private typed binary block. Strings, empty arrays, empty cells and empty structs remain distinct. A script receives ordinary Octave values and does not manage transport files.

Execution context

gxtxt_context() returns bridge_api_id, bridge_api_version, module_id, run_id, operation, script_name, script_sha256, arguments_raw, output_dir, and inputs. Each input alias has its alias/source ID, selected dataset_id, and contract/kind when available. Dataset IDs are stable logical bindings; the context omits Session and Dataset storage paths. output_dir is the current framework-owned script execution directory for completed files intended for public file publication. An optional source can have an empty Dataset ID. Python consumes the same provider bindings through the Python Script Client.

The module runner calls gxtxt_script_bridge_start(runtime_config_path, execution_metadata) once before executing the exact script snapshot and gxtxt_script_bridge_stop() during success or error cleanup. A second start while active fails. After stop, all normal bridge calls fail with GXTXT:ScriptBridge:NotActive until the next start. Open managed Dataset publication writers are aborted on bridge stop.

Errors and public boundary

Unknown APIs and operations, invalid arguments, transport faults, and provider failures raise Octave errors. The stable bridge identifiers are GXTXT:ScriptBridge:NotActive, UnknownAPI, UnknownOperation, InvalidArguments, Transport, and RemoteError. A provider error cannot be mistaken for an empty successful result. Diagnostic messages include the API ID and operation when applicable.

gxtxt_api_call accepts only exact API and operation names from the provider-owned registry. It cannot evaluate Tcl, source files, call an arbitrary ::GX::* command, or invoke a private CORE operation. This restriction applies to the bridge; it is not an Octave process sandbox.

Provider maintenance

A script binding registers api_id, api_version, provider_kind, provider_id, documentation_ref, and operation descriptors. Each descriptor declares at least name, summary, argument_convention, and result_convention. A CORE API owns its binding under core/script_bindings/; a module API owns its binding under its module’s api/ directory. The API’s own manual must document every script-callable operation. The bridge manual describes the stable generic transport and does not enumerate installed provider APIs.

Python Script Client v1

Python Script Client v1

SPDX-License-Identifier: GPL-3.0-or-later

analysis.python_script runs registered Session .py scripts with the configured runtime.python. Import the public gxtxt package from the script. The framework activates and closes its Bridge; user code does not start a server or reference Tcl, private paths or provider binding files.

For compatibility, Bridge metadata retains the historical OCTAVE_SCRIPT_BRIDGE_API_v1 ID. Its provider bindings and transport are shared by Octave and Python; supported_languages and the context’s script_language identify the available clients and current execution.

from gxtxt import (
    gxtxt_context, gxtxt_bridge_info, gxtxt_api_list, gxtxt_api_has,
    gxtxt_api_describe, gxtxt_api_has_operation, gxtxt_api_require,
    gxtxt_api_call, GXTXTBridgeError,
)

context = gxtxt_context()
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
datasets = gxtxt_api_call("CANONICAL_DATASET_API_v2", "list", [])

gxtxt_api_list() and gxtxt_api_describe(api_id) provide machine-readable provider identity, version, capabilities and structured operation arguments. gxtxt_api_has and gxtxt_api_has_operation check availability. These are the same provider-owned descriptors and operations used by Octave. The machine-readable coverage inventory marks availability for both languages. A future provider supplies one binding.

gxtxt_api_call(api_id, operation, args) takes a positional Python list or tuple. API and operation names must be registered. Unknown/private APIs, unsupported operations, argument errors and provider failures raise GXTXTBridgeError with a stable identifier and a useful message. Calls outside an active GX-TXT run raise GXTXT:ScriptBridge:NotActive.

Values

The client carries UTF-8 strings, booleans, integers, floating-point scalars, dictionaries, lists, nested values and numeric vectors/matrices. Numeric arrays returned by public APIs are NumPy ndarray values when NumPy is installed in the configured runtime. Without NumPy they are Python lists; the script may convert them itself. NumPy arrays passed to an operation keep their shape, including column-major matrix transport compatible with Octave. Arrays over 10,000 elements reuse the Bridge’s private little-endian float64 binary payload. A script never manages transport files. Integer scalars retain integer identity; numeric array transport uses float64, as in the existing Bridge contract.

import numpy as np

ctx = gxtxt_context()
dataset_id = ctx["inputs"]["primary"]["dataset_id"]
description = gxtxt_api_call("CANONICAL_DATASET_API_v2", "describe", [dataset_id])
block = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range",
                       [dataset_id, ["v0001"], 0, int(description["row_count"])])
values = np.asarray(block["v0001"]["values"]).reshape(-1)

Each API’s own manual defines its operation arguments. The client transports values and does not import internal GX-TXT implementation modules.

Required APIs and provenance

Script Registry required_apis is checked before Python source executes. Use semicolon-separated declarations:

CANONICAL_DATASET_API_v2@2;PLOT_DATASET_API_v3@3:plot.dataset+plotspec

The optional @version, :provider_id and +capability|capability clauses require exact matches. gxtxt_api_require also accepts Python dictionaries with api_id, api_version, provider_kind, provider_id and capabilities, or a list of declarations. The Session owns an exact source snapshot with stable ID, language, semantic version, revision and SHA-256; each execution verifies and records those values, required APIs, actual Python executable/version, available NumPy/SciPy versions and results. Editing a user script cannot change its assigned Session copy.

Outputs and resource policy

gxtxt_context() includes Analysis input aliases, typed script parameters, run identity and output_dir. Write a completed scientific file inside that framework-owned directory and call DATASET_FILE_PUBLICATION_API_v1/publish to retain it as a Canonical Dataset with source lineage. Structured Datasets use DATASET_PUBLICATION_API_v2; graphs use PLOT_DATASET_API_v3; progress uses PROGRESS_API_v1.

Read PARALLEL_EXECUTION_API_v1/resources before creating a Python pool:

policy = gxtxt_api_call("PARALLEL_EXECUTION_API_v1", "resources", [])
workers = min(requested, int(policy["default_workers"]),
              int(policy["max_workers"])) if policy["enabled"] else 1

concurrent.futures, multiprocessing and optional researcher libraries remain normal Python choices. Bound their worker counts, close pools, and use the serial branch when workers is one. The Bridge exposes policy, never arbitrary host command execution. The configured runtime supplies optional scientific packages; a missing import produces the normal Python traceback.

The acceptance example is dataset_numpy_plot_file.py.

Analysis Tcl Bridge v1

Analysis Tcl Bridge v1

The CORE core/tcl/analysis_tcl_bridge_v1.tcl is the supported companion process for a managed standard-Octave analysis that must call public Tcl CORE APIs. Invoke it as:

tclsh analysis_tcl_bridge_v1.tcl FRAMEWORK_ROOT MODULE_RUNTIME_TCL RUNTIME_INI

MODULE_RUNTIME_TCL must be a file below the framework’s plugins/modules directory. The bridge initializes framework defaults and the module catalog, then sources that script with argv containing the framework root and runtime INI path. The script can call documented public CORE APIs; it should not source the desktop entrypoint itself. The bridge does not grant access to private module files and does not change Dataset ownership semantics.

The installed analysis.spectroscopy.ir module is the first consumer. It uses the bridge to publish normal Session Datasets and a report before its Octave renderer creates the corresponding graph from those published results. This bridge is headless; Tk initialization is not required.

Script Execution API v1

Script Execution API v1

SPDX-License-Identifier: GPL-3.0-or-later

CORE owns one Script Registry for GNU Octave and Python. Each registered record has a stable ID, display name, language, semantic version, revision, SHA-256, description, required public APIs, typed parameter schema, scope, source provenance and creation/update timestamps. Its qualified reference is user:<id> or session:<id>; a filesystem path is never the registered identity. Existing Octave records keep their source.m bytes and format; Python records store source.py in the same registry structure.

scriptRegistrySave, scriptRegistryUpdate, scriptRegistryDescribe, scriptRegistryList, scriptRegistryAssignToSession and scriptExecutionRun are the framework-owned Tcl operations. The Script Library and Session Script Explorer use these operations for both languages. Assignment copies exact user source bytes into a separate Session record. Later user edits cannot change that record. A Session edit keeps the ID, increments revision and replaces the current SHA; older execution snapshots remain under analysis/scripts/<run_id>/. Reads and execution reject a source whose SHA differs from the registry record.

scriptExecutionRun selects the language adapter from the verified registry record. Octave uses the existing Octave runner; Python uses the configured runtime.python and the public Python Script Client. Both languages use the same provider-owned Script Bridge API descriptors and operations. Required API declarations are checked before researcher code. Execution writes the exact source snapshot, report, log and execution.ini in a framework-owned Session run directory. Provenance includes the qualified reference, language, stable ID, version, revision, SHA-256, required APIs, source provenance and actual runtime information where applicable.

Normal Analysis modules analysis.octave_script and analysis.python_script select only matching-language Session records and invoke this shared execution path. Script Library Run and Session Explorer Run invoke the same path. The Octave module retains its explicit standalone external_file .m compatibility mode; registered Session scripts are the normal reproducible workflow for both languages.