> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejecutar con el SDK de Python

> Invoca un deployment de prompt desde Python con el paquete fetch-hive-sdk

# Ejecutar con el SDK de Python

Usa el paquete oficial `fetch-hive-sdk` cuando quieras invocar un deployment de prompt desde Python. El SDK envuelve el endpoint público [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) con ayudantes idiomáticos, maneja la autenticación y analiza las respuestas en streaming por ti.

## Instalación

```bash theme={null}
pip install fetch-hive-sdk
```

El SDK requiere Python 3.9+ y usa `httpx` por debajo.

## Autenticación

Configura la variable de entorno `FETCH_HIVE_API_KEY` con tu clave de API del workspace (el SDK la lee automáticamente):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()
```

O pasa la clave explícitamente:

```python theme={null}
client = FetchHive(api_key="fhk_...")
```

Consulta [API Keys](../workspace/api-keys) para saber cómo crear y rotar claves.

## Ejemplo básico

Invoca un deployment de prompt y lee la respuesta final:

```python theme={null}
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` es síncrono y devuelve el cuerpo JSON analizado una vez que el prompt se ha completado. Consulta la [forma de respuesta sin streaming](../api-reference/prompts/invoke#response).

## Referencia del método

| Argumento    | Tipo                                             | Requerido | Descripción                                                                                                                                      |
| ------------ | ------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deployment` | `str`                                            | Sí        | El nombre del deployment de prompt                                                                                                               |
| `variant`    | `str`                                            | No        | El nombre de la variante del deployment                                                                                                          |
| `inputs`     | `dict[str, Any]`                                 | No        | Pares clave-valor para las variables del prompt                                                                                                  |
| `user`       | `str`                                            | No        | Identificador opaco de quien llama, expuesto en [User Tracking](../user-tracking/overview)                                                       |
| `metadata`   | `dict[str, str \| int \| float \| bool \| None]` | No        | Metadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta [Metadata de invoke](../user-tracking/invoke-metadata) |

El SDK inyecta `streaming: false` para `invoke_prompt`. Para transmitir, usa `invoke_prompt_stream` (a continuación).

## Manejo de la respuesta

La respuesta sin streaming es un `dict` simple:

```python theme={null}
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

Usa `invoke_prompt_stream` para recibir Server-Sent Events a medida que llegan. El método devuelve un generador que produce diccionarios de eventos analizados:

```python theme={null}
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"])
```

La transmisión produce los mismos tipos de evento documentados en [Invoke Prompt → Response](../api-reference/prompts/invoke#response): `reasoning`, `response`, un evento `usage` final o un evento `error` si el proveedor falla durante la transmisión.

### Streaming asíncrono

Para aplicaciones `asyncio`, usa `ainvoke_prompt_stream`. Tiene los mismos argumentos pero devuelve un iterador asíncrono:

```python theme={null}
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())
```

## Configuración

| Opción     | Predeterminado                           | Descripción                         |
| ---------- | ---------------------------------------- | ----------------------------------- |
| `api_key`  | variable de entorno `FETCH_HIVE_API_KEY` | Token bearer del dashboard          |
| `base_url` | `https://api.fetchhive.com/v1`           | Sobrescribe la URL base de la API   |
| `timeout`  | `120`                                    | Timeout de la solicitud en segundos |

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

## Errores

Las respuestas distintas a 2xx lanzan un `httpx.HTTPStatusError` con el código de estado y el cuerpo de la respuesta. Envuelve las llamadas en `try`/`except` si necesitas manejar fallos:

```python theme={null}
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)
```

Consulta [Errors and Rate Limits](../api-reference/errors-and-rate-limits) para el significado de los códigos de estado.

## Enlaces

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

## Siguientes pasos

* [Ejecutar con API](./run-with-api) - El mismo flujo con cURL
* [Ejecutar con el SDK de Node.js](./run-with-nodejs-sdk)
* [Ejecutar con el SDK de Ruby](./run-with-ruby-sdk)
* [Ejecutar con el SDK de PHP](./run-with-php-sdk)
* [Invoke Prompt](../api-reference/prompts/invoke) - Referencia completa del endpoint