Skip to main content
Version: 1.0.0

SDK Python: call Touba

Same program, inputs and results as the other SDK. No model, handler or external service is needed.

1. Install the SDK​

From an empty application directory:

Terminal
touba sdk install python
source .venv/bin/activate

Python 3.11+ is required. On Windows use .venv\Scripts\Activate.ps1.

2. Declare the Touba program​

This program returns a typed value. It is identical in both SDK tutorials.

program.tb
module sdk.engine
strategy Review
    takes value as Text
    gives Text
    do
        give value

3. Import and run​

run.py
from touba_sdk import ToubaEngine

engine = ToubaEngine(project_root=".")
run = engine.run(source="program.tb", inputs={"value": "Invoice 42"})
assert run.status == "success", run
assert run.result == "Invoice 42", run
print(run.result)

Run python run.py; expected result: Invoice 42.

4. Compile and reuse AIR​

Use this alternative entry point to compile once and pass the AIR to the same engine:

compiled.py
from touba_sdk import ToubaEngine

engine = ToubaEngine(project_root=".")
compiled = engine.compile("program.tb")
for air_json in (compiled.air_json, compiled.air_document):
    run = engine.run(air_json=air_json, inputs={"value": "Invoice 42"})
    assert run.status == "success", run
    assert run.result == "Invoice 42", run
print(run.result)

Run python compiled.py. Same result; the Core retains all checks.

5. Check results and errors​

An incorrect input type must cause refusal, not silent success:

refused.py
from touba_sdk import ToubaEngine, ToubaEngineError

engine = ToubaEngine(project_root=".")
try:
    engine.run(source="program.tb", inputs={"value": 42})
except ToubaEngineError as error:
    assert error.phase == "run", error
    assert error.details["status"] == "failure", error
else:
    raise AssertionError("An Int must not be accepted as Text")
print("refused")

Run python refused.py. Human waits and explicit stops instead remain controlled outcomes with status and reason; do not treat them as technical errors.

Validate the full example​

Terminal
.venv/bin/python run.py
.venv/bin/python compiled.py
.venv/bin/python refused.py

6. Continue with handlers​

Continue with the handlers tutorial Python to run host business code. The SDK Python documents options, resumes, testing and limits. Compare the same path with the SDK JavaScript.

Inside asyncio, use AsyncToubaEngine and await for compile and run, without calling the synchronous client from the active loop.