Metadata-Version: 2.4
Name: ragaas
Version: 0.1.0
Summary: SDK Python oficial do RAGaaS (ragaas.com.br) — RAG, memória de agente e gateway OpenAI-compatible
Project-URL: Homepage, https://ragaas.com.br/developers
Project-URL: Documentation, https://ragaas.com.br/developers
Project-URL: Repository, https://github.com/vertikon/ragaas.com.br
Author: Vertikon
License-Expression: MIT
License-File: LICENSE
Keywords: brasil,embeddings,lgpd,llm,memory,openai,rag,retrieval,sdk
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ragaas — SDK Python

SDK oficial do **RAGaaS** — RAG, memória de agente e gateway OpenAI-compatible. Zero dependências (só stdlib).

```bash
pip install ragaas
```

```python
from ragaas import Ragaas, RagaasError

ragaas = Ragaas(api_key="rag_sk_...")   # chave da subconta

# pergunta com RAG completo (resposta + fontes citadas + run_id)
r = ragaas.query("qual o prazo de matrícula?")
print(r["answer"], r["sources"], r["run_id"])

# busca híbrida sem LLM
hits = ragaas.search("matrícula", kb_id="kb_...", top_k=8)["hits"]

# memória de agente (sempre armazenada no Brasil)
ragaas.memory.add("o cliente prefere respostas curtas", kind="preference")
ragaas.memory.search("preferências", top_k=5)

# streaming pelo gateway OpenAI-compatible
for delta in ragaas.chat_stream({"model": "ragaas", "messages": msgs}, kb_id="kb_..."):
    print(delta["choices"][0]["delta"].get("content", ""), end="", flush=True)
```

## Robustez (produção)

- **Retry/backoff** exponencial com jitter em `429/502/503/504` e falhas de rede; respeita `Retry-After`. Configurável via `max_retries` / `timeout`.
- **Erros tipados:** `RagaasError` expõe `.status`, `.message`, `.request_id` (header `X-Request-Id` — cite no suporte) e `.retryable`.

```python
try:
    r = ragaas.query("...")
except RagaasError as e:
    print(e.status, e.message, "request:", e.request_id, "retryable:", e.retryable)
```

## Superfície

`query` · `search` · `feedback` · `ingest_url` · `ingest_file` · `documents.{list,get,delete}` ·
`knowledge_bases.{list,get}` · `runs.get` · `memory.{add,search,list,update,delete}` ·
`chat` · `chat_stream` · `embeddings` · `models`.

Especificação completa (OpenAPI 3.1): <https://api.ragaas.com.br/openapi.json> · docs: <https://ragaas.com.br/developers>
