pop-python 1.0.3__tar.gz → 1.1.0__tar.gz

{pop_python-1.0.3/pop_python.egg-info → pop_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pop-python
-Version: 1.0.3
+Version: 1.1.0
 Summary: Prompt Oriented Programming (POP): reusable, composable prompt functions for LLMs.
 Home-page: https://github.com/sgt1796/POP
 Author: Guotai Shen
@@ -35,11 +35,11 @@ Dynamic: summary
 # Prompt Oriented Programming (POP)
 
 ```python
-from POP import PromptFunction
+from pop import PromptFunction
 
 pf = PromptFunction(
     prompt="Draw a simple ASCII art of <<<object>>>.",
-    client = "openai"
+    client="openai",
 )
 
 print(pf.execute(object="a cat"))
@@ -61,7 +61,7 @@ print(pf.execute(object="a rocket"))
 ---
 Reusable, composable prompt functions for LLM workflows.
 
-This release cleans the architecture, moves all LLM client logic to a separate `LLMClient` module, and extends multi-LLM backend support.
+This 1.1.0 dev update restructures POP into small, focused modules and adds a provider registry inspired by pi-mono's `ai` package.
 
 PyPI:
 [https://pypi.org/project/pop-python/](https://pypi.org/project/pop-python/)
@@ -74,21 +74,19 @@ GitHub:
 ## Table of Contents
 
 1. [Overview](#1-overview)
-2. [Major Updates](#2-major-updates)
-3. [Features](#3-features)
-4. [Installation](#4-installation)
-5. [Setup](#5-setup)
-6. [PromptFunction](#6-promptfunction)
-
-   * Placeholders
-   * Reserved Keywords
-   * Executing prompts
-   * Improving prompts
-7. [Function Schema Generation](#7-function-schema-generation)
-8. [Embeddings](#8-embeddings)
-9. [Web Snapshot Utility](#9-web-snapshot-utility)
-10. [Examples](#10-examples)
-11. [Contributing](#11-contributing)
+2. [Update Note](#2-update-note)
+3. [Major Updates](#3-major-updates)
+4. [Features](#4-features)
+5. [Installation](#5-installation)
+6. [Setup](#6-setup)
+7. [PromptFunction](#7-promptfunction)
+8. [Provider Registry](#8-provider-registry)
+9. [Tool Calling](#9-tool-calling)
+10. [Function Schema Generation](#10-function-schema-generation)
+11. [Embeddings](#11-embeddings)
+12. [Web Snapshot Utility](#12-web-snapshot-utility)
+13. [Examples](#13-examples)
+14. [Contributing](#14-contributing)
 ---
 
 # 1. Overview
@@ -102,43 +100,64 @@ Instead of scattering prompt strings across your codebase, POP lets you:
 * improve prompts using meta-prompting
 * generate OpenAI-compatible function schemas
 * use unified embedding tools
-* work with multiple LLM providers through `LLMClient` subclasses
+* work with multiple LLM providers through a centralized registry
 
 POP is designed to be simple, extensible, and production-friendly.
 
 ---
 
-# 2. Major Updates
+# 2. Update Note
 
-This version introduces structural and functional improvements:
+**1.1.0-dev (February 5, 2026)**
 
-### 2.1. LLMClient moved into its own module
+* **Breaking import path**: use `pop` (lowercase) for imports. Example: `from pop import PromptFunction`.
+* **Provider registry**: clients live under `pop/providers/` and are instantiated via `pop.api_registry`.
+* **LLMClient base class**: now in `pop.providers.llm_client` (kept as an abstract base class).
 
-`LLMClient.py` now holds all LLM backends:
+---
+
+# 3. Major Updates
+
+### 3.1. Modularized architecture
+
+The project has been decomposed into small, focused modules:
+
+* `pop/prompt_function.py`
+* `pop/embedder.py`
+* `pop/context.py`
+* `pop/api_registry.py`
+* `pop/providers/` (one provider per file)
+* `pop/utils/`
+
+This mirrors the structure in the pi-mono `ai` package for clarity and maintainability.
 
-* OpenAI
-* Gemini
-* Deepseek
-* Doubao
-* Local PyTorch stub
-* Extensible architecture for adding new backends
+### 3.2. Provider registry + per-provider clients
 
-### 2.2. Expanded multi-LLM support
+Each provider has its own adaptor (OpenAI, Gemini, DeepSeek, Doubao, Local, Ollama). The registry gives you:
 
-Each backend now has consistent interface behavior and multimodal (text + image) support where applicable.
+* `list_providers()`
+* `list_default_model()`
+* `list_models()`
+* `get_client()`
 
 ---
 
-# 3. Features
+# 4. Features
 
 * **Reusable Prompt Functions**
   Use `<<<placeholder>>>` syntax to inject dynamic content.
 
 * **Multi-LLM Backend**
-  Choose between OpenAI, Gemini, Deepseek, Doubao, or local models.
+  Choose between OpenAI, Gemini, DeepSeek, Doubao, Local, or Ollama.
+
+* **Tool Calling**
+  Pass a tool schema list to `execute()` and receive tool-call arguments.
+
+* **Multimodal (Text + Image)**
+  Pass `images=[...]` (URLs or base64) when the provider supports it.
 
 * **Prompt Improvement**
-  Improve or rewrite prompts using Fabric-style metaprompts.
+  Improve or rewrite prompts using Fabric-style meta-prompts.
 
 * **Function Schema Generation**
   Convert natural language descriptions into OpenAI-function schemas.
@@ -151,7 +170,7 @@ Each backend now has consistent interface behavior and multimodal (text + image)
 
 ---
 
-# 4. Installation
+# 5. Installation
 
 Install from PyPI:
 
@@ -169,7 +188,7 @@ pip install -e .
 
 ---
 
-# 5. Setup
+# 6. Setup
 
 Create a `.env` file in your project root:
 
@@ -185,16 +204,16 @@ All clients automatically read keys from environment variables.
 
 ---
 
-# 6. PromptFunction
+# 7. PromptFunction
 
 The core abstraction of POP is the `PromptFunction` class.
 
 ```python
-from POP import PromptFunction
+from pop import PromptFunction
 
 pf = PromptFunction(
     sys_prompt="You are a helpful AI.",
-    prompt="Give me a summary about <<<topic>>>."
+    prompt="Give me a summary about <<<topic>>>.",
 )
 
 print(pf.execute(topic="quantum biology"))
@@ -202,7 +221,7 @@ print(pf.execute(topic="quantum biology"))
 
 ---
 
-## 6.1. Placeholder Syntax
+## 7.1. Placeholder Syntax
 
 Use angle-triple-brackets inside your prompt:
 
@@ -220,7 +239,7 @@ prompt = "Translate <<<sentence>>> to French."
 
 ---
 
-## 6.2. Reserved Keywords
+## 7.2. Reserved Keywords
 
 Within `.execute()`, the following keyword arguments are **reserved** and should not be used as placeholder names:
 
@@ -228,6 +247,7 @@ Within `.execute()`, the following keyword arguments are **reserved** and should
 * `sys`
 * `fmt`
 * `tools`
+* `tool_choice`
 * `temp`
 * `images`
 * `ADD_BEFORE`
@@ -237,32 +257,104 @@ Most keywords are used for parameters. `ADD_BEFORE` and `ADD_AFTER` will attach
 
 ---
 
-## 6.3. Executing prompts
+## 7.3. Executing prompts
 
 ```python
 result = pf.execute(
     topic="photosynthesis",
-    model="gpt-4o-mini",
-    temp=0.3
+    model="gpt-5-mini",
+    temp=0.3,
 )
 ```
 
 ---
 
-## 6.4. Improving Prompts
+## 7.4. Improving Prompts
 
 You can ask POP to rewrite or enhance your system prompt:
 
 ```python
-better = pf._improve_prompt()
+better = pf.improve_prompt()
 print(better)
 ```
 
-This uses a Fabric-inspired meta-prompt bundled in the `prompts/` directory.
+This uses a Fabric-inspired meta-prompt bundled in the `pop/prompts/` directory.
+
+---
+
+# 8. Provider Registry
+
+Use the registry to list providers/models or instantiate clients.
+
+```python
+from pop import list_providers, list_models, list_default_model, get_client
+
+print(list_providers())
+print(list_default_model())
+print(list_models())
+
+client = get_client("openai")
+```
+
+Non-default model example:
+
+```python
+from pop import PromptFunction, get_client
+
+client = get_client("gemini", "gemini-2.5-pro")
+
+pf = PromptFunction(prompt="Draw a rocket.", client=client)
+print(pf.execute())
+```
+
+Direct provider class example:
+
+```python
+from pop import PromptFunction
+from pop.providers.gemini_client import GeminiClient
+
+pf = PromptFunction(prompt="Draw a rocket.", client=GeminiClient(model="gemini-2.5-pro"))
+print(pf.execute())
+```
+
+---
+
+# 9. Tool Calling
+
+```python
+from pop import PromptFunction
+
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "create_reminder",
+            "description": "Create a reminder.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "description": {"type": "string"},
+                    "when": {"type": "string"},
+                },
+                "required": ["description"],
+            },
+        },
+    }
+]
+
+pf = PromptFunction(
+    sys_prompt="You are a helpful assistant.",
+    prompt="<<<input>>>",
+    client="openai",
+)
+
+result = pf.execute(input="Remind me to walk at 9am.", tools=tools)
+print(result)
+```
 
 ---
 
-# 7. Function Schema Generation
+# 10. Function Schema Generation
 
 POP supports generating **OpenAI function-calling schemas** from natural language descriptions.
 
@@ -279,16 +371,16 @@ What this does:
 * Applies a standard meta-prompt
 * Uses the selected LLM backend
 * Produces a valid JSON Schema for OpenAI function calling
-* Optionally saves it under `functions/`
+* Optionally saves it under `schemas/`
 
 ---
 
-# 8. Embeddings
+# 11. Embeddings
 
 POP includes a unified embedding interface:
 
 ```python
-from POP.Embedder import Embedder
+from pop import Embedder
 
 embedder = Embedder(use_api="openai")
 vecs = embedder.get_embedding(["hello world"])
@@ -304,10 +396,10 @@ Large inputs are chunked automatically when needed.
 
 ---
 
-# 9. Web Snapshot Utility
+# 12. Web Snapshot Utility
 
 ```python
-from POP import get_text_snapshot
+from pop.utils.web_snapshot import get_text_snapshot
 
 text = get_text_snapshot("https://example.com", image_caption=True)
 print(text[:500])
@@ -322,10 +414,10 @@ Supports:
 
 ---
 
-# 10. Examples
+# 13. Examples
 
 ```python
-from POP import PromptFunction
+from pop import PromptFunction
 
 pf = PromptFunction(prompt="Give me 3 creative names for a <<<thing>>>.")
 
@@ -333,9 +425,20 @@ print(pf.execute(thing="robot"))
 print(pf.execute(thing="new language"))
 ```
 
+Multimodal example (provider must support images):
+
+```python
+from pop import PromptFunction
+
+image_b64 = "..."  # base64-encoded image
+
+pf = PromptFunction(prompt="Describe the image.", client="openai")
+print(pf.execute(images=[image_b64]))
+```
+
 ---
 
-# 11. Contributing
+# 14. Contributing
 
 Steps:
 

pop_python-1.1.0/POP/Embedder.py

@@ -0,0 +1,231 @@
+"""
+Embedding utilities for POP.
+
+This module implements a unified embedding interface capable of
+fetching embeddings via third‑party APIs (JinaAI, OpenAI) or via
+a local PyTorch model.  It is largely derived from the original
+POP project’s ``Embedder.py`` and can be used independently of
+``PromptFunction``.
+
+Example usage:
+
+>>> from pop.embedder import Embedder
+>>> embedder = Embedder(use_api='openai')
+>>> vectors = embedder.get_embedding(["Hello, world!"])
+
+The return value is a numpy array of shape (n_texts, embedding_dim).
+"""
+
+import numpy as np
+import openai
+import requests as HTTPRequests
+from os import getenv
+from backoff import on_exception, expo
+from typing import List
+
+from transformers import AutoTokenizer, AutoModel
+
+# Maximum number of tokens permitted by the Jina segmenter
+MAX_TOKENS = 8194
+
+class Embedder:
+    """
+    A class supporting multiple embedding methods, including Jina API,
+    OpenAI API, and local model embeddings via PyTorch.
+
+    Parameters
+    ----------
+    model_name:
+        Name of the model to use for embedding.  If ``None`` the default
+        model for the selected API will be chosen.
+    use_api:
+        Which API to use for embedding.  Supported values are
+        ``'jina'``, ``'openai'`` and ``None`` (for local embedding).
+    to_cuda:
+        If ``True``, use GPU; otherwise use CPU for local embeddings.
+    attn_implementation:
+        Optional attention implementation to pass to the transformer
+        when loading the local model.
+    """
+
+    def __init__(self, model_name: str = None, use_api: str = None,
+                 to_cuda: bool = False, attn_implementation: str = None):
+        self.use_api = use_api
+        self.model_name = model_name
+        self.to_cuda = to_cuda
+
+        # API‑based embedding initialisation
+        if self.use_api is not None:
+            supported_apis = ['', 'jina', 'openai']
+            if self.use_api not in supported_apis:
+                raise ValueError(f"API type '{self.use_api}' not supported. Supported APIs: {supported_apis}")
+
+            if self.use_api == '':
+                # empty string falls back to OpenAI
+                self.use_api = 'openai'
+
+            if self.use_api == 'jina':
+                # The Jina client requires an API key; nothing to initialise
+                self.client = None
+            elif self.use_api == 'openai':
+                # Initialise OpenAI client
+                self.client = openai.Client(api_key=getenv("OPENAI_API_KEY"))
+        else:
+            # Load PyTorch model for local embedding generation
+            if not model_name:
+                raise ValueError("Model name must be provided when using a local model.")
+            self.attn_implementation = attn_implementation
+            self._initialize_local_model()
+
+    def _initialize_local_model(self) -> None:
+        """Initialise the PyTorch model and tokenizer for local embedding generation."""
+        import torch
+        import torch.nn.functional as F
+
+        if self.attn_implementation:
+            self.model = AutoModel.from_pretrained(
+                self.model_name,
+                trust_remote_code=True,
+                attn_implementation=self.attn_implementation,
+                torch_dtype=torch.float16,
+            ).to('cuda' if self.to_cuda else 'cpu')
+        else:
+            self.model = AutoModel.from_pretrained(
+                self.model_name,
+                trust_remote_code=True,
+                torch_dtype=torch.float16,
+            ).to('cuda' if self.to_cuda else 'cpu')
+        self.tokenizer = AutoTokenizer.from_pretrained(self.model_name)
+        self.model.eval()
+
+    def get_embedding(self, texts: List[str]) -> np.ndarray:
+        """
+        Generate embeddings for a list of texts.
+
+        Parameters
+        ----------
+        texts:
+            A list of strings to embed.
+
+        Returns
+        -------
+        numpy.ndarray
+            Embeddings as a 2‑D array of shape (len(texts), embedding_dim).
+        """
+        if not isinstance(texts, list):
+            raise ValueError("Input must be a list of strings.")
+
+        if self.use_api:
+            if self.use_api == 'jina':
+                # set default model if not provided
+                if not self.model_name:
+                    self.model_name = "jina-embeddings-v3"
+                return self._get_jina_embedding(texts)
+            elif self.use_api == 'openai':
+                if not self.model_name:
+                    self.model_name = "text-embedding-3-small"
+                return self._get_openai_embedding(texts)
+            else:
+                raise ValueError(f"API type '{self.use_api}' is not supported.")
+        else:
+            return self._get_torch_embedding(texts)
+
+    @on_exception(expo, HTTPRequests.exceptions.RequestException, max_time=30)
+    def _get_jina_embedding(self, texts: List[str]) -> np.ndarray:
+        """Fetch embeddings from the Jina API.  Requires Jina API key in .env."""
+        url = 'https://api.jina.ai/v1/embeddings'
+        headers = {
+            'Content-Type': 'application/json',
+            'Authorization': f"Bearer {getenv('JINAAI_API_KEY')}"
+        }
+        data = {
+            "model": self.model_name or "jina-embeddings-v3",
+            "task": "text-matching",
+            "dimensions": 1024,
+            "late_chunking": False,
+            "embedding_type": "float",
+            "input": [text for text in texts],
+        }
+        response = HTTPRequests.post(url, headers=headers, json=data)
+        if response.status_code == 200:
+            embeddings = response.json().get('data', [])
+            embeddings_np = np.array([e['embedding'] for e in embeddings], dtype='f')
+            return embeddings_np
+        elif response.status_code == 429:
+            raise HTTPRequests.exceptions.RequestException(
+                f"Rate limit exceeded: {response.status_code}, {response.text}"
+            )
+        elif response.status_code == 400:
+            # input too long; segment and average
+            ebd = []
+            for text in texts:
+                chunks = self._Jina_segmenter(text, max_token=MAX_TOKENS)
+                token_counts = [len(chunk) for chunk in chunks]
+                chunk_embedding = self.get_embedding(chunks)
+                weighted_avg = np.average(chunk_embedding, weights=token_counts, axis=0)
+                ebd.append(weighted_avg)
+            return np.array(ebd, dtype='f')
+        else:
+            raise Exception(f"Failed to get embedding from Jina API: {response.status_code}, {response.text}")
+
+    @on_exception(expo, HTTPRequests.exceptions.RequestException, max_time=30)
+    def _get_openai_embedding(self, texts: List[str]) -> np.ndarray:
+        """Fetch embeddings from the OpenAI API and return them as a NumPy array."""
+        batch_size = 2048
+        if len(texts) > batch_size:
+            all_embeddings = []
+            for i in range(0, len(texts), batch_size):
+                batch_texts = texts[i:i + batch_size]
+                batch_embeddings = self._get_openai_embedding(batch_texts)
+                all_embeddings.append(batch_embeddings)
+            return np.vstack(all_embeddings)
+        texts = [text.replace("\n", " ") for text in texts]
+        response = self.client.embeddings.create(input=texts, model=self.model_name)
+        embeddings = [item.embedding for item in response.data]
+        return np.array(embeddings, dtype='f')
+
+    def _get_torch_embedding(self, texts: List[str]) -> np.ndarray:
+        """Generate embeddings using a local PyTorch model."""
+        import torch
+        import torch.nn.functional as F
+
+        @torch.no_grad()
+        def _encode(instance: 'Embedder', input_texts: List[str]) -> np.ndarray:
+            batch_dict = instance.tokenizer(
+                input_texts,
+                max_length=512,
+                padding=True,
+                truncation=True,
+                return_tensors='pt',
+                return_attention_mask=True,
+            ).to('cuda' if instance.to_cuda else 'cpu')
+            outputs = instance.model(**batch_dict)
+            attention_mask = batch_dict['attention_mask']
+            hidden = outputs.last_hidden_state
+            def _weighted_mean_pooling(hidden_states, mask):
+                # compute weighted mean over tokens
+                mask_ = mask * mask.cumsum(dim=1)
+                s = (hidden_states * mask_.unsqueeze(-1).float()).sum(dim=1)
+                d = mask_.sum(dim=1, keepdim=True).float()
+                return s / d
+            reps = _weighted_mean_pooling(hidden, attention_mask)
+            embeddings = F.normalize(reps, p=2, dim=1).detach().cpu().numpy()
+            return embeddings
+        return _encode(self, texts)
+
+    @on_exception(expo, HTTPRequests.exceptions.RequestException, max_time=30)
+    def _Jina_segmenter(self, text: str, max_token: int) -> List[str]:
+        """Segments text into chunks using Jina API.  (free but needs API key)"""
+        url = 'https://segment.jina.ai/'
+        headers = {
+            'Content-Type': 'application/json',
+            'Authorization': f"Bearer {getenv('JINAAI_API_KEY')}"
+        }
+        data = {
+            "content": text,
+            "return_tokens": True,
+            "return_chunks": True,
+            "max_chunk_length": max_token,
+        }
+        response = HTTPRequests.post(url, headers=headers, json=data)
+        return response.json().get('chunks', [])

pop_python-1.1.0/POP/__init__.py

@@ -0,0 +1,40 @@
+"""Top‑level package for the restructured POP library.
+
+This package exposes the main classes and helper functions for creating
+prompt functions, embeddings and conversation contexts.  It also
+re‑exports provider registry functions for convenience.
+
+Example usage::
+
+    from pop import PromptFunction, Context, list_providers
+
+    ctx = Context(system="You are a helpful assistant")
+    pf = PromptFunction(sys_prompt="Translate", prompt="<<<text>>>", client="openai")
+    result = pf.execute(text="Hello")
+    print(result)
+"""
+
+from .prompt_function import PromptFunction
+from .embedder import Embedder
+from .context import Context, MessageBlock
+from .api_registry import (
+    list_providers,
+    list_default_model,
+    list_models,
+    get_default_model,
+    get_model,
+    get_client,
+)
+
+__all__ = [
+    "PromptFunction",
+    "Embedder",
+    "Context",
+    "MessageBlock",
+    "list_providers",
+    "list_default_model",
+    "list_models",
+    "get_default_model",
+    "get_model",
+    "get_client",
+]