# Run with Python SDK

Use the official `fetch-hive-sdk` package when you want to invoke a prompt deployment from Python. The SDK wraps the public [`POST /v1/invoke`](/api-reference/invoke-prompt.md) endpoint with idiomatic helpers, handles authentication, and parses streaming responses for you.

## Installation

```bash
pip install fetch-hive-sdk
```

The SDK requires Python 3.9+ and uses `httpx` under the hood.

## Authentication

Set the `FETCH_HIVE_API_KEY` environment variable to your workspace API key (the SDK reads it automatically):

```bash
export FETCH_HIVE_API_KEY=fhk_...
```

```python
from fetch_hive_sdk import FetchHive

client = FetchHive()
```

Or pass the key explicitly:

```python
client = FetchHive(api_key="fhk_...")
```

See [API Keys](/your-workspace/api-keys.md) for how to create and rotate keys.

## Basic example

Invoke a prompt deployment and read the final response:

```python
from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
)

print(result["response"])
```

`invoke_prompt` is synchronous and returns the parsed JSON body once the prompt has completed. See the [non-streaming response shape](/api-reference/invoke-prompt.md#response).

## Method reference

| Argument     | Type             | Required | Description                                                                           |
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------- |
| `deployment` | `str`            | Yes      | The prompt deployment name                                                            |
| `variant`    | `str`            | No       | The deployment variant name                                                           |
| `inputs`     | `dict[str, Any]` | No       | Key-value pairs for the prompt variables                                              |
| `user`       | `str`            | No       | Opaque caller identifier surfaced in [User Tracking](/user-tracking/user-tracking.md) |

The SDK injects `streaming: false` for `invoke_prompt`. To stream, use `invoke_prompt_stream` (below).

## Handling the response

The non-streaming response is a plain `dict`:

```python
result = client.invoke_prompt(deployment="my-prompt", variant="default")

print(result["response"])       # final text
print(result["model"])          # model identifier
print(result["usage"])          # token usage breakdown
print(result["request_id"])     # use this to look up the run in Logs
```

## Streaming

Use `invoke_prompt_stream` to receive Server-Sent Events as they arrive. The method returns a generator that yields parsed event dicts:

```python
for chunk in client.invoke_prompt_stream(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
):
    if chunk.get("type") == "response":
        print(chunk.get("response", ""), end="", flush=True)
    elif chunk.get("type") == "usage":
        print("\n\nUsage:", chunk["usage"])
```

The stream yields the same event types documented in [Invoke Prompt → Response](/api-reference/invoke-prompt.md#response): `reasoning`, `response`, and a final `usage` event.

### Async streaming

For `asyncio` applications, use `ainvoke_prompt_stream`. It has the same arguments but returns an async iterator:

```python
import asyncio
from fetch_hive_sdk import FetchHive

async def main():
    client = FetchHive()
    async for chunk in client.ainvoke_prompt_stream(
        deployment="YOUR_DEPLOYMENT_NAME",
        variant="YOUR_VARIANT_NAME",
        inputs={"text": "Hello"},
    ):
        if chunk.get("type") == "response":
            print(chunk.get("response", ""), end="", flush=True)

asyncio.run(main())
```

## Configuration

| Option     | Default                        | Description                     |
| ---------- | ------------------------------ | ------------------------------- |
| `api_key`  | `FETCH_HIVE_API_KEY` env var   | Bearer token from the dashboard |
| `base_url` | `https://api.fetchhive.com/v1` | Override the API base URL       |
| `timeout`  | `120`                          | Request timeout in seconds      |

```python
client = FetchHive(
    api_key="fhk_...",
    base_url="https://api.fetchhive.com/v1",
    timeout=60,
)
```

## Errors

Non-2xx responses raise an `httpx.HTTPStatusError` with the status code and response body. Wrap calls in `try`/`except` if you need to handle failures:

```python
import httpx

try:
    result = client.invoke_prompt(deployment="my-prompt", variant="default")
except httpx.HTTPStatusError as exc:
    print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```

See [Errors and Rate Limits](/api-reference/errors-and-rate-limits.md) for status code meanings.

## Links

* [Package on PyPI](https://pypi.org/project/fetch-hive-sdk/)
* [Source on GitHub](https://github.com/Fetch-Hive/python-sdk)

## Next steps

* [Run with API](/prompts/run-with-api.md) - The same flow with cURL
* [Run with Node.js SDK](/prompts/run-with-nodejs-sdk.md)
* [Run with Ruby SDK](/prompts/run-with-ruby-sdk.md)
* [Run with PHP SDK](/prompts/run-with-php-sdk.md)
* [Invoke Prompt](/api-reference/invoke-prompt.md) - Full endpoint reference


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fetchhive.com/prompts/run-with-python-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.