ml/QUICK_START.md

Quick Start Guide

Installation

For Python Development

# Install VRAM coordination
pip install lilith-vram-boss

# Install RAM coordination + cache management
pip install lilith-ram-boss

# Install model loading (uses vram-boss internally)
pip install lilith-model-boss

For CLI Usage (Recommended)

# Install global CLI
npm install -g @lilith/bitch --registry=http://forge.nasty.sh/api/packages/lilith/npm/

# Install Python backends
pip install lilith-vram-boss lilith-ram-boss

---

Common Tasks

Check System Resources

# Via bitch CLI (recommended)
bitch ram status         # RAM usage and leases
bitch vram status        # GPU usage and leases

# Direct
ram-boss status
vram-boss status

Analyze Memory

# Via bitch CLI
bitch ram analyze --processes --leaks

# Direct
ram-boss analyze --processes --leaks

Clear RAM Caches

# Via bitch CLI
bitch ram clear auto            # Auto-detect mode
bitch ram clear aggressive      # Maximum cleanup

# Direct
sudo ram-boss clear auto

GPU Coordination

# Via bitch CLI
bitch vram drain                # Unload all GPU models
bitch vram cleanup              # Clean stale leases
bitch vram diagnose             # Diagnose issues

# Direct
vram-boss drain
vram-boss cleanup

---

Python Usage

Load Model with GPU Coordination

from lilith_vram_boss import GPUBoss
from lilith_model_boss import ManagedModelLoader

# Create GPU coordinator
boss = GPUBoss()
await boss.connect()

# Load model with automatic VRAM lease
loader = ManagedModelLoader(boss=boss)
model = await loader.load("deepseek-r1", vram_mb=8000)

# Model is now loaded with VRAM reserved
await boss.close()

Coordinate RAM Usage

from lilith_ram_boss import RAMBoss

# Create RAM coordinator
boss = RAMBoss()
await boss.connect()

# Reserve RAM before loading large dataset
async with boss.acquire(ram_mb=16000, process_id="data-loader") as lease:
    # RAM is reserved, safe to load
    data = load_large_dataset()
    process(data)
    # Lease automatically released on exit

await boss.close()

Memory Analysis

from lilith_ram_boss import MemoryAnalyzer, PressureLevel

# Analyze system memory
analyzer = MemoryAnalyzer()
analysis = analyzer.analyze()

print(f"Total: {analysis.total_mb} MB")
print(f"Available: {analysis.available_mb} MB")
print(f"Pressure: {analysis.pressure.value}")

if analysis.pressure in [PressureLevel.MODERATE, PressureLevel.CRITICAL]:
    print(f"Recommended: Clear RAM with {analysis.recommended_cleanup_mode} mode")

Cache Cleanup

from lilith_ram_boss import CacheManager, CleanupMode

manager = CacheManager()

# Auto mode (detects pressure and chooses mode)
freed_mb = manager.cleanup(mode=CleanupMode.AUTO)
print(f"Freed {freed_mb} MB")

# Or specify mode
freed_mb = manager.cleanup(mode=CleanupMode.AGGRESSIVE)

---

TypeScript Usage

GPU Coordination

import { GPUBoss, Priority } from '@lilith/ml-vram-boss';

const boss = new GPUBoss();
await boss.connect();

// Acquire VRAM lease
const lease = await boss.acquire({
  vramMb: 8000,
  priority: Priority.NORMAL,
  modelId: 'llm',
});

try {
  // Load your model
  await loadModel();

  // Use model
  const result = await model.generate();
} finally {
  await lease.release();
  await boss.close();
}

RAM Coordination

import { RAMBoss, Priority } from '@lilith/ml-ram-boss';

const boss = new RAMBoss();
await boss.connect();

// Acquire RAM lease
const lease = await boss.acquire({
  ramMb: 16000,
  priority: Priority.NORMAL,
  processId: 'data-processor',
});

try {
  // Process data
  const data = await loadLargeDataset();
  await processData(data);
} finally {
  await lease.release();
  await boss.close();
}

---

CLI Reference

bitch CLI (Unified Interface)

# VRAM commands
bitch vram status                  # Show GPU status
bitch vram cleanup                 # Clean stale leases
bitch vram drain [--force]         # Unload models
bitch vram kill <lease-id>         # Kill specific lease
bitch vram init-gpu <idx> <mb>     # Initialize GPU
bitch vram diagnose [--verbose]    # Diagnose issues

# RAM commands
bitch ram status                   # Show RAM status
bitch ram analyze                  # Memory analysis
bitch ram analyze --processes      # Top consumers
bitch ram analyze --leaks          # Leak detection
bitch ram clear <mode>             # Clear caches
bitch ram cleanup                  # Clean stale leases

Direct CLI Access

# Direct access still works
vram-boss <command>                # Same as: bitch vram <command>
ram-boss <command>                 # Same as: bitch ram <command>

---

Troubleshooting

Check Installation

# Check if CLIs are installed
which bitch vram-boss ram-boss

# Check Python packages
pip list | grep -E "(vram|ram|model)-boss"

# Check if Redis is running (required for coordination)
redis-cli ping

Common Issues

"vram-boss command not found"

pip install lilith-vram-boss

"ram-boss command not found"

pip install lilith-ram-boss

"Permission denied" when clearing RAM

sudo bitch ram clear auto          # Cache cleanup requires root

Redis connection failed

# Check Redis is running
systemctl status redis
# Or start Redis
redis-server

---

Next Steps

• See ARCHITECTURE.md for detailed usage patterns
• See IMPLEMENTATION_SUMMARY.md for package details
• Check individual package READMEs:
  • vram-boss
  • ram-boss
  • model-boss