pullai 0.3.5__tar.gz

pullai-0.3.5/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: pullai
+Version: 0.3.5
+Summary: Python SDK for PullAI — run AI models locally
+Author: Metiu
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/pullai/pullai
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PullAI Python SDK
+
+```bash
+pip install pullai
+```
+
+Requires the server running: `pullai serve`
+
+---
+
+## Quick start
+
+```python
+from pullai import PullAI
+
+ai = PullAI()
+
+# List installed models
+ai.models()
+
+# Single message (streaming)
+ai.chat("llm/mistral:7b", "What is Python?")
+
+# Multi-turn conversation (model remembers everything)
+conv = ai.conversation("llm/mistral:7b")
+conv.say("My name is Marco and I love Python.")
+conv.say("What is my name?")        # → "Your name is Marco."
+conv.say("What language do I love?") # → "You love Python."
+conv.clear()                         # wipe memory, start fresh
+
+# Generate an image
+ai.image("image/sdxl", "an astronaut cat on Mars", "cat.png")
+
+# Transcribe audio
+ai.transcribe("audio/whisper:large", "meeting.mp3")
+
+# Text to speech
+ai.speak("audio/kokoro", "Hello!", "hello.wav")
+
+# Generate a video
+ai.video("video/cogvideo:5b", "a panda running", "panda.mp4")
+
+# Generate a 3D model from text
+ai.model3d("3d/shap-e", "chair.ply", description="a wooden chair")
+
+# Generate a 3D model from image
+ai.model3d("3d/triposr", "chair.obj", image="photo.jpg")
+```
+
+---
+
+## License
+
+Apache-2.0 © Metiu — PullAI Contributors

pullai-0.3.5/README.md

@@ -0,0 +1,54 @@
+# PullAI Python SDK
+
+```bash
+pip install pullai
+```
+
+Requires the server running: `pullai serve`
+
+---
+
+## Quick start
+
+```python
+from pullai import PullAI
+
+ai = PullAI()
+
+# List installed models
+ai.models()
+
+# Single message (streaming)
+ai.chat("llm/mistral:7b", "What is Python?")
+
+# Multi-turn conversation (model remembers everything)
+conv = ai.conversation("llm/mistral:7b")
+conv.say("My name is Marco and I love Python.")
+conv.say("What is my name?")        # → "Your name is Marco."
+conv.say("What language do I love?") # → "You love Python."
+conv.clear()                         # wipe memory, start fresh
+
+# Generate an image
+ai.image("image/sdxl", "an astronaut cat on Mars", "cat.png")
+
+# Transcribe audio
+ai.transcribe("audio/whisper:large", "meeting.mp3")
+
+# Text to speech
+ai.speak("audio/kokoro", "Hello!", "hello.wav")
+
+# Generate a video
+ai.video("video/cogvideo:5b", "a panda running", "panda.mp4")
+
+# Generate a 3D model from text
+ai.model3d("3d/shap-e", "chair.ply", description="a wooden chair")
+
+# Generate a 3D model from image
+ai.model3d("3d/triposr", "chair.obj", image="photo.jpg")
+```
+
+---
+
+## License
+
+Apache-2.0 © Metiu — PullAI Contributors

pullai-0.3.5/pullai/__init__.py

@@ -0,0 +1,4 @@
+from .client import PullAI, Conversation
+
+__version__ = "0.3.5"
+__all__ = ["PullAI", "Conversation"]

pullai-0.3.5/pullai/client.py

