Skip to content

Alan — a TuringDB Agent

Alan is a graph-powered RAG chatbot built on TuringDB. It combines vector similarity search, graph traversal, and LLM generation to answer natural-language questions over a knowledge graph.

The default configuration targets Reactome — an open-source, manually curated database of biological pathways and reactions. Reactome covers roughly 11 000 pathways and 700 000 molecular entities (proteins, genes, complexes, small molecules) connected by tens of millions of relationships, making it a rich graph for exploring questions about cellular processes, disease mechanisms, and drug targets. You do not need to know Reactome's schema to start asking questions: Alan explores the graph structure on its own before writing any queries. See Running Alan → Docker for import instructions.

You are not limited to Reactome — Alan works with any graph you load into TuringDB. See Using your own knowledge graph below.

How it works

Each incoming message is classified into one of two routes:

Route When What happens
lookup Specific fact, entity, or definition Vector search → formatted Markdown, no LLM call
agent Everything else: explanations, comparisons, multi-step reasoning Agentic loop: LLM calls tools iteratively until it synthesises an answer

Low-confidence lookup classifications are automatically escalated to agent.

User question
     │
     ▼
[Intent router]          ← classify_intent()
     │
     ├── lookup → [Embedding] → [Vector search] → Markdown
     │
     └── agent  → [LLM + tools]
                       │
                       ├── vector_search  ──── TuringDB vector index
                       ├── graph_query    ──── TuringDB Cypher engine
                       └── schema tools   ──── db.labels(), db.edgeTypes(), ...
                       │
                       ▼
                    Answer + sources

Key features

  • Graph skeleton — a compact structural summary of the knowledge graph injected into the agent system prompt at startup. Gives the LLM enough context to write correct Cypher queries without calling schema tools on every turn.
  • No external vector DB — vector indexes live inside TuringDB alongside the graph data.
  • Local-first embeddings — Ollama or sentence-transformers; no API key required for embeddings.
  • Pluggable LLM — start with Ollama locally, switch to Mistral via environment variable.
  • Session persistence — chat history stored in Valkey, keyed by anonymous user cookie.
  • Rate limiting — per-user sliding-window request and token budgets enforced in Valkey.

Using your own knowledge graph

To use Alan with a graph other than Reactome:

  1. Import your graph into TuringDB and save it to the turing-dir directory (the same volume TuringDB uses). Give it a name, e.g. mygraph.

  2. Set the graph name in .env: 

    TURINGDB_GRAPH=mygraph

  3. Build the vector index once the server is running: 

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

Nodes must have a text property

The current indexing pipeline fetches all nodes where n.text IS NOT NULL and uses that property for embedding. Nodes without a text property are not indexed and cannot be retrieved via vector search. Before loading your graph, make sure the nodes you want to be searchable carry a text property with descriptive prose.

Broader indexing strategies (embedding from multiple properties, neighbour-enriched text, publication abstracts) are planned for Phase 2.

Quick start

git clone https://github.com/turing-db/askalan.git
cd askalan
cp .env.example .env
mkdir -p turing-dir          # place your graph files here
docker compose up --build

Then pull an Ollama model and build the vector index — see Running Alan → Docker for the full walkthrough.

brew install valkey ollama
brew services start valkey ollama
ollama pull qwen2.5:3b && ollama pull qwen2.5:7b
git clone https://github.com/turing-db/askalan.git
cd askalan
uv run askalan          # starts TUI — handles everything else

See Running Alan → Local for the full walkthrough.