Knowledge Module

The knowledge module provides document storage and hybrid semantic/full-text search for RAG.

Import

from bifrost import knowledge

Methods

knowledge.store()

Store a document with automatic embedding.

async def store(
    content: str,
    *,
    namespace: str = "default",
    key: str | None = None,
    metadata: dict[str, Any] | None = None,
    scope: str | None = None,
) -> str

Parameters

Parameter	Type	Description
content	str	Document text to store
namespace	str	Namespace for organization (default: “default”)
key	str	Unique key for upsert behavior
metadata	dict	Arbitrary metadata
scope	str | None	Organization scope (see below)

Scope parameter:

• (omitted) (default): Use execution context’s org, with automatic global fallback via cascade
• Org UUID string: Target specific organization (provider orgs only)
• None explicitly: Target global scope directly (visible to all orgs)

Note: Targeting a specific org via UUID requires provider org context. Managed orgs can only access their own scope. Use context.set_scope() to override scope for all calls at once.

Returns

Document ID string.

Example

doc_id = await knowledge.store(
    "Our refund policy allows returns within 30 days.",
    namespace="policies",
    key="refund-policy",
    metadata={"version": "2.0"}
)

knowledge.store_many()

Batch store multiple documents.

async def store_many(
    documents: list[dict[str, Any]],
    *,
    namespace: str = "default",
    scope: str | None = None,
) -> list[str]

Parameters

Parameter	Type	Description
documents	list[dict]	List of {content, key?, metadata?}
namespace	str	Namespace for all documents
scope	str | None	Organization scope (see above)

Example

docs = [
    {"content": "Doc 1...", "key": "doc-1"},
    {"content": "Doc 2...", "metadata": {"type": "faq"}}
]
ids = await knowledge.store_many(docs, namespace="docs")

knowledge.search()

Hybrid semantic and full-text search across documents.

async def search(
    query: str,
    *,
    namespace: str | list[str] = "default",
    limit: int = 5,
    min_score: float | None = None,
    metadata_filter: dict[str, Any] | None = None,
    scope: str | None = None,
    fallback: bool = True,
) -> list[KnowledgeDocument]

Parameters

Parameter	Type	Description
query	str	Search query
namespace	str | list	Namespace(s) to search
limit	int	Max results (default: 5)
min_score	float	Minimum similarity score (0-1)
metadata_filter	dict	Filter by metadata fields
scope	str | None	Organization scope (see above)
fallback	bool	Also search global scope (default: True)

Returns

List of KnowledgeDocument objects sorted by fused relevance.

Example

results = await knowledge.search(
    "refund policy",
    namespace=["policies", "faq"],
    limit=10
)
for doc in results:
    print(f"{doc.score:.2f}: {doc.content[:100]}")

# With metadata filter
results = await knowledge.search(
    "password reset",
    namespace="tickets",
    metadata_filter={"status": "open"},
    min_score=0.7
)

knowledge.list_namespaces()

List all namespaces with document counts.

async def list_namespaces(
    scope: str | None = None,
    include_global: bool = True,
) -> list[NamespaceInfo]

Parameters

Parameter	Type	Description
scope	str | None	Organization scope (see above)
include_global	bool	Include global namespaces (default: True)

Example

namespaces = await knowledge.list_namespaces()
for ns in namespaces:
    print(f"{ns.namespace}: {ns.scopes['total']} docs")

knowledge.get()

Get a document by key.

async def get(
    key: str,
    *,
    namespace: str = "default",
    scope: str | None = None,
) -> KnowledgeDocument | None

Parameters

Parameter	Type	Description
key	str	Document key
namespace	str	Namespace to search in
scope	str | None	Organization scope (see above)

Example

doc = await knowledge.get("refund-policy", namespace="policies")
if doc:
    print(doc.content)

knowledge.delete()

Delete a document by key.

async def delete(
    key: str,
    *,
    namespace: str = "default",
    scope: str | None = None,
) -> bool

Parameters

Parameter	Type	Description
key	str	Document key to delete
namespace	str	Namespace containing the document
scope	str | None	Organization scope (see above)

Example

deleted = await knowledge.delete("ticket-123", namespace="tickets")

knowledge.delete_namespace()

Delete all documents in a namespace.

async def delete_namespace(
    namespace: str,
    *,
    scope: str | None = None,
) -> int

Parameters

Parameter	Type	Description
namespace	str	Namespace to delete
scope	str | None	Organization scope (see above)

Returns

Number of documents deleted.

Example

count = await knowledge.delete_namespace("old-data")
print(f"Deleted {count} documents")

Types

KnowledgeDocument

class KnowledgeDocument(BaseModel):
    id: str
    namespace: str
    content: str
    metadata: dict | None
    score: float | None        # Similarity score (0-1)
    organization_id: str | None
    key: str | None
    created_at: datetime | None

NamespaceInfo

class NamespaceInfo(BaseModel):
    namespace: str
    scopes: dict   # {"global": N, "org": N, "total": N}

Scopes

Documents can be scoped:

Scope	Description
org	Only visible to the storing organization (default)
global	Visible to all organizations

Search returns both global and org-specific documents automatically when fallback=True.

See Also

• Knowledge Bases - Usage guide
• AI Module - Using knowledge with completions