@@ -0,0 +1,519 @@
+"""
+PullAI Python SDK
+Requires the server to be running: pullai serve
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import urllib.request
+import urllib.error
+from pathlib import Path
+from typing import List, Optional
+
+
+class PullAI:
+    """
+    Python client for PullAI — run AI models locally.
+
+    Start the server first with:  pullai serve
+
+    Example:
+        ai = PullAI()
+        ai.models()
+        ai.chat("llm/mistral:7b", "Hello!")
+    """
+
+    def __init__(self, port: int = 11500) -> None:
+        """
+        Create the PullAI client.
+
+        Args:
+            port (int): Port of the PullAI server. Default is 11500.
+                        Start the server with: pullai serve --port 11500
+
+        Example:
+            ai = PullAI()           # default port 11500
+            ai = PullAI(port=8080)  # custom port
+        """
+        self._base: str = f"http://127.0.0.1:{port}"
+
+    # ──────────────────────────────────────────────────────────────────────
+    # MODELS
+    # ──────────────────────────────────────────────────────────────────────
+
+    def models(self) -> None:
+        """
+        Print a table of all locally installed models.
+
+        No arguments needed. Shows name, size and format of every
+        downloaded model.
+
+        Example:
+            ai.models()
+
+            # Output:
+            # 📦  3 models installed
+            # ──────────────────────────────────────────────────
+            #   1   llm/mistral:7b           4.1 GB   gguf
+            #   2   image/sdxl:latest        6.5 GB   gguf
+            #   3   audio/whisper:large      1.5 GB   safetensors
+        """
+        response: dict = self._get("/api/models")
+        items: List[dict] = response.get("models") or []
+
+        if not items:
+            print("No models installed.")
+            print("Download one with:  pullai pull llm/mistral:7b")
+            return
+
+        print(f"\n📦  {len(items)} model{'s' if len(items) != 1 else ''} installed")
+        print("─" * 50)
+        for i, m in enumerate(items, 1):
+            ref:  str = f"{m.get('type','?')}/{m.get('name','?')}:{m.get('tag','?')}"
+            size: str = _human_size(m.get("size_bytes", 0))
+            fmt:  str = m.get("format", "")
+            print(f"  {i:<3} {ref:<32} {size:>8}   {fmt}")
+        print()
+
+    # ──────────────────────────────────────────────────────────────────────
+    # CHAT — single message
+    # ──────────────────────────────────────────────────────────────────────
+
+    def chat(self, model: str, message: str) -> str:
+        """
+        Send a single message to a language model and get a reply.
+
+        Tokens are printed in real time as the model generates them
+        (streaming), just like ChatGPT.
+
+        For a multi-turn conversation where the model remembers previous
+        messages, use conversation() instead.
+
+        Args:
+            model   (str): The model to use.
+                           Examples: "llm/mistral:7b"
+                                     "llm/llama3:8b"
+                                     "llm/phi3:mini"
+                                     "llm/qwen:0.5b"
+            message (str): The text to send to the model.
+
+        Returns:
+            str: The full reply as a string.
+
+        Example:
+            ai.chat("llm/mistral:7b", "What is Python?")
+            ai.chat("llm/phi3:mini",  "Write a poem about the sea")
+            ai.chat("llm/llama3:8b",  "Translate to Italian: Hello world")
+        """
+        return self._stream(model, [{"role": "user", "content": message}])
+
+    # ──────────────────────────────────────────────────────────────────────
+    # CONVERSATION — multi-turn chat with memory
+    # ──────────────────────────────────────────────────────────────────────
+
+    def conversation(
+        self,
+        model: str,
+        system: str = "You are a helpful assistant.",
+    ) -> "Conversation":
+        """
+        Start a multi-turn conversation with a language model.
+
+        Unlike chat(), the model remembers everything said so far.
+        You can keep talking back and forth without starting over.
+
+        Args:
+            model  (str): The model to use.
+                          Examples: "llm/mistral:7b"
+                                    "llm/llama3:8b"
+                                    "llm/phi3:mini"
+            system (str): Instructions that define how the model behaves.
+                          Sent once at the start and never changes.
+                          Default: "You are a helpful assistant."
+                          Examples:
+                            "You are a Python expert. Answer only with code."
+                            "You are a translator. Translate everything to French."
+                            "You are a friendly tutor explaining things simply."
+
+        Returns:
+            Conversation: An object with a .say() method to send messages.
+
+        Example:
+            conv = ai.conversation("llm/mistral:7b")
+            conv.say("My name is Marco.")
+            conv.say("What is my name?")    # model remembers: "Your name is Marco."
+            conv.say("Tell me a joke.")
+
+            # Custom personality
+            conv = ai.conversation(
+                "llm/mistral:7b",
+                system="You are a sarcastic assistant who answers very briefly."
+            )
+            conv.say("What is 2 + 2?")
+        """
+        return Conversation(model=model, system=system, client=self)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # IMAGE
+    # ──────────────────────────────────────────────────────────────────────
+
+    def image(
+        self,
+        model: str,
+        description: str,
+        save_to: str,
+        steps: int = 20,
+    ) -> None:
+        """
+        Generate an image from a text description and save it to a file.
+
+        Args:
+            model       (str): The model to use.
+                               Examples: "image/sdxl"
+                                         "image/flux:schnell"
+                                         "image/openjourney"
+                                         "image/dreamshaper"
+            description (str): What the image should contain.
+                               Example: "an astronaut cat on Mars, digital art"
+            save_to     (str): Path where the image will be saved (.png).
+                               Example: "cat.png"
+            steps       (int): Generation steps. Default 20.
+                               More steps = better quality but slower.
+                               Recommended: 20 (fast) · 30 (good) · 50 (best)
+
+        Example:
+            ai.image("image/sdxl", "a purple sunset over the ocean", "sunset.png")
+            ai.image("image/flux:schnell", "medieval castle", "castle.png", steps=30)
+        """
+        self._generate_media(model, prompt=description, output=save_to, steps=steps)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # TRANSCRIBE
+    # ──────────────────────────────────────────────────────────────────────
+
+    def transcribe(
+        self,
+        model: str,
+        audio_file: str,
+        save_to: Optional[str] = None,
+    ) -> str:
+        """
+        Transcribe an audio file to text (Speech-to-Text) using Whisper.
+
+        Args:
+            model      (str):           The Whisper model to use.
+                                        Examples: "audio/whisper:large"  (most accurate)
+                                                  "audio/whisper:base"   (faster)
+            audio_file (str):           Path to the audio file to transcribe.
+                                        Supported: .mp3  .wav  .flac  .m4a  .ogg
+                                        Example: "meeting.mp3"
+            save_to    (str, optional): Path to save the transcription as .txt.
+                                        If not given, text is only returned.
+                                        Example: "transcript.txt"
+
+        Returns:
+            str: The transcribed text.
+
+        Example:
+            text = ai.transcribe("audio/whisper:large", "meeting.mp3")
+            ai.transcribe("audio/whisper:base", "note.wav", save_to="note.txt")
+        """
+        return self._generate_media(model, input_file=audio_file, output=save_to)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # SPEAK
+    # ──────────────────────────────────────────────────────────────────────
+
+    def speak(
+        self,
+        model: str,
+        text: str,
+        save_to: str,
+    ) -> None:
+        """
+        Convert text to speech and save the audio as a .wav file.
+
+        Args:
+            model   (str): The TTS engine to use.
+                           Examples: "audio/kokoro"  (high quality, recommended)
+                                     "audio/bark"    (very expressive, slower)
+            text    (str): The text to convert to speech.
+                           Example: "Hello! I am PullAI, your local AI assistant."
+            save_to (str): Path where the audio file will be saved (.wav).
+                           Example: "greeting.wav"
+
+        Example:
+            ai.speak("audio/kokoro", "Good morning!", "morning.wav")
+            ai.speak("audio/bark",   "Hello everyone!", "hello.wav")
+        """
+        self._generate_media(model, prompt=text, output=save_to)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # VIDEO
+    # ──────────────────────────────────────────────────────────────────────
+
+    def video(
+        self,
+        model: str,
+        description: str,
+        save_to: str,
+        steps: int = 20,
+    ) -> None:
+        """
+        Generate a video from a text description and save it as .mp4.
+
+        Warning: video generation can take several minutes even with a GPU.
+
+        Args:
+            model       (str): The model to use.
+                               Examples: "video/cogvideo:5b"     (high quality)
+                                         "video/animatediff:v3"  (faster)
+            description (str): What the video should show.
+                               Example: "a panda eating bamboo in the forest"
+            save_to     (str): Path where the video will be saved (.mp4).
+                               Example: "panda.mp4"
+            steps       (int): Generation steps. Default 20.
+                               More steps = better quality but slower.
+
+        Example:
+            ai.video("video/cogvideo:5b", "a horse galloping", "horse.mp4")
+            ai.video("video/animatediff:v3", "ocean waves", "ocean.mp4", steps=30)
+        """
+        self._generate_media(model, prompt=description, output=save_to, steps=steps)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # MODEL 3D
+    # ──────────────────────────────────────────────────────────────────────
+
+    def model3d(
+        self,
+        model: str,
+        save_to: str,
+        description: Optional[str] = None,
+        image: Optional[str] = None,
+    ) -> None:
+        """
+        Generate a 3D model from text or from an image.
+
+        You must provide at least one of 'description' or 'image'.
+
+        Args:
+            model       (str):           The 3D model to use.
+                                         Examples: "3d/triposr"  (image → 3D, fast)
+                                                   "3d/shap-e"   (text → 3D, OpenAI)
+                                                   "3d/lgm"      (image → 3D, quality)
+                                                   "3d/trellis"  (text/image, Microsoft)
+            save_to     (str):           Path where the 3D model will be saved.
+                                         .obj → TripoSR
+                                         .ply → Shap-E, LGM
+                                         .glb → TRELLIS
+                                         Example: "chair.obj"
+            description (str, optional): Text description of the object.
+                                         Example: "a wooden chair with four legs"
+            image       (str, optional): Path to a photo of the object.
+                                         Best with plain white background.
+                                         Example: "chair.jpg"
+
+        Example:
+            # From text
+            ai.model3d("3d/shap-e",  "chair.ply", description="a wooden chair")
+
+            # From image
+            ai.model3d("3d/triposr", "chair.obj", image="photo.jpg")
+        """
+        if not description and not image:
+            raise ValueError("Provide at least 'description' or 'image'.")
+        self._generate_media(model, prompt=description or "", input_file=image, output=save_to)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # INTERNALS
+    # ──────────────────────────────────────────────────────────────────────
+
+    def _stream(self, model: str, messages: List[dict]) -> str:
+        prompt: str = "\n".join(
+            f"[{m['role'].capitalize()}]: {m['content']}" for m in messages
+        )
+        body: bytes = json.dumps({
+            "model": model, "prompt": prompt, "stream": True,
+        }).encode()
+        req = urllib.request.Request(
+            f"{self._base}/api/generate", data=body,
+            method="POST", headers={"Content-Type": "application/json"},
+        )
+        tokens: List[str] = []
+        try:
+            with urllib.request.urlopen(req, timeout=600) as resp:
+                for raw in resp:
+                    line: str = raw.decode("utf-8").rstrip("\n\r")
+                    if not line.startswith("data: "):
+                        continue
+                    payload: str = line[6:]
+                    if payload == "[DONE]":
+                        break
+                    if payload.startswith("[ERROR]"):
+                        raise RuntimeError(payload[8:])
+                    print(payload, end="", flush=True)
+                    tokens.append(payload)
+        except urllib.error.URLError as exc:
+            raise ConnectionError(
+                f"PullAI server not reachable at {self._base}\n"
+                "Start it with: pullai serve"
+            ) from exc
+        print()
+        return "".join(tokens)
+
+    def _generate_media(
+        self,
+        model: str,
+        prompt: str = "",
+        input_file: Optional[str] = None,
+        output: Optional[str] = None,
+        steps: int = 20,
+    ) -> str:
+        body: bytes = json.dumps({
+            "model":       model,
+            "prompt":      prompt,
+            "input_file":  str(input_file) if input_file else "",
+            "output_file": str(output) if output else "",
+            "steps":       steps,
+        }).encode()
+        req = urllib.request.Request(
+            f"{self._base}/api/generate", data=body,
+            method="POST", headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=900) as resp:
+                data: dict = json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            msg: str = json.loads(exc.read()).get("error", str(exc))
+            raise RuntimeError(msg) from exc
+        except urllib.error.URLError as exc:
+            raise ConnectionError(
+                f"PullAI server not reachable at {self._base}\n"
+                "Start it with: pullai serve"
+            ) from exc
+
+        if "error" in data:
+            raise RuntimeError(data["error"])
+
+        if data.get("data") and output:
+            Path(output).write_bytes(base64.b64decode(data["data"]))
+            print(f"✅  Saved to: {output}")
+            return str(output)
+
+        if data.get("data"):
+            return base64.b64decode(data["data"]).decode("utf-8", errors="replace")
+
+        return data.get("saved_to", "")
+
+    def _get(self, path: str) -> dict:
+        try:
+            with urllib.request.urlopen(f"{self._base}{path}", timeout=10) as r:
+                return json.loads(r.read())  # type: ignore[no-any-return]
+        except urllib.error.URLError as exc:
+            raise ConnectionError(
+                f"PullAI server not reachable at {self._base}\n"
+                "Start it with: pullai serve"
+            ) from exc
+
+    def __repr__(self) -> str:
+        return f"<PullAI {self._base}>"
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# CONVERSATION
+# ──────────────────────────────────────────────────────────────────────────────
+
+class Conversation:
+    """
+    A multi-turn conversation with a language model.
+
+    The model remembers every message sent so far, so you can talk
+    back and forth naturally without repeating context.
+
+    Do not create this class directly — use ai.conversation() instead.
+
+    Example:
+        conv = ai.conversation("llm/mistral:7b")
+        conv.say("My name is Marco and I love Python.")
+        conv.say("What is my name?")         # → "Your name is Marco."
+        conv.say("What language do I love?") # → "You love Python."
+        conv.clear()                          # wipe history, start fresh
+    """
+
+    def __init__(self, model: str, system: str, client: "PullAI") -> None:
+        self._model:   str        = model
+        self._client:  PullAI     = client
+        self._history: List[dict] = [{"role": "system", "content": system}]
+
+    def say(self, message: str) -> str:
+        """
+        Send a message and get a reply. The full history is remembered automatically.
+
+        The model sees every previous message in the conversation, so it
+        can refer back to anything said earlier.
+
+        Args:
+            message (str): The message to send to the model.
+
+        Returns:
+            str: The model's reply. Also printed in real time as tokens stream in.
+
+        Example:
+            conv = ai.conversation("llm/mistral:7b")
+
+            conv.say("My favourite colour is blue.")
+            conv.say("What is my favourite colour?")  # → "Your favourite colour is blue."
+            conv.say("Why did I mention it?")          # → model refers back to context
+        """
+        self._history.append({"role": "user", "content": message})
+        reply: str = self._client._stream(self._model, self._history)
+        self._history.append({"role": "assistant", "content": reply})
+        return reply
+
+    def clear(self) -> None:
+        """
+        Wipe the conversation history and start fresh.
+
+        The system prompt is kept, but all previous messages
+        (both yours and the model's replies) are deleted.
+
+        Example:
+            conv.say("My name is Marco.")
+            conv.clear()
+            conv.say("What is my name?")  # model no longer knows
+        """
+        system: dict = self._history[0]
+        self._history = [system]
+
+    def history(self) -> List[dict]:
+        """
+        Return the full conversation history as a list of messages.
+
+        Each message is a dict with 'role' and 'content'.
+        Roles: 'system', 'user', 'assistant'.
+
+        Returns:
+            List[dict]: All messages, ordered from oldest to newest.
+
+        Example:
+            for msg in conv.history():
+                print(f"{msg['role']}: {msg['content']}")
+        """
+        return list(self._history)
+
+    def __repr__(self) -> str:
+        turns: int = (len(self._history) - 1) // 2
+        return f"<Conversation model={self._model!r} turns={turns}>"
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _human_size(b: int) -> str:
+    if b >= 1_000_000_000:
+        return f"{b / 1e9:.1f} GB"
+    if b >= 1_000_000:
+        return f"{b / 1e6:.0f} MB"
+    return f"{b / 1e3:.0f} KB"

pullai-0.3.5/pullai.egg-info/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: pullai
+Version: 0.3.5
+Summary: Python SDK for PullAI — run AI models locally
+Author: Metiu
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/pullai/pullai
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PullAI Python SDK
+
+```bash
+pip install pullai
+```
+
+Requires the server running: `pullai serve`
+
+---
+
+## Quick start
+
+```python
+from pullai import PullAI
+
+ai = PullAI()
+
+# List installed models
+ai.models()
+
+# Single message (streaming)
+ai.chat("llm/mistral:7b", "What is Python?")
+
+# Multi-turn conversation (model remembers everything)
+conv = ai.conversation("llm/mistral:7b")
+conv.say("My name is Marco and I love Python.")
+conv.say("What is my name?")        # → "Your name is Marco."
+conv.say("What language do I love?") # → "You love Python."
+conv.clear()                         # wipe memory, start fresh
+
+# Generate an image
+ai.image("image/sdxl", "an astronaut cat on Mars", "cat.png")
+
+# Transcribe audio
+ai.transcribe("audio/whisper:large", "meeting.mp3")
+
+# Text to speech
+ai.speak("audio/kokoro", "Hello!", "hello.wav")
+
+# Generate a video
+ai.video("video/cogvideo:5b", "a panda running", "panda.mp4")
+
+# Generate a 3D model from text
+ai.model3d("3d/shap-e", "chair.ply", description="a wooden chair")
+
+# Generate a 3D model from image
+ai.model3d("3d/triposr", "chair.obj", image="photo.jpg")
+```
+
+---
+
+## License
+
+Apache-2.0 © Metiu — PullAI Contributors

pullai-0.3.5/pullai.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+pullai/__init__.py
+pullai/client.py
+pullai/py.typed
+pullai.egg-info/PKG-INFO
+pullai.egg-info/SOURCES.txt
+pullai.egg-info/dependency_links.txt
+pullai.egg-info/top_level.txt

pullai-0.3.5/pullai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pullai-0.3.5/pullai.egg-info/top_level.txt

@@ -0,0 +1 @@
+pullai

pullai-0.3.5/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pullai"
+version = "0.3.5"
+description = "Python SDK for PullAI — run AI models locally"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Metiu" }]
+requires-python = ">=3.8"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/pullai/pullai"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pullai*"]

pullai-0.3.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+