File Loaders

Utilities for loading examples, prompts, and other file-based data.

app/file_loaders.py

File-loading utilities for the Axis Descriptor Lab.

This module reads example JSON files and prompt text files via the shared path resolver, which supports only world-scoped and explicitly lab-only roots.

Current prompt groups

  • app/prompts/character_description/ — descriptive-generation system prompts used by the Character Description page.

  • app/prompts/chat_translation/ — standalone IC translation prompt templates used by the Chat Translation page.

Path precedence is deterministic:

  1. world-scoped roots

  2. lab-only roots

Exports

load_default_prompt() -> str

Read and return the default Character Description system prompt.

load_chat_default_prompt() -> str

Read and return the default Chat Translation prompt template.

load_example(name) -> dict

Load and parse a named example JSON file.

load_prompt(name) -> str

Load a named prompt text file.

list_example_names() -> list[str]

Return sorted stems of all .json files in app/examples/.

list_prompt_names() -> list[str]

Return sorted stems of all .txt files in the prompt tree, optionally filtered by prompt purpose.

Dependencies

Uses fastapi.HTTPException for error signalling so that callers (route handlers in main.py) get properly formatted HTTP error responses without extra try/except boilerplate.

app.file_loaders.load_default_prompt()[source]

Read the default system prompt from disk.

Returns the text of the default Character Description prompt, app/lab_only/prompts/character_description/system_prompt_v01.txt, stripped of leading and trailing whitespace.

Returns:

str

Return type:

The default system prompt text.

Raises:

HTTPException(500) – If the file is missing (indicates a broken deployment).

app.file_loaders.load_chat_default_prompt()[source]

Read the default Chat Translation prompt from disk.

Returns the text of the default standalone chat prompt, the supported chat translation prompt roots, stripped of leading and trailing whitespace.

Returns:

The default Chat Translation prompt text.

Return type:

str

Raises:

HTTPException(500) – If the default chat prompt is missing.

app.file_loaders.load_example(name)[source]

Load and parse a named example JSON file from the supported local roots.

Parameters:

name (Bare filename without extension (e.g. "proud_operator").)

Returns:

dict

Return type:

Parsed JSON object.

Raises:

  • HTTPException(404) – If the file doesn’t exist.

  • HTTPException(500) – If the file contains invalid JSON.

app.file_loaders.list_example_names()[source]

Return a sorted list of example names (without .json extension).

Scans the supported local roots for all .json files and returns their stems in alphabetical order. Used by the GET /api/examples route to populate the frontend dropdown.

Returns:

list[str]

Return type:

Sorted example name stems.

app.file_loaders.load_prompt(name, purpose=None)[source]

Load a named prompt text file from the supported prompt roots.

Unlike load_example() which parses structured JSON, this simply reads the file as plain UTF-8 text and returns it stripped of leading/trailing whitespace. Prompts are natural-language instructions for the LLM, not structured data.

Parameters:

  • name (Bare filename without extension (e.g. "system_prompt_v01").)

  • purpose (PromptPurpose | None) – Optional prompt-purpose filter. When provided, the lookup is limited to that prompt group.

Returns:

str

Return type:

The prompt text content, stripped of surrounding whitespace.

Raises:

HTTPException(404) – If the file doesn’t exist.

app.file_loaders.list_prompt_names(purpose=None)[source]

Return a sorted list of prompt names (without .txt extension).

Scans the supported prompt roots and returns prompt stems in alphabetical order. Used by GET /api/prompts to populate prompt dropdowns. The optional purpose filter lets each page request only the prompt family it actually uses.

Returns:

list[str]

Return type:

Sorted prompt name stems.