shadow-tools 0.7.2__tar.gz → 0.8.0__tar.gz

{shadow_tools-0.7.2 → shadow_tools-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shadow-tools
-Version: 0.7.2
+Version: 0.8.0
 Summary: A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs.
 Project-URL: Homepage, https://github.com/WilliamLaurento/shadow-tools
 Project-URL: Issues, https://github.com/WilliamLaurento/shadow-tools/issues
@@ -76,6 +76,22 @@ bot.save("my_text_model")
 Training prints the tokenizer status plus each epoch and loss. Use
 `learn("corpus.txt", epochs=20, verbose=False)` when you do not want updates.
 
+## Train a question-and-answer bot
+
+```python
+from shadowtools import ask, teach
+
+bot = teach({
+    "What is ChatGPT?": "ChatGPT is an AI system that predicts useful next tokens to answer a prompt.",
+    "How does a tokenizer work?": "A tokenizer splits text into smaller tokens a model can process.",
+    "What is machine learning?": "Machine learning is when a model learns patterns from examples.",
+}, epochs=20)
+
+print(ask(bot, "What is ChatGPT?"))
+```
+
+Add many more real Q&A pairs for better answers.
+
 Install it with `pip install "shadow-tools[ml,nlp]"`. The package trains the
 tokenizer and Transformer together, then converts predicted token IDs back to
 normal text for you.

{shadow_tools-0.7.2 → shadow_tools-0.8.0}/README.md

@@ -48,6 +48,22 @@ bot.save("my_text_model")
 Training prints the tokenizer status plus each epoch and loss. Use
 `learn("corpus.txt", epochs=20, verbose=False)` when you do not want updates.
 
+## Train a question-and-answer bot
+
+```python
+from shadowtools import ask, teach
+
+bot = teach({
+    "What is ChatGPT?": "ChatGPT is an AI system that predicts useful next tokens to answer a prompt.",
+    "How does a tokenizer work?": "A tokenizer splits text into smaller tokens a model can process.",
+    "What is machine learning?": "Machine learning is when a model learns patterns from examples.",
+}, epochs=20)
+
+print(ask(bot, "What is ChatGPT?"))
+```
+
+Add many more real Q&A pairs for better answers.
+
 Install it with `pip install "shadow-tools[ml,nlp]"`. The package trains the
 tokenizer and Transformer together, then converts predicted token IDs back to
 normal text for you.

{shadow_tools-0.7.2 → shadow_tools-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shadow-tools"
-version = "0.7.2"
+version = "0.8.0"
 description = "A practical all-in-one Python toolkit for HTTP, WebSockets, files, data, validation, async work, and CLIs."
 readme = "README.md"
 requires-python = ">=3.10"

{shadow_tools-0.7.2 → shadow_tools-0.8.0}/src/shadowtools/__init__.py

@@ -5,7 +5,7 @@ from .bpe import BPETokenizer
 from .config import env, require_env, to_bool
 from .files import append_text, ensure_dir, read_text, write_text
 from .hashing import file_hash, hash_text
-from .generator import GeneratorConfig, TextGenerator, generate_text, learn, say, train_generator
+from .generator import GeneratorConfig, TextGenerator, ask, generate_text, learn, say, teach, train_generator
 from .http import get, request
 from .ids import random_token, timestamp_id, uuid4
 from .network import generate_random_ips, generate_test_ips, is_subdomain_of, make_subdomain, resolve_dns, reverse_dns
@@ -15,10 +15,10 @@ from .text import chunks, slugify, to_camel, to_snake
 from .training import SmartTokenizer, fine_tune, make_loaders, predict_text, train, train_text
 from .validation import is_email, is_url, require_keys
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 __all__ = [
-    "append_text", "audit_headers", "BPETokenizer", "chunks", "ensure_dir", "env", "file_hash", "GeneratorConfig", "generate_random_ips", "generate_test_ips", "generate_text", "get", "hash_text", "is_email", "is_subdomain_of", "is_url", "learn", "make_password", "make_subdomain", "random_token", "read_csv",
-    "read_json", "read_text", "request", "require_env", "require_keys", "retry", "reverse_dns", "resolve_dns", "say", "slugify", "timestamp_id", "to_bool", "to_camel", "to_snake", "TextGenerator", "train", "train_generator", "fine_tune", "make_loaders", "SmartTokenizer", "train_text", "predict_text", "uuid4", "write_csv",
+    "append_text", "ask", "audit_headers", "BPETokenizer", "chunks", "ensure_dir", "env", "file_hash", "GeneratorConfig", "generate_random_ips", "generate_test_ips", "generate_text", "get", "hash_text", "is_email", "is_subdomain_of", "is_url", "learn", "make_password", "make_subdomain", "random_token", "read_csv",
+    "read_json", "read_text", "request", "require_env", "require_keys", "retry", "reverse_dns", "resolve_dns", "say", "slugify", "teach", "timestamp_id", "to_bool", "to_camel", "to_snake", "TextGenerator", "train", "train_generator", "fine_tune", "make_loaders", "SmartTokenizer", "train_text", "predict_text", "uuid4", "write_csv",
     "write_json", "write_text", "redact_secrets", "verify_file_hash",
 ]

{shadow_tools-0.7.2 → shadow_tools-0.8.0}/src/shadowtools/generator.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from dataclasses import asdict, dataclass
 from pathlib import Path
-from typing import Any, Sequence
+from typing import Any, Mapping, Sequence
 
 from .bpe import BPETokenizer
 
@@ -226,3 +226,25 @@ def learn(source: str | Path | Sequence[str], *, epochs: int = 10,
 def say(generator: TextGenerator, prompt: str, **options: Any) -> str:
     """Beginner-friendly name for generating text from a trained model."""
     return generator.generate(prompt, **options)
+
+
+def teach(questions_and_answers: Mapping[str, str] | Sequence[tuple[str, str]], *,
+          epochs: int = 10, verbose: bool = True, **options: Any) -> TextGenerator:
+    """Train a small Q&A bot from question-and-answer pairs."""
+    pairs = list(questions_and_answers.items()) if isinstance(questions_and_answers, Mapping) else list(questions_and_answers)
+    if len(pairs) < 2:
+        raise ValueError("Give teach() at least two question-and-answer pairs.")
+    sections: list[str] = []
+    for question, answer in pairs:
+        if not isinstance(question, str) or not isinstance(answer, str) or not question.strip() or not answer.strip():
+            raise ValueError("Every question and answer must be non-empty text.")
+        sections.append(f"Question: {question.strip()}\nAnswer: {answer.strip()}")
+    return learn("\n\n".join(sections), epochs=epochs, verbose=verbose, **options)
+
+
+def ask(generator: TextGenerator, question: str, *, max_tokens: int = 200,
+        **options: Any) -> str:
+    """Ask a Q&A bot a question and get its generated answer."""
+    if not isinstance(question, str) or not question.strip():
+        raise ValueError("question must be non-empty text.")
+    return generator.generate(f"Question: {question.strip()}\nAnswer:", max_tokens=max_tokens, **options)