Installation

The ntro SDK is the Python interface to Ntropii. It’s what runbooks import (when they run inside Ntropii Tenant) and what the CLI and MCP server import (to talk to Ntropii Workspace on your behalf).

Install

Core (just the client)
With workflow authoring
With test harness

pip install ntro

Includes everything you need to call Ntropii Workspace: Client, all resource accessors, all Pydantic models, all exceptions.

pip install 'ntro[workflow]'

Adds ntro.workflow (NtroWorkflow, @runbook.step), ntro.ingest, ntro.subledger, all ntro.capabilities.* modules, ntro.events, ntro.accounting, and ntro.data. This is what your runbook’s requirements.txt should pin — it’s the runtime dependency Ntropii Tenant installs alongside your runbook.

pip install 'ntro[testing]'

Adds ntro.testing (WorkflowHarness, Scenario, load_runbook, auto-mocked activities) on top of [workflow]. Use this in your runbook repo’s dev dependencies — the ntro workflow test CLI command installs this transitively.

In a runbook repo, pin ntro[workflow] in requirements.txt (worker installs this) and ntro[testing] in dev dependencies (CI / local iteration).

Quick start

from ntro.workspace import Client

# Reads ~/.ntro/config.toml — uses the default connection
client = Client.from_config()

# Or pick a named connection
client = Client.from_config(connection="staging")

# Or be explicit (scripting / testing)
client = Client(
    host="https://api.ntropii.com/v1",
    api_key="ntro_prod_xxx",
)

Confirm it works:

profile = client.identity.whoami_sync()
print(profile.email, profile.orgId)

Configuration

The SDK reads ~/.ntro/config.toml (or $NTRO_HOME/config.toml):

default_connection_name = "local"

[connections.local]
host = "http://localhost:3000/v1"
api_key = "ntro_dev_key"
default_tenant = "acme-fund"

[connections.production]
host = "https://api.ntropii.com/v1"
api_key = "ntro_prod_xxx"

Run ntro auth login to populate this file interactively.

Resolution priority

When Client.from_config() runs, it resolves credentials in this order:

Explicit constructor args

Client(host=..., api_key=...) always wins. Useful in tests where you want zero environmental influence.

Environment variables

NTRO_HOST / NTRO_API_KEY. Useful in CI/CD where you don’t want a config.toml on disk.

Named connection

Client.from_config(connection="staging") reads [connections.staging] from the config file.

Default connection

Falls back to the connection named in default_connection_name.

Async vs sync

Every resource method is async-first with a _sync wrapper for scripts and notebooks:

# Sync — fine for scripts, notebooks, the CLI
tenants = client.tenants.list_sync()

# Async — for runbooks (Temporal workers run async), high-throughput scripts
import asyncio

async def main():
    client = Client.from_config()
    tenants, workflows = await asyncio.gather(
        client.tenants.list(),
        client.workflows.list(),
    )
    await client.close()

asyncio.run(main())

The _sync variants call asyncio.run() internally — don’t use them inside an async function or you’ll get nested event-loop errors.

What’s next

Ntropii client

The full surface of ntro.workspace.Client — every resource accessor and exception.

Workflows overview

NtroWorkflow + @runbook.step — the SDK primitives runbooks compose.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

Install

Quick start

Configuration

Resolution priority

Async vs sync

What’s next

Ntropii client

Workflows overview

​Install

​Quick start

​Configuration

​Resolution priority

​Async vs sync

​What’s next

Ntropii client

Workflows overview

Install

Quick start

Configuration

Resolution priority

Async vs sync

What’s next