PyIntell 0.1.0__py3-none-any.whl

pyintell/__init__.py

@@ -0,0 +1,31 @@
+"""pyintell: a modular NumPy-based framework for building AI models."""
+
+from .tokenization import *
+from .embeddings import *
+from .attention import *
+from .layers import *
+from .transformer import *
+from .loss import *
+from .optim import *
+from .training import *
+from .generation import *
+from .system import *
+from .autograd import *
+from .utilities import *
+from .serialization import *
+from .quantization import *
+from .scheduling import *
+from .finetuning import *
+from .focus import SUPPORTED_FOCUSES, FOCUS_PROFILES, normalize_focus, build_focus_config, focus_description
+from .model import Model
+from .builder import build
+
+__version__ = "0.1.0"
+
+# Explicitly expose the high-level model-management API.
+save_model = save_model
+load_model = load_model
+generate = generate
+model_run = model_run
+
+__all__ = [name for name in globals() if not name.startswith("_")]

pyintell/attention.py

@@ -0,0 +1,126 @@
+"""Numerically stable attention primitives used by pyintell."""
+
+import numpy as np
+
+
+def _softmax(x):
+    x = np.asarray(x, dtype=np.float32)
+    x = x - np.max(x, axis=-1, keepdims=True)
+    e = np.exp(np.clip(x, -80.0, 80.0))
+    return e / np.maximum(np.sum(e, axis=-1, keepdims=True), 1e-12)
+
+
+def attention(query, key, value, mask=None, dropout=0.0):
+    """Scaled dot-product attention with stable masking."""
+    q, k, v = map(lambda a: np.asarray(a, dtype=np.float32), (query, key, value))
+    depth = q.shape[-1]
+    scores = q @ np.swapaxes(k, -1, -2) / np.sqrt(max(depth, 1))
+    if mask is not None:
+        m = np.asarray(mask, dtype=bool)
+        scores = np.where(m, scores, -1e9)
+    weights = _softmax(scores)
+    if dropout:
+        raise NotImplementedError("dropout is intentionally disabled in the NumPy inference core")
+    return weights @ v
+
+
+def scaled_dot_product_attention(query, key, value, mask=None):
+    return attention(query, key, value, mask)
+
+
+def self_attention(x, mask=None):
+    return attention(x, x, x, mask)
+
+
+def cross_attention(query, context, mask=None):
+    return attention(query, context, context, mask)
+
+
+def causal_mask(length):
+    return np.tril(np.ones((int(length), int(length)), dtype=bool))
+
+
+def padding_mask(ids, pad_id=0):
+    return np.asarray(ids) != pad_id
+
+
+def attention_mask(length, causal=False):
+    return causal_mask(length) if causal else np.ones((length, length), dtype=bool)
+
+
+def causal_attention(x):
+    return attention(x, x, x, causal_mask(x.shape[-2]))
+
+
+def multihead_attention(x, heads=8, mask=None, weights=None):
+    """Multi-head attention.
+
+    When ``weights`` is supplied it must contain q/k/v/o projection matrices.
+    This makes attention deterministic and trainable instead of regenerating
+    random projections on every forward pass.
+    """
+    x = np.asarray(x, dtype=np.float32)
+    heads = int(heads)
+    if heads < 1 or x.shape[-1] % heads:
+        raise ValueError("embedding dimension must be divisible by heads")
+    d_model = x.shape[-1]
+    if weights is None:
+        q = k = v = x
+        output = np.concatenate(
+            [attention(a, a, a, mask) for a in np.split(x, heads, axis=-1)], axis=-1
+        )
+        return output
+    q = x @ weights["q"] + weights.get("q_bias", 0.0)
+    k = x @ weights["k"] + weights.get("k_bias", 0.0)
+    v = x @ weights["v"] + weights.get("v_bias", 0.0)
+    d_head = d_model // heads
+    q = q.reshape(x.shape[0], heads, d_head).transpose(1, 0, 2)
+    k = k.reshape(x.shape[0], heads, d_head).transpose(1, 0, 2)
+    v = v.reshape(x.shape[0], heads, d_head).transpose(1, 0, 2)
+    attended = attention(q, k, v, mask)
+    attended = attended.transpose(1, 0, 2).reshape(x.shape[0], d_model)
+    return attended @ weights["o"] + weights.get("o_bias", 0.0)
+
+
+def multi_query_attention(x, heads=8, mask=None):
+    return multihead_attention(x, heads, mask)
+
+
+def grouped_query_attention(x, heads=8, mask=None):
+    return multihead_attention(x, heads, mask)
+
+
+def local_attention(x, window=128):
+    length = x.shape[-2]
+    mask = np.zeros((length, length), dtype=bool)
+    for i in range(length):
+        mask[i, max(0, i - int(window) + 1):i + 1] = True
+    return attention(x, x, x, mask)
+
+
+def sliding_window_attention(x, window=128):
+    return local_attention(x, window)
+
+
+def global_attention(x, mask=None):
+    return attention(x, x, x, mask)
+
+
+def sparse_attention(x, mask):
+    return attention(x, x, x, mask)
+
+
+def block_attention(x, block_size=64):
+    return local_attention(x, block_size)
+
+
+def rotary_attention(x, mask=None):
+    return self_attention(x, mask)
+
+
+def alibi_attention(x, mask=None):
+    return self_attention(x, mask)
+
+
+def flash_attention(query, key, value, mask=None):
+    return attention(query, key, value, mask)

