npcpy 1.2.22__tar.gz → 1.2.24__tar.gz

{npcpy-1.2.22/npcpy.egg-info → npcpy-1.2.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcpy
-Version: 1.2.22
+Version: 1.2.24
 Summary: npcpy is the premier open-source library for integrating LLMs and Agents into python systems.
 Home-page: https://github.com/NPC-Worldwide/npcpy
 Author: Christopher Agostino
@@ -399,6 +399,152 @@ the citizens, being directed by simple and incontestable principles, may tend to
 maintenance of the Constitution, and the general happiness. ''')
 # it will play the audio automatically.
 ```
+## Fine-Tuning and Evolution
+
+`npcpy` provides modular tools for building adaptive AI systems through supervised fine-tuning, reinforcement learning, and genetic algorithms.
+
+See examples/fine_tuning_demo.py for a complete working example.
+
+
+### Supervised Fine-Tuning (SFT)
+
+Train models on specific tasks using simple X, y pairs:
+```python
+from npcpy.ft.sft import run_sft, load_sft_model, predict_sft
+
+X_train = ["translate to french: hello", "translate to french: goodbye"]
+y_train = ["bonjour", "au revoir"]
+
+model_path = run_sft(X_train, y_train)
+
+model, tokenizer = load_sft_model(model_path)
+response = predict_sft(model, tokenizer, "translate to french: thanks")
+```
+### Unsupervised Fine-Tuning (USFT)
+Adapt models to domain-specific text corpora without labels:
+```python
+from npcpy.ft.usft import run_usft, load_corpus_from_hf
+
+texts = load_corpus_from_hf("tiny_shakespeare", split="train[:1000]")
+
+model_path = run_usft(
+    texts,
+    config=USFTConfig(
+        output_model_path="models/shakespeare",
+        num_train_epochs=3
+    )
+)
+Train on your own text corpus:
+pythondomain_texts = [
+    "Your domain-specific text 1",
+    "Your domain-specific text 2",
+] * 100
+
+model_path = run_usft(domain_texts)
+```
+### Diffusion Fine-tuning
+```
+from npcpy.ft.diff import train_diffusion, generate_image
+
+image_paths = ["img1.png", "img2.png", "img3.png"]
+captions = ["a cat", "a dog", "a bird"]
+
+model_path = train_diffusion(
+    image_paths,
+    captions,
+    config=DiffusionConfig(
+        num_epochs=100,
+        batch_size=4
+    )
+)
+
+generated = generate_image(
+    model_path,
+    prompt="a white square",
+    image_size=128
+)
+Resume training from checkpoint:
+pythonmodel_path = train_diffusion(
+    image_paths,
+    captions,
+    config,
+    resume_from="models/diffusion/checkpoints/checkpoint-epoch10-step1000.pt"
+)
+```
+
+
+### Reinforcement Learning (RL)
+Collect agent traces and train with DPO based on reward signals:
+```python
+from npcpy.ft.rl import collect_traces, run_rl_training
+from npcpy.npc_compiler import NPC
+
+tasks = [
+    {'prompt': 'Solve 2+2', 'expected': '4'},
+    {'prompt': 'Solve 5+3', 'expected': '8'}
+]
+
+agents = [
+    NPC(name="farlor", primary_directive="Be concise", 
+        model="qwen3:0.6b", provider="ollama"),
+    NPC(name="tedno", primary_directive="Show your work",
+        model="qwen3:0.6b", provider="ollama")
+]
+
+def reward_fn(trace):
+    if trace['task_metadata']['expected'] in trace['final_output']:
+        return 1.0
+    return 0.0
+
+adapter_path = run_rl_training(tasks, agents, reward_fn)
+```
+### Genetic Evolution
+
+Evolve populations of knowledge graphs or model ensembles:
+```python
+from npcpy.ft.ge import GeneticEvolver, GAConfig
+
+config = GAConfig(
+    population_size=20,
+    generations=50,
+    mutation_rate=0.15
+)
+
+evolver = GeneticEvolver(
+    fitness_fn=your_fitness_function,
+    mutate_fn=your_mutation_function,
+    crossover_fn=your_crossover_function,
+    initialize_fn=your_init_function,
+    config=config
+)
+
+best_individual = evolver.run()
+```
+
+### Smart Model Ensembler and response router 
+Build fast intuitive responses with fallback to reasoning:
+```python
+from npcpy.ft.model_ensembler import (
+    ResponseRouter,
+    create_model_genome
+)
+
+genome = create_model_genome(['math', 'code', 'factual'])
+router = ResponseRouter(fast_threshold=0.8)
+
+result = router.route_query("What is 2+2?", genome)
+
+if result['used_fast_path']:
+    print("Fast gut reaction")
+elif result['used_ensemble']:
+    print("Ensemble voting")
+else:
+    print("Full reasoning")
+```
+The intention for this model ensembler system is to mimic human cognition: pattern-matched gut reactions (System 1 of Kahneman) for familiar queries, falling back to deliberate reasoning (System 2 of Kahneman) for novel problems. Genetic algorithms evolve both knowledge structures and model specializations over time.
+
+
+
 ## Serving an NPC Team
 
 `npcpy` includes a built-in Flask server that makes it easy to deploy NPC teams for production use. You can serve teams with tools, jinxs, and complex workflows that frontends can interact with via REST APIs.

{npcpy-1.2.22 → npcpy-1.2.24}/README.md

@@ -303,6 +303,152 @@ the citizens, being directed by simple and incontestable principles, may tend to
 maintenance of the Constitution, and the general happiness. ''')
 # it will play the audio automatically.
 ```
+## Fine-Tuning and Evolution
+
+`npcpy` provides modular tools for building adaptive AI systems through supervised fine-tuning, reinforcement learning, and genetic algorithms.
+
+See examples/fine_tuning_demo.py for a complete working example.
+
+
+### Supervised Fine-Tuning (SFT)
+
+Train models on specific tasks using simple X, y pairs:
+```python
+from npcpy.ft.sft import run_sft, load_sft_model, predict_sft
+
+X_train = ["translate to french: hello", "translate to french: goodbye"]
+y_train = ["bonjour", "au revoir"]
+
+model_path = run_sft(X_train, y_train)
+
+model, tokenizer = load_sft_model(model_path)
+response = predict_sft(model, tokenizer, "translate to french: thanks")
+```
+### Unsupervised Fine-Tuning (USFT)
+Adapt models to domain-specific text corpora without labels:
+```python
+from npcpy.ft.usft import run_usft, load_corpus_from_hf
+
+texts = load_corpus_from_hf("tiny_shakespeare", split="train[:1000]")
+
+model_path = run_usft(
+    texts,
+    config=USFTConfig(
+        output_model_path="models/shakespeare",
+        num_train_epochs=3
+    )
+)
+Train on your own text corpus:
+pythondomain_texts = [
+    "Your domain-specific text 1",
+    "Your domain-specific text 2",
+] * 100
+
+model_path = run_usft(domain_texts)
+```
+### Diffusion Fine-tuning
+```
+from npcpy.ft.diff import train_diffusion, generate_image
+
+image_paths = ["img1.png", "img2.png", "img3.png"]
+captions = ["a cat", "a dog", "a bird"]
+
+model_path = train_diffusion(
+    image_paths,
+    captions,
+    config=DiffusionConfig(
+        num_epochs=100,
+        batch_size=4
+    )
+)
+
+generated = generate_image(
+    model_path,
+    prompt="a white square",
+    image_size=128
+)
+Resume training from checkpoint:
+pythonmodel_path = train_diffusion(
+    image_paths,
+    captions,
+    config,
+    resume_from="models/diffusion/checkpoints/checkpoint-epoch10-step1000.pt"
+)
+```
+
+
+### Reinforcement Learning (RL)
+Collect agent traces and train with DPO based on reward signals:
+```python
+from npcpy.ft.rl import collect_traces, run_rl_training
+from npcpy.npc_compiler import NPC
+
+tasks = [
+    {'prompt': 'Solve 2+2', 'expected': '4'},
+    {'prompt': 'Solve 5+3', 'expected': '8'}
+]
+
+agents = [
+    NPC(name="farlor", primary_directive="Be concise", 
+        model="qwen3:0.6b", provider="ollama"),
+    NPC(name="tedno", primary_directive="Show your work",
+        model="qwen3:0.6b", provider="ollama")
+]
+
+def reward_fn(trace):
+    if trace['task_metadata']['expected'] in trace['final_output']:
+        return 1.0
+    return 0.0
+
+adapter_path = run_rl_training(tasks, agents, reward_fn)
+```
+### Genetic Evolution
+
+Evolve populations of knowledge graphs or model ensembles:
+```python
+from npcpy.ft.ge import GeneticEvolver, GAConfig
+
+config = GAConfig(
+    population_size=20,
+    generations=50,
+    mutation_rate=0.15
+)
+
+evolver = GeneticEvolver(
+    fitness_fn=your_fitness_function,
+    mutate_fn=your_mutation_function,
+    crossover_fn=your_crossover_function,
+    initialize_fn=your_init_function,
+    config=config
+)
+
+best_individual = evolver.run()
+```
+
+### Smart Model Ensembler and response router 
+Build fast intuitive responses with fallback to reasoning:
+```python
+from npcpy.ft.model_ensembler import (
+    ResponseRouter,
+    create_model_genome
+)
+
+genome = create_model_genome(['math', 'code', 'factual'])
+router = ResponseRouter(fast_threshold=0.8)
+
+result = router.route_query("What is 2+2?", genome)
+
+if result['used_fast_path']:
+    print("Fast gut reaction")
+elif result['used_ensemble']:
+    print("Ensemble voting")
+else:
+    print("Full reasoning")
+```
+The intention for this model ensembler system is to mimic human cognition: pattern-matched gut reactions (System 1 of Kahneman) for familiar queries, falling back to deliberate reasoning (System 2 of Kahneman) for novel problems. Genetic algorithms evolve both knowledge structures and model specializations over time.
+
+
+
 ## Serving an NPC Team
 
 `npcpy` includes a built-in Flask server that makes it easy to deploy NPC teams for production use. You can serve teams with tools, jinxs, and complex workflows that frontends can interact with via REST APIs.

npcpy-1.2.24/npcpy/ft/diff.py

@@ -0,0 +1,110 @@
+# finetuning diffuser models
+try:
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+    from torch.utils.data import DataLoader, Dataset as TorchDataset
+    from transformers import CLIPTextModel, CLIPTokenizer
+except:
+    torch = None
+    nn = None    
+    F = None
+    DataLoader = None
+    TorchDataset = None
+    CLIPTextModel = None
+    CLIPTokenizer = None
+import math
+from dataclasses import dataclass, field
+from typing import List, Optional, Callable
+import numpy as np
+from PIL import Image
+import os
+from tqdm import tqdm
+import gc
+
+
+@dataclass
+class DiffusionConfig:
+    image_size: int = 128
+    channels: int = 256
+    time_emb_dim: int = 128
+    timesteps: int = 1000
+    beta_start: float = 1e-4
+    beta_end: float = 0.02
+    num_epochs: int = 100
+    batch_size: int = 4
+    learning_rate: float = 1e-5
+    checkpoint_frequency: int = 1000
+    output_dir: str = "diffusion_model"
+    use_clip: bool = True
+    num_channels: int = 1
+
+
+class SinusoidalPositionEmbeddings(nn.Module):
+    
+    def __init__(self, dim):
+        super().__init__()
+        self.dim = dim
+
+    def forward(self, time):
+        device = time.device
+        half_dim = self.dim // 2
+        embeddings = math.log(10000) / (half_dim - 1)
+        embeddings = torch.exp(
+            torch.arange(half_dim, device=device) * -embeddings
+        )
+        embeddings = time[:, None] * embeddings[None, :]
+        embeddings = torch.cat(
+            (embeddings.sin(), embeddings.cos()),
+            dim=-1
+        )
+        return embeddings
+
+
+class SimpleUNet(nn.Module):
+    
+    def __init__(
+        self,
+        image_size=128,
+        channels=256,
+        time_emb_dim=128,
+        num_channels=1
+    ):
+        super().__init__()
+        
+        self.image_size = image_size
+        
+        self.time_mlp = nn.Sequential(
+            SinusoidalPositionEmbeddings(time_emb_dim),
+            nn.Linear(time_emb_dim, time_emb_dim * 4),
+            nn.GELU(),
+            nn.Linear(time_emb_dim * 4, channels),
+        )
+        
+        self.text_mlp = nn.Sequential(
+            nn.Linear(768, time_emb_dim),
+            nn.GELU(),
+            nn.Linear(time_emb_dim, time_emb_dim),
+            nn.GELU(),
+            nn.Linear(time_emb_dim, channels),
+        )
+        
+        self.conv_in = nn.Conv2d(num_channels, channels, 1, padding=0)
+        
+        self.down1 = nn.Sequential(
+            nn.Conv2d(channels, channels * 2, 4, 2, 1),
+            nn.GroupNorm(8, channels * 2),
+            nn.GELU(),
+        )
+        
+        self.down2 = nn.Sequential(
+            nn.Conv2d(channels * 2, channels * 4, 4, 2, 1),
+            nn.GroupNorm(8, channels * 4),
+            nn.GELU(),
+        )
+        
+        self.down3 = nn.Sequential(
+            nn.Conv2d(channels * 4, channels * 8, 4, 2, 1),
+            nn.GroupNorm(8, channels * 8),
+            nn.GELU(),
+        )

npcpy-1.2.24/npcpy/ft/ge.py

@@ -0,0 +1,115 @@
+import random
+from dataclasses import dataclass
+from typing import Callable, Optional, List
+
+
+@dataclass
+class GAConfig:
+    population_size: int = 20
+    mutation_rate: float = 0.15
+    crossover_rate: float = 0.7
+    tournament_size: int = 3
+    elitism_count: int = 2
+    generations: int = 50
+
+
+class GeneticEvolver:
+    """
+    Generic GA that takes fitness, mutation, crossover 
+    and initialization functions to evolve any population
+    """
+    def __init__(
+        self,
+        fitness_fn: Callable,
+        mutate_fn: Callable,
+        crossover_fn: Callable,
+        initialize_fn: Callable,
+        config: Optional[GAConfig] = None
+    ):
+        self.fitness_fn = fitness_fn
+        self.mutate_fn = mutate_fn
+        self.crossover_fn = crossover_fn
+        self.initialize_fn = initialize_fn
+        self.config = config or GAConfig()
+        self.population = []
+        self.history = []
+    
+    def initialize_population(self):
+        self.population = [
+            self.initialize_fn() 
+            for _ in range(self.config.population_size)
+        ]
+    
+    def evaluate_population(self) -> List[float]:
+        return [
+            self.fitness_fn(individual) 
+            for individual in self.population
+        ]
+    
+    def tournament_select(self, fitness_scores: List[float]):
+        indices = random.sample(
+            range(len(self.population)),
+            self.config.tournament_size
+        )
+        tournament_fitness = [fitness_scores[i] for i in indices]
+        winner_idx = indices[
+            tournament_fitness.index(max(tournament_fitness))
+        ]
+        return self.population[winner_idx]
+    
+    def evolve_generation(self):
+        fitness_scores = self.evaluate_population()
+        
+        sorted_pop = sorted(
+            zip(self.population, fitness_scores),
+            key=lambda x: x[1],
+            reverse=True
+        )
+        
+        new_population = [
+            ind for ind, _ in sorted_pop[:self.config.elitism_count]
+        ]
+        
+        while len(new_population) < self.config.population_size:
+            parent1 = self.tournament_select(fitness_scores)
+            parent2 = self.tournament_select(fitness_scores)
+            
+            if random.random() < self.config.crossover_rate:
+                child = self.crossover_fn(parent1, parent2)
+            else:
+                child = parent1
+            
+            if random.random() < self.config.mutation_rate:
+                child = self.mutate_fn(child)
+            
+            new_population.append(child)
+        
+        self.population = new_population[:self.config.population_size]
+        
+        best_fitness = max(fitness_scores)
+        avg_fitness = sum(fitness_scores) / len(fitness_scores)
+        
+        return {
+            'best_fitness': best_fitness,
+            'avg_fitness': avg_fitness,
+            'best_individual': sorted_pop[0][0]
+        }
+    
+    def run(self, generations: Optional[int] = None):
+        if not self.population:
+            self.initialize_population()
+        
+        gens = generations or self.config.generations
+        
+        for gen in range(gens):
+            gen_stats = self.evolve_generation()
+            self.history.append(gen_stats)
+            
+            if gen % 10 == 0:
+                print(
+                    f"Gen {gen}: "
+                    f"Best={gen_stats['best_fitness']:.3f}, "
+                    f"Avg={gen_stats['avg_fitness']:.3f}"
+                )
+        
+        return self.history[-1]['best_individual']