CLI Command Reference

This document is the command reference for rag-cli.

Overview

Top-level help:

uv run python -m src.cli --help

Current commands:

convert
chunk prepare
rag baseline
parser
dataset peek
indexing
query
eval create-dataset
eval run

Implemented parser subcommands:

parser
parser review
parser preprocess

`convert`

Convert one file from a source format to a target format.

Help:

uv run python -m src.cli convert --help

Current supported pair:

docx -> pdf

Example:

uv run python -m src.cli convert \
  --source docx \
  --target pdf \
  --input "data/ir-sample-a.docx" \
  --output data/raw/avatar-comments.pdf

Notes:

conversion uses LibreOffice in headless mode
requires soffice or libreoffice on PATH

`parser`

Run the raw parser pipeline from a YAML config.

Help:

uv run python -m src.cli parser --help

Example:

uv run python -m src.cli parser --config configs/baseline.yml --pretty

Override the run output directory:

uv run python -m src.cli parser \
  --config configs/baseline.yml \
  --output-dir data/artifacts/ir_document \
  --pretty

Behavior:

writes raw parser artifacts, manifest, and telemetry
if --output-dir is omitted, outputs are written under pipeline.artifact_dir/<run_id>
if --output-dir is set, outputs are written directly under that directory

Primary raw artifact:

parsed/unstructured_elements.json

`parser review`

Render saved parser output into a reviewable file.

Help:

uv run python -m src.cli parser review --help

Example:

uv run python -m src.cli parser review \
  --input data/artifacts/ir_document/parsed/unstructured_elements.json \
  --output-format html

Optional explicit output file:

uv run python -m src.cli parser review \
  --input data/artifacts/ir_document/parsed/unstructured_elements.json \
  --output-format html \
  --output data/artifacts/ir_document/parsed/unstructured_elements.html

Behavior:

reads saved raw parser JSON
reconstructs Unstructured elements
writes a review file such as HTML
falls back to non-paged HTML when page_number metadata is missing

Typical use:

manual QA of raw parser output

`parser preprocess`

Normalize saved parser output into lighter-weight artifacts.

Help:

uv run python -m src.cli parser preprocess --help

Example:

uv run python -m src.cli parser preprocess \
  --input data/artifacts/ir_document/parsed/unstructured_elements.json

Use a YAML config to control preprocess steps:

uv run python -m src.cli parser preprocess \
  --input data/artifacts/ir_document/parsed/unstructured_elements.json \
  --config configs/preprocess.yml

Explicit output directory:

uv run python -m src.cli parser preprocess \
  --input data/artifacts/ir_document/parsed/unstructured_elements.json \
  --output-dir data/artifacts/ir_document/normalized

Outputs:

normalized/elements.json
normalized/review.html

Behavior:

keeps raw parser output unchanged
normalizes text and metadata for downstream consumption
accepts optional YAML step toggles through --config
strips heavy image base64 payloads
removes decorative elements and repeated boilerplate
reclassifies heading-like bold UncategorizedText
cleans table HTML for review and table text for retrieval
emits structured warnings for extraction gaps such as missing page metadata
merge_table_columns is disabled by default so sparse extracted table columns are preserved unless explicitly collapsed

Config example:

preprocess:
  steps:
    merge_table_columns: true

Typical use:

prepare parser output for human review
prepare cleaner artifacts for later indexing work

`chunk prepare`

Build structured retrieval chunks from normalized parser elements.

Detailed chunker behavior and output schema are documented in docs/chunker.md.

Help:

uv run python -m src.cli chunk prepare --help

Example:

uv run python -m src.cli chunk prepare \
  --input data/artifacts/ir_document/normalized/elements.json

Use the default section-table chunker from YAML:

uv run python -m src.cli chunk prepare \
  --input data/artifacts/ir_document/normalized/elements.json \
  --config configs/chunker.yml

Use the section-token (RAGFlow-inspired) chunker:

uv run python -m src.cli chunk prepare \
  --input data/artifacts/ir_document/normalized/elements.json \
  --config configs/chunkers/section-token.yml

Use the title-hierarchy chunker (multi-level heading tree):

uv run python -m src.cli chunk prepare \
  --input data/artifacts/ir_document/normalized/elements.json \
  --config configs/chunkers/title-hierarchy.yml

Explicit output directory:

uv run python -m src.cli chunk prepare \
  --input data/artifacts/ir_document/normalized/elements.json \
  --output-dir data/artifacts/ir_document/chunked

Outputs:

chunked/chunks.json

Behavior:

reads normalized parser elements
supports pluggable chunker strategies through core/chunker
default section_table strategy writes section parent chunks plus child text and table chunks
section_token strategy builds token-sized child chunks with RAGFlow-style table context windows and optional parent-child splitting (accepts legacy ragflow provider alias)
title_hierarchy strategy builds a multi-level section tree from heading-text regexes and emits one chunk per leaf-path with ancestor titles inlined
preserves table structure in table_html, table_text, and table_text_markdown
attaches nearby narrative context to table chunks through pre_text and post_text
emits chunk_strategy plus provenance fields such as doc_id, heading_path, source_element_ids, and page_number

Chunker config examples:

chunker:
  provider: section_table
  options: {}

chunker:
  provider: section_token
  options:
    chunk_token_size: 128
    children_delimiters:
      - "\n\n"
    use_parent_child: true
    table_context_size: 64

chunker:
  provider: title_hierarchy
  options:
    levels:
      - - "^\\d+\\.\\s+[A-Z].*"
        - "^\\([a-z]\\)\\s"
    hierarchy: null
    include_heading_content: false
    root_chunk_as_heading: false

`dataset peek`

Inspect local benchmark datasets and print a compact JSON summary.

Help:

uv run python -m src.cli dataset peek --help

Example:

uv run python -m src.cli dataset peek \
  --dataset all \
  --root data/datasets \
  --pretty

Supported dataset selectors:

financebench
t2-ragbench
finder
all

`indexing`

Embed and index chunks into a vector store.

Help:

uv run python -m src.cli indexing --help

Example:

uv run python -m src.cli indexing \
  --input data/artifacts/ir_document/chunked/chunks.json \
  --config configs/rag-baseline.yml \
  --pretty

Behavior:

reads chunks.json, optionally runs an ordered enrichment pipeline, embeds chunk retrieval text, and stores chunks in the vector DB
requires embedding and vector_store sections in the YAML config
optional enrichment section runs before embedding
current providers: OpenAI embeddings + ChromaDB

Supported enrichment steps today:

table_context: RAGFlow-style table context augmentation; writes content_with_weight for table chunks using nearby text
auto_keywords: RAGFlow-style keyword extraction; writes important_kwd and important_tks
auto_questions: RAGFlow-style question generation; writes question_kwd and question_tks

Example:

enrichment:
  pipeline:
    - table_context
    - auto_keywords
    - auto_questions
  options:
    table_context:
      table_context_size: 64
    auto_keywords:
      model: gpt-4.1-mini
      topn: 3
    auto_questions:
      model: gpt-4.1-mini
      topn: 3

Prebuilt enrichment configs:

configs/enrichment/table-context.yml
configs/enrichment/auto-keywords.yml
configs/enrichment/auto-questions.yml
configs/enrichment/all.yml

To inspect enrichment output without embedding:

uv run python scripts/enrichment/preview.py \
  --input data/artifacts/ir_document/chunked/chunks.json \
  --config configs/enrichment/table-context.yml

uv run python scripts/enrichment/show_chunks.py \
  --input data/artifacts/ir_document/enriched/table-context.json \
  --feature table_context \
  --chunk-type table \
  --limit 5

Convenience shell wrapper:

scripts/enrichment/run.sh \
  configs/enrichment/table-context.yml \
  data/artifacts/ir_document/chunked/chunks.json \
  table_context \
  table \
  5

The wrapper enables verbose enrichment progress automatically.

`query`

Run a RAG query: retrieve context and generate an answer.

Help:

uv run python -m src.cli query --help

Single question:

uv run python -m src.cli query \
  --question "What was AMD total revenue in FY2022?" \
  --config configs/rag-baseline.yml \
  --pretty

Batch mode (JSONL input):

uv run python -m src.cli query \
  --input questions.jsonl \
  --config configs/rag-baseline.yml \
  --output results.jsonl

Behavior:

single mode: retrieves top-k chunks, generates answer, prints JSON result
batch mode: processes each row in JSONL, writes results to output JSONL
requires embedding, vector_store, retrieval, and generation config sections

`rag baseline`

Run one-shot baseline RAG over a local chunks.json file.

Detailed behavior is documented in docs/rag-baseline.md.

Help:

uv run python -m src.cli rag baseline --help

Example:

uv run python -m src.cli rag baseline \
  --input data/artifacts/ir_document/chunked/chunks.json \
  --question "What was Cash as of December 31, 2024?" \
  --config configs/rag-simple-baseline.yml \
  --pretty

Behavior:

reads local chunk artifacts
converts chunks to LangChain Document objects
builds an in-memory vector store for the command run
retrieves top-k context
calls the configured chat model
does not persist an index

`eval run`

Run end-to-end RAG evaluation against a benchmark dataset.

Help:

uv run python -m src.cli eval run --help

Example:

uv run python -m src.cli eval run \
  --dataset financebench \
  --filter-doc AMD_2022_10K \
  --config configs/rag-baseline.yml \
  --pretty

Behavior:

loads benchmark questions (FinanceBench supported)
optionally filters to a specific document via --filter-doc
for each question: retrieves context, generates answer, collects results
scores results using RAGAS (faithfulness, answer relevancy, context precision)
writes per_question.jsonl and eval_results.json to output directory

FilesExpand file tree

command.md

Latest commit

History

command.md

File metadata and controls

CLI Command Reference

Overview

convert

parser

parser review

parser preprocess

chunk prepare

dataset peek

indexing

query

rag baseline

eval run

`convert`

`parser`

`parser review`

`parser preprocess`

`chunk prepare`

`dataset peek`

`indexing`

`query`

`rag baseline`

`eval run`