lang_tools.llm ¶

LLM service layer built on llm-core's StructuredLLMChain.

Each module exposes a typed input model, a typed output model, and a build_*_chain(chat_config, base_prompt_fol=...) factory that loads the versioned Jinja prompt and wires everything into a StructuredLLMChain.

Public API

TranslationInput, TranslationOutput, build_translation_chain ConversationInput, ConversationOutput, ConversationTurn, build_conversation_chain TutorInput, TutorOutput, CorrectionBlock, ConversationBlock, ErrorDetail, build_tutor_chain TopicSuggestionInput, TopicSuggestionOutput, build_topic_suggestion_chain SplitterInput, SplitterOutput, build_paragraph_splitter_chain GreetingInput, GreetingOutput, build_greeting_chain WordGeneratorInput, WordGeneratorOutput, GeneratedWord, build_word_generator_chain

Modules:

conversation –

ConversationGeneratorChain: generate a multi-turn bilingual dialogue.
greeting –

GreetingGeneratorChain: open a conversational tutor session.
splitter –

ParagraphSplitterChain: split text into reconstruction-friendly portions.
topics –

TopicSuggestionChain: generate practice topics for a language.
translation –

TranslationChain: translate text between any two supported languages.
tutor –

TutorResponseChain: produce a correction + conversation continuation.
word_generator –

WordGeneratorChain: generate themed vocabulary on demand.

Classes:

ConversationBlock –

Tutor's conversation continuation.
ConversationInput –

Inputs to ConversationGeneratorChain.
ConversationOutput –

Outputs from ConversationGeneratorChain.
ConversationTurn –

One turn in a generated conversation.
CorrectionBlock –

Tutor's correction block.
ErrorDetail –

Structured grammar / vocabulary error.
GeneratedWord –

One LLM-generated vocabulary item.
GreetingInput –

Inputs to GreetingGeneratorChain.
GreetingOutput –

Outputs from GreetingGeneratorChain.
SplitterInput –

Inputs to ParagraphSplitterChain.
SplitterOutput –

Outputs from ParagraphSplitterChain.
TopicSuggestionInput –

Inputs to TopicSuggestionChain.
TopicSuggestionOutput –

Outputs from TopicSuggestionChain.
TranslationInput –

Inputs to TranslationChain.
TranslationOutput –

Outputs from TranslationChain.
TutorInput –

Inputs to TutorResponseChain.
TutorOutput –

Outputs from TutorResponseChain.
WordGeneratorInput –

Inputs to WordGeneratorChain.
WordGeneratorOutput –

Outputs from WordGeneratorChain.

Functions:

build_conversation_chain –

Build a conversation generator chain wired to chat_config.
build_greeting_chain –

Build a greeting generator chain wired to chat_config.
build_paragraph_splitter_chain –

Build a paragraph splitter chain wired to chat_config.
build_topic_suggestion_chain –

Build a topic suggestion chain wired to chat_config.
build_translation_chain –

Build a translation chain wired to chat_config.
build_tutor_chain –

Build a tutor response chain wired to chat_config.
build_word_generator_chain –

Build a word generator chain wired to chat_config.

ConversationBlock ¶

Bases: BaseModel

Tutor's conversation continuation.

Attributes:

content (str) –

Continuation text in the target language.
translation (str) –

Translation of the continuation.

ConversationInput ¶

Bases: BaseModelKwargs

Inputs to ConversationGeneratorChain.

Attributes:

topic (str) –

Topic prompt for the dialogue.
language (str) –

ISO 639-1 code of the target language.
difficulty_level (str) –

"beginner" / "intermediate" / "advanced".
num_turns (int) –

How many turns the dialogue should contain.
max_sentences_per_turn (int) –

Per-turn sentence cap.
sample_conversation (str | None) –

Optional few-shot example to calibrate level.

ConversationOutput ¶

Bases: BaseModel

Outputs from ConversationGeneratorChain.

Attributes:

turns (list[ConversationTurn]) –

Generated dialogue turns.

