Skip to content

Quick Start Guide

Get started with SteadyText in minutes. Learn how to use custom seeds for reproducible AI generation.

Prerequisites

  • Python: 3.10 or later (3.11 recommended)
  • RAM: Minimum 4GB (8GB+ recommended for large models)
  • Disk Space: 5-15GB for model storage
  • OS: Linux, macOS, or Windows

Installation

# Install UV first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Then install SteadyText
uv add steadytext

pip install steadytext

poetry add steadytext

First Steps

First Run

On first use, SteadyText will download the required models (~5GB total). This is a one-time process. Models are stored in: - Linux/Mac: ~/.cache/steadytext/models/ - Windows: %LOCALAPPDATA%\steadytext\steadytext\models\

1. Basic Text Generation

import steadytext

# Generate deterministic text (always same result)
text = steadytext.generate("Write a Python function to calculate fibonacci")
print(text)

# Use custom seed for different but reproducible results
text1 = steadytext.generate("Write a Python function", seed=123)
text2 = steadytext.generate("Write a Python function", seed=123)  # Same as text1
text3 = steadytext.generate("Write a Python function", seed=456)  # Different result

print(f"Same seed results identical: {text1 == text2}")  # True
print(f"Different seeds produce different output: {text1 != text3}")  # True

2. Streaming Generation

For real-time output:

# Default streaming
for token in steadytext.generate_iter("Explain machine learning"):
    print(token, end="", flush=True)

# Streaming with custom seed for reproducible streams
print("\nStream 1 (seed 789):")
for token in steadytext.generate_iter("Tell me a joke", seed=789):
    print(token, end="", flush=True)

print("\nStream 2 (same seed - identical result):")
for token in steadytext.generate_iter("Tell me a joke", seed=789):
    print(token, end="", flush=True)

3. Create Embeddings

# Single text (deterministic)
vector = steadytext.embed("Hello world")
print(f"Embedding shape: {vector.shape}")  # (1024,)

# Multiple texts (returns a single, averaged embedding)
vector = steadytext.embed(["Hello", "world", "AI"])

# Custom seeds for different embedding variations
vec1 = steadytext.embed("artificial intelligence", seed=100)
vec2 = steadytext.embed("artificial intelligence", seed=100)  # Identical
vec3 = steadytext.embed("artificial intelligence", seed=200)  # Different

import numpy as np
print(f"Same seed embeddings equal: {np.array_equal(vec1, vec2)}")  # True
print(f"Different seed similarity: {np.dot(vec1, vec3):.3f}")  # Cosine similarity

Command Line Usage

SteadyText includes both steadytext and st commands:

# Generate text (deterministic)
st generate "write a haiku about programming"

# Generate with custom seed for reproducible variations
st generate "write a haiku about programming" --seed 123
st generate "write a haiku about programming" --seed 456  # Different result

# Stream generation with seed
echo "explain quantum computing" | st --seed 789

# Create embeddings with custom seed
st embed "machine learning concepts" --seed 100

# JSON output with metadata
st generate "list 3 colors" --json --seed 555

# Control output length
st generate "explain AI" --max-new-tokens 100 --seed 42

# Vector operations with seeds
st vector similarity "cat" "dog" --seed 777

# Preload models (optional)
st models --preload

Model Management

Models are automatically downloaded on first use to:

  • Linux/Mac: ~/.cache/steadytext/models/
  • Windows: %LOCALAPPDATA%\steadytext\steadytext\models\
# Check where models are stored
cache_dir = steadytext.get_model_cache_dir()
print(f"Models stored at: {cache_dir}")

# Preload models manually (optional)
steadytext.preload_models(verbose=True)

Configuration

Control caching and behavior via environment variables:

# Generation cache settings
export STEADYTEXT_GENERATION_CACHE_CAPACITY=512
export STEADYTEXT_GENERATION_CACHE_MAX_SIZE_MB=100

# Embedding cache settings  
export STEADYTEXT_EMBEDDING_CACHE_CAPACITY=1024
export STEADYTEXT_EMBEDDING_CACHE_MAX_SIZE_MB=200

# Model compatibility settings
export STEADYTEXT_USE_FALLBACK_MODEL=true  # Use compatible models

# Default seed (optional)
export STEADYTEXT_DEFAULT_SEED=42

Common Patterns

Reproducible Research

# Document your seeds for reproducibility
RESEARCH_SEED = 42

results = []
for prompt in research_prompts:
    result = steadytext.generate(prompt, seed=RESEARCH_SEED)
    results.append(result)
    RESEARCH_SEED += 1  # Increment for each generation

A/B Testing

# Generate content variations
prompt = "Write a product description"
variant_a = steadytext.generate(prompt, seed=100)  # Version A
variant_b = steadytext.generate(prompt, seed=200)  # Version B

# Test which performs better
print(f"Variant A: {variant_a[:100]}...")
print(f"Variant B: {variant_b[:100]}...")

Content Variations

# Generate multiple versions for testing
base_prompt = "Explain machine learning"
variations = []

for i, style_seed in enumerate([300, 400, 500], 1):
    variation = steadytext.generate(base_prompt, seed=style_seed)
    variations.append(f"Version {i}: {variation}")

for variation in variations:
    print(variation[:80] + "...\n")

PostgreSQL Integration

SteadyText now includes a PostgreSQL extension:

# Install the PostgreSQL extension
git clone https://github.com/julep-ai/steadytext.git
cd steadytext/pg_steadytext
make && sudo make install

# Enable in PostgreSQL
psql -c "CREATE EXTENSION pg_steadytext CASCADE;"

-- Use in SQL queries
SELECT steadytext_generate('Write a product description', max_tokens := 200, seed := 123);

-- Generate embeddings
SELECT steadytext_embed('machine learning', seed := 456);

-- Semantic search with pgvector
SELECT title, content <-> steadytext_embed('AI technology') AS distance
FROM documents
ORDER BY distance
LIMIT 5;

Next Steps

Common Issues and Solutions

Model Loading Errors

If you see "Failed to load model": 

# Use fallback models
export STEADYTEXT_USE_FALLBACK_MODEL=true

# Or clear model cache and re-download
rm -rf ~/.cache/steadytext/models/

llama-cpp-python Build Issues

If installation fails with llama-cpp-python errors: 

# Set required build flags
export FORCE_CMAKE=1
export CMAKE_ARGS="-DLLAVA_BUILD=OFF -DGGML_ACCELERATE=OFF -DGGML_BLAS=OFF -DGGML_CUDA=OFF"

# Then reinstall
pip install --force-reinstall steadytext

Daemon Connection Issues

# Check if daemon is running
st daemon status

# Start daemon if not running
st daemon start

# Or disable daemon and use direct loading
export STEADYTEXT_DISABLE_DAEMON=1

Need Help?