Quick Start Guide

November 1, 2025 · View on GitHub

Get started with Esperanto in 5 minutes! This guide walks you through installation, setup, and your first AI interactions.

Installation

Install Esperanto via pip:

pip install esperanto

Optional Dependencies

For local Transformers models:

pip install "esperanto[transformers]"

For LangChain integration:

pip install "langchain>=0.3.8" "langchain-core>=0.3.29"
# Plus provider-specific packages as needed

Your First LLM Call

1. Get an API Key

For this quickstart, we'll use OpenAI. Get your API key from platform.openai.com/api-keys.

Other providers work similarly - see Provider Comparison to choose.

2. Set Environment Variable

export OPENAI_API_KEY="your-api-key-here"

Or create a .env file:

# .env
OPENAI_API_KEY=your-api-key-here

3. Generate Text

from esperanto.factory import AIFactory

# Create a language model
model = AIFactory.create_language("openai", "gpt-4")

# Have a conversation
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Esperanto?"}
]

response = model.chat_complete(messages)
print(response.content)

Output:

Esperanto is an international auxiliary language created in the late 19th century by L. L. Zamenhof...

🎉 Congratulations! You just made your first AI call with Esperanto.

More Examples

Text Embeddings

Convert text to vectors for semantic search:

from esperanto.factory import AIFactory

# Create an embedding model
embedder = AIFactory.create_embedding("openai", "text-embedding-3-small")

# Generate embeddings
texts = [
    "Esperanto is a universal AI interface",
    "Python is a programming language"
]

response = embedder.embed(texts)
vectors = [item.embedding for item in response.data]

print(f"Generated {len(vectors)} vectors")
print(f"Vector dimension: {len(vectors[0])}")

Speech-to-Text

Transcribe audio files:

from esperanto.factory import AIFactory

# Create a transcriber
transcriber = AIFactory.create_speech_to_text("openai", "whisper-1")

# Transcribe audio
transcript = transcriber.transcribe("meeting_recording.mp3")
print(transcript)

Text-to-Speech

Generate natural-sounding audio:

from esperanto.factory import AIFactory

# Create a TTS model
speaker = AIFactory.create_text_to_speech("openai", "tts-1")

# Generate speech
audio_bytes = speaker.generate_speech(
    text="Hello! This is Esperanto text to speech.",
    voice="nova"
)

# Save to file
with open("output.mp3", "wb") as f:
    f.write(audio_bytes)

Reranking

Improve search relevance:

from esperanto.factory import AIFactory

# Create a reranker
reranker = AIFactory.create_reranker("jina", "jina-reranker-v2-base-multilingual")

# Rerank documents
query = "What is machine learning?"
documents = [
    "Machine learning is a subset of artificial intelligence",
    "The weather is nice today",
    "Python is used in ML development"
]

response = reranker.rerank(query, documents, top_k=2)

for result in response.results:
    print(f"Score: {result.relevance_score:.4f} - {result.document}")

Switching Providers

The beauty of Esperanto is that switching providers is as simple as changing two parameters:

# OpenAI
model = AIFactory.create_language("openai", "gpt-4")

# Switch to Anthropic
model = AIFactory.create_language("anthropic", "claude-3-5-sonnet-20241022")

# Switch to Google
model = AIFactory.create_language("google", "gemini-pro")

# Switch to local Ollama
model = AIFactory.create_language("ollama", "llama3.2")

# Everything else stays the same!
messages = [{"role": "user", "content": "Hello!"}]
response = model.chat_complete(messages)

No code changes needed - just provider name and model!

Common Configurations

Streaming Responses

Get responses token by token:

model = AIFactory.create_language(
    "openai", "gpt-4",
    config={"streaming": True}
)

messages = [{"role": "user", "content": "Write a haiku about coding"}]

for chunk in model.chat_complete(messages):
    print(chunk.choices[0].delta.content, end="", flush=True)

JSON Output

Request structured JSON responses:

model = AIFactory.create_language(
    "openai", "gpt-4",
    config={"structured": {"type": "json"}}
)

messages = [{
    "role": "user",
    "content": "List three programming languages in JSON format"
}]

response = model.chat_complete(messages)
print(response.content)  # Valid JSON string

Temperature Control

Adjust creativity (0.0 = deterministic, 2.0 = very creative):

model = AIFactory.create_language(
    "openai", "gpt-4",
    config={"temperature": 0.3}  # More focused
)

# Or per-request
response = model.chat_complete(messages, temperature=0.9)  # More creative

Async Operations

For better performance with multiple requests:

import asyncio
from esperanto.factory import AIFactory