ConversationTurn ¶

Bases: BaseModel

One turn in a generated conversation.

Attributes:

role (Literal['user', 'system']) –

"user" or "system".
content (str) –

Target-language text.
translation (str) –

User-language translation.

CorrectionBlock ¶

Bases: BaseModel

Tutor's correction block.

Attributes:

content (str) –

Correction text in the target language.
translation (str) –

Translation of the correction text.
errors (list[ErrorDetail]) –

Structured list of individual errors.

ErrorDetail ¶

Bases: BaseModel

Structured grammar / vocabulary error.

Attributes:

original (str) –

The user's wording.
corrected (str) –

The corrected wording.
explanation (str) –

Brief grammar / vocab note.

GeneratedWord ¶

Bases: BaseModel

One LLM-generated vocabulary item.

Attributes:

text (str) –

The word in the target language.
translation (str) –

English translation.
part_of_speech (str) –

Word class label.
example_sentence (str) –

Example sentence in the target language.
example_translation (str) –

English translation of the example sentence.

GreetingInput ¶

Bases: BaseModelKwargs

Inputs to GreetingGeneratorChain.

Attributes:

topic (str) –

Topic the conversation will revolve around.
language (str) –

ISO 639-1 target language code.
difficulty_level (str) –

"beginner" / "intermediate" / "advanced".

GreetingOutput ¶

Bases: BaseModel

Outputs from GreetingGeneratorChain.

Attributes:

greeting (str) –

Greeting text in the target language.
translation (str) –

Translation in the user's language.

SplitterInput ¶

Bases: BaseModelKwargs

Inputs to ParagraphSplitterChain.

Attributes:

text (str) –

Text to split.
language (str) –

ISO 639-1 code of the source language.

SplitterOutput ¶

Bases: BaseModel

Outputs from ParagraphSplitterChain.

Attributes:

portions (list[str]) –

Ordered list of split portions.

TopicSuggestionInput ¶

Bases: BaseModelKwargs

Inputs to TopicSuggestionChain.

Attributes:

language (str) –

ISO 639-1 target language code.
difficulty_level (str) –

"beginner" / "intermediate" / "advanced".
num_topics (int) –

How many topics to return.
exclude_topics (list[str]) –

Topics to avoid (de-duplication).

TopicSuggestionOutput ¶

Bases: BaseModel

Outputs from TopicSuggestionChain.

Attributes:

topics (list[str]) –

List of topic strings.

TranslationInput ¶

Bases: BaseModelKwargs

Inputs to TranslationChain.

Attributes:

text (str) –

Source text.
source_language (str) –

ISO 639-1 code of the source.
target_language (str) –

ISO 639-1 code of the destination.

TranslationOutput ¶

Bases: BaseModel

Outputs from TranslationChain.

Attributes:

translated_text (str) –

The translated string.

TutorInput ¶

Bases: BaseModelKwargs

Inputs to TutorResponseChain.

Attributes:

topic (str) –

Conversation topic.
language (str) –

ISO 639-1 target language code.
user_message (str) –

Latest user message.
history (list[TutorMessage]) –

Prior TutorMessages.
difficulty_level (str) –

"beginner" / "intermediate" / "advanced".

TutorOutput ¶

Bases: BaseModel

Outputs from TutorResponseChain.

Attributes:

correction (CorrectionBlock) –

Correction block (may be empty when no errors).
conversation (ConversationBlock) –

Conversation continuation block.

WordGeneratorInput ¶

Bases: BaseModelKwargs

Inputs to WordGeneratorChain.

Attributes:

language (str) –

ISO 639-1 target language code.
topic (str) –

Theme to draw vocabulary from.
num_words (int) –

How many words to produce.
difficulty (str) –

"beginner" / "intermediate" / "advanced".
require_accents (bool) –

If True, only return words containing accented chars.

WordGeneratorOutput ¶

Bases: BaseModel

Outputs from WordGeneratorChain.

Attributes:

words (list[GeneratedWord]) –

Generated vocabulary list.

