@callback concept_prompt_task_section_title() :: binary()

A callback that returns the title of the "Artefacts" subsection for this type of matter in the Magma.Concept document where for the text returned by the request_prompt_task/1 callback is rendered.

By default, this is just the concept_section_title/0 with "prompt task" appended.

@callback concept_section_title() :: binary()

A callback that returns the title of the "Artefacts" subsection for this type of matter in the Magma.Concept document.

This section consists of links to the Magma.Artefact.Prompt and the Magma.Artefact.Version of this document and another subsection for the text returned by the request_prompt_task/1 callback.

@callback context_knowledge(Magma.Concept.t()) :: binary() | nil

A callback that allows to specify texts which should be included generally in the "Context knowledge" section of the Magma.Artefact.Prompt document about this type of artefact.

@callback create_version(
  Magma.Artefact.Version.t(),
  keyword()
) :: {:ok, Path.t() | Magma.Artefact.Version.t()} | {:error, any()} | nil

A callback that allows to implement a custom Magma.Artefact.Version document creation function.

This function should return nil if the default Magma.Artefact.Version.create/2 should be used (which the default implementation does automatically).

@callback default_name(Magma.Concept.t()) :: binary() | nil

A callback that returns the name of an artefact to be used as default for the :name field.

@callback new(Magma.Concept.t()) :: {:ok, t()} | {:error, any()}

A callback that creates a new instance of a type of artefact with the default name.

@callback new(
  Magma.Concept.t(),
  keyword()
) :: {:ok, t()} | {:error, any()}

A callback that creates a new instance of a type of artefact.

@callback prompt_name(t()) :: binary()

A callback that returns the name of the Magma.Artefact.Prompt document for this type of matter.

@callback relative_base_path(t()) :: Path.t()

A callback that returns the general path segment to be used for documents for this type of artefact.

@callback relative_prompt_path(t()) :: Path.t()

A callback that returns the path for Magma.Artefact.Prompt documents about this type of artefact.

Since the Magma.PromptResult document are always stored in the subdirectory where the prompt are stored, this function also determines their path.

This path is relative to the Magma.Vault.artefact_generation_path/0.

@callback relative_version_path(t()) :: Path.t()

A callback that returns the path for Magma.Artefact.Version documents about this type of artefact.

This path is relative to the Magma.Vault.artefact_version_path/0.

@callback request_prompt_task(Magma.Concept.t()) :: binary()

A callback that returns the request prompt text of the Magma.Artefact.Concept document for this type of matter that describes what to generate.

Despite returning also a general text like the system_prompt_task/1, this one is included in the "Artefacts" section of the Magma.Concept document (and only transcluded in Magma.Artefact.Prompt document), so that the user has a chance to adapt it for a specific instance of this artefact type.

The generated default implementation returns the content of the "Task prompt" section of the respective artefact config document, after EEx evaluation with the bindings returned by request_prompt_task_template_bindings/1.

@callback request_prompt_task_template_bindings(Magma.Concept.t()) :: keyword()

A callback that returns the bindings to be applied when rendering the request_prompt_task/1 EEx template.

@callback system_prompt_task(Magma.Concept.t()) :: binary()

A callback that returns the system prompt text of the Magma.Artefact.Prompt document for this type of matter that describes what to generate.

As opposed to the request_prompt_task/1 this is a general, static text used by artefacts of this type.

The generated default implementation returns a transclusion of the "System prompt" section of the respective artefact config document.

@callback trim_prompt_result_header?() :: boolean()

A callback that returns if the initial header of a generated Magma.PromptResult for this type artefact should be stripped.

Since the title for the Magma.PromptResult is already defined, the title generated by an LLM should be ignored usually. For some types of artefacts, however, this should not be the case. These artefact types, the default implementation returning true, can be overwritten.

@callback version_prologue(Magma.Artefact.Version.t()) :: binary() | nil

A callback that allows to specify a text which should be included in the prologue of the Magma.Artefact.Version document of this artefact type.

@callback version_title(Magma.Artefact.Version.t()) :: binary()

A callback that returns the title to be used for the Magma.Artefact.Version document.