Skip to content

About

Open-source, self-hosted AI employees that ask before they act. 46 business roles, approval-gated autonomy, untrusted-content safeguards, sandboxed execution, Graph RAG and token budgets. Expanding across memory, voice, security and physical AI. WhatsApp, Telegram, Discord and 20 LLM providers. MIT licensed.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

2 watching

Forks

Latest commit

 

History

2,171 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RagLeap Core logo

RagLeap Core

Open-source AI employees that ask before they act.

Core engine

license MIT Core Release 46 AI Employees Autonomous Self--Hosted

RAG and retrieval (Python, Java, npm)

PyPI ragleap-rag Downloads Maven Central ragleap-rag (Java) npm @ragleap/rag PyPI ragleap-graph Downloads Maven Central ragleap-graph (Java) PyPI ragleap-vectorstores Downloads Maven Central ragleap-vectorstores (Java)

Agents and tools (Python)

PyPI ragleap-tools Downloads PyPI ragleap-integrations Downloads PyPI ragleap-agents Downloads

Speech (Python)

PyPI ragleap-voice Downloads

Memory and security (Python)

PyPI ragleap-memory Downloads PyPI ragleap-security Downloads

Tracing and cost (Python)

PyPI ragleap-trace Downloads PyPI ragleap-optimizer Downloads

Physical AI (Python, simulation only)

PyPI ragleap-physical Downloads

DevOps libraries (Python; Java jars for terraform, ansible and observability)

PyPI ragleap-ops Downloads PyPI ragleap-app-chart Downloads PyPI ragleap-observability Downloads Maven Central ragleap-observability (Java) PyPI ragleap-terraform Downloads Maven Central ragleap-terraform (Java) PyPI ragleap-ansible Downloads Maven Central ragleap-ansible (Java)

Community

Python Discord Repo clones

English · Afrikaans · العربية · Български · বাংলা · Català · Čeština · Cymraeg · Dansk · Deutsch · Ελληνικά · Español · Eesti · فارسی · Suomi · Français · ગુજરાતી · עברית · हिन्दी · Hrvatski · Magyar · Bahasa Indonesia · Italiano · 日本語 · ಕನ್ನಡ · 한국어 · Lietuvių · Latviešu · Македонски · മലയാളം · मराठी · नेपाली · Nederlands · Norsk · ਪੰਜਾਬੀ · Polski · Português · Română · Русский · Slovenčina · Slovenščina · Soomaali · Shqip · Svenska · Kiswahili · தமிழ் · తెలుగు · ไทย · Tagalog · Türkçe · Українська · اردو · Tiếng Việt · 简体中文 · 繁體中文

RagLeap Core is the open-source engine behind RagLeap — a self-hosted, agentic system that runs your business from your own documents on your own server, with no vendor lock-in.

46 role-based AI Employees: 9 core generalist roles (AI Manager, Secretary, CEO, Sales, Support, HR, Finance, Marketing, Operations) plus 37 vertical-specific global roles (Recruiter, Real Estate Agent, Legal Intake, Healthcare Intake, Insurance Agent, and more) — full list in core/employees/defaults.py.

What it does:

  • Self-learning, outcome-weighted memory
  • Auto-trigger workflows and escalation
  • Autonomy modes: off (default, the AI acts only when you start it), semi (you approve each action) and full (opt-in; sensitive roles are never fully autonomous)
  • Think-act-decide loop, not just retrieval
  • Act-observe agent loop (opt-in): the model proposes one action at a time, each action goes through the approval gate, and the result comes back as untrusted text
  • Safe tools, all opt-in: Python and shell in a network-less sandbox, read-only page fetch, an MCP client with an allowlist, task tickets and scheduled check-ins
  • AI Office dashboard at /office: approvals, employees by department, tasks, agent runs, activity, Settings and a Setup checklist
  • Can run fully local with Ollama for chat and embeddings (small models on a CPU are slower and less accurate than hosted ones), or with any of 19 provider options and your own key
  • Optional token budgets, failed-login throttling and an audit log of every action

Install in one command (needs Docker Desktop on macOS and Windows, or Docker Engine on Linux; the script asks which AI to use and never changes an existing .env):

curl -fsSL https://raw.githubusercontent.com/ragleap/ragleap-core/main/install.sh | bash

Prefer to read it first? See install.sh. For a fully local setup with no API key, use bash -s -- --ollama at the end of that command.

Windows: install Docker Desktop (it needs WSL 2 and CPU virtualization turned on) and Git for Windows, then type this in an open PowerShell window:

irm https://raw.githubusercontent.com/ragleap/ragleap-core/main/install.ps1 | iex

It asks which AI to use, builds and starts RagLeap, and opens the dashboard in your browser without printing your login key in the terminal. Type it directly in PowerShell: wrapped inside powershell -c "...", Windows Defender stopped that form on the one machine we tested. To read the script first, run $s = irm with the same address, look at $s, then run iex $s. After the install, run RagLeap commands in Git Bash from the install folder, for example bash scripts/ragleap key.

If port 8000 or 5433 is already used on your computer (for example by a local PostgreSQL), a fresh install picks the next free port and writes it to .env (APP_PORT, DB_PORT and so on). ragleap key --rotate replaces your API key and restarts the app; the old key stops working at once.

