Integrations SDK

The Integrations SDK is the toolkit and contract for building custom modules that extend the Istari Digital Platform. A module packages one or more functions that an Istari Digital agent can execute as part of a user job — typically wrapping a CAD tool, simulation solver, in-house script, or external service so it becomes a first-class platform capability.

This section is for integration developers — designing, implementing, validating, and packaging modules. The Istari Digital CLI is the tool used at every step of the workflow; this section explains the contract, the authoring framework, and the end-to-end workflow that the CLI supports.

Key features

• Language-agnostic, file-based contract. A module is a directory containing a module_manifest.json and the executable that runs your function. The agent passes inputs and outputs as JSON files on disk — your function can be written in any language. See Module concepts.
• Two authoring paths. Hand-roll a manifest plus any executable (shell, Go, .NET, …) for maximum flexibility, or scaffold a structured Python module with stari module scaffold --type python-module to get a Pydantic-typed function framework, a function registry, build scripts, hooks, and pre-built templates out of the box.
• Function variants for OS and tool versions. A single module can declare multiple variants of the same function targeting different operating systems (Windows 10/11, Ubuntu 20.04/22.04/24.04, RHEL 8/9) or different tool versions; the platform resolves which to invoke at runtime.
• Manifest-driven publishing. A versioned manifest declares everything the platform needs — entrypoint, run command, function schemas, dependencies, supported OS, build / test / install / clean scripts.
• Scoped naming. Modules and functions use a @scope:name convention. @istari is reserved for first-party integrations; pick your own scope (e.g. @acme_corp:cad_tools) for internal or distributed modules.

Authoring workflow

The end-to-end module-authoring workflow:

1. Scaffold or hand-roll the module structure. For Python: stari module scaffold <name> --type python-module generates a project with Pydantic Input / Output types, a function registry, function templates for common patterns (1-input → 1-output, parameter sweep, OIDC auth, etc.), pyproject.toml build configuration, hooks, and tests. For other languages: create a directory with module_manifest.json and your executable.
2. Define the function schema in the manifest. Inputs declare types (@string, @number, @object, validation types like @extension:txt); outputs declare files or directories. Export the JSON schema with stari schemas get function_input for editor tooling or LLM-assisted editing.
3. Implement the function. Read the input JSON, run your logic, write the output JSON. The Python scaffold provides a registry-based dispatch and Pydantic validation; non-Python modules parse --input-file and write --output-file directly.
4. Validate the manifest — stari module lint module_manifest.json. If it lints, it's publishable.
5. Generate sample inputs and outputs — stari function generate test_files --function @scope:<fn> produces realistic JSON files for local testing. See Function test file generation.
6. Run the manifest's scripts — stari module run build, stari module run test_unit, stari module run install, stari module run clean. The Python scaffold wires these to Poetry; non-Python modules wire them however they like.
7. Package — for Python, build a self-contained binary with PyInstaller (or your preferred bundler) and zip the result. For other languages, zip the directory.
8. Publish to the registry — stari client publish module_manifest.json. See the Istari Digital CLI for credentials configuration.
9. Grant access — through the platform UI, assign the published module to users or pools so they can run it.

After publishing, deploying the module onto agent hosts is Module deployment: unpack the package into the agent's istari_modules folder.

What's in this section

Page	What it covers
Module concepts	Modules, functions, manifests, the file-based agent contract, lifecycle, package layout, function variants, scopes, and best practices.
Authoring with the CLI	How stari supports module authors — scaffolding, manifest creation, schema generation, script execution, linting, mock test data.
Design patterns	Patterns for modules that interact with a third-party app or DE tool — reporting failures, repeatable writes, dry runs, preconditions.
Module Manifest API reference	Every manifest field — required vs optional, types, semver-aware version ranges, function info, scripts, dependencies, enums.
Manifest examples	Worked examples of entrypoint, run_command, function schemas, input / output / config file payloads.

tip

For a guided first build:

• Integration 301 — First module (shell): hand-rolled manifest plus a shell script. Teaches the file contract end-to-end without a Python framework.
• Integration 302 — Build a Python module: uses stari module scaffold --type python-module to generate a Pydantic-typed framework, then compiles to a standalone binary with PyInstaller.