Gralkor.Search (jido_gralkor v11.0.0)

Copy Markdown View Source

A search across registered memory Destinations.

With empty destinations and lenses, search reads episodes from every accessible registered Destination and from direct capture and every Lens and Reflection writer. The packaged personal Destination resolves only to the current operator_id's graph.

destinations selects graphs and lenses filters episode writers. Names are ORed within either list and the two dimensions are ANDed together. Lens filtering is valid for episode and fact results. Direct episodes expose content, source_description, source_kind, and writer: :direct without Lens or Reflection authorship. Historical unmarked episodes remain available without invented authorship; historical operator Lens provenance is preserved but never matched by a personal-chat Lens selector. A Lens-written episode exposes content, source_description, and lens; a Reflection-written episode exposes artefact: %{id: id, payload: payload}, source_description, and its writer as reflection. Reflection episodes have no encoded content. Naturally textual Lens content remains text, including JSON-looking source records. Facts retain their text, timestamps, and structured sources with named Lens or Reflection provenance where available. Lens selection filters matching edges before the result limit and retains only selected Lens sources. Use Gralkor.Format.format_fact/1 explicitly for readable fact presentation.

Episodes are the default result type. Facts, nodes, and Reflection artefacts remain available by explicitly setting result_type to :facts, :nodes, or :artefacts.

Summary

Types

direct_episode()
lens_episode()
reflection_episode()
result()
result_type()

The requested representation; episodes are the public default.

t()

One search request.

Types

direct_episode()

@type direct_episode() :: %{
  :content => String.t(),
  :source_description => String.t(),
  optional(:source_kind) => String.t(),
  optional(:writer) => :direct
}

lens_episode()

@type lens_episode() :: %{
  content: String.t(),
  source_description: String.t(),
  lens: String.t()
}

reflection_episode()

@type reflection_episode() :: %{
  artefact: %{id: String.t(), payload: map()},
  source_description: String.t(),
  reflection: String.t()
}

result()

@type result() ::
  %{
    destination: String.t(),
    episode: direct_episode() | lens_episode() | reflection_episode()
  }
  | %{destination: String.t(), fact: map()}
  | %{destination: String.t(), node: map()}
  | %{destination: String.t(), artefact: Gralkor.Artefact.t()}

result_type()

@type result_type() :: :facts | :nodes | :episodes | :artefacts

The requested representation; episodes are the public default.

t()

@type t() :: %Gralkor.Search{
  artefact_id: String.t() | nil,
  destinations: [String.t()],
  edge_types: [String.t()],
  entity_types: [String.t()],
  lenses: [String.t()],
  max_results: pos_integer(),
  operator_id: String.t(),
  query: String.t(),
  result_type: result_type()
}

One search request.

Empty selector lists mean all accessible Destinations and all episode writers. entity_types, edge_types, and artefact_id apply only to their corresponding explicit advanced result types. max_results applies independently to each selected Destination.