Python SDK

Install and configure the woodwide Python client — typed methods, async support, and error handling.

The woodwide package is the official Python client for Wood Wide. It provides typed methods, Pydantic responses, and IDE autocomplete for training and inference workflows.

For your first upload → train → infer workflow, use the Python (SDK) tab in the API quickstart. This page covers installation, configuration, and SDK-specific features.

PyPI

Install, release history, and package README.

API quickstart

First workflow with an SDK tab alongside curl and JavaScript.

These examples target woodwide==0.9.0. Use the PyPI package README for the complete client guide, or inspect methods in Python with help(client.models.train).

---

Install

Requires Python 3.9+.

pip install "woodwide==0.9.0"

Pin a version in production. Check PyPI for the latest release.

---

Configure authentication

export WOODWIDE_API_KEY="sk_your_api_key_here"
export WOODWIDE_BASE_URL="https://api.woodwide.ai"

from woodwide import WoodWide

client = WoodWide()  # reads env vars; or pass api_key= / base_url=

The SDK, HTTP examples, and CLI all use WOODWIDE_API_KEY and WOODWIDE_BASE_URL. The base URL defaults to https://api.woodwide.ai.

Verify authentication:

datasets = client.datasets.list(limit=1)
print("Authenticated. Visible datasets:", len(datasets.items))

Never commit API keys to source control.

---

Async client

Use AsyncWoodWide with await on each call:

import asyncio
from pathlib import Path
from woodwide import AsyncWoodWide

async def main() -> None:
    async with AsyncWoodWide() as client:
        dataset = await client.datasets.create(
            file=Path("train.csv"),
            dataset_name="async_train",
        )
        print(dataset.id)

asyncio.run(main())

Optional aiohttp backend: pip install woodwide[aiohttp]

---

Errors and retries

The SDK raises typed exceptions (AuthenticationError, RateLimitError, etc.) and retries connection errors and many 5xx responses by default.

import woodwide
from woodwide import WoodWide

client = WoodWide(max_retries=3)

try:
    client.datasets.list(limit=1)
except woodwide.AuthenticationError:
    print("Check WOODWIDE_API_KEY")
except woodwide.APIStatusError as e:
    print(e.status_code, e.response.text)

See the PyPI package README for timeouts, logging, and HTTP configuration.

---

Model types

All model types use the same methods. Select the task with model_type when training:

Task	Train	Infer
Prediction	client.models.train(model_type="prediction", ...)	client.models.infer(...)
Clustering	client.models.train(model_type="clustering", ...)	client.models.infer(...)
Anomaly	client.models.train(model_type="anomaly", ...)	client.models.infer(..., anomaly_format="per_row")
Embedding	client.models.train(model_type="embedding", ...)	client.models.infer(...)
Factors	client.models.train(model_type="factors", ...)	client.models.infer(...)
Search	client.models.train(model_type="search", ...)	client.models.infer(..., k=10)

Use client.models.infer(model_id, file=..., output_type="json") for synchronous file inference. Use client.models.infer_batch(model_id, dataset_id=...) for asynchronous inference on an existing dataset, then poll and retrieve the result through client.jobs.

See Capabilities for task-specific examples with SDK tabs.

---

Next steps

API quickstart

First workflow with an SDK tab alongside curl and JavaScript.

CLI

Script the same workflow from the shell.