The Oda Python SDK

The Oda Python SDK lets a Python program drive DataMind Oda as a subprocess: your program starts a bundled Oda runtime and talks to it over newline-delimited JSON-RPC on standard input and output. Use it when a script or an internal tool of yours should run Oda tasks from outside the app.

This page covers installation, a first run from the shipped example, the profiles and the settings you pass. The run results, the runtime's lifecycle, the wire surface and the error details are in the Python SDK reference.

Install the SDK

The Python side of the SDK is two packages, installed together: the SDK package (the client, which starts the bundled runtime for you and drives runs through it) and the runtime package (the bundled Oda runtime for one system, with its supporting files). The SDK package declares the runtime package as a dependency, so an install brings the package that matches your operating system and processor, and the two share one version.

Python 3.10 or later. Both packages install on Python 3.10 and newer.
No system Node.js. The runtime ships prebuilt inside the runtime package: using the SDK needs no system Node.js and no build step, and nothing extra is downloaded or compiled at install time.
Source builds are explicit. The released packages carry the production runtime only; running against a development source build takes an explicit request, and a normal launch never selects one, so a production deployment never runs on a source build by accident.
The right package for your system. A system with no published runtime package is refused rather than served by another system's build. Platform support lists the systems.

Your first run

Choose the folders. Pass the home folder: every launch needs one, and the SDK never falls back to a default home folder; the runtime keeps the profile it runs and the sessions it creates there. Pass the workspace folder the agent should work in; it is resolved to an absolute path before the runtime starts.
Create the client. Construct it with the home folder, the workspace folder and the profile you want; the settings table below lists what else you can pass. The client starts the bundled runtime as a subprocess when it is first needed and reuses it for later runs; you never start the runtime by hand.
Run a prompt. Pass the task text, and a session id if you want to name the session. The call returns when the session goes idle; read the final response from the result.
Close when you are done. Closing stops the runtime; a context manager closes it for you when the block ends.

Start from the shipped example

The SDK package ships a runnable minimal example: it drives the sdk-minimal profile, runs one task and prints the agent's final response. These are the choices it takes:

What you pass	What it decides
The task text	The prompt for the run.
The workspace folder	The folder the agent works in.
The home folder	Where the runtime keeps its profile and sessions; the example stops without one, with a message that an explicit home is required.
The profile	Which profile to drive; it defaults to `sdk-minimal`.
The session id	A name for the session; without one, the run gets its own.
The provider and model	The model route; without them, the built-in route applies, and the runtime resolves it before the first prompt.
The token cap	Optional; caps the output of each request.

Profiles

sdk is the default. A client you create runs the sdk profile unless you pass another; it answers SDK clients and carries the usual tool set.
sdk-minimal is a small standalone runtime. It exposes exactly one tool, a persistent shell, and it is built as its own tree rather than an extension of the usual profile, so anything extra is an explicit change. Automation clients describes what it includes and leaves out.
A profile of your own must keep the JSON-RPC server. A profile you build must keep the part that answers SDK clients; without it the profile cannot serve a client, and the problem surfaces when the runtime starts or the SDK initializes, with no fallback to a working configuration.
The web application is separate. An SDK client cannot select it: it is not a serving profile.

Settings and defaults

These are the settings you pass when you create the client, with their defaults:

Setting	Default	What it does
Home folder	required	Where the runtime keeps its profile and sessions; every launch needs one and the SDK never falls back to a default.
Working folder	your program's folder	The folder the agent works in; resolved to an absolute path before launch.
Runtime folder	the working folder	The folder the runtime process itself starts in.
Profile	`sdk`	The profile the bundled runtime runs.
Patch files	none	Applied in order after the profile's own layers; the later file wins.
Provider and model	the built-in route	The model route, resolved before the runtime accepts a prompt; a route it cannot serve fails the start instead of falling back.
Reasoning effort	the model's default	How long the model thinks before it answers; omit it for the model's own default.
Token cap	none	Caps the output of each request.
Service address and key	your environment	Override the address and key the runtime starts with; without them the runtime inherits your program's environment, so credentials already set there keep working.
Start-up timeout	30 seconds	How long the start-up handshake may take before the client gives up.
Shutdown timeout	1 second	How long the shutdown request may take before the client moves on.
Request timeout	none	With no value, a run waits for the task, however long it takes.

Patches, Office and skills

Ordered patch files. Pass one or more patch files as absolute paths; they apply in order after the profile's own layers, and when two change the same entry the later file wins.
Applied at the next start. A patch change takes effect when the runtime process starts; there is no rebuild step, even for skills and other resources.
Office documents out of the box. The runtime package carries the Office document skills, so a session can author and check Word, PowerPoint and Excel files.
Turn them off or replace them. A patch can disable the Office skill, or point it at a replacement resource folder; both take effect at the next start.
Your files win. A skill you keep on the filesystem overrides a bundled skill with the same name.

Questions, answered

How do I install the Python SDK?

Two packages, installed together: the SDK package (the client) and the runtime package for your operating system and processor. The SDK package brings the matching runtime package with it, and the two share one version. Both run on Python 3.10 or later.

Do I need a system Node.js?

No. The runtime ships prebuilt inside the runtime package, so using the SDK needs no system Node.js and no build step. Only a development source build needs a system Node.js, and that route is an explicit request.

What happens if I launch without a home folder?

The launch is refused: every launch needs an explicit home folder, and the SDK never falls back to a default one. The error says an explicit home is required.

Which profile should I use?

Start with sdk, the default: it answers SDK clients with the usual tool set. Choose sdk-minimal for exactly one persistent shell tool; Automation clients describes what it includes and leaves out. A profile you build must keep the part that answers SDK clients.

What does the shipped example do?

It drives the sdk-minimal profile, runs one task and prints the agent's final response. You give it the task, the workspace and home folders, the profile, a session id and the model route; without a home folder it stops with a message that an explicit home is required.

When do patch changes take effect?

At the runtime's next start. There is no rebuild step, even for skills and other resources.

Can I disable the Office document features?

Yes. Disable the Office skill in a patch, or point it at a replacement resource folder; the change takes effect at the next start. A skill you keep on the filesystem still overrides a bundled skill with the same name.

What if the model I name cannot be served?

The start fails: the runtime resolves the route before it accepts a prompt, and a route it cannot serve does not fall back to a default. Name a provider and model this runtime can serve and start again.

Why can't my custom profile serve a client?

It is missing the part that answers SDK clients (the JSON-RPC server). Without it the profile cannot serve a client, and the problem surfaces when the runtime starts or the SDK initializes. Keep that part in the profile and try again.

Can I drive the web application with the SDK?

No. The web application is separate and is not a serving profile, so an SDK client cannot select it.