API Reference¶

Auto-generated documentation from source code docstrings.

Configuration¶

Configuration management for Ragdoll.

Settings are resolved from four layers, highest priority first:

Environment variables (RAGDOLL_*) Ephemeral overrides, great for CI or one-off runs. Example: RAGDOLL_CHAT_MODEL=deepseek-r1:32b ragdoll chat
Working-directory config (per-project) - ./ragdoll.toml — project-level settings (safe to commit) - ./.env — project-level secrets (git-ignored)
User config (~/.ragdoll/config.toml) Personal defaults shared across all projects.
Package defaults (hardcoded in this file) Sensible fallbacks so ragdoll works out of the box.

This follows the same convention as git, pip, and npm: most-specific scope wins.

class ragdoll.config.MaskedSecret(secret_value)[source]¶

Bases: SecretStr

SecretStr wrapper that masks in logs/repr while supporting equality with str for testing.

Parameters:: secret_value (SecretType)

class ragdoll.config.Settings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_show_env_vars=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, *, jira_servers=<factory>, jira_url='https://jira.example.com', jira_user='', jira_token=MaskedSecret(''), jira_batch_size=100, jira_auth_method='pat', bitbucket_servers=<factory>, bitbucket_url='https://bitbucket.example.com', bitbucket_user='', bitbucket_token=MaskedSecret(''), bitbucket_auth_method='pat', github_servers=<factory>, github_url='https://api.github.com', github_token=MaskedSecret(''), github_default_owner='', github_repos=<factory>, confluence_servers=<factory>, confluence_url='https://confluence.example.com', confluence_user='', confluence_token=MaskedSecret(''), confluence_auth_method='pat', confluence_cookie=MaskedSecret(''), ollama_host='http://localhost:11434', embed_model='nomic-embed-text', chat_model='gemma4:12b', temperature=0.0, enable_thinking=False, num_predict=4096, data_dir=PosixPath('/home/docs/.ragdoll/data'), collection_name='ragdoll', chroma_host=None, chroma_port=8000, chroma_ssl=False, chroma_auth_token=None, chroma_tenant='default_tenant', chroma_database='default_database', chunk_size=1000, chunk_overlap=200, top_k=10)[source]¶

Bases: BaseSettings

Ragdoll configuration.

All fields map to environment variables prefixed with RAGDOLL_. For example RAGDOLL_CHAT_MODEL → chat_model.

Precedence: env vars > ./ragdoll.toml > ./.env > ~/.ragdoll/config.toml > defaults.

Parameters:

_case_sensitive (bool | None)
_nested_model_default_partial_update (bool | None)
_env_prefix (str | None)
_env_prefix_target (EnvPrefixTarget | None)
_env_file (DotenvType | None)
_env_file_encoding (str | None)
_env_ignore_empty (bool | None)
_env_nested_delimiter (str | None)
_env_nested_max_split (int | None)
_env_parse_none_str (str | None)
_env_parse_enums (bool | None)
_cli_prog_name (str | None)
_cli_parse_args (bool | list[str] | tuple[str, ...] | None)
_cli_settings_source (CliSettingsSource[Any] | None)
_cli_parse_none_str (str | None)
_cli_hide_none_type (bool | None)
_cli_avoid_json (bool | None)
_cli_enforce_required (bool | None)
_cli_use_class_docs_for_groups (bool | None)
_cli_show_env_vars (bool | None)
_cli_exit_on_error (bool | None)
_cli_prefix (str | None)
_cli_flag_prefix_char (str | None)
_cli_implicit_flags (bool | Literal['dual', 'toggle'] | None)
_cli_ignore_unknown_args (bool | None)
_cli_kebab_case (bool | Literal['all', 'no_enums'] | None)
_cli_shortcuts (Mapping[str, str | list[str]] | None)
_secrets_dir (PathType | None)
_build_sources (tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None)
jira_servers (dict[str, dict])
jira_url (str)
jira_user (str)
jira_token (MaskedSecret)
jira_batch_size (int)
jira_auth_method (str)
bitbucket_servers (dict[str, dict])
bitbucket_url (str)
bitbucket_user (str)
bitbucket_token (MaskedSecret)
bitbucket_auth_method (str)
github_servers (dict[str, dict])
github_url (str)
github_token (MaskedSecret)
github_default_owner (str)
github_repos (list[str])
confluence_servers (dict[str, dict])
confluence_url (str)
confluence_user (str)
confluence_token (MaskedSecret)
confluence_auth_method (str)
confluence_cookie (MaskedSecret)
ollama_host (str)
embed_model (str)
chat_model (str)
temperature (float)
enable_thinking (bool)
num_predict (int)
data_dir (Path)
collection_name (str)
chroma_host (str | None)
chroma_port (int)
chroma_ssl (bool)
chroma_auth_token (MaskedSecret | None)
chroma_tenant (str)
chroma_database (str)
chunk_size (int)
chunk_overlap (int)
top_k (int)

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_show_env_vars': False, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': '.env', 'env_file_encoding': 'utf-8', 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': 'RAGDOLL_', 'env_prefix_target': 'variable', 'extra': 'ignore', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': ['ragdoll.toml', '/home/docs/.ragdoll/config.toml'], 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod settings_customise_sources(settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings)[source]¶

