synkro 0.4.12__py3-none-any.whl

synkro/generation/follow_ups.py

@@ -0,0 +1,134 @@
+"""Follow-up question generation for multi-turn conversations."""
+
+from typing import Literal
+
+from synkro.llm.client import LLM
+from synkro.models import Model, OpenAI
+from synkro.types.core import Message
+from synkro.prompts.multiturn_templates import FOLLOW_UP_GENERATION_PROMPT
+from synkro.schemas import FollowUpQuestion
+
+
+QuestionType = Literal["clarification", "edge_case", "what_if", "specificity", "challenge"]
+
+# Question type progression for multi-turn conversations
+# Earlier turns focus on clarification, later turns probe deeper
+QUESTION_TYPE_BY_TURN = {
+    1: "clarification",
+    2: "specificity",
+    3: "edge_case",
+    4: "what_if",
+    5: "challenge",
+}
+
+
+class FollowUpGenerator:
+    """
+    Generates follow-up questions for multi-turn conversations.
+
+    Uses different question types based on turn index:
+    - Turn 1: clarification - Ask for more details
+    - Turn 2: specificity - Drill into specifics
+    - Turn 3: edge_case - Probe boundary conditions
+    - Turn 4: what_if - Explore hypotheticals
+    - Turn 5+: challenge - Question reasoning
+
+    Examples:
+        >>> gen = FollowUpGenerator()
+        >>> follow_up = await gen.generate(policy_text, messages, turn_index=2)
+        >>> print(follow_up.question)
+    """
+
+    def __init__(self, llm: LLM | None = None, model: Model = OpenAI.GPT_4O_MINI):
+        """
+        Initialize the follow-up generator.
+
+        Args:
+            llm: LLM client to use (creates one if not provided)
+            model: Model to use if creating LLM
+        """
+        self.llm = llm or LLM(model=model)
+
+    def _select_question_type(self, turn_index: int) -> QuestionType:
+        """
+        Select question type based on turn index.
+
+        Args:
+            turn_index: Which turn this is (1-based, counting user-assistant exchanges)
+
+        Returns:
+            Appropriate question type for this turn
+        """
+        if turn_index in QUESTION_TYPE_BY_TURN:
+            return QUESTION_TYPE_BY_TURN[turn_index]
+        # For turns beyond 5, cycle through challenging questions
+        return "challenge"
+
+    def _format_conversation(self, messages: list[Message]) -> str:
+        """Format conversation messages for prompt inclusion."""
+        formatted = []
+        for msg in messages:
+            role = msg.role.upper()
+            content = msg.content or "[No content]"
+            formatted.append(f"{role}: {content}")
+        return "\n\n".join(formatted)
+
+    async def generate(
+        self,
+        policy_text: str,
+        messages: list[Message],
+        turn_index: int,
+        question_type: QuestionType | None = None,
+        scenario_index: int = 0,
+    ) -> FollowUpQuestion:
+        """
+        Generate a follow-up question for the conversation.
+
+        Args:
+            policy_text: The policy text for context
+            messages: Conversation messages so far
+            turn_index: Which turn this is (1-based)
+            question_type: Override auto-selected question type
+            scenario_index: Index for the scenario (default 0)
+
+        Returns:
+            FollowUpQuestion with the generated question
+        """
+        # Select question type if not specified
+        if question_type is None:
+            question_type = self._select_question_type(turn_index)
+
+        # Format conversation for prompt
+        conversation = self._format_conversation(messages)
+
+        # Build prompt
+        prompt = FOLLOW_UP_GENERATION_PROMPT.format(
+            question_type=question_type,
+            conversation=conversation,
+            policy=policy_text,
+        )
+
+        try:
+            # Generate the follow-up question
+            response = await self.llm.generate(prompt)
+            question_text = response.strip()
+
+            return FollowUpQuestion(
+                index=scenario_index,
+                question=question_text,
+                question_type=question_type,
+            )
+        except Exception:
+            # Fallback generic follow-up
+            fallback_questions = {
+                "clarification": "Can you clarify that further?",
+                "edge_case": "What about edge cases?",
+                "what_if": "What if the situation changes?",
+                "specificity": "Can you be more specific?",
+                "challenge": "Why is that the best approach?",
+            }
+            return FollowUpQuestion(
+                index=scenario_index,
+                question=fallback_questions.get(question_type, "Can you elaborate?"),
+                question_type=question_type,
+            )

