git:20260520.e763040 to git:20260601.86790aa

- This file provides guidance to Claude Code (claude.ai/code) when working

- with code in this repository.

-

- ## Project Overview

-

- Soliplex is an AI-powered RAG system with a FastAPI backend, Flutter web

- frontend, and terminal UI. It provides semantic document retrieval, multi-room

- chat, and multi-provider LLM support.

-

- **This repository contains the Python backend and TUI only.** The Flutter

- frontend lives in a sibling repo at

- <https://github.com/soliplex/frontend> with its own tooling.

-

- See `AGENTS.md` for deeper guidance on adding tools, rooms, and API

- endpoints.

-

- ## Quick Reference

-

- ```bash

- # Run unit tests (100% coverage required)

- uv run pytest

-

- # Run a single test file / test

- uv run pytest tests/unit/test_agents.py

- uv run pytest tests/unit/test_agents.py::test_name

-

- # Run functional tests (require a running LLM, skipped by default)

- uv run pytest tests/functional/ -m needs_llm

-

- # Lint and format

- uv run ruff check

- uv run ruff format --check

-

- # Start dev server

- uv run soliplex-cli serve example/minimal.yaml --no-auth-mode

-

- # Validate config

- uv run soliplex-cli check-config example/minimal.yaml

- ```

-

- ## Repository Structure

-

- Non-obvious modules and directories (the rest are self-explanatory from

- their filenames -- `ls src/soliplex/` for the full layout):

-

- - `agui/` -- AG-UI protocol (threads, runs, persistence)

- - `authz/` -- Authorization policy engine

- - `config/` -- YAML config parsing (16 modules, see `installation.py`

- for the top-level entry)

- - `tools/` -- Agent tools (RAG, feedback, file uploads)

- - `agents.py` -- Pydantic AI agent creation

- - `completions.py` -- OpenAI-compatible streaming endpoint (not just

- LLM-level completions)

- - `installation.py` -- Installation lifespan, admin bootstrap, and

- global state management

- - `main.py` -- FastAPI app factory (`create_app`)

- - `tests/unit/` -- 100% coverage required; mirrors `src/soliplex/`

- - `tests/functional/` -- tests requiring an LLM (marked `needs_llm`)

- are skipped by default; other functional tests run

- - `example/` -- sample configs (rooms, completions, oidc, quizzes, skills)

- - `schemas/` -- AG-UI feature JSON schemas

-

- ## Technical Details

-

- - Python 3.12+, ruff targets 3.13, line length 79

- - Single-line imports enforced via isort

- - 100% branch coverage enforced on unit tests; `cli.py`, `examples.py`,

- and `tui.py` are omitted from coverage (see `[tool.coverage.run]` in

- `pyproject.toml`) -- new code in those modules silently bypasses the

- threshold

- - Config classes use dataclasses with `from_yaml` classmethod pattern

- - Config dataclasses carry `_installation_config` and `_config_path` as

- private fields so nested configs can resolve env vars, secrets, and

- paths relative to the config file without threading them through every

- `from_yaml` call

-

- ## Key Dependencies

-

- See `pyproject.toml` for authoritative version constraints.

-

- - FastAPI / Uvicorn -- REST API and ASGI server

- - pydantic-ai-slim[google] -- Agent framework

- - haiku.rag-slim -- RAG functionality

- - FastMCP -- Model Context Protocol

- - ag-ui-protocol -- AG-UI event protocol

- - SQLModel / aiosqlite -- Database ORM

- - haiku-skills -- Haiku skills framework

-

- ## Entry Points

-

- - `soliplex-cli` -- Backend CLI; run `soliplex-cli --help` for the full

- command list

- - `soliplex-tui` -- Terminal UI client

- - `soliplex-tui-serve` -- TUI server

-

- ## Environment Variables

-

- See `.env.example` for the full reference. Key variables:

-

- - `OLLAMA_BASE_URL` -- Ollama server URL (without `/v1` suffix)

- - `OPENAI_API_KEY` / `GEMINI_API_KEY` -- LLM provider keys

- - `SOLIPLEX_URL_SAFE_TOKEN_SECRET` -- MCP token secret (auto-generated if

- unset)

- - `LOGFIRE_TOKEN` -- Pydantic Logfire token (optional)

-

- ## Documentation

- Detailed configuration and usage docs are in [docs/](docs/) (served via

- Zensical). Example configurations are in [example/](example/).