AI Coaching System

Multi-turn conversational AI that guides users through articulating intent.

When to Use This Skill

• Building AI assistants that need to understand complex user intent

• Need structured parameter extraction from conversation

• Want to detect when user intent is ready for action

• Implementing clarification flows for ambiguous input

Core Concepts

The coach helps users articulate WHAT they want, not HOW to achieve it. It extracts structured intent through conversation, tracks ambiguities, and signals readiness only after user confirmation.

User Input → Intent Parser → Schema Update → Readiness Check → Coach Response

Implementation

Python

from dataclasses import dataclass, field from datetime import datetime from typing import Optional, List, Dict, Any from enum import Enum import re

class ReadinessState(str, Enum): NOT_READY = "not_ready" NEEDS_CLARIFICATION = "needs_clarification" AWAITING_CONFIRMATION = "awaiting_confirmation" READY = "ready"

@dataclass class AmbiguousAnnotation: text: str possible_intents: List[str] resolved: bool = False resolution: Optional[str] = None

@dataclass class CreativeIntentSchema: """Structured representation of user's creative intent.""" asset_type: str mood: Optional[str] = None scene_elements: List[Dict] = field(default_factory=list) display_texts: List[Dict] = field(default_factory=list) ambiguous_annotations: List[AmbiguousAnnotation] = field(default_factory=list) turn_count: int = 0 user_confirmed_vision: bool = False last_coach_summary: Optional[str] = None

def get_readiness(self) -> ReadinessState:
    if self.turn_count == 0:
        return ReadinessState.NOT_READY
    
    unresolved = [a for a in self.ambiguous_annotations if not a.resolved]
    if unresolved:
        return ReadinessState.NEEDS_CLARIFICATION
    
    if not self.user_confirmed_vision:
        return ReadinessState.AWAITING_CONFIRMATION
    
    return ReadinessState.READY

def is_ready(self) -> bool:
    return self.get_readiness() == ReadinessState.READY

def get_clarification_questions(self) -> List[str]:
    return [
        f'Should "{a.text}" be rendered as an image or displayed as text?'
        for a in self.ambiguous_annotations if not a.resolved
    ]

class IntentParser: """Parses messages to extract and update intent."""

CONFIRMATION_PATTERNS = [
    r"\b(yes|yeah|sure|ok|perfect|great|looks good|exactly)\b",
    r"\b(let's go|do it|generate|create it)\b",
]

def parse_initial_request(
    self,
    description: str,
    asset_type: str,
    mood: Optional[str] = None,
) -> CreativeIntentSchema:
    schema = CreativeIntentSchema(asset_type=asset_type, mood=mood)
    
    # Extract quoted text as display text
    quoted = re.findall(r'"([^"]+)"', description)
    for text in quoted:
        schema.display_texts.append({"text": text})
    
    if description and not quoted:
        schema.scene_elements.append({"description": description})
    
    return schema

def parse_user_message(
    self,
    message: str,
    schema: CreativeIntentSchema,
) -> tuple[CreativeIntentSchema, bool]:
    schema.turn_count += 1
    
    is_confirmation = self._is_confirmation(message)
    if is_confirmation:
        schema.user_confirmed_vision = True
    
    # Resolve ambiguities from user response
    message_lower = message.lower()
    for amb in schema.ambiguous_annotations:
        if not amb.resolved:
            if "text" in message_lower or "display" in message_lower:
                amb.resolved = True
                amb.resolution = "display_text"
            elif "render" in message_lower or "image" in message_lower:
                amb.resolved = True
                amb.resolution = "render"
    
    return schema, is_confirmation

def _is_confirmation(self, message: str) -> bool:
    message_lower = message.lower().strip()
    return any(re.search(p, message_lower) for p in self.CONFIRMATION_PATTERNS)

@dataclass class StreamChunk: type: str # "token", "intent_ready", "done", "error" content: str = "" metadata: Optional[Dict[str, Any]] = None

class CoachService: """Orchestrates coaching conversations."""

MAX_TURNS = 10

def __init__(self, llm_client, session_store):
    self.llm = llm_client
    self.sessions = session_store
    self.parser = IntentParser()

