arioso.named_prompts#

Named prompts: a ledger of (name, prompt_text) pairs organized by category.

Provides a system for looking up sonic descriptions by name (artist, mood, genre, instrument, etc.) to help users craft prompts for AI music generation without using restricted names.

The system has two layers:

Starter data: ships with arioso in arioso/data/named_prompts/*.yaml
User data: stored in ~/.local/share/arioso/named_prompts/*.yaml

User data overlays starter data, so users can extend or override entries.

Usage:

>>> from arioso.named_prompts import named_prompts, search
>>> named_prompts.artists['billie_eilish']  # attribute access by category
'...'
>>> named_prompts['artists', 'billie_eilish']  # flat key access
'...'
>>> results = search('jazz')  # search across all categories

Functions

`add_prompt`(category, name, prompt_text, *[, ...])	Add or update a prompt in the user's data.
`get_named_prompts`()	Return a module-level singleton `NamedPrompts` instance.
`remove_prompt`(category, name)	Remove a prompt from the user's data.
`search`(query, *[, categories, ...])	Search for prompts matching a query string.

Classes

NamedPrompts(*[, include_user_data])

Two-level mapping of (category, name) -> prompt_text.

class arioso.named_prompts.NamedPrompts(*, include_user_data=True)[source]#

Bases: Mapping

Two-level mapping of (category, name) -> prompt_text.

Supports both hierarchical and flat access:

np = NamedPrompts()
np.artists['billie_eilish']     # attribute access to a category
np['artists']['billie_eilish']  # dict-style
np['artists', 'billie_eilish']  # flat tuple key

Categories are auto-discovered from YAML files in the starter and user dirs.

Parameters:: include_user_data (bool) – Whether to layer user data on top of starter data. Defaults to True.

property categories: Tuple[str, ...]#: Return all available category names.

flat()[source]#

Return a flat dict of {(category, name): prompt_text}.

Return type:: Dict[Tuple[str, str], str]

flat_names(*, warn_collisions=True)[source]#

Return a flat dict of {name: prompt_text}, ignoring categories.

If the same name appears in multiple categories, the last one wins and a warning is issued (unless warn_collisions=False).

Return type:: Dict[str, str]

arioso.named_prompts.add_prompt(category, name, prompt_text, *, confirm_override=True)[source]#

Add or update a prompt in the user’s data.

If the name already exists in either user or starter data and confirm_override is True, a confirmation prompt is printed on the first collision.

Parameters:

category (str) – The category to add to (e.g. ‘artists’, ‘moods’).
name (str) – The identifier for this prompt.
prompt_text (str) – The sonic description / prompt text.
confirm_override (bool) – If True, warn when overriding an existing entry.

Return type:

None

arioso.named_prompts.get_named_prompts()[source]#

Return a module-level singleton NamedPrompts instance.

Return type:: NamedPrompts

arioso.named_prompts.remove_prompt(category, name)[source]#

Remove a prompt from the user’s data.

This only removes from user data. Starter data entries cannot be removed (but can be overridden via add_prompt).

Return type:: None

arioso.named_prompts.search(query, *, categories=None, search_prompts=True, search_names=True)[source]#

Search for prompts matching a query string.

Parameters:

query (str) – Case-insensitive substring to search for.
categories (Optional[Tuple[str, ...]]) – If given, restrict search to these categories.
search_prompts (bool) – Whether to search in prompt text.
search_names (bool) – Whether to search in entry names.

Return type:

Dict[Tuple[str, str], str]

Returns:

Dict of {(category, name): prompt_text} for all matches.