async def main():
    model = AIFactory.create_language("openai", "gpt-4")

    messages = [{"role": "user", "content": "Hello!"}]

    # Async call
    response = await model.achat_complete(messages)
    print(response.content)

asyncio.run(main())

Multi-Capability Example

Use multiple AI capabilities together:

from esperanto.factory import AIFactory

# Create models for different capabilities
llm = AIFactory.create_language("openai", "gpt-4")
embedder = AIFactory.create_embedding("openai", "text-embedding-3-small")
speaker = AIFactory.create_text_to_speech("openai", "tts-1")

# 1. Generate text with LLM
messages = [{"role": "user", "content": "Explain quantum computing in one sentence"}]
explanation = llm.chat_complete(messages).content

# 2. Create embeddings for search
texts = [explanation, "Quantum computers use qubits"]
embeddings = embedder.embed(texts)

# 3. Convert to speech
audio = speaker.generate_speech(explanation, voice="nova")
with open("explanation.mp3", "wb") as f:
    f.write(audio)

print(f"Generated explanation: {explanation}")
print(f"Created {len(embeddings.data)} embeddings")
print("Saved audio to explanation.mp3")

Local Models (No API Costs!)

Use local models for privacy and zero API costs:

from esperanto.factory import AIFactory

# Local LLM with Ollama (requires ollama installed)
llm = AIFactory.create_language("ollama", "llama3.2")

# Local embeddings with Transformers
embedder = AIFactory.create_embedding(
    "transformers",
    "BAAI/bge-base-en-v1.5"
)

# Local reranking
reranker = AIFactory.create_reranker(
    "transformers",
    "BAAI/bge-reranker-base"
)

# Use exactly like cloud models!
response = llm.chat_complete([{"role": "user", "content": "Hello!"}])

RAG (Retrieval-Augmented Generation) Pipeline

Complete RAG in 20 lines:

from esperanto.factory import AIFactory

# Setup models
embedder = AIFactory.create_embedding("openai", "text-embedding-3-small")
reranker = AIFactory.create_reranker("jina", "jina-reranker-v2-base-multilingual")
llm = AIFactory.create_language("anthropic", "claude-3-5-sonnet-20241022")

# Your knowledge base
documents = [
    "Esperanto is a universal AI interface for Python",
    "It supports 17 different AI providers",
    "You can switch providers without changing code"
]

# User query
query = "What is Esperanto?"

# Step 1: Embed and retrieve (simplified - normally you'd use vector DB)
doc_embeddings = embedder.embed(documents)
query_embedding = embedder.embed([query])
# ... compute similarity and get top candidates ...

# Step 2: Rerank for accuracy
reranked = reranker.rerank(query, documents, top_k=2)
context = "\n".join([r.document for r in reranked.results])

# Step 3: Generate answer with LLM
messages = [{
    "role": "user",
    "content": f"Context:\n{context}\n\nQuestion: {query}"
}]
answer = llm.chat_complete(messages)

print(answer.content)

Error Handling

Always handle potential errors:

from esperanto.factory import AIFactory

try:
    model = AIFactory.create_language("openai", "gpt-4")
    messages = [{"role": "user", "content": "Hello!"}]
    response = model.chat_complete(messages)
    print(response.content)

except ValueError as e:
    print(f"Configuration error: {e}")
except Exception as e:
    print(f"API error: {e}")

Environment Setup Best Practices

Create a .env file for your API keys:

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
GROQ_API_KEY=...

# Optional timeout overrides
ESPERANTO_LLM_TIMEOUT=90
ESPERANTO_EMBEDDING_TIMEOUT=120

Then load in your Python code:

from dotenv import load_dotenv
load_dotenv()

# API keys are now available to Esperanto

Next Steps

Now that you've got the basics, explore more:

Learn Capabilities

Language Models Guide - Complete LLM documentation
Embeddings Guide - Semantic search and vectors
Reranking Guide - Improve search relevance
Speech-to-Text Guide - Audio transcription
Text-to-Speech Guide - Voice generation

Choose Providers

Provider Comparison - Compare all 17 providers
Provider Setup Guides - Detailed setup for each provider

Advanced Features

Task-Aware Embeddings - Optimize for specific tasks
LangChain Integration - Use with LangChain
Timeout Configuration - Control request timeouts
Model Discovery - Discover available models
Transformers Features - Advanced local model features

Configuration

Configuration Guide - Complete configuration reference

Get Help

Documentation Index - All documentation
GitHub Issues - Report bugs or ask questions
Changelog - Version history

Questions? Check the Documentation Index or Provider Comparison.