Commands

CLI Commands

The raghelm CLI provides both evaluation and production-grade document ingestion.

eval

Run the evaluation suite against the golden dataset.

python -m raghelm eval [--suite full|quick]

Flag	Description
--suite full	Run all 100 examples (default)
--suite quick	Run 10 randomly selected examples

ingest run

The primary command for ingesting documents into Pinecone with formal verification, cost tracking, and Hollywood-grade terminal UX.

python -m raghelm ingest [OPTIONS] SOURCE

Arguments

Argument	Description
SOURCE	Path to a directory or single file (.md / .txt supported)

Options

Flag	Default	Description
--namespace, -n	default	Target Pinecone namespace
--chunk-size	512	Maximum characters per chunk (128-2048)
--dry-run	false	Simulate without calling embedding or vector DB APIs

Examples

Basic dry-run (recommended first step)

uv run python -m raghelm ingest ./docs --dry-run --namespace default

Production ingestion with custom chunk size

uv run python -m raghelm ingest /path/to/knowledge-base \
  --namespace semantic-512 \
  --chunk-size 512

Large context namespace

uv run python -m raghelm ingest data/raw \
  --namespace chunk-1024-large \
  --chunk-size 1024

Output

The CLI produces a rich verification report:

╭───────────────────────────────────────────────────╮
│ RAGHELM INGESTION v0.2 - FORMAL VERIFICATION MODE │
╰───────────────────────────────────────────────────╯
...
Ingestion Verification Report
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Metric            ┃ Value          ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ Files Processed   │ 12             │
│ Chunks Created    │ 487            │
│ Tokens Embedded   │ 124,300        │
│ Vectors Upserted  │ 487            │
│ Est. Cost (USD)   │ $0.002486      │
│ Namespace         │ semantic-512   │
│ Checksum Sample   │ a3f9c2e1       │
└───────────────────┴────────────────┘

Formal Verification & Safety

• Every chunk receives a SHA-256 checksum (first 16 chars stored in metadata)
• Recursive chunker guarantees len(chunk) <= chunk_size + 50
• Pydantic models enforce namespace regex and size bounds at runtime
• Dry-run mode uses deterministic fake embeddings (no API keys required)
• Token counting uses tiktoken when available, graceful fallback otherwise

Performance Notes

• Batched upserts (default 100 vectors)
• Lazy Pinecone/OpenAI client initialization
• Progress bar with spinner + elapsed time
• Cost estimation uses the exact embedding model pricing

Audit logs are written to data/ingestion_audit.json after every run.