repository·main·Indexed 42 days ago
https://github.com/lfnovo/esperantoA lightweight, production-ready Python library providing a unified interface for AI model providers including OpenAI, Anthropic, Google, and local options like Ollama and Transformers. Version 2.27.0 uses direct HTTP communication via httpx to minimize dependencies. It supports LLMs, Embeddings, Reranking, Speech-to-Text (STT), and Text-to-Speech (TTS) through a standardized AIFactory pattern and unified tool calling.
Esperanto provides a unified interface for the following AI capabilities:
The openai-compatible provider allows you to connect to any service implementing the OpenAI API format. This is ideal for local deployments (like LM Studio, Ollama, vLLM, or LocalAI) and custom cloud services.
Supported Capabilities:
To use a local service like LM Studio, ensure the server is running (e.g., at http://localhost:1234) before attempting to connect.
from esperanto.factory import AIFactory
# Language model
model = AIFactory.create_language(
"openai-compatible",
"your-model-name",
config={"base_url": "http://localhost:1234/v1"}
)When working with the transformers provider, consider the following for resource management:
Qwen/Qwen3-Embedding-4B require significant GPU memory.sentence-transformers/all-MiniLM-L6-v2) and force the device to cpu.output_dimensions can help manage memory.model.embed(list_of_texts)) instead of individual calls for better efficiency.HF_HOME environment variable to change the cache location.# Set custom cache directory
export HF_HOME=/path/to/cache# For limited memory environments
model = AIFactory.create_embedding(
"transformers",
"sentence-transformers/all-MiniLM-L6-v2",
config={
"device": "cpu",
"output_dimensions": 256
}
)
# Efficient batch processing
texts = ["text1", "text2", "text3"]
embeddings = model.embed(texts)Esperanto distinguishes between two types of non-standard behavior to maintain a reliable API:
temperature and top_p simultaneously), the provider's request-builder will automatically sanitize the request and log a debug message. You do not need to manually handle these quirks in your application code.Esperanto supports specialized environment variables for OpenAI-compatible providers to allow granular configuration of different model types (LLM, Embedding, STT, TTS).
When configuring an OpenAI-compatible provider, you can use generic variables or type-specific variables. The precedence order for configuration is:
OPENAI_COMPATIBLE_BASE_URL_LLM)OPENAI_COMPATIBLE_BASE_URL) - Lowest priority### Precedence Order (Highest to Lowest):
1. Direct Parameters
2. Config Dict
3. `OPENAI_COMPATIBLE_<TYPE>_BASE_URL` / `OPENAI_COMPATIBLE_<TYPE>_API_KEY`
4. `OPENAI_COMPATIBLE_BASE_URL` / `OPENAI_COMPATIBLE_API_KEY`All reranker providers return a standardized RerankResponse object. The results attribute contains a list of objects with the following fields:
document: The original text of the document.relevance_score: A normalized score between 0.0 and 1.0 (higher is more relevant).index: The original position of the document in the input list.The response also includes a model field indicating the model name used.
Note on Scores: Scores are relative within a single rerank call and are always sorted by score in descending order.
response = reranker.rerank(query, documents, top_k=3)
# Accessing fields
first_doc = response.results[0].document
first_score = response.results[0].relevance_score
first_index = response.results[0].index
model_used = response.modelAll model methods in Esperanto have asynchronous equivalents. To use the async version of a method, prefix the method name with a and use the await keyword.
Example:
# Synchronous call
response = model.chat_complete(messages)
# Asynchronous call
response = await model.achat_complete(messages)response = await model.achat_complete(messages)Jina supports native task optimization. Use EmbeddingTaskType to map your intent to the correct Jina API parameter. This is highly recommended for RAG systems to ensure queries and documents are in the same vector space.
Task Type Mappings:
EmbeddingTaskType.RETRIEVAL_QUERY $\rightarrow$ "retrieval.query" (Optimize for search queries)EmbeddingTaskType.RETRIEVAL_DOCUMENT $\rightarrow$ "retrieval.passage" (Optimize for document storage)EmbeddingTaskType.CLASSIFICATION $\rightarrow$ "classification"EmbeddingTaskType.CLUSTERING $\rightarrow$ "separation"EmbeddingTaskType.SIMILARITY $\rightarrow$ "text-matching"EmbeddingTaskType.CODE_RETRIEVAL $\rightarrow$ "code.query" (Optimize for code search)from esperanto.common_types.task_type import EmbeddingTaskType
from esperanto.factory import AIFactory
# Optimize for search queries
query_model = AIFactory.create_embedding(
"jina",
"jina-embeddings-v3",
config={"task_type": EmbeddingTaskType.RETRIEVAL_QUERY}
)
# Optimize for document storage
document_model = AIFactory.create_embedding(
"jina",
"jina-embeddings-v3",
config={"task_type": EmbeddingTaskType.RETRIEVAL_DOCUMENT}
)Task-aware embeddings optimize vector representations for specific semantic purposes rather than using a single generic model for all inputs. This is crucial because queries (short, intent-focused) and documents (long, information-rich) have different semantic patterns. Using specialized task types can improve search relevance by 15-30%.
Esperanto provides a unified interface to apply these optimizations across different providers, whether they support it natively (like Jina or Google) or via intelligent prefix emulation (like OpenAI).
In Azure OpenAI, you interact with deployment names rather than the underlying model names. When using Esperanto, the model_name parameter (or the second argument in AIFactory methods) must correspond to your specific Azure deployment name.
For example, if your GPT-4 deployment is named my-gpt4-deployment, you must use that string in your code.
# Correct usage using the deployment name
model = AIFactory.create_language("azure", "my-gpt4-deployment")You can discover available voices in two ways:
DEEPGRAM_VOICES constant in esperanto.providers.tts.deepgram.available_voices property on an existing model instance.Deepgram supports the Aura-2 family (English, Spanish, French, German, Italian, Japanese, Dutch) and the legacy Aura-1 family (English only).
When configuring timeouts in Esperanto, follow these guidelines:
groq at 30s) and longer timeouts for slower providers (e.g., anthropic at 120s).ESPERANTO_LLM_TIMEOUT and ESPERANTO_EMBEDDING_TIMEOUT to simplify configuration.