kbforge

Build an Amazon Bedrock knowledge base from a notebook.

Describe what you want in one line of Python. kbforge checks your setup, shows you exactly what it will create, and builds it only when you say so.

%pip install -q "kbforge @ git+https://github.com/utkarsh5026/bedrcok.git"

A tour of under two minutes, recorded from real kbforge output against a simulated AWS account. Click the video to pause. Download as MP4 · Full screen

What it builds

A knowledge base is a search index over your own documents that matches on meaning rather than exact words. Chat assistants use one to find the right passages before they answer. Getting there takes five steps, and five AWS resources:

DocumentsPDF, Word, Excel, HTML, Markdown in an S3 bucket
ChunksEach file split into short passages
EmbeddingsEach passage turned into a vector by a Bedrock model
Vector storeVectors stored so similar meanings are found quickly
RetrievalA question returns the closest passages

Wiring that up by hand means an IAM role with the right policy, a vector bucket and index, the knowledge base, a data source, and an ingestion job, each with its own waiting and failure modes. kbforge does it in order, explains any error in plain English, and can be safely re-run.

Before you start

Documents in S3

In the region you'll build in. PDF, Word, Excel, CSV, HTML, Markdown and plain text all work. A public website can be crawled instead.

A role that can build

Your SageMaker role needs access to Bedrock, S3 Vectors and IAM: copy the ready-made policy. If IAM is locked down, ask an admin for a Bedrock role and pass it as role_arn=.

Four cells

After installing, this is the whole thing. Each line is explained below.

from kbforge import KnowledgeBase

kb = KnowledgeBase("hr-policies", source="s3://my-company-docs/hr/")
kb.plan()
kb.apply()
kb.ask("How many weeks of parental leave do we get?")
  1. DescribeA name and a source. No AWS calls yet.
  2. PlanChecks and a list of what will be created. Changes nothing.
  3. BuildCreates everything, with live progress.
  4. AskShows which passages come back for a question.

What each step shows

Every call draws a card under the cell. Click a screenshot to open it full size.

Step 1

Describe what you want

kb = KnowledgeBase(
    "hr-policies",
    source="s3://my-company-docs/hr/",
)
kb

Give it a name and a source. Everything else (the AI model, the storage, how files are split) has a sensible default you can change later.

This doesn't touch AWS. It just shows the pipeline it's going to set up.

A card showing the data flow: source, chunking, embeddings, vector store, knowledge base
Step 2

Read the plan

kb.plan()

Think of it as a preview. It's read-only, so run it as often as you like. It checks your credentials, that the AI model works for you, and what's in your bucket. Then it lists every AWS resource it would create, by name.

create will be made
exists already there
update will be adjusted
blocked fix this first
Full plan card: summary, data flow, four preflight checks and six numbered steps with CREATE and RUN badges
If something's wrong

Problems are caught before anything is built

A typo in the bucket name, a model you don't have access to, the wrong region: the plan turns red, says what to do, and apply() refuses to start. Nothing is ever half-built.

Fix it, run kb.plan() again, carry on. Common fixes are on the help page.

A plan with a red Blocked banner: the source bucket finanse-reports doesn't exist
Step 3

Build it

kb.apply()

The card updates live as each piece is created, so the cell never looks frozen. A fresh build takes a few minutes, mostly for the first sync of your documents.

At the end you get a Ready card with the IDs and the code your applications need.

Stopped halfway? The card explains the error in plain English. Fix it and run kb.apply() again: finished steps are skipped.
Progress card mid-run: five steps done with timings, the ingestion step spinning with a live status line
While it works.
Finished build: all six steps ticked, then a Ready card with the knowledge base ID, data source ID and example code
When it's done.
Step 4

Ask it something

kb.ask("How many weeks of parental leave?")

You'll see the passages that match best, with a score and the file each came from. If the right passages come back, your knowledge base is ready to plug into a chatbot or app.

Want a written answer too? kb.ask("…", answer=True) has a model answer from those passages, with numbered citations to each one it used.

Three retrieved chunks with relevance bars, scores and the S3 path of each source document
Just the passages.
A written answer about parental leave with numbered citation markers, followed by the two cited source passages
With answer=True: a written answer that cites them.
Afterwards

Keep it fresh, or clean it up

kb = KnowledgeBase.open("hr-policies")   # in a new notebook
kb.sync()                  # documents changed
kb.status()                # is everything healthy?
kb.destroy()               # preview the delete
kb.destroy(confirm=True)   # actually delete

Forgot the name? kbforge.knowledge_bases() lists every one kbforge built in the region. destroy() only removes what kbforge created. Your documents are never touched.

Status card: knowledge base ID, region, embedding model, vector store, data source and last sync
How one is doing.
Table of three knowledge bases built by kbforge, with status, source, last sync and model, plus a KnowledgeBase.open example
Everything kbforge built in the region.

Other ways to run it

The same describe, plan, build flow without writing Python.

import kbforge
kbforge.wizard()

A form for the same three stages. Each answer is checked as you type, and the choices with trade-offs (embedding model, vector store, chunking) are cards that say when to pick each one. A side panel shows the data flow and the exact AWS names kbforge will use.

Click Review plan, then Build it. The build button only unlocks when nothing is blocked.

Show as code gives you the equivalent Python and YAML, so you can graduate to a saved config later.

The wizard: a stepper header, numbered sections with option cards for documents, embedding model, vector store and chunking, and a live preview panel on the right
The wizard after building: every stage ticked, the progress card, the ready card and a Try it box for asking questions
After building, a "Try it" box lets you ask a question straight away.