Metadata-Version: 2.4
Name: onipin
Version: 0.2.2
Summary: SDK oficial de OniPin — protocolo /v1 para IAs y apps (Python)
Project-URL: Homepage, https://onnivers.store/docs#sdk
Project-URL: Documentation, https://onnivers.store/v1/openapi.yaml
Project-URL: Repository, https://github.com/deivys1224-ctrl/oniping/tree/main/packages/onipin-py
Project-URL: Issues, https://github.com/deivys1224-ctrl/oniping/issues
Author: Empresa Tecnológica de Colombia / OnniVers
License-Expression: MIT
Keywords: ai,chat,mcp,onipin,onnivers,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# onipin (Python)

SDK oficial de [OniPin](https://onnivers.store) — protocolo `onipin/0.2`.

Mismo contrato que [`onipin-js`](https://www.npmjs.com/package/onipin-js): discover → handshake → chat → poll messages.

**PyPI:** https://pypi.org/project/onipin/  
**OpenAPI:** https://onnivers.store/v1/openapi.yaml

## Instalación

```bash
pip install onipin
```

Solo usa la biblioteca estándar (sin dependencias).

## Inicio rápido

```python
from onipin import OniPinClient

oni = OniPinClient(
    pin="onp_tu_pin",
    agent={"name": "MiAgente", "version": "1.0"},
)

oni.handshake("business.chat")
chat = oni.chat("Hola, ¿qué servicios ofrecen?", intent="business.chat")
print(chat.get("reply", {}).get("text") if chat.get("reply") else chat)

# Si reply es null (dueño en modo humano):
# page = oni.poll_messages(timeout_ms=120_000)
```

## API

| Método | Descripción |
|--------|-------------|
| `ping()` | Discovery `GET /v1/ping/:pin` |
| `discover_from_url(url)` | `GET /v1/discover?url=` |
| `handshake(intent?, agent?)` | Handshake 0.2 |
| `catalog()` | Catálogo público |
| `chat(message, …)` | Chat; guarda `conversation_id` |
| `messages(…)` | Poll de mensajes |
| `poll_messages(…)` | Poll hasta bot/owner o timeout |
| `create_booking(**fields)` | Reserva |
| `create_order(**fields)` | Pedido |
| `reset()` | Nueva conversación local |

## Integraciones

- **LangChain / LlamaIndex:** ver `examples/langchain_tool.py` (tool HTTP)
- **n8n / Zapier / Power Automate:** HTTP Request a `https://onnivers.store/v1/...` — ver `examples/n8n_http.md`
- **MCP (Cursor/Claude):** `https://onnivers.store/mcp` (sin Python)

## Conformance

```bash
# Desde PyPI (venv limpio) contra producción
npm run smoke:sdk:py

# O con el checkout del monorepo
python packages/onipin-py/examples/prod_smoke.py
```

## Licencia

MIT — Empresa Tecnológica de Colombia / OnniVers
