pythonai-grounded-generator 0.1.0__tar.gz

pythonai_grounded_generator-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: pythonai-grounded-generator
+Version: 0.1.0
+Summary: Lightweight grounded text generation from retrieved context
+Keywords: llm,rag,grounded-generation,transformers,qwen
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers>=4.51.0
+
+# PythonAI Grounded Generator
+
+A compact Python helper for generating answers from retrieved context with an already loaded Hugging Face causal language model.
+
+It provides:
+
+- Custom system prompts and questions
+- Token-budget-aware context truncation
+- Qwen3 non-thinking chat formatting
+- CPU or CUDA inference (device controlled by the caller)
+- A plain-text answer suitable for wrapping in application-specific Pydantic models
+
+Retrieval, context assembly, and structured JSON serialization remain the responsibility of the calling application. This package does **not** guarantee factual correctness or replace source validation.
+
+## Installation
+
+After publication:
+
+```bash
+pip install pythonai-grounded-generator
+```
+
+Or install the local project:
+
+```bash
+pip install .
+```
+
+## Example
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from pythonai_grounded import generate_answer
+
+name = "Qwen/Qwen3-0.6B"
+tokenizer = AutoTokenizer.from_pretrained(name)
+model = AutoModelForCausalLM.from_pretrained(name).to("cpu")
+model.eval()
+
+answer = generate_answer(
+    model=model,
+    tokenizer=tokenizer,
+    question="Which endpoint loads an adapter?",
+    context="Use POST /v1/load_lora_adapter to load an adapter.",
+    system_prompt="Answer only from the context. Copy technical names exactly.",
+    max_new_tokens=64,
+    device="cpu",
+)
+print(answer)
+```
+
+## API
+
+```python
+generate_answer(
+    model,
+    tokenizer,
+    question: str,
+    context: str,
+    system_prompt: str,
+    max_new_tokens: int = 64,
+    device: str = "cpu",
+) -> str
+```
+
+The supplied `model` and `tokenizer` must be compatible. The model must already be on the requested device and in evaluation mode. Model context limits are read from `model.config.max_position_embeddings`, falling back to 32768 if absent. Check actual model capabilities when switching models.
+
+## Build
+
+```bash
+uv build
+```
+
+The distributions are created in `dist/`.

pythonai_grounded_generator-0.1.0/README.md

@@ -0,0 +1,74 @@
+# PythonAI Grounded Generator
+
+A compact Python helper for generating answers from retrieved context with an already loaded Hugging Face causal language model.
+
+It provides:
+
+- Custom system prompts and questions
+- Token-budget-aware context truncation
+- Qwen3 non-thinking chat formatting
+- CPU or CUDA inference (device controlled by the caller)
+- A plain-text answer suitable for wrapping in application-specific Pydantic models
+
+Retrieval, context assembly, and structured JSON serialization remain the responsibility of the calling application. This package does **not** guarantee factual correctness or replace source validation.
+
+## Installation
+
+After publication:
+
+```bash
+pip install pythonai-grounded-generator
+```
+
+Or install the local project:
+
+```bash
+pip install .
+```
+
+## Example
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from pythonai_grounded import generate_answer
+
+name = "Qwen/Qwen3-0.6B"
+tokenizer = AutoTokenizer.from_pretrained(name)
+model = AutoModelForCausalLM.from_pretrained(name).to("cpu")
+model.eval()
+
+answer = generate_answer(
+    model=model,
+    tokenizer=tokenizer,
+    question="Which endpoint loads an adapter?",
+    context="Use POST /v1/load_lora_adapter to load an adapter.",
+    system_prompt="Answer only from the context. Copy technical names exactly.",
+    max_new_tokens=64,
+    device="cpu",
+)
+print(answer)
+```
+
+## API
+
+```python
+generate_answer(
+    model,
+    tokenizer,
+    question: str,
+    context: str,
+    system_prompt: str,
+    max_new_tokens: int = 64,
+    device: str = "cpu",
+) -> str
+```
+
+The supplied `model` and `tokenizer` must be compatible. The model must already be on the requested device and in evaluation mode. Model context limits are read from `model.config.max_position_embeddings`, falling back to 32768 if absent. Check actual model capabilities when switching models.
+
+## Build
+
+```bash
+uv build
+```
+
+The distributions are created in `dist/`.

pythonai_grounded_generator-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pythonai-grounded-generator"
+version = "0.1.0"
+description = "Lightweight grounded text generation from retrieved context"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "torch>=2.2",
+    "transformers>=4.51.0",
+]
+keywords = ["llm", "rag", "grounded-generation", "transformers", "qwen"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pythonai_grounded = ["py.typed"]

pythonai_grounded_generator-0.1.0/setup.cfg

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

pythonai_grounded_generator-0.1.0/src/pythonai_grounded/__init__.py

@@ -0,0 +1,5 @@
+"""Helpers for grounded generation with an already loaded causal language model."""
+
+from .core import generate_answer
+
+__all__ = ["generate_answer"]

pythonai_grounded_generator-0.1.0/src/pythonai_grounded/core.py

@@ -0,0 +1,91 @@
+"""Grounded answer generation with configurable prompts and token budgets."""
+
+from typing import Any
+
+import torch
+
+
+def generate_answer(
+    model: Any,
+    tokenizer: Any,
+    question: str,
+    context: str,
+    system_prompt: str,
+    max_new_tokens: int = 64,
+    device: str = "cpu",
+) -> str:
+    """Generate an answer using a preloaded model and retrieved context.
+
+    The caller owns retrieval, augmentation, model loading, and output schema.
+    This function formats the prompt, truncates context to the token budget,
+    generates an answer, and returns only the decoded completion.
+
+    Raises:
+        ValueError: If inputs are invalid or the prompt exceeds the budget.
+    """
+    if not question.strip() or not system_prompt.strip():
+        raise ValueError("Question and system prompt must not be empty")
+    if max_new_tokens <= 0:
+        raise ValueError("max_new_tokens must be positive")
+
+    user_prefix = "Retrieved context:\n"
+    user_suffix = (
+        f"\n\nQuestion:\n{question}\n\n"
+        "Important: copy technical identifiers exactly as written "
+        "in the retrieved context."
+    )
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prefix + user_suffix},
+    ]
+
+    # Count tokens needed even when the retrieved context is empty.
+    fixed_ids = tokenizer.apply_chat_template(
+        messages,
+        tokenize=True,
+        return_dict=False,
+        add_generation_prompt=True,
+        enable_thinking=False,
+    )
+    model_limit = getattr(model.config, "max_position_embeddings", 32768)
+    budget = model_limit - len(fixed_ids) - max_new_tokens - 32
+    if budget <= 0:
+        raise ValueError("Not enough token budget for the prompt")
+
+    context_ids = tokenizer(
+        context,
+        add_special_tokens=False,
+        truncation=True,
+        max_length=budget,
+    )["input_ids"]
+    trimmed_context = tokenizer.decode(context_ids, skip_special_tokens=True)
+    messages[1]["content"] = user_prefix + trimmed_context + user_suffix
+
+    prompt = tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+        enable_thinking=False,
+    )
+    inputs = tokenizer(
+        prompt,
+        return_tensors="pt",
+        add_special_tokens=False,
+    ).to(device)
+    input_length = inputs["input_ids"].shape[1]
+    if input_length + max_new_tokens > model_limit:
+        raise ValueError("Prompt exceeds the model token budget")
+
+    with torch.inference_mode():
+        output = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            do_sample=False,
+            eos_token_id=tokenizer.eos_token_id,
+            pad_token_id=tokenizer.eos_token_id,
+        )
+
+    return tokenizer.decode(
+        output[0][input_length:],
+        skip_special_tokens=True,
+    ).strip()

