> ## 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 class

> Add, list, search, and delete documents in a knowledge base.

`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.

```python theme={"dark"}
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.

```python theme={"dark"}
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. |

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.

```python theme={"dark"}
docs = await kb.alist_documents()
```

Returns `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.

```python theme={"dark"}
await kb.adelete_multiple_documents(document_ids=["doc-123", "doc-456"])
```

| Parameter      | Type        | Required | Description             |
| -------------- | ----------- | -------- | ----------------------- |
| `document_ids` | `list[str]` | Yes      | Document ids to delete. |

To delete a single document, you can also call `await doc.delete()` on a `KnowledgeBaseDocumentItem` returned by `alist_documents`.

### `asearch` / `search`

Semantic search over the KB. Returns top-K matches by score.

```python theme={"dark"}
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.                                                                                                                                                                                              |

Returns `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.

```python theme={"dark"}
await kb.adelete()
```

This is irreversible. The KB and all its documents are removed.

## Examples

### Bulk-add and verify

```python theme={"dark"}
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

```python theme={"dark"}
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)

```python theme={"dark"}
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`](/developers/sdk-reference/error-handling) on API failures.