.. _knowledge_bases:

Knowledge Bases
===============

.. contents:: On this page
   :local:
   :depth: 2

A **knowledge base** is a collection of source documents that AI tools draw on to answer
questions, generate content, and grade submissions. Knowledge bases power the
:ref:`AI Expert Chat <ai_expert_chat>` and the AI features of :ref:`Free Text <free_text>`.

You manage knowledge bases from **Knowledge Bases** in the workspace sidebar.

Creating a knowledge base
-------------------------

#. Open **Knowledge Bases** and create a new one.
#. Give it a clear name describing its scope (for example "Biology 101 Course Notes").
#. Optionally set **default chunking settings**, which control how documents are split for AI
   retrieval. The defaults are a good starting point.

Adding sources
--------------

A **source** is a document added to a knowledge base. To add one:

#. Open the knowledge base and add a **source** (for example, upload a PDF).
#. Optionally **override the chunking settings** for that source — but only **before the source
   has been created in the backend** for the first time.
#. Save. Control returns to the workspace immediately while Blocks finishes processing in the
   background.

Processing and syncing
----------------------

After you add a file source, Blocks does some work before the content is searchable:

* **Pre-processing** — uploaded files (such as PDFs) are converted into clean Markdown ingest
  artifacts, stored alongside the original. During PDF pre-processing, obvious plain-text math is
  conservatively upgraded into MathJax-ready notation.
* **Token estimation** — Blocks estimates the size of the content for usage planning.

While a source shows the **pre-processing** state, you cannot start a source-level or whole
knowledge base **sync**. Once pre-processing clears, sync the source (or the whole knowledge
base) to make it available to AI tools.

.. note::

   You can **stop** an active pre-processing or sync operation. Stopping revokes the background
   work, removes intermediate artifacts, and restores the source to its last stable state.

Using a knowledge base in a tool
--------------------------------

Once a knowledge base is synced, select it when authoring an :ref:`AI Expert Chat
<ai_expert_chat>` or when enabling AI generation or AI grading on a :ref:`Free Text <free_text>`
assignment.

Plan limits and credits
-----------------------

The number of knowledge bases and sources your workspace may create depends on your subscription
plan. AI operations that use a knowledge base consume :ref:`credits <billing>`. See
:ref:`usage_reports` to monitor consumption.

`Back to Home <index.html>`_