> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# RAG CLI

> Command-line interface for RAG operations

# RAG CLI

The `praisonai rag` command group provides full RAG functionality from the command line.

## Commands

### index

Build or update an index from source documents.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai rag index <sources> [options]
```

**Arguments:**

* `sources` - Files, directories, or URLs to index

**Options:**

* `--collection, -c` - Collection name (default: "default")
* `--chunking` - Chunking strategy: token, sentence, recursive, semantic
* `--chunk-size` - Chunk size in tokens (default: 512)
* `--config, -f` - Config file path
* `--verbose, -v` - Verbose output
* `--profile` - Enable performance profiling
* `--profile-out` - Save profile to JSON file
* `--profile-top` - Top N items in profile (default: 20)

<Note>
  This command uses the Knowledge substrate for indexing. Equivalent to `praisonai knowledge index`.
</Note>

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Index a directory
praisonai rag index ./documents

# Index specific files
praisonai rag index paper.pdf report.docx

# Index with custom collection
praisonai rag index ./data --collection research

# Index with semantic chunking
praisonai rag index ./docs --chunking semantic --chunk-size 256
```

### query

One-shot question answering with citations.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai rag query "<question>" [options]
```

**Options:**

* `--collection, -c` - Collection to query (default: "default")
* `--top-k, -k` - Number of results (default: 5)
* `--hybrid` - Use hybrid retrieval (dense + BM25)
* `--rerank` - Enable reranking of results
* `--citations/--no-citations` - Include citations (default: true)
* `--config, -f` - Config file path
* `--verbose, -v` - Verbose output
* `--profile` - Enable performance profiling
* `--profile-out` - Save profile to JSON file
* `--profile-top` - Top N items in profile (default: 20)

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple query
praisonai rag query "What is the main finding?"

# Query specific collection
praisonai rag query "Summarize the methodology" --collection research

# Query with hybrid retrieval (combines dense vectors + BM25 keyword search)
praisonai rag query "What are the key findings?" --hybrid

# Query with hybrid + reranking for best quality
praisonai rag query "Summarize conclusions" --hybrid --rerank

# Query with more results
praisonai rag query "List all conclusions" --top-k 10

# Query without citations
praisonai rag query "Quick summary" --no-citations

# Query with profiling
praisonai rag query "Summary?" --profile --profile-out ./profile.json
```

### chat

Interactive RAG chat session with streaming.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai rag chat [options]
```

**Options:**

* `--collection, -c` - Collection to chat with (default: "default")
* `--top-k, -k` - Results per query (default: 5)
* `--hybrid` - Use hybrid retrieval (dense + BM25)
* `--rerank` - Enable reranking of results
* `--config, -f` - Config file path
* `--stream/--no-stream` - Stream responses (default: true)

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start chat session
praisonai rag chat

# Chat with specific collection
praisonai rag chat --collection research

# Chat with hybrid retrieval
praisonai rag chat --hybrid --rerank

# Chat without streaming
praisonai rag chat --no-stream
```

**Chat Commands:**

* Type questions to get answers
* `exit`, `quit`, or `q` to end session
* `Ctrl+C` to interrupt

### eval

Evaluate RAG retrieval quality against golden queries.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai rag eval <test_file> [options]
```

**Arguments:**

* `test_file` - JSON file with test queries

**Options:**

* `--collection, -c` - Collection to evaluate (default: "default")
* `--top-k, -k` - Results to retrieve (default: 5)
* `--output, -o` - Output results to file
* `--verbose, -v` - Verbose output
* `--profile` - Enable performance profiling
* `--profile-out` - Save profile to JSON file
* `--profile-top` - Top N items in profile (default: 20)

**Test File Format:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
[
  {
    "query": "What is the main finding?",
    "expected_doc": "paper.pdf",
    "expected_answer_contains": "significant improvement"
  },
  {
    "query": "What methodology was used?",
    "expected_doc": "methods.pdf",
    "expected_answer_contains": "randomized"
  }
]
```

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run evaluation
praisonai rag eval golden_queries.json

# Evaluate with output
praisonai rag eval tests.json --output results.json

