Skip to content

Phase 1 — Working end-to-end pipeline

Status: Current

Phase 1 delivers a fully functional RAG chatbot over a knowledge graph. Every layer from ingestion to the chat interface is in place and tested on the Reactome biological pathway graph.

What is included

Data ingestion

  • POST /dev/build_vector_index — one-time index build from all nodes with a text property
  • Batch embedding with overlap-aware chunking (agentlib/rag/chunker.py)
  • Idempotent build: interrupted runs resume from cached batches (agentlib/rag/cache.py)
  • Embedding providers: Ollama and sentence-transformers (local, no API key needed)

Retrieval

  • Vector similarity search via TuringDB's built-in vector index (agentlib/rag/index.py)
  • Cypher graph queries via the TuringDB Python client (agentlib/graph/query.py)
  • Schema introspection: db.labels(), db.edgeTypes(), db.propertyTypes() (agentlib/graph/schema.py)
  • Graph skeleton generation at startup (agentlib/graph/skeleton.py)

Intent routing and handlers

  • Two routes: lookup and agent (chat-agent/router.py)
  • Confidence-based escalation: lookup below threshold (0.75) is promoted to agent
  • lookup_handler — vector search → formatted Markdown, no LLM call
  • agent_handler — agentic loop, up to 32 iterations, with 7 tools
  • rag_handler — single-turn RAG exists in code but is not wired to the router

Agent tools

Tool Description
vector_search Semantic similarity search over the knowledge base
graph_query Execute a Cypher query against TuringDB
get_node_labels All node label types in the graph
get_edge_types All edge (relationship) types in the graph
get_property_types All property names and their types
get_node_label_counts Node labels with their counts
get_edge_type_counts Edge types with their counts

Server

  • FastAPI with full OpenAPI docs at /docs
  • Anonymous user identity via anon_id cookie (3-day TTL, rotated after 2 hours)
  • Chat session persistence in Valkey (7-day TTL, refreshed on activity)
  • Per-user rate limiting: 20 requests / 10 min and 500 000 tokens / 10 min
  • MCP tools exposed at /mcp_tools/

Interfaces

  • Streamlit web UI (app/)
  • Textual TUI for service management (tui/)
  • uv run askalan starts everything from one command

Open items in Phase 1

Item Notes
POST /query is a stub Raises NotImplementedError — implement vector search + RAG single-call endpoint
rag_handler not active Available in code but not wired to the router
CORS ["*"] Must be restricted to known origins before any HTTPS deployment
secure=False on anon_id cookie Must be True before any HTTPS deployment

Supported graph

Phase 1 supports a single graph: Reactome (biological pathway database, ~700k nodes and ~2M edges).

Multi-graph support is deferred to Phase 4.