Lmml (lmml v0.2.0)
View Sourcelmml is a markup format for talking to LLMs, designed as a strict
superset of Markdown.
A .lmml file is a self-contained narrative (Markdown-superset text).
A .lmmlz file is the same narrative packed into a zip archive
alongside the external files it references (its canonical narrative
entry is named by stripping the trailing z from the archive's own
filename, e.g. foo.lmmlz contains foo.lmml).
Both forms express the same underlying model: an ordered narrative with
zero or more named embeds, differing only in whether each embed's
content is inline (@@@name ... @@@) or external (@name, resolved
against the zip).
This top-level module is a convenience façade delegating to the focused
underlying modules: Lmml.Bundle, Lmml.Pack, Lmml.Manifest,
Lmml.Settings, and Lmml.Narrative.*.
Naming conventions for raising vs tagged tuple functions
Across the entire surface of lmml:
- Constructors and loaders (
open/1,resolve/1,pack/2,inline/2,manifest/1,settings/2) return tagged tuples{:ok, result}or{:error, reason}by default. - Bang variants (
open!/1,resolve!/1,pack!/2,inline!/2,manifest!/1,settings!/2) raise on failure. - I/O Writers (
Bundle.write!/2) raise on failure.
Summary
Functions
Returns every embed mentioned in the bundle's narrative. Delegates to Lmml.Bundle.embeds/1.
Inlines zip entries into narrative fence blocks. Delegates to Lmml.Pack.inline/2.
Same as inline/2, but raises on failure. Delegates to Lmml.Pack.inline!/2.
Loads manifest metadata from a bundle. Delegates to Lmml.Manifest.load/1.
Same as manifest/1, but raises on failure. Delegates to Lmml.Manifest.load!/1.
Returns the bundle's raw narrative text. Delegates to Lmml.Bundle.narrative/1.
Builds a bare-text bundle from narrative text. Delegates to Lmml.Bundle.new_text/2.
Builds a zip-backed bundle from narrative text plus external entries. Delegates to Lmml.Bundle.new_zip/3.
Opens a .lmml/.lmmlz entity from disk. Delegates to Lmml.Bundle.open/1.
Same as open/1, but raises on failure. Delegates to Lmml.Bundle.open!/1.
Externalizes inline embeds into a zip-backed bundle. Delegates to Lmml.Pack.pack/2.
Same as pack/2, but raises on failure. Delegates to Lmml.Pack.pack!/2.
Renders a resolved narrative into typed content parts. Delegates to Lmml.Narrative.Renderer.render/2.
Segments and renders each turn into message objects. Delegates to Lmml.Narrative.Segment.render_turns/2.
Resolves every embed a bundle's narrative mentions. Delegates to Lmml.Narrative.Resolver.resolve/1.
Same as resolve/1, but raises on failure. Delegates to Lmml.Narrative.Resolver.resolve!/1.
Splits a resolved narrative into ordered role turns. Delegates to Lmml.Narrative.Segment.segment/2.
Loads settings from a bundle. Delegates to Lmml.Settings.load/2.
Same as settings/2, but raises on failure. Delegates to Lmml.Settings.load!/2.
Exports a narrative or bundle to standard Markdown with text placeholders. Delegates to Lmml.Narrative.Renderer.to_md/2.
Cross-checks a bundle's narrative against its own entries. Delegates to Lmml.Bundle.validate/1.
Functions
@spec embeds(Lmml.Bundle.t()) :: [Lmml.Embed.t()]
Returns every embed mentioned in the bundle's narrative. Delegates to Lmml.Bundle.embeds/1.
@spec inline(Lmml.Bundle.t(), String.t() | nil) :: {:ok, Lmml.Bundle.t()} | {:error, term()}
Inlines zip entries into narrative fence blocks. Delegates to Lmml.Pack.inline/2.
@spec inline!(Lmml.Bundle.t(), String.t() | nil) :: Lmml.Bundle.t()
Same as inline/2, but raises on failure. Delegates to Lmml.Pack.inline!/2.
@spec manifest(Lmml.Bundle.t()) :: {:ok, Lmml.Manifest.t() | nil} | {:error, term()}
Loads manifest metadata from a bundle. Delegates to Lmml.Manifest.load/1.
@spec manifest!(Lmml.Bundle.t()) :: Lmml.Manifest.t() | nil
Same as manifest/1, but raises on failure. Delegates to Lmml.Manifest.load!/1.
@spec narrative(Lmml.Bundle.t()) :: binary()
Returns the bundle's raw narrative text. Delegates to Lmml.Bundle.narrative/1.
@spec new_text(String.t(), binary()) :: {:ok, Lmml.Bundle.t()} | {:error, term()}
Builds a bare-text bundle from narrative text. Delegates to Lmml.Bundle.new_text/2.
@spec new_zip(String.t(), binary(), %{optional(String.t()) => binary()}) :: {:ok, Lmml.Bundle.t()} | {:error, term()}
Builds a zip-backed bundle from narrative text plus external entries. Delegates to Lmml.Bundle.new_zip/3.
@spec open(Path.t()) :: {:ok, Lmml.Bundle.t()} | {:error, term()}
Opens a .lmml/.lmmlz entity from disk. Delegates to Lmml.Bundle.open/1.
@spec open!(Path.t()) :: Lmml.Bundle.t()
Same as open/1, but raises on failure. Delegates to Lmml.Bundle.open!/1.
@spec pack(Lmml.Bundle.t(), String.t() | nil) :: {:ok, Lmml.Bundle.t()} | {:error, term()}
Externalizes inline embeds into a zip-backed bundle. Delegates to Lmml.Pack.pack/2.
@spec pack!(Lmml.Bundle.t(), String.t() | nil) :: Lmml.Bundle.t()
Same as pack/2, but raises on failure. Delegates to Lmml.Pack.pack!/2.
@spec render(Lmml.Narrative.Resolver.t(), Lmml.Narrative.Renderer.opts()) :: [ Lmml.Narrative.Renderer.content_part() ]
Renders a resolved narrative into typed content parts. Delegates to Lmml.Narrative.Renderer.render/2.
@spec render_turns( Lmml.Narrative.Resolver.t(), keyword() ) :: [%{role: Lmml.Narrative.Segment.role(), content: [map()]}]
Segments and renders each turn into message objects. Delegates to Lmml.Narrative.Segment.render_turns/2.
@spec resolve(Lmml.Bundle.t()) :: {:ok, Lmml.Narrative.Resolver.t()} | {:error, term()}
Resolves every embed a bundle's narrative mentions. Delegates to Lmml.Narrative.Resolver.resolve/1.
@spec resolve!(Lmml.Bundle.t()) :: Lmml.Narrative.Resolver.t()
Same as resolve/1, but raises on failure. Delegates to Lmml.Narrative.Resolver.resolve!/1.
@spec segment( Lmml.Narrative.Resolver.t(), keyword() ) :: [Lmml.Narrative.Segment.t()]
Splits a resolved narrative into ordered role turns. Delegates to Lmml.Narrative.Segment.segment/2.
@spec settings(Lmml.Bundle.t(), String.t()) :: {:ok, Lmml.Settings.t() | nil} | {:error, term()}
Loads settings from a bundle. Delegates to Lmml.Settings.load/2.
@spec settings!(Lmml.Bundle.t(), String.t()) :: Lmml.Settings.t() | nil
Same as settings/2, but raises on failure. Delegates to Lmml.Settings.load!/2.
@spec to_md( Lmml.Narrative.Resolver.t() | Lmml.Bundle.t(), keyword() ) :: String.t()
Exports a narrative or bundle to standard Markdown with text placeholders. Delegates to Lmml.Narrative.Renderer.to_md/2.
@spec validate(Lmml.Bundle.t()) :: :ok | {:error, [Lmml.Bundle.validation_issue()]}
Cross-checks a bundle's narrative against its own entries. Delegates to Lmml.Bundle.validate/1.