Honest limits: the Windows installer has been run on two Windows machines so far: the maintainer's, and one community tester's (Windows 11 with Docker Desktop and Ollama, see #781). On that second machine the local Ollama option installed, answered a question about an uploaded PDF and named its source. Response times were not measured. macOS and Linux desktops have not been verified yet.

Quickstart · Docs · Website · Packages


Open source, self-hosted. ragleap-core (this repo) is MIT-licensed, completely free, and never requires a license key. RagLeap is built for self-hosting; no managed cloud service is currently offered.

Install

pip install ragleap-rag

⭐ If this helps you, please consider starring the repo — it genuinely helps more people find it.

Prefer Java? ragleap-rag is also on Maven Central:

<dependency>
    <groupId>io.github.antonyrag</groupId>
    <artifactId>ragleap-rag</artifactId>
    <version>0.14.0</version>
</dependency>

Independently versioned from the Python package above — see java/ragleap-rag for current scope.

The Neo4j graph index has a Java port too, over the HTTP Query API (regex or, optionally, LLM entity and relation extraction, deduplication, document indexing and lookups, GraphRetriever, backfills and migrations, and the Postgres audit writer):

<dependency>
    <groupId>io.github.antonyrag</groupId>
    <artifactId>ragleap-graph</artifactId>
    <version>0.4.0</version>
</dependency>

See java/ragleap-graph for current scope.

The extra vector backends have a Java port too (OpenSearch, Upstash Vector and Redis Stack, each over its own protocol with no vendor SDK, implementing ragleap-rag's VectorBackend):

<dependency>
    <groupId>io.github.antonyrag</groupId>
    <artifactId>ragleap-vectorstores</artifactId>
    <version>0.1.0</version>
</dependency>

See java/ragleap-vectorstores for current scope.

Add ragleap-graph too if you want Neo4j-backed knowledge graph retrieval:

pip install ragleap-rag ragleap-graph

Add ragleap-vectorstores too if you want pluggable vector backends beyond ragleap-rag's built-in six (Chroma, LanceDB, Redis, Upstash Vector and OpenSearch):

pip install ragleap-rag ragleap-vectorstores[chroma]
# or, with uv
uv add ragleap-rag ragleap-vectorstores[chroma]

Add ragleap-tools too if you want ready-made tools for LLM tool-calling (calculator, sandboxed file ops, date/time, unit conversion, JSON/CSV parsing, text utilities):

pip install ragleap-rag ragleap-tools
# or, with uv
uv add ragleap-rag ragleap-tools

Deploying to Kubernetes? ragleap-ops ships live-tested manifests and a Helm chart for the full stack:

pip install ragleap-ops
# or, with uv
uv add ragleap-ops

Need a generic, reusable chart for your own app (not RagLeap-specific)? ragleap-app-chart takes an arbitrary services: list, not hardcoded names:

pip install ragleap-app-chart
# or, with uv
uv add ragleap-app-chart

Want metrics and logs for your ragleap-ops deployment? ragleap-observability ships Prometheus, Grafana, Loki + Promtail, and AlertManager, live-verified end-to-end against a real cluster:

pip install ragleap-observability
# or, with uv
uv add ragleap-observability

The same chart files are also on Maven Central as a jar, io.github.antonyrag:ragleap-observability (see the Maven Central badge in the list above for the current version). It is not a code port: it carries the files of the PyPI wheel of the same version (the jar can be behind PyPI, and the badge shows the jar's version), and a small class reads them from the classpath, for example RagleapObservability.openHelm("ragleap-observability/Chart.yaml"). Helm and Kubernetes are not included.

Want your agents to call tools on remote MCP servers? ragleap-integrations is an MCP client that turns allowlisted tools on remote servers into ragleap-tools Tool objects (Streamable HTTP only, alpha) and, since 0.4.0, a UTCP client for http manuals (0.5.0 adds owner-listed static query parameters and one accepted auth shape; discovery live-checked, no tool call yet verified against a real UTCP server):

pip install ragleap-integrations
# or, with uv
uv add ragleap-integrations

Need a small agent loop for your own model? ragleap-agents runs one proposed action at a time over ragleap-tools Tool objects, with approval gates, no provider code and no database (alpha):

pip install ragleap-agents
# or, with uv
uv add ragleap-agents

Prefer Terraform for a local cluster? ragleap-terraform is a Terraform module that creates a kind cluster and installs the RagLeap Helm charts (local kind cluster only for now):

pip install ragleap-terraform
# or, with uv
uv add ragleap-terraform

The same module files are also on Maven Central as a jar, io.github.antonyrag:ragleap-terraform (see the Maven Central badge in the list above for the current version). It is not a code port: it carries the files of the PyPI wheel, and a small class reads them from the classpath, for example RagleapTerraform.readString("modules/kind-cluster/main.tf"). Terraform itself is not included.

Prefer Ansible for a fresh Ubuntu server? ragleap-ansible is a set of Ansible roles that create a deploy user, set up sudo and unattended upgrades, and can optionally harden SSH and enable a firewall. It does not install k3s, Helm or the charts yet, and it has been tested in a container only:

pip install ragleap-ansible
# or, with uv
uv add ragleap-ansible

The same files are also on Maven Central as a jar, io.github.antonyrag:ragleap-ansible (see the Maven Central badge in the list above for the current version). It is not a code port: it carries the files of the PyPI wheel, and a small read-only class reads them from the classpath, for example RagleapAnsible.readPlaybookString("bootstrap.yml"). It does not run Ansible.

Looking at open, local speech models? ragleap-voice is a pre-alpha library (MIT) with transcribe() and synthesize(), an optional Whisper large-v3 engine and an Indic Parler-TTS engine, on top of a licence-checked manifest of candidate models with hash-verified downloads from Hugging Face. Every model is still unverified and none is a default, each engine has been tested on only a few clips, and no claim is made that it is better than any other product:

pip install ragleap-voice
# or, with uv
uv add ragleap-voice

Need durable, tenant-scoped long-term memory for an LLM app? ragleap-memory stores it in one SQLite file with FTS5 keyword search, typed entries with trust labels, supersede and erase, plus (version 0.2.0) a token budget on search, per-tenant quotas, one file per tenant and download/upload of a memory, and (version 0.3.0) optional vector and hybrid search with your own embedder, and (version 0.3.1) encrypted export and import of a memory file (alpha, not independently audited):

pip install ragleap-memory
# or, with uv
uv add ragleap-memory

Need tenant scopes, a tamper-evident audit log, secret handling, rate limits, file-integrity checks or optional encryption in a Python AI app? ragleap-security is a small package of security primitives (standard library only; encryption needs an optional extra; alpha, not independently audited):

pip install ragleap-security
# optional encryption
pip install "ragleap-security[crypto]"
# or, with uv
uv add ragleap-security

Need to see what your Python AI code does without recording its content? ragleap-trace is a dependency-free tracing library (standard library only): spans with hard limits, privacy-safe by default, and an adapter for ragleap-rag hooks. It writes to memory or a local file and has no network exporters.

pip install ragleap-trace
# or, with uv
uv add ragleap-trace

Want to cut the token use of LLM requests, and measure what you lose? ragleap-optimizer is an alpha library, not independently audited: every step reports what it changed and whether it can lose information, and evaluate compares quality on your own cases. No savings figure has been measured.

pip install ragleap-optimizer
# or, with uv
uv add ragleap-optimizer

Or run the full self-hosted app (channels, the AI Office dashboard, Docker Compose) — see Quickstart below. Browse every package at packages.ragleap.com. Try it hands-on with the runnable scripts in examples/ — 01_ingest_and_query.py (upload a document, ask a question via the API) and 02_test_channel_directly.py (test channel answering logic without real bot credentials).

If a RAG chatbot answers questions, RagLeap runs your business

Most open-source RAG projects give you a toolkit — you still have to build the app, wire up a UI, add memory, and connect every channel yourself. RagLeap Core gives you one AI across WhatsApp, Telegram, Discord, and voice calls, instead of a different disconnected bot per channel. Memory persists across sessions and channels, so it isn't relearning who a customer is every time. Voice is a real, working inbound-call handler (Twilio Media Streams, Whisper STT, OpenAI TTS) — not just document Q&A with a phone number bolted on — and n8n workflow automation can be triggered directly from any conversation.

What this repo doesn't include yet: a multi-tenant admin dashboard (settings, analytics, team, billing) and an executive-assistant layer (Manager AI). It does ship a single-tenant dashboard, the AI Office at /office (approvals, employees by department, tasks, agent runs, activity, Settings and a Setup checklist). RagLeap Core itself is single-tenant, self-hosted, and configured via .env. Multi-tenant use and hosting are planned inside ragleap-core, with no date.

What makes RagLeap Core specifically different

This repo isn't a general-purpose RAG framework you assemble into something — it's a real, working engine you can run today. The code here is honest about being early.

Why RagLeap exists

Open-source AI agent projects like OpenClaw took off for a specific reason: people wanted an assistant that runs on their own infrastructure, with their own keys, answering from the chat apps they already use — not a black box hosted by someone else. That same principle is what RagLeap Core is built on for business AI specifically.

Your keys, your infrastructure, your data. RagLeap Core never asks for a system API key. You bring your own AI key (or use local Ollama with no key), you run your own PostgreSQL database, your documents are stored on your own server, and text is sent only to the AI providers you configure (your chat model and your embedding provider; with local Ollama for both, your document text stays on your server).

Chat is the interface, not a separate dashboard you have to learn. The same way OpenClaw meets people on WhatsApp, Telegram, and Slack, RagLeap's full platform meets business owners on the channels they already use — WhatsApp, Telegram, Discord, and real phone calls — not a new app they have to check.

A real, working system — not an abstract framework. This isn't a toolkit like LangChain where you assemble your own app from primitives. RagLeap Core is the actual chunking → embedding → retrieval → generation pipeline extracted from a production system that already answers real customer questions, at a company that already runs on it.

Built in public, honestly. This repo says clearly what's done and what isn't. No inflated claims, no vaporware Quickstart commands that don't work yet — the Roadmap reflects the real state of the code, updated as it progresses.

What RagLeap Core is

RagLeap Core is a document-grounded chat engine. Upload your documents, ask questions, get cited answers — self-hosted, on your own infrastructure, with your own API key.

WhatsApp, Telegram, and Discord bots are included in this repo too — single-tenant, .env-configured channel adapters that answer from the same document knowledge base.

RagLeap Core is right for you if

  • ✅ You want a self-hosted RAG chatbot with full control over your data
  • ✅ You want to understand exactly how document retrieval and citation works, not use a black box
  • ✅ You're comfortable running your own server and your own AI provider key
  • ✅ You want to contribute to or extend an open document-QA engine
  • ✅ You'd rather see the code than trust a vendor's word on data privacy

What RagLeap Core is not

It's not... It is...
A hosted product Self-hosted software you run yourself today. Hosting is planned inside ragleap-core (no date)
Multi-tenant, with persistent cross-session memory Single-tenant today: one document set per deployment, served by a staff of AI employees (46 roles), not by one bot. Multi-tenant use is planned (no date)
A multi-tenant platform Not yet: multi-tenant use is planned (no date). WhatsApp/Telegram/Discord/Voice channel adapters are included, single-tenant
A no-code SaaS dashboard A codebase you deploy and configure
Feature-complete The foundational subset — see Roadmap

Features

📄 Document ingestion Upload 28 file types (PDF, Word, Excel, PowerPoint, CSV, HTML, EPUB and more) or add a public web page by address
🔍 RAG retrieval Vector search over your documents via pgvector
💬 Chat with citations Answers reference the source document, not a black box
🔌 Bring your own AI key OpenAI, Gemini, Anthropic, or any OpenAI-compatible endpoint
🌐 Web chat widget (planned) Not built yet: an embeddable widget for customer websites is on the Roadmap
🐳 Docker-based setup One-command local deployment
🕸️ Knowledge Graph (Neo4j) Entity extraction and graph-boosted retrieval alongside vector search
🌍 Language detection Auto-detects document and query language, applied across every channel
🔗 Integrations Connect MySQL, PostgreSQL, MongoDB, REST APIs, Salesforce, HubSpot, Shopify, Google Sheets, Stripe
🔀 Hybrid search Combines dense (vector) and sparse (full-text) retrieval via Reciprocal Rank Fusion
⚡ Streaming responses Answers stream token-by-token instead of waiting for the full response
🔁 Provider fallback Automatically retries with a backup LLM provider if the primary fails
💰 Token usage reporting Real per-call token counts from the provider, plus context-size budget trimming
🧑‍💼 AI Employees Role-based agents (46 default roles) with persistent business-context memory, wired into /chat via role=<role>
🖥️ AI Office dashboard Approvals inbox, employees by department, tasks, agent runs, activity, Settings (keys are encrypted and write-only) and a Setup checklist at /office
🛡️ Approval-gated autonomy off, semi and full modes; webhook, Slack, email, HubSpot CRM record updates and Google Calendar events are opt-in via .env (nothing sends or is written until you configure them) and all behind the same approval gate; sensitive roles always need approval; after the agent reads web or MCP content, outgoing actions need your approval even in full mode; every action is logged
🔁 Act-observe agent loop Opt-in: propose an action, approve it, observe the result, continue (up to 4 steps by default)
🧰 Sandboxed tools (opt-in) Python and shell in a network-less container, read-only page fetch with SSRF protection, MCP client with an allowlist, task tickets
⏰ Scheduled check-ins Proactive triggers every N minutes or by cron with a time zone
💸 Budgets and limits Optional daily and monthly token caps (global or per role) and failed-login throttling
🦙 Local mode Chat and embeddings through Ollama; ragleap launch --ollama
🛠️ Build your own AI Employee Define a fully custom role (any name, personality, channels, skill tags) via PATCH /employees/{role} - no fork, no code change. Verified live: create, retrieve, and list a new role end-to-end.
🔗 n8n workflow automation Fire a webhook after the AI replies on WhatsApp/Telegram/Discord — no-code automations triggered directly from a conversation

Architecture

How RagLeap Core is put together:

flowchart TD
    subgraph Core["RagLeap Core — this repo (open)"]
        WebUI["Your app or REST client"] --> ChatAPI["Chat API"]
        ChatAPI --> WA["WhatsApp"]
        ChatAPI --> TG["Telegram"]
        ChatAPI --> DC["Discord"]
        ChatAPI --> VC["Voice"]

        WA --> N8N["n8n Workflow Trigger (fires after AI reply)"]
        TG --> N8N
        DC --> N8N

        Employees["AI Employees (role context, learned memory)"] --> Provider

        WA --> Ingest["Document Ingest"]
        TG --> Ingest
        DC --> Ingest
        VC --> Ingest

        WA --> RAG["RAG Retrieve"]
        TG --> RAG
        DC --> RAG
        VC --> RAG

        WA --> Provider["AI Provider Adapter"]
        TG --> Provider
        DC --> Provider
        VC --> Provider

        Ingest --> PG[("PostgreSQL + pgvector")]
        RAG --> PG
        Provider --> PG
        PG --> Neo[("Neo4j (Knowledge Graph)")]
    end

Loading

Optional background job queue. The periodic integration sync job runs inline in the API process by default. Setting REDIS_URL switches it to a real Redis queue (RQ) instead, processed by separate worker process(es) that scale independently — horizontally via docker compose up -d --scale worker=N, or in Kubernetes via a queue-depth autoscaler like KEDA (see examples/keda-scaledobject-worker.yaml for a reference ScaledObject). Entirely optional — nothing changes if REDIS_URL is unset.

Repo structure

ragleap-core/
├── core/                  # RAG engine — chunking, embedding, retrieval, generation
│   ├── chunker.py
│   ├── embedding.py       # Embeddings: Gemini (default, 3072-dim) or Ollama/OpenAI/Mistral/...
│   ├── retrieval.py       # pgvector cosine search
│   ├── generation.py      # 19-provider BYOK generation (Gemini, OpenAI, Anthropic, etc.)
│   ├── ingest.py          # chunk -> embed -> store pipeline
│   ├── parsers.py         # PDF/DOCX/TXT text extraction
│   ├── employees/         # AI Employees — roles, business profile, learned memory
│   ├── workflows.py       # n8n workflow automation — webhook triggers
│   └── api.py             # FastAPI app — /health, /upload, /chat, /profile, /employees, /n8n-workflows, /webhook/*
├── channels/              # Messaging + voice channel adapters
│   ├── whatsapp/          # Twilio + Gupshup + Meta Cloud API
│   ├── telegram/
│   ├── discord/
│   └── voice/             # Twilio Media Streams, WebSocket server
├── db/
│   └── schema.sql         # documents + chunks tables, pgvector index
├── examples/              # Runnable example scripts
├── sandbox/               # Locked-down code and shell runner (opt-in)
├── scripts/               # The `ragleap` command
├── skills/ragleap/        # Read-only skill for coding agents
├── .codex-plugin/         # Plugin manifest for that skill
├── packages/              # Standalone pip packages (ragleap-rag, -graph, -tools, ...)
├── java/                  # Java ports of ragleap-rag, ragleap-graph and ragleap-vectorstores, plus jars of the ragleap-terraform, ragleap-ansible and ragleap-observability files
├── .github/workflows/     # CI: compile check, Docker build, smoke tests
├── docker-compose.yml     # app + db + voice, plus optional neo4j, redis, worker, sandbox and ollama profiles
└── Dockerfile

Quickstart

✅ Status: core pipeline verified working. Ingest -> embed -> retrieve -> generate runs end-to-end via Docker Compose, including a clean fresh-clone test. See the Roadmap for what's next (PDF/DOCX support, alternative BYOK providers).

Fastest way to try it — one command checks Docker, clones the repo, and sets up .env for you:

curl -fsSL https://raw.githubusercontent.com/ragleap/ragleap-core/main/install.sh | bash

(Windows users: run this in Git Bash, not Command Prompt or PowerShell.)

The installer asks which AI to use (Gemini, or fully local Ollama with no API key), generates your API key and secrets, starts everything and prints a one-click link to the dashboard. For local AI run curl -fsSL https://raw.githubusercontent.com/ragleap/ragleap-core/main/install.sh | bash -s -- --ollama (small local models on a CPU are slower and less accurate than Gemini). For unattended installs set RAGLEAP_PROVIDER (gemini, ollama or skip) and GEMINI_API_KEY. An existing .env is never modified.

After installing, control RagLeap with the ragleap command: ragleap launch (start; --ollama also runs the local AI service and switches to it), ragleap stop, ragleap status, ragleap logs, ragleap update (backs up the database first) and ragleap key (prints your one-click dashboard link).

Or, the manual way — better if you want to read the code before running anything:

git clone https://github.com/ragleap/ragleap-core.git
cd ragleap-core
cp .env.example .env
# add your Gemini API key to .env
docker compose up --build -d

Requirements: Docker, Docker Compose, and either a Gemini API key (the default) or a local Ollama setup with no key (use ragleap launch --ollama, or set EMBEDDING_PROVIDER=ollama for embeddings). For chat you can use Gemini or any of the 20 providers listed under Supported LLM Providers, including a local Ollama model and any OpenAI-compatible endpoint.

Try it in 30 seconds — with the stack running, see examples/ for two runnable scripts:

  • examples/01_ingest_and_query.py — upload a document and ask a question via the API. The installer put an API key in your .env file: set it first as RAGLEAP_API_KEY (bash: export RAGLEAP_API_KEY=..., PowerShell: $env:RAGLEAP_API_KEY = "...") and run pip install requests
  • examples/02_test_channel_directly.py — test the WhatsApp/Telegram/Discord answering logic without real bot credentials

The AI Office dashboard has no chat screen yet. To ask a question without writing code, use python3 skills/ragleap/scripts/ragleap_client.py ask "your question" (see Use RagLeap from a coding agent for the settings it reads), or one of the chat channels.

Just want the RAG engine as a Python library?

If you don't need the full Docker app — WhatsApp/Telegram/Discord/Voice adapters, the AI Office dashboard, all of it — the core retrieval engine is also published as standalone, pip-installable Python packages:

pip install ragleap-rag
  • ragleap-rag — the chunking → embedding → retrieval → generation pipeline as a library. Pluggable embeddings (8 providers: Gemini, OpenAI, Mistral, Together, Ollama, Cohere, Voyage and a custom endpoint), 6 vector backends (FAISS, PgVector, Pinecone, Weaviate, Qdrant, Milvus), cross-encoder reranking, and more.
  • ragleap-graph — Neo4j-backed knowledge graph retrieval, usable standalone or alongside ragleap-rag.
  • ragleap-vectorstores — pluggable vector backends beyond ragleap-rag core's 6. Backends: Chroma and LanceDB (embedded/local), Redis (RediSearch/Redis Stack), Upstash Vector (managed serverless) and OpenSearch (k-NN). Install with pip install ragleap-vectorstores[chroma] or uv add ragleap-vectorstores[chroma].
  • ragleap-tools — standalone, dependency-light tools for LLM tool-calling. 12 stateless tools (calculator, date/time, unit conversion, JSON/CSV parsing, text utilities), sandboxed file ops (symlink-escape protected), search_documents (hybrid vector+keyword search), search_web (pluggable BYOK providers such as Tavily and Serper), search_github_repositories, describe_image (BYOK vision providers for Gemini and Anthropic; only Gemini has been live-checked), and optional ragleap-rag-backed document ingestion. Every HTTP provider has a response-size cap and a hard total deadline. Does not own a tool-calling execution loop — provides Tool objects for your own loop or for ragleap-agents. Write your own tools with the @tool decorator and dispatch a model's call safely with Toolkit (arguments are validated before your code runs). Install with pip install ragleap-tools or uv add ragleap-tools.
  • ragleap-integrations — MCP (Model Context Protocol) client over Streamable HTTP that returns ragleap-tools Tool objects (since 0.4.0 it is also a UTCP client for http manuals, see below). The owner configures the servers and an exact server.tool allowlist; the model only supplies arguments. HTTPS-only transport with DNS pinning and a hard wall-clock deadline. Live-checked against public servers: DeepWiki on the legacy protocol path, and Google Cloud's MCP endpoints on the newest revision (2026-07-28; discovery only). Also live-checked on 2026-10-17 (0.1.1) and again on 2026-10-24 (the published 0.2.0 wheel) against a third party's public mock MCP servers (mcpplaygroundonline.com): modern-path tools/call succeeded (pinned and unpinned), bearer-token authentication worked (HTTP 401 without a token, success with a fresh one) and the legacy fallback worked. Not yet live-verified: x-mcp-header mirroring, pagination and this client's handling of a live -32022 reply. The default response cap is 1 MiB (256 KiB in 0.1.0, which Google Cloud's Pub/Sub MCP endpoint exceeded); raise max_response_bytes if discovery fails. Version 0.5.0 (PyPI, 2026-11-11) adds two owner-controlled options to the UTCP client: allowed_query=[...] (the owner lists the static query parameter names a tool URL may carry; default none, which is the 0.4.0 behaviour) and one accepted auth shape (an api_key in the Authorization header with the value Bearer ${NAME}, which only describes what the client already does with the owner's token; the name is never looked up; without a token the tool is skipped; any other auth block is still skipped). It also fixes a 0.4.0 defect (a URL ending in a bare ? was accepted). It is tested with 626 tests and 48 of 52 deliberate breaks of the new code were caught (the other 4 are equivalent mutants); the published wheel and sdist were verified after release. Discovery was live-checked again on 2026-11-12 with the published 0.5.0 wheel and no token, against the same public manual (37 tools, all http): none of the 20 tools tried was offered, and all 20 were skipped only because no token is configured, so the manual's auth block is recognised as the accepted shape; the query rule and a tool call with a token were not tried (no credential was used). Version 0.4.0 adds a UTCP (Universal Tool Calling Protocol) client, connect_utcp(): it reads one UTCP manual once and offers only its allowlisted http tools, with an exact allowlist, approved origins checked at discovery and on every call, no variable substitution, the same approval hook and audit events (marked "protocol": "utcp") and constant error texts; the bounded HTTPS transport now also supports GET, PUT, DELETE and PATCH. It is tested against a recording fake transport and a local TLS server. Its discovery was first live-checked on 2026-11-07, against Unified.to's public UTCP manual (HTTP 200, 33 tools, all http): none of the 20 tools tried was offered, because every template declares auth, which 0.4.0 does not support. No tool call against a real UTCP server has been made, the normative text of the UTCP specification was not read, and, apart from the one auth shape accepted since 0.5.0, auth blocks, header_fields, OAuth, OpenAPI conversion and a multi-tenant hub are not supported yet. Version 0.3.0 adds multi-tenant use (McpHub: a token per request for each Scope, narrowed allowlists, per-tenant approval and rate limits, scoped audit events; ragleap-security is an optional extra); it was live-checked on 2026-10-26 (branch source) and 2026-10-27 (published wheel) against a mock MCP auth server, which cannot tell tenants apart, so separation is shown from the requests that were sent. Version 0.2.0 added connect(url, allow=[...]) (one call from a URL to ready tools and a ragleap-tools Toolkit) and governance: server tool hints are treated as untrusted, flagged tools can require approval through an approve hook, and an on_event hook reports one audit event per discovery and per call (never arguments or results). Live-checked on 2026-10-25 against Google Cloud's Pub/Sub MCP endpoint (tools/list only, no credentials): connect(), the annotation parsing and the approval flags matched an independent calculation from the real hints. The approve hook, its denial text and the per-call audit events are tested against fake servers only. No curated business connectors and no agent loop yet. Install with pip install ragleap-integrations or uv add ragleap-integrations.
  • ragleap-agents — a small act-observe agent loop over ragleap-tools Tool objects, one proposed action at a time: schema-checked actions, untrusted tool results, a taint rule that forces approval for outbound actions after untrusted content, pause and resume, and (from 0.5.0) sub-agents through a delegate tool. Since 0.5.1, runs and approvals can be tied to a tenant scope (an optional ragleap-security Scope), so one tenant cannot resume or approve another tenant's run. Standard library plus ragleap-tools and ragleap-security; alpha; live results with real models are limited (see its release notes). Install with pip install ragleap-agents.
  • ragleap-security — small, auditable security primitives: immutable tenant scopes, a hash-chained audit log (tamper-evident, not tamper-proof), secrets that do not print themselves with a heuristic redactor, hard input limits, key rotation with optional AES-256-GCM encryption, rate limits, and file-integrity checks. Standard library only (encryption needs the optional cryptography extra: pip install ragleap-security[crypto]); alpha; not independently audited. Install with pip install ragleap-security.
  • ragleap-memory — durable, tenant-scoped long-term memory in one SQLite file: FTS5 keyword search, typed entries with trust labels (new entries default to untrusted), supersede, forget, export, and erase that removes the text from the file. Version 0.3.1 adds encrypted export and import of a memory file (a key, a key ring or a passphrase, through ragleap-security; install with ragleap-memory[crypto]; it protects the file, not the database). Version 0.3.0 adds optional vector and hybrid search over vectors that your own embedder function produces (no provider code in the library), with a per-tenant daily embedding cap. Version 0.2.0 added a token budget on search (max_tokens), usage counters and per-tenant quotas, ShardedStore (one file per tenant) and download/upload of a memory as a file. Needs ragleap-security; alpha; retrieval quality not benchmarked; not independently audited. Install with pip install ragleap-memory.
  • ragleap-optimizer — a measure-first layer that reduces the token use of LLM requests: exact repeated-context removal, whitespace and JSON minifying, a stable prompt prefix, bounded tool-output trimming (it reports when it loses information), a tenant-scoped exact cache, retries and fallback, and an evaluation harness that compares quality before and after on your own cases. No savings figure is claimed; alpha; not independently audited. Install with pip install ragleap-optimizer.
  • ragleap-physical — a simulation-first, observe-first safety bridge between AI agents and simulators (pre-alpha, simulation only). The AI can only propose; a named person approves the exact change; limits are checked again when it is applied; the outcome is verified in the simulator. Four AI-facing tools and a small MCP server, an operator console for the human approval step, MuJoCo adapters (optional extra), workspace limits, two- and three-joint arms, an offline ROS 2 observe-only mock, a simulated machine tool, and observe-only energy and MTConnect mocks. Not built: MQTT, PLC or real-robot bridges; nothing here controls real hardware. Not independently audited. Install with pip install ragleap-physical.
  • ragleap-ops — Kubernetes deployment manifests for RagLeap Core, live-tested end-to-end on a real cluster. Install with pip install ragleap-ops or uv add ragleap-ops.
  • ragleap-app-chart — generic, reusable Helm chart for deploying arbitrary services to Kubernetes, not RagLeap-specific. Point it at your own app via a services: list. Install with pip install ragleap-app-chart or uv add ragleap-app-chart.
  • ragleap-observability — Prometheus, Grafana, Loki + Promtail for ragleap-ops, live-verified end-to-end against a real cluster (real connection confirmed, real non-zero metrics returned; 21+ real log streams with correct namespace/pod/container labels). AlertManager is wired to Prometheus with a first real alert rule, plus optional Slack/email receivers (off by default; delivery verified against a stand-in, real send not yet confirmed). Install with pip install ragleap-observability or uv add ragleap-observability. The same chart files are also on Maven Central as a jar, io.github.antonyrag:ragleap-observability (not a code port).
  • ragleap-terraform — Terraform module that creates a local kind cluster and installs the RagLeap Helm charts, applied and destroyed on a real cluster (no cloud modules yet). Install with pip install ragleap-terraform or uv add ragleap-terraform. The same files are also on Maven Central as a jar, io.github.antonyrag:ragleap-terraform (not a code port).
  • ragleap-ansible — Ansible roles that prepare and harden a fresh Ubuntu server: deploy user, sudo, unattended upgrades, opt-in SSH hardening and an opt-in firewall (tested in a container; does not install k3s, Helm or the charts yet). Install with pip install ragleap-ansible or uv add ragleap-ansible. The same files are also on Maven Central as a jar, io.github.antonyrag:ragleap-ansible (not a code port).
  • ragleap-trace — dependency-free tracing, standard library only. Spans with hard limits (name 128, key 64, 32 attributes, strings cut at 256), a context manager and a decorator for sync and async code, in-memory and JSONL exporters (the file is created with mode 0600), and an adapter for ragleap-rag's on_ingest, on_query and on_answer hooks that records only allow-listed counts, never query or answer text or file names. Tested against a real RagLeap with Postgres; first release (0.1.0); not independently audited; no retention or rotation yet. It does not do hallucination detection or judging. Install with pip install ragleap-trace or uv add ragleap-trace.
  • ragleap-voice — pre-alpha, open and local (MIT). transcribe() and synthesize() with an optional Whisper large-v3 engine and an Indic Parler-TTS engine, on top of a licence-checked manifest and hash-verified model downloads. Every model is still unverified and none is a default; each engine has been tested on only a few clips. Install with pip install ragleap-voice or uv add ragleap-voice (engines are optional extras, e.g. ragleap-voice[whisper]).

All sixteen are MIT licensed. Browse the full package index at packages.ragleap.com.

Use RagLeap from a coding agent (read-only plugin)

If you already run a RagLeap server, a small read-only skill lets a coding agent check it and ask it questions. The skill lives in skills/ragleap and the manifest is .codex-plugin/plugin.json. It is a client for a server you run yourself, not a way to install RagLeap, and it uses only the Python standard library.

Set the server URL and your API key in the environment:

export RAGLEAP_URL=http://127.0.0.1:8000
export RAGLEAP_API_KEY=your-key-here

Commands:

python3 skills/ragleap/scripts/ragleap_client.py health
python3 skills/ragleap/scripts/ragleap_client.py employees --active-only
python3 skills/ragleap/scripts/ragleap_client.py ask "What is our refund policy?" --role support --top-k 5

Safety choices: it is read-only (no upload or delete), the key is read only from the environment and sent as a header, it refuses to send the key over plain http to a non-local host, it does not follow redirects, and responses are capped at 2 MB. Treat answers as untrusted text. See skills/ragleap/SKILL.md for details.

Supported LLM Providers (BYOK)

RagLeap Core is bring-your-own-key only there is no system-provided key for any provider. Set LLM_PROVIDER in .env to choose which one to use for the generation (chat) step. Embeddings are configured separately with EMBEDDING_PROVIDER (default gemini, using gemini-embedding-001; ollama, openai, mistral, together, openrouter, qwen, zhipu and custom are also supported). The vector size must match your embedding model (EMBEDDING_DIMENSIONS): empty tables are resized at startup, tables that already hold embeddings are never changed.

LLM_PROVIDER value Required env vars Notes
gemini (default) GEMINI_API_KEY Get a key at aistudio.google.com/apikey
anthropic ANTHROPIC_API_KEY, ANTHROPIC_MODEL (optional) Get a key at console.anthropic.com
openai OPENAI_API_KEY, OPENAI_MODEL
mistral MISTRAL_API_KEY, MISTRAL_MODEL
groq GROQ_API_KEY, GROQ_MODEL Free tier available
together TOGETHER_API_KEY, TOGETHER_MODEL
openrouter OPENROUTER_API_KEY, OPENROUTER_MODEL
ollama OLLAMA_MODEL (no API key needed) Self-hosted; requires Ollama running locally
deepseek DEEPSEEK_API_KEY, DEEPSEEK_MODEL
demonroute DEMONROUTE_API_KEY, DEMONROUTE_MODEL Hosted open-weight models through a third-party gateway. DemonRoute states that it does not retain prompts, but it forwards them to the upstream host that serves the model, and its privacy page does not describe that host's retention: avoid sensitive business data
cheaperinference CHEAPERINFERENCE_API_KEY, CHEAPERINFERENCE_MODEL OpenAI-compatible gateway to models from several labs, through a third-party service that forwards prompts to the upstream provider. Its retention policy is not reviewed by RagLeap: avoid sensitive business data
xai XAI_API_KEY, XAI_MODEL
cohere COHERE_API_KEY, COHERE_MODEL
perplexity PERPLEXITY_API_KEY, PERPLEXITY_MODEL
qwen QWEN_API_KEY, QWEN_MODEL
moonshot MOONSHOT_API_KEY, MOONSHOT_MODEL
zhipu ZHIPU_API_KEY, ZHIPU_MODEL
yi YI_API_KEY, YI_MODEL
baidu BAIDU_API_KEY, BAIDU_MODEL
minimax MINIMAX_API_KEY, MINIMAX_MODEL
custom CUSTOM_API_KEY, CUSTOM_MODEL, CUSTOM_BASE_URL Any OpenAI-compatible endpoint

Example, switching to Groq in .env:

LLM_PROVIDER=groq
GROQ_API_KEY=your-groq-key
GROQ_MODEL=llama-3.3-70b-versatile

Ollama in Docker: known gotchas

No internet, or a GPU? See the offline and GPU guide.

Running Ollama as a fallback/local provider from inside this app's Docker container (rather than bare metal) has real, verified setup steps beyond just setting OLLAMA_MODEL:

  1. host.docker.internal isn't reliable on plain Linux Docker Engine (unlike Docker Desktop) — it can resolve to the wrong bridge network's gateway. If Ollama connections fail with this alias, override OLLAMA_BASE_URL with the container's actual compose-network gateway IP directly, e.g. OLLAMA_BASE_URL=http://172.18.0.1:11434/v1 (find your real gateway with docker network inspect <network> | grep Gateway).
  2. Ollama binds to 127.0.0.1 by default, which a container can't reach even with the correct gateway IP. Override it to listen on all interfaces:
   mkdir -p /etc/systemd/system/ollama.service.d
   cat > /etc/systemd/system/ollama.service.d/override.conf << 'EOF'
   [Service]
   Environment="OLLAMA_HOST=0.0.0.0:11434"
   EOF
   systemctl daemon-reload && systemctl restart ollama
  1. The host firewall may silently drop container→host traffic even after the above — container-to-bridge-gateway traffic hits ufw's INPUT chain, not FORWARD/DOCKER-USER. Allow it explicitly: ufw allow from 172.18.0.0/16 to any port 11434 proto tcp (adjust the subnet to match your actual Docker network).

WhatsApp Channel (Twilio, Gupshup or Meta)

The WhatsApp adapter answers incoming messages through one of three providers, picked with WHATSAPP_PROVIDER in .env: twilio (the default), gupshup, or meta (Meta's WhatsApp Cloud API — any business with a verified Meta Business Account can connect directly, no reseller in between). Replies go out through the configured provider's send API; incoming messages arrive at the same /webhook/whatsapp route for all three.

Setup (Meta Cloud API):

  1. Create an app at developers.facebook.com and add the WhatsApp product. WhatsApp > API Setup gives you a temporary access token and your phone number's ID; for a token that outlives the test window, create a system user token in Business settings.
  2. Set in .env:
    • WHATSAPP_PROVIDER=meta
    • META_ACCESS_TOKEN — the access token from step 1
    • META_PHONE_NUMBER_ID — the ID of the phone number you send from
  3. In WhatsApp > Configuration, set the webhook callback URL to https://your-domain.com/webhook/whatsapp and enter the same string in the "Verify token" field that you set as META_VERIFY_TOKEN in .env. Meta checks it once with a GET during setup (the handler echoes hub.challenge).
  4. Set META_APP_SECRET from App settings > Basic. Every incoming webhook request must then carry a valid X-Hub-Signature-256 (HMAC-SHA256 of the raw body with that secret) or it is rejected with 403.

For Twilio the credentials are TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN and TWILIO_WHATSAPP_NUMBER; for Gupshup GUPSHUP_API_KEY, GUPSHUP_APP_NAME and GUPSHUP_SOURCE_NUMBER. WHATSAPP_ALLOW_UNSIGNED=true accepts webhook requests without a signature, for local testing only (logs a warning each time).

Honest status: the Meta send path and webhook verification are covered by offline tests (tests/test_whatsapp_meta.py); they have not yet been live-tested against a real Meta app. Twilio and Gupshup are the long-standing, verified paths.

Voice Channel (Twilio)

RagLeap Core includes a real-time voice channel: Twilio Media Streams connects via WebSocket, your speech is transcribed with OpenAI Whisper, answered by the core RAG pipeline, and spoken back with OpenAI TTS. The voice-activity detection and echo-suppression logic is carried over from a production system tuned against real call traffic.

Runs as a separate service on port 8765 (see docker-compose.yml), since Twilio's real-time audio protocol needs a raw WebSocket server, not an HTTP route.

Setup:

  1. Set OPENAI_API_KEY in .env (used for both Whisper STT and TTS by default; VOICE_STT_PROVIDER=deepgram uses DEEPGRAM_API_KEY instead, and VOICE_TTS_PROVIDER=elevenlabs uses ELEVENLABS_API_KEY with the voice id from ELEVENLABS_VOICE_ID)
  2. Optionally set VOICE_BOT_NAME, VOICE_GREETING, VOICE_TTS_VOICE
  3. Set VOICE_WS_TOKEN in .env to a long random value (the installer does this for new installs; openssl rand -hex 24 makes one). Without it the voice server refuses every call.
  4. Point a Twilio phone number's <Connect><Stream> TwiML at wss://your-domain.com:8765/<your VOICE_WS_TOKEN>. Use wss (not ws): the token is part of the address, and a connection without it never becomes a call. If the token ever leaks, change it in .env and in the TwiML.

Security: anyone who can phone your number can talk to the bot, which is the point of a public line, so decide what your documents and role instructions should say to a stranger. Spoken feedback ("good answer" / "bad answer") is ignored on the voice channel, because callers are anonymous and that feedback changes the memory used on every channel. VOICE_MAX_CALLS (default 10) and VOICE_MAX_CALL_MINUTES (default 30) limit simultaneous calls and call length, which also limits what a caller can spend of your speech and model credits.

Honest status: the WebSocket server, Twilio event protocol handling, and error handling are verified working. The full Whisper/TTS round-trip has not yet been live-tested end-to-end (requires OpenAI API credits). If you try it and hit issues, please open one — this is exactly the kind of real-world testing this project needs.

Known limitations, carried over from production and not yet fixed here:

  • OpenAI Whisper (STT) and OpenAI TTS are the defaults — Deepgram STT and ElevenLabs TTS (multi-language support) are now also supported via VOICE_STT_PROVIDER / VOICE_TTS_PROVIDER, but have not been live-tested
  • Non-English TTS quality varies since OpenAI's TTS voices are English-tuned
  • Typical round-trip latency in production was 6-8 seconds

Knowledge Graph (Neo4j)

RagLeap Core builds a lightweight entity co-occurrence graph alongside its vector index. When you ingest a document, entities (product names, acronyms, proper nouns) are extracted and linked in Neo4j. When you ask a question, the same extraction runs on your query, and any documents linked to matching entities get a similarity boost in retrieval — on top of, not instead of, normal pgvector search.

Runs as a fourth Docker Compose service on ports 7475/7688 (remapped from Neo4j's defaults to avoid colliding with another Neo4j instance on the same host). If Neo4j is unreachable or NEO4J_PASSWORD is unset, the graph degrades gracefully — retrieval falls back to pure vector search, ingestion is unaffected.

Setup:

  1. Set NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD in .env. Use a long random password (for example openssl rand -hex 24). docker-compose.yml hands the same NEO4J_PASSWORD to the Neo4j container, so the two always match. The old public default (ragleapgraph) is used only while NEO4J_PASSWORD is unset, and the app logs a warning if you configure it. Neo4j reads the password when its data volume is first created, so on an existing volume change it inside Neo4j first (ALTER CURRENT USER SET PASSWORD), then update .env
  2. Optionally set DOMAIN_TERMS — a comma-separated list of domain-specific terms to boost during extraction (e.g. DOMAIN_TERMS=API,SDK,RAG)

Honest status: entity extraction, document graph writes, entity-based document lookup, and graph-boosted chat retrieval are all verified working end-to-end, including in CI (fresh build, real ingest, real query, real graph lookup). The graph boost is currently a simple additive score bump, not a full weighted re-ranker — a richer hybrid ranking system is a good next step for anyone who wants to dig in.

Known limitations:

  • Entity extraction is regex-based (CamelCase, acronyms, capitalized phrases, plus optional domain terms) — not a trained NER model, so it will miss some entities and occasionally include noise
  • search_related_entities() (multi-hop graph traversal) is implemented but not yet wired into the retrieval pipeline — good-first-issue candidate for anyone wanting a project

Language Detection

RagLeap Core auto-detects language during document ingestion (per chunk) and during chat (per query), using the langdetect library plus script-based heuristics for CJK, Hangul, and Kana text. Since every channel (WhatsApp, Telegram, Discord, Voice, and the API directly) routes through the same core chat pipeline, detection applies consistently everywhere without per-channel wiring.

Setup: works out of the box with no configuration. Optionally set DEFAULT_LANGUAGE (fallback when detection fails or text is too short), LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD (default 0.7), and LANGUAGE_DETECTION_SUPPORTED_LANGUAGES (comma-separated allowlist, blank = unrestricted).

Honest status: verified working end-to-end — document-level detection tested at high confidence (0.9999) on a real mixed-language document, and query-level detection confirmed working via both the API and CLI.

Known limitations:

  • langdetect covers roughly 55 languages — noticeably fewer than the hosted platform's 222+, which layers additional detection and per-user language preferences on top
  • Short queries in closely-related languages can be misdetected (in testing, a short French query was detected as Italian) — this is an inherent limitation of statistical detection on short text, not specific to this port. A good-first-issue candidate for anyone wanting to improve short-query accuracy
  • Detection is one-way only: RagLeap Core detects the query's language and surfaces it, but does not yet steer the AI's response language to match — that's a reasonable next step for a contributor

Documents, folders and computer control

Documents tab. In the dashboard you can list, upload and delete documents and add web pages by address. 28 file types are supported. Deleting a document also removes its entries from the knowledge graph.

Computer control is experimental, off by default and has not been independently reviewed. Please do not switch it on for real data. Folders are shared with AI employees only by a command you run on the machine, ragleap files. The app, the API and the AI employees cannot create or widen a grant. A small sandbox runner reads granted folders read-only. AI employees can list and read files and can ask for access; a request always needs the owner's approval and grants nothing by itself. File contents stay out of the activity log, and the Files tab shows the grants.

ragleap files add ~/Documents/handbook --name handbook --purpose knowledge
ragleap files list
ragleap files status
ragleap files off      # pause all file access now
ragleap files on
ragleap files remove handbook

ragleap files add PATH --name NAME takes a folder (not a single file), --purpose use or knowledge, and an optional --expires such as 30m, 12h, 7d or a date. Only read-only grants exist for now. .env files and keys inside a granted folder stay hidden from the AI, and a folder that contains or sits inside the RagLeap install folder is refused. To turn computer control on, add COMPUTER_CONTROL=true to .env and run docker compose --profile sandbox up -d. The file tools also need FILE_TOOLS_ENABLED=true and the SANDBOX_TOKEN that the installer creates.

Folder auto-ingest (off by default). Grant a folder with --purpose knowledge and the sandbox copies the allowed documents (28 supported formats; no symlinks, no .env files or keys, 25 MB per file) into a read-only staging volume. The app reads new, changed and deleted files every 15 minutes. The first read of a folder waits for the owner's approval, because embeddings can cost money; the Documents tab has a Folders card with an Approve button. It needs COMPUTER_CONTROL=true, FOLDER_INGEST_ENABLED=true, a rebuilt sandbox image and db/schema.sql applied. Optional settings: FOLDER_INGEST_INTERVAL_MINUTES (default 15), FOLDER_INGEST_MAX_FILES (default 50), FOLDER_INGEST_DELETE_REMOVED (default true) and FOLDER_INGEST_AUTO_APPROVE (default off). Folder ingest was tested on one server with a small folder; Docker Desktop, rootless Docker and macOS are untested.

Integrations

flowchart TD
    subgraph Connectors["10 connectors, one shared interface"]
        C1[MySQL] --- C2[PostgreSQL] --- C3[MongoDB]
        C4[REST API] --- C5[Salesforce] --- C6[HubSpot]
        C7[Shopify] --- C8[Google Sheets] --- C9[Stripe]
        C10[CSV Upload]
    end
    Connectors --> Svc["RealTimeExternalDataService<br/>real-time query, 5-min cache, no separate sync step"]

    Owner["Owner configures an action:<br/>trigger phrase or auto-match on SQL/field names<br/>+ a query template (SELECT / UPDATE / INSERT / DELETE)"] --> Svc

    Svc --> Match["match_and_execute_action(workspace_id, user_message, user_identifier)<br/>extracts order_id / email / phone from the message,<br/>substitutes into the template, runs the query"]

    Match --> Chat["Chat channels (WhatsApp/Telegram/Discord/Web)<br/>api/personal_bot_views.py"]
    Match --> Voice["Voice channel<br/>memory/voice_views.py::twilio_voice_speech<br/>wired in 2026-08"]

    Chat --> RAGCtx["Result injected as context<br/>into the RAG prompt"]
    Voice --> RAGCtx
    RAGCtx --> Answer["AI answers with real account/order/appointment<br/>data, not just document knowledge"]
Loading

Verified live, read from api/addon_realtime.py's RealTimeExternalDataService. Two things worth being direct about: match_and_execute_action genuinely supports write queries (UPDATE/INSERT/DELETE), not just read-only lookups — owner-configured, so the safety boundary is whatever SQL the owner writes into the template, not something the framework restricts on its own. And until 2026-08, this action-matching step only ran on chat channels; voice calls had no equivalent, which is the gap closed in the Voice Channel Routing diagram above.

RagLeap Core connects to external databases and business tools, syncing per-user context to personalize RAG responses. Nine connectors are included: MySQL, PostgreSQL, MongoDB, generic REST APIs, Salesforce, HubSpot, Shopify, Google Sheets, and Stripe. Newer connector code for CSV upload, Airtable, BigQuery, Snowflake, WooCommerce, Notion, Slack, Gmail and Razorpay is also in the repo; treat those as experimental until you have verified them against your own account (tracked in #27).

Every CRM/SaaS connector uses credentials you provide directly — a username/password, a private-app token, an admin API token, a service-account JSON file, or a secret key, depending on the service. None require registering an OAuth app; nothing here depends on RagLeap owning any third-party developer account.

Credentials are encrypted at rest (Fernet/AES-128) before being stored.

Setup:

  1. Generate an encryption key: python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
  2. Set ADDON_ENCRYPTION_KEY in .env to that value
  3. Install the SDK for the connector(s) you want (each is optional — see requirements.txt)
  4. Create a data source: POST /integrations with name, source_type, and the relevant credential fields
  5. Test it: POST /integrations/{id}/test
  6. Sync it: POST /integrations/{id}/sync

Honest status: verified end-to-end against a real public API — connection testing, syncing, correct identifier-field matching, and credential encryption (checked as actual ciphertext in the database, not just assumed) all confirmed working.

Known limitations:

  • 9 of the 18 source types listed in the hosted platform's UI have real connectors here. CSV Upload, Snowflake, BigQuery, WooCommerce, Airtable, Notion, Razorpay, Slack, and Gmail are good-first-issue candidates for anyone wanting to add one
  • Sync is on-demand only (POST /integrations/{id}/sync) — no scheduled background sync yet, though the schema tracks sync_interval_minutes for a future Celery-beat-equivalent
  • Synced context isn't automatically injected into chat responses yet — each channel adapter would need to know its own user's identifier first, which is a reasonable next contribution

Retrieval, Generation & Reliability

Beyond the core RAG pipeline, /chat (and the underlying core.chat.ask()) support several controls aimed at production use: retrieval quality, response latency, provider reliability, and cost.

Hybrid search (dense + sparse). By default, retrieval combines pgvector cosine similarity with Postgres full-text search (tsvector/ GIN index), fused via Reciprocal Rank Fusion — catching both semantic matches and exact keyword/identifier matches a pure embedding search can miss. Pass hybrid=false to use dense-only retrieval instead (cheaper — one query instead of two).

Streaming. POST /chat/stream streams the answer as it's generated (text/plain, chunked transfer) instead of waiting for the full response. Implemented natively per provider (Gemini, Anthropic, and OpenAI-compatible each have different streaming APIs — all three are real, not one stubbed).

Provider fallback. Set LLM_FALLBACK_PROVIDERS (comma-separated) to automatically retry with backup providers if the primary fails — a rate limit, outage, or bad key on your primary provider doesn't have to mean a failed request. Each fallback needs its own API key configured normally. Streaming can only fall back before any text has been sent to the caller — a mid-stream failure surfaces as an error rather than silently switching providers and confusing the output.

Generation controls. temperature, system_prompt, and max_tokens are all real per-call parameters (not just env-var defaults) — build your own agent behavior on top of RagLeap's retrieval without forking the library.

Token usage & context budget. Every blocking /chat call returns real token usage (prompt_tokens, completion_tokens, total_tokens) pulled directly from the provider's response — not an estimate. Retrieved context is also trimmed to MAX_CONTEXT_CHARS (default 12000, roughly 4 characters per token for English text) before being sent, dropping the lowest-ranked chunks first, so you're not paying for more context than necessary. Set MAX_CONTEXT_CHARS=0 to disable trimming.

Honest status: hybrid search's RRF fusion math verified correct against hand calculation. Streaming verified working end-to-end for the default provider. Provider fallback verified with a real broken-primary test — deliberately invalid API key, confirmed fallback to a working secondary provider with a correct answer. Token usage and context trimming verified with real numbers: a 3-chunk retrieval trimmed to 1 chunk under a tight budget reduced actual prompt_tokens by 38% on the same live API.

Known limitations:

  • Token usage reporting is not available for streaming responses — each provider's streaming API surfaces usage differently, and doing all three correctly is separate, not-yet-done work
  • MAX_CONTEXT_CHARS is a character-count approximation (~4 chars/token for English), not an exact per-provider tokenizer count
  • Hybrid search hasn't been benchmarked for actual ranking-quality improvement on a multi-document corpus with genuinely conflicting dense vs. sparse rankings — only correctness (fusion math, tokenization of unusual identifiers) has been verified so far

Roadmap

  • Public repository created
  • Core RAG engine extracted and cleaned from production codebase
  • Standalone Docker Compose setup (no external Django project dependency)
  • Document ingestion in the app: 28 file types and web pages by address
  • Audio, video and image ingestion in the app (they exist in the ragleap-rag package; audio and video need a hosted transcription provider, because local speech-to-text is not supported yet)
  • Embeddable web chat widget (planned; not built yet)
  • Bring-your-own-API-key support (20 providers)
  • WhatsApp, Telegram, Discord, and Voice channel adapters (single-tenant)
  • Knowledge Graph (Neo4j), language detection, database/CRM integrations
  • Contribution guide and good-first-issue labels — 8+ issues labeled, with a real external contributor active on #134
  • Community Discord
  • AI Office dashboard with settings and a setup checklist (v0.9.0)
  • Approval-gated agent loop, sandboxed tools, MCP client and scheduled check-ins
  • One-command installer and ragleap command, local Ollama mode (one community tester ran the Windows installer with the Ollama option on one machine, see #781; macOS and Linux desktops are not verified)
  • Failed-login throttling and optional token budgets
  • Four roles with personal keys, a request audit log, folder auto-ingest (off by default) and single sign-on with OpenID Connect (off by default; tested on Keycloak for sign-in and refusals only, per the v0.13.0 notes)
  • Documents treated as untrusted content for actions (v0.13.0), structured audit log lines (v0.13.1), audit filters, opt-in audit retention and a sign-in rate limit (v0.13.2)
  • Separate libraries beyond rag and graph: memory, security, trace, optimizer, voice (pre-alpha), physical (simulation only), agents, tools, integrations and vectorstores (see ROADMAP.md, Phase 8)
  • Multi-tenant use and hosting inside ragleap-core (planned, no date)
  • Prebuilt Docker images (GHCR) for a faster install
  • Triggers and autonomy controls in the dashboard
  • Slack and email inbound, SMS, and the web widget (these need a public HTTPS address)
  • Live verification of more LLM providers (see #10)

See ROADMAP.md for the full phase-by-phase history.

Tested by others

We call a feature proven only when someone other than the maintainers has run it and reported the result. This table starts empty on purpose. It is filled in from reports on the community testing issues, and nothing counts as tested until a report is listed here.

You do not need to write code to help: pick a test, run a few steps on sample files, and comment with what happened, even if everything worked. Please never share keys or real data.

Area Tested by OS / setup Result Issue
Windows installer with the Ollama option @Anurag07-crypto Windows 11 Pro 25H2 (build 26200.9711), Docker 29.9.2, Ollama 0.40.14, qwen2.5:3b and nomic-embed-text Services started, the dashboard opened, the chat and embedding connection tests passed, one PDF was ingested (5 chunks) and one chat request was answered (HTTP 200). One machine, one PDF, one question: not a compatibility guarantee, and macOS and Linux desktops are not verified. Evidence #781

Contributing

RagLeap Core is working, tested, and open for contributions now. See CONTRIBUTING.md for how to get started, and check the good first issue label for scoped tasks.

Want to see exactly what's being worked on and what's open to claim? Check the Project board — issues are staged as Good First Issue, Ready (Scoped), or Needs Scoping, so you can pick something that matches how much design work you want to do versus just build.

Student, professor, or looking for a capstone/thesis project? See STUDENT_PROJECTS.md for scoped project ideas at starter, semester, and research-grade levels.

Community

License

MIT © 2026 RagLeap

Troubleshooting

"could not translate host name 'db'" error after a failed docker compose up: If your first docker compose up attempt fails (e.g. a port conflict on 5433 or 8000), a retry can sometimes leave the database container attached to a stale, orphaned Docker network. Fix:

docker compose down
docker network prune -f
docker compose up --build -d

Port 5433 or 8000 already in use: Another instance of this project (or something else, such as a local PostgreSQL on 5433) is using the port. A fresh install with install.sh or install.ps1 picks the next free port by itself and writes it to .env. If you started with docker compose up yourself, or reuse an existing .env, set the host port there instead: APP_PORT (default 8000), DB_PORT (5433), VOICE_PORT (8766), NEO4J_HTTP_PORT (7475), NEO4J_BOLT_PORT (7688) or REDIS_PORT (6380), for example DB_PORT=5434, then run docker compose up -d again. The dashboard address follows APP_PORT, for example http://localhost:8001/office.

About

Open-source, self-hosted AI employees that ask before they act. 46 business roles, approval-gated autonomy, untrusted-content safeguards, sandboxed execution, Graph RAG and token budgets. Expanding across memory, voice, security and physical AI. WhatsApp, Telegram, Discord and 20 LLM providers. MIT licensed.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages