Tutorial - Python SDK, Engine and provider

Connect a Python provider to the real Core, retain history in SQLite and check the result. This recipe runs entirely locally: no API key, no model call and no synthetic price presented as a vendor tariff.

1. Install the project SDK

From a project directory, with Touba already installed:

touba sdk install python
source .venv/bin/activate

On Windows, use .venv\Scripts\Activate.ps1. Keep touba on your terminal's PATH. See the Python SDK guide.

2. Declare the program

program.tb

module sdk.provider
agent Reviewer
    gives Text
    responsibility "Return the text Ready."
    callable_by strategy Run
strategy Run
    gives Text
    uses Reviewer
    do
        Reviewer
            into result
        give result

3. Connect the provider and history

provider.py

from pathlib import Path
from touba_sdk import create_ai_sdk_decision_provider
from touba_sdk.history.sqlite import create_sqlite_decision_history_store

Path(".touba/private").mkdir(parents=True, exist_ok=True, mode=0o700)
store = create_sqlite_decision_history_store(
    filename=".touba/private/history.sqlite"
)

async def generate(options):
    # Deterministic teaching example, not a model call.
    return {
        "finishReason": "stop",
        "object": {"decision": {
            "action": "answer_directly",
            "source": "tutorial",
            "reason": "The requested text is available.",
            "result": "Ready",
        }},
    }

decide_agent_capability = create_ai_sdk_decision_provider(
    model="offline-demo",
    generate_object=generate,
    json_schema=lambda schema: schema,
    history={"store": store, "namespace": "tutorial"},
)

The generate callback supplies a deterministic teaching fixture in the adapter's expected format. For a model application, use your vendor transport or a factory such as create_open_ai_decision_provider. Core validation still checks the output type and proposed actions.

SQLite comes with the backend bundled with Touba: no database server to install. History uses run and invocation identities, not just the agent name. A new run does not implicitly reuse a completed conversation. RAM also works during the module lifetime: omit history to use the default.

4. Run and check

app.py

from touba_sdk import ToubaEngine
from touba_sdk.testing import assert_run_succeeded

engine = ToubaEngine(project_root=".")
run = engine.run(
    source="program.tb",
    entry_ref="strategy:sdk.provider/Run",
    agent_decision_provider="provider.py",
    timeout=20,
)
assert_run_succeeded(run, "Ready")
print(run.result)

python app.py

Expected result: Ready. Python loads the module from the project; stdout is reserved for the protocol. Module logs may use stderr. The CLI closes the module and backend at the end of the run; SQLite remains on disk.

5. Connect a model

The Python SDK guide shows the HTTP factory and decision_interface="native". Set an available model, its host environment key and a suitable budget before making a paid call. Both interfaces retain the same Core admission. The generic adapter also accepts generate_text and json_schema following the AI SDK contract.

For bounded context, read history and compaction. History limits are separate from the monetary ceiling described in the provider-cost guide.