Define the 4-layer config precedence.

pydantic-settings resolves left-to-right: the first source to provide a value wins.

Parameters:

settings_cls (Type[BaseSettings])
init_settings (PydanticBaseSettingsSource)
env_settings (PydanticBaseSettingsSource)
dotenv_settings (PydanticBaseSettingsSource)
file_secret_settings (PydanticBaseSettingsSource)

Return type:

Tuple[PydanticBaseSettingsSource, …]

jira_servers: dict[str, dict]¶

jira_url: str¶

jira_user: str¶

jira_token: MaskedSecret¶

jira_batch_size: int¶

jira_auth_method: str¶

get_jira_config(server_name=None, project=None)[source]¶

Get the active Jira configuration.

Resolution precedence: 1. Explicit server_name in jira_servers. 2. Match by project key against jira_servers[…][“projects”]. 3. Single server in jira_servers (if top-level token is not set). 4. “default” server in jira_servers (if present). 5. Global top-level jira_* settings.

Parameters:

server_name (str | None)
project (str | None)

Return type:

dict

bitbucket_servers: dict[str, dict]¶

bitbucket_url: str¶

bitbucket_user: str¶

bitbucket_token: MaskedSecret¶

bitbucket_auth_method: str¶

get_bitbucket_config(server_name=None)[source]¶

Get the active Bitbucket configuration.

Parameters:: server_name (str | None)
Return type:: dict

github_servers: dict[str, dict]¶

github_url: str¶

github_token: MaskedSecret¶

github_default_owner: str¶

github_repos: list[str]¶

get_github_config(server_name=None)[source]¶

Get the active GitHub configuration.

Parameters:: server_name (str | None)
Return type:: dict

get_all_github_repos()[source]¶

Get list of all tracked GitHub repositories across all servers.

Return type:: list[str]

confluence_servers: dict[str, dict]¶

confluence_url: str¶

confluence_user: str¶

confluence_token: MaskedSecret¶

confluence_auth_method: str¶

confluence_cookie: MaskedSecret¶

get_confluence_config(server_name=None, space=None)[source]¶

Get the active Confluence configuration.

Resolution precedence: 1. Explicit server_name in confluence_servers. 2. Match by space against confluence_servers[…][“spaces”]. 3. Single server in confluence_servers (if top-level token is not set). 4. “default” server in confluence_servers (if present). 5. Global top-level confluence_* settings.

Parameters:

server_name (str | None)
space (str | None)

Return type:

dict

ollama_host: str¶

embed_model: str¶

chat_model: str¶

temperature: float¶

enable_thinking: bool¶

num_predict: int¶

data_dir: Path¶

collection_name: str¶

chroma_host: str | None¶

chroma_port: int¶

chroma_ssl: bool¶

chroma_auth_token: MaskedSecret | None¶

chroma_tenant: str¶

chroma_database: str¶

chunk_size: int¶

chunk_overlap: int¶

top_k: int¶

property llm_model: str¶

property ollama_base_url: str¶

property thinking: bool¶

property chroma_dir: Path¶: Path to the ChromaDB persistent storage directory.

ensure_dirs()[source]¶

Create data directories if they don’t exist.

Return type:: None

ragdoll.config.setup_llamaindex(thinking=None)[source]¶

Parameters:: thinking (bool | None)

ragdoll.config.get_llm(thinking=None)[source]¶

Get an Ollama LLM instance with runtime thinking toggle support.

Parameters:: thinking (bool | None)

CLI¶

Ragdoll CLI — the main user-facing entry point.

Provides commands for ingesting data, searching, summarizing, and interacting with the local RAG system.

Usage:

