Soliplex
An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface.
Ask AI about Soliplex
Powered by Claude ยท Grounded in docs
I know everything about Soliplex. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
https://pypi.org/project/soliplex/# Soliplex
An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface.
Features
- RAG-Powered Search: Semantic document retrieval using LanceDB vector database
- Multi-Room Architecture: Independent chat environments (rooms) with separate configurations and knowledge bases
- Multiple LLM Providers: OpenAI, Ollama, and compatible APIs
- AI Agent System: Function calling and tool integration for AI agents
- OIDC Authentication: Enterprise SSO with Keycloak integration
- Model Context Protocol (MCP): Extended AI capabilities through MCP client or exposing Room as MCP server
- Real-time Communication: WebSocket-based conversation streams
- Quiz System: Custom quizzes with LLM-based evaluation
- Observability: Logfire integration for monitoring
Architecture
Backend (/src/soliplex/)
Python 3.12+ / FastAPI
- Core: FastAPI application with async support
- RAG Engine: haiku.rag-slim with LanceDB vector storage
- AI Integration: Pydantic AI for agent management
- Authentication: Python-Keycloak with OIDC/JWT support
- MCP: FastMCP server and client implementations
- Configuration: YAML-based configuration system
Key modules:
views/- API endpoints (auth, completions, conversations, rooms, quizzes)agents.py- AI agent configuration and managementagui/- AG-UI thread persistence and retrievaltools.py- Tool definitions for AI agentsmcp_server.py/mcp_client.py- Model Context Protocol integrationtui/- Terminal user interface
Frontend (/src/flutter/)
Flutter 3.35+ / Dart 3.10.0+
- Framework: Flutter web with Material Design
- State Management: Riverpod (2.6.1)
- Navigation: Go Router (16.0.0)
- Authentication: Flutter AppAuth (9.0.1) for OIDC
- Real-time: WebSocket communication
- Secure Storage: Flutter Secure Storage for credentials
Key files:
main.dart- Application entry pointsoliplex_client.dart- Backend API clientoidc_client.dart- OIDC authentication clientcontrollers.dart- Riverpod state managementconfigure.dart- Configuration UI
TUI (src/soliplex/tui)
Quick-and-dirty client for room queries
- Framework: Python
textual
Quick Start
For detailed installation instructions, see the Prerequisites Guide.
Install Soliplex and dependencies
# Install
python3.13 -m venv venv
source venv/bin/activate
pip install -e .
# Configure environment
cp .env.example .env
# Edit .env with your settings
Index Soliplex docs into RAG database
source venv/bin/activate
export OLLAMA_BASE_URL=<your Ollama server / port>
# Run docling-serve if you have not installed the full haiku.rag
docker run -p 5001:5001 -d -e DOCLING_SERVE_ENABLE_UI=1 \
quay.io/docling-project/docling-serve
haiku-rag --config example/haiku.rag.yaml \
init --db db/rag/rag.lancedb
haiku-rag --config example/haiku.rag.yaml \
add-src --db db/rag/rag.lancedb docs/
...
17 documents added successfully.
See: docs/rag.md for more options.
Backend Server CLI Commands
The soliplex-cli command provides several utilities for managing your Soliplex installation:
Check Configuration
Validate your configuration file and report any missing secrets or environment variables:
soliplex-cli check-config example/minimal.yaml
List Rooms
Show all configured chat rooms:
soliplex-cli list-rooms example/minimal.yaml
List Completions
Show all configured completion endpoints:
soliplex-cli list-completions example/minimal.yaml
List Secrets
Display all configured secrets and their status:
soliplex-cli list-secrets example/minimal.yaml
List Environment Variables
Show all environment variables and their values:
soliplex-cli list-environment example/minimal.yaml
List OIDC Providers
Display configured OIDC authentication providers:
soliplex-cli list-oidc-auth-providers example/minimal.yaml
Export Configuration
Export the installation configuration as YAML:
soliplex-cli config example/minimal.yaml
Export AG-UI Feature Schemas
Export AG-UI feature schemas as JSON:
soliplex-cli agui-feature-schemas example/minimal.yaml
Run Backend Server
Start the Soliplex backend server:
export OLLAMA_BASE_URL=<your Ollama server / port>
soliplex-cli serve example/minimal.yaml --no-auth-mode
Server options:
--no-auth-mode- Disable authentication (for development/testing)--host HOST- Bind to specific host (default: 127.0.0.1)--port PORT- Listen on specific port (default: 8000)--reload {python,config,both}- Enable hot reload for python code, config, or both--reload-dirs DIRS- Additional directories to watch for reload--reload-includes PATTERNS- File patterns to include in reload watch--proxy-headers- Enable proxy header parsing--forwarded-allow-ips IPS- Trusted IP addresses for proxy headers
Frontend
cd src/flutter
flutter pub get
flutter run -d chrome --web-port 59001
TUI
The TUI does not yet support authentication, so run the back-end with
--no-auth-mode when using the TUI.
Within the virtual environment where you installed soliplex:
soliplex-tui --help
Usage: soliplex-tui [OPTIONS]
โญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ --version -v โ
โ --url TEXT Base URL for Soliplex back-end โ
โ [default: http://127.0.0.1:8000] โ
โ --help -h Show this message and exit. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
soliplex-tui
By default, the TUI connects to a Soliplex back-end server running on port 8000 on your local machine:
soliplex-tui --url http://127.0.0.1:8000
Development
This project uses PEP 735 Dependency Groups
for managing development dependencies. This is the modern standard supported by
uv and recent versions of pip.
Installing dev dependencies
# Using pip (requires pip 24.0+)
pip install -e . --group dev
# Using uv (recommended)
uv sync --group dev
Note: The older syntax pip install -e ".[dev]" is for [project.optional-dependencies]
and will NOT work with [dependency-groups]. Always use --group dev instead.
Available dependency groups
| Group | Purpose |
|---|---|
dev | Testing tools (pytest, ruff, coverage) |
docs | Documentation (mkdocs, mkdocs-material) |
postgres | PostgreSQL support (asyncpg) |
tui | Terminal UI (textual, typer) |
Running tests
# Run unit tests with coverage
pytest
# Run with specific coverage threshold (CI enforces 100%)
pytest --cov-fail-under=100
# Run linting
ruff check
# Check formatting
ruff format --check
Configuration
YAML-based configuration with:
- Installation (
installation.yaml) - Main config referencing agents, rooms, and OIDC providers - Rooms (
rooms/*.yaml) - Individual chat room configurations with RAG settings - Agents (
completions/*.yaml) - LLM provider and model configurations - OIDC (
oidc/*.yaml) - Authentication provider settings
See example/ directory for sample configurations.
Environment Variables
Non-secret environment variables can and mostly should be configured
directly in the installation.yaml file (e.g. example/installation.yaml,
example/minimal.yaml, etc.).
Those files are checked into the Soliplex repository, and cannot know
the URL of your Ollama server (if you use Ollama), They therefore declare
the OLLAMA_BASE_URL variable without a value, meaning that the configuration
expects the value to be present in the environments (see:
https://soliplex.github.io/soliplex/config/environment/).
Those files also must not contain secrets (API keys, etc.): instead, they configure secret values to be found from the environment (see https://soliplex.github.io/soliplex/config/secrets/).
If your installation configures such values to be found from the OS
environment, you can create a .env file which defines them, and arrange
for the file to be sourced into your environment before startin the Soliplex
application.
Copy .env.example to .env and edit it to configure your values:
cp .env.example .env
Documentation
Comprehensive documentation is available in the docs/ directory:
- Prerequisites Guide - Step-by-step installation checklist
- Server Setup - Backend server configuration and CLI reference
- Client Setup - Frontend Flutter application setup
- Docker Deployment - Complete Docker and docker-compose guide
- RAG Setup - RAG database initialization and management
- Configuration - Detailed configuration options
Running with Docker
See the Docker Deployment Guide for complete instructions:
# Setup
cp .env.example .env
# Edit .env with your settings
# Run
docker-compose up
Access:
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
- Frontend Web UI: http://localhost:9000
Related Repositories
- soliplex/flutter - Flutter frontend (cross-platform mobile/desktop)
- Documentation - Documentation site (MkDocs)
- soliplex/ingester - Content ingestion pipeline
- soliplex/ingester-agents - Document ingestion agents
- soliplex/whitelabel - Customer white-label appshell template
License
MIT License - Copyright (c) 2025 Enfold Systems, Inc.
