PtcRunner.Lisp.LanguageSpec (PtcRunner v0.10.0)

Language specification compositions for PTC-Lisp.

Provides pre-composed language specs built from two axes plus optional capabilities:

Behavior axis: :single_shot, :explicit_return
Reference: Optional language reference (tool syntax, Java interop, restrictions)
Capabilities: :journal (task caching, semantic progress)

Compositions include the language reference by default. Use {:profile, behavior, reference: :none} to omit it for capable models.

Compositions

Key	Description
`:single_shot`	Last expr = answer, one turn
`:explicit_return`	Multi-turn, must call `(return ...)`/`(fail ...)`
`:explicit_journal`	Explicit return + journal (task/step-done)

Structured Profiles

For programmatic composition, use resolve_profile/1 with a tuple:

# Omit language reference for capable models
LanguageSpec.resolve_profile({:profile, :explicit_return, reference: :none})

# Add journal capability
LanguageSpec.resolve_profile({:profile, :explicit_return, journal: true})

Usage

# For single-turn queries
PtcRunner.Lisp.LanguageSpec.get(:single_shot)

# For multi-turn conversations
PtcRunner.Lisp.LanguageSpec.get(:explicit_return)

# Raw snippets for custom compositions
PtcRunner.Lisp.LanguageSpec.get(:reference) <> my_custom_addon

Summary

Functions

get(key)

Get a prompt by key.

get!(key)

Get a prompt by key, raising if not found.

list()

List all available prompt keys.

list_with_descriptions()

List all prompts with descriptions.

metadata(key)

Get full metadata for a prompt.

resolve_profile(profile)

Resolve a structured prompt profile to a composed prompt string.

version(key)

Get the version number for a prompt.

Functions

get(key)

@spec get(atom()) :: String.t() | nil

Get a prompt by key.

Supports both raw snippets (:reference, :behavior_multi_turn) and compositions (:single_shot, :explicit_return).

Examples

iex> prompt = PtcRunner.Lisp.LanguageSpec.get(:single_shot)
iex> is_binary(prompt)
true

iex> prompt = PtcRunner.Lisp.LanguageSpec.get(:explicit_return)
iex> String.contains?(prompt, "<state>")
true

get!(key)

@spec get!(atom()) :: String.t()

Get a prompt by key, raising if not found.

Examples

iex> prompt = PtcRunner.Lisp.LanguageSpec.get!(:single_shot)
iex> is_binary(prompt)
true

list()

@spec list() :: [atom()]

List all available prompt keys.

Examples

iex> keys = PtcRunner.Lisp.LanguageSpec.list()
iex> :single_shot in keys
true
iex> :explicit_return in keys
true

list_with_descriptions()

@spec list_with_descriptions() :: [{atom(), String.t()}]

List all prompts with descriptions.

Returns a list of {key, description} tuples.

Examples

iex> list = PtcRunner.Lisp.LanguageSpec.list_with_descriptions()
iex> Enum.any?(list, fn {k, _} -> k == :single_shot end)
true

metadata(key)

@spec metadata(atom()) :: map()

Get full metadata for a prompt.

Returns a map with metadata keys like :version, :date, :changes. For compositions, returns metadata of the first component.

Examples

iex> meta = PtcRunner.Lisp.LanguageSpec.metadata(:reference)
iex> is_map(meta)
true

resolve_profile(profile)

@spec resolve_profile(atom() | {:profile, atom()} | {:profile, atom(), keyword()}) ::
  String.t()

Resolve a structured prompt profile to a composed prompt string.

Accepts either an atom (delegates to get!/1) or a tuple for structured composition:

# Atom form (existing)
resolve_profile(:explicit_return)

# Tuple form with options
resolve_profile({:profile, :explicit_return, reference: :full, journal: true})

Options

:reference - :full (default) or :none
:journal - true or false (default)

Validation

Raises ArgumentError for:

Unknown behavior (must be :single_shot or :explicit_return)
journal: true with :single_shot (single-shot skips the loop)
Unknown reference value (must be :full or :none)
Unknown option keys

version(key)

@spec version(atom()) :: pos_integer()

Get the version number for a prompt.

Returns the version from the prompt's metadata, or 1 if not specified. For compositions, returns the version of the first component.