ragdoll ingest pdf ./docs/
ragdoll ingest jira --jql "project = PROJ AND updated >= -30d"
ragdoll search "database query performance regression"
ragdoll summarize "connection pool known issues"
ragdoll chat
ragdoll status

Ingestion¶

PDF¶

Incremental PDF ingestion pipeline via LlamaIndex.

Loads PDF documents, computes content hashes, checks existing ChromaDB records, bypasses unmodified files, and re-indexes modified/new PDFs.

ragdoll.ingest.pdf.ingest_pdfs(paths, force=False)[source]¶

Ingest PDFs into the vector store with incremental content-hash change detection.

Parameters:

paths (str | Path | list[str | Path]) – Directory or file path(s) containing PDF files.
force (bool) – If True, re-indexes all PDFs even if already present and unchanged.

Returns:

(newly_ingested_chunks_count, skipped_up_to_date_files_count)

Return type:

tuple[int, int]

JIRA¶

JIRA ingestion pipeline via LlamaIndex.

Connects to a JIRA instance, retrieves issues using JQL, and indexes them into the vector store using a fast 2-phase scanning architecture.

ragdoll.ingest.jira.ingest_jira(jql, server=None, max_results=None, force=False, override_url=None, override_user=None, override_token=None, override_auth_method=None)[source]¶

Ingest JIRA issues with ultra-fast 2-phase scanning and server namespacing.

Phase 1 (Lightweight Scan):: Fast-scans JIRA using only fields=[‘updated’] (~0.15s per 100 issues) and diffs against stored ChromaDB timestamps.
Phase 2 (Targeted Full Fetch):: Fetches complete issue details and full comment threads ONLY for new or modified issues.
Phase 3 (Vector Embedding):: Embeds and indexes documents in batches via LlamaIndex and Ollama.

Returns:

(newly_ingested_count, skipped_existing_count)

Return type:

tuple[int, int]

Parameters:

jql (str)
server (str | None)
max_results (int | None)
force (bool)
override_url (str | None)
override_user (str | None)
override_token (str | None)
override_auth_method (str | None)

Code¶

Multi-language source-code ingestion module.

Recursively walks directories for source code files across multiple languages: - Python (.py) - C / C++ (.c, .h, .cpp, .cc, .cxx, .hpp, .hh, .hxx, .tcc, .cu, .cuh) - Fortran (.f, .for, .f90, .f95) - Shell Scripts (.sh, .bash, .zsh) - Templates & Build (CMakeLists.txt, .cmake, .xml, .mako, Makefile, Dockerfile) - Config & Modern Languages (.json, .yaml, .yml, .toml, .rs, .go, .js, .ts, .sql)

Extracts semantically meaningful code units (classes, functions, subroutines) or coherent chunk blocks for the RAG vector store.

ragdoll.ingest.code.ingest_code(paths, chunk_size=None, chunk_overlap=None, extensions=None, force=False)[source]¶

Ingest source code files across supported languages with incremental file-hash caching.

Parameters:

paths (list[Path]) – Files or directories to ingest.
chunk_size (int | None) – Custom chunk size for non-AST splitters.
chunk_overlap (int | None) – Custom overlap for non-AST splitters.
extensions (set[str] | None) – Optional whitelist of extensions to ingest (e.g. {‘.py’, ‘.cpp’}).
force (bool) – If True, re-indexes all source files even if unmodified.

Returns:

(extracted_documents, skipped_files_count).

Return type:

tuple[list[Document], int]

LLM¶

Ollama HTTP client for Ragdoll CLI status.

(Note: Generation and Embeddings are now handled natively by LlamaIndex.)

ragdoll.llm.ollama.list_models()[source]¶

Return a list of all model dicts available on the local Ollama instance.

Return type:: list[dict]

Vector Store¶

ChromaDB vector store wrapper for LlamaIndex.

Manages a local or remote ChromaDB collection for storing and querying document chunk embeddings via LlamaIndex.

class ragdoll.store.vectordb.RagdollChromaVectorStore(chroma_collection=None, collection_name=None, host=None, port=None, ssl=False, headers=None, persist_dir=None, collection_kwargs=None, *, stores_text=True, is_embedding_query=True, flat_metadata=True)[source]¶

Enhanced ChromaVectorStore that uses collection.upsert instead of collection.add.

Default LlamaIndex ChromaVectorStore calls collection.add(), which silently ignores nodes if their ID already exists in ChromaDB. Using upsert ensures that updated issues, wiki pages, pull requests, and documentation chunks overwrite the previous record with the new text, embedding, and updated_at_ts metadata.

Parameters:

chroma_collection (Any | None)
collection_name (str | None)
host (str | None)
port (str | int | None)
ssl (bool)
headers (Dict[str, str] | None)
persist_dir (str | None)
collection_kwargs (dict | None)
stores_text (bool)
is_embedding_query (bool)
flat_metadata (bool)

add(nodes, **add_kwargs)[source]¶

Add nodes to index.

Parameters:

nodes (List[BaseNode]) – List[BaseNode]: list of nodes with embeddings
add_kwargs (Any)

Return type:

List[str]

model_config = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

ragdoll.store.vectordb.get_vector_store(name=None)[source]¶

Get the LlamaIndex ChromaVectorStore wrapper with upsert support.

Parameters:: name (str | None)
Return type:: RagdollChromaVectorStore

ragdoll.store.vectordb.get_index(name=None)[source]¶

Get the LlamaIndex VectorStoreIndex for querying and inserting.

Parameters:: name (str | None)
Return type:: VectorStoreIndex

ragdoll.store.vectordb.count(name=None)[source]¶

Parameters:: name (str | None)
Return type:: int

ragdoll.store.vectordb.delete_collection(name=None, purge_storage=True)[source]¶

Delete a ChromaDB collection and optionally purge local storage to reclaim disk space.

Parameters:

name (str | None)
purge_storage (bool)

Return type:

None

ragdoll.store.vectordb.list_collections()[source]¶

Return type:: list[str]

Query¶

Retriever¶

Semantic retriever via LlamaIndex.

Queries the vector store and returns structured search results.

class ragdoll.query.retriever.SearchResult(chunk_id, text, score, metadata=<factory>)[source]¶

A single search hit.

Parameters:

chunk_id (str)
text (str)
score (float)
metadata (dict)

chunk_id¶

The chunk identifier.

Type:: str

text¶

The chunk text.

Type:: str

score¶

Similarity score (cosine distance — lower is better).

Type:: float

metadata¶

Chunk metadata.

Type:: dict

chunk_id: str¶

text: str¶

score: float¶

metadata: dict¶

ragdoll.query.retriever.search(query, top_k=None, source_filter=None)[source]¶

Perform semantic search over the indexed documents.

Parameters:

query (str) – Natural-language search query.
top_k (int, optional) – Number of results (default: from settings).
source_filter (str, optional) – If provided, filter by source type ("pdf", "jira", "code", etc.).

Returns:

Ranked search results.

Return type:

list[SearchResult]

RAG Chain¶

RAG chain via LlamaIndex.

This module ties together retrieval and generation into a single question-answering pipeline using LlamaIndex LLM engines.

ragdoll.query.rag.query(question, top_k=None, source_filter=None, stream=False)[source]¶

Single-turn RAG query.

Parameters:

question (str)
top_k (int | None)
source_filter (str | None)
stream (bool)

Return type:

str | Generator[str, None, None]

ragdoll.query.rag.summarize(topic, top_k=None, source_filter=None, stream=False)[source]¶

Summarize context retrieved for a topic.

Parameters:

topic (str)
top_k (int | None)
source_filter (str | None)
stream (bool)

Return type:

str | Generator[str, None, None]

ragdoll.query.rag.query_live_jira(jql)[source]¶

Execute a JQL query directly against all configured JIRA APIs.

Parameters:: jql (str)
Return type:: str

ragdoll.query.rag.query_live_bitbucket(project, repo, state='OPEN')[source]¶

Execute a query directly against configured Bitbucket APIs for PRs.

Parameters:

project (str)
repo (str)
state (str)

Return type:

str

ragdoll.query.rag.query_live_github(owner, repo, state='open', item_type='all')[source]¶

Execute a query directly against GitHub API for issues/PRs.

Parameters:

owner (str)
repo (str)
state (str)
item_type (str)

Return type:

str

ragdoll.query.rag.chat_with_context(messages, top_k=None, source_filter=None, stream=False, enable_thinking=None, on_status=None, on_metadata=None)[source]¶

Chat with RAG context injected from the latest user message.

Parameters:

messages (list[dict[str, str]])
top_k (int | None)
source_filter (str | None)
stream (bool)
enable_thinking (bool | None)
on_status (Callable[[str], None] | None)
on_metadata (Callable[[dict[str, Any]], None] | None)

Return type:

str | Generator[str, None, None]