ML Response Generator

Orchestrate the ML pipeline to generate diverse response options with themes and variations.

Overview

This package is the final orchestration layer in the ML pipeline, bringing together all other ML packages to generate multiple response options with different themes, styles, and confidence scores.

Installation

pip install lilith-ml-response-generator

# With all dependencies
pip install lilith-ml-response-generator[full]

Quick Start

Basic Response Generation

from ml_response_generator import ResponseGenerator, Theme

generator = ResponseGenerator(model_client=llm)

result = await generator.generate(
    context=[
        {"role": "user", "content": "Hey, are you free Saturday?"}
    ],
    count=8,
    themes=[Theme.CASUAL, Theme.FORMAL, Theme.BRIEF],
    diversity=0.7
)

for option in result.options:
    print(f"{option.descriptor}: {option.text}")
    # Output:
    # Enthusiastic agreement: Yes! What's up?
    # Formal acknowledgment: I believe I am available.
    # Brief confirmation: Yep

Full Pipeline with All Components

from ml_response_generator import ResponsePipeline, PipelineConfig

pipeline = ResponsePipeline(
    model_client=llm,
    intent_classifier=classifier,      # From ml-intent-classifier
    context_manager=context_mgr,        # From ml-context-manager
    style_adapter=style_adapter,        # From ml-style-adapter
    quality_scorer=scorer,              # From ml-quality-scorer
    safety_filter=safety,               # From ml-safety-filter
    model_router=router,                # From ml-model-router
)

result = await pipeline.generate(
    messages=conversation_history,
    count=8,
    style_profile=user_style,
    safety_boundaries=contact_boundaries,
)

print(f"Generated in {result.pipeline_time_ms}ms")
print(f"Stages: {result.stages_completed}")

for option in result.options:
    print(f"[{option.confidence:.2f}] {option.descriptor}: {option.text}")

Themes

Each theme produces responses with a distinct tone:

Theme	Description	Example
CASUAL	Relaxed, friendly	"Hey! Yeah, sounds good!"
FORMAL	Professional, structured	"I would be happy to assist."
BRIEF	Short, to the point	"Sure."
EMPATHETIC	Supportive, understanding	"I understand how you feel..."
PLAYFUL	Light, fun	"Ooh, that sounds exciting!"
NEUTRAL	Balanced, matter-of-fact	"Yes, that is correct."

API Reference

ResponseGenerator

The base generator for creating themed responses.

from ml_response_generator import ResponseGenerator, GenerationConfig

config = GenerationConfig(
    count=8,                    # Total options to generate
    themes=[Theme.CASUAL],      # Themes to use
    diversity=0.7,              # 0.0-1.0, higher = more varied
    max_tokens=100,             # Per response
    temperature=0.8,            # Generation temperature
    min_confidence=0.3,         # Minimum quality to include
)

generator = ResponseGenerator(
    model_client=llm,
    default_config=config,
)

# Full generation
result = await generator.generate(context=messages)

# Simple interface
responses = await generator.generate_simple("How are you?", count=4)

# Single theme
options = await generator.generate_for_theme(context, Theme.FORMAL, count=3)

ResponsePipeline

Full pipeline with optional ML components.

from ml_response_generator import ResponsePipeline, PipelineConfig

config = PipelineConfig(
    use_intent_classification=True,   # Classify message intent
    use_context_optimization=True,    # Optimize context within token limits
    use_style_adaptation=True,        # Apply user's communication style
    use_quality_scoring=True,         # Score and rank responses
    use_safety_filtering=True,        # Filter unsafe content
    use_model_routing=True,           # Route to fast/reasoning model
    auto_select_themes=True,          # Select themes based on intent
)

pipeline = ResponsePipeline(
    model_client=llm,
    intent_classifier=classifier,
    context_manager=context_mgr,
    style_adapter=adapter,
    quality_scorer=scorer,
    safety_filter=safety,
    model_router=router,
    config=config,
)

result = await pipeline.generate(messages)

ResponseOption

Individual response with metadata.

@dataclass
class ResponseOption:
    text: str              # The response text
    descriptor: str        # Human-readable description
    theme: str             # Theme used
    confidence: float      # Quality score (0.0-1.0)
    metadata: dict         # Additional info

GenerationResult

Result of generation operation.

@dataclass
class GenerationResult:
    options: list[ResponseOption]   # Generated options
    total_generated: int            # Before filtering
    total_filtered: int             # Filtered out
    generation_time_ms: float       # Timing
    metadata: dict                  # Additional info

Pipeline Stages

The full pipeline executes these stages in order:

1. Intent Classification - Understand message intent, urgency, tone
2. Theme Selection - Auto-select themes based on intent (optional)
3. Context Optimization - Build optimal context within token limits
4. Model Selection - Route to fast or reasoning model
5. Response Generation - Generate candidates per theme
6. Style Adaptation - Apply user's personal style
7. Quality Scoring - Score and rank candidates
8. Safety Filtering - Filter unsafe content
9. Return - Return top options with metadata

Dependencies

This package orchestrates the following ML packages:

Package	Purpose	Optional
lilith-ml-model-router	Fast/reasoning model selection	Yes
lilith-ml-intent-classifier	Message intent classification	Yes
lilith-ml-context-manager	Context optimization	Yes
lilith-ml-style-adapter	User style application	Yes
lilith-ml-quality-scorer	Response quality scoring	Yes
lilith-ml-safety-filter	Content moderation	Yes

All dependencies are optional - the package works with just the base model client.

Model Client Protocol

Any LLM client implementing this protocol can be used:

class ModelClientProtocol(Protocol):
    async def generate(
        self,
        messages: list[dict[str, str]],
        **kwargs: Any,
    ) -> str:
        """Generate a response from the model."""
        ...

Examples

Generating Diverse Responses

# Generate with high diversity
result = await generator.generate(
    context=messages,
    count=8,
    diversity=0.9,  # Very different options
)

Filtering by Theme

result = await generator.generate(context=messages)

# Get only casual responses
casual = result.get_by_theme(Theme.CASUAL)

# Get best overall response
best = result.best_option

Safety-Aware Generation

from ml_safety_filter import ContactBoundaries

boundaries = ContactBoundaries(
    blocked_topics=["financial", "location"],
    classification="unknown",
)

result = await pipeline.generate(
    messages=messages,
    safety_boundaries=boundaries,
)

# Unsafe content is automatically filtered

Style-Adapted Responses

from ml_style_adapter import StyleProfile

user_style = StyleProfile(
    formality=0.3,
    emoji_usage=True,
    response_brevity=0.8,
)

result = await pipeline.generate(
    messages=messages,
    style_profile=user_style,
)

# Responses match user's communication style

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=ml_response_generator

License

MIT