Nodetool Rag Indexing

---
name: nodetool-rag-indexing
description: Set up RAG pipelines, vector indexing, document ingestion, vector search, and knowledge base creation in NodeTool. Use when user asks about RAG, document indexing, vector search, chat with documents, knowledge base, embeddings, or collection management.
---

You help users build Retrieval-Augmented Generation (RAG) pipelines in NodeTool.

# RAG Architecture

```
INDEXING:  Documents → Load → Split → Embed → Store (vector collection)
QUERY:     Question → Embed → Search → Format → LLM → Answer
```

# Vector Store Backends

NodeTool's vector store (`@nodetool-ai/vectorstore`) is backend-pluggable. The
workflow nodes are the same regardless of backend — you pick the backend via
configuration.

| Backend | Best for | Notes |
|---------|----------|-------|
| **SQLite-vec** | Default, local, embedded | No external service |
| **ChromaDB** | Self-host / remote | `CHROMA_URL`, `CHROMA_PATH`, `CHROMA_TOKEN` |
| **Pinecone** | Managed cloud | API-key based |
| **Supabase (pgvector)** | Postgres-backed | Pairs with Supabase auth/storage |

There are **no FAISS nodes**; the backends above cover local and hosted use.

# Vector Nodes (`vector.*`)

All RAG nodes live under the single `vector.*` namespace (not `vector.chroma.*`
or `vector.faiss.*`).

| Node | Purpose |
|------|---------|
| `vector.Collection` | Reference/select a collection by name (the collection ref other nodes consume) |
| `vector.IndexTextChunk` | Index a single text chunk with its embedding |
| `vector.IndexString` | Index a string value |
| `vector.IndexAggregatedText` | Index aggregated text |
| `vector.IndexEmbedding` | Index a precomputed embedding |
| `vector.IndexImage` | Index an image |
| `vector.QueryText` | Vector similarity search over text |
| `vector.QueryImage` | Vector similarity search over images |
| `vector.HybridSearch` | Vector + keyword search (best accuracy) |
| `vector.GetDocuments` | Retrieve specific documents |
| `vector.Count` | Count documents in a collection |
| `vector.Peek` | Preview collection contents |
| `vector.RemoveOverlap` | De-duplicate overlapping chunks in results |

Query nodes (`QueryText`, `QueryImage`, `HybridSearch`) output `ids`,
`documents`, `metadatas`, and `distances` (HybridSearch also returns `scores`).

# Document Loading & Splitting

| Node | Namespace | Purpose |
|------|-----------|---------|
| `Code` | `nodetool.code` | Enumerate files with `await workspace.list(dir)` |
| `LoadDocumentFile` | `nodetool.document` | Load a PDF/TXT/MD into a document |
| `Chunk` | `nodetool.text` | Fixed-size word chunking with overlap (general purpose) |
| `RegexSplit` | `nodetool.text` | Structure-aware splitting on a delimiter pattern |

## Chunk Size Guidance

| Content type | Chunk size | Overlap |
|--------------|-----------|---------|
| Technical docs | 200-500 tokens | 50 tokens |
| Prose/articles | 300-600 tokens | 75 tokens |
| Code | 100-300 tokens | 25 tokens |

# Indexing — Workflow Pattern

```
ListFiles → LoadDocumentFile → Chunk → IndexTextChunk(collection)
```

Pair every index/query node with a `vector.Collection` node (or a collection
name) so they target the same store. Use the **same embedding model** for
indexing and querying.

# Indexing — HTTP API

```bash
# Index a file into a collection
curl -X POST http://localhost:7777/api/collections/<name>/index \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/document.pdf"}'
```

The server resolves the collection, runs its ingestion workflow if one is
registered, otherwise falls back to split → embed → store.

# Query — Workflow Pattern

```
ChatInput → HybridSearch(collection, top_k) → FormatText → Agent → Output
```

| Node | Purpose |
|------|---------|
| `ChatInput` | User question |
| `vector.HybridSearch` | Vector + keyword retrieval (best accuracy) |
| `vector.QueryText` | Vector-only retrieval (faster) |
| `FormatText` | Build the context string for the LLM |
| `Agent` | Generate the answer from context + question |
| `Output` | Return the answer |

# Complete RAG Example

## Index
```
ListFiles("/docs/") → LoadDocumentFile → Chunk(length=400, overlap=50)
                                                  ↓
                                  IndexTextChunk(collection="my-docs")
```

## Query
```
ChatInput("What is...?") → HybridSearch(collection="my-docs", top_k=5)
                                  ↓
                         FormatText(template="Context:\n{documents}\n\nQuestion: {query}")
                                  ↓
                         Agent(model=gpt-5.4, system="Answer using only the context provided.")
                                  ↓
                         Output
```

# Environment Variables

```bash
# ChromaDB backend (only when using Chroma — SQLite-vec needs no config)
CHROMA_URL=                          # Remote Chroma URL (empty = local)
CHROMA_PATH=~/.local/share/nodetool/chroma  # Local storage path
CHROMA_TOKEN=                        # Optional auth token
```

The embedding model is chosen on the index/query nodes via model selection
(e.g. `text-embedding-3-small`, or a local sentence-transformers model).

# Common Pitfalls

- **Embedding model mismatch**: use the same embedding model for indexing and search.
- **Chunks too large**: dilute the LLM context — keep to 200-500 tokens.
- **Chunks too small**: sentences get fragmented; use 10-20% overlap.
- **Empty collection**: index before querying — an unindexed collection returns nothing.
- **Wrong node names**: it's `vector.IndexTextChunk` / `vector.QueryText` / `vector.HybridSearch`, not `IndexTextChunks` / `TextSearch`, and there is no `vector.chroma.*`/`vector.faiss.*` namespace.
- **No `nodetool collections` CLI**: manage collections through the editor UI or the `/api/collections/...` endpoints.