Skip to main content

Installation

This page covers installing AMADEQ LIS 3 and bringing the stack up locally. All processes are launched through a single bash entrypoint, run/run.sh, which starts, stops, health-checks and reports status for every layer.

Prerequisites​

  • Python ≥ 3.11 with a virtualenv at .venv/ in the project root. The run scripts prefer .venv/bin/python and fall back to python3.
  • Docker for the containerized dependencies: Qdrant (vector store), the TEI embeddings server, and the TEI reranker.
  • A CUDA-capable GPU with vllm installed in the virtualenv for the local model servers: guard (safety) and vlm (vision). These run as local vLLM processes, not Docker containers.
note

run/ does not manage Postgres. The infra group starts Qdrant only. Postgres connection settings are declared but no run script starts, migrates, or connects to Postgres — the Python services own that. For local development without Postgres, see the ENABLE_DB_ON_STARTUP note below.

Install dependencies​

Create the virtualenv and install requirements:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Start everything​

Bring up the full stack (externals first, then the FastAPI services):

bash run/run.sh start all

The invocation form is bash run/run.sh <action> <target>. Actions are start, stop, health, and status.

warning

start all is dependency-aware and strict: externals start first (qdrant, embeddings, reranker, guard, vlm), then the services (stt … gateway). Because this path runs under set -euo pipefail without per-item tolerance, the first failing dependency aborts the whole bring-up. The per-group targets below tolerate individual failures.

Start individual layers​

bash run/run.sh start infra        # Qdrant only
bash run/run.sh start services     # all FastAPI services
bash run/run.sh start chat_engine  # conversation_engine only
bash run/run.sh start gateway      # gateway_service only

Available targets:

TargetMembers
allexternals + services
servicesstt, tts_elevenlabs, tts_omnivoice, image_analysis, memory, rag, chat_engine, gateway
externalsqdrant, embeddings, reranker, guard, vlm
infraqdrant
mlembeddings, reranker, guard, vlm

Individual service and external names may also be passed directly (e.g. rag, memory, qdrant, guard).

Each FastAPI service is launched as a local uvicorn process bound to 127.0.0.1 on a fixed port, writes a pidfile to run/pids/<name>.pid, and logs to run/logs/<name>.log. Startup waits for the service's /health endpoint (30s) before reporting success.

Stop​

bash run/run.sh stop all

Stop is best-effort (never aborts): services are stopped first, then externals. Each service receives a single SIGTERM; the Docker externals are stopped with docker stop but their containers are not removed, so a later start reuses them.

Health check​

bash run/run.sh health all

health probes each target's health endpoint. status reports process/container state instead:

bash run/run.sh status all

Health endpoints (all under 127.0.0.1):

TargetHealth URL
gatewayhttp://127.0.0.1:8040/health
chat_enginehttp://127.0.0.1:8050/health
raghttp://127.0.0.1:8051/health
memoryhttp://127.0.0.1:8052/health
image_analysishttp://127.0.0.1:8012/health
stthttp://127.0.0.1:8010/health
tts_elevenlabshttp://127.0.0.1:8014/health
tts_omnivoicehttp://127.0.0.1:8015/health
qdranthttp://127.0.0.1:6333/healthz
embeddingshttp://127.0.0.1:8080/health
rerankerhttp://127.0.0.1:8081/health
guardhttp://127.0.0.1:4915/health
vlmhttp://127.0.0.1:8013/health
note

Qdrant uses /healthz, unlike every other target which uses /health.

Local development without Postgres​

Opening the database pool on startup is controlled by ENABLE_DB_ON_STARTUP (default true). For local development without a Postgres instance, set it to false:

ENABLE_DB_ON_STARTUP=false

Place it in .env (loaded by both the run scripts and the services) or export it in your shell.

Test console​

A minimal HTML console for exercising the gateway endpoints ships in .html_lis. Serve it with the standard library HTTP server:

python -m http.server 8062 --bind 127.0.0.1 --directory .html_lis
note

The console requires a running gateway service and a pre-existing avatar in the database.

Next steps​

  • Configuration — environment variables, defaults, and per-service settings.
  • Running the Services — the run/ scripts, process/container management, and startup ordering in depth.