pyintell/autograd.py

@@ -0,0 +1,50 @@
+"""Small numerical automatic-differentiation helpers.
+
+This module intentionally stays lightweight; it provides finite-difference
+helpers for experiments rather than a production reverse-mode engine.
+"""
+
+import numpy as np
+
+
+def gradient(function, x, epsilon=1e-5):
+    x = np.asarray(x, dtype=float)
+    result = np.zeros_like(x)
+    for index in np.ndindex(x.shape):
+        plus = x.copy(); minus = x.copy()
+        plus[index] += epsilon; minus[index] -= epsilon
+        result[index] = (function(plus) - function(minus)) / (2 * epsilon)
+    return result
+
+
+def compute_gradients(function, x, epsilon=1e-5):
+    return gradient(function, x, epsilon)
+
+
+def numerical_gradient(function, x, epsilon=1e-5):
+    return gradient(function, x, epsilon)
+
+
+def backward(function, x, epsilon=1e-5):
+    return gradient(function, x, epsilon)
+
+
+def requires_grad(x, value=True):
+    array = np.asarray(x)
+    setattr(array, "requires_grad", value) if hasattr(array, "__dict__") else None
+    return array
+
+
+def detach(x):
+    return np.array(x, copy=True)
+
+
+def no_grad(function):
+    return function
+
+
+def zero_grad(gradients):
+    if isinstance(gradients, dict):
+        for key, value in gradients.items(): gradients[key] = np.zeros_like(value)
+        return gradients
+    return np.zeros_like(gradients)

pyintell/builder.py

