Running Alan — Local

Running without Docker gives lower latency and direct access to logs. You need to manage a few system services yourself, but the TUI handles the rest.

Prerequisites

• uv — Python package manager
• Valkey — in-memory session store
• Ollama — local LLM and embedding server

Step 1 — Install and start system services

brew install valkey ollama
brew services start valkey
brew services start ollama

sudo apt-get install valkey
# Install Ollama via the official installer:
curl -fsSL https://ollama.com/install.sh | sh

sudo systemctl start valkey
sudo systemctl start ollama
# Enable on boot:
sudo systemctl enable valkey ollama

Step 2 — Pull Ollama models

ollama pull qwen2.5:3b   # intent router (fast, small)
ollama pull qwen2.5:7b   # agent (more capable)

The default model names are set in .env.example. If you want to use different models, override OLLAMA_ROUTER_MODEL and OLLAMA_AGENT_MODEL in your .env file.

The embedding model (minishlab/potion-base-32M) is a sentence-transformers model downloaded automatically from Hugging Face the first time you build the vector index — no manual step needed.

Step 3 — Clone the repo

git clone https://github.com/turing-db/askalan.git
cd askalan

No uv sync needed — the TUI and each sub-package manage their own dependencies through the uv workspace.

Step 4 — Provide the knowledge graph

Create the turing-dir directory at the project root — TuringDB will read and write graph files here:

mkdir -p turing-dir

Then import a graph into it. To use the default Reactome graph, follow the import instructions in turing-bench. For a custom graph, import it into TuringDB and save it under turing-dir/.

Step 5 — Start Alan

Option A — TUI (recommended)

The TUI starts and monitors all services (TuringDB, FastAPI, Streamlit) from a single terminal window and shows live logs for each:

uv run askalan

No manual uv sync or individual server commands needed — the TUI handles everything. Use the RAG tab to build the vector index the first time.

Option B — Manual startup

Start each service in a separate terminal from the project root.

TuringDB:

uv run turingdb -demon -turing-dir ./turing-dir -load reactome -p 1234

FastAPI server:

uv run --directory server fastapi run

Streamlit app:

uv run streamlit run ./app/main.py

Step 6 — Build the vector index (first time only)

After the servers are running, build the vector index once:

curl -X POST http://localhost:8000/dev/build_vector_index \
  -H "Content-Type: application/json" \
  -d '{"graph_name": "reactome", "model": "minishlab/potion-base-32M"}'

The index persists inside TuringDB — you do not need to rebuild it on subsequent runs. The TUI's RAG tab provides a "Build index" button that does the same thing.

Configuration

All settings have sensible defaults — the stack runs out of the box without a configuration file. To override specific settings, create a .env file at the project root:

cp .env.example .env
# edit as needed

Server settings (prefix TURINGDB_):

Chat-agent settings (no prefix):

Tip: ROUTER_PROVIDER lets you run a fast local model for intent classification while using Mistral for the agent — useful for reducing cloud costs on routing. Set LLM_PROVIDER=mistral ROUTER_PROVIDER=ollama to split the two.