Python Installation

pip install noukai-sdk

uv pip install noukai-sdk

export NOUKAI_API_KEY=nk_yourkey_...

export NOUKAI_ORG=acme
export NOUKAI_PROJECT=spelling

from noukai_sdk import Noukai
 
client = Noukai(api_key="nk_yourkey_...", org="acme", project="spelling")

from noukai_sdk import Noukai
 
with Noukai(org="acme", project="spelling") as client:
    flow = client.flow("grade-3")
    result = flow.execute(message="The cat sat on the mat.")
    print(result.output)

Advanced configuration

Local development

For local development, use env="dev" to connect to http://localhost:8080/api/v1:

from noukai_sdk import Noukai
 
client = Noukai(
    api_key="nk_...",
    env="dev",
    org="acme",
    project="spelling"
)

Or set the environment variable:

export NOUKAI_ENV=dev

The env parameter accepts:

• "dev" or "development" → http://localhost:8080/api/v1
• "production" (default) → https://api.noukai.xyz/api/v1
• Other values use the production default

URL targeting

The SDK targets Noukai's hosted endpoints (api.noukai.xyz for production, localhost:8080 for env="dev"). There is no way to point the SDK at a custom URL — this is a deliberate constraint to prevent accidental misrouting.

The only user-facing way to switch URL targets is the env option (or NOUKAI_ENV env var).

Timeouts and retries

Customize request timeouts and retry behavior:

from noukai_sdk import Noukai
 
client = Noukai(
    timeout=300_000,    # 5 minutes (default: 300 seconds)
    max_retries=1       # Retry once on 5xx (default: 1)
)

Logging

Enable debug logging:

import logging
 
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("noukai_sdk")
logger.setLevel(logging.DEBUG)

Next steps

• Quickstart — Run your first flow
• Guides — Learn key patterns
• API Reference — Class and method signatures