Documentation Index
Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
| Field | Type | Description |
|---|
id | str | KB identifier. |
name | str | Display name. |
description | str | None | Description. |
type | KnowledgeBaseType | MANAGED (xpander.ai vector store) or EXTERNAL. |
organization_id | str | Owning org. |
total_documents | int | Document count. |
configuration | Configuration | None | SDK 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)
| Parameter | Type | Required | Default | Description |
|---|
document_urls | list[str] | Yes | – | URLs to ingest. |
sync | bool | No | False | When True, the platform synchronously waits for indexing before returning. |
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()
list[KnowledgeBaseDocumentItem].
KnowledgeBaseDocumentItem fields:
| Field | Type | Description |
|---|
kb_id | str | None | Owning KB id. |
id | str | None | Document id. |
document_url | str | URL the platform ingested. |
raw_data | str | None | Inline 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"])
| Parameter | Type | Required | Description |
|---|
document_ids | list[str] | Yes | Document ids to delete. |
await doc.delete() on a KnowledgeBaseDocumentItem returned by alist_documents.
asearch / search
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]}")
| Parameter | Type | Required | Default | Description |
|---|
search_query | str | Yes | – | Natural-language query. |
use_bubble | bool | No | False | When 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_size | int | No | 1000 | Width of the surrounding bubble in characters when use_bubble=True. |
top_k | int | No | 10 | Max number of results. |
list[KnowledgeBaseSearchResult]:
| Field | Type | Description |
|---|
content | str | Matching text (with bubble context if enabled). |
score | float | Relevance score (0.0–1.0). |
adelete / delete
Delete the entire knowledge base.
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.
