# stewai (Python SDK)

[![PyPI version](https://img.shields.io/pypi/v/stewai.svg)](https://pypi.org/project/stewai/)
[![Python versions](https://img.shields.io/pypi/pyversions/stewai.svg)](https://pypi.org/project/stewai/)

Base URL (only): `https://api.stewai.com/v1`

Public docs:

- SDK overview: `https://docs.stewai.com/sdk-api/overview`
- Availability, scopes, and feature gates: `https://docs.stewai.com/sdk-api/availability-and-access`

## Install

```bash
pip install -U stewai
```

## Get an API key

1. Log in to `stewai.com`
2. Go to `Settings → API keys`
3. Create a key and copy it once (`sk-live-...`)

## Usage

```python
from stewai import Client

client = Client(api_key="sk-live-...")

# Use the Input step “API input id” shown in the editor as the inputs key
run = client.runs.create(
    recipe_id="01K....",
    inputs={"USERQUESTION": "What should I focus on this week?"},
)

print(run["status"])  # done|failed|cancelled|blocked

# Debug only: full execution trace (steps + outputs)
trace = client.runs.steps(run["id"])
```

## List runs

```python
runs = client.runs.list(page=1, page_size=20, status="done")
print(runs["count"])
```

## List own recipes (`/v1/recipes/`)

```python
recipes = client.recipes.list(page=1, page_size=20)
print(recipes["count"])
```

`client.recipes.get/create/update/delete` map to server endpoints that are
currently disabled by default and may return `404`.

## Access and availability notes

- `client.runs` is baseline public v1.
- `client.recipes.list()` is baseline public v1.
- `client.recipes.get/create/update/delete` exist in the SDK, but may return `404` when recipe self-service is disabled on the deployment.
- `client.marketplace.*` requires Marketplace to be enabled on the deployment.
- `client.marketplace.search(...)` also requires the Marketplace search index.
- `client.storage.*` requires Storage to be enabled on the deployment.
- Scoped keys need the matching permissions such as `runs:create`, `runs:read`, `recipes:read`, `recipes:write`, `marketplace:read`, and `marketplace:run`.

## Marketplace discovery (query -> detail -> run)

```python
from stewai import Client

client = Client(api_key="sk-live-...")

recipes = client.marketplace.search(
    "gemini web search",
    visibility="public_open",
    page=1,
    page_size=20,
)

first = recipes["results"][0]
detail = client.marketplace.detail(first["recipe_ulid"])

run = client.marketplace.run(
    first["recipe_ulid"],
    inputs={"query": "latest gemini model updates"},
    wait=True,
)
print(run["status"])
```

## Ingest sources (URLs + Pantry docs)

```python
from stewai import Client, IngestSource

client = Client(api_key="sk-live-...")

run = client.runs.create(
    recipe_id="01K....",
    ingest={
        "ingest_1": [
            IngestSource(uri="https://example.com/docs", kind="url"),
        ]
    },
)
```

## Upload + resolve Pantry paths

```python
from stewai import Client, IngestSource

client = Client(api_key="sk-live-...")

upload = client.storage.upload("./report.pdf")
run = client.runs.create(
    recipe_id="01K....",
    ingest={"ingest_1": [upload.to_ingest_source(label="Q4 Report")]},
)

resolved = client.storage.resolve_path("Reports/Q4.pdf")
if resolved:
    client.runs.create(
        recipe_id="01K....",
        ingest={"ingest_1": [resolved.to_ingest_source()]},
    )
```

## Environment variable

```bash
export STEWAI_API_KEY="sk-live-..."
```

```python
from stewai import Client

client = Client()  # reads STEWAI_API_KEY
run = client.runs.create(recipe_id="01K....", wait=False)
run = client.runs.wait(run["id"], timeout=300)
```

## Output usage contract (credits-first)

- `client.runs.steps(run_id)` returns `output_flat.usage` with credits-focused billing fields.
- Raw token counters are hidden by default in user-facing v1 responses.
- Compatibility mode for token counters is server-gated and requires privileged access.
