# deluxer/oliva architecture

> Architecture diagram of the GitHub repository deluxer/oliva, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deluxer/oliva
- Repository: https://github.com/deluxer/oliva

## Overview

##### Main Components
- Voice Assistant Module:
- Located under app/voice_assistant, this component handles real-time voice input.
- Integrates with Livekit for real-time communication and with a speech-to-text service (e.g., Deepgram) for voice conversion.
- Agent Components:
- Under app/agents, these include:
▪ Core: (app/agents/core) Base classes handling state management and common interfaces.
▪ Implementations: (app/agents/implementations) Specific agents – for example, blog post processing, Amazon product searches (both JSON and superlinked versions).
▪ Supervisor: A coordinator (found in app/agents/implementations/supervisor.py) that routes voice commands and queries to the appropriate agent.
- LangChain Integration:
- Located in app/agents/langchain, it contains several sub-components:
▪ Nodes (app/agents/langchain/nodes): Represent the discrete processing steps (e.g., agent logic, generate, rewrite).
▪ Edges (app/agents/langchain/edges): Manage conditional transitions between nodes.
▪ Tools (app/agents/langchain/tools): Provide specific functionality like Amazon product search and blog post tools.
▪ Vector Store (app/agents/langchain/vector_store): Implements document retrieval functionality interfacing with the Qdrant vector database.
▪ Factory and Interface: Used for initializing and managing LangChain components.
- Utilities:
- In app/utils, common helper functions and constants are shared across modules.

##### Relationships and Interactions
- The Voice Assistant receives user input via Livekit, converts speech to text, and forwards the request.
- The Supervisor agent determines which specific agent should be triggered next based on the input (implementing the core multi-agent decision logic).
- Each agent implementation processes the request using:
- Interactions with external services – for example, fetching vectors from Qdrant or running semantic searches with Superlinked.
- Data flows from the user (voice input) to the voice assistant module, then to the supervisor agent, and finally through the appropriate agent’s workflow (utilizing LangChain’s nodes/edges) before potentially returning a result.

##### Architectural Patterns and Design Principles
- Modular Architecture: Clear separation between voice input, supervision, agent-specific implementations, and shared utilities.
- Integration of External Services: Clearly delineated responsibilities for external services (Livekit for real-time, Qdrant for vector storage, Superlinked for semantic search, Deepgram as speech-to-text).
- Extensibility: Each agent implementation (placed under app/agents/implementations) can be enhanced or replaced independently while maintaining consistent communication protocols through core interfaces.

##### Relevant Technologies
- LangChain (LLM integration, nodes, edges, tools, and vector store)
- Livekit (real-time voice communication)
- Qdrant (vector database for semantic search)
- Superlinked (framework for semantic search)
- Deepgram (speech-to-text conversion)
- Python (version 3.12+ as the core implementation language)

- Detail dynamic routing: Show how the supervisor agent directs requests to different agent implementations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UVI["User Voice Input"]:::external
    subgraph "Voice Assistant Module"
        VA["Voice Assistant (Livekit & Deepgram)"]:::voice
    end
    UVI --> VA
    VA -->|"uses"| DG["Deepgram"]:::external
    VA -->|"uses"| LK["Livekit"]:::external

    subgraph "Agent Management"
        CA1["Core Agent: Base"]:::agent
        CA2["Core Agent: State"]:::agent
        SA["Supervisor Agent"]:::agent
        CA1 --- CA2
        CA1 --> SA
        CA2 --> SA
    end
    VA --> SA

    subgraph "Agent Implementations"
        BP["Blog Post Agent"]:::agent
        AASJ["Amazon Search Agent (JSON)"]:::agent
        AASS["Amazon Search Agent (Superlinked)"]:::agent
    end
    SA --> BP
    SA --> AASJ
    SA --> AASS

    subgraph "LangChain Workflow"
        LCn["LangChain Nodes"]:::langchain
        LCe["LangChain Edges"]:::langchain
        LCt["LangChain Tools"]:::langchain
        VS["Vector Store"]:::langchain
        LCF["LangChain Factory"]:::langchain
        LCI["LangChain Interface"]:::langchain
        LCn --> LCe
        LCe --> LCt
        LCt --> VS
        VS --> LCF
        LCF --> LCI
    end
    BP --> LCn
    AASJ --> LCn
    AASS --> LCn

    UT["Utilities"]:::utils
    SA --> UT

    LCt -->|"calls"| SL["Superlinked"]:::external
    VS -->|"fetches from"| QD["Qdrant"]:::external

    classDef voice fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef agent fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef langchain fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utils fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    click VA "https://github.com/deluxer/oliva/blob/main/app/voice_assistant/assistant.py"
    click CA1 "https://github.com/deluxer/oliva/blob/main/app/agents/core/base_agent.py"
    click CA2 "https://github.com/deluxer/oliva/blob/main/app/agents/core/agent_state.py"
    click SA "https://github.com/deluxer/oliva/blob/main/app/agents/implementations/supervisor.py"
    click BP "https://github.com/deluxer/oliva/blob/main/app/agents/implementations/blog_post/agent.py"
    click AASJ "https://github.com/deluxer/oliva/blob/main/app/agents/implementations/search_amazon_products/agent_by_json.py"
    click AASS "https://github.com/deluxer/oliva/blob/main/app/agents/implementations/search_amazon_products/agent_by_superlinked.py"
    click LCn "https://github.com/deluxer/oliva/tree/main/app/agents/langchain/nodes"
    click LCe "https://github.com/deluxer/oliva/tree/main/app/agents/langchain/edges"
    click LCt "https://github.com/deluxer/oliva/tree/main/app/agents/langchain/tools"
    click VS "https://github.com/deluxer/oliva/tree/main/app/agents/langchain/vector_store"
    click LCF "https://github.com/deluxer/oliva/blob/main/app/agents/langchain/factory.py"
    click LCI "https://github.com/deluxer/oliva/tree/main/app/agents/langchain/interface"
    click UT "https://github.com/deluxer/oliva/tree/main/app/utils"
```
