Metadata-Version: 2.1
Name: esperanto
Version: 0.3.0
Summary: A unified interface for various AI model providers
Home-page: https://github.com/lfnovo/esperanto
License: MIT
Keywords: ai,llm,text-to-speech,speech-to-text,openai,anthropic,google,elevenlabs
Author: LUIS NOVO
Author-email: lfnovo@gmail.com
Requires-Python: >=3.11,<3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: all
Provides-Extra: anthropic
Provides-Extra: google
Provides-Extra: ollama
Provides-Extra: openai
Provides-Extra: vertex
Requires-Dist: anthropic (>=0.39.0,<0.40.0) ; extra == "anthropic" or extra == "all"
Requires-Dist: google-generativeai (>=0.8.3,<0.9.0) ; extra == "google" or extra == "all"
Requires-Dist: langchain (>=0.3.8,<0.4.0) ; extra == "openai" or extra == "ollama" or extra == "all"
Requires-Dist: langchain-anthropic (>=0.3.0,<0.4.0) ; extra == "anthropic" or extra == "all"
Requires-Dist: langchain-ollama (>=0.2.0,<0.3.0) ; extra == "ollama" or extra == "all"
Requires-Dist: langchain-openai (>=0.2.9,<0.3.0) ; extra == "openai" or extra == "all"
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: ollama (>=0.4.1,<0.5.0) ; extra == "ollama" or extra == "all"
Requires-Dist: openai (>=1.55.1,<2.0.0) ; extra == "openai" or extra == "all"
Requires-Dist: vertexai (>=1.71.1,<2.0.0) ; extra == "vertex" or extra == "all"
Project-URL: Documentation, https://github.com/lfnovo/esperanto#readme
Project-URL: Repository, https://github.com/lfnovo/esperanto
Description-Content-Type: text/markdown

# Esperanto 🌐

[![PyPI version](https://badge.fury.io/py/esperanto.svg)](https://badge.fury.io/py/esperanto)
[![PyPI Downloads](https://img.shields.io/pypi/dm/esperanto)](https://pypi.org/project/esperanto/)
[![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen)](https://github.com/lfnovo/esperanto)
[![Python Versions](https://img.shields.io/pypi/pyversions/esperanto)](https://pypi.org/project/esperanto/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Esperanto is a powerful Python library that provides a unified interface for interacting with various Large Language Model (LLM) providers. It simplifies the process of working with different LLM APIs by offering a consistent interface while maintaining provider-specific optimizations.

## Features ✨

- **Unified Interface**: Work with multiple LLM providers using a consistent API
- **Provider Support**:
  - OpenAI (GPT-4, GPT-3.5)
  - Anthropic (Claude 3)
  - OpenRouter (Access to multiple models)
  - xAI (Grok)
  - Google (Gemini)
  - Vertex AI (Google Cloud)
  - Ollama (Local deployment)
- **Embedding Support**: Multiple embedding providers for vector representations
- **Async Support**: Both synchronous and asynchronous API calls
- **Streaming**: Support for streaming responses
- **Structured Output**: JSON output formatting (where supported)
- **LangChain Integration**: Easy conversion to LangChain chat models

For detailed information about our providers, check out:
- [LLM Providers Documentation](https://github.com/lfnovo/esperanto/blob/main/docs/llm.md)
- [Embedding Providers Documentation](https://github.com/lfnovo/esperanto/blob/main/docs/embedding.md)

## Installation 🚀

Install Esperanto using Poetry:

```bash
poetry add esperanto
```

Or with pip:

```bash
pip install esperanto
```

### Optional Dependencies

Esperanto supports multiple providers through optional dependencies. Install only what you need:

```bash
# OpenAI support
poetry add esperanto[openai]
# or pip install esperanto[openai]

# Anthropic support
poetry add esperanto[anthropic]
# or pip install esperanto[anthropic]

# Google support
poetry add esperanto[google]
# or pip install esperanto[google]

# Vertex AI support
poetry add esperanto[vertex]
# or pip install esperanto[vertex]

# Ollama support
poetry add esperanto[ollama]
# or pip install esperanto[ollama]

# Install multiple providers
poetry add "esperanto[openai,anthropic,google]"
# or pip install "esperanto[openai,anthropic,google]"

# Install all providers
poetry add "esperanto[all]"
# or pip install "esperanto[all]"
```

## Provider Support Matrix

| Provider  | LLM Support | Embedding Support |
|-----------|-------------|------------------|
| OpenAI    | ✅          | ✅               |
| Anthropic | ✅          | ❌               |
| Google    | ✅          | ✅               |
| Vertex AI | ✅          | ✅               |
| Ollama    | ✅          | ✅               |

## Quick Start 🏃‍♂️

You can use Esperanto in two ways: directly with provider-specific classes or through the AI Factory.

### Using AI Factory

```python
from esperanto.factory import AIFactory

# Create an LLM instance
model = AIFactory.create_llm("openai", "gpt-3.5-turbo")
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the capital of France?"},
]
response = model.chat_complete(messages)

# Create an embedding instance
model = AIFactory.create_embedding("openai", "text-embedding-3-small")
texts = ["Hello, world!", "Another text"]
embeddings = model.embed(texts)
```

## Standardized Responses

All providers in Esperanto return standardized response objects, making it easy to work with different models without changing your code.

### LLM Responses

```python
from esperanto.factory import AIFactory

model = AIFactory.create_llm("openai", "gpt-3.5-turbo")
messages = [{"role": "user", "content": "Hello!"}]

# All LLM responses follow this structure
response = model.chat_complete(messages)
print(response.choices[0].message.content)  # The actual response text
print(response.choices[0].message.role)     # 'assistant'
print(response.model)                       # The model used
print(response.usage.total_tokens)          # Token usage information

# For streaming responses
for chunk in model.chat_complete(messages):
    print(chunk.choices[0].delta.content)   # Partial response text
```

### Embedding Responses

```python
from esperanto.factory import AIFactory

model = AIFactory.create_embedding("openai", "text-embedding-3-small")
texts = ["Hello, world!", "Another text"]

# All embedding responses follow this structure
response = model.embed(texts)
print(response.data[0].embedding)     # Vector for first text
print(response.data[0].index)         # Index of the text (0)
print(response.model)                 # The model used
print(response.usage.total_tokens)    # Token usage information
```

The standardized response objects ensure consistency across different providers, making it easy to:
- Switch between providers without changing your application code
- Handle responses in a uniform way
- Access common attributes like token usage and model information

## Links 🔗

- **Documentation**: [GitHub Documentation](https://github.com/lfnovo/esperanto#readme)
- **Source Code**: [GitHub Repository](https://github.com/lfnovo/esperanto)
- **Issue Tracker**: [GitHub Issues](https://github.com/lfnovo/esperanto/issues)

## License 📄

This project is licensed under the MIT License - see the [LICENSE](https://github.com/lfnovo/esperanto/blob/main/LICENSE) file for details.