@@ -0,0 +1,211 @@
+"""High-level model builder."""
+
+import math
+
+from .model import Model
+from .system import ram, storage_info
+from .serialization import set_current_model
+
+_SUPPORTED_FOCUS = {
+    "intelligence", "natural", "coding", "reasoning", "math", "knowledge",
+    "creativity", "conversation", "instruction", "accuracy", "speed", "memory",
+    "context", "language", "translation", "summarization", "classification", "roleplay",
+}
+_SUPPORTED_DTYPES = {"float64", "float32", "float16", "bfloat16", "int8", "int4"}
+_SUPPORTED_PLATFORMS = {"auto", "cpu", "gpu", "cuda", "mps", "rocm", "tpu", "android", "mobile"}
+
+# Focus is a model specialization, not merely a label. These profiles describe
+# the capabilities the builder should prioritize when choosing defaults.
+_FOCUS_PROFILES = {
+    "intelligence": {"reasoning": 1.0, "knowledge": 0.9, "accuracy": 0.9},
+    "natural": {"language": 1.0, "conversation": 0.8, "creativity": 0.6},
+    "coding": {"reasoning": 1.0, "instruction": 0.9, "accuracy": 0.9},
+    "reasoning": {"reasoning": 1.0, "accuracy": 0.9, "math": 0.8},
+    "math": {"math": 1.0, "reasoning": 0.9, "accuracy": 0.9},
+    "knowledge": {"knowledge": 1.0, "memory": 0.8, "accuracy": 0.8},
+    "creativity": {"creativity": 1.0, "language": 0.8, "natural": 0.7},
+    "conversation": {"conversation": 1.0, "natural": 0.9, "instruction": 0.7},
+    "instruction": {"instruction": 1.0, "accuracy": 0.9, "conversation": 0.6},
+    "accuracy": {"accuracy": 1.0, "reasoning": 0.8, "knowledge": 0.7},
+    "speed": {"speed": 1.0, "efficiency": 0.9},
+    "memory": {"memory": 1.0, "knowledge": 0.8, "context": 0.7},
+    "context": {"context": 1.0, "memory": 0.8, "language": 0.6},
+    "language": {"language": 1.0, "natural": 0.8, "translation": 0.7},
+    "translation": {"translation": 1.0, "language": 0.9, "accuracy": 0.8},
+    "summarization": {"summarization": 1.0, "language": 0.8, "accuracy": 0.7},
+    "classification": {"classification": 1.0, "accuracy": 0.9, "instruction": 0.6},
+    "roleplay": {"roleplay": 1.0, "conversation": 0.9, "creativity": 0.8},
+}
+
+
+def _dtype_bytes(dtype):
+    return {"float64": 8, "float32": 4, "float16": 2, "bfloat16": 2, "int8": 1, "int4": 0.5}[dtype]
+
+
+def _normalize_focus(focus):
+    focuses = [focus] if isinstance(focus, str) else list(focus)
+    if not focuses:
+        raise ValueError("focus must contain at least one focus")
+    normalized = []
+    for item in focuses:
+        if not isinstance(item, str):
+            raise TypeError("focus values must be strings")
+        value = item.strip().lower()
+        if value not in _SUPPORTED_FOCUS:
+            raise ValueError(f"unsupported focus values: {[value]}")
+        if value not in normalized:
+            normalized.append(value)
+    return normalized
+
+
+def _build_focus_config(focuses):
+    priorities = {}
+    for focus in focuses:
+        for capability, weight in _FOCUS_PROFILES[focus].items():
+            priorities[capability] = priorities.get(capability, 0.0) + weight
+    scale = max(priorities.values(), default=1.0)
+    priorities = {key: round(value / scale, 4) for key, value in priorities.items()}
+    return {"focuses": list(focuses), "priorities": priorities}
+
+
+def _estimate_architecture(target, vocab_size, settings, focus_config):
+    # Focus influences defaults only; explicit architecture settings always win.
+    priorities = focus_config["priorities"]
+    reasoning_boost = max(priorities.get("reasoning", 0.0), priorities.get("math", 0.0))
+    context_boost = priorities.get("context", 0.0)
+    speed_boost = priorities.get("speed", 0.0)
+    default_layers = round((target / 2.0e6) ** 0.45)
+    default_layers += int(round(reasoning_boost * 2))
+    default_layers -= int(round(speed_boost))
+    layers = max(1, int(settings.get("layers", default_layers)))
+
+    heads_default = 4 if target < 10_000_000 else 8
+    heads_default += int(round(reasoning_boost))
+    heads = max(1, int(settings.get("heads", heads_default)))
+
+    embedding_default = round((target / max(vocab_size, 1)) ** 0.5 * 8)
+    if context_boost:
+        embedding_default += int(round(embedding_default * 0.05 * context_boost))
+    embedding_size = max(32, int(settings.get("embedding_size", embedding_default)))
+    embedding_size = max(heads, (embedding_size // heads) * heads)
+
+    hidden_multiplier = 4
+    if reasoning_boost:
+        hidden_multiplier += int(round(reasoning_boost))
+    hidden_size = max(embedding_size, int(settings.get("hidden_size", embedding_size * hidden_multiplier)))
+    estimated = vocab_size * embedding_size + layers * (4 * embedding_size**2 + 2 * embedding_size * hidden_size) + embedding_size * vocab_size
+    return {"layers": layers, "heads": heads, "embedding_size": embedding_size, "hidden_size": hidden_size, "estimated_parameters": estimated}
+
+
+def _validate_positive_int(settings, key, default, minimum=1):
+    value = int(settings.get(key, default))
+    if value < minimum:
+        raise ValueError(f"settings['{key}'] must be at least {minimum}")
+    return value
+
+
+def _validate_positive_float(settings, key, default):
+    value = float(settings.get(key, default))
+    if value <= 0:
+        raise ValueError(f"settings['{key}'] must be positive")
+    return value
+
+
+def build(vocab, reverse_vocab, dataset, parameters, focus, dtype=None, settings=None, model_name=None):
+    """Build a configurable, focus-specialized Transformer model.
+
+    ``focus`` selects the capabilities the model should prioritize. Multiple
+    focuses can be supplied and are merged into a normalized priority map.
+    Focus changes architecture defaults when explicit architecture settings are
+    omitted and is persisted in the model for training/inference tooling.
+    """
+    if not isinstance(vocab, dict) or not isinstance(reverse_vocab, dict):
+        raise TypeError("vocab and reverse_vocab must be dictionaries")
+    if not isinstance(parameters, int) or isinstance(parameters, bool) or parameters <= 0:
+        raise ValueError("parameters must be a positive integer")
+    if settings is None:
+        settings = {}
+    elif not isinstance(settings, dict):
+        raise TypeError("settings must be a dictionary or None")
+    else:
+        settings = dict(settings)
+    dtype = "float32" if dtype is None else str(dtype).lower()
+    if dtype not in _SUPPORTED_DTYPES:
+        raise ValueError(f"unsupported dtype: {dtype}")
+
+    focuses = _normalize_focus(focus)
+    focus_config = _build_focus_config(focuses)
+
+    if model_name is not None:
+        if not isinstance(model_name, str):
+            raise TypeError("model_name must be a string or None")
+        model_name = model_name.strip()
+        if not model_name:
+            raise ValueError("model_name must not be empty")
+
+    platform = str(settings.get("platform", "auto")).lower()
+    if platform not in _SUPPORTED_PLATFORMS:
+        raise ValueError(f"unsupported platform: {platform}")
+    device = settings.get("device")
+    seed = settings.get("seed")
+    if seed is not None:
+        if isinstance(seed, bool):
+            raise TypeError("settings['seed'] must be an integer or None")
+        seed = int(seed)
+    batch_size = _validate_positive_int(settings, "batch_size", 1)
+    context_length = _validate_positive_int(settings, "context_length", 512)
+    epochs = _validate_positive_int(settings, "epochs", 1)
+    gradient_accumulation = _validate_positive_int(settings, "gradient_accumulation", 1)
+    learning_rate = _validate_positive_float(settings, "learning_rate", 3e-4)
+    weight_decay = float(settings.get("weight_decay", 0.0))
+    gradient_clip = float(settings.get("gradient_clip", 1.0))
+    dropout = float(settings.get("dropout", 0.0))
+    if weight_decay < 0:
+        raise ValueError("settings['weight_decay'] must not be negative")
+    if gradient_clip < 0:
+        raise ValueError("settings['gradient_clip'] must not be negative")
+    if not 0 <= dropout < 1:
+        raise ValueError("settings['dropout'] must be in [0, 1)")
+    optimizer = str(settings.get("optimizer", "adamw")).lower()
+    if optimizer not in {"sgd", "adam", "adamw", "rmsprop", "adagrad", "adadelta"}:
+        raise ValueError(f"unsupported optimizer: {optimizer}")
+
+    architecture = _estimate_architecture(parameters, len(vocab), settings, focus_config)
+    weight_bytes = parameters * _dtype_bytes(dtype)
+    required_storage = int(math.ceil(weight_bytes * 1.25))
+    required_ram = int(math.ceil(weight_bytes * (2.0 if dtype in {"int4", "int8"} else 4.0)))
+    available_ram = ram().get("available")
+    available_storage = storage_info().get("free")
+    if available_ram is not None and required_ram > available_ram:
+        raise MemoryError(f"requested model may require about {required_ram / 2**30:.2f} GiB RAM, but only {available_ram / 2**30:.2f} GiB is available")
+    if available_storage is not None and required_storage > available_storage:
+        raise OSError(f"requested model may require about {required_storage / 2**30:.2f} GiB storage, but only {available_storage / 2**30:.2f} GiB is free")
+
+    final_settings = dict(settings)
+    final_settings.update({
+        "model_name": model_name or settings.get("model_name", "pyintell_model"),
+        "platform": platform,
+        "device": device,
+        "seed": seed,
+        "layers": architecture["layers"],
+        "heads": architecture["heads"],
+        "embedding_size": architecture["embedding_size"],
+        "hidden_size": architecture["hidden_size"],
+        "context_length": context_length,
+        "batch_size": batch_size,
+        "learning_rate": learning_rate,
+        "epochs": epochs,
+        "optimizer": optimizer,
+        "weight_decay": weight_decay,
+        "gradient_clip": gradient_clip,
+        "gradient_accumulation": gradient_accumulation,
+        "dropout": dropout,
+        "focus_config": focus_config,
+        "estimated_parameters": architecture["estimated_parameters"],
+        "estimated_weight_bytes": int(weight_bytes),
+        "estimated_ram_bytes": required_ram,
+        "estimated_storage_bytes": required_storage,
+    })
+    model = Model(vocab, reverse_vocab, dataset, parameters, focuses, dtype, final_settings)
+    set_current_model(model)
+    return model

pyintell/embeddings.py

@@ -0,0 +1,33 @@
+"""Embedding layers implemented with NumPy."""
+
+import numpy as np
+
+
+def embedding(tokens, dimensions=128, weights=None, vocab_size=None):
+    ids = np.asarray(tokens, dtype=np.int64)
+    if weights is None:
+        if vocab_size is None: vocab_size = int(ids.max()) + 1 if ids.size else 1
+        weights = np.random.randn(vocab_size, dimensions).astype(np.float32) * 0.02
+    return weights[ids]
+
+
+def positional_embedding(sequence_length, dimensions, weights=None):
+    if weights is None: weights = np.random.randn(sequence_length, dimensions).astype(np.float32) * 0.02
+    return weights[:sequence_length]
+
+
+def sinusoidal_embedding(sequence_length, dimensions):
+    positions = np.arange(sequence_length)[:, None]
+    div = np.exp(np.arange(0, dimensions, 2) * (-np.log(10000.0) / dimensions))
+    result = np.zeros((sequence_length, dimensions), dtype=np.float32)
+    result[:, 0::2] = np.sin(positions * div)
+    result[:, 1::2] = np.cos(positions * div[:result[:, 1::2].shape[1]])
+    return result
+
+
+def rotary_embedding(sequence_length, dimensions): return sinusoidal_embedding(sequence_length, dimensions)
+def position_embedding(sequence_length, dimensions): return positional_embedding(sequence_length, dimensions)
+
+def embedding_similarity(a, b):
+    a = np.asarray(a); b = np.asarray(b)
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-12))

