🧶 Ragdoll

Retrieval-Augmented Generation Driven by Offline Local LLMs

A fully-local RAG system that ingests JIRA tickets, PDF documents, and Python source code, indexes them for semantic search, and connects to a local LLM via Ollama for interactive Q&A, summarization, and chat.

Privacy-first: All data stays on your machine — nothing is sent to external services by default.

Key Features

• Multi-source ingestion — PDF, JIRA, Bitbucket, GitHub, Git, and Python code (AST-parsed)
• Semantic search — ChromaDB vector store with cosine similarity
• Local LLM — Ollama-powered embedding and generation
• Interactive chat — Multi-turn RAG chat with persistent history
• MCP Server — First-class support for the Model Context Protocol (stdio & sse). (Note: If you connect a cloud-based AI client to this MCP server, the search results it retrieves will be sent to that external AI provider).
• Privacy-first — Everything runs locally; no external API calls
• Flexible configuration — 4-layer precedence (env → project → user → defaults)

Prerequisites

• Python 3.12+
• Ollama running locally with:
  • An embedding model (e.g. nomic-embed-text)
  • A chat model (e.g. gpt-oss:20b, deepseek-r1:32b)
• pixi for environment management

Quick Start

# Clone and enter the project
cd ragdoll

# Install with pixi (creates isolated env + editable install)
pixi install

# Set up user-level configuration
mkdir -p ~/.ragdoll && chmod 700 ~/.ragdoll
cat > ~/.ragdoll/config.toml << 'EOF'
jira_url = "https://your-jira.example.com"
jira_user = "your.user"
jira_token = "YOUR_PAT_TOKEN"
jira_auth_method = "pat"  # "pat" for JIRA Data Center, "basic" for Cloud

bitbucket_url = "https://your-bitbucket.example.com"
bitbucket_user = "your.user"
bitbucket_token = "YOUR_HTTP_ACCESS_TOKEN"
bitbucket_auth_method = "pat"

github_token = "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
EOF
chmod 600 ~/.ragdoll/config.toml

# Check everything is connected
pixi run ragdoll status

Usage

Ingest Data

# Ingest PDF files or directories
pixi run ragdoll ingest pdf ./docs/technical_handbook.pdf
pixi run ragdoll ingest pdf ./reports/

# Ingest JIRA issues via JQL
pixi run ragdoll ingest jira --jql "project = CORE AND updated >= -30d"
pixi run ragdoll ingest jira --jql "project = AUTH AND updated >= -60d" --max-results 100

# Ingest from a different JIRA instance (multi-site)
pixi run ragdoll ingest jira \
  --url https://other-jira.example.com \
  --token OTHER_PAT \
  --jql "project = EXT AND updated >= -30d"

# Ingest Bitbucket Pull Requests and comments
pixi run ragdoll ingest bitbucket --project PROJ --repo backend --state ALL

# Ingest GitHub Issues and PR discussions
pixi run ragdoll ingest github myorg myrepo --state all

# Ingest Python source code (AST-parsed per function/class)
pixi run ragdoll ingest code ./src/
pixi run ragdoll ingest code ./path/to/project/

Reingesting Data (LlamaIndex Update)

If you are upgrading from an older version of ragdoll to the LlamaIndex-backed version, your existing ChromaDB data is fully backward compatible. However, it is highly recommended to wipe the old index and reingest your data to take advantage of LlamaIndex's superior semantic chunking (which splits by sentences instead of fixed character limits).

To clear your database and start fresh:

# Delete the old ChromaDB collection
rm -rf ~/.ragdoll/data/chroma

# Re-run your ingestion commands
pixi run ragdoll ingest jira --jql "project = CORE AND updated >= -30d"
pixi run ragdoll ingest pdf ./docs/

Search

# Semantic search across all ingested data
pixi run ragdoll search "database query performance regression"
pixi run ragdoll search "connection pool lazy initialization" --source jira
pixi run ragdoll search "data processing pipeline" --source pdf -n 5
pixi run ragdoll search "embedding function" --source code

Summarize

# Summarize a topic from ingested data
pixi run ragdoll summarize "What are the known issues with the connection pool?"
pixi run ragdoll summarize "batch worker parallelization" --source jira

Interactive Chat

# Start an interactive RAG chat session
pixi run ragdoll chat
pixi run ragdoll chat --source jira  # only use JIRA context
pixi run ragdoll chat --source code  # only use source code context

Chat features:

• Persistent history — arrow-up recalls previous questions across sessions (stored in ~/.ragdoll/chat_history)
• Line editing — full readline support (backspace, arrows, Home/End)
• Multi-turn — context accumulates within a session

Configuration

Ragdoll uses a 4-layer precedence configuration strategy:

Settings Reference

Architecture

Source Data                Pipeline                        Storage
───────────                ────────                        ───────
PDF files     ─┐
JIRA tickets  ─┼─→  Ingestor  →  Chunker  →  Embedder  →  ChromaDB
Python code   ─┘              (AST-aware)   (Ollama)       (local)
                                                             ↑
Query Flow                                                   │
──────────                                                   │
CLI / Chat  →  Embed query  →  Retriever  ←──────────────────┘
                                 ↓
                           LLM (Ollama)  →  Streamed answer

Data Sources

Key Components

• Config (ragdoll.config) — Pydantic Settings with 4-layer precedence
• Chunker (ragdoll.ingest.chunker) — Recursive character text splitter
• Embedder (ragdoll.llm.ollama) — Ollama HTTP client for embeddings and generation
• Vector Store (ragdoll.store.vectordb) — ChromaDB with cosine similarity
• Retriever (ragdoll.query.retriever) — Semantic search with source filtering
• RAG Chain (ragdoll.query.rag) — Context-augmented generation and chat
• CLI (ragdoll.cli) — Click-based interface with Rich formatting

Documentation

Full documentation is hosted at ragdoll.readthedocs.io.

You can also build the documentation locally from the docs/ directory using Sphinx:

pixi run docs

AI Assistance & Transparency Disclosure

Ragdoll is developed using AI pair-programming and agentic workflows alongside human engineers.

• Human Oversight & Responsibility: The codebase, architectural designs, and operational policies are reviewed, edited, and validated by human maintainers. Human contributors retain full responsibility for the accuracy, security, and licensing integrity of all code in this repository.
• Rigorous Verification: All code changes, refactors, and features must pass comprehensive offline test suites (pixi run test), linting, and documentation builds before merging.
• Strict Privacy & Secret Hygiene: Development strictly adheres to zero-egress policies—no proprietary tokens, internal credentials, or confidential datasets are ever exposed during AI-assisted workflows. Architectural invariants and agent safety rules are codified in AGENTS.md.

Independent Community Project & Personal Capacity Disclaimer

This repository is an independent open-source software project:

• Personal Effort: All contributions, code, documentation, and architectural designs represent the independent, voluntary efforts of individual contributors acting strictly in their personal capacities.
• Outside Official Working Hours: Work on this project is conducted entirely during personal, off-duty time.
• Not Work-for-Hire: Contributions are not commissioned, assigned, supervised, or endorsed by any current, past, or future employers of the contributors.
• No Institutional Affiliation: Opinions, designs, and implementations expressed herein are solely those of the individual authors and do not reflect the official positions, policies, or technical roadmaps of any employer or institution.

License

MIT