Safira AI Chatbot

Retrieval, in the database

The knowledge base lives next to the conversations in Supabase. Similarity search is one SQL function, so the API stays thin and the ranking is testable on its own.

-- server/sql/schema.sql (production)
create or replace function match_documents (
  query_embedding vector(1024),
  match_count     int default 5,
  filter_lang     text default null
)
returns table (id bigint, content text, lang text, source text, similarity float)
language sql stable
as $$
  select d.id, d.content, d.lang, d.source,
         1 - (d.embedding <=> query_embedding) as similarity
  from documents d
  where filter_lang is null or d.lang = filter_lang
  order by d.embedding <=> query_embedding
  limit match_count;
$$;

Both languages are searched on purpose. A question in Arabic can be answered from an English page, and Claude replies in the visitor's language.

Grounding as a rule, not a hope

If the sources don't cover it, Safira says so and offers WhatsApp. It never quotes a price it didn't retrieve.

The demo in demos/safira_grounded_chat shows that contract with a confidence floor: below it, the assistant hands the visitor to a human instead of answering.

The live demo on this page

The chat above calls a server route, so the key never reaches the browser. With a key configured, the FastAPI service streams Claude's answer from retrieved sources. Without one, or if the model is down, it degrades to retrieval-only answers instead of failing.

# services/safira-api/app/llm.py
async with self.client.beta.messages.stream(
    model=MODEL,                      # claude-opus-5-5
    max_tokens=2048,
    system=SYSTEM,                    # answer only from numbered sources, cite [n]
    messages=messages,
    output_config={"effort": "low"},  # chat: fast first token
    betas=["server-side-fallback-2026-07-01"],
    fallbacks="default",
) as stream:
    async for text in stream.text_stream:
        yield text

Rate limiting (a per-IP token bucket), input caps, history trimming and the offline fallback are all covered by the service's 11 automated tests.