gptperoz 0.2.3

Alchemy Learning Framework (AL) - Complete Guide

---

📦 Installation

pip install gptperoz

---

🚀 Quick Start

import al

# 3 lines to AI
ai = al.make("my_ai")                    # Create AI
ai.learn("data.json", epochs=10)         # Train it
print(ai.chat("Hello!"))                 # Use it

---

📚 Complete API Reference

🎯 Core Functions

Function Description Example al.make(name, device) Create new AI instance ai = al.make("bot", device='cuda') al.quick(data, epochs, name) Create + train in one line ai = al.quick("data.json", epochs=5) al.load(path) Load saved .llk model ai = al.load("model.llk") al.version Get framework version print(al.version) al.DEVICE Check current device print(al.DEVICE)

---

🤖 AI Class Methods

ai.learn(data_source, epochs=10, lr=0.01, **kwargs)

Train the AI on your dataset.

# From JSON file
ai.learn("conversations.json", epochs=20, lr=0.001)

# From list
data = [{"input": "hello", "output": "hi"}]
ai.learn(data, epochs=5)

# From text file (auto-converts Q&A)
ai.learn("dialogues.txt", epochs=15)

# With custom config
ai.learn("data.json", epochs=30, lr=0.0005, batch_size=16)

Parameter Type Default Description data_source str/list Required JSON file, list, or text file epochs int 10 Training rounds lr float 0.01 Learning rate batch_size int 16 Samples per batch

---

ai.chat(prompt, max_len=50, temp=0.8, use_cache=True)

Generate a response from the AI.

# Basic chat
response = ai.chat("Hello, how are you?")

# With custom settings
response = ai.chat(
    prompt="Tell me a story",
    max_len=200,      # Longer response
    temp=0.9,         # More creative
    use_cache=True    # Cache responses
)

# Deterministic (temp=0)
response = ai.chat("What is 2+2?", temp=0)

Parameter Type Default Description prompt str "" Input text max_len int 50 Maximum response length temp float 0.8 Temperature (0=deterministic, 1=creative) use_cache bool True Cache responses for speed

---

ai.save(path)

Save trained model to .llk file.

# Basic save
ai.save("my_model.llk")

# Auto-adds .llk extension
ai.save("my_model")  # Saves as my_model.llk

---

ai.load(path)

Load a saved model.

ai = al.load("my_model.llk")
print(ai.chat("Hello!"))

---

ai.add_pattern(pattern, response)

Add deterministic pattern matching.

# Exact match responses
ai.add_pattern("hello", "Hi there! How can I help?")
ai.add_pattern("bye", "Goodbye! Have a great day!")
ai.add_pattern("what is your name", "I'm AL, your AI assistant!")

# These will always return the exact response
print(ai.chat("hello"))  # "Hi there! How can I help?"

---

ai.add_rule(condition, action)

Add conditional logic rules.

# Respond based on condition
ai.add_rule("'weather' in text", "I can't check weather, but look outside!")
ai.add_rule("len(text) < 3", "That's a short message!")
ai.add_rule("'?' in text", lambda t: f"You asked: {t}")

---

ai.info()

Display model information.

ai.info()

# Output:
# AL v10.0.0
# Device: cuda
# Vocab: 1250 tokens
# Config: dim=256, layers=6
# Trained: True
# Final Loss: 1.2345
# Patterns: 5
# Cache: 23 items

---

ai.clear_cache()

Clear response cache.

ai.clear_cache()  # Fresh responses

---

⚙️ Model Configuration

Access and modify model settings through ai.config:

ai = al.make("bot")

# View config
print(ai.config)

# Modify before training
ai.config.update({
    'dim': 512,      # Embedding dimension
    'layers': 12,    # Transformer layers
    'heads': 8       # Attention heads
})

# Then train
ai.learn("data.json")

Config Key Default Description dim 64 Embedding dimension layers 2 Number of transformer layers heads 4 Attention heads vocab_size auto Vocabulary size (auto-built)

---

📊 Training History

Access training metrics:

ai = al.load("model.llk")

# Loss history
print(ai.history['loss'])   # [4.523, 3.891, 3.445, ...]

# Perplexity history
print(ai.history['ppl'])    # [92.15, 48.96, 31.34, ...]

# Final metrics
print(f"Final Loss: {ai.history['loss'][-1]:.4f}")
print(f"Final PPL: {ai.history['ppl'][-1]:.2f}")

---

📁 Data Format

JSON Format (Recommended)

[
    {"input": "hello", "output": "Hi there!"},
    {"input": "how are you", "output": "I'm great!"},
    {"input": "what is AI", "output": "Artificial Intelligence"}
]

Text Format (Auto-converted)

hello
Hi there!
how are you
I'm great!
what is AI
Artificial Intelligence

---

🎮 Complete Examples

Example 1: Basic Chatbot

import al
import json

# Training data
data = [
    {"input": "hello", "output": "Hi! How can I help?"},
    {"input": "bye", "output": "Goodbye!"}
]

with open("chat.json", "w") as f:
    json.dump(data, f)

# Train
ai = al.quick("chat.json", epochs=10)

# Chat
while True:
    user = input("You: ")
    if user == "quit": break
    print(f"AI: {ai.chat(user)}")

Example 2: Load and Continue Training

import al

# Load existing model
ai = al.load("base_model.llk")

# Continue training with new data
ai.learn("new_data.json", epochs=5)

# Save updated model
ai.save("updated_model.llk")

Example 3: Custom Configuration

import al

# Create with custom config
ai = al.make("large_bot")
ai.config.update({'dim': 512, 'layers': 12, 'heads': 8})

# Train
ai.learn("big_dataset.json", epochs=30, lr=0.0005)

# Add patterns
ai.add_pattern("hello", "Hello! I'm a large language model.")
ai.add_pattern("help", "I can assist with coding, questions, and more!")

# Save
ai.save("large_bot.llk")

Example 4: Multiple Models

import al

# Load different models
coder = al.load("coder.llk")
chatbot = al.load("chatbot.llk")
teacher = al.load("teacher.llk")

def smart_response(prompt):
    if "code" in prompt or "function" in prompt:
        return coder.chat(prompt)
    elif "learn" in prompt or "explain" in prompt:
        return teacher.chat(prompt)
    else:
        return chatbot.chat(prompt)

print(smart_response("write a python function"))
print(smart_response("explain quantum physics"))
print(smart_response("hello how are you"))

---

🔧 Troubleshooting

Issue Solution Training too slow Reduce dim, layers, or sample size Out of memory Use smaller batch_size Poor responses Increase epochs, add more data Repetitive output Increase temp (0.8-1.0) CUDA errors Set device='cpu'

---

📈 Performance Tips

# For speed (development)
ai.config.update({'dim': 128, 'layers': 3})
ai.learn(data, epochs=5)

# For quality (production)
ai.config.update({'dim': 512, 'layers': 12})
ai.learn(data, epochs=50, lr=0.0001)

# For mobile/edge
ai.config.update({'dim': 64, 'layers': 2})

---

🎯 Quick Reference Card

import al

# Create & Train
ai = al.quick("data.json", epochs=10)

# Chat
response = ai.chat("Hello")

# Save
ai.save("model.llk")

# Load
ai = al.load("model.llk")

# Patterns
ai.add_pattern("hi", "Hello!")

# Info
ai.info()

# Clear cache
ai.clear_cache()

---