async def start_session(
    self,
    user_id: str,
    asset_type: str,
    description: str,
    mood: Optional[str] = None,
):
    # Initialize intent schema
    schema = self.parser.parse_initial_request(description, asset_type, mood)
    
    # Build system prompt
    system_prompt = f"""You are a creative coach helping users design {asset_type} assets.

RULES:

1. Ask clarifying questions to understand their vision

2. Summarize what you understand after each exchange

3. When vision is clear, say [INTENT_READY]

4. Never say [INTENT_READY] on first turn

5. Focus on WHAT they want, not HOW"""

    first_message = f'User wants to create a {asset_type}. Description: "{description}"'
    
    # Stream LLM response
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": first_message},
    ]
    
    full_response = ""
    async for token in self.llm.stream_chat(messages):
        full_response += token
        yield StreamChunk(type="token", content=token)
    
    # First turn is NEVER ready
    yield StreamChunk(
        type="intent_ready",
        metadata={
            "is_ready": False,
            "readiness_state": ReadinessState.NOT_READY.value,
            "clarification_questions": schema.get_clarification_questions(),
        },
    )
    
    yield StreamChunk(type="done", metadata={"turns_remaining": self.MAX_TURNS - 1})
   

   async def continue_chat( self, session_id: str, message: str, schema: CreativeIntentSchema, ): if schema.turn_count >= self.MAX_TURNS: yield StreamChunk(type="error", content="Turn limit reached") return

    schema, is_confirmation = self.parser.parse_user_message(message, schema)
    
    # Stream response...
    full_response = ""
    async for token in self.llm.stream_chat([...]):
        full_response += token
        yield StreamChunk(type="token", content=token)
    
    readiness = schema.get_readiness()
    
    yield StreamChunk(
        type="intent_ready",
        metadata={
            "is_ready": schema.is_ready(),
            "readiness_state": readiness.value,
            "is_confirmation": is_confirmation,
        },
    )
   

TypeScript

enum ReadinessState { NOT_READY = 'not_ready', NEEDS_CLARIFICATION = 'needs_clarification', AWAITING_CONFIRMATION = 'awaiting_confirmation', READY = 'ready', }

interface AmbiguousAnnotation { text: string; possibleIntents: string[]; resolved: boolean; resolution?: string; }

interface CreativeIntentSchema { assetType: string; mood?: string; sceneElements: Array<{ description: string }>; displayTexts: Array<{ text: string }>; ambiguousAnnotations: AmbiguousAnnotation[]; turnCount: number; userConfirmedVision: boolean; }

function getReadiness(schema: CreativeIntentSchema): ReadinessState { if (schema.turnCount === 0) return ReadinessState.NOT_READY;

const unresolved = schema.ambiguousAnnotations.filter(a => !a.resolved); if (unresolved.length > 0) return ReadinessState.NEEDS_CLARIFICATION;

if (!schema.userConfirmedVision) return ReadinessState.AWAITING_CONFIRMATION;

return ReadinessState.READY; }

const CONFIRMATION_PATTERNS = [ /\b(yes|yeah|sure|ok|perfect|great|looks good)\b/i, /\b(let's go|do it|generate|create it)\b/i, ];

function isConfirmation(message: string): boolean { return CONFIRMATION_PATTERNS.some(p => p.test(message)); }

Usage Examples

Start coaching session

async for chunk in coach.start_session( user_id="user_123", asset_type="thumbnail", description="gaming video thumbnail", mood="energetic", ): if chunk.type == "token": print(chunk.content, end="") elif chunk.type == "intent_ready": if chunk.metadata["is_ready"]: # Proceed to generation pass else: # Show clarification questions for q in chunk.metadata.get("clarification_questions", []): print(f"Coach asks: {q}")

Best Practices

• Never mark intent as ready on first turn - always ask questions

• Require explicit user confirmation before proceeding

• Track and resolve ambiguities explicitly

• Summarize understanding after each exchange

• Limit total turns to prevent infinite conversations

• Stream responses for better UX

Common Mistakes

• Auto-confirming intent without user acknowledgment

• Not tracking ambiguous terms that need clarification

• Allowing ready state on first turn

• Not persisting session state for reconnections

• Forgetting turn limits

Related Patterns

• prompt-engine (prompt construction)

• ai-generation-client (generation execution)

• sse-streaming (response streaming)