synkro/generation/generator.py

@@ -0,0 +1,220 @@
+"""Main Generator class orchestrating the full trace generation pipeline."""
+
+import asyncio
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from synkro.llm.client import LLM
+from synkro.llm.rate_limits import auto_workers
+from synkro.models import Model, OpenAI
+from synkro.types.dataset_type import DatasetType
+from synkro.core.policy import Policy
+from synkro.core.dataset import Dataset
+from synkro.core.checkpoint import CheckpointManager, hash_policy
+from synkro.modes.config import get_mode_config
+from synkro.errors import handle_error
+from synkro.factory import ComponentFactory
+from synkro.reporting import ProgressReporter, RichReporter
+from synkro.pipeline.runner import GenerationPipeline, GenerationResult
+
+if TYPE_CHECKING:
+    from synkro.types.tool import ToolDefinition
+
+
+class Generator:
+    """
+    Main orchestrator for generating training datasets.
+
+    The Generator handles the full pipeline:
+    1. Plan: Analyze policy and create category distribution
+    2. Generate: Create scenarios and responses
+    3. Grade: Evaluate response quality
+    4. Refine: Fix failed responses
+    5. Return: Dataset of passing traces
+
+    Examples:
+        >>> generator = Generator()
+        >>> dataset = generator.generate(policy, traces=20)
+
+        >>> # QA dataset
+        >>> generator = Generator(dataset_type=DatasetType.QA)
+        >>> dataset = generator.generate(policy)
+
+        >>> # Silent mode (no console output)
+        >>> from synkro.reporting import SilentReporter
+        >>> generator = Generator(reporter=SilentReporter())
+        >>> dataset = generator.generate(policy)
+        
+        >>> # Tool call dataset
+        >>> from synkro import ToolDefinition
+        >>> tools = [ToolDefinition(name="search", description="...", parameters={})]
+        >>> generator = Generator(dataset_type=DatasetType.TOOL_CALL, tools=tools)
+        >>> dataset = generator.generate("Usage guidelines", traces=20)
+    """
+
+    def __init__(
+        self,
+        dataset_type: DatasetType = DatasetType.SFT,
+        generation_model: Model = OpenAI.GPT_4O_MINI,
+        grading_model: Model = OpenAI.GPT_4O,
+        max_iterations: int = 1,
+        skip_grading: bool = False,
+        reporter: ProgressReporter | None = None,
+        tools: list["ToolDefinition"] | None = None,
+        turns: int | str = "auto",
+        checkpoint_dir: str | Path | None = None,
+        enable_hitl: bool = True,
+    ):
+        """
+        Initialize the Generator.
+
+        Args:
+            dataset_type: Type of dataset to generate (QA, SFT, or TOOL_CALL)
+            generation_model: Model for scenarios/responses (default: gpt-4o-mini)
+            grading_model: Model for grading (default: gpt-4o, recommend stronger)
+            max_iterations: Max refinement iterations per trace (default: 1, no retries)
+            skip_grading: Skip grading phase for faster generation (default: False)
+            reporter: Progress reporter (default: RichReporter for console output)
+            tools: List of ToolDefinition for TOOL_CALL dataset type
+            turns: Conversation turns per trace. Use int for fixed turns, or "auto"
+                for policy complexity-driven turns (Simple=1-2, Conditional=3, Complex=5+)
+            checkpoint_dir: Directory for checkpoints. If provided, enables resumable
+                generation. Progress is saved after each stage.
+            enable_hitl: Enable Human-in-the-Loop Logic Map editing. When enabled,
+                pauses after Logic Map extraction to allow interactive refinement.
+        """
+        self.dataset_type = dataset_type
+        self.mode_config = get_mode_config(dataset_type)
+        self.max_iterations = max_iterations
+        self.skip_grading = skip_grading
+        self.tools = tools
+        self.turns = turns
+        self.checkpoint_dir = Path(checkpoint_dir) if checkpoint_dir else None
+
+        # Create checkpoint manager if checkpointing enabled
+        self.checkpoint_manager = (
+            CheckpointManager(self.checkpoint_dir) if self.checkpoint_dir else None
+        )
+
+        # HITL configuration
+        self.enable_hitl = enable_hitl
+
+        # Validate tools for TOOL_CALL dataset type
+        if dataset_type == DatasetType.TOOL_CALL and not tools:
+            raise ValueError("TOOL_CALL dataset type requires tools parameter")
+        
+        # Store model info for reporting
+        self.generation_model = generation_model
+        self.grading_model = grading_model
+        
+        # Create LLM clients
+        self.generation_llm = LLM(model=generation_model)
+        self.grading_llm = LLM(model=grading_model)
+        
+        # Create factory for component creation
+        self.factory = ComponentFactory(
+            generation_llm=self.generation_llm,
+            grading_llm=self.grading_llm,
+            mode_config=self.mode_config,
+            tools=tools,
+        )
+
+        # Reporter for progress output
+        self.reporter = reporter or RichReporter()
+
+        # Auto-scale workers based on provider
+        model_str = generation_model.value if isinstance(generation_model, Enum) else str(generation_model)
+        self.workers = auto_workers(model_str)
+
+        # Create HITL editor if enabled
+        hitl_editor = self.factory.create_logic_map_editor() if enable_hitl else None
+
+        # Create pipeline
+        self.pipeline = GenerationPipeline(
+            factory=self.factory,
+            reporter=self.reporter,
+            workers=self.workers,
+            max_iterations=max_iterations,
+            skip_grading=skip_grading,
+            checkpoint_manager=self.checkpoint_manager,
+            enable_hitl=enable_hitl,
+            hitl_editor=hitl_editor,
+        )
+
+    @handle_error
+    def generate(
+        self,
+        policy: Policy | str,
+        traces: int = 20,
+        return_logic_map: bool = False,
+    ) -> Dataset | GenerationResult:
+        """
+        Generate a training dataset from a policy.
+
+        Args:
+            policy: Policy object or text string
+            traces: Target number of traces to generate (default: 20)
+            return_logic_map: If True, return GenerationResult with access to
+                the Logic Map, scenarios, and distribution (default: False)
+
+        Returns:
+            Dataset (default) or GenerationResult if return_logic_map=True
+
+        Examples:
+            >>> # Standard usage
+            >>> dataset = generator.generate(policy, traces=50)
+
+            >>> # Access Logic Map for inspection
+            >>> result = generator.generate(policy, return_logic_map=True)
+            >>> print(result.logic_map.rules)  # See extracted rules
+            >>> print(result.distribution)     # See scenario type counts
+            >>> dataset = result.dataset       # Get the dataset
+        """
+        if isinstance(policy, str):
+            policy = Policy(text=policy)
+
+        # Validate policy has enough content
+        policy.validate_length()
+
+        return asyncio.run(self._generate_async(policy, traces, return_logic_map))
+
+    async def _generate_async(
+        self,
+        policy: Policy,
+        traces: int,
+        return_logic_map: bool = False,
+    ) -> Dataset | GenerationResult:
+        """Async implementation of generation pipeline."""
+        model_str = self.generation_model.value if isinstance(self.generation_model, Enum) else str(self.generation_model)
+
+        return await self.pipeline.run(
+            policy=policy,
+            traces=traces,
+            model=model_str,
+            dataset_type=self.dataset_type.value,
+            turns=self.turns,
+            return_result=return_logic_map,
+        )
+
+    async def generate_async(
+        self,
+        policy: Policy | str,
+        traces: int = 20,
+        return_logic_map: bool = False,
+    ) -> Dataset | GenerationResult:
+        """
+        Async version of generate for use in async contexts.
+
+        Args:
+            policy: Policy object or text string
+            traces: Target number of traces to generate (default: 20)
+            return_logic_map: If True, return GenerationResult with Logic Map access
+
+        Returns:
+            Dataset (default) or GenerationResult if return_logic_map=True
+        """
+        if isinstance(policy, str):
+            policy = Policy(text=policy)
+
+        return await self._generate_async(policy, traces, return_logic_map)

