Oliva Multi-Agent Assistant

Oliva is a multi-agent assistant that combines different agents to handle various tasks. These agents can be used to perform various tasks such as semantic search, text generation, question answering, and more. The project is designed to be flexible and extensible, allowing you to add more agents as needed.

Requirements:

Requirement	Description
Database Population	Follow the setup instructions in the tabular-semantic-search-tutorial or download the snapshot in assets/snapshot.zip
Qdrant	Vector database for efficient similarity search and storage of embeddings.
Superlinked	Framework for building AI applications with semantic search capabilities.
Deepgram Account	Speech-to-text service account required for converting voice input into text.
Livekit Account	Real-time communication platform needed for handling voice interactions.
Python Knowledge	Understanding of Python programming language (version 3.12+).

Installation

1. Install project dependencies:

uv sync

This will create a virtual environment in .venv and install all required dependencies.

2. Livekit account

Create a Livekit account in Livekit Cloud and get LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET.

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=secret
LIVEKIT_API_SECRET=********

3. Environment variables

Before running any Python scripts, set the following environment variables:

cp .env.example .env

4. Qdrant

Use docker to run Qdrant, set an API key wherever you want:

docker run -p 6333:6333 -p 6334:6334 \
    -e QDRANT__SERVICE__API_KEY=******** \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

Usage

Voice assistant

make oliva-start

Voice assistant frontend

Use Agent playground and connect with your Livekit project to interact with the voice assistant. If you prefer run locally, download the repo Agent playground and run npm run start.

Project Structure

oliva/
├── app/
│    ├── agents/
│    │   ├── implementations/     # Individual agent implementations
│    │   ├── core/       # Base classes and interfaces for agent components
│    │   └── langchain/
│    │       ├── base/      # Base LangChain integration classes
│    │       ├── config/    # LangChain configuration
│    │       ├── edges/     # Edge conditions for workflow routing
│    │       ├── nodes/     # Node implementations (agent, rewrite, generate)
│    │       └── tools/     # LangChain-specific tools
│    ├── voice_assistant/
│    └── utils/              # Shared utilities

Architecture Overview

The project follows a modular architecture implementing an agentic RAG (Retrieval-Augmented Generation) system:

1. Agent Components (app/agents/)

   • agents/: Contains specific agent implementations
   • core/: Defines core interfaces and abstract classes for:
     • State management
     • Node implementations
     • Edge conditions
     • Tool interfaces
     • Graph workflow definitions

2. LangChain Integration (app/agents/integrations/langchain/)

   • Provides LangChain-specific implementations for:
     • Document retrieval
     • Tool operations
     • State management
     • Workflow nodes and edges

3. Voice Assistant (app/voice_assistant/)

   • LiveKit integration
     • Voice interface implementation
     • Speech-to-text and text-to-speech capabilities

4. Utilities (app/utils/)

   • Shared helper functions
   • Common utilities used across modules

The system implements a graph-based workflow where each agent processes state through a series of nodes (functions) connected by conditional edges, supporting dynamic routing based on the agent's decisions.

Use cases

Langchain workflow by supervisor agent

make agent-supervisor

Langchain workflow by superlinked

make agent-search-by-superlinked

Langchain workflow by json file

make agent-search-by-json

Tech Stack

Technology	Version/Type	Role
Langchain	Latest	LLM application framework
Livekit	Cloud/Self-hosted	Real-time voice communication
Qdrant	Vector DB	Semantic search storage
Superlinked	Framework	Semantic search capabilities
Deepgram	API Service	Speech-to-text conversion
OpenAI	API Service	LLM provider
Python	3.12+	Core implementation

📚 Contributing

This project is open-source and welcomes contributions from the community. For more details on how to contribute, please refer to the Contributing Guide.