Gralkor.Generalisation (jido_gralkor v6.0.0)

Copy Markdown View Source

Struct and wire format for generalisations stored as graphiti episodes in a dedicated group ("#{group_id}_gen").

The struct :id identifies the generalisation inside the episode body, which is what :generalises points at when one generalisation supersedes another. It is not the graphiti episode UUID: graphiti mints those, and its add_episode(uuid: …) parameter loads an existing episode to re-extract rather than creating one under an id we chose.

Wire format

Episode content uses a single-line metadata prefix followed by the free-text generalisation:

GEN|v1|{"id":"abc123","level":2,"confidence":0.85,"generalises":["def456"]}
Eli prefers concise, structured responses by default.

The prefix is part of the episode body, so a generalisation stays parseable on read — but only through an episode search, which returns that body. Edge and node search return what an extractor derived from it, and no derived text carries the prefix.

See test-trees/unit/generalisation_TEST_TREES.md.

Summary

Types

t()

Functions

decode(raw)

Decodes a stored episode body (from a graphiti episode search) into a %Generalisation{} struct and the plain content.

encode(gen)

Encodes a %Generalisation{} struct into an episode body string suitable for GraphitiPool.add_episode/5. The returned string has the metadata prefix as its first line, followed by the free-text content.

Types

t()

@type t() :: %Gralkor.Generalisation{
  confidence: float(),
  content: String.t(),
  created_at: String.t() | nil,
  generalises: [String.t()],
  id: String.t(),
  level: non_neg_integer()
}

Functions

decode(raw)

@spec decode(String.t()) :: {:ok, t(), String.t()} | {:error, :not_a_generalisation}

Decodes a stored episode body (from a graphiti episode search) into a %Generalisation{} struct and the plain content.

Returns {:ok, %Generalisation{}, plain_content} on success, {:error, :not_a_generalisation} for strings without the prefix, or raises GeneralisationParseFailed for malformed metadata.

encode(gen)

@spec encode(t()) :: String.t()

Encodes a %Generalisation{} struct into an episode body string suitable for GraphitiPool.add_episode/5. The returned string has the metadata prefix as its first line, followed by the free-text content.