Sententia

FastAPI-based search and RAG engine for local Markdown files, powered by FAISS and multilingual E5 embeddings.

Quick Start

Install:

pip install sententia

Run with OpenAI-compatible LLM:

sententia /path/to/markdown/docs \
  --llm-protocol openai \
  --llm-url https://api.openai.com \
  --llm-model gpt-4o \
  --llm-token sk-...

Run with Anthropic:

sententia /path/to/markdown/docs \
  --llm-protocol anthropic \
  --llm-url https://api.anthropic.com \
  --llm-model claude-sonnet-4-6 \
  --llm-token sk-ant-...

Run with Ollama (no API key needed):

sententia /path/to/markdown/docs \
  --llm-protocol ollama \
  --llm-url http://localhost:11434 \
  --llm-model llama3

Features

• Semantic search — FAISS index with intfloat/multilingual-e5-base embeddings
• RAG Q&A — retrieve relevant chunks and generate answers via LLM
• Multiple LLM providers — OpenAI, Anthropic, Ollama
• Dual interface — REST API server or MCP server (Model Context Protocol)
• File access — read original Markdown files by relative path

Usage

sententia DATA_DIR [OPTIONS]

Option	Description	Default
DATA_DIR	Path to Markdown files directory	(required)
--index-path	Path to FAISS index file (persisted)	in-memory
--llm-protocol	LLM provider: openai, anthropic, ollama	(required)
--llm-url	LLM API base URL (without /v1 version path)	(required)
--llm-model	LLM model identifier	(required)
--llm-token	API key (falls back to SENTENTIA_LLM_TOKEN env var)	—
--host	Server bind address	0.0.0.0
--port	Server port	8000
--mcp	Run as MCP server instead of REST API	false

Reference

REST API

Search documents

POST /search

{ "query": "how to configure logging", "top": 10 }

Response:

{
  "results": [
    { "text": "...", "source": "docs/guide.md", "score": 0.87 }
  ]
}

Parameter	Type	Default	Description
query	string	""	Search query
top	integer	10	Number of results (1–100)

Ask a question (RAG)

POST /ask

{ "query": "how to configure logging" }

Response:

{
  "answer": "To configure logging...",
  "sources": ["docs/guide.md", "docs/reference.md"]
}

Parameter	Type	Default	Description
query	string	""	Question to answer

Read file

GET /files/{path}

Response:

{ "text": "file contents...", "source": "docs/guide.md" }

MCP Tools

Launch with --mcp flag to expose tools via Model Context Protocol.

search — Search for relevant documents in the knowledge base.

Parameter	Type	Default	Description
query	string	—	Search query
top	integer	10	Number of results

Returns list of { text, source, score }.

ask — Ask a question and get an answer based on indexed documents.

Parameter	Type	Default	Description
query	string	—	Question to answer

Returns { answer, sources }.

files — Read file content by path.

Parameter	Type	Default	Description
path	string	—	Relative file path

Returns { text, source }.

Development

Clone and install with dev dependencies:

git clone https://github.com/qarium/sententia.git
cd sententia
pip install -e ".[test]"

Run tests:

pytest

Lint:

ruff check sententia tests