CLAUDE.md · diff
git:20260413.8a9df6d to git:20260422.fce3da4
51 added, 35 removed. Audit A to A.
# CLAUDE.md
- Guidance for AI assistants working with the Soliplex codebase.
+ 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/flutter> 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
- ```text
- src/soliplex/
- ├── views/ # FastAPI routers
- ├── config/ # YAML config parsing (16 modules)
- ├── agui/ # AG-UI protocol (threads, runs, persistence)
- ├── authz/ # Authorization policy engine
- ├── tools/ # Agent tools (RAG, feedback, file uploads)
- ├── tui/ # Terminal UI (Textual)
- ├── main.py # FastAPI app factory
- ├── cli.py # CLI entry point
- ├── installation.py # Installation management
- ├── agents.py # Pydantic AI agent creation
- ├── models.py # Public API response models
- ├── authn.py # OIDC/JWT authentication
- ├── mcp_server.py # FastMCP server
- ├── mcp_client.py # MCP client toolsets
- ├── mcp_auth.py # MCP token auth
- ├── secrets.py # Secret resolution
- └── completions.py # OpenAI-compatible streaming
- tests/
- ├── unit/ # 100% coverage required
- └── functional/ # Require LLM, skip by default
- example/ # Configs: rooms, completions, oidc, quizzes, skills
- docs/ # MkDocs documentation
- schemas/ # AG-UI feature JSON schemas
- ```
+ 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
+ - 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
- - Private fields `_installation_config` and `_config_path` carry context
+ - 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 (>=0.38.0) -- RAG functionality
- - FastMCP (>=2.14.0) -- Model Context Protocol
- - ag-ui-protocol (>=0.1.15) -- AG-UI event protocol
+ - haiku.rag-slim -- RAG functionality
+ - FastMCP -- Model Context Protocol
+ - ag-ui-protocol -- AG-UI event protocol
- SQLModel / aiosqlite -- Database ORM
- - haiku-skills (>=0.13.2) -- Haiku skills framework
+ - haiku-skills -- Haiku skills framework
## Entry Points
- - `soliplex-cli` -- Backend CLI (serve, check-config, list-rooms,
- validate-config, add-admin-user)
+ - `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
MkDocs). Example configurations are in [example/](example/).