| Name | litemind JSON |
| Version |
2025.3.2
JSON |
| download |
| home_page | None |
| Summary | A wrapper API around LLM APIs and agentic AI framework |
| upload_time | 2025-03-03 06:49:33 |
| maintainer | None |
| docs_url | None |
| author | Loic A. Royer |
| requires_python | >=3.8 |
| license | None |
| keywords |
agents
ai
llm
wrapper
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# LiteMind
[](https://badge.fury.io/py/litemind)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://github.com/royerlab/litemind)
## Summary
LiteMind is a Python library designed to streamline the development of agentic AI applications. It provides a unified and elegant API for interacting with various Large Language Models (LLMs) and offers a powerful framework for building conversational agents and tools. The library is structured around two key layers:
1. **API Wrapper Layer**: This layer abstracts the complexities of interacting with different LLM providers (OpenAI, Anthropic, Google, Ollama), allowing developers to switch between them with minimal code changes. It provides a consistent interface for common operations like text generation, image generation, audio transcription, and embeddings.
2. **Agentic API**: This high-level framework provides the building blocks for creating sophisticated conversational agents and tools. It supports multimodal inputs (text, images, audio, video, documents), tool usage, and reasoning capabilities, enabling the creation of agents that can understand and respond to complex queries, use external tools, and maintain context across conversations.
LiteMind's core philosophy is to provide a developer-friendly experience by handling the intricacies of LLM interactions while empowering developers to build advanced AI applications with ease. The library is designed to be extensible, allowing for the addition of new LLM providers and customization of various components.
## Features
* **Unified API Wrapper**:
* Supports multiple LLM providers:
* OpenAI (GPT models)
* Anthropic (Claude models)
* Google (Gemini models)
* Ollama (local open-source models)
* **Multimodal Support**:
* Text generation and structured output
* Image, audio, and video inputs
* Document processing (PDFs, webpages, etc.)
* Table handling
* **Agentic Framework**:
* Conversational agents with memory
* Tool usage and function calling
* ReAct agents with reasoning capabilities
* Agent-to-agent communication
* **Tooling**:
* Function tools that wrap Python functions
* Agent tools that delegate to other agents
* Tool composition and chaining
* **Extensible Architecture**:
* Easy to add new LLM providers
* Customizable callbacks for monitoring and logging
* Flexible message handling
## Installation
Install LiteMind using pip:
```bash
pip install litemind
```
To install optional dependencies, use the following:
```bash
# For RAG (Retrieval Augmented Generation) support
pip install "litemind[rag]"
# For audio transcription with Whisper
pip install "litemind[whisper]"
# For document processing
pip install "litemind[documents]"
# For table handling
pip install "litemind[tables]"
# For video processing
pip install "litemind[videos]"
# For all optional dependencies
pip install "litemind[rag,whisper,documents,tables,videos]"
```
## Usage
### API Wrapper Examples
#### Text Generation
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
# Create an API instance
api = CombinedApi()
# Create messages
system_message = Message(role="system", text="You are a helpful assistant.")
user_message = Message(role="user", text="What is the capital of France?")
# Generate a response
response = api.generate_text(messages=[system_message, user_message])
# Print the response
print(response[0])
# Expected output: "The capital of France is Paris."
```
#### Multimodal Input (Image)
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
from litemind.apis.model_features import ModelFeatures
# Create an API instance
api = CombinedApi()
# Get a model that supports images
model_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Image])
# Create a message with text and an image
message = Message(role="user")
message.append_text("What's in this image?")
message.append_image("https://upload.wikimedia.org/wikipedia/commons/4/4f/Eiffel_Tower_from_Champ_de_Mars%2C_Paris%2C_France.jpg")
# Generate a response
response = api.generate_text(messages=[message], model_name=model_name)
# Print the response
print(response[0])
# Expected output: A description of the Eiffel Tower
```
#### Multimodal Input (Audio)
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
from litemind.apis.model_features import ModelFeatures
# Create an API instance
api = CombinedApi()
# Get a model that supports audio
model_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Audio])
# Create a message with text and an audio
message = Message(role="user")
message.append_text("What is said in this audio?")
message.append_audio("file:///path/to/audio.mp3") # Replace with your audio file path
# Generate a response
response = api.generate_text(messages=[message], model_name=model_name)
# Print the response
print(response[0])
# Expected output: Transcription of the audio
```
#### Multimodal Input (Video)
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
from litemind.apis.model_features import ModelFeatures
# Create an API instance
api = CombinedApi()
# Get a model that supports video
model_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Video])
# Create a message with text and a video
message = Message(role="user")
message.append_text("What is happening in this video?")
message.append_video("file:///path/to/video.mp4") # Replace with your video file path
# Generate a response
response = api.generate_text(messages=[message], model_name=model_name)
# Print the response
print(response[0])
# Expected output: Description of the video content
```
#### Structured Output
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
from pydantic import BaseModel
from typing import List
# Define a structured output model
class MovieRecommendation(BaseModel):
title: str
year: int
genre: str
director: str
rating: float
description: str
class MovieRecommendations(BaseModel):
recommendations: List[MovieRecommendation]
# Create an API instance
api = CombinedApi()
# Create messages
system_message = Message(role="system", text="You are a movie recommendation assistant.")
user_message = Message(role="user", text="Recommend 3 sci-fi movies from the 1980s.")
# Generate a structured response
response = api.generate_text(
messages=[system_message, user_message],
response_format=MovieRecommendations
)
# Access the structured data
recommendations = response[0][-1].content.recommendations
for movie in recommendations:
print(f"{movie.title} ({movie.year}) - {movie.rating}/10 - {movie.genre}")
print(f"Directed by: {movie.director}")
print(f"Description: {movie.description}")
```
### Agentic API Examples
#### Basic Agent with Tool
```python
from litemind.agent.agent import Agent
from litemind.apis.combined_api import CombinedApi
from litemind.agent.tools.toolset import ToolSet
# Define a tool function
def get_weather(city: str) -> str:
"""Get the weather for a city."""
# In a real application, this would call a weather API
return f"The weather in {city} is sunny and 75°F."
# Create a toolset and add the function tool
toolset = ToolSet()
toolset.add_function_tool(get_weather)
# Create an agent with the toolset
api = CombinedApi()
agent = Agent(api=api, toolset=toolset)
# Add a system message to define the agent's behavior
agent.append_system_message("You are a helpful weather assistant.")
# Run the agent with a user query
response = agent("What's the weather like in Paris?")
# Print the response
print(response[-1])
# Expected output: Information about the weather in Paris
```
#### ReAct Agent
```python
from litemind.agent.react.react_agent import ReActAgent
from litemind.apis.combined_api import CombinedApi
from litemind.agent.tools.toolset import ToolSet
from datetime import datetime
# Define tool functions
def get_current_date() -> str:
"""Get the current date."""
return datetime.now().strftime("%Y-%m-%d")
def calculate_days_between(start_date: str, end_date: str) -> int:
"""Calculate the number of days between two dates."""
from datetime import datetime
start = datetime.strptime(start_date, "%Y-%m-%d")
end = datetime.strptime(end_date, "%Y-%m-%d")
return abs((end - start).days)
# Create a toolset and add the function tools
toolset = ToolSet()
toolset.add_function_tool(get_current_date)
toolset.add_function_tool(calculate_days_between)
# Create a ReAct agent with the toolset
api = CombinedApi()
agent = ReActAgent(api=api, toolset=toolset)
# Run the agent with a complex query
response = agent("How many days are there between today and Christmas this year?")
# Print the response
print(response)
# Expected output: A reasoned response calculating the days until Christmas
```
#### Agent-to-Agent Communication
```python
from litemind.agent.agent import Agent
from litemind.agent.tools.tool_agent import ToolAgent
from litemind.apis.combined_api import CombinedApi
from litemind.agent.tools.toolset import ToolSet
# Create a translation agent
api = CombinedApi()
translation_agent = Agent(api=api)
translation_agent.append_system_message("You are a translator that translates English to French.")
# Create a tool agent that wraps the translation agent
translation_tool = ToolAgent(
agent=translation_agent,
description="Translates English text to French."
)
# Create a main agent that uses the translation tool
toolset = ToolSet()
toolset.add_tool(translation_tool)
main_agent = Agent(api=api, toolset=toolset)
main_agent.append_system_message("You are a helpful assistant that can translate text when needed.")
# Run the main agent
response = main_agent("Can you translate 'Hello, how are you?' to French?")
# Print the response
print(response[-1])
# Expected output: "Bonjour, comment allez-vous?"
```
## Concepts
### API Wrapper Layer
The API wrapper layer provides a unified interface to different LLM providers:
* **BaseApi**: Abstract base class that defines the interface for all API implementations.
* **DefaultApi**: Provides default implementations for common functionality.
* **Provider-specific APIs**: Implementations for OpenAI, Anthropic, Google, and Ollama.
* **CombinedApi**: Aggregates multiple API providers and automatically selects the best one for each request.
The API wrapper handles:
* Model selection based on required features
* Message conversion between different formats
* Multimodal input processing
* Tool usage and function calling
* Structured output generation
### Agentic API
The Agentic API builds on top of the API wrapper to provide a higher-level framework for building conversational agents:
* **Message**: Represents a message in a conversation, containing multiple blocks of different types (text, image, audio, etc.).
* **MessageBlock**: A single block of content within a message.
* **Conversation**: A collection of messages that maintains context.
* **Agent**: A conversational agent that can use tools and maintain a conversation.
* **ReActAgent**: An agent that implements the ReAct (Reasoning + Acting) methodology for step-by-step reasoning.
* **ToolSet**: A collection of tools that an agent can use.
* **BaseTool**: Abstract base class for all tools.
* **FunctionTool**: A tool that wraps a Python function.
* **ToolAgent**: A tool that delegates to another agent.
### Model Features
LiteMind uses a feature-based approach to model selection:
* **ModelFeatures**: An enum that defines the features a model can support (TextGeneration, Image, Audio, Video, Tools, etc.).
* **get_best_model()**: A method that selects the best model based on required features.
* **has_model_support_for()**: A method that checks if a model supports specific features.
## More Code Examples
### API Wrapper: Text Generation with Different Providers
```python
# Using OpenAI API
from litemind.apis.providers.openai.openai_api import OpenAIApi
from litemind.agent.messages.message import Message
api = OpenAIApi()
messages = [Message(role="user", text="Hello, world!")]
response = api.generate_text(messages=messages, model_name="gpt-4o")
print(response[0])
# Expected output: "Hello there!"
# Using Anthropic API
from litemind.apis.providers.anthropic.anthropic_api import AnthropicApi
from litemind.agent.messages.message import Message
api = AnthropicApi()
messages = [Message(role="user", text="Hello, world!")]
response = api.generate_text(messages=messages, model_name="claude-3-opus-20240229")
print(response[0])
# Expected output: "Hello there!"
# Using Google Gemini API
from litemind.apis.providers.google.google_api import GeminiApi
from litemind.agent.messages.message import Message
api = GeminiApi()
messages = [Message(role="user", text="Hello, world!")]
response = api.generate_text(messages=messages, model_name="models/gemini-1.5-pro")
print(response[0])
# Expected output: "Hello there!"
# Using Ollama API (local models)
from litemind.apis.providers.ollama.ollama_api import OllamaApi
from litemind.agent.messages.message import Message
api = OllamaApi()
messages = [Message(role="user", text="Hello, world!")]
response = api.generate_text(messages=messages, model_name="llama3")
print(response[0])
# Expected output: "Hello there!"
```
### API Wrapper: Text Generation with Streaming
```python
from litemind.apis.combined_api import CombinedApi
from litemind.agent.messages.message import Message
from litemind.apis.callbacks.print_callbacks import PrintCallbacks
from litemind.apis.callbacks.callback_manager import CallbackManager
# Create a callback manager with print callbacks
callback_manager = CallbackManager()
callback_manager.add_callback(PrintCallbacks(
print_text_generation=True,
print_text_streaming=True
))
# Create an API instance with callbacks
api = CombinedApi(callback_manager=callback_manager)
# Create messages
messages = [Message(role="user", text="Tell me a short story about a robot.")]
# Generate a response (callbacks will print information during generation)
response = api.generate_text(messages=messages)
# Print the final response
print("\nFinal response:")
print(response[0])
```
### API Wrapper: Embedding and Similarity
```python
from litemind.apis.combined_api import CombinedApi
import numpy as np
# Create an API instance
api = CombinedApi()
# Get text embeddings
texts = [
"The quick brown fox jumps over the lazy dog",
"A fast auburn fox leaps above the sleepy canine",
"The weather is nice today"
]
embeddings = api.embed_texts(texts=texts, dimensions=512)
# Calculate cosine similarity
def cosine_similarity(a, b):
return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
# Compare similarities
sim_1_2 = cosine_similarity(embeddings[0], embeddings[1])
sim_1_3 = cosine_similarity(embeddings[0], embeddings[2])
sim_2_3 = cosine_similarity(embeddings[1], embeddings[2])
print(f"Similarity between text 1 and 2: {sim_1_2:.4f}") # Should be high (similar meaning)
print(f"Similarity between text 1 and 3: {sim_1_3:.4f}") # Should be low (different topics)
print(f"Similarity between text 2 and 3: {sim_2_3:.4f}") # Should be low (different topics)
```
### Agentic API: Creating a Tool Agent
```python
from litemind.agent.agent import Agent
from litemind.agent.tools.toolset import ToolSet
from litemind.agent.tools.tool_agent import ToolAgent
from litemind.apis.combined_api import CombinedApi
# Create a translation agent
api = CombinedApi()
translation_agent = Agent(api=api)
translation_agent.append_system_message("You are a translator that translates English to French.")
# Create a tool agent that wraps the translation agent
translation_tool = ToolAgent(
agent=translation_agent,
description="Translates English text to French."
)
# Create a main agent that uses the translation tool
toolset = ToolSet()
toolset.add_tool(translation_tool)
main_agent = Agent(api=api, toolset=toolset)
main_agent.append_system_message("You are a helpful assistant that can translate text when needed.")
# Run the main agent
response = main_agent("Can you translate 'Hello, how are you?' to French?")
# Print the response
print(response[-1])
# Expected output: "Bonjour, comment allez-vous?"
```
### Agentic API: Creating a Function Tool
```python
from litemind.agent.agent import Agent
from litemind.agent.tools.toolset import ToolSet
from litemind.apis.combined_api import CombinedApi
from datetime import datetime
# Define a tool function
def get_current_date() -> str:
"""Get the current date."""
return datetime.now().strftime("%Y-%m-%d")
# Create a toolset and add the function tool
toolset = ToolSet()
toolset.add_function_tool(get_current_date)
# Create an agent with the toolset
api = CombinedApi()
agent = Agent(api=api, toolset=toolset)
# Add a system message to define the agent's behavior
agent.append_system_message("You are a helpful assistant that can provide the current date.")
# Run the agent with a user query
response = agent("What is the current date?")
# Print the response
print(response[-1])
# Expected output: The current date
```
## Tools
LiteMind provides a command-line tool `litemind` to perform various operations.
### `litemind codegen`
This command generates files, such as README.md files, for a Python repository based on a prompt and the contents of the repository.
#### Usage
```bash
litemind codegen [model]
```
* `model`: (Optional) The LLM model to use for generation. Defaults to `combined`. Available options are `gemini`, `openai`, `claude`, `ollama`, and `combined`.
This command requires a `.codegen` folder in the root of your repository. This folder should contain `.codegen.yml` files.
#### `.codegen.yml` file format
The `.codegen.yml` files contain instructions for the code generation process. Here's a template:
```yaml
# .codegen/README.codegen.yml
prompt: |
You are a helpful assistant that generates a README.md file for a Python repository.
The README.md should include the following sections:
- Summary
- Features
- Installation
- Usage
- Concepts
- More Code Examples
- Tools
- Caveats and Limitations
- Code Health
- Roadmap
- Contributing
- License
The 'Summary' section should provide an enthusiastic and complete description of the library, its purpose, and philosophy.
The 'Usage' section should consist of rich, striking and illustrative examples of the Agentic API in use with multimodal inputs.
The 'Concepts' section should explain the concepts behind the library, the main classes and their purpose, and how they interact.
The 'Code Health' section should include the results of unit test in file 'test_report.md'. Please provide file names for failed tests and statistics about the number of failed tests and an analysis of what happened.
The 'Roadmap' section can use the contents of TODO.md as a starting point, keep the checkmarks.
The 'More Code Examples' section further expands with many more also covering the wrapper API, uses ideas and code from the unit tests (no need to mention that).
The 'Tools' section should explain litemind command line tools and how to use them, with example command lines (check tools package and its contents for details). Please also explain the format of the *.codegen.yml files and give a template. Explain that you need a .codegen folder in the root of the repository and you can apply that to your own repositories.
folder:
path: .
file: README.md
allowed_extensions:
- .py
- .md
- .txt
- .toml
- LICENSE
- .tests
- .html
excluded_files:
- litemind.egg-info
- dist
- build
```
* `prompt`: The prompt to use for generating the file. This prompt should include instructions for the LLM on what to generate.
* `folder`: Specifies the folder to include in the context of the prompt.
* `path`: The path to the folder to include. Use `.` for the current directory.
* `file`: The name of the file to generate.
* `allowed_extensions`: A list of file extensions to include in the context.
* `excluded_files`: A list of files to exclude from the context.
#### Example
To generate a README.md file for a repository, create a `.codegen` folder in the root of the repository and add a `.codegen.yml` file with the appropriate prompt and file information. Then, run:
```bash
litemind codegen
```
This will generate a README.md file in the root of the repository.
### `litemind export`
This command exports the entire repository to a single file.
#### Usage
```bash
litemind export <folder_path> -o <output_file> [-e <extensions>] [-x <exclude>]
```
* `<folder_path>`: The path to the folder containing the repository to export.
* `-o` or `--output-file`: The path to the file to save the entire repository to.
* `-e` or `--extensions`: (Optional) A list of allowed extensions for files to include in the export.
* `-x` or `--exclude`: (Optional) A list of files to exclude from the export.
#### Example
To export a repository to a single file, run:
```bash
litemind export . -o repository.txt -e .py .md -x README.md
```
This will export the current directory (.), including all `.py` and `.md` files, excluding `README.md`, to a file named `repository.txt`.
## Caveats and Limitations
* **API Keys**: You need to provide your own API keys for the various providers (OpenAI, Anthropic, Google, Ollama).
* **Cost**: Using commercial LLM APIs incurs costs based on their pricing models.
* **Model Availability**: Not all features are available with all models or providers.
* **Token Limits**: Different models have different token limits that may affect the complexity of tasks they can handle.
* **Tool Execution**: Tools are executed locally, which means they have access to your local environment.
* **ReAct Agent Limitations**: The ReAct agent implementation has some limitations in handling complex reasoning chains and may occasionally fail to follow the correct reasoning format.
* **Video Processing**: Video processing requires ffmpeg to be installed and may be resource-intensive.
* **Document Processing**: Document processing requires additional dependencies and may not work perfectly with all document formats.
## Code Health
The test suite for LiteMind shows good overall health with 452 passing tests out of 525 total tests (86% pass rate). There are 12 failing tests and 61 skipped tests.
The failing tests are primarily in the ReAct agent implementation:
* `test_react_agent_single_tool` (1 failure)
* `test_react_agent_multiple_tools` (2 failures)
* `test_react_agent_chained_tools` (2 failures)
* `test_react_agent_longer_dialog` (2 failures)
* `test_agent_tool` (1 failure)
* `test_agent_tool_translation` (1 failure)
* `test_agent_tool_with_internal_tool` (1 failure)
* `test_toolset_add_agent_tool` (1 failure)
* `test_text_generation_with_folder` (1 failure)
These failures indicate that the ReAct agent and tool agent implementations need further refinement to ensure consistent behavior across different LLM providers.
The skipped tests are primarily due to certain features not being available with all providers, which is expected behavior.
## Roadmap
- [ ] Deal with message sizes in tokens sent to models
- [ ] RAG
- [ ] Improve vendor api robustness features such as retry call when server errors, etc...
- [ ] Reorganise media files used for testing into a single media folder
- [ ] Improve and uniformize exception handling
- [ ] Add support for adding nD images to messages.
- [ ] Improve logging with arbol, with option to turn off.
- [ ] Implement 'brainstorming' mode for text generation, possibly with API fusion.
## Contributing
We welcome contributions to LiteMind! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.
## License
LiteMind is licensed under the BSD-3-Clause License. See [LICENSE](LICENSE) for details.
---
This README was generated with the help of AI.
Raw data
{
"_id": null,
"home_page": null,
"name": "litemind",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "agents, ai, llm, wrapper",
"author": "Loic A. Royer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/44/8f/cbb5957fcdc60c31c48b1a4f362bdf96096bb3999121d6bbaf888e7891ec/litemind-2025.3.2.tar.gz",
"platform": null,
"description": "\n# LiteMind\n\n[](https://badge.fury.io/py/litemind)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](https://github.com/royerlab/litemind)\n\n## Summary\n\nLiteMind is a Python library designed to streamline the development of agentic AI applications. It provides a unified and elegant API for interacting with various Large Language Models (LLMs) and offers a powerful framework for building conversational agents and tools. The library is structured around two key layers:\n\n1. **API Wrapper Layer**: This layer abstracts the complexities of interacting with different LLM providers (OpenAI, Anthropic, Google, Ollama), allowing developers to switch between them with minimal code changes. It provides a consistent interface for common operations like text generation, image generation, audio transcription, and embeddings.\n\n2. **Agentic API**: This high-level framework provides the building blocks for creating sophisticated conversational agents and tools. It supports multimodal inputs (text, images, audio, video, documents), tool usage, and reasoning capabilities, enabling the creation of agents that can understand and respond to complex queries, use external tools, and maintain context across conversations.\n\nLiteMind's core philosophy is to provide a developer-friendly experience by handling the intricacies of LLM interactions while empowering developers to build advanced AI applications with ease. The library is designed to be extensible, allowing for the addition of new LLM providers and customization of various components.\n\n## Features\n\n* **Unified API Wrapper**:\n * Supports multiple LLM providers:\n * OpenAI (GPT models)\n * Anthropic (Claude models)\n * Google (Gemini models)\n * Ollama (local open-source models)\n* **Multimodal Support**:\n * Text generation and structured output\n * Image, audio, and video inputs\n * Document processing (PDFs, webpages, etc.)\n * Table handling\n* **Agentic Framework**:\n * Conversational agents with memory\n * Tool usage and function calling\n * ReAct agents with reasoning capabilities\n * Agent-to-agent communication\n* **Tooling**:\n * Function tools that wrap Python functions\n * Agent tools that delegate to other agents\n * Tool composition and chaining\n* **Extensible Architecture**:\n * Easy to add new LLM providers\n * Customizable callbacks for monitoring and logging\n * Flexible message handling\n\n## Installation\n\nInstall LiteMind using pip:\n\n```bash\npip install litemind\n```\n\nTo install optional dependencies, use the following:\n\n```bash\n# For RAG (Retrieval Augmented Generation) support\npip install \"litemind[rag]\"\n\n# For audio transcription with Whisper\npip install \"litemind[whisper]\"\n\n# For document processing\npip install \"litemind[documents]\"\n\n# For table handling\npip install \"litemind[tables]\"\n\n# For video processing\npip install \"litemind[videos]\"\n\n# For all optional dependencies\npip install \"litemind[rag,whisper,documents,tables,videos]\"\n```\n\n## Usage\n\n### API Wrapper Examples\n\n#### Text Generation\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\n\n# Create an API instance\napi = CombinedApi()\n\n# Create messages\nsystem_message = Message(role=\"system\", text=\"You are a helpful assistant.\")\nuser_message = Message(role=\"user\", text=\"What is the capital of France?\")\n\n# Generate a response\nresponse = api.generate_text(messages=[system_message, user_message])\n\n# Print the response\nprint(response[0])\n# Expected output: \"The capital of France is Paris.\"\n```\n\n#### Multimodal Input (Image)\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\nfrom litemind.apis.model_features import ModelFeatures\n\n# Create an API instance\napi = CombinedApi()\n\n# Get a model that supports images\nmodel_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Image])\n\n# Create a message with text and an image\nmessage = Message(role=\"user\")\nmessage.append_text(\"What's in this image?\")\nmessage.append_image(\"https://upload.wikimedia.org/wikipedia/commons/4/4f/Eiffel_Tower_from_Champ_de_Mars%2C_Paris%2C_France.jpg\")\n\n# Generate a response\nresponse = api.generate_text(messages=[message], model_name=model_name)\n\n# Print the response\nprint(response[0])\n# Expected output: A description of the Eiffel Tower\n```\n\n#### Multimodal Input (Audio)\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\nfrom litemind.apis.model_features import ModelFeatures\n\n# Create an API instance\napi = CombinedApi()\n\n# Get a model that supports audio\nmodel_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Audio])\n\n# Create a message with text and an audio\nmessage = Message(role=\"user\")\nmessage.append_text(\"What is said in this audio?\")\nmessage.append_audio(\"file:///path/to/audio.mp3\") # Replace with your audio file path\n\n# Generate a response\nresponse = api.generate_text(messages=[message], model_name=model_name)\n\n# Print the response\nprint(response[0])\n# Expected output: Transcription of the audio\n```\n\n#### Multimodal Input (Video)\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\nfrom litemind.apis.model_features import ModelFeatures\n\n# Create an API instance\napi = CombinedApi()\n\n# Get a model that supports video\nmodel_name = api.get_best_model([ModelFeatures.TextGeneration, ModelFeatures.Video])\n\n# Create a message with text and a video\nmessage = Message(role=\"user\")\nmessage.append_text(\"What is happening in this video?\")\nmessage.append_video(\"file:///path/to/video.mp4\") # Replace with your video file path\n\n# Generate a response\nresponse = api.generate_text(messages=[message], model_name=model_name)\n\n# Print the response\nprint(response[0])\n# Expected output: Description of the video content\n```\n\n#### Structured Output\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\nfrom pydantic import BaseModel\nfrom typing import List\n\n# Define a structured output model\nclass MovieRecommendation(BaseModel):\n title: str\n year: int\n genre: str\n director: str\n rating: float\n description: str\n\nclass MovieRecommendations(BaseModel):\n recommendations: List[MovieRecommendation]\n\n# Create an API instance\napi = CombinedApi()\n\n# Create messages\nsystem_message = Message(role=\"system\", text=\"You are a movie recommendation assistant.\")\nuser_message = Message(role=\"user\", text=\"Recommend 3 sci-fi movies from the 1980s.\")\n\n# Generate a structured response\nresponse = api.generate_text(\n messages=[system_message, user_message],\n response_format=MovieRecommendations\n)\n\n# Access the structured data\nrecommendations = response[0][-1].content.recommendations\nfor movie in recommendations:\n print(f\"{movie.title} ({movie.year}) - {movie.rating}/10 - {movie.genre}\")\n print(f\"Directed by: {movie.director}\")\n print(f\"Description: {movie.description}\")\n```\n\n### Agentic API Examples\n\n#### Basic Agent with Tool\n\n```python\nfrom litemind.agent.agent import Agent\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.tools.toolset import ToolSet\n\n# Define a tool function\ndef get_weather(city: str) -> str:\n \"\"\"Get the weather for a city.\"\"\"\n # In a real application, this would call a weather API\n return f\"The weather in {city} is sunny and 75\u00b0F.\"\n\n# Create a toolset and add the function tool\ntoolset = ToolSet()\ntoolset.add_function_tool(get_weather)\n\n# Create an agent with the toolset\napi = CombinedApi()\nagent = Agent(api=api, toolset=toolset)\n\n# Add a system message to define the agent's behavior\nagent.append_system_message(\"You are a helpful weather assistant.\")\n\n# Run the agent with a user query\nresponse = agent(\"What's the weather like in Paris?\")\n\n# Print the response\nprint(response[-1])\n# Expected output: Information about the weather in Paris\n```\n\n#### ReAct Agent\n\n```python\nfrom litemind.agent.react.react_agent import ReActAgent\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.tools.toolset import ToolSet\nfrom datetime import datetime\n\n# Define tool functions\ndef get_current_date() -> str:\n \"\"\"Get the current date.\"\"\"\n return datetime.now().strftime(\"%Y-%m-%d\")\n\ndef calculate_days_between(start_date: str, end_date: str) -> int:\n \"\"\"Calculate the number of days between two dates.\"\"\"\n from datetime import datetime\n start = datetime.strptime(start_date, \"%Y-%m-%d\")\n end = datetime.strptime(end_date, \"%Y-%m-%d\")\n return abs((end - start).days)\n\n# Create a toolset and add the function tools\ntoolset = ToolSet()\ntoolset.add_function_tool(get_current_date)\ntoolset.add_function_tool(calculate_days_between)\n\n# Create a ReAct agent with the toolset\napi = CombinedApi()\nagent = ReActAgent(api=api, toolset=toolset)\n\n# Run the agent with a complex query\nresponse = agent(\"How many days are there between today and Christmas this year?\")\n\n# Print the response\nprint(response)\n# Expected output: A reasoned response calculating the days until Christmas\n```\n\n#### Agent-to-Agent Communication\n\n```python\nfrom litemind.agent.agent import Agent\nfrom litemind.agent.tools.tool_agent import ToolAgent\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.tools.toolset import ToolSet\n\n# Create a translation agent\napi = CombinedApi()\ntranslation_agent = Agent(api=api)\ntranslation_agent.append_system_message(\"You are a translator that translates English to French.\")\n\n# Create a tool agent that wraps the translation agent\ntranslation_tool = ToolAgent(\n agent=translation_agent,\n description=\"Translates English text to French.\"\n)\n\n# Create a main agent that uses the translation tool\ntoolset = ToolSet()\ntoolset.add_tool(translation_tool)\n\nmain_agent = Agent(api=api, toolset=toolset)\nmain_agent.append_system_message(\"You are a helpful assistant that can translate text when needed.\")\n\n# Run the main agent\nresponse = main_agent(\"Can you translate 'Hello, how are you?' to French?\")\n\n# Print the response\nprint(response[-1])\n# Expected output: \"Bonjour, comment allez-vous?\"\n```\n\n## Concepts\n\n### API Wrapper Layer\n\nThe API wrapper layer provides a unified interface to different LLM providers:\n\n* **BaseApi**: Abstract base class that defines the interface for all API implementations.\n* **DefaultApi**: Provides default implementations for common functionality.\n* **Provider-specific APIs**: Implementations for OpenAI, Anthropic, Google, and Ollama.\n* **CombinedApi**: Aggregates multiple API providers and automatically selects the best one for each request.\n\nThe API wrapper handles:\n\n* Model selection based on required features\n* Message conversion between different formats\n* Multimodal input processing\n* Tool usage and function calling\n* Structured output generation\n\n### Agentic API\n\nThe Agentic API builds on top of the API wrapper to provide a higher-level framework for building conversational agents:\n\n* **Message**: Represents a message in a conversation, containing multiple blocks of different types (text, image, audio, etc.).\n* **MessageBlock**: A single block of content within a message.\n* **Conversation**: A collection of messages that maintains context.\n* **Agent**: A conversational agent that can use tools and maintain a conversation.\n* **ReActAgent**: An agent that implements the ReAct (Reasoning + Acting) methodology for step-by-step reasoning.\n* **ToolSet**: A collection of tools that an agent can use.\n* **BaseTool**: Abstract base class for all tools.\n* **FunctionTool**: A tool that wraps a Python function.\n* **ToolAgent**: A tool that delegates to another agent.\n\n### Model Features\n\nLiteMind uses a feature-based approach to model selection:\n\n* **ModelFeatures**: An enum that defines the features a model can support (TextGeneration, Image, Audio, Video, Tools, etc.).\n* **get_best_model()**: A method that selects the best model based on required features.\n* **has_model_support_for()**: A method that checks if a model supports specific features.\n\n## More Code Examples\n\n### API Wrapper: Text Generation with Different Providers\n\n```python\n# Using OpenAI API\nfrom litemind.apis.providers.openai.openai_api import OpenAIApi\nfrom litemind.agent.messages.message import Message\n\napi = OpenAIApi()\nmessages = [Message(role=\"user\", text=\"Hello, world!\")]\nresponse = api.generate_text(messages=messages, model_name=\"gpt-4o\")\nprint(response[0])\n# Expected output: \"Hello there!\"\n\n# Using Anthropic API\nfrom litemind.apis.providers.anthropic.anthropic_api import AnthropicApi\nfrom litemind.agent.messages.message import Message\n\napi = AnthropicApi()\nmessages = [Message(role=\"user\", text=\"Hello, world!\")]\nresponse = api.generate_text(messages=messages, model_name=\"claude-3-opus-20240229\")\nprint(response[0])\n# Expected output: \"Hello there!\"\n\n# Using Google Gemini API\nfrom litemind.apis.providers.google.google_api import GeminiApi\nfrom litemind.agent.messages.message import Message\n\napi = GeminiApi()\nmessages = [Message(role=\"user\", text=\"Hello, world!\")]\nresponse = api.generate_text(messages=messages, model_name=\"models/gemini-1.5-pro\")\nprint(response[0])\n# Expected output: \"Hello there!\"\n\n# Using Ollama API (local models)\nfrom litemind.apis.providers.ollama.ollama_api import OllamaApi\nfrom litemind.agent.messages.message import Message\n\napi = OllamaApi()\nmessages = [Message(role=\"user\", text=\"Hello, world!\")]\nresponse = api.generate_text(messages=messages, model_name=\"llama3\")\nprint(response[0])\n# Expected output: \"Hello there!\"\n```\n\n### API Wrapper: Text Generation with Streaming\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nfrom litemind.agent.messages.message import Message\nfrom litemind.apis.callbacks.print_callbacks import PrintCallbacks\nfrom litemind.apis.callbacks.callback_manager import CallbackManager\n\n# Create a callback manager with print callbacks\ncallback_manager = CallbackManager()\ncallback_manager.add_callback(PrintCallbacks(\n print_text_generation=True,\n print_text_streaming=True\n))\n\n# Create an API instance with callbacks\napi = CombinedApi(callback_manager=callback_manager)\n\n# Create messages\nmessages = [Message(role=\"user\", text=\"Tell me a short story about a robot.\")]\n\n# Generate a response (callbacks will print information during generation)\nresponse = api.generate_text(messages=messages)\n\n# Print the final response\nprint(\"\\nFinal response:\")\nprint(response[0])\n```\n\n### API Wrapper: Embedding and Similarity\n\n```python\nfrom litemind.apis.combined_api import CombinedApi\nimport numpy as np\n\n# Create an API instance\napi = CombinedApi()\n\n# Get text embeddings\ntexts = [\n \"The quick brown fox jumps over the lazy dog\",\n \"A fast auburn fox leaps above the sleepy canine\",\n \"The weather is nice today\"\n]\nembeddings = api.embed_texts(texts=texts, dimensions=512)\n\n# Calculate cosine similarity\ndef cosine_similarity(a, b):\n return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))\n\n# Compare similarities\nsim_1_2 = cosine_similarity(embeddings[0], embeddings[1])\nsim_1_3 = cosine_similarity(embeddings[0], embeddings[2])\nsim_2_3 = cosine_similarity(embeddings[1], embeddings[2])\n\nprint(f\"Similarity between text 1 and 2: {sim_1_2:.4f}\") # Should be high (similar meaning)\nprint(f\"Similarity between text 1 and 3: {sim_1_3:.4f}\") # Should be low (different topics)\nprint(f\"Similarity between text 2 and 3: {sim_2_3:.4f}\") # Should be low (different topics)\n```\n\n### Agentic API: Creating a Tool Agent\n\n```python\nfrom litemind.agent.agent import Agent\nfrom litemind.agent.tools.toolset import ToolSet\nfrom litemind.agent.tools.tool_agent import ToolAgent\nfrom litemind.apis.combined_api import CombinedApi\n\n# Create a translation agent\napi = CombinedApi()\ntranslation_agent = Agent(api=api)\ntranslation_agent.append_system_message(\"You are a translator that translates English to French.\")\n\n# Create a tool agent that wraps the translation agent\ntranslation_tool = ToolAgent(\n agent=translation_agent,\n description=\"Translates English text to French.\"\n)\n\n# Create a main agent that uses the translation tool\ntoolset = ToolSet()\ntoolset.add_tool(translation_tool)\n\nmain_agent = Agent(api=api, toolset=toolset)\nmain_agent.append_system_message(\"You are a helpful assistant that can translate text when needed.\")\n\n# Run the main agent\nresponse = main_agent(\"Can you translate 'Hello, how are you?' to French?\")\n\n# Print the response\nprint(response[-1])\n# Expected output: \"Bonjour, comment allez-vous?\"\n```\n\n### Agentic API: Creating a Function Tool\n\n```python\nfrom litemind.agent.agent import Agent\nfrom litemind.agent.tools.toolset import ToolSet\nfrom litemind.apis.combined_api import CombinedApi\nfrom datetime import datetime\n\n# Define a tool function\ndef get_current_date() -> str:\n \"\"\"Get the current date.\"\"\"\n return datetime.now().strftime(\"%Y-%m-%d\")\n\n# Create a toolset and add the function tool\ntoolset = ToolSet()\ntoolset.add_function_tool(get_current_date)\n\n# Create an agent with the toolset\napi = CombinedApi()\nagent = Agent(api=api, toolset=toolset)\n\n# Add a system message to define the agent's behavior\nagent.append_system_message(\"You are a helpful assistant that can provide the current date.\")\n\n# Run the agent with a user query\nresponse = agent(\"What is the current date?\")\n\n# Print the response\nprint(response[-1])\n# Expected output: The current date\n```\n\n## Tools\n\nLiteMind provides a command-line tool `litemind` to perform various operations.\n\n### `litemind codegen`\n\nThis command generates files, such as README.md files, for a Python repository based on a prompt and the contents of the repository.\n\n#### Usage\n\n```bash\nlitemind codegen [model]\n```\n\n* `model`: (Optional) The LLM model to use for generation. Defaults to `combined`. Available options are `gemini`, `openai`, `claude`, `ollama`, and `combined`.\n\nThis command requires a `.codegen` folder in the root of your repository. This folder should contain `.codegen.yml` files.\n\n#### `.codegen.yml` file format\n\nThe `.codegen.yml` files contain instructions for the code generation process. Here's a template:\n\n```yaml\n# .codegen/README.codegen.yml\nprompt: |\n You are a helpful assistant that generates a README.md file for a Python repository.\n The README.md should include the following sections:\n - Summary\n - Features\n - Installation\n - Usage\n - Concepts\n - More Code Examples\n - Tools\n - Caveats and Limitations\n - Code Health\n - Roadmap\n - Contributing\n - License\n The 'Summary' section should provide an enthusiastic and complete description of the library, its purpose, and philosophy.\n The 'Usage' section should consist of rich, striking and illustrative examples of the Agentic API in use with multimodal inputs.\n The 'Concepts' section should explain the concepts behind the library, the main classes and their purpose, and how they interact.\n The 'Code Health' section should include the results of unit test in file 'test_report.md'. Please provide file names for failed tests and statistics about the number of failed tests and an analysis of what happened.\n The 'Roadmap' section can use the contents of TODO.md as a starting point, keep the checkmarks.\n The 'More Code Examples' section further expands with many more also covering the wrapper API, uses ideas and code from the unit tests (no need to mention that).\n The 'Tools' section should explain litemind command line tools and how to use them, with example command lines (check tools package and its contents for details). Please also explain the format of the *.codegen.yml files and give a template. Explain that you need a .codegen folder in the root of the repository and you can apply that to your own repositories.\nfolder:\n path: .\nfile: README.md\nallowed_extensions:\n - .py\n - .md\n - .txt\n - .toml\n - LICENSE\n - .tests\n - .html\nexcluded_files:\n - litemind.egg-info\n - dist\n - build\n```\n\n* `prompt`: The prompt to use for generating the file. This prompt should include instructions for the LLM on what to generate.\n* `folder`: Specifies the folder to include in the context of the prompt.\n * `path`: The path to the folder to include. Use `.` for the current directory.\n* `file`: The name of the file to generate.\n* `allowed_extensions`: A list of file extensions to include in the context.\n* `excluded_files`: A list of files to exclude from the context.\n\n#### Example\n\nTo generate a README.md file for a repository, create a `.codegen` folder in the root of the repository and add a `.codegen.yml` file with the appropriate prompt and file information. Then, run:\n\n```bash\nlitemind codegen\n```\n\nThis will generate a README.md file in the root of the repository.\n\n### `litemind export`\n\nThis command exports the entire repository to a single file.\n\n#### Usage\n\n```bash\nlitemind export <folder_path> -o <output_file> [-e <extensions>] [-x <exclude>]\n```\n\n* `<folder_path>`: The path to the folder containing the repository to export.\n* `-o` or `--output-file`: The path to the file to save the entire repository to.\n* `-e` or `--extensions`: (Optional) A list of allowed extensions for files to include in the export.\n* `-x` or `--exclude`: (Optional) A list of files to exclude from the export.\n\n#### Example\n\nTo export a repository to a single file, run:\n\n```bash\nlitemind export . -o repository.txt -e .py .md -x README.md\n```\n\nThis will export the current directory (.), including all `.py` and `.md` files, excluding `README.md`, to a file named `repository.txt`.\n\n## Caveats and Limitations\n\n* **API Keys**: You need to provide your own API keys for the various providers (OpenAI, Anthropic, Google, Ollama).\n* **Cost**: Using commercial LLM APIs incurs costs based on their pricing models.\n* **Model Availability**: Not all features are available with all models or providers.\n* **Token Limits**: Different models have different token limits that may affect the complexity of tasks they can handle.\n* **Tool Execution**: Tools are executed locally, which means they have access to your local environment.\n* **ReAct Agent Limitations**: The ReAct agent implementation has some limitations in handling complex reasoning chains and may occasionally fail to follow the correct reasoning format.\n* **Video Processing**: Video processing requires ffmpeg to be installed and may be resource-intensive.\n* **Document Processing**: Document processing requires additional dependencies and may not work perfectly with all document formats.\n\n## Code Health\n\nThe test suite for LiteMind shows good overall health with 452 passing tests out of 525 total tests (86% pass rate). There are 12 failing tests and 61 skipped tests.\n\nThe failing tests are primarily in the ReAct agent implementation:\n* `test_react_agent_single_tool` (1 failure)\n* `test_react_agent_multiple_tools` (2 failures)\n* `test_react_agent_chained_tools` (2 failures)\n* `test_react_agent_longer_dialog` (2 failures)\n* `test_agent_tool` (1 failure)\n* `test_agent_tool_translation` (1 failure)\n* `test_agent_tool_with_internal_tool` (1 failure)\n* `test_toolset_add_agent_tool` (1 failure)\n* `test_text_generation_with_folder` (1 failure)\n\nThese failures indicate that the ReAct agent and tool agent implementations need further refinement to ensure consistent behavior across different LLM providers.\n\nThe skipped tests are primarily due to certain features not being available with all providers, which is expected behavior.\n\n## Roadmap\n\n- [ ] Deal with message sizes in tokens sent to models\n- [ ] RAG\n- [ ] Improve vendor api robustness features such as retry call when server errors, etc...\n- [ ] Reorganise media files used for testing into a single media folder\n- [ ] Improve and uniformize exception handling\n- [ ] Add support for adding nD images to messages.\n- [ ] Improve logging with arbol, with option to turn off.\n- [ ] Implement 'brainstorming' mode for text generation, possibly with API fusion.\n\n## Contributing\n\nWe welcome contributions to LiteMind! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute.\n\n## License\n\nLiteMind is licensed under the BSD-3-Clause License. See [LICENSE](LICENSE) for details.\n\n---\n\nThis README was generated with the help of AI.\n",
"bugtrack_url": null,
"license": null,
"summary": "A wrapper API around LLM APIs and agentic AI framework",
"version": "2025.3.2",
"project_urls": {
"Homepage": "https://github.com/royerlab/litemind",
"Issues": "https://github.com/royerlab/litemind/issues"
},
"split_keywords": [
"agents",
" ai",
" llm",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4fc16792dd1abcca9dbdf31826d918143cc094483ccf994c34b6ce4a4692f7db",
"md5": "2c63b4ddc58587a667d45a96c7e5a085",
"sha256": "dcc6d91d46009fc9117e50609c27e01f24bed8aa5b789ef1e929c2160c675c81"
},
"downloads": -1,
"filename": "litemind-2025.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c63b4ddc58587a667d45a96c7e5a085",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21746483,
"upload_time": "2025-03-03T06:49:37",
"upload_time_iso_8601": "2025-03-03T06:49:37.164053Z",
"url": "https://files.pythonhosted.org/packages/4f/c1/6792dd1abcca9dbdf31826d918143cc094483ccf994c34b6ce4a4692f7db/litemind-2025.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "448fcbb5957fcdc60c31c48b1a4f362bdf96096bb3999121d6bbaf888e7891ec",
"md5": "ad0defc7402f629d43dde7866479990d",
"sha256": "748397bd39d10ac70b8bc5ff297c2b306b1928471fb2ddb31e30c6c2aaf662d0"
},
"downloads": -1,
"filename": "litemind-2025.3.2.tar.gz",
"has_sig": false,
"md5_digest": "ad0defc7402f629d43dde7866479990d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4416453,
"upload_time": "2025-03-03T06:49:33",
"upload_time_iso_8601": "2025-03-03T06:49:33.450790Z",
"url": "https://files.pythonhosted.org/packages/44/8f/cbb5957fcdc60c31c48b1a4f362bdf96096bb3999121d6bbaf888e7891ec/litemind-2025.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-03 06:49:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "royerlab",
"github_project": "litemind",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "litemind"
}