synkro/generation/golden_responses.py

@@ -0,0 +1,244 @@
+"""Golden Response Generator - The Thinker.
+
+Generates traces with grounded Chain-of-Thought reasoning and rule citations.
+This is Stage 3 of the Golden Trace pipeline for SFT/QA datasets.
+"""
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from synkro.llm.client import LLM
+from synkro.models import Model, OpenAI
+from synkro.schemas import GoldenTraceOutput
+from synkro.types.core import Trace, Message, Scenario
+from synkro.types.logic_map import (
+    LogicMap,
+    GoldenScenario,
+    ReasoningStep,
+)
+from synkro.prompts.golden_templates import (
+    GOLDEN_TRACE_PROMPT,
+    GOLDEN_TRACE_MULTI_TURN_PROMPT,
+)
+
+
+class GoldenResponseGenerator:
+    """
+    The Thinker - Generates traces with grounded reasoning.
+
+    Produces traces with:
+    - Explicit Chain-of-Thought reasoning
+    - Rule citations (Rule IDs) for each reasoning step
+    - Exclusionary reasoning (why rules DON'T apply)
+    - DAG-compliant dependency order
+
+    Examples:
+        >>> generator = GoldenResponseGenerator(llm=LLM(model=OpenAI.GPT_4O_MINI))
+        >>> trace = await generator.generate_single(
+        ...     policy_text="...",
+        ...     logic_map=logic_map,
+        ...     scenario=scenario,
+        ...     target_turns=1,
+        ... )
+    """
+
+    def __init__(
+        self,
+        llm: LLM | None = None,
+        model: Model = OpenAI.GPT_4O_MINI,
+    ):
+        """
+        Initialize the Golden Response Generator.
+
+        Args:
+            llm: LLM client to use (creates one if not provided)
+            model: Model to use if creating LLM
+        """
+        self.llm = llm or LLM(model=model, temperature=0.7)
+
+    async def generate_single(
+        self,
+        policy_text: str,
+        logic_map: LogicMap,
+        scenario: GoldenScenario,
+        target_turns: int = 1,
+    ) -> Trace:
+        """
+        Generate a single trace with grounded reasoning.
+
+        Args:
+            policy_text: The policy document text
+            logic_map: The extracted Logic Map (DAG of rules)
+            scenario: The golden scenario to respond to
+            target_turns: Number of conversation turns
+
+        Returns:
+            Trace with messages and reasoning metadata
+        """
+        if target_turns > 1:
+            return await self._generate_multi_turn(
+                policy_text, logic_map, scenario, target_turns
+            )
+
+        return await self._generate_single_turn(policy_text, logic_map, scenario)
+
+    async def _generate_single_turn(
+        self,
+        policy_text: str,
+        logic_map: LogicMap,
+        scenario: GoldenScenario,
+    ) -> Trace:
+        """Generate a single-turn trace."""
+        # Format Logic Map for prompt
+        logic_map_str = self._format_logic_map(logic_map)
+
+        # Build prompt
+        prompt = GOLDEN_TRACE_PROMPT.format(
+            policy_text=policy_text,
+            logic_map=logic_map_str,
+            scenario_description=scenario.description,
+            scenario_context=scenario.context,
+            target_rule_ids=", ".join(scenario.target_rule_ids),
+            scenario_type=scenario.scenario_type.value.upper(),
+            expected_outcome=scenario.expected_outcome,
+        )
+
+        # Generate structured output
+        result = await self.llm.generate_structured(prompt, GoldenTraceOutput)
+
+        # Convert to Trace
+        messages = [
+            Message(role=m.role, content=m.content)
+            for m in result.messages
+        ]
+
+        # Convert GoldenScenario to base Scenario for Trace
+        base_scenario = scenario.to_base_scenario()
+
+        # Convert reasoning chain to serializable format
+        reasoning_chain = None
+        if result.reasoning_chain:
+            reasoning_chain = [
+                {
+                    "rule_id": step.rule_id,
+                    "rule_text": step.rule_text,
+                    "applies": step.applies,
+                    "reasoning": step.reasoning,
+                    "exclusions": step.exclusions,
+                }
+                for step in result.reasoning_chain
+            ]
+
+        return Trace(
+            messages=messages,
+            scenario=base_scenario,
+            reasoning_chain=reasoning_chain,
+            rules_applied=result.rules_applied,
+            rules_excluded=result.rules_excluded,
+        )
+
+    async def _generate_multi_turn(
+        self,
+        policy_text: str,
+        logic_map: LogicMap,
+        scenario: GoldenScenario,
+        target_turns: int,
+    ) -> Trace:
+        """Generate a multi-turn trace."""
+        # Format Logic Map for prompt
+        logic_map_str = self._format_logic_map(logic_map)
+
+        # Build prompt
+        prompt = GOLDEN_TRACE_MULTI_TURN_PROMPT.format(
+            policy_text=policy_text,
+            logic_map=logic_map_str,
+            scenario_description=scenario.description,
+            scenario_context=scenario.context,
+            target_rule_ids=", ".join(scenario.target_rule_ids),
+            scenario_type=scenario.scenario_type.value.upper(),
+            target_turns=target_turns,
+        )
+
+        # Generate structured output
+        result = await self.llm.generate_structured(prompt, GoldenTraceOutput)
+
+        # Convert to Trace
+        messages = [
+            Message(role=m.role, content=m.content)
+            for m in result.messages
+        ]
+
+        # Convert GoldenScenario to base Scenario for Trace
+        base_scenario = scenario.to_base_scenario()
+
+        # Convert reasoning chain to serializable format
+        reasoning_chain = None
+        if result.reasoning_chain:
+            reasoning_chain = [
+                {
+                    "rule_id": step.rule_id,
+                    "rule_text": step.rule_text,
+                    "applies": step.applies,
+                    "reasoning": step.reasoning,
+                    "exclusions": step.exclusions,
+                }
+                for step in result.reasoning_chain
+            ]
+
+        return Trace(
+            messages=messages,
+            scenario=base_scenario,
+            reasoning_chain=reasoning_chain,
+            rules_applied=result.rules_applied,
+            rules_excluded=result.rules_excluded,
+        )
+
+    def _format_logic_map(self, logic_map: LogicMap) -> str:
+        """Format Logic Map for prompt inclusion."""
+        lines = []
+        lines.append("RULES:")
+        for rule in logic_map.rules:
+            deps = f" [depends on: {', '.join(rule.dependencies)}]" if rule.dependencies else ""
+            lines.append(
+                f"  {rule.rule_id} ({rule.category.value}): {rule.text}{deps}"
+            )
+            lines.append(f"    IF: {rule.condition}")
+            lines.append(f"    THEN: {rule.action}")
+
+        lines.append("\nDEPENDENCY ORDER (evaluate in this order):")
+        # Show topological order for root rules and their chains
+        for root_id in logic_map.root_rules:
+            chain = logic_map.get_chain(root_id)
+            if chain:
+                chain_str = " -> ".join(r.rule_id for r in chain)
+                lines.append(f"  {chain_str}")
+
+        return "\n".join(lines)
+
+    async def generate(
+        self,
+        policy_text: str,
+        logic_map: LogicMap,
+        scenarios: list[GoldenScenario],
+        target_turns: int = 1,
+    ) -> list[Trace]:
+        """
+        Generate traces for multiple scenarios.
+
+        Args:
+            policy_text: The policy document text
+            logic_map: The extracted Logic Map
+            scenarios: List of golden scenarios
+            target_turns: Number of conversation turns
+
+        Returns:
+            List of traces with grounded reasoning
+        """
+        tasks = [
+            self.generate_single(policy_text, logic_map, s, target_turns)
+            for s in scenarios
+        ]
+        return await asyncio.gather(*tasks)
+
+
+__all__ = ["GoldenResponseGenerator"]