vortelio 0.3.49__tar.gz

vortelio-0.3.49/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2024 Metiu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

vortelio-0.3.49/PKG-INFO

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: vortelio
+Version: 0.3.49
+Summary: Python SDK for Vortelio — run LLMs, images, audio, video & 3D locally. OpenAI & Ollama API compatible.
+Author: Vortelio Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/metiu1/Vortelio
+Project-URL: Repository, https://github.com/metiu1/Vortelio-python_libraries
+Project-URL: Bug Tracker, https://github.com/metiu1/Vortelio/issues
+Project-URL: Changelog, https://github.com/metiu1/Vortelio/blob/main/CHANGELOG.md
+Keywords: ai,llm,local-ai,local-llm,offline-ai,ollama,ollama-alternative,openai-compatible,stable-diffusion,flux,sdxl,image-generation,whisper,tts,stt,audio,video-generation,3d,llama-cpp,gguf,huggingface,rag,embeddings,multimodal,ai-agent,privacy,self-hosted,cuda,rocm,metal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8; extra == "async"
+Dynamic: license-file
+
+# Vortelio Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/vortelio.svg)](https://pypi.org/project/vortelio/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+
+Official Python client for [Vortelio](https://github.com/metiu1/Vortelio) — run LLMs, generate images, audio, video, and 3D models locally.
+
+Zero external dependencies. Fully OpenAI API and Ollama API compatible.
+
+```bash
+pip install vortelio
+```
+
+For async support:
+```bash
+pip install "vortelio[async]"   # adds aiohttp
+```
+
+---
+
+## Prerequisites
+
+Start the Vortelio server first:
+
+```bash
+vortelio serve          # default port 11500
+```
+
+Or let the SDK auto-start it:
+
+```python
+from vortelio import ensure_server
+ensure_server()          # finds and starts vortelio if installed
+```
+
+---
+
+## Quick Start
+
+```python
+from vortelio import Vortelio
+
+ai = Vortelio()          # connects to http://localhost:11500
+
+# Download a model
+ai.pull("llm/mistral:7b")
+
+# Chat — streams tokens to stdout, returns full reply
+reply = ai.chat("llm/mistral:7b", "What is quantum computing?")
+
+# Generator streaming
+for token in ai.chat_stream("llm/mistral:7b", "Tell me a story"):
+    print(token, end="", flush=True)
+print()
+```
+
+---
+
+## Chat & Conversations
+
+```python
+# Simple chat
+reply = ai.chat("llm/mistral:7b", "Hello!")
+
+# With messages list (Ollama/OpenAI format)
+reply = ai.chat("llm/mistral:7b", [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user",   "content": "What is 2 + 2?"},
+])
+
+# Stateful multi-turn conversation
+conv = ai.conversation("llm/mistral:7b", system="You are a pirate.")
+conv.say("What is your name?")
+reply = conv.say("Where do you sail?")
+
+# Streaming from a conversation
+for tok in conv.stream("Tell me about treasure"):
+    print(tok, end="", flush=True)
+```
+
+---
+
+## Generate (Ollama-style)
+
+```python
+# Non-streaming
+result = ai.generate("llm/mistral:7b", "The capital of France is")
+print(result["response"])
+
+# Streaming generator
+for tok in ai.generate_stream("llm/mistral:7b", "Count to 10"):
+    print(tok, end="", flush=True)
+
+# With options
+result = ai.generate(
+    "llm/mistral:7b",
+    "Explain photosynthesis",
+    system="You are a biology teacher.",
+    options={"temperature": 0.7, "num_ctx": 4096},
+    think=True,   # chain-of-thought with <think> models
+)
+print(result.get("thinking", ""))
+print(result["response"])
+```
+
+---
+
+## Embeddings
+
+```python
+# Batch embeddings
+vecs = ai.embed("llm/nomic-embed-text:latest", ["Hello", "World"])
+# → [[0.1, 0.2, ...], [0.3, 0.4, ...]]
+
+# Legacy single-prompt
+vec = ai.embeddings("llm/nomic-embed-text:latest", "Hello world")
+```
+
+---
+
+## RAG (Retrieval-Augmented Generation)
+
+```python
+# Ingest documents
+ai.rag_ingest(
+    "llm/nomic-embed-text:latest",
+    [
+        {"text": "Paris is the capital of France.", "meta": {"source": "facts"}},
+        {"text": "Berlin is the capital of Germany.", "meta": {"source": "facts"}},
+    ],
+    collection="my-docs",
+)
+
+# Query
+hits = ai.rag_query("llm/nomic-embed-text:latest", "capital of France", collection="my-docs")
+for h in hits["results"]:
+    print(f"[{h['score']:.3f}] {h['text']}")
+```
+
+---
+
+## Model Management
+
+```python
+ai.models()                         # list all downloaded models
+ai.pull("llm/llama3:8b")            # download from HuggingFace
+ai.show("llm/mistral:7b")           # model details, template, capabilities
+ai.delete("llm/old-model:latest")   # remove a model
+ai.copy("llm/mistral:7b", "llm/my-mistral:latest")  # duplicate
+ai.quantize("llm/mistral:7b", "q4_k_m")             # quantize
+ai.create("llm/my-model:latest", from_model="llm/mistral:7b",
+          system="You are a helpful assistant.")
+ai.ps()                             # currently loaded models
+ai.version()                        # server version
+```
+
+---
+
+## Media Generation
+
+```python
+# Image
+ai.image("image/sdxl:latest", "a red panda on the moon", "panda.png")
+
+# Or get bytes directly
+png_bytes = ai.generate_image("image/sdxl:latest", "sunset over mountains")
+
+# Audio (TTS / music)
+wav_bytes = ai.generate_audio("audio/kokoro:latest", "Hello, this is a test.")
+
+# Video
+mp4_bytes = ai.generate_video("video/wan2-1:latest", "a cat playing piano")
+
+# 3D
+obj_bytes = ai.generate_3d("3d/triposr:latest", "a wooden chair")
+```
+
+---
+
+## Advanced API
+
+```python
+# A/B compare models
+result = ai.compare(
+    ["llm/mistral:7b", "llm/llama3:8b"],
+    "Explain gravity in one sentence.",
+)
+for r in result["results"]:
+    print(f"{r['model']}: {r['response']}")
+
+# Structured JSON output
+result = ai.structured(
+    "llm/mistral:7b",
+    "List 3 programming languages",
+    schema={"type": "array", "items": {"type": "string"}},
+)
+print(result["parsed"])
+
+# Long-text summarization (map-reduce)
+summary = ai.summarize("llm/mistral:7b", very_long_text, style="bullets")
+print(summary["summary"])
+
+# Chain-of-thought
+result = ai.think("llm/qwq:32b", "Is 97 a prime number?")
+print("Reasoning:", result["thinking"])
+print("Answer:", result["answer"])
+
+# Smart model router
+best = ai.route("code", prompt="Write a sorting algorithm")
+print("Best model:", best["model"])
+```
+
+---
+
+## OpenAI-Compatible API
+
+```python
+# Drop-in OpenAI replacement
+response = ai.openai_chat(
+    "mistral:7b",
+    [{"role": "user", "content": "Hello!"}],
+    temperature=0.7,
+)
+print(response["choices"][0]["message"]["content"])
+
+# Streaming
+for tok in ai.openai_chat_stream("mistral:7b", [{"role":"user","content":"Hi"}]):
+    print(tok, end="", flush=True)
+
+# Embeddings (OpenAI format)
+result = ai.openai_embeddings("nomic-embed-text:latest", "Hello world")
+```
+
+---
+
+## Async Client
+
+```python
+import asyncio
+from vortelio import AsyncVortelio
+
+async def main():
+    ai = AsyncVortelio()
+
+    # All methods are async
+    reply = await ai.chat("llm/mistral:7b", "Hello!")
+
+    # Async streaming
+    async for tok in ai.chat_stream("llm/mistral:7b", "Tell me a joke"):
+        print(tok, end="", flush=True)
+
+    # Async conversation
+    conv = ai.conversation("llm/mistral:7b", system="You are helpful.")
+    reply = await conv.say("My name is Alice.")
+
+asyncio.run(main())
+```
+
+---
+
+## Agents
+
+```python
+# List available agents (Open WebUI, OpenClaw, CrewAI, AnythingLLM, ...)
+catalog = ai.agents_catalog()
+
+# Install and start an agent
+ai.agents_install("open-webui")
+ai.agents_start("open-webui")
+
+# Stop an agent
+ai.agents_stop("open-webui")
+```
+
+---
+
+## Webhooks & Audit
+
+```python
+# Register a webhook
+ai.hooks_create("https://my-server.com/webhook", event="generate")
+
+# List webhooks
+ai.hooks_list()
+
+# Audit log
+entries = ai.audit(limit=50)
+```
+
+---
+
+## GGUF Inspect & Ollama Import
+
+```python
+# Inspect a local GGUF file
+info = ai.gguf_inspect("/path/to/model.gguf")
+
+# Import models from a local Ollama installation
+ai.import_ollama()   # imports all
+ai.import_ollama(["mistral:7b", "llama3:8b"])  # selective
+```
+
+---
+
+## Custom Port / Remote Server
+
+```python
+ai = Vortelio(host="http://192.168.1.100", port=11500)
+ai = Vortelio(port=8080)               # local custom port
+ai = Vortelio(timeout=600)             # longer timeout for large models
+```
+
+---
+
+## Server Version Compatibility
+
+This SDK version **0.3.49** requires Vortelio server **≥ 0.3.38**.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

vortelio-0.3.49/README.md

@@ -0,0 +1,324 @@
+# Vortelio Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/vortelio.svg)](https://pypi.org/project/vortelio/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
+
+Official Python client for [Vortelio](https://github.com/metiu1/Vortelio) — run LLMs, generate images, audio, video, and 3D models locally.
+
+Zero external dependencies. Fully OpenAI API and Ollama API compatible.
+
+```bash
+pip install vortelio
+```
+
+For async support:
+```bash
+pip install "vortelio[async]"   # adds aiohttp
+```
+
+---
+
+## Prerequisites
+
+Start the Vortelio server first:
+
+```bash
+vortelio serve          # default port 11500
+```
+
+Or let the SDK auto-start it:
+
+```python
+from vortelio import ensure_server
+ensure_server()          # finds and starts vortelio if installed
+```
+
+---
+
+## Quick Start
+
+```python
+from vortelio import Vortelio
+
+ai = Vortelio()          # connects to http://localhost:11500
+
+# Download a model
+ai.pull("llm/mistral:7b")
+
+# Chat — streams tokens to stdout, returns full reply
+reply = ai.chat("llm/mistral:7b", "What is quantum computing?")
+
+# Generator streaming
+for token in ai.chat_stream("llm/mistral:7b", "Tell me a story"):
+    print(token, end="", flush=True)
+print()
+```
+
+---
+
+## Chat & Conversations
+
+```python
+# Simple chat
+reply = ai.chat("llm/mistral:7b", "Hello!")
+
+# With messages list (Ollama/OpenAI format)
+reply = ai.chat("llm/mistral:7b", [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user",   "content": "What is 2 + 2?"},
+])
+
+# Stateful multi-turn conversation
+conv = ai.conversation("llm/mistral:7b", system="You are a pirate.")
+conv.say("What is your name?")
+reply = conv.say("Where do you sail?")
+
+# Streaming from a conversation
+for tok in conv.stream("Tell me about treasure"):
+    print(tok, end="", flush=True)
+```
+
+---
+
+## Generate (Ollama-style)
+
+```python
+# Non-streaming
+result = ai.generate("llm/mistral:7b", "The capital of France is")
+print(result["response"])
+
+# Streaming generator
+for tok in ai.generate_stream("llm/mistral:7b", "Count to 10"):
+    print(tok, end="", flush=True)
+
+# With options
+result = ai.generate(
+    "llm/mistral:7b",
+    "Explain photosynthesis",
+    system="You are a biology teacher.",
+    options={"temperature": 0.7, "num_ctx": 4096},
+    think=True,   # chain-of-thought with <think> models
+)
+print(result.get("thinking", ""))
+print(result["response"])
+```
+
+---
+
+## Embeddings
+
+```python
+# Batch embeddings
+vecs = ai.embed("llm/nomic-embed-text:latest", ["Hello", "World"])
+# → [[0.1, 0.2, ...], [0.3, 0.4, ...]]
+
+# Legacy single-prompt
+vec = ai.embeddings("llm/nomic-embed-text:latest", "Hello world")
+```
+
+---
+
+## RAG (Retrieval-Augmented Generation)
+
+```python
+# Ingest documents
+ai.rag_ingest(
+    "llm/nomic-embed-text:latest",
+    [
+        {"text": "Paris is the capital of France.", "meta": {"source": "facts"}},
+        {"text": "Berlin is the capital of Germany.", "meta": {"source": "facts"}},
+    ],
+    collection="my-docs",
+)
+
+# Query
+hits = ai.rag_query("llm/nomic-embed-text:latest", "capital of France", collection="my-docs")
+for h in hits["results"]:
+    print(f"[{h['score']:.3f}] {h['text']}")
+```
+
+---
+
+## Model Management
+
+```python
+ai.models()                         # list all downloaded models
+ai.pull("llm/llama3:8b")            # download from HuggingFace
+ai.show("llm/mistral:7b")           # model details, template, capabilities
+ai.delete("llm/old-model:latest")   # remove a model
+ai.copy("llm/mistral:7b", "llm/my-mistral:latest")  # duplicate
+ai.quantize("llm/mistral:7b", "q4_k_m")             # quantize
+ai.create("llm/my-model:latest", from_model="llm/mistral:7b",
+          system="You are a helpful assistant.")
+ai.ps()                             # currently loaded models
+ai.version()                        # server version
+```
+
+---
+
+## Media Generation
+
+```python
+# Image
+ai.image("image/sdxl:latest", "a red panda on the moon", "panda.png")
+
+# Or get bytes directly
+png_bytes = ai.generate_image("image/sdxl:latest", "sunset over mountains")
+
+# Audio (TTS / music)
+wav_bytes = ai.generate_audio("audio/kokoro:latest", "Hello, this is a test.")
+
+# Video
+mp4_bytes = ai.generate_video("video/wan2-1:latest", "a cat playing piano")
+
+# 3D
+obj_bytes = ai.generate_3d("3d/triposr:latest", "a wooden chair")
+```
+
+---
+
+## Advanced API
+
+```python
+# A/B compare models
+result = ai.compare(
+    ["llm/mistral:7b", "llm/llama3:8b"],
+    "Explain gravity in one sentence.",
+)
+for r in result["results"]:
+    print(f"{r['model']}: {r['response']}")
+
+# Structured JSON output
+result = ai.structured(
+    "llm/mistral:7b",
+    "List 3 programming languages",
+    schema={"type": "array", "items": {"type": "string"}},
+)
+print(result["parsed"])
+
+# Long-text summarization (map-reduce)
+summary = ai.summarize("llm/mistral:7b", very_long_text, style="bullets")
+print(summary["summary"])
+
+# Chain-of-thought
+result = ai.think("llm/qwq:32b", "Is 97 a prime number?")
+print("Reasoning:", result["thinking"])
+print("Answer:", result["answer"])
+
+# Smart model router
+best = ai.route("code", prompt="Write a sorting algorithm")
+print("Best model:", best["model"])
+```
+
+---
+
+## OpenAI-Compatible API
+
+```python
+# Drop-in OpenAI replacement
+response = ai.openai_chat(
+    "mistral:7b",
+    [{"role": "user", "content": "Hello!"}],
+    temperature=0.7,
+)
+print(response["choices"][0]["message"]["content"])
+
+# Streaming
+for tok in ai.openai_chat_stream("mistral:7b", [{"role":"user","content":"Hi"}]):
+    print(tok, end="", flush=True)
+
+# Embeddings (OpenAI format)
+result = ai.openai_embeddings("nomic-embed-text:latest", "Hello world")
+```
+
+---
+
+## Async Client
+
+```python
+import asyncio
+from vortelio import AsyncVortelio
+
+async def main():
+    ai = AsyncVortelio()
+
+    # All methods are async
+    reply = await ai.chat("llm/mistral:7b", "Hello!")
+
+    # Async streaming
+    async for tok in ai.chat_stream("llm/mistral:7b", "Tell me a joke"):
+        print(tok, end="", flush=True)
+
+    # Async conversation
+    conv = ai.conversation("llm/mistral:7b", system="You are helpful.")
+    reply = await conv.say("My name is Alice.")
+
+asyncio.run(main())
+```
+
+---
+
+## Agents
+
+```python
+# List available agents (Open WebUI, OpenClaw, CrewAI, AnythingLLM, ...)
+catalog = ai.agents_catalog()
+
+# Install and start an agent
+ai.agents_install("open-webui")
+ai.agents_start("open-webui")
+
+# Stop an agent
+ai.agents_stop("open-webui")
+```
+
+---
+
+## Webhooks & Audit
+
+```python
+# Register a webhook
+ai.hooks_create("https://my-server.com/webhook", event="generate")
+
+# List webhooks
+ai.hooks_list()
+
+# Audit log
+entries = ai.audit(limit=50)
+```
+
+---
+
+## GGUF Inspect & Ollama Import
+
+```python
+# Inspect a local GGUF file
+info = ai.gguf_inspect("/path/to/model.gguf")
+
+# Import models from a local Ollama installation
+ai.import_ollama()   # imports all
+ai.import_ollama(["mistral:7b", "llama3:8b"])  # selective
+```
+
+---
+
+## Custom Port / Remote Server
+
+```python
+ai = Vortelio(host="http://192.168.1.100", port=11500)
+ai = Vortelio(port=8080)               # local custom port
+ai = Vortelio(timeout=600)             # longer timeout for large models
+```
+
+---
+
+## Server Version Compatibility
+
+This SDK version **0.3.49** requires Vortelio server **≥ 0.3.38**.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).