The SpektraBot Brain

One page, no code. For executives, commissioners, clinical advisors, and anyone new to the project. Each section links to a deeper technical page. Last verified against source on 17 April 2026 (commit 8acfbb72e).

What "the brain" is

When a parent or professional sends a message, SpektraBot doesn't just hand the text to a language model and hope. The message travels through a pipeline. That pipeline decides how to respond, pulls the right source material from a curated knowledge base, assembles a system prompt tuned to who's asking and what they need, streams the answer back, and runs safety checks on what the model produced. Collectively, those stages are the brain.

The brain's job is to make the model's output safe, sourced, and appropriate to the situation. So a parent asking about an EHCP refusal gets trauma-informed guidance with the actual statute number. A SENCO asking the same thing gets a terse, actionable plan. And neither of them gets an invented paragraph number or a fabricated helpline.

The five layers

Routing decides what the user actually needs. Is this a greeting? A crisis? A vague query that needs clarifying? A pasted document? A specific question ready to answer? Wrong answers to the wrong questions are the commonest AI failure, so routing earns the right to everything that follows.

Retrieval pulls supporting material from about 450 000 chunks of curated content: the SEND Code of Practice, local authority Local Offers, national charity pages, and school policies. The answer has to come from real sources, and usually from the user's own local authority.

Prompting assembles a system prompt from 12 modular pieces: the base rules, a role module matching the user's persona, and a task module matching their intent. Same model, very different behaviour for a parent in crisis versus a SENCO writing Section F.

Generation streams a response from Azure OpenAI GPT-4.1, with tools bound (school search) and conversation history threaded in. Token-by-token streaming keeps the interface responsive. Tool calls let the model fetch structured data when it needs to.

Safety and grounding runs alongside and after generation. Crisis helplines are injected deterministically. Citations the model couldn't have verified are hedged. Statutory facts (the 6-week response window, the 20-week plan deadline) are pattern-matched and any mismatches are logged. If a reference isn't in the retrieved sources, the system writes "ask your SENCO before using it", rather than leaving a parent to verify it themselves.

How a message moves through the brain

Most messages travel the happy path. The greeting check fails, the ambiguity check passes, retrieve pulls the top chunks, generate streams the answer, the hallucination check is skipped by default in production, and the response reaches the user in three to five seconds.

The exceptional paths are where the brain earns its keep.

The greeting fast path uses 39 regex patterns backed by a short LLM fallback. A matched greeting gets warm onboarding text, no retrieval, about 200ms.

The crisis path uses a deterministic keyword regex against self-harm, suicidal ideation, and safeguarding language. The helpline block is always prepended, never contingent on LLM output. It runs in parallel with normal generation so the user sees helpline numbers first.

The clarification path fires when a query is too vague to answer well ("tell me about SEND"). The brain emits an interactive clarification with options, rather than guessing.

The document-paste path fires when the user pastes an IPP, EHCP, or one-page profile. A structural-signals heuristic (document-header phrases plus field-value pairs plus length thresholds) routes to a dedicated document-review prompt. That heuristic was tightened after a round of review flagged false positives on long emotional narratives.

The 12 prompt modules

The system prompt is assembled fresh for every message from up to five of 12 modules:

Always	If crisis	Else: role	Else: task	Optional
base_core	crisis_response	role_parent or role_professional	task_letter_writing, task_document_review, task_nd_referral, or task_ehcp_writing	domain_social_services
confidence_signalling
tools_awareness
discovery (contextual)

Crisis mode overrides role and task. A parent in distress doesn't need a Section-F writing scaffold, they need the Samaritans number.

All 12 modules are stored in the database and as markdown files in packages/api/src/prompts/modules/. Deploys auto-seed new modules without overwriting admin edits. Admins edit module content through the /admin/prompts interface; changes take effect within the cache TTL.

See Prompt Modules for the per-module reference.

Where answers come from

The knowledge base is currently about 451 000 chunks across about 27 700 documents, covering 143 English local authorities plus national charity sources and school policies. Sources include:

• The SEND Code of Practice and Children and Families Act 2014 regulations. National, always available.
• Local Authority Local Offers. Each of 152 English LAs has its own seed URLs, crawled on a schedule.
• Charity content from IPSEA, SENDIASS, Contact, the NSPCC, and a handful of others.
• School SEND policies scraped from the websites of about 52 000 GIAS-registered schools, where available.

Retrieval is hybrid: vector similarity (cosine, 1536-dimension embeddings from Azure OpenAI text-embedding-3-large) combined with BM25 keyword search, fused via Reciprocal Rank Fusion. Results are biased towards the user's local authority, detected via their child's school URN or a fallback postcode lookup.

See Retrieval and Knowledge Base.

How we know it works

There's a standing evaluation harness:

• 176 test cases across 12 personas (parents at different life stages, SENCOs, trauma-informed cases, post-16, early years, and the Lancashire pilot schools).
• 29 custom graders, each watching for a distinct failure mode: overclaim, missing citation, invented deadline, missing LA context, jargon without expansion, deficit framing, context-forgetting across turns.
• A judge LLM (Azure OpenAI GPT-4.1-mini, a different family from the model under test) scores responses against per-tier rubrics.
• Runnable from /admin/evaluation in the web app. Live progress streams over SSE.

Specific numbers move, so they aren't pinned in this document. The admin UI is the source of truth.

See Evaluation.

Where it runs

Everything runs on Azure Container Apps in spektrabot-rg (UK South). Three apps (spektrabot-api, spektrabot-web, spektrabot-worker) alongside a managed Postgres (pgvector plus tsvector) and managed Redis. The Azure OpenAI GPT-4.1 and text-embedding-3-large deployments are also in UK South for UK data residency.

Older documentation may mention Civo Kubernetes, Helm charts, or GHCR. That stack was retired months ago. Ignore those references.

What the brain doesn't do

It doesn't fine-tune. GPT-4.1 is used as-is. The intelligence is in the prompt assembly, retrieval quality, and grounding checks.

It doesn't learn from individual conversations. Retention is controlled by GDPR policy, not by model training.

It doesn't call out to external services beyond Azure OpenAI and the internal knowledge base. The only registered tool today is an internal school search over the GIAS table.

It doesn't make clinical or legal determinations. Every statutory-fact surface is paired with a "by law..." marker and a route to SENDIASS, IPSEA, or tribunal advice for human-specialist follow-up.

Further reading

• Message Flow. End-to-end request journey, from Socket.IO to the final chunk.
• Prompt System. Assembly order, crisis override, admin management.
• Prompt Modules. All 12 modules documented individually.
• Agentic RAG. LangGraph state machine, nodes, self-correction.
• Retrieval. Hybrid search, RRF, LA bias, chunk expansion.
• Knowledge Base. Ingestion, crawlers, validation.
• Safety & Grounding. Crisis, security markers, grounding check, statutory validation.
• Evaluation. The promptfoo harness, graders, admin UI.
• Traces. Three worked examples end-to-end.