AI Query & Assistant

Overview#

The AI layer in Mithrilis lets you ask questions about your logistics data in plain English and get structured, trustworthy answers — backed by your actual data, not hallucinations.

Instead of writing SQL or navigating dashboards, your team can ask things like "How many shipments were late last week?" or "What's the average transit time for FedEx from Memphis to Dallas?" and get an accurate answer drawn from your connected databases, documents, and definitions.

The system is designed for trust: every answer shows its sources, explains its reasoning, and gives you confidence indicators so you know how much to rely on the result.

AI Assistant with conversational interface and source attribution

Query Router#

The query router is the intelligence behind how Mithrilis handles questions. When you ask something, the router doesn't just run a search — it classifies your query and routes it to the right execution path.

4-Way Classification#

Every query is analyzed and classified into one of four categories:

• SQL lookup — Questions that can be answered by querying your connected databases (e.g., "How many shipments are in transit?")
• Document retrieval — Questions that require finding information in uploaded documents (e.g., "What are the penalty clauses in our FedEx contract?")
• Computed metric — Questions that need calculation across multiple data points (e.g., "What's our on-time delivery rate this quarter?")
• Conversational — General questions, follow-ups, and clarifications that don't need data lookup (e.g., "Can you explain that in simpler terms?")

The classifier runs in milliseconds and routes to the appropriate execution pipeline. This means simple SQL lookups are fast, document searches use RAG for accuracy, and conversational follow-ups maintain context without unnecessary database queries.

RAG Integration#

For document-based queries, the router uses Retrieval-Augmented Generation (RAG) to connect your question to the most relevant passages in your Knowledge Base:

• Documents and definitions are pre-embedded using vector embeddings
• When a document query arrives, the system performs a semantic similarity search to find the most relevant chunks
• Those chunks are included as context when generating the answer, grounding the AI's response in your actual documentation

Unified SQL Executor#

For data queries, the router translates your natural language question into SQL:

• The generated SQL is shown alongside the answer so you can verify it
• Results are displayed in a structured table format
• The executor works across all connected data sources in the Knowledge Base

Query router in action — natural language to SQL with result table

Conversational Assistant#

The assistant is a full chat interface for interacting with your data over multiple turns.

Conversation Management#

• Multi-conversation support — Create and manage multiple conversation threads. Each conversation maintains its own context, so you can have one thread investigating carrier performance and another exploring cost data.
• Collapsible sidebar — Conversations are listed in a sidebar that can be collapsed to maximize the chat area. The sidebar stays out of your way when you're focused on a single conversation.
• Star, rename, and delete — Organize your conversations. Star important ones for quick access, rename them for clarity, and delete ones you no longer need.
• Edit and delete messages — Made a typo or want to rephrase? Edit or delete individual messages within a conversation.

Session Persistence#

Conversations are persisted server-side using Redis-backed caching, with a Zustand store on the client for fast local state management. This means:

• Your conversations survive page refreshes and browser restarts
• Session data loads instantly from the client cache while syncing with the server in the background
• Multiple team members can have their own independent conversation histories

ML and Embeddings#

The @convoya/ml package provides the machine learning foundation that powers the AI layer.

Vector Search#

• pgvector integration — Vector embeddings are stored alongside your relational data in PostgreSQL, enabling hybrid queries that combine semantic search with traditional SQL filters
• OpenAI embeddings — Documents, definitions, and queries are embedded using OpenAI's embedding models for high-quality semantic understanding
• Similarity search — When the AI needs context, it performs a vector similarity search to find the most relevant documents and definitions, ranked by semantic relevance

Embedding Pipeline#

Documents uploaded to the Knowledge Base are automatically processed:

1. Content is extracted and cleaned
2. Text is chunked into semantically meaningful segments
3. Each chunk is embedded using the configured embedding model
4. Embeddings are stored in pgvector for fast retrieval

This pipeline runs asynchronously, so uploading a document doesn't block your workflow. Embeddings are typically available within minutes.

ML pipeline — document processing, embedding, and vector search

Shared Reasoning#

A reasoning component library standardizes how AI results are presented across the platform. Instead of each feature implementing its own result display, they all use shared components that present information consistently.

Confidence Categories#

Raw confidence percentages are replaced with human-readable categories:

• High confidence — The AI is very sure about this answer, backed by strong data support
• Medium confidence — The answer is likely correct but may have some uncertainty
• Low confidence — The AI found relevant data but the answer should be verified
• Insufficient data — Not enough information to provide a reliable answer

These categories are more useful than showing "87.3% confidence" because they give a clear signal about how much to trust the result.

Cross-Platform Reuse#

The reasoning components are used across:

• The Query Playground
• The Conversational Assistant
• Data Unification confidence scoring
• Any future AI-powered feature in the platform

This consistency means your team learns one mental model for understanding AI outputs and applies it everywhere.

Getting Started#