Retrieval (RAG)

Retrieval-augmented generation gives an agent the passages of your documents that matter for a question. In Gwenflow the pipeline has four steps: readers turn files into Documents, a splitter cuts them into chunks, a vector store indexes the chunks with embeddings, and a retriever searches it, optionally with a reranker, at question time.

from gwenflow import Agent, ChatOpenAI, Retriever, SimpleDirectoryReader

documents = SimpleDirectoryReader(input_dir="./handbook").read()

retriever = Retriever(name="handbook", top_k=5)
retriever.load_documents(documents)

agent = Agent(
    name="HR assistant",
    instructions="Answer from the handbook. Say so when the handbook does not cover the question.",
    llm=ChatOpenAI(model="gpt-5-mini"),
    retriever=retriever,
)

print(agent.run("How many days of remote work are allowed per week?").content)

Documents

A Document (gwenflow.types) holds content, metadata, and once indexed an embedding; a search result also has a score. Its id defaults to a hash of the content, so re-ingesting the same chunk keeps its identity.

Readers

Reader	Reads
`SimpleDirectoryReader`	every file of a directory or a list of files
`PDFReader`	PDF, page by page, tables included
`DocxReader`, `PptxReader`, `ExcelReader`	Word, PowerPoint, Excel
`CSVReader`, `JSONReader`, `XmlReader`, `TextReader`	structured and plain text
`WebsiteReader`	a website, following links up to `max_depth`

They are importable from gwenflow.readers. The PDF and Office readers need pip install "gwenflow[readers]".

from pathlib import Path
from gwenflow.readers import PDFReader, SimpleDirectoryReader, WebsiteReader

docs = PDFReader().read(Path("./reports/annual-2025.pdf"))     # a Path or a BytesIO
docs = WebsiteReader(max_depth=2).read("https://docs.example.com")
docs = SimpleDirectoryReader(input_dir="./data", required_exts=[".pdf", ".md"], recursive=True).read()

SimpleDirectoryReader reads PDF and JSON files with their readers and other files as text. Its options: input_files instead of input_dir, exclude, exclude_hidden (default True), recursive (default True), required_exts, encoding, filename_as_id, raise_on_error.

Splitting

TokenTextSplitter cuts text into chunks of a number of tokens, with an overlap so a sentence cut at a boundary keeps its context:

from gwenflow.parsers import TokenTextSplitter

splitter = TokenTextSplitter(chunk_size=500, chunk_overlap=100)
chunks = splitter.split_documents(documents)

The retriever splits documents itself when you load them; use the splitter when you index chunks yourself.

The retriever

from gwenflow import Retriever

retriever = Retriever(
    name="handbook",
    chunk_size=500,      # tokens per chunk
    chunk_overlap=100,
    top_k=5,             # passages returned by a search
)
retriever.load_documents(documents)   # Documents or strings: split, embedded, indexed

for doc in retriever.search("remote work policy"):
    print(doc.score, doc.content[:80])

Without a vector_db, the retriever creates a LanceDB table in ./<name> (or pathname), with Gwenlake embeddings (multilingual-e5-large) and the Gwenlake reranker (BAAI/bge-reranker-v2-m3). This default needs pip install lancedb and a GWENLAKE_API_KEY. search fetches ten times top_k candidates, and returns the best top_k.

In an agent

With retriever=, the agent searches it with the task before each run and puts the passages in its system prompt, as references.

As a tool

To let the model decide when and what to search, give it a RetrieverTool instead:

from gwenflow.tools import RetrieverTool

agent = Agent(name="HR assistant", llm=llm, tools=[RetrieverTool(retriever=retriever)])

Vector stores

Store	Import	Needs
LanceDB	`gwenflow.vector_stores.lancedb.LanceDB(uri, collection="default", ...)`	`lancedb`; local path, `s3://` or LanceDB Cloud (`api_key`)
Qdrant	`gwenflow.vector_stores.qdrant.Qdrant(collection, host=..., url=..., path=..., api_key=...)`	`qdrant-client`
FAISS	`gwenflow.vector_stores.faiss.FAISS(filename)`	`faiss-cpu`; saved to a `.pkl` file

Each takes embeddings and an optional reranker, and offers insert(documents), search(query, limit, filters), get(id), delete(id), count() and drop(). Pass one to the retriever:

from gwenflow import Retriever
from gwenflow.embeddings import GwenlakeEmbeddings
from gwenflow.reranker import GwenlakeReranker
from gwenflow.vector_stores.qdrant import Qdrant

store = Qdrant(
    collection="handbook",
    url="https://qdrant.example.com",
    api_key="...",
    embeddings=GwenlakeEmbeddings(model="multilingual-e5-large"),
    reranker=GwenlakeReranker(model="BAAI/bge-reranker-v2-m3"),
)
retriever = Retriever(name="handbook", vector_db=store)

Embeddings and reranking

GwenlakeEmbeddings and GwenlakeReranker call the Gwenlake API (GWENLAKE_API_KEY). To use another provider, subclass gwenflow.embeddings.Embeddings (implement embed_documents(texts) and embed_query(text)) or gwenflow.reranker.Reranker (implement rerank(query, documents)). For keyword search without embeddings, BM25(documents).rank(query, top_n=5) (gwenflow.retriever) ranks documents with BM25.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Documents

Readers

Splitting

The retriever

In an agent

As a tool

Vector stores

Embeddings and reranking

​Documents

​Readers

​Splitting

​The retriever

​In an agent

​As a tool

​Vector stores

​Embeddings and reranking

Documents

Readers

Splitting

The retriever

In an agent

As a tool

Vector stores

Embeddings and reranking