RAGCore

A self-hosted retrieval platform for applications that need trustworthy, authorized knowledge.

RAGCore ingests documents, preserves their source versions, and returns search results, bounded context packs or cited answers. Applications use the REST API, typed SDKs or MCP adapter instead of managing vector databases directly. Retrieval remains useful when an optional generation provider is unavailable.

How it works

flowchart LR
  A[Upload / folder / Git source] --> B[Parse and version]
  B --> C[PostgreSQL + immutable blobs]
  C --> D[Derived Qdrant index]
  D --> E[Authorized hybrid retrieval]
  E --> F[Search / context / cited answers]
  E --> G[Query Lab]

Capabilities

• Workspace, application, service-account, knowledge-space and grant management with audit events.
• Persistent source registry, scheduled folder/Git synchronization, uploads and durable ingestion jobs.
• Text/Markdown/code parsing and Docling support for born-digital PDF, DOCX, PPTX, XLSX and HTML.
• Dense/sparse hybrid search with reciprocal rank fusion, explicit filters and provenance-rich citations.
• Optional Ollama generation and streamed answers with claim/citation validation.
• Browser control plane for sources, documents, jobs, access, profiles, Query Lab and system health.
• Typed Python/TypeScript clients and a read-only MCP service using the same authorization boundary.
• Backup/restore tools, Alembic migrations, observability and explicit embedding/index selection.

Run locally

Python development requires Python 3.13 and uv. Deployment requires Docker Compose and sufficient storage for PostgreSQL, Qdrant, immutable document blobs and parsing/model artifacts.

git clone https://gitea.itworx.tech/Jens/RAGcore-Public.git
cd RAGcore-Public
cp .env.example .env
# Configure independent strong secrets, database credentials and provider settings.
docker compose up --build

The app listens on http://localhost:8088; MCP uses port 8090. The stack contains app, worker, MCP, PostgreSQL and Qdrant. The optional models profile adds Ollama. State defaults to .state/; persist and back it up independently of the checkout.

Configure RAGCORE_BOOTSTRAP_EMBEDDING_PROVIDER and RAGCORE_BOOTSTRAP_EMBEDDING_MODEL together, or activate a profile through the control plane. Retrieval needs an active compatible embedding profile and an available provider; starting the containers alone does not create a useful corpus. Model changes require an explicit selection/reindex workflow.

For folder/Git sources, mount only the intended corpus read-only into the worker and set RAGCORE_SOURCE_ROOTS to its container path. An empty allowlist deliberately disables filesystem-backed sources. Create the workspace/application, issue a scoped service credential, grant its knowledge spaces, ingest content and wait for successful publication before searching.

Integrate

from ragcore_sdk import RAGCoreClient

with RAGCoreClient(base_url="https://ragcore.example.test", token=service_token) as client:
    response = client.search(query="What is the retention policy?")
    for result in response.results:
        print(result.rank, result.citation.source_uri)

Install the Python SDK from sdk/python; the TypeScript SDK is in sdk/typescript. The REST contract and MCP specification describe supported operations and authentication.

Production considerations

Use HTTPS, a deliberately trusted reverse proxy, independent secrets and configured OIDC roles. Keep PostgreSQL and Qdrant private. Production validation rejects weak credentials and unsafe storage/network settings. PostgreSQL and blobs are authoritative; Qdrant is rebuildable. On Unraid, place active database/vector storage on direct pool paths. Review the deployment guide, backup/restore guide and security controls before deployment.

The shipped parsing image does not OCR scanned PDFs without a text layer. Model weights and parsing artifacts may need downloads during image construction. This source snapshot is not a claim that experimental ModelForge routes or a particular live deployment have been qualified.

Development

uv sync --all-extras --group dev
uv run ruff check src tests
uv run mypy src
uv run pytest

Integration tests require disposable PostgreSQL/Qdrant and model services; use the supplied test Compose files rather than production data. Architecture explains module boundaries and data flows.

Source distribution and licensing

This is the curated public source edition. Development continues in the private canonical repository; reviewed snapshots are published automatically after changes reach main, without private Git history, operational evidence, corpora or credentials.

The package declares Proprietary and no repository-wide distribution license has been selected. Public visibility does not grant reuse or redistribution rights. See licensing status; model, dataset and third-party terms must be reviewed separately.