pythonai_grounded_generator-0.1.0/src/pythonai_grounded_generator.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: pythonai-grounded-generator
+Version: 0.1.0
+Summary: Lightweight grounded text generation from retrieved context
+Keywords: llm,rag,grounded-generation,transformers,qwen
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers>=4.51.0
+
+# PythonAI Grounded Generator
+
+A compact Python helper for generating answers from retrieved context with an already loaded Hugging Face causal language model.
+
+It provides:
+
+- Custom system prompts and questions
+- Token-budget-aware context truncation
+- Qwen3 non-thinking chat formatting
+- CPU or CUDA inference (device controlled by the caller)
+- A plain-text answer suitable for wrapping in application-specific Pydantic models
+
+Retrieval, context assembly, and structured JSON serialization remain the responsibility of the calling application. This package does **not** guarantee factual correctness or replace source validation.
+
+## Installation
+
+After publication:
+
+```bash
+pip install pythonai-grounded-generator
+```
+
+Or install the local project:
+
+```bash
+pip install .
+```
+
+## Example
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from pythonai_grounded import generate_answer
+
+name = "Qwen/Qwen3-0.6B"
+tokenizer = AutoTokenizer.from_pretrained(name)
+model = AutoModelForCausalLM.from_pretrained(name).to("cpu")
+model.eval()
+
+answer = generate_answer(
+    model=model,
+    tokenizer=tokenizer,
+    question="Which endpoint loads an adapter?",
+    context="Use POST /v1/load_lora_adapter to load an adapter.",
+    system_prompt="Answer only from the context. Copy technical names exactly.",
+    max_new_tokens=64,
+    device="cpu",
+)
+print(answer)
+```
+
+## API
+
+```python
+generate_answer(
+    model,
+    tokenizer,
+    question: str,
+    context: str,
+    system_prompt: str,
+    max_new_tokens: int = 64,
+    device: str = "cpu",
+) -> str
+```
+
+The supplied `model` and `tokenizer` must be compatible. The model must already be on the requested device and in evaluation mode. Model context limits are read from `model.config.max_position_embeddings`, falling back to 32768 if absent. Check actual model capabilities when switching models.
+
+## Build
+
+```bash
+uv build
+```
+
+The distributions are created in `dist/`.

pythonai_grounded_generator-0.1.0/src/pythonai_grounded_generator.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/pythonai_grounded/__init__.py
+src/pythonai_grounded/core.py
+src/pythonai_grounded/py.typed
+src/pythonai_grounded_generator.egg-info/PKG-INFO
+src/pythonai_grounded_generator.egg-info/SOURCES.txt
+src/pythonai_grounded_generator.egg-info/dependency_links.txt
+src/pythonai_grounded_generator.egg-info/requires.txt
+src/pythonai_grounded_generator.egg-info/top_level.txt
+tests/test_core.py

pythonai_grounded_generator-0.1.0/src/pythonai_grounded_generator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pythonai_grounded_generator-0.1.0/src/pythonai_grounded_generator.egg-info/requires.txt

@@ -0,0 +1,2 @@
+torch>=2.2
+transformers>=4.51.0

pythonai_grounded_generator-0.1.0/src/pythonai_grounded_generator.egg-info/top_level.txt

@@ -0,0 +1 @@
+pythonai_grounded

pythonai_grounded_generator-0.1.0/tests/test_core.py

@@ -0,0 +1,95 @@
+"""Unit tests using fake tokenizer and model: no model download needed."""
+
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+from pythonai_grounded import generate_answer
+
+
+class TensorInputs(dict):
+    def to(self, device):
+        return self
+
+
+class DummyTokenizer:
+    eos_token_id = 2
+
+    def __init__(self, final_length=8):
+        self.final_length = final_length
+        self.last_context_ids = None
+        self.last_messages = None
+
+    def apply_chat_template(self, messages, tokenize, **kwargs):
+        self.last_messages = [dict(message) for message in messages]
+        assert kwargs["enable_thinking"] is False
+        if tokenize:
+            return [1, 2, 3, 4]
+        return "\n".join(message["content"] for message in messages)
+
+    def __call__(self, text, **kwargs):
+        if kwargs.get("return_tensors") == "pt":
+            length = self.final_length
+            return TensorInputs({
+                "input_ids": torch.ones((1, length), dtype=torch.long),
+                "attention_mask": torch.ones((1, length), dtype=torch.long),
+            })
+        max_length = kwargs["max_length"]
+        self.last_context_ids = list(range(min(len(text.split()), max_length)))
+        return {"input_ids": self.last_context_ids}
+
+    def decode(self, ids, **kwargs):
+        ids = ids.tolist() if hasattr(ids, "tolist") else ids
+        return "GENERATED ANSWER" if 999 in ids else "context"
+
+
+class DummyModel:
+    def __init__(self, limit=200):
+        self.config = SimpleNamespace(max_position_embeddings=limit)
+        self.last_inputs = None
+
+    def generate(self, **kwargs):
+        self.last_inputs = kwargs
+        return torch.cat(
+            [kwargs["input_ids"], torch.tensor([[999]], dtype=torch.long)],
+            dim=1,
+        )
+
+
+def test_basic_generation_and_prompt():
+    model = DummyModel()
+    tokenizer = DummyTokenizer()
+    output = generate_answer(model, tokenizer, "What?", "evidence here", "Use evidence")
+    assert output == "GENERATED ANSWER"
+    assert tokenizer.last_messages[0]["content"] == "Use evidence"
+    assert "Question:\nWhat?" in tokenizer.last_messages[1]["content"]
+    assert model.last_inputs["do_sample"] is False
+
+
+def test_context_is_truncated():
+    model = DummyModel(limit=50)
+    tokenizer = DummyTokenizer()
+    generate_answer(model, tokenizer, "Question?", "word " * 100, "Instruction", 5)
+    assert len(tokenizer.last_context_ids) == 9  # 50 - 4 - 5 - 32
+
+
+@pytest.mark.parametrize("question,prompt,tokens", [
+    ("", "Instruction", 64),
+    ("Question", "", 64),
+    ("Question", "Instruction", 0),
+])
+def test_invalid_inputs(question, prompt, tokens):
+    with pytest.raises(ValueError):
+        generate_answer(DummyModel(), DummyTokenizer(), question, "context", prompt, tokens)
+
+
+def test_insufficient_budget():
+    with pytest.raises(ValueError, match="Not enough token budget"):
+        generate_answer(DummyModel(limit=30), DummyTokenizer(), "Q", "text", "S")
+
+
+def test_final_length_check():
+    tokenizer = DummyTokenizer(final_length=100)
+    with pytest.raises(ValueError, match="exceeds"):
+        generate_answer(DummyModel(limit=90), tokenizer, "Q", "text", "S", 5)