Struct KnowledgeChatRuntime 

pub struct KnowledgeChatRuntime { /* private fields */ }

A real, knowledge-grounded chat runtime over smooth-operator.

This is the first end-to-end “knowledge-chat turn” for smooth-operator: it wires a StorageAdapter’s KnowledgeBase into a smooth-operator Agent two ways —

1. Auto-injected context via AgentConfig::with_knowledge: the engine queries the KB with the user’s message and prepends the top matches as a [Relevant knowledge] system message before the first LLM call.
2. Agent-driven search via the KnowledgeSearchTool: the model can issue its own knowledge_search query mid-turn with its own phrasing.

Construct with KnowledgeChatRuntime::new for production (a real LlmClient is built from the LlmConfig), or inject a mock via KnowledgeChatRuntime::with_llm_provider for deterministic, key-free tests.

Implementations

impl KnowledgeChatRuntime

pub fn new(storage: Arc<dyn StorageAdapter>, llm: LlmConfig) -> Self

Build a production runtime over a storage adapter and LLM config.

pub fn with_curation( self, store: CuratedKnowledgeStore, context: AccessContext, filter: RetrievalFilter, ) -> Self

Enable query-time curation for this runtime (Phase 11): scope retrieval to named document sets / metadata equalities and re-rank by per-document boost.

store is a CuratedKnowledgeStore wrapping the same inner KnowledgeBase the documents were ingested through (so its curation + ACL side tables are populated), context is the requester’s identity (ACL ∧ curation both apply — the curated store enforces document-level access control itself), and filter scopes the reads. Both the auto-injected [Relevant knowledge] context and the knowledge_search tool read through this filtered, boosted reader.

Pass RetrievalFilter::none to apply boost re-ranking with no set/metadata scoping. Without calling this, retrieval is unchanged.

pub fn with_retrieval_filter(self, filter: RetrievalFilter) -> Self

Set (or replace) just the RetrievalFilter on an already-configured curation store, so a per-turn scope can be applied without rebuilding the store. No-op (logs nothing) when curation is not configured.

pub fn with_access_control( self, store: AclKnowledgeStore, context: AccessContext, ) -> Self

Enable document-level access control for this runtime (feature gap G3).

store is an AclKnowledgeStore that wraps the same inner KnowledgeBase the documents were ingested through (so its ACL side table is populated), and context is the requester’s identity. With this set, every turn reads knowledge through an AccessContext-bound reader — both the auto-injected [Relevant knowledge] context and the knowledge_search tool drop documents the requester is not entitled to.

Without it, the runtime reads the raw storage.knowledge() exactly as before (backward-compatible — existing no-ACL knowledge stays retrievable).

pub fn with_llm_provider(self, provider: Arc<dyn LlmProvider>) -> Self

Inject a custom LlmProvider (e.g. a MockLlmClient) so the agent loop runs deterministically with no network / API key. This is the test seam.

pub fn with_max_iterations(self, max: u32) -> Self

Cap on agent loop iterations (LLM call → tool calls → LLM call → …). Defaults to 8.

pub async fn run_turn( &self, conversation_id: &str, user_message: &str, ) -> Result<TurnOutcome>

Run one knowledge-grounded turn.

Drives the smooth-operator agent loop to completion, then returns the final assistant text plus every AgentEvent emitted. The inbound user message and the outbound reply are also persisted to the storage adapter’s message log under conversation_id (best-effort: a persist failure surfaces as an error so callers don’t silently lose history).

Errors

Returns an error if the agent loop fails fatally or message persistence fails.