# RagLeap Roadmap

This page summarizes the current status of the RagLeap ecosystem across
its two layers: the standalone open-source app and the focused pip-installable packages. All version numbers here
are live-verified against real PyPI releases and real code - not
projected or aspirational. If anything here looks out of date, check
[Home.md](Home.md) and the package's own CHANGELOG.md, which are the
real sources of truth.

## Layer 2 — pip-installable packages (current focus)

| # | Package | Purpose | Status |
|---|---|---|---|
| 1 | `ragleap-rag` | Core retrieval: ingestion, hybrid vector search, provider-agnostic generation, guardrails | Complete v0.13.0 - 350 passed, 18 skipped in CI (skipped tests are not counted as passing). Live-verified against real infrastructure: PgVector, FAISS, Qdrant, Weaviate. NOT live-verified: Milvus and Pinecone (tracked in issue #510). CORRECTION: this row previously said v0.12.3 / 245 tests and was stale. v0.12.9 fixed real bugs found by live testing: Qdrant and Weaviate returned raw cosine scores in [-1,1] instead of the [0,1] range the other backends use, and Weaviate hardcoded localhost and mismatched its named vector. v0.13.0 (behavior change) made ingest_url() download through a guarded fetcher (non-public addresses are refused unless allow_private_urls=True) and added size limits on zip-based extraction; v0.12.10 fixed the [web] extra (lxml_html_clean was missing, so a fresh install could not import trafilatura), parquet extraction (no extra installed pandas) and ragleap.__version__ (the 0.12.9 wheel reported 0.12.6), made 12 environment-dependent tests hermetic, and CI now installs the formats, web and backend extras. Known limits of the v0.13.0 guards: name resolution is not covered by the timeouts, and 6to4/NAT64 addresses are not specially handled (issue #534). Known honest limitation: token_count is word-count not real tokenization. (Milvus similarity_score normalization was fixed in v0.12.3 - previously inconsistent with the other 5 backends' [0,1] range; verified against Milvus's own docs before fixing.) |
| 2 | `ragleap-graph` | Neo4j knowledge-graph-augmented retrieval | Complete v0.9.0 - 108 tests (92 passed without live credentials, 16 skipped). LLM entity/relation extraction, hybrid vector+graph retrieval, per-document idempotency, lineage lookup (find_lineage), per-user data isolation (user_id=), Postgres-backed audit logging (audit=), concurrent-write safety via composite_key uniqueness constraints + automatic retry-with-backoff on Neo4j transient deadlocks (closes #183), cross-chunk relation extraction (cross_chunk_relations=, #154, best with a capable provider - small local models can produce incorrect relations rather than none), and ontology cross-validation between relation types and entity types (relation_ontology=, #152). Eval framework (graph-RAG vs vector-RAG accuracy, #153) remains open - needs domain-expert-authored labeled test cases. |
| 3 | `ragleap-vectorstores` | Pluggable vector backends beyond what ships in ragleap-rag core | Complete v0.5.1 - 78 tests (48 always-run + 14 live-only Upstash + 16 live-only OpenSearch), live-verified. CORRECTION: v0.5.0 shipped OpenSearchBackend using datetime.UTC, which only exists on Python 3.11+, so insert_document() raised AttributeError on Python 3.10 despite this package declaring support for 3.10 - reproduced with the published v0.5.0 wheel and fixed in v0.5.1 (datetime.timezone.utc, works on every supported version); the deprecated datetime.utcnow() was also removed from the four older backends in the same release, with the identical timestamp format preserved; the 16 OpenSearch tests were run locally against OpenSearch 3.8.0 only and skip in CI. Five backends: ChromaBackend (chromadb's embedded PersistentClient), LanceDBBackend (embedded via a directory path, real upsert semantics via merge_insert()), RedisBackend (RediSearch/Redis Stack HNSW index - requires a real running server), UpstashBackend (managed serverless REST API - no local mode at all, index must pre-exist via the Upstash console), and OpenSearchBackend (OpenSearch k-NN with the lucene engine - requires a real running instance; the document registry is a second OpenSearch index). Live-verified OpenSearch gotchas: the nmslib engine is rejected on OpenSearch 3.0+, and the cosinesimil score is (1 + cosine) / 2. Known honest limitations: supports_sparse() reports False for all five; RedisBackend's metadata filtering only supports document_id (RediSearch requires predeclared schema fields) while UpstashBackend and OpenSearchBackend support arbitrary multi-key filters; OpenSearchBackend has no bulk-insert path yet (CORRECTION, 2026-10-02: an earlier version of this row said the four older backends still call the deprecated datetime.utcnow(); the current 0.5.1 source contains no such call, only a comment mentioning it). More backends remain planned (MongoDB Atlas, Vespa, Turbopuffer, and others under consideration). |
| 4 | `ragleap-tools` | Built-in tools: search, image description, calculators, file ops | Complete v0.5.1 - 362 tests passing in CI (Python 3.10, 3.11, 3.12). Includes search_documents, search_web (BYOK providers; Tavily and Serper NOT live-verified), describe_image (BYOK vision; Gemini live-checked on 2026-10-03 and again on the v0.4.1 transport on 2026-10-09, Anthropic provider NOT live-verified) and search_github_repositories (token optional; live-checked unauthenticated on 2026-10-01 and again on the v0.4.1 transport on 2026-10-09, authenticated path NOT live-verified, mocked tests only). Code-exec and HTTP-fetch deliberately deferred. Every HTTP provider has a response-size cap and a hard total deadline (v0.4.1). v0.5.0 adds a @tool decorator (a type-annotated function becomes a Tool), a Toolkit that dispatches a model's call safely, ToolError and Tool.metadata; the generated schemas are NOT live-checked against OpenAI, Gemini or Anthropic. |
| 5 | `ragleap-integrations` | MCP client over Streamable HTTP returning `ragleap-tools` Tool objects (curated native connectors and channel integrations are not built yet) | Live - v0.1.1 (MCP client only; live-checked on the legacy protocol path (DeepWiki, 2026-10-05) and on the modern 2026-07-28 path for discovery only (Google Cloud MCP endpoints, 2026-10-12; re-checked with 0.1.1 on 2026-10-16: the default 1 MiB response cap now accepts a 15-tool list, and 4 of its tool schemas exceed max_schema_chars); modern tools/call, x-mcp-header mirroring, bearer auth and pagination are NOT live-verified) |
| 6 | `ragleap-agents` | Single-agent act-observe loop over `ragleap-tools` Tool objects, with approval gates (multi-agent crews planned) | Live - v0.4.0 - 151 tests, run in CI on 3.10/3.11/3.12; the published 0.4.0 wheel was installed fresh and checked on 3.10 and 3.12 (scripted models and a local fake server; run against Groq with three models, but the taint rule has NOT been triggered by a real model; Gemini not tried). Correction 2026-10-09: this row previously described role-based crews, which v0.1.0 does not include. Update 2026-10-12: 0.2.0 adds an OpenAI-compatible adapter; behaviour change from 0.1.0: an unparseable model reply now stops the run instead of reporting done. Update 2026-10-16: 0.3.0 changes the prompt wording by adapter mode (behaviour change); JSON mode on gpt-oss-20b stays intermittent (Groq HTTP 400 tool_use_failed) and is not fixed; the taint rule still has NOT been triggered by a real model. Update 2026-10-17: 0.4.0 (behaviour change: a run with no tools or an empty task now stops with status=stopped instead of done) adds SQLiteStateStore (one local file, standard library only, not encrypted) and an atomic resume claim (tested with four processes racing for one run; SQLite on network filesystems NOT verified); the prompt wording is unchanged and the 0.3.0 real-model results were not re-run: JSON mode stays intermittent and the taint rule still has NOT been triggered by a real model. |
| 7 | `ragleap-flows` | Low-code orchestration + HITL checkpoints, bootstrapped from the existing n8n integration | AFTER |
| 8 | `ragleap-observability` | Tracing, hallucination detection, and a full LLM-as-judge evaluation framework (Ragas/DeepEval-caliber) | DECISION NEEDED - this is new engineering, not extraction; nothing like the eval-framework half exists internally today. |
| ⚠️ | **Naming note** | The PyPI name `ragleap-observability` is already taken by a separate, shipped package -- infra monitoring (Prometheus/Grafana/Loki/AlertManager) for `ragleap-ops`, live at https://pypi.org/project/ragleap-observability/. 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 | ONGOING - grows alongside every phase above, not a single release. |
| 10 | `ragleap-studio` | Visual low-code builder UI | LATER |
| 11 | `ragleap-memory` | Shared long-term memory layer across agents/employees | LATER - an untracked packages/ragleap-memory/ directory already exists from concurrent automation; not yet a scoped, owned package. |
| 12 | `ragleap-intelligence` | Early-stage vision, not yet scoped - see note below | VISION / EARLY DISCUSSION ONLY |

**A note on `ragleap-intelligence`:** this entry exists to hold a place
for the "AI Employee Twin" concept discussed in project chat - one
persistent AI assistant per employee, capable of autonomous action
(with optional human-in-the-loop), cross-device presence, and role
continuity across employee turnover. This is a genuinely large, mostly
unscoped vision at this stage, not a committed roadmap item with a
version target. Open questions before this becomes real scoped work:
device/data-access boundaries (office-only vs personal devices),
telephony impersonation of an employee, consent and labor-law
implications of persistent per-employee monitoring/assistance, and
local-vs-cloud model requirements for data sensitivity.

## Immediate next steps for `ragleap-graph`

Audit logging, ontology cross-validation, and cross-chunk relation
extraction have all shipped (v0.6.6, v0.9.0, v0.8.0 respectively) - see
the summary row above. Only real item remaining:

1. **Eval framework** (graph-RAG vs vector-RAG) - new engineering, needs
   domain-expert-authored labeled test cases, not something to invent
   generically.

Plus non-code items: Gemini key rotation (still open), the Layer 1/2
voice-package relationship decision, and /simple/ endpoint data
verification. See the repo's open issues for the full tracked list.

## Contributing

RagLeap's open-source layers (the ragleap-core monorepo: the standalone
app in core/ and channels/, and the pip-installable packages in
packages/) are open to external contributors. If you'd like to help:

- Check open issues on GitHub for scoped, ready-to-pick-up work - each
  one states what's needed and why, following the same
  live-verification standard the rest of the project holds itself to.
- New packages (ragleap-tools, ragleap-vectorstores,
  ragleap-integrations, and beyond) are genuinely open for design
  proposals, not just implementation - open an issue with a proposed
  API surface before a large PR, so design discussion happens before
  code review.
- The project's non-negotiable standard: every claim in code, docs, and
  release notes is either live-verified against real infrastructure, or
  explicitly labeled unverified. PRs that claim "tested" without a
  real, reproducible test are held to the same bar as everyone else's
  work here.
- See Home.md for the full package/version table and links to each
  package's own CHANGELOG.

## Layer 1 — standalone open-source app

The full RagLeap Core app (`core/`, `channels/`, `db/`, deployable with `docker compose up`). Install and usage docs live at docs.ragleap.com.

## Cloud version

A managed cloud version of RagLeap is planned. For now, RagLeap is open source only.