# Verbose evaluation
praisonai rag eval tests.json --verbose
```

### serve

Start RAG as a microservice API.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai serve rag [options]
```

**Options:**

* `--collection, -c` - Collection to serve (default: "default")
* `--host, -h` - Host to bind (default: 127.0.0.1)
* `--port, -p` - Port to bind (default: 8080)
* `--hybrid` - Use hybrid retrieval (dense + BM25)
* `--rerank` - Enable reranking of results
* `--openai-compat` - Enable OpenAI-compatible `/v1/chat/completions` endpoint
* `--config, -f` - Config file path
* `--verbose, -v` - Verbose output
* `--profile` - Enable performance profiling
* `--profile-out` - Save profile to JSON file
* `--profile-top` - Top N items in profile (default: 20)

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start server
praisonai serve rag

# Serve specific collection on custom port
praisonai serve rag --collection research --port 9000

# Serve with hybrid retrieval + reranking
praisonai serve rag --hybrid --rerank

# Serve with OpenAI-compatible endpoint
praisonai serve rag --openai-compat --port 8080

# Serve on all interfaces
praisonai serve rag --host 0.0.0.0
```

**API Endpoints:**

| Endpoint               | Method | Description                                              |
| ---------------------- | ------ | -------------------------------------------------------- |
| `/health`              | GET    | Health check (returns collection, hybrid, rerank status) |
| `/rag/query`           | POST   | Query with JSON body                                     |
| `/rag/chat`            | POST   | Streaming chat (SSE)                                     |
| `/v1/chat/completions` | POST   | OpenAI-compatible endpoint (with `--openai-compat`)      |
| `/docs`                | GET    | OpenAPI documentation                                    |

**Query Request:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "question": "What is the main finding?",
  "top_k": 5,
  "include_citations": true,
  "hybrid": false,
  "rerank": false
}
```

## Configuration File

Create a YAML config file for reusable settings:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# rag_config.yaml
knowledge:
  sources:
    - ./documents
  collection: my_docs
  
  chunking:
    strategy: semantic
    chunk_size: 512
    chunk_overlap: 50
  
  vector_store:
    provider: chroma
    config:
      persist_directory: ./.praison/knowledge/my_docs

retrieval:
  hybrid: true
  rerank: true
  top_k: 5
  min_score: 0.5

rag:
  include_citations: true
  max_context_tokens: 4000
```

Use with any command:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai rag query "Question" --config rag_config.yaml
```

## Configuration Precedence

Settings are applied in this order (highest priority first):

1. **CLI flags** - `--hybrid`, `--rerank`, `--top-k`, etc.
2. **Environment variables** - `PRAISONAI_HYBRID=true`, etc.
3. **Config file** - YAML configuration
4. **Defaults** - Built-in defaults

This means CLI flags always override environment variables, which override config file settings.

## Environment Variables

Override settings with environment variables:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_COLLECTION=my_docs
export PRAISONAI_TOP_K=10
export PRAISONAI_HYBRID=true
export PRAISONAI_RERANK=true
export PRAISONAI_MODEL=gpt-4o-mini
```

## Exit Codes

| Code | Meaning                                  |
| ---- | ---------------------------------------- |
| 0    | Success                                  |
| 1    | Error (missing deps, config error, etc.) |

## Knowledge vs RAG

**Knowledge** is the indexing and retrieval substrate:

* Indexes documents into vector stores
* Performs similarity search
* Returns raw chunks/documents
* Use `praisonai knowledge` for indexing and search without LLM generation

**RAG** orchestrates on top of Knowledge:

* Retrieves context using Knowledge
* Generates answers with an LLM
* Provides citations
* Use `praisonai rag` for question answering with generated responses

Both share the same underlying index. You can index with `knowledge index` and query with `rag query`.

## Tips

1. **Start simple**: Use defaults, then customize
2. **Use hybrid retrieval**: `--hybrid` combines dense + keyword search for better recall
3. **Enable reranking**: `--rerank` improves precision for complex queries
4. **Name collections**: Organize by project or topic
5. **Use config files**: For reproducible setups
6. **Check verbose output**: Debug retrieval issues
7. **Profile performance**: Use `--profile` to identify bottlenecks
8. **Evaluate regularly**: Track quality over time