pythonai-grounded-generator 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+pythonai_grounded/__init__.py,sha256=VoALTJM08Vfh4Rt44qVd-xz_htWNsd2Rko18TWaw1w0,150
+pythonai_grounded/core.py,sha256=V57eiU8LCgEAkdcNt8CkE2t69J-wI4mXLlQWiCpxb7Y,2879
+pythonai_grounded/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pythonai_grounded_generator-0.1.0.dist-info/METADATA,sha256=eediSxZCziHVRvbOiaxe_ubdGJsUgAjir-4gPVbmAdw,2494
+pythonai_grounded_generator-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pythonai_grounded_generator-0.1.0.dist-info/top_level.txt,sha256=WXeBLJShJI8NUnf3iz8bPytvdXFTcG7gwbnOFsc7VvA,18
+pythonai_grounded_generator-0.1.0.dist-info/RECORD,,

pythonai_grounded_generator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pythonai_grounded_generator-0.1.0.dist-info/top_level.txt

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