Knowledge

KnowledgeSource

Bases: ABC

Pluggable knowledge retrieval backend.

Implement this ABC to provide external knowledge for AI context enrichment. Backends can be vector stores, search engines, document indexes, SQL databases, or any system that can answer relevance queries.

Lifecycle methods index and close are concrete no-ops so that read-only sources only need to override search.

name property

name

Human-readable source name.

search abstractmethod async

search(query, *, room_id=None, limit=5)

Search for relevant knowledge.

Parameters:

Name	Type	Description	Default
query	str	The search query text.	required
room_id	str | None	Optional room scope for filtering results.	None
limit	int	Maximum number of results to return.	5

Returns:

Type	Description
list[KnowledgeResult]	A list of :class:KnowledgeResult ordered by relevance.

index async

index(content, metadata=None)

Index new content (optional).

Knowledge sources backed by writable stores can override this to ingest new content as conversation events arrive. Called by :class:~roomkit.memory.RetrievalMemory during ingest().

close async

close()

Release resources held by the source (optional).

KnowledgeResult dataclass

KnowledgeResult(content, score=0.0, source='', metadata=dict())

A single result from a knowledge source search.

Attributes:

Name	Type	Description
content	str	The retrieved text content.
score	float	Relevance score (higher is better). Used for ranking and deduplication when multiple sources return results.
source	str	Human-readable source identifier (e.g. "faq-db", "product-docs").
metadata	dict[str, Any]	Arbitrary metadata (document ID, chunk index, etc.).

MockKnowledgeSource

MockKnowledgeSource(results=None)

Bases: KnowledgeSource

Records calls and returns configured results.

Example::

source = MockKnowledgeSource(
    results=[KnowledgeResult(content="Paris is the capital", score=0.95)],
)
results = await source.search("capital of France")
assert len(source.search_calls) == 1