# lunaversex-genai
**LunaVerseX Generative AI SDK for Python**
SDK oficial de **LunaVerseX** para integrar capacidades de **IA generativa** en aplicaciones Python.
Provee interfaces simples para chat, streaming, manejo de modelos y utilidades relacionadas.
📚 Documentación completa: [docs.lunaversex.com/sdks/genai](https://docs.lunaversex.com/sdks/genai)
---
## 🚀 Instalación
```bash
pip install lunaversex-genai
```
---
## ✨ Características
* 🔹 **Chat conversacional** con soporte para múltiples modelos.
* 🔹 **Streaming de respuestas** para baja latencia.
* 🔹 **Gestión de modelos disponibles**.
* 🔹 **Generación de texto simple o con razonamiento**.
* 🔹 **Extracción de uso de tokens**.
* 🔹 **Tipado completo** con soporte `py.typed`.
---
## 🧪 Modelos disponibles
| Modelo | ID | Soporta Reasoning | Descripción |
| ------------ | ------------ | ----------------- | ---------------------------------------------------- |
| Lumi o1 Mini | lumi-o1-mini | ✅ Sí | Modelo compacto para tareas generales. |
| Lumi o1 | lumi-o1 | ❌ No | Modelo equilibrado para uso general. |
| Lumi o1 Pro | lumi-o1-pro | ❌ No | El modelo más creativo y sentimental. |
| Lumi o1 High | lumi-o1-high | ✅ Sí | Razonamiento profundo y rápido, código, matemáticas. |
| Lumi o3 | lumi-o3 | ✅ Sí (Nativo) | El modelo más avanzado de LunaVerseX. |
---
## 🧩 Funciones y Clases Exportadas
### Funciones Principales
* `genai.init(api_key: str, base_url: str = "https://api.lunaversex.com")`
Inicializa el SDK con la clave API.
* `genai.chat(messages: List[Message], options: ChatOptions) -> ChatResponse`
Envía un mensaje al modelo y recibe la respuesta completa.
* `genai.chatStream(messages: List[Message], options: ChatOptions) -> AsyncGenerator[StreamDelta, None]`
Envía un mensaje al modelo y recibe la respuesta en streaming.
* `genai.listModels() -> ModelsResponse`
Lista los modelos disponibles y sus características.
* `genai.generate(prompt: str, model: str = "lumi-o1") -> str`
Genera texto simple desde un prompt.
* `genai.generateWithReasoning(prompt: str, effort: str = "medium", model: str = "lumi-o1-mini") -> Tuple[str, Optional[Dict]]`
Genera texto incluyendo el proceso de razonamiento.
* `genai.tokens(response: ChatResponse) -> Usage`
Extrae información de tokens de una respuesta.
* `genai.close()`
Cierra las conexiones HTTP y libera recursos.
---
### Clases y Tipos de Datos
* `Message` – Representa un mensaje en la conversación.
* `ChatOptions` – Configuraciones para una petición de chat.
* `ChatResponse` – Respuesta completa de un chat.
* `StreamDelta` – Fragmentos recibidos durante el streaming.
* `Model` – Información de un modelo.
* `ModelsResponse` – Contenedor con todos los modelos disponibles.
* `ReasoningConfig` – Configuración de razonamiento para modelos.
* `ToolFunction` – Definición de función/herramienta para el modelo.
* `FileAttachment` – Archivos adjuntos a un mensaje.
* `Usage` – Información de uso de tokens.
* `ChatChoice` – Elección individual dentro de la respuesta de chat.
### Excepciones
* `LunaVerseXError` – Clase base para errores del SDK.
* `APIError` – Errores relacionados con solicitudes HTTP o la API.
* `ValidationError` – Error de validación en parámetros.
* `ConfigurationError` – Error de configuración del SDK.
* `ModelNotFoundError` – Modelo no encontrado o inválido.
---
## 🔧 Uso básico
### Configuración global
```python
from lunaversex-genai import genai
genai.init(api_key="your-api-key")
```
### Chat básico
```python
import asyncio
from lunaversex-genai import genai, Message, ChatOptions
genai.init(api_key="your-api-key")
async def run_chat():
messages = [Message(role="user", content="Hola")]
options = ChatOptions(model="lumi-o1")
response = await genai.chat(messages, options)
print("Respuesta:", response.choices[0].message.content)
await genai.close()
asyncio.run(run_chat())
```
### Streaming de chat
```python
import asyncio
from lunaversex-genai import genai, Message, ChatOptions
genai.init(api_key="your-api-key")
async def run_stream():
messages = [Message(role="user", content="Cuéntame una historia corta")]
options = ChatOptions(model="lumi-o1-mini")
async for delta in genai.chatStream(messages, options):
if delta.type == "delta" and delta.content:
print(delta.content, end="")
elif delta.type == "end":
print("\n[Fin del stream]")
await genai.close()
asyncio.run(run_stream())
```
---
## 🔐 Seguridad
* **Nunca incluyas tu API Key directamente en el código fuente.**
* Usá variables de entorno (`os.environ["LUNAVERSEX_API_KEY"]`).
* El SDK no guarda ni expone claves sensibles.
---
## 📜 Licencia
Este proyecto está bajo licencia [Apache-2.0](LICENSE).
---
## 🧑💻 Autor
Desarrollado por **[LunaVerseX](https://www.lunaversex.com)**.
Mantenido por **[Joaco Heredia](https://github.com/joaco-heredia)**.
---
## 📈 Changelog
### v1.0.0 (2025-08-18)
* 🎉 Lanzamiento inicial del SDK Python.
* ✅ Implementación completa de `genai` con chat, streaming, manejo de modelos, generación con razonamiento y tokenización.
* 📝 Documentación inicial con ejemplos de uso.
Raw data
{
"_id": null,
"home_page": null,
"name": "lunaversex-genai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Joaco Heredia <joaco@lunaversex.com>",
"keywords": "ai, sdk, lunaversex, generative-ai, chat, llm, reasoning, tools",
"author": null,
"author_email": "LunaVerseX <support@lunaversex.com>, Joaco Heredia <joaco@lunaversex.com>",
"download_url": "https://files.pythonhosted.org/packages/67/ed/8cf03527c9481c0c5a507cc124d5dc7ab4f36f4463bce8cc3db5c5770ed5/lunaversex_genai-1.0.1.tar.gz",
"platform": null,
"description": "# lunaversex-genai\r\n\r\n\r\n\r\n\r\n\r\n**LunaVerseX Generative AI SDK for Python**\r\n\r\nSDK oficial de **LunaVerseX** para integrar capacidades de **IA generativa** en aplicaciones Python.\r\nProvee interfaces simples para chat, streaming, manejo de modelos y utilidades relacionadas.\r\n\r\n\ud83d\udcda Documentaci\u00f3n completa: [docs.lunaversex.com/sdks/genai](https://docs.lunaversex.com/sdks/genai)\r\n\r\n---\r\n\r\n## \ud83d\ude80 Instalaci\u00f3n\r\n\r\n```bash\r\npip install lunaversex-genai\r\n```\r\n\r\n---\r\n\r\n## \u2728 Caracter\u00edsticas\r\n\r\n* \ud83d\udd39 **Chat conversacional** con soporte para m\u00faltiples modelos.\r\n* \ud83d\udd39 **Streaming de respuestas** para baja latencia.\r\n* \ud83d\udd39 **Gesti\u00f3n de modelos disponibles**.\r\n* \ud83d\udd39 **Generaci\u00f3n de texto simple o con razonamiento**.\r\n* \ud83d\udd39 **Extracci\u00f3n de uso de tokens**.\r\n* \ud83d\udd39 **Tipado completo** con soporte `py.typed`.\r\n\r\n---\r\n\r\n## \ud83e\uddea Modelos disponibles\r\n\r\n| Modelo | ID | Soporta Reasoning | Descripci\u00f3n |\r\n| ------------ | ------------ | ----------------- | ---------------------------------------------------- |\r\n| Lumi o1 Mini | lumi-o1-mini | \u2705 S\u00ed | Modelo compacto para tareas generales. |\r\n| Lumi o1 | lumi-o1 | \u274c No | Modelo equilibrado para uso general. |\r\n| Lumi o1 Pro | lumi-o1-pro | \u274c No | El modelo m\u00e1s creativo y sentimental. |\r\n| Lumi o1 High | lumi-o1-high | \u2705 S\u00ed | Razonamiento profundo y r\u00e1pido, c\u00f3digo, matem\u00e1ticas. |\r\n| Lumi o3 | lumi-o3 | \u2705 S\u00ed (Nativo) | El modelo m\u00e1s avanzado de LunaVerseX. |\r\n\r\n---\r\n\r\n## \ud83e\udde9 Funciones y Clases Exportadas\r\n\r\n### Funciones Principales\r\n\r\n* `genai.init(api_key: str, base_url: str = \"https://api.lunaversex.com\")`\r\n Inicializa el SDK con la clave API.\r\n\r\n* `genai.chat(messages: List[Message], options: ChatOptions) -> ChatResponse`\r\n Env\u00eda un mensaje al modelo y recibe la respuesta completa.\r\n\r\n* `genai.chatStream(messages: List[Message], options: ChatOptions) -> AsyncGenerator[StreamDelta, None]`\r\n Env\u00eda un mensaje al modelo y recibe la respuesta en streaming.\r\n\r\n* `genai.listModels() -> ModelsResponse`\r\n Lista los modelos disponibles y sus caracter\u00edsticas.\r\n\r\n* `genai.generate(prompt: str, model: str = \"lumi-o1\") -> str`\r\n Genera texto simple desde un prompt.\r\n\r\n* `genai.generateWithReasoning(prompt: str, effort: str = \"medium\", model: str = \"lumi-o1-mini\") -> Tuple[str, Optional[Dict]]`\r\n Genera texto incluyendo el proceso de razonamiento.\r\n\r\n* `genai.tokens(response: ChatResponse) -> Usage`\r\n Extrae informaci\u00f3n de tokens de una respuesta.\r\n\r\n* `genai.close()`\r\n Cierra las conexiones HTTP y libera recursos.\r\n\r\n---\r\n\r\n### Clases y Tipos de Datos\r\n\r\n* `Message` \u2013 Representa un mensaje en la conversaci\u00f3n.\r\n* `ChatOptions` \u2013 Configuraciones para una petici\u00f3n de chat.\r\n* `ChatResponse` \u2013 Respuesta completa de un chat.\r\n* `StreamDelta` \u2013 Fragmentos recibidos durante el streaming.\r\n* `Model` \u2013 Informaci\u00f3n de un modelo.\r\n* `ModelsResponse` \u2013 Contenedor con todos los modelos disponibles.\r\n* `ReasoningConfig` \u2013 Configuraci\u00f3n de razonamiento para modelos.\r\n* `ToolFunction` \u2013 Definici\u00f3n de funci\u00f3n/herramienta para el modelo.\r\n* `FileAttachment` \u2013 Archivos adjuntos a un mensaje.\r\n* `Usage` \u2013 Informaci\u00f3n de uso de tokens.\r\n* `ChatChoice` \u2013 Elecci\u00f3n individual dentro de la respuesta de chat.\r\n\r\n### Excepciones\r\n\r\n* `LunaVerseXError` \u2013 Clase base para errores del SDK.\r\n* `APIError` \u2013 Errores relacionados con solicitudes HTTP o la API.\r\n* `ValidationError` \u2013 Error de validaci\u00f3n en par\u00e1metros.\r\n* `ConfigurationError` \u2013 Error de configuraci\u00f3n del SDK.\r\n* `ModelNotFoundError` \u2013 Modelo no encontrado o inv\u00e1lido.\r\n\r\n---\r\n\r\n## \ud83d\udd27 Uso b\u00e1sico\r\n\r\n### Configuraci\u00f3n global\r\n\r\n```python\r\nfrom lunaversex-genai import genai\r\n\r\ngenai.init(api_key=\"your-api-key\")\r\n```\r\n\r\n### Chat b\u00e1sico\r\n\r\n```python\r\nimport asyncio\r\nfrom lunaversex-genai import genai, Message, ChatOptions\r\ngenai.init(api_key=\"your-api-key\")\r\n\r\nasync def run_chat():\r\n messages = [Message(role=\"user\", content=\"Hola\")]\r\n options = ChatOptions(model=\"lumi-o1\")\r\n\r\n response = await genai.chat(messages, options)\r\n print(\"Respuesta:\", response.choices[0].message.content)\r\n\r\n await genai.close()\r\n\r\nasyncio.run(run_chat())\r\n```\r\n\r\n### Streaming de chat\r\n\r\n```python\r\nimport asyncio\r\nfrom lunaversex-genai import genai, Message, ChatOptions\r\ngenai.init(api_key=\"your-api-key\")\r\nasync def run_stream():\r\n messages = [Message(role=\"user\", content=\"Cu\u00e9ntame una historia corta\")]\r\n options = ChatOptions(model=\"lumi-o1-mini\")\r\n\r\n async for delta in genai.chatStream(messages, options):\r\n if delta.type == \"delta\" and delta.content:\r\n print(delta.content, end=\"\")\r\n elif delta.type == \"end\":\r\n print(\"\\n[Fin del stream]\")\r\n\r\n await genai.close()\r\n\r\nasyncio.run(run_stream())\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udd10 Seguridad\r\n\r\n* **Nunca incluyas tu API Key directamente en el c\u00f3digo fuente.**\r\n* Us\u00e1 variables de entorno (`os.environ[\"LUNAVERSEX_API_KEY\"]`).\r\n* El SDK no guarda ni expone claves sensibles.\r\n\r\n---\r\n\r\n## \ud83d\udcdc Licencia\r\n\r\nEste proyecto est\u00e1 bajo licencia [Apache-2.0](LICENSE).\r\n\r\n---\r\n\r\n## \ud83e\uddd1\u200d\ud83d\udcbb Autor\r\n\r\nDesarrollado por **[LunaVerseX](https://www.lunaversex.com)**.\r\nMantenido por **[Joaco Heredia](https://github.com/joaco-heredia)**.\r\n\r\n---\r\n\r\n## \ud83d\udcc8 Changelog\r\n\r\n### v1.0.0 (2025-08-18)\r\n\r\n* \ud83c\udf89 Lanzamiento inicial del SDK Python.\r\n* \u2705 Implementaci\u00f3n completa de `genai` con chat, streaming, manejo de modelos, generaci\u00f3n con razonamiento y tokenizaci\u00f3n.\r\n* \ud83d\udcdd Documentaci\u00f3n inicial con ejemplos de uso.\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "LunaVerseX Generative AI SDK for Python",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/lunaversex/genai-python/blob/main/CHANGELOG.md",
"Documentation": "https://docs.lunaversex.com/sdks/genai",
"Homepage": "https://www.lunaversex.com",
"Issues": "https://github.com/lunaversex/genai-python/issues",
"Repository": "https://github.com/lunaversex/genai-python"
},
"split_keywords": [
"ai",
" sdk",
" lunaversex",
" generative-ai",
" chat",
" llm",
" reasoning",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "61509ba15fa26f85c1f6d8fb3e5f3af482161f76cb9ea273ab16e52a0d843104",
"md5": "b6aa4652da708505abb35e2262ebf58e",
"sha256": "927b3c73b5f075895d70297aed4bc6ff046f89af9d346a8b5e83da70310562e9"
},
"downloads": -1,
"filename": "lunaversex_genai-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b6aa4652da708505abb35e2262ebf58e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11406,
"upload_time": "2025-08-19T01:13:30",
"upload_time_iso_8601": "2025-08-19T01:13:30.208847Z",
"url": "https://files.pythonhosted.org/packages/61/50/9ba15fa26f85c1f6d8fb3e5f3af482161f76cb9ea273ab16e52a0d843104/lunaversex_genai-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "67ed8cf03527c9481c0c5a507cc124d5dc7ab4f36f4463bce8cc3db5c5770ed5",
"md5": "6a89f02b0a5e06a5ce7a82a57b17e075",
"sha256": "5f87749b5287d93964e69034c498cba92e12fa05d7323c79749f5825c777d1c3"
},
"downloads": -1,
"filename": "lunaversex_genai-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6a89f02b0a5e06a5ce7a82a57b17e075",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13098,
"upload_time": "2025-08-19T01:13:31",
"upload_time_iso_8601": "2025-08-19T01:13:31.985749Z",
"url": "https://files.pythonhosted.org/packages/67/ed/8cf03527c9481c0c5a507cc124d5dc7ab4f36f4463bce8cc3db5c5770ed5/lunaversex_genai-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 01:13:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lunaversex",
"github_project": "genai-python",
"github_not_found": true,
"lcname": "lunaversex-genai"
}
JSON
