soliplex 0.42__tar.gz

soliplex-0.42/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Enfold Systems, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soliplex-0.42/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: soliplex
+Version: 0.42
+Summary: An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface.
+Author-email: Enfold <info@enfoldsystems.net>
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ag-ui-protocol>=0.1.10
+Requires-Dist: aiosqlite
+Requires-Dist: authlib
+Requires-Dist: fastapi
+Requires-Dist: fastmcp<2.15,>=2.14.0
+Requires-Dist: greenlet
+Requires-Dist: haiku.rag-slim<0.30.0,>=0.29.1
+Requires-Dist: itsdangerous
+Requires-Dist: jsonpatch
+Requires-Dist: jwcrypto
+Requires-Dist: logfire[fastapi]
+Requires-Dist: pydantic-ai-slim[google]
+Requires-Dist: pyjwt
+Requires-Dist: python-keycloak
+Requires-Dist: sqlmodel
+Requires-Dist: starlette
+Requires-Dist: trio
+Requires-Dist: uvicorn[standard]
+Requires-Dist: certifi>=2025.11.12
+Dynamic: license-file
+
+https://pypi.org/project/haiku.rag-slim/# 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](https://pypi.org/project/haiku.rag-slim/)
+  with LanceDB vector storage
+- **AI Integration**: [Pydantic AI](https://pypi.org/project/pydantic-ai/)
+  for agent management
+- **Authentication**: Python-Keycloak with OIDC/JWT support
+- **MCP**: [FastMCP](https://pypi.org/project/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 management
+- `agui/` - AG-UI thread persistence and retrieval
+- `tools.py` - Tool definitions for AI agents
+- `mcp_server.py` / `mcp_client.py` - Model Context Protocol integration
+- `tui/` - 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 point
+- `soliplex_client.dart` - Backend API client
+- `oidc_client.dart` - OIDC authentication client
+- `controllers.dart` - Riverpod state management
+- `configure.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](docs/prerequisites.md).
+
+### Install Soliplex and dependencies
+
+```bash
+# 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
+
+```bash
+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:
+```bash
+soliplex-cli check-config example/minimal.yaml
+```
+
+#### List Rooms
+Show all configured chat rooms:
+```bash
+soliplex-cli list-rooms example/minimal.yaml
+```
+
+#### List Completions
+Show all configured completion endpoints:
+```bash
+soliplex-cli list-completions example/minimal.yaml
+```
+
+#### List Secrets
+Display all configured secrets and their status:
+```bash
+soliplex-cli list-secrets example/minimal.yaml
+```
+
+#### List Environment Variables
+Show all environment variables and their values:
+```bash
+soliplex-cli list-environment example/minimal.yaml
+```
+
+#### List OIDC Providers
+Display configured OIDC authentication providers:
+```bash
+soliplex-cli list-oidc-auth-providers example/minimal.yaml
+```
+
+#### Export Configuration
+Export the installation configuration as YAML:
+```bash
+soliplex-cli config example/minimal.yaml
+```
+
+#### Export AG-UI Feature Schemas
+Export AG-UI feature schemas as JSON:
+```bash
+soliplex-cli agui-feature-schemas example/minimal.yaml
+```
+
+#### Run Backend Server
+Start the Soliplex backend server:
+```bash
+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
+
+```bash
+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`:
+
+```bash
+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.                 │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+```bash
+soliplex-tui
+```
+
+By default, the TUI connects to a Soliplex back-end server running
+on port 8000 on your local machine:
+
+```bash
+soliplex-tui --url http://127.0.0.1:8000
+```
+
+## Development
+
+This project uses [PEP 735 Dependency Groups](https://peps.python.org/pep-0735/)
+for managing development dependencies. This is the modern standard supported by
+`uv` and recent versions of `pip`.
+
+### Installing dev dependencies
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+cp .env.example .env
+```
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/` directory:
+
+- **[Prerequisites Guide](docs/prerequisites.md)** - Step-by-step installation checklist
+- **[Server Setup](docs/server.md)** - Backend server configuration and CLI reference
+- **[Client Setup](docs/client.md)** - Frontend Flutter application setup
+- **[Docker Deployment](docs/docker.md)** - Complete Docker and docker-compose guide
+- **[RAG Setup](docs/rag.md)** - RAG database initialization and management
+- **[Configuration](docs/config/)** - Detailed configuration options
+
+### Running with Docker
+
+See the [Docker Deployment Guide](docs/docker.md) for complete instructions:
+
+```bash
+# 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](https://github.com/soliplex/flutter)** - Flutter frontend (cross-platform mobile/desktop)
+- **[Documentation](https://soliplex.github.io/)** - Documentation site (MkDocs)
+- **[soliplex/ingester](https://github.com/soliplex/ingester)** - Content ingestion pipeline
+- **[soliplex/ingester-agents](https://github.com/soliplex/ingester-agents)** - Document ingestion agents
+- **[soliplex/whitelabel](https://github.com/soliplex/whitelabel)** - Customer white-label appshell template
+
+## License
+
+MIT License - Copyright (c) 2025 Enfold Systems, Inc.

soliplex-0.42/README.md

@@ -0,0 +1,326 @@
+https://pypi.org/project/haiku.rag-slim/# 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](https://pypi.org/project/haiku.rag-slim/)
+  with LanceDB vector storage
+- **AI Integration**: [Pydantic AI](https://pypi.org/project/pydantic-ai/)
+  for agent management
+- **Authentication**: Python-Keycloak with OIDC/JWT support
+- **MCP**: [FastMCP](https://pypi.org/project/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 management
+- `agui/` - AG-UI thread persistence and retrieval
+- `tools.py` - Tool definitions for AI agents
+- `mcp_server.py` / `mcp_client.py` - Model Context Protocol integration
+- `tui/` - 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 point
+- `soliplex_client.dart` - Backend API client
+- `oidc_client.dart` - OIDC authentication client
+- `controllers.dart` - Riverpod state management
+- `configure.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](docs/prerequisites.md).
+
+### Install Soliplex and dependencies
+
+```bash
+# 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
+
+```bash
+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:
+```bash
+soliplex-cli check-config example/minimal.yaml
+```
+
+#### List Rooms
+Show all configured chat rooms:
+```bash
+soliplex-cli list-rooms example/minimal.yaml
+```
+
+#### List Completions
+Show all configured completion endpoints:
+```bash
+soliplex-cli list-completions example/minimal.yaml
+```
+
+#### List Secrets
+Display all configured secrets and their status:
+```bash
+soliplex-cli list-secrets example/minimal.yaml
+```
+
+#### List Environment Variables
+Show all environment variables and their values:
+```bash
+soliplex-cli list-environment example/minimal.yaml
+```
+
+#### List OIDC Providers
+Display configured OIDC authentication providers:
+```bash
+soliplex-cli list-oidc-auth-providers example/minimal.yaml
+```
+
+#### Export Configuration
+Export the installation configuration as YAML:
+```bash
+soliplex-cli config example/minimal.yaml
+```
+
+#### Export AG-UI Feature Schemas
+Export AG-UI feature schemas as JSON:
+```bash
+soliplex-cli agui-feature-schemas example/minimal.yaml
+```
+
+#### Run Backend Server
+Start the Soliplex backend server:
+```bash
+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
+
+```bash
+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`:
+
+```bash
+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.                 │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+```bash
+soliplex-tui
+```
+
+By default, the TUI connects to a Soliplex back-end server running
+on port 8000 on your local machine:
+
+```bash
+soliplex-tui --url http://127.0.0.1:8000
+```
+
+## Development
+
+This project uses [PEP 735 Dependency Groups](https://peps.python.org/pep-0735/)
+for managing development dependencies. This is the modern standard supported by
+`uv` and recent versions of `pip`.
+
+### Installing dev dependencies
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+cp .env.example .env
+```
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/` directory:
+
+- **[Prerequisites Guide](docs/prerequisites.md)** - Step-by-step installation checklist
+- **[Server Setup](docs/server.md)** - Backend server configuration and CLI reference
+- **[Client Setup](docs/client.md)** - Frontend Flutter application setup
+- **[Docker Deployment](docs/docker.md)** - Complete Docker and docker-compose guide
+- **[RAG Setup](docs/rag.md)** - RAG database initialization and management
+- **[Configuration](docs/config/)** - Detailed configuration options
+
+### Running with Docker
+
+See the [Docker Deployment Guide](docs/docker.md) for complete instructions:
+
+```bash
+# 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](https://github.com/soliplex/flutter)** - Flutter frontend (cross-platform mobile/desktop)
+- **[Documentation](https://soliplex.github.io/)** - Documentation site (MkDocs)
+- **[soliplex/ingester](https://github.com/soliplex/ingester)** - Content ingestion pipeline
+- **[soliplex/ingester-agents](https://github.com/soliplex/ingester-agents)** - Document ingestion agents
+- **[soliplex/whitelabel](https://github.com/soliplex/whitelabel)** - Customer white-label appshell template
+
+## License
+
+MIT License - Copyright (c) 2025 Enfold Systems, Inc.