Artefact (Artefact v0.1.3)

A knowledge graph fragment — a small, self-contained piece of knowledge expressed as a property graph.

The canonical form is the %Artefact{} struct. Arrows JSON and Cypher are derived representations: JSON for interchange and visual editing, Cypher for persistence.

Summary

Functions

combine(heart, other, opts \\ [])

Combine other into heart using bindings auto-found between them.

compose(a1, a2, opts \\ [])

Compose two artefacts into one. Graphs are concatenated without merging. Nodes remain disjoint; label-based relationships are implicit.

harmonise(a1, a2, bindings, opts \\ [])

Harmonise two artefacts using declared bindings.

new(attrs \\ [])

Create a new Artefact. Defaults base_label and title to the short name of the calling module. Override with title: or base_label: in attrs.

Types

t()

@type t() :: %Artefact{
  base_label: String.t() | nil,
  description: String.t() | nil,
  graph: Artefact.Graph.t(),
  id: String.t(),
  metadata: map(),
  style: atom() | nil,
  title: String.t() | nil,
  uuid: String.t()
}

Functions

combine(heart, other, opts \\ [])

(macro)

Combine other into heart using bindings auto-found between them.

Designed for pipelines — heart flows through the pipe as the first argument, so a chain of combines accumulates a single heart from many others:

me_knowing
|> Artefact.combine(me_valuing)
|> Artefact.combine(me_being)
|> Artefact.combine(me_doing, title: "MeMind", description: "Mind of Me.")

Bindings are found via Artefact.Binding.find/2 — every node sharing a uuid between heart and other becomes a binding. Raises MatchError if no bindings are found.

Internally delegates to harmonise/4, so :title and :base_label overrides in opts are honoured. :description is also accepted and applied to the result.

Records :harmonised provenance with the calling module.

compose(a1, a2, opts \\ [])

(macro)

Compose two artefacts into one. Graphs are concatenated without merging. Nodes remain disjoint; label-based relationships are implicit.

base_label defaults to the portmanteau of both artefacts' base_labels. Override with base_label: or title: in opts.

Records :composed provenance with the calling module and the metadata of both source artefacts.

harmonise(a1, a2, bindings, opts \\ [])

(macro)

Harmonise two artefacts using declared bindings.

Bound nodes are merged: lower uuid wins for identity and properties, labels are unioned. All relationships are preserved and remapped. Returns a new artefact with a portmanteau base_label unless overridden.

Records :harmonised provenance with the calling module and the metadata of both source artefacts.

new(attrs \\ [])

(macro)

Create a new Artefact. Defaults base_label and title to the short name of the calling module. Override with title: or base_label: in attrs.

Optional description: is a longer human-readable note about the artefact — surfaced as Mermaid accDescr and in the ArtefactKino inspector. Defaults to nil; pass it explicitly when you have something to say.

Records :struct provenance with the calling module.