How Ragtime Works

If you are new to Ragtime, or new to retrieval-based AI in general, this page is the place to start. It explains what actually happens when you upload a document and someone asks a question about it, without assuming you have worked with language models before.

Everything here is conceptual. The other pages in this documentation tell you which button to press and which endpoint to call.

The problem Ragtime solves

A language model like the ones behind ChatGPT has read an enormous amount of the public internet, but it has never seen your product manual, your course materials, or your internal policies. Ask it about them and it will either say it doesn’t know, or — worse — invent something plausible.

There are two ways to fix that. You can retrain the model on your content, which is slow, expensive, and out of date the moment your content changes. Or you can look up the relevant passages of your content at the moment the question is asked and hand them to the model along with the question.

Ragtime does the second one. The technique is called RAG — Retrieval Augmented Generation. “Retrieval” is the lookup, “generation” is the model writing the answer, and “augmented” is the fact that the answer is grounded in what was retrieved rather than in the model’s memory.

The practical consequence: the model is not being asked what it knows. It is being asked to answer using this specific text. That is why Ragtime assistants can cite their sources, and why updating a document updates the answers within minutes rather than requiring anything to be retrained.

An assistant is a project

In Ragtime, project and assistant mean the same thing. A project bundles everything that makes one assistant what it is:

• Its persona — the name, tone, and instructions that shape how it speaks.
• Its knowledge — the content it is allowed to draw on.
• Its behaviour — flows, actions, voice settings, languages.
• Its deployment — where it lives and who may reach it.

If you need two assistants with genuinely different personalities or different knowledge, that is two projects. Most of the configuration in the dashboard is scoped to whichever project you have selected.

From a document to something searchable

When you add content — an uploaded file, a crawled page, or a document pushed through the Ingest API — it goes through four steps.

1. It becomes a source. A source is one item of content: one PDF, one web page, one article. Sources keep their identity so you can see where an answer came from and remove content later.

2. The text is extracted. A PDF is not text — it is a description of marks on a page. Ragtime pulls out the readable content, including text embedded in images where it can.

3. The text is cut into chunks. A chunk is a passage of a few hundred words. This matters more than it sounds. Retrieval works at chunk level, not document level, so a hundred-page manual can contribute exactly the one paragraph that answers a question without dragging in the other ninety-nine pages. Chunks overlap slightly at their edges so a sentence spanning a boundary isn’t lost.

4. Each chunk gets an embedding. An embedding is a list of numbers — a few thousand of them — that represents the meaning of a passage. Passages about similar things end up with similar numbers, even when they share no words. This is the part that makes retrieval work on meaning rather than keywords: a question about “how do I get my money back” can find a chunk about “refund eligibility” without either phrase appearing in the other.

Embeddings are produced by a model, and different models produce numbers that are not comparable with each other. That is why changing your embedding model requires re-processing existing content, and why Ragtime flags libraries as incompatible when their embeddings were made with a different model than your organization currently uses.

What happens when someone asks a question

1. The question is turned into an embedding, using the same model as the content.
2. Ragtime compares it against the chunks the visitor is allowed to see and picks the closest handful. This is a vector search — mathematically, finding the nearest points in a very high-dimensional space; practically, finding the passages that mean the most similar thing.
3. Those chunks are assembled into a prompt together with the assistant’s persona and the conversation so far.
4. The language model writes an answer from that material and cites which chunks it used.

Two things follow from this that surprise people:

The model only sees what was retrieved. If an answer is wrong or incomplete, the usual cause is that the right chunk was never retrieved — not that the model “forgot”. Retrieval diagnostics in the dashboard show you what was actually found.

Retrieval happens per question, not per conversation. Each turn does its own lookup, which is why an assistant can move between topics without you reloading anything.

Libraries: the unit you actually manage

Sources are grouped into libraries. A library is a reusable collection of knowledge — “Product Documentation”, “2025 Course Materials”, “HR Policies” — and it exists independently of any one project.

That independence is the point:

• One library can be linked to several projects. Update it once and every assistant using it is current.
• One project can link several libraries and search across all of them.
• A library is also the permission boundary. Whether a visitor can retrieve from a library is decided per library, never per document. If they can reach a library, they can reach everything in it.

That last point should shape how you organise content. Group by who is allowed to see it and who needs different answers, not by filing-cabinet tidiness. Where different groups must see different things, see audience labels.

Distillation, briefly

Raw chunks are verbatim source text, which is ideal for precise, quotable answers. Sometimes you want the opposite: a condensed, rewritten version of an entire library that gives the assistant an overview instead of fragments.

That is distillation — Ragtime reads the whole library and produces a summarized version, optionally shaped by a lens that tells it what to emphasise. A library can then be retrieved in raw mode or distilled mode. See Distillation & Lenses.

Publishing, snapshots and devices

Editing an assistant does not change what the public sees. Publishing takes a frozen snapshot of the assistant’s configuration and makes that reachable. You can keep editing safely; the outside world stays on the last snapshot until you publish again.

A device is one surface the published assistant is served on — a website embed, a lobby kiosk, an LMS activity. Every public link points at a device, and access rules and analytics are configured per device. See the Deployment Overview.

Talking to Ragtime from your own systems

An API key authenticates a machine — a sync job, an automation, your backend — rather than a person. Keys carry scopes limiting what they may do, and can optionally be restricted to a single library. See API Keys.

Glossary

Term	Plain meaning
Project	One assistant, with its persona, knowledge and settings.
Source	One item of content: a file, a page, a document.
Chunk	A passage of a few hundred words. The unit retrieval actually works on.
Embedding	A list of numbers representing a passage’s meaning, used to find similar text.
Library	A reusable collection of sources, and the boundary that decides who may see it.
RAG	Looking up relevant passages and giving them to the model to answer from.
Retrieval	The lookup step: finding the chunks most relevant to a question.
Distillation	A condensed, rewritten version of a whole library.
Snapshot	The frozen version of an assistant that the public sees.
Device	One surface the published assistant is served on.
API key	A credential for a machine, limited by scopes.

Where to go next

• Embedding — put an assistant on your website.
• Deployment Overview — snapshots, devices, access.
• Ingest API — push content in from your own systems.
• Audience Labels — serve different groups different knowledge from one assistant.