Metadata-Version: 2.4
Name: runflow-sdk
Version: 1.9.0
Summary: SDK Python da Runflow (porte do @runflow-ai/sdk) — só biblioteca padrão no núcleo
Author: Runflow
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: fabric
Requires-Dist: pyodbc>=5; extra == "fabric"
Provides-Extra: pydantic
Requires-Dist: pydantic>=2; extra == "pydantic"
Provides-Extra: rpa
Requires-Dist: playwright>=1.40; extra == "rpa"

# runflow-sdk (Python)

SDK Python da Runflow, porte do `@runflow-ai/sdk` (TypeScript).

- **Paridade com o TS.** Os endpoints, cabeçalhos e corpos são os mesmos; os nomes viram snake_case.
- **Sem dependências no núcleo.** Só biblioteca padrão, Python ≥ 3.11.
- **Extras opcionais.** `pip install runflow-sdk[fabric]` (pyodbc), `[pydantic]` e `[rpa]` (playwright).

A tabela de paridade e as diferenças de comportamento estão em [PORTING.md](./PORTING.md).

## Como um agente Python roda na Runflow

1. O build da plataforma reconhece um agente Python quando a árvore tem `requirements.txt` e não tem `package.json`.
2. A execução roda `python3 agent.py`.
3. O executor escreve um JSON na entrada padrão: `{"type":"execute","execution_id","agent_id","input":{...},"context":{...}}`.
4. O agente responde com uma linha JSON na saída padrão. `run(handler)` cuida desse protocolo.
5. A chave da API vem de `.runflow/rf.json`, que vai junto no pacote (como no SDK TS). O executor injeta `RUNFLOW_TENANT_ID`, `RUNFLOW_AGENT_ID`, `RUNFLOW_EXECUTION_ID`, `RUNFLOW_THREAD_ID`, `RUNFLOW_ENVIRONMENT` e `RUNFLOW_API_URL`.

Estrutura mínima:

```
meu-agente/
  agent.py
  requirements.txt        # pode ficar vazio; o SDK não precisa de nada
  runflow_sdk/            # copie o pacote (ou instale via requirements)
  .runflow/rf.json        # gerado pelo `rf`
```

## Exemplo de `agent.py`

```python
from runflow_sdk import Agent, create_tool, get_credential, load_env, run, track
from runflow_sdk.models import anthropic

# credenciais → os.environ (sem logar valores)
load_env(json_credentials=["FABRIC"], secrets=["ERP_TOKEN"])


def buscar_pedido(call):
    numero = call.context["numero"]
    return {"numero": numero, "status": "faturado"}


pedido = create_tool(
    id="buscar_pedido",
    description="Busca o status de um pedido pelo número",
    input_schema={"numero": "string"},          # notação curta; JSON Schema também serve
    execute=buscar_pedido,
)

agente = Agent(
    name="Atendimento Pedidos",
    instructions="Você responde sobre pedidos. Responda exclusivamente com base nas ferramentas.",
    model=anthropic("claude-sonnet-4-5-20250929", provider_name="Anthropic (Brasal)"),
    model_config={"temperature": 0},
    tools={"buscar_pedido": pedido},
    memory={"max_turns": 10},
)


def handler(ctx):
    out = agente.process({"message": ctx.message, "sessionId": ctx.session_id, "metadata": ctx.metadata})
    track("pedido_respondido", {"tools": out["metadata"]["toolsUsed"]})
    return out            # dict vira o output; str vira {"message": str}


if __name__ == "__main__":
    run(handler)          # lê stdin, responde na stdout, faz flush de eventos e traces
```

Dentro do handler, `print()` vai para stderr, para não corromper o protocolo. Exceções viram `{"type":"error"}`.

## Mapa rápido (TS → Python)

| TS | Python |
|---|---|
| `new Agent({...}).process(input)` | `Agent(...).process(input)` |
| `Memory.get()`, `KV.set(k, v, {ttl})` | `Memory.get()`, `KV.set(k, v, ttl=60)` |
| `new Knowledge({vectorStore}).search(q)` | `Knowledge(vector_store=...).search(q)` |
| `LLM.anthropic(model).generate(...)` | `LLM.anthropic(model, provider_name=...).generate(...)` |
| `track(name, props)` / `flushTrackEvents()` | `track(name, props)` / `flush()` |
| `identify({type, value})` | `identify({"type": ..., "value": ...})` ou `identify("+55...")` |
| `connector('hubspot', 'get-contact', data)` | `connector("hubspot", "get-contact", data)` |
| `getCredential(name)` (objeto) | `get_credential_record(name)`; `get_credential(name)` devolve só o valor |
| `createWorkflow({...}).step(...).build()` | `create_workflow(id=..., name=...).step(...).build()` |
| `await x` | síncrono; para asyncio, `await aio(x).metodo()` |

Corpos e filtros que vão para a API ficam no formato do fio (camelCase). Os kwargs dos managers aceitam snake_case e são convertidos. `None` não é enviado; para mandar `null` explícito use `JSON_NULL`.

## Versão

Mesma numeração do `@runflow-ai/sdk`: `runflow-sdk 1.9.x` tem paridade com `@runflow-ai/sdk 1.9.x`. A versão vive só em `runflow_sdk/__init__.py` (`__version__`); o `pyproject.toml` lê de lá.

- Release do TS com mudança de API → porte a mudança e iguale `__version__`. O teste `tests/test_version.py` falha enquanto as bases divergirem, e o workflow roda também quando `packages/sdk/package.json` muda.
- Correção que só existe no Python → pós-release: `1.9.0.post1`, `1.9.0.post2`. A base continua a do TS.
- O workflow `publish-sdk-python.yml` publica no PyPI no merge para `main` quando a versão ainda não existe lá.

## Testes

```
cd packages/sdk-python
python3 -m unittest discover
```

Os testes usam HTTP simulado (mock de `urllib.request.urlopen`) e conferem URL, método, cabeçalhos e corpo de cada endpoint. Nenhum teste chama a API real.
