# RagLeap Core — Wiki Home

Welcome to the `ragleap-core` monorepo wiki. This repo hosts the open,
pip-installable layer of the RagLeap ecosystem: focused, independently
versioned Python libraries published to PyPI, plus the standalone
self-hostable app they're built alongside.

This wiki and `packages.ragleap.com` cover the open-source project. RagLeap is currently open source only; a managed cloud version is planned.

---

## Live packages

| Package | Purpose | PyPI version | Tests | Docs |
|---|---|---|---|---|
| [`ragleap-rag`](https://pypi.org/project/ragleap-rag/) | Core retrieval — 6 vector backends, guardrails, query rewriting, structured output, cost tracking, metadata-aware ingest() | **v0.13.0** | 350 passed, 18 skipped (CI) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-graph`](https://pypi.org/project/ragleap-graph/) | Neo4j knowledge-graph retrieval — entity/relation extraction, cross-chunk relation extraction, ontology cross-validation, lineage tracing, audit logging, concurrent-write safety, schema migrations | **v0.9.0** | 108 (92 passed without live credentials, 16 skipped) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-vectorstores`](https://pypi.org/project/ragleap-vectorstores/) | Pluggable vector backends beyond `ragleap-rag` core's 6 — Chroma, LanceDB (embedded/local), Redis (RediSearch/Redis Stack), Upstash Vector (managed serverless), and OpenSearch (k-NN) | **v0.5.2** | 48 passing (+14 live-only Upstash tests, +16 live-only OpenSearch tests) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-tools`](https://pypi.org/project/ragleap-tools/) | Standalone, dependency-light tools for LLM tool-calling — 12 stateless tools, sandboxed file ops (symlink-escape protected), search_documents (hybrid vector+keyword search, optional per-document filename= scoping), search_web (pluggable BYOK providers - Tavily, Serper), search_github_repositories (optional token), describe_image (pluggable BYOK vision providers - Gemini, Anthropic), optional ragleap-rag-backed ingestion; every HTTP provider has a response-size cap and a hard total deadline; a @tool decorator turns a type-annotated function into a tool and a Toolkit dispatches a model's call safely (arguments validated before the handler runs, no exception escapes; the generated schemas are not live-checked against any provider) | **v0.5.1** | 362 passing | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-integrations`](https://pypi.org/project/ragleap-integrations/) | MCP client over Streamable HTTP returning `ragleap-tools` Tool objects - owner-configured servers and an exact tool allowlist, modern (2026-07-28) and legacy (2025-06-18) protocol paths, stdlib-only bounded HTTPS transport (public-address check, pinned IP, verified TLS, wall-clock deadline). Live-checked against public servers: the legacy path (DeepWiki) and the modern 2026-07-28 path for discovery only (Google Cloud MCP endpoints); modern tools/call not yet live-verified | **v0.1.1** | 208 passing | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-agents`](https://pypi.org/project/ragleap-agents/) | Single-agent act-observe loop over `ragleap-tools` Tool objects: schema-checked actions, untrusted tool results, a taint rule that forces approval for outbound tools after untrusted content, pause/resume through a pluggable store (in-memory and SQLite included). Verified with scripted models and a local fake server, and run against Groq with three models; since 0.5.0, sub-agents through a delegate tool; in a live delegation check the taint rule held a send for approval in 3 of 8 runs whose prompts asked for it, and no real model has yet proposed an injected send on its own | **v0.5.0** | 208 tests | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-ops`](https://pypi.org/project/ragleap-ops/) | Kubernetes deployment manifests + Helm chart with NetworkPolicies, Ingress+TLS, multi-env values, and Backup/DR, zero-permission ServiceAccounts and read-only root filesystems (not neo4j), live-tested on a real cluster | **v0.5.1** | 1 passing (+ live kind-cluster deploy) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-app-chart`](https://pypi.org/project/ragleap-app-chart/) | Generic, reusable Helm chart for arbitrary services -- not RagLeap-specific, deployable via a `services:` list and range loops, with multi-env values and a live-tested worked example | **v0.3.1** | 0 unit tests (helm lint + live kind-cluster deploy) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-terraform`](https://pypi.org/project/ragleap-terraform/) | Terraform module that creates a local kind cluster and installs the RagLeap Helm charts; tested on a real cluster, no cloud modules yet | **v0.1.0** | 1 passing (+ live apply/destroy on a real cluster) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-ansible`](https://pypi.org/project/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 only, does not install k3s, Helm or the charts yet | **v0.1.0** | 1 passing (+ container idempotence test) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-observability`](https://pypi.org/project/ragleap-observability/) | Prometheus, Grafana, Loki + Promtail for `ragleap-ops`, live-verified end-to-end against a real cluster (pg_up 1, real non-zero metrics; 21+ real log streams with correct namespace/pod/container labels). AlertManager wired to Prometheus with a first real alert rule (optional Slack/email receivers, off by default; delivery verified against a Slack-compatible stand-in, real Slack/email send not yet confirmed); per-workload zero-permission ServiceAccounts, pods-only Promtail role, configurable Grafana admin password; optional Grafana Alloy log shipper (off by default, verified on one kind node); opt-in availability SLO alerts (0.8.0, plus an absent() alert for vanished targets in 0.8.2; tested with promtool, on a real Prometheus in one container, and on a kind cluster with AlertManager delivering to a stand-in receiver (slow burn firing and a real Slack or email send not tested); no request-level SLOs because the app exports no metrics yet); the wheel includes the chart from 0.8.1; SLO/SLI dashboards not yet built. | **v0.8.3** | 0 unit tests (helm lint + live kind-cluster deploy) | [packages.ragleap.com](https://packages.ragleap.com) |


### Java

| Package | Purpose | Maven Central version | Tests | Docs |
|---|---|---|---|---|
| [`ragleap-rag` (Java)](https://central.sonatype.com/artifact/io.github.antonyrag/ragleap-rag) | Java port of ragleap-rag's core pipeline — connection pooling, embeddings (7 providers), all 6 vector backends (pgvector, FAISS, Qdrant, Weaviate, Milvus, Pinecone — Milvus and Pinecone are code-complete but not live-verified), retrieval, generation (streaming, structured output, vision), conversation memory, query rewriting, 27-format document parser, OCR, audio and video ingestion, ingestion service, and the RagLeap entry point (ask, streaming, retrieve, evaluate, history, document methods, batch ingestion) | **v0.13.0** | 502 (release build: 0 failing, 8 skipped; five timing-sensitive live-Ollama tests are excluded from the release build; tests that need live services or the tesseract and ffmpeg binaries skip themselves in CI) | [packages.ragleap.com](https://packages.ragleap.com) |
| [`ragleap-graph` (Java)](https://central.sonatype.com/artifact/io.github.antonyrag/ragleap-graph) | Java port of ragleap-graph's Neo4j graph index over the HTTP Query API (no Bolt driver): regex entity extraction, optional LLM entity and relation extraction with deduplication (through a small LlmClient interface, with an optional ragleap-rag adapter; not live-verified against real model providers), document upsert with composite keys and typed relations, document, entity, related-entity, relation, lineage and entity-type queries, GraphRetriever (hybrid or graph only, with citations), and one-time backfills with a migration runner. The Postgres audit writer is not ported yet | **v0.2.0** | 129 (release build: 0 failing, 31 skipped; parity tests need Python-generated fixtures and live tests need a Neo4j server; verified live on Neo4j 5.26.29 Community only) | [release notes](https://github.com/ragleap/ragleap-core/releases/tag/ragleap-graph-java-v0.2.0) |

Independently versioned from the Python `ragleap-rag` package above, not kept in lockstep — now at full vector-backend parity (all 6 ported), but not yet at full feature parity overall (the document parser covers 27 of 28 formats, no Parquet; OCR, video audio extraction, transcription, the ingestion service, batch ingestion and the RagLeap entry point are ported; URL ingestion, reranking, the Redis query cache and the async variants are not). Cross-backend benchmark and failure-mode matrix: [results and raw data](https://github.com/ragleap/ragleap-core/blob/main/java/ragleap-rag/benchmark/RESULTS.md). See `java/ragleap-rag/pom.xml`'s description in the main repo for exact current scope.

---

## Full ecosystem roadmap (12 packages)

Status definitions: **Live** = published to PyPI today · **Next** = actively
planned, not yet started · **After** = planned, depends on the "Next" tier
landing first · **Ongoing** = grows continuously alongside every phase ·
**Decision needed** / **Later** = intentionally not yet scoped · **Vision**
= early discussion only, explicitly not a committed roadmap item.
**Evolution** = post 1-12 vision — same AI Workforce OS extends to physical world (MQTT/ROS/PLC, sensors → actions).

| # | Package | Purpose | Status |
|---|---|---|---|
| 1 | `ragleap-rag` | Core retrieval | **Live — v0.13.0** |
| 2 | `ragleap-graph` | Neo4j knowledge-graph retrieval | **Live — v0.9.0** |
| 3 | `ragleap-vectorstores` | Pluggable vector backends beyond `ragleap-rag` core's 6 | **Live — v0.5.2** |
| 4 | `ragleap-tools` | Stateless tools + sandboxed file ops + document search + web search + image description + a @tool decorator and a Toolkit for LLM tool-calling (code-exec/HTTP-fetch/connectors deliberately deferred) | **Live — v0.5.1** |
| 5 | `ragleap-integrations` | MCP client over Streamable HTTP that returns `ragleap-tools` Tool objects (curated native connectors and channel integrations are not built yet) | **Live — v0.1.1** |
| 6 | `ragleap-agents` | Single-agent act-observe loop over `ragleap-tools` Tool objects: schema-checked actions, untrusted tool results, taint rule with approval gates, pause/resume, an OpenAI-compatible adapter, sub-agents through a delegate tool (nested approval planned) | **Live — v0.5.0** |
| 7 | `ragleap-flows` | Low-code orchestration + HITL, bootstrapped from existing n8n integration | After |
| 8 | `ragleap-observability` | Tracing, hallucination detection, LLM-as-judge eval framework | Decision needed — no internal precedent yet |
| ⚠️ | **Naming note** | The PyPI name `ragleap-observability` is already taken by a separate, shipped package (infra monitoring — Prometheus/Grafana/Loki/AlertManager for `ragleap-ops`, see the live-packages table above). This roadmap item (LLM tracing/eval framework) will need a different package name when built. | — |
| 9 | `ragleap-ops` | Docker/K8s templates, Helm charts, CI/CD, IaC | **Live — v0.5.1** (K8s manifests, Helm chart, NetworkPolicies, Ingress+TLS, multi-env, Backup/DR — all live-tested) |
| -- | `ragleap-app-chart` | Generic, reusable Helm chart for arbitrary services -- not RagLeap-specific, not part of the numbered 1-14 sequence above | **Live -- v0.3.1** |
| -- | `ragleap-terraform` | Terraform modules (local kind cluster + RagLeap charts) -- not part of the numbered sequence | **Live -- v0.1.0** |
| -- | `ragleap-ansible` | Ansible roles that prepare and harden a fresh Ubuntu server (user, sudo, updates, opt-in SSH hardening and firewall) -- not part of the numbered sequence | **Live -- v0.1.0** |
| 10 | `ragleap-studio` | Visual low-code builder UI | Later |
| 11 | `ragleap-memory` | Shared long-term memory layer across agents/employees | Later — an untracked scaffold directory exists from concurrent automation, not yet a scoped package |
| 12 | `ragleap-intelligence` | "AI Employee Twin" vision — persistent per-employee AI assistant | **Vision only** — not scoped, not committed |
| 13 | `ragleap` | Meta-package — everything bundled | Later — packaging/bundling strategy not yet decided |
| 14 | `ragleap-physical` | **Evolution:** Embodied AI — MQTT/ROS/PLC bridge, sensors → actions | Evolution — After 1-13 |

For the full narrative behind each phase, see [Roadmap](./Roadmap.md).

---

## The two layers

| Layer | What | Where |
|---|---|---|
| 1. Standalone open-source app | Full "RagLeap Core" app — FastAPI web layer, WhatsApp/Telegram/Discord/Voice channels, Neo4j knowledge graph, `docker compose up` deployable | This repo — `core/`, `channels/`, `db/` |
| 2. Focused pip-installable libraries | `ragleap-rag`, `ragleap-graph`, `ragleap-vectorstores`, `ragleap-tools`, `ragleap-ops`, `ragleap-app-chart`, `ragleap-observability`, `ragleap-terraform`, `ragleap-integrations`, `ragleap-agents`, `ragleap-ansible` (live today), more planned | This repo — `packages/` |

`docs.ragleap.com` covers the standalone app (Layer 1): how to install, configure and use it. If you're here for the pip packages, see `packages.ragleap.com` for API reference and quickstarts.

---

## Contributing

- Everyone who has contributed, including people who reported and discussed issues, has a public, verifiable record at https://ragleap.com/contributors/
- Every claim in code, docs, and marketing is either live-verified against
  real infrastructure or explicitly labeled unverified. No projected or
  estimated numbers presented as measured.
- PRs go through the standard 14-step release cycle for anything touching
  a published package (see [Roadmap](./Roadmap.md) for the full checklist).
- Open issues are the source of truth for what's actually planned next —
  check the issue tracker before proposing new scope, especially around
  items marked "decision needed" above.
- This monorepo has concurrent automated sessions working on it alongside
  human contributors. If you see unfamiliar branches or stashes, they're
  very likely legitimate in-progress work — please don't discard them.

---

*Last synced with `Roadmap.md` and PyPI as of `ragleap-graph` v0.9.0 /
`ragleap-rag` v0.13.0 / `ragleap-vectorstores` v0.5.2 / `ragleap-tools` v0.5.1 / `ragleap-integrations` v0.1.1 / `ragleap-agents` v0.5.0. If anything here
looks stale, the PyPI version pages and `packages.ragleap.com` are the
live source of truth.*