pyintell/finetuning.py

@@ -0,0 +1,29 @@
+"""Fine-tuning helpers and configuration primitives."""
+
+import numpy as np
+
+
+def freeze(model): setattr(model, "frozen", True); return model
+def unfreeze(model): setattr(model, "frozen", False); return model
+def freeze_layers(model, layers=None): setattr(model, "frozen_layers", layers); return model
+def unfreeze_layers(model, layers=None): setattr(model, "frozen_layers", []); return model
+def trainable(model): return not getattr(model, "frozen", False)
+def finetune(model, dataset, **settings): setattr(model, "finetune_settings", dict(settings)); return model
+
+def lora(model, rank=8, alpha=16): setattr(model, "lora", {"rank": rank, "alpha": alpha}); return model
+def qlora(model, rank=8, alpha=16): setattr(model, "qlora", {"rank": rank, "alpha": alpha}); return model
+def adapter(model, size=64): setattr(model, "adapter_size", size); return model
+def prompt_tuning(model, tokens=20): setattr(model, "prompt_tuning_tokens", tokens); return model
+def prefix_tuning(model, tokens=20): setattr(model, "prefix_tuning_tokens", tokens); return model
+
+def parameter_efficient_finetuning(model, method="lora", **kwargs):
+    methods = {"lora": lora, "qlora": qlora, "adapter": adapter, "prompt_tuning": prompt_tuning, "prefix_tuning": prefix_tuning}
+    if method not in methods: raise ValueError(f"unknown fine-tuning method: {method}")
+    return methods[method](model, **kwargs)
+
+def gradient_clipping(gradients, max_norm=1.0):
+    norm = np.sqrt(sum(np.sum(np.asarray(g) ** 2) for g in gradients.values())) if isinstance(gradients, dict) else np.linalg.norm(gradients)
+    scale = min(1.0, max_norm / (norm + 1e-12)); return {k: v*scale for k,v in gradients.items()} if isinstance(gradients, dict) else gradients*scale
+
+def weight_decay(value, rate=0.01): return value * (1-rate)
+def ema(previous, current, decay=0.99): return decay * previous + (1-decay) * current

pyintell/focus.py

@@ -0,0 +1,81 @@
+"""Alpha focus/capability utilities for pyintell.
+
+Focus is intentionally lightweight in 0.1.x. It describes intended model
+specialization and provides metadata/priorities for future training systems.
+It does not claim that a focus alone makes a model capable.
+"""
+
+SUPPORTED_FOCUSES = (
+    "intelligence", "natural", "coding", "reasoning", "math", "knowledge",
+    "creativity", "conversation", "instruction", "accuracy", "speed", "memory",
+    "context", "language", "translation", "summarization", "classification", "roleplay",
+)
+
+FOCUS_PROFILES = {
+    "intelligence": {"reasoning": 1.0, "knowledge": 0.9, "accuracy": 0.9},
+    "natural": {"language": 1.0, "conversation": 0.8, "creativity": 0.6},
+    "coding": {"reasoning": 1.0, "instruction": 0.9, "accuracy": 0.9},
+    "reasoning": {"reasoning": 1.0, "accuracy": 0.9, "math": 0.8},
+    "math": {"math": 1.0, "reasoning": 0.9, "accuracy": 0.9},
+    "knowledge": {"knowledge": 1.0, "memory": 0.8, "accuracy": 0.8},
+    "creativity": {"creativity": 1.0, "language": 0.8, "natural": 0.7},
+    "conversation": {"conversation": 1.0, "natural": 0.9, "instruction": 0.7},
+    "instruction": {"instruction": 1.0, "accuracy": 0.9, "conversation": 0.6},
+    "accuracy": {"accuracy": 1.0, "reasoning": 0.8, "knowledge": 0.7},
+    "speed": {"speed": 1.0, "efficiency": 0.9},
+    "memory": {"memory": 1.0, "knowledge": 0.8, "context": 0.7},
+    "context": {"context": 1.0, "memory": 0.8, "language": 0.6},
+    "language": {"language": 1.0, "natural": 0.8, "translation": 0.7},
+    "translation": {"translation": 1.0, "language": 0.9, "accuracy": 0.8},
+    "summarization": {"summarization": 1.0, "language": 0.8, "accuracy": 0.7},
+    "classification": {"classification": 1.0, "accuracy": 0.9, "instruction": 0.6},
+    "roleplay": {"roleplay": 1.0, "conversation": 0.9, "creativity": 0.8},
+}
+
+
+def normalize_focus(focus):
+    """Normalize and validate one or more focus names."""
+    if isinstance(focus, str):
+        values = [focus]
+    else:
+        try:
+            values = list(focus)
+        except TypeError as exc:
+            raise TypeError("focus must be a string or iterable of strings") from exc
+    if not values:
+        raise ValueError("focus must contain at least one focus")
+
+    result = []
+    for value in values:
+        if not isinstance(value, str):
+            raise TypeError("focus values must be strings")
+        value = value.strip().lower()
+        if value not in SUPPORTED_FOCUSES:
+            raise ValueError(f"unsupported focus: {value}")
+        if value not in result:
+            result.append(value)
+    return result
+
+
+def build_focus_config(focus):
+    """Build a serializable alpha focus configuration."""
+    focuses = normalize_focus(focus)
+    priorities = {}
+    for name in focuses:
+        for capability, weight in FOCUS_PROFILES[name].items():
+            priorities[capability] = priorities.get(capability, 0.0) + weight
+
+    maximum = max(priorities.values(), default=1.0)
+    priorities = {name: round(value / maximum, 4) for name, value in priorities.items()}
+    return {"focuses": focuses, "priorities": priorities}
+
+
+def focus_description(focus):
+    """Return a small human-readable description of a focus selection."""
+    config = build_focus_config(focus)
+    ranked = sorted(config["priorities"].items(), key=lambda item: (-item[1], item[0]))
+    return {
+        "focuses": config["focuses"],
+        "top_capabilities": [name for name, _ in ranked[:5]],
+        "priorities": config["priorities"],
+    }

pyintell/generation.py

@@ -0,0 +1,73 @@
+"""Generation and sampling utilities."""
+
+import numpy as np
+
+from .serialization import get_model
+
+
+def sample(logits, temperature=1.0, top_k=None, rng=None):
+    """Sample one token ID from a logits vector."""
+    logits = np.asarray(logits, dtype=np.float64)
+    if logits.ndim != 1 or logits.size == 0:
+        raise ValueError("logits must be a non-empty one-dimensional array")
+    if temperature <= 0:
+        raise ValueError("temperature must be greater than zero")
+    scaled = logits / temperature
+    if top_k is not None:
+        if isinstance(top_k, bool):
+            raise TypeError("top_k must be an integer")
+        top_k = int(top_k)
+        if top_k <= 0: raise ValueError("top_k must be greater than zero")
+        top_k = min(top_k, scaled.size)
+        indices = np.argpartition(scaled, -top_k)[-top_k:]
+        filtered = np.full_like(scaled, -np.inf)
+        filtered[indices] = scaled[indices]
+        scaled = filtered
+    scaled -= np.max(scaled)
+    probabilities = np.exp(scaled)
+    total = probabilities.sum()
+    if not np.isfinite(total) or total <= 0:
+        raise ValueError("logits produced invalid sampling probabilities")
+    probabilities /= total
+    generator = rng or np.random.default_rng()
+    return int(generator.choice(len(probabilities), p=probabilities))
+
+
+def generate(model_name, prompt, max_tokens=50, temperature=1.0, top_k=None, **kwargs):
+    """Generate a response using a saved model name."""
+    model = get_model(model_name)
+    if not hasattr(model, "generate"):
+        raise TypeError("saved object is not a valid pyintell model")
+    return model.generate(prompt, max_tokens=max_tokens, temperature=temperature, top_k=top_k, **kwargs)
+
+
+def model_run(model_name, max_tokens=50, temperature=1.0, top_k=None, **kwargs):
+    """Run an interactive terminal chat session with a saved model.
+
+    Invalid prompts or generation errors are reported without terminating the
+    entire chat session. Enter ``exit``, ``quit``, ``/exit``, or ``/quit`` to
+    stop the session.
+    """
+    # Validate/load once before opening the interactive session.
+    get_model(model_name)
+    print(f"pyintell model '{model_name}' is running.")
+    print("Type 'exit' or 'quit' to stop.")
+
+    while True:
+        try:
+            prompt = input("You: ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if prompt.strip().lower() in {"exit", "quit", "/exit", "/quit"}:
+            break
+        if not prompt.strip():
+            continue
+        try:
+            response = generate(model_name, prompt, max_tokens=max_tokens,
+                                temperature=temperature, top_k=top_k, **kwargs)
+            print(f"AI: {response}")
+        except (TypeError, ValueError, RuntimeError, FileNotFoundError) as error:
+            print(f"AI error: {error}")
+
+    return None