docs/QUICKSTART.md

KerdosAI Quick Start Guide

Installation

Using pip (Recommended)

# Clone the repository
git clone https://github.com/bhaskarvilles/kerdosai.git
cd kerdosai

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install pytest pytest-cov black ruff mypy rich typer

Using Docker

# Build the image
docker-compose build

# Run training
docker-compose run kerdosai-train

# Start API server
docker-compose up kerdosai-api

Quick Start

1. Basic Training

# Train with default configuration
python cli.py train \
    --model gpt2 \
    --data ./data/train.json \
    --output ./output

# Train with custom configuration
python cli.py train --config configs/default.yaml

2. Using Configuration Files

Create a configuration file my_config.yaml:

base_model: "gpt2"
output_dir: "./my_output"

training:
  epochs: 5
  batch_size: 8
  learning_rate: 0.00001

lora:
  enabled: true
  r: 16
  alpha: 64

data:
  train_file: "./data/train.json"

Then train:

python cli.py train --config my_config.yaml

3. Text Generation

python cli.py generate \
    ./output \
    --prompt "Once upon a time" \
    --max-length 200 \
    --temperature 0.8

4. Model Information

# View model details
python cli.py info ./output

# View KerdosAI version
python cli.py info

Configuration Presets

KerdosAI includes several pre-configured training presets:

# Quick test (fast, minimal resources)
python cli.py train --config configs/training_presets.yaml#quick_test

# Small model (resource-constrained)
python cli.py train --config configs/training_presets.yaml#small_model

# Production (optimized settings)
python cli.py train --config configs/training_presets.yaml#production

Python API

from kerdosai.agent import KerdosAgent
from kerdosai.config import load_config

# Load configuration
config = load_config("configs/default.yaml")

# Initialize agent
agent = KerdosAgent(
    base_model="gpt2",
    training_data="./data/train.json"
)

# Prepare for efficient training
agent.prepare_for_training(
    use_lora=True,
    lora_r=8,
    use_4bit=True
)

# Train
metrics = agent.train(
    epochs=3,
    batch_size=4,
    learning_rate=2e-5
)

# Save model
agent.save("./output")

# Generate text
output = agent.generate(
    "Hello, AI!",
    max_length=100,
    temperature=0.7
)
print(output)

Data Format

KerdosAI supports various data formats:

JSON Format

[
  {"text": "First training example..."},
  {"text": "Second training example..."}
]

CSV Format

text
"First training example..."
"Second training example..."

HuggingFace Datasets

from config import KerdosConfig

config = KerdosConfig(
    base_model="gpt2",
    data=DataConfig(
        dataset_name="wikitext",
        dataset_config="wikitext-2-raw-v1"
    )
)

Advanced Features

LoRA (Low-Rank Adaptation)

config.lora.enabled = True
config.lora.r = 16  # Rank
config.lora.alpha = 64  # Alpha parameter
config.lora.dropout = 0.1

Quantization

config.quantization.enabled = True
config.quantization.bits = 4  # 4-bit or 8-bit
config.quantization.quant_type = "nf4"  # nf4 or fp4

Mixed Precision Training

config.training.fp16 = True  # For NVIDIA GPUs
# or
config.training.bf16 = True  # For newer GPUs

Monitoring

Weights & Biases

# Set API key
export WANDB_API_KEY=your_key_here

# Enable in config
python cli.py train --config configs/default.yaml

TensorBoard

# Start TensorBoard
tensorboard --logdir=./runs

# Or use Docker Compose
docker-compose up tensorboard

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=kerdosai --cov-report=html

# Run specific tests
pytest tests/test_config.py -v

Troubleshooting

Out of Memory

1. Reduce batch size: --batch-size 2
2. Enable gradient accumulation: gradient_accumulation_steps: 4
3. Use quantization: --quantize
4. Use smaller model

Slow Training

1. Enable mixed precision: fp16: true
2. Increase batch size if memory allows
3. Use multiple GPUs (see distributed training docs)

Import Errors

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Next Steps

• Read the full documentation
• Check out example notebooks
• Join our community
• Report issues on GitHub