Skip to main content
KnowledgeBase is the instance you get back from KnowledgeBases.aget, acreate, or alist. It carries the KB metadata and the methods to populate, query, and tear it down. 
from xpander_sdk import KnowledgeBases

kb = await KnowledgeBases().aget("kb-456")
print(kb.id, kb.name, kb.total_documents)

​
Attributes

FieldTypeDescription
idstrKB identifier.
namestrDisplay name.
descriptionstr | NoneDescription.
typeKnowledgeBaseTypeMANAGED (xpander.ai vector store) or EXTERNAL.
organization_idstrOwning org.
total_documentsintDocument count.
configurationConfiguration | NoneSDK config (carried from the loader).

​
Methods

​
aadd_documents / add_documents

Upload documents by URL. The platform fetches the URLs, chunks the content, embeds it, and indexes the embeddings. 
docs = await kb.aadd_documents([
    "https://example.com/policy.pdf",
    "https://example.com/handbook.md",
])
for d in docs:
    print(d.id, d.document_url)
ParameterTypeRequiredDefaultDescription
document_urlslist[str]Yes–URLs to ingest.
syncboolNoFalseWhen True, the platform synchronously waits for indexing before returning.
Returns list[KnowledgeBaseDocumentItem]: one entry per uploaded document with the platform-assigned id and the document_url.

​
alist_documents / list_documents

List all documents in the KB. 
docs = await kb.alist_documents()
Returns list[KnowledgeBaseDocumentItem]. KnowledgeBaseDocumentItem fields:
FieldTypeDescription
kb_idstr | NoneOwning KB id.
idstr | NoneDocument id.
document_urlstrURL the platform ingested.
raw_datastr | NoneInline raw text, if it was uploaded directly.

​
adelete_multiple_documents / delete_multiple_documents

Delete documents by id. 
await kb.adelete_multiple_documents(document_ids=["doc-123", "doc-456"])
ParameterTypeRequiredDescription
document_idslist[str]YesDocument ids to delete.
To delete a single document, you can also call await doc.delete() on a KnowledgeBaseDocumentItem returned by alist_documents. Semantic search over the KB. Returns top-K matches by score. 
results = await kb.asearch(
    search_query="how do we handle PII?",
    top_k=5,
)
for r in results:
    print(f"{r.score:.2f}  {r.content[:100]}")
ParameterTypeRequiredDefaultDescription
search_querystrYes–Natural-language query.
use_bubbleboolNoFalseWhen False, each result is just the matched chunk (the indexed text segment). When True, the SDK widens each result with surrounding text from the source document (a “bubble” of context) for richer snippets.
bubble_sizeintNo1000Width of the surrounding bubble in characters when use_bubble=True.
top_kintNo10Max number of results.
Returns list[KnowledgeBaseSearchResult]:
FieldTypeDescription
contentstrMatching text (with bubble context if enabled).
scorefloatRelevance score (0.0–1.0).

​
adelete / delete

Delete the entire knowledge base. 
await kb.adelete()
This is irreversible. The KB and all its documents are removed.

​
Examples

​
Bulk-add and verify

docs = await kb.aadd_documents([
    f"https://docs.acme.com/handbook/{slug}.md"
    for slug in ["onboarding", "policies", "engineering"]
])

assert len(docs) == 3
print(f"Added {len(docs)} documents to {kb.name}")

​
Search with context

results = await kb.asearch(
    search_query="vacation policy",
    use_bubble=True,
    bubble_size=2000,
    top_k=3,
)

for r in results:
    print(f"--- score: {r.score:.2f} ---")
    print(r.content)
use_bubble=True is great for human-readable snippets; for embedding into LLM prompts, the default False (chunk-only) is usually enough.

​
Reindex (delete + re-add)

docs = await kb.alist_documents()
ids = [d.id for d in docs]
await kb.adelete_multiple_documents(document_ids=ids)

await kb.aadd_documents([d.document_url for d in docs], sync=True)
sync=True blocks until reindexing finishes, so the KB is queryable when the call returns.

​
Errors

All KB methods raise ModuleException on API failures.