Metadata-Version: 2.4
Name: stewai
Version: 0.1.7
Summary: Official StewAI Python SDK
Project-URL: Documentation, https://docs.stewai.com/sdk-api/overview
Project-URL: Availability, https://docs.stewai.com/sdk-api/availability-and-access
Project-URL: Marketplace, https://docs.stewai.com/marketplace/overview
Project-URL: Website, https://stewai.com
Author-email: StewAI <dev@stewai.com>
License: StewAI Commercial License
        Version 0.0.0 – June 2025
        Copyright © 2025 Christian Mueller. All rights reserved.
        
        1. Grant of License
           You are granted a non-exclusive, non-transferable, revocable license to
           (a) view and modify the source code in this repository,
           (b) run the Software for your internal evaluation or development purposes only.
        
        2. Restrictions
           • No distribution, sublicensing, or SaaS offering of the Software or
           Derivative Works is permitted without a separate commercial agreement.
           • You may not remove or alter any proprietary notices.
           • Reverse engineering of any binary distribution is prohibited unless
           required by law.
        
        3. Termination
           This License terminates automatically if you breach any term. Upon
           termination you must destroy all copies and cease all use.
        
        4. DISCLAIMER
           THE SOFTWARE IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND. THE AUTHOR
           DISCLAIMS ALL LIABILITY FOR DAMAGES, DIRECT OR INDIRECT, ARISING FROM USE
           OF THE SOFTWARE.
        
        For a production or redistribution license, contact:
        Christian Mueller · christian.mueller@camueller.org
License-File: LICENSE.md
Keywords: api,sdk,stewai
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# 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.
