Nous.KnowledgeBase.Store behaviour (nous v0.16.3)

Storage behaviour for knowledge base backends.

Defines callbacks for document, entry, and link CRUD operations plus search and graph traversal. Follows the same pattern as Nous.Memory.Store but with wiki-specific operations.

All list/search callbacks accept a :kb_id option for scoping.

State threading caveat

Several call sites (kb_link, persist_to_store) read store_state once and reuse it across multiple write callbacks. This is safe for backends where state is a mutable handle (the included ETS impl, any process-wrapped backend) but NOT for purely-functional stores that depend on threading the new state through every call. New backends must either:

use mutable handles in state (ETS / process registry / database connection ref), OR
implement their own concurrency control / write log (the kb code cannot guarantee atomicity across multi-step operations).

This contract may tighten in a future version; for now, prefer mutable-handle backends.

Summary

Callbacks

backlinks(state, entry_id)

delete_document(state, id)

delete_entry(state, id)

delete_link(state, id)

fetch_document(state, id)

fetch_entry(state, id)

fetch_entry_by_slug(state, slug)

init(opts)

link_counts_by_source(state)

Optional bulk callback for getting all link counts grouped by source entry.

list_documents(state, opts)

list_entries(state, opts)

outlinks(state, entry_id)

related_entries(state, entry_id, opts)

search_entries(state, query, opts)

store_document(state, doc)

store_entry(state, entry)

store_link(state, link)

update_document(state, id, updates)

update_entry(state, id, updates)

Callbacks

backlinks(state, entry_id)

@callback backlinks(state :: term(), entry_id :: String.t()) ::
  {:ok, [Nous.KnowledgeBase.Link.t()]}

delete_document(state, id)

@callback delete_document(state :: term(), id :: String.t()) ::
  {:ok, term()} | {:error, term()}

delete_entry(state, id)

@callback delete_entry(state :: term(), id :: String.t()) ::
  {:ok, term()} | {:error, term()}

delete_link(state, id)

@callback delete_link(state :: term(), id :: String.t()) ::
  {:ok, term()} | {:error, term()}

fetch_document(state, id)

@callback fetch_document(state :: term(), id :: String.t()) ::
  {:ok, Nous.KnowledgeBase.Document.t()} | {:error, :not_found}

fetch_entry(state, id)

@callback fetch_entry(state :: term(), id :: String.t()) ::
  {:ok, Nous.KnowledgeBase.Entry.t()} | {:error, :not_found}

fetch_entry_by_slug(state, slug)

@callback fetch_entry_by_slug(state :: term(), slug :: String.t()) ::
  {:ok, Nous.KnowledgeBase.Entry.t()} | {:error, :not_found}

init(opts)

@callback init(opts :: keyword()) :: {:ok, term()} | {:error, term()}

link_counts_by_source(state)

(optional)

@callback link_counts_by_source(state :: term()) ::
  {:ok, %{optional(String.t()) => non_neg_integer()}}

Optional bulk callback for getting all link counts grouped by source entry.

Backends that can answer "for every entry, how many outgoing links does it have?" with a single scan should implement this for O(L) instead of O(E*L) health checks. Falls back to per-entry outlinks/2 when not implemented (the default in the macro below). Returns {:ok, %{entry_id => count}}.

list_documents(state, opts)

@callback list_documents(state :: term(), opts :: keyword()) ::
  {:ok, [Nous.KnowledgeBase.Document.t()]}

list_entries(state, opts)

@callback list_entries(state :: term(), opts :: keyword()) ::
  {:ok, [Nous.KnowledgeBase.Entry.t()]}

outlinks(state, entry_id)

@callback outlinks(state :: term(), entry_id :: String.t()) ::
  {:ok, [Nous.KnowledgeBase.Link.t()]}

related_entries(state, entry_id, opts)

(optional)

@callback related_entries(state :: term(), entry_id :: String.t(), opts :: keyword()) ::
  {:ok, [Nous.KnowledgeBase.Entry.t()]}

search_entries(state, query, opts)

(optional)

@callback search_entries(state :: term(), query :: String.t(), opts :: keyword()) ::
  {:ok, [{Nous.KnowledgeBase.Entry.t(), float()}]}

store_document(state, doc)

@callback store_document(state :: term(), doc :: Nous.KnowledgeBase.Document.t()) ::
  {:ok, term()} | {:error, term()}

store_entry(state, entry)

@callback store_entry(state :: term(), entry :: Nous.KnowledgeBase.Entry.t()) ::
  {:ok, term()} | {:error, term()}

store_link(state, link)

@callback store_link(state :: term(), link :: Nous.KnowledgeBase.Link.t()) ::
  {:ok, term()} | {:error, term()}

update_document(state, id, updates)

@callback update_document(state :: term(), id :: String.t(), updates :: map()) ::
  {:ok, term()} | {:error, term()}

update_entry(state, id, updates)

@callback update_entry(state :: term(), id :: String.t(), updates :: map()) ::
  {:ok, term()} | {:error, term()}