Environment Variables

Mistral

Overview

Mistral AI provides high-performance language models and embeddings with a focus on efficiency, multilingual capabilities, and European data residency. Their models are known for excellent performance-to-cost ratios.

Supported Capabilities:

Official Documentation: https://docs.mistral.ai

Prerequisites

Account Requirements

• Mistral AI account (sign up at https://console.mistral.ai)
• API key with credits or billing enabled

Getting API Keys

1. Visit https://console.mistral.ai/api-keys
2. Click "Create new key"
3. Copy and store the key securely

Environment Variables

# Mistral API key (required)
MISTRAL_API_KEY="..."

Variable Priority:

1. Direct parameter in code (api_key="...")
2. Environment variable (MISTRAL_API_KEY)

Quick Start

Via Factory (Recommended)

from esperanto.factory import AIFactory

# Language model
model = AIFactory.create_language("mistral", "mistral-large-latest")

# Embedding model
embedder = AIFactory.create_embedding("mistral", "mistral-embed")

Direct Instantiation

from esperanto.providers.llm.mistral import MistralLanguageModel
from esperanto.providers.embedding.mistral import MistralEmbeddingModel

# Language model
llm = MistralLanguageModel(
    api_key="your-api-key",
    model_name="mistral-large-latest"
)

# Embedding model
embedder = MistralEmbeddingModel(
    api_key="your-api-key",
    model_name="mistral-embed"
)

Capabilities

Language Models (LLM)

Available Models:

Configuration:

from esperanto.factory import AIFactory

model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={
        "temperature": 0.7,           # Randomness (0.0 - 1.0)
        "max_tokens": 1000,           # Maximum response length
        "top_p": 0.9,                 # Nucleus sampling
        "streaming": True,            # Enable streaming
        "structured": {"type": "json"}, # JSON mode
        "timeout": 60.0               # Request timeout
    }
)

Example - Basic Chat:

from esperanto.factory import AIFactory

# Create Mistral model
model = AIFactory.create_language("mistral", "mistral-large-latest")

# Chat completion
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the capital of France?"}
]

response = model.chat_complete(messages)
print(response.choices[0].message.content)

Example - Streaming:

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

# Async streaming
async for chunk in model.achat_complete(messages, stream=True):
    print(chunk.choices[0].delta.content, end="", flush=True)

Example - JSON Mode:

# Enable JSON output
model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={"structured": {"type": "json"}}
)

messages = [{
    "role": "user",
    "content": "List three European capitals as JSON with country and capital"
}]

response = model.chat_complete(messages)
print(response.choices[0].message.content)
# Response will be valid JSON

Example - Code Generation:

# Use Codestral for code tasks
code_model = AIFactory.create_language("mistral", "codestral-latest")

messages = [{
    "role": "user",
    "content": "Write a Python function to calculate Fibonacci numbers"
}]

response = code_model.chat_complete(messages)
print(response.choices[0].message.content)

Example - Multilingual:

# Mistral models excel at multilingual tasks
model = AIFactory.create_language("mistral", "mistral-large-latest")

messages = [
    {"role": "user", "content": "Explain quantum computing in French"}
]

response = model.chat_complete(messages)
print(response.choices[0].message.content)

Example - Async Chat:

async def chat_async():
    model = AIFactory.create_language("mistral", "mistral-large-latest")

    messages = [{"role": "user", "content": "Explain machine learning"}]
    response = await model.achat_complete(messages)
    print(response.choices[0].message.content)

# Run async
# await chat_async()

Example - Temperature Control:

# More creative (higher temperature)
creative_model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={"temperature": 1.0, "max_tokens": 1024}
)

# More focused (lower temperature)
focused_model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={"temperature": 0.2, "max_tokens": 1024}
)

Example - Multi-turn Conversation:

# Build conversation history
messages = [
    {"role": "user", "content": "What is Rust programming language?"},
    {"role": "assistant", "content": "Rust is a systems programming language..."},
    {"role": "user", "content": "How does it compare to C++?"}
]

response = model.chat_complete(messages)
print(response.choices[0].message.content)

Embeddings

Available Models:

• mistral-embed - High-quality embeddings (1024 dimensions)

Configuration:

from esperanto.factory import AIFactory

embedder = AIFactory.create_embedding(
    "mistral",
    "mistral-embed",
    config={
        "timeout": 60.0  # Request timeout in seconds
    }
)

Example - Basic Embeddings:

from esperanto.factory import AIFactory

# Create embedding model
embedder = AIFactory.create_embedding("mistral", "mistral-embed")

# Generate embeddings
texts = ["Hello, world!", "Mistral embeddings are great"]
response = embedder.embed(texts)

# Access embeddings
for i, embedding_obj in enumerate(response.data):
    print(f"Text {i}: {len(embedding_obj.embedding)} dimensions")
    print(f"First 5 values: {embedding_obj.embedding[:5]}")

Example - Batch Processing:

# Process many documents
documents = [f"Document {i} content here" for i in range(100)]

response = embedder.embed(documents)
embeddings = [item.embedding for item in response.data]

print(f"Generated {len(embeddings)} embeddings")

Example - Async Embeddings:

async def embed_documents():
    embedder = AIFactory.create_embedding("mistral", "mistral-embed")

    texts = ["Document 1", "Document 2", "Document 3"]
    response = await embedder.aembed(texts)

    return [item.embedding for item in response.data]

# Run async
# embeddings = await embed_documents()

Example - Semantic Search:

# Create embeddings for search
embedder = AIFactory.create_embedding("mistral", "mistral-embed")

# Embed documents
documents = [
    "Paris is the capital of France",
    "Berlin is the capital of Germany",
    "Rome is the capital of Italy"
]
doc_embeddings = embedder.embed(documents)

# Embed query
query = "What is the capital of France?"
query_embedding = embedder.embed([query])

# Use embeddings for similarity search (with your vector DB)

Advanced Features

JSON Mode

Mistral supports structured JSON output:

model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={"structured": {"type": "json"}}
)

messages = [{
    "role": "user",
    "content": "Create a JSON object with user information"
}]

response = model.chat_complete(messages)
# Response will be valid JSON

Timeout Configuration

Customize request timeouts:

# Extended timeout for complex tasks
model = AIFactory.create_language(
    "mistral",
    "mistral-large-latest",
    config={"timeout": 120.0, "max_tokens": 4096}
)

# Quick timeout for simple queries
model = AIFactory.create_language(
    "mistral",
    "mistral-small-latest",
    config={"timeout": 30.0}
)

LangChain Integration

from esperanto.factory import AIFactory

model = AIFactory.create_language("mistral", "mistral-large-latest")
langchain_model = model.to_langchain()

# Use with LangChain
from langchain.chains import ConversationChain
chain = ConversationChain(llm=langchain_model)

Model Selection Guide

Mistral Large (Recommended for Quality)

Best for: Complex reasoning, analysis, high-quality outputs

• Most capable Mistral model
• Excellent reasoning and analysis
• Strong multilingual performance
• 128K token context window
• Best for production use cases

model = AIFactory.create_language("mistral", "mistral-large-latest")

Mistral Small (Recommended for Speed)

Best for: Fast responses, cost optimization

• Fast inference
• Cost-effective
• Good for simple tasks
• 32K token context window
• Ideal for high-volume applications

model = AIFactory.create_language("mistral", "mistral-small-latest")

Codestral (Best for Code)

Best for: Code generation, code understanding

• Optimized for code tasks
• Supports multiple programming languages
• Fast code generation
• 32K token context window
• Best for developer tools

model = AIFactory.create_language("mistral", "codestral-latest")

Mistral Nemo

Best for: Balanced performance

• Good balance of speed and quality
• 128K token context window
• Multilingual capabilities
• Moderate cost

model = AIFactory.create_language("mistral", "mistral-nemo")

Performance Characteristics

Context Windows

• Large: 128K tokens (~96,000 words)
• Small: 32K tokens (~24,000 words)
• Codestral: 32K tokens
• Nemo: 128K tokens

Multilingual Support

Mistral models excel at:

• French (native language)
• English
• German
• Spanish
• Italian
• Portuguese
• And many more European languages

Response Speed

• Small: Fastest (1-2 seconds)
• Nemo: Fast (2-3 seconds)
• Large: Moderate (2-4 seconds)
• Codestral: Fast for code (1-3 seconds)

Use Cases

When to Choose Mistral

Perfect for:

• European data residency requirements
• Multilingual applications (especially European languages)
• French language content
• Cost-effective production deployments
• Code generation and analysis
• Balanced performance and cost

Consider alternatives if:

• Need strongest possible reasoning (use Claude or GPT-4)
• Primary language is not European
• Need embeddings with task optimization (use Jina or OpenAI)

Common Applications

1. Multilingual Customer Support:

model = AIFactory.create_language("mistral", "mistral-large-latest")

# Handles French, German, Spanish, etc.
messages = [{"role": "user", "content": "Comment puis-je vous aider?"}]

2. Code Generation:

code_model = AIFactory.create_language("mistral", "codestral-latest")

# Generate code in multiple languages
messages = [{"role": "user", "content": "Write a REST API in Python"}]

3. Content Analysis:

model = AIFactory.create_language("mistral", "mistral-large-latest")

# Analyze multilingual content
messages = [{"role": "user", "content": "Analyze this European market report..."}]

4. Document Embeddings:

embedder = AIFactory.create_embedding("mistral", "mistral-embed")

# Create semantic search for multilingual docs
docs = ["English doc", "Document français", "Documento español"]
embeddings = embedder.embed(docs)

Troubleshooting

Common Errors

Authentication Error:

Error: Invalid API key

Solution: Verify your API key at https://console.mistral.ai/api-keys

Rate Limit Error:

Error: Rate limit exceeded

Solution: Implement retry logic with exponential backoff or upgrade plan

Context Length Exceeded:

Error: Prompt too long

Solution:

• Use Mistral Large or Nemo for longer contexts (128K)
• Reduce message history
• Summarize earlier messages

Model Not Available:

Error: Model not found

Solution: Check model name - use "mistral-large-latest" not "mistral-large"

Timeout Error:

Error: Request timed out

Solution: Increase timeout:

config={"timeout": 120.0, "max_tokens": 1024}

Best Practices

1. Use Latest Versions: Always use "-latest" suffix for newest models

2. Choose Appropriate Model:

   • Large for quality
   • Small for speed
   • Codestral for code
   • Nemo for balance

3. Leverage Multilingual: Mistral excels at European languages

4. Temperature Settings:

   • 0.2-0.5 for factual tasks
   • 0.7-0.9 for creative tasks

5. Streaming: Use streaming for better UX with longer responses

See Also

• Language Models Guide
• Embeddings Guide
• OpenAI Provider
• Anthropic Provider
• Google Provider