build_conversation_chain ¶

build_conversation_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[
    ConversationInput, ConversationOutput
]

Build a conversation generator chain wired to chat_config.

Source code in src/lang_tools/llm/conversation.py

def build_conversation_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[ConversationInput, ConversationOutput]:
    """Build a conversation generator chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "conversation_generator",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=ConversationInput,
        output_model=ConversationOutput,
    )

build_greeting_chain ¶

build_greeting_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[GreetingInput, GreetingOutput]

Build a greeting generator chain wired to chat_config.

Source code in src/lang_tools/llm/greeting.py

def build_greeting_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[GreetingInput, GreetingOutput]:
    """Build a greeting generator chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "greeting_generator",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=GreetingInput,
        output_model=GreetingOutput,
    )

build_paragraph_splitter_chain ¶

build_paragraph_splitter_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[SplitterInput, SplitterOutput]

Build a paragraph splitter chain wired to chat_config.

Source code in src/lang_tools/llm/splitter.py

def build_paragraph_splitter_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[SplitterInput, SplitterOutput]:
    """Build a paragraph splitter chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "paragraph_splitter",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=SplitterInput,
        output_model=SplitterOutput,
    )

build_topic_suggestion_chain ¶

build_topic_suggestion_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[
    TopicSuggestionInput, TopicSuggestionOutput
]

Build a topic suggestion chain wired to chat_config.

Source code in src/lang_tools/llm/topics.py

def build_topic_suggestion_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[TopicSuggestionInput, TopicSuggestionOutput]:
    """Build a topic suggestion chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "topic_suggestion",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=TopicSuggestionInput,
        output_model=TopicSuggestionOutput,
    )

build_translation_chain ¶

build_translation_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[
    TranslationInput, TranslationOutput
]

Build a translation chain wired to chat_config.

Parameters:

chat_config (ChatConfig) –

llm-core ChatConfig (e.g. ChatOpenAIConfig).
base_prompt_fol (Path | None, default: None ) –

Override prompts root; defaults to in-package folder.
version (str, default: 'auto' ) –

Prompt version ("1" or "auto").

Returns:

StructuredLLMChain[TranslationInput, TranslationOutput] –

StructuredLLMChain ready to invoke / ainvoke.

Source code in src/lang_tools/llm/translation.py

def build_translation_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[TranslationInput, TranslationOutput]:
    """Build a translation chain wired to `chat_config`.

    Args:
        chat_config: `llm-core` `ChatConfig` (e.g. `ChatOpenAIConfig`).
        base_prompt_fol: Override prompts root; defaults to in-package folder.
        version: Prompt version (``"1"`` or ``"auto"``).

    Returns:
        `StructuredLLMChain` ready to `invoke` / `ainvoke`.
    """
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "translation",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=TranslationInput,
        output_model=TranslationOutput,
    )

build_tutor_chain ¶

build_tutor_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[TutorInput, TutorOutput]

Build a tutor response chain wired to chat_config.

Source code in src/lang_tools/llm/tutor.py

def build_tutor_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[TutorInput, TutorOutput]:
    """Build a tutor response chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "tutor_response",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=TutorInput,
        output_model=TutorOutput,
    )

build_word_generator_chain ¶

build_word_generator_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[
    WordGeneratorInput, WordGeneratorOutput
]

Build a word generator chain wired to chat_config.

Source code in src/lang_tools/llm/word_generator.py

def build_word_generator_chain(
    chat_config: ChatConfig,
    *,
    base_prompt_fol: Path | None = None,
    version: str = "auto",
) -> StructuredLLMChain[WordGeneratorInput, WordGeneratorOutput]:
    """Build a word generator chain wired to `chat_config`."""
    return StructuredLLMChain(
        chat_config=chat_config,
        prompt_str=load_prompt(
            "word_generator",
            base_prompt_fol=base_prompt_fol,
            version=version,
        ),
        input_model=WordGeneratorInput,
        output_model=WordGeneratorOutput,
    )