synkro 0.4.12__py3-none-any.whl

synkro/factory.py

@@ -0,0 +1,276 @@
+"""Component factory for dependency injection.
+
+This module provides a factory for creating pipeline components,
+enabling testability and flexible configuration.
+
+Supports both legacy components and Golden Trace components:
+- Logic Extractor (The Cartographer)
+- Golden Scenario Generator (The Adversary)
+- Golden Response Generator (The Thinker)
+- Trace Verifier (The Auditor)
+- Golden Refiner
+"""
+
+from typing import TYPE_CHECKING
+
+from synkro.llm.client import LLM
+from synkro.modes.config import ModeConfig
+from synkro.generation.planner import Planner
+from synkro.generation.scenarios import ScenarioGenerator
+from synkro.generation.responses import ResponseGenerator
+from synkro.generation.follow_ups import FollowUpGenerator
+from synkro.generation.multiturn_responses import MultiTurnResponseGenerator
+from synkro.quality.grader import Grader
+from synkro.quality.refiner import Refiner
+from synkro.quality.multiturn_grader import MultiTurnGrader
+
+if TYPE_CHECKING:
+    from synkro.types.tool import ToolDefinition
+    from synkro.generation.tool_simulator import ToolSimulator
+    from synkro.generation.tool_responses import ToolCallResponseGenerator
+    from synkro.quality.tool_grader import ToolCallGrader
+    from synkro.quality.tool_refiner import ToolCallRefiner
+    from synkro.generation.logic_extractor import LogicExtractor
+    from synkro.generation.golden_scenarios import GoldenScenarioGenerator
+    from synkro.generation.golden_responses import GoldenResponseGenerator
+    from synkro.generation.golden_tool_responses import GoldenToolCallResponseGenerator
+    from synkro.quality.verifier import TraceVerifier
+    from synkro.quality.golden_refiner import GoldenRefiner
+    from synkro.interactive.logic_map_editor import LogicMapEditor
+
+
+class ComponentFactory:
+    """
+    Factory for creating pipeline components with shared LLM clients.
+    
+    This centralizes component creation and ensures consistent configuration
+    across the pipeline.
+    
+    Examples:
+        >>> factory = ComponentFactory(gen_llm, grade_llm, mode_config)
+        >>> planner = factory.create_planner()
+        >>> grader = factory.create_grader()
+        
+        >>> # With tools for tool_call dataset type
+        >>> factory = ComponentFactory(gen_llm, grade_llm, mode_config, tools=[...])
+        >>> simulator = factory.create_tool_simulator()
+    """
+    
+    def __init__(
+        self,
+        generation_llm: LLM,
+        grading_llm: LLM,
+        mode_config: ModeConfig,
+        tools: list["ToolDefinition"] | None = None,
+    ):
+        """
+        Initialize the factory.
+        
+        Args:
+            generation_llm: LLM client for generation tasks (scenarios, responses, refinement)
+            grading_llm: LLM client for grading and planning (typically stronger model)
+            mode_config: Configuration for the dataset type (prompts, etc.)
+            tools: Optional list of tool definitions for tool_call dataset type
+        """
+        self.generation_llm = generation_llm
+        self.grading_llm = grading_llm
+        self.mode_config = mode_config
+        self.tools = tools or []
+    
+    def create_planner(self) -> Planner:
+        """Create a Planner instance."""
+        return Planner(llm=self.grading_llm)
+    
+    def create_scenario_generator(self) -> ScenarioGenerator:
+        """Create a ScenarioGenerator with mode-specific prompts."""
+        gen = ScenarioGenerator(llm=self.generation_llm)
+        gen.prompt_template = self.mode_config.scenario_prompt
+        return gen
+    
+    def create_response_generator(self) -> ResponseGenerator:
+        """Create a ResponseGenerator with mode-specific prompts."""
+        gen = ResponseGenerator(llm=self.generation_llm)
+        gen.prompt_template = self.mode_config.response_prompt
+        return gen
+    
+    def create_grader(self) -> "Grader | ToolCallGrader":
+        """
+        Create a Grader with mode-specific prompts.
+        
+        Auto-selects ToolCallGrader when tools are configured.
+        """
+        if self.has_tools:
+            from synkro.quality.tool_grader import ToolCallGrader
+            return ToolCallGrader(llm=self.grading_llm, tools=self.tools)
+        
+        grader = Grader(llm=self.grading_llm)
+        grader.prompt_template = self.mode_config.grade_prompt
+        return grader
+    
+    def create_refiner(self) -> "Refiner | ToolCallRefiner":
+        """
+        Create a Refiner with mode-specific prompts.
+        
+        Auto-selects ToolCallRefiner when tools are configured.
+        This ensures tool_calls format is preserved during refinement.
+        """
+        if self.has_tools:
+            from synkro.quality.tool_refiner import ToolCallRefiner
+            simulator = self.create_tool_simulator()
+            return ToolCallRefiner(
+                llm=self.generation_llm,
+                tools=self.tools,
+                simulator=simulator,
+            )
+        
+        refiner = Refiner(llm=self.generation_llm)
+        refiner.prompt_template = self.mode_config.refine_prompt
+        return refiner
+    
+    def create_tool_simulator(self) -> "ToolSimulator":
+        """Create a ToolSimulator instance for tool_call dataset type."""
+        from synkro.generation.tool_simulator import ToolSimulator
+        
+        if not self.tools:
+            raise ValueError("Cannot create ToolSimulator without tools")
+        
+        return ToolSimulator(tools=self.tools, llm=self.generation_llm)
+    
+    def create_tool_call_response_generator(self) -> "ToolCallResponseGenerator":
+        """
+        Create a ToolCallResponseGenerator for generating proper tool call traces.
+        
+        This generator uses JSON mode to produce structured tool calls in
+        OpenAI function calling format.
+        """
+        from synkro.generation.tool_responses import ToolCallResponseGenerator
+        
+        if not self.tools:
+            raise ValueError("Cannot create ToolCallResponseGenerator without tools")
+        
+        # Create simulator for generating tool responses
+        simulator = self.create_tool_simulator()
+        
+        return ToolCallResponseGenerator(
+            tools=self.tools,
+            llm=self.generation_llm,
+            simulator=simulator,
+        )
+    
+    def get_tools_description(self) -> str:
+        """Get formatted description of all available tools."""
+        if not self.tools:
+            return "No tools available"
+        
+        descriptions = []
+        for tool in self.tools:
+            descriptions.append(tool.to_system_prompt())
+        return "\n\n".join(descriptions)
+    
+    @property
+    def has_tools(self) -> bool:
+        """Check if tools are configured."""
+        return bool(self.tools)
+
+    def create_follow_up_generator(self) -> FollowUpGenerator:
+        """Create a FollowUpGenerator for multi-turn conversations."""
+        return FollowUpGenerator(llm=self.generation_llm)
+
+    def create_multi_turn_response_generator(self) -> MultiTurnResponseGenerator:
+        """Create a MultiTurnResponseGenerator for multi-turn trace generation."""
+        return MultiTurnResponseGenerator(llm=self.generation_llm)
+
+    def create_multi_turn_grader(self) -> MultiTurnGrader:
+        """Create a MultiTurnGrader for per-turn and overall conversation grading."""
+        return MultiTurnGrader(llm=self.grading_llm)
+
+    # =========================================================================
+    # GOLDEN TRACE COMPONENTS
+    # =========================================================================
+
+    def create_logic_extractor(self) -> "LogicExtractor":
+        """
+        Create a LogicExtractor (The Cartographer).
+
+        Uses the grading LLM (stronger model) for accurate rule extraction.
+        """
+        from synkro.generation.logic_extractor import LogicExtractor
+        return LogicExtractor(llm=self.grading_llm)
+
+    def create_golden_scenario_generator(self) -> "GoldenScenarioGenerator":
+        """
+        Create a GoldenScenarioGenerator (The Adversary).
+
+        Generates typed scenarios (positive, negative, edge_case, irrelevant)
+        with rule targeting.
+        """
+        from synkro.generation.golden_scenarios import GoldenScenarioGenerator
+        return GoldenScenarioGenerator(llm=self.generation_llm)
+
+    def create_golden_response_generator(self) -> "GoldenResponseGenerator":
+        """
+        Create a GoldenResponseGenerator (The Thinker).
+
+        Generates traces with grounded Chain-of-Thought reasoning
+        and rule citations.
+        """
+        from synkro.generation.golden_responses import GoldenResponseGenerator
+        return GoldenResponseGenerator(llm=self.generation_llm)
+
+    def create_golden_tool_call_generator(self) -> "GoldenToolCallResponseGenerator":
+        """
+        Create a GoldenToolCallResponseGenerator (The Thinker for Tools).
+
+        Generates tool call traces with rule citations for tool selection
+        decisions. Requires tools to be configured.
+        """
+        from synkro.generation.golden_tool_responses import GoldenToolCallResponseGenerator
+
+        if not self.tools:
+            raise ValueError("Cannot create GoldenToolCallResponseGenerator without tools")
+
+        simulator = self.create_tool_simulator()
+        return GoldenToolCallResponseGenerator(
+            tools=self.tools,
+            llm=self.generation_llm,
+            simulator=simulator,
+        )
+
+    def create_verifier(self) -> "TraceVerifier":
+        """
+        Create a TraceVerifier (The Auditor).
+
+        Verifies traces against the Logic Map to ensure:
+        - No skipped rules
+        - No hallucinated rules
+        - No contradictions
+        - DAG compliance
+
+        Uses the grading LLM (stronger model) for accurate verification.
+        """
+        from synkro.quality.verifier import TraceVerifier
+        return TraceVerifier(llm=self.grading_llm)
+
+    def create_golden_refiner(self) -> "GoldenRefiner":
+        """
+        Create a GoldenRefiner.
+
+        Refines traces that fail verification, using Logic Map context
+        to fix skipped rules, hallucinations, and contradictions.
+        """
+        from synkro.quality.golden_refiner import GoldenRefiner
+        return GoldenRefiner(llm=self.generation_llm)
+
+    def create_logic_map_editor(self) -> "LogicMapEditor":
+        """
+        Create a LogicMapEditor for Human-in-the-Loop sessions.
+
+        The editor uses the grading LLM (stronger model) to interpret
+        natural language feedback and refine Logic Maps.
+        """
+        from synkro.interactive.logic_map_editor import LogicMapEditor
+        return LogicMapEditor(llm=self.grading_llm)
+
+
+__all__ = ["ComponentFactory"]
+

synkro/formatters/__init__.py

@@ -0,0 +1,12 @@
+"""Output formatters for different training data formats."""
+
+from synkro.formatters.sft import SFTFormatter
+from synkro.formatters.qa import QAFormatter
+from synkro.formatters.tool_call import ToolCallFormatter
+
+__all__ = [
+    "SFTFormatter",
+    "QAFormatter",
+    "ToolCallFormatter",
+]
+

synkro/formatters/qa.py

@@ -0,0 +1,98 @@
+"""QA (Question-Answer) formatter."""
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synkro.types.core import Trace
+
+
+class QAFormatter:
+    """
+    Format traces for Question-Answer datasets.
+
+    Outputs OpenAI-compatible messages format for finetuning compatibility
+    with OpenAI, TogetherAI, and similar platforms.
+
+    Example output:
+        {"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
+
+    For multi-turn traces, all messages are included in the output.
+    """
+
+    def __init__(self, include_context: bool = True, include_metadata: bool = False):
+        """
+        Initialize the QA formatter.
+
+        Args:
+            include_context: If True, include context in system message
+            include_metadata: If True, include scenario metadata
+        """
+        self.include_context = include_context
+        self.include_metadata = include_metadata
+
+    def format(self, traces: list["Trace"]) -> list[dict]:
+        """
+        Format traces as OpenAI-compatible messages format.
+
+        Args:
+            traces: List of traces to format
+
+        Returns:
+            List of examples with 'messages' key containing role/content dicts
+        """
+        examples = []
+
+        for trace in traces:
+            # Build messages list from trace
+            messages = []
+            for msg in trace.messages:
+                message_dict = {
+                    "role": msg.role,
+                    "content": msg.content or "",
+                }
+                messages.append(message_dict)
+
+            example = {"messages": messages}
+
+            if self.include_metadata:
+                example["metadata"] = {
+                    "scenario": trace.scenario.description,
+                    "context": trace.scenario.context,
+                    "category": trace.scenario.category,
+                    "turn_count": sum(1 for m in trace.messages if m.role == "assistant"),
+                }
+
+            examples.append(example)
+
+        return examples
+
+    def save(self, traces: list["Trace"], path: str | Path) -> None:
+        """
+        Save formatted traces to a JSONL file.
+
+        Args:
+            traces: List of traces to save
+            path: Output file path
+        """
+        path = Path(path)
+        examples = self.format(traces)
+
+        with open(path, "w") as f:
+            for example in examples:
+                f.write(json.dumps(example) + "\n")
+
+    def to_jsonl(self, traces: list["Trace"]) -> str:
+        """
+        Convert traces to JSONL string.
+
+        Args:
+            traces: List of traces to convert
+
+        Returns:
+            JSONL formatted string
+        """
+        examples = self.format(traces)
+        return "\n".join(json.dumps(e) for e in examples)
+

synkro/formatters/sft.py

@@ -0,0 +1,90 @@
+"""SFT (Supervised Fine-Tuning) formatter."""
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synkro.types.core import Trace
+
+
+class SFTFormatter:
+    """
+    Format traces for Supervised Fine-Tuning (SFT).
+
+    SFT format is a simple array of conversations, each with messages.
+    This is the standard format used by OpenAI, HuggingFace, and most
+    fine-tuning platforms.
+
+    Example output:
+        {"messages": [{"role": "system", "content": "..."}, ...]}
+        {"messages": [{"role": "system", "content": "..."}, ...]}
+    """
+
+    def __init__(self, include_metadata: bool = False):
+        """
+        Initialize the SFT formatter.
+
+        Args:
+            include_metadata: If True, include trace metadata in output
+        """
+        self.include_metadata = include_metadata
+
+    def format(self, traces: list["Trace"]) -> list[dict]:
+        """
+        Format traces as SFT training examples.
+
+        Args:
+            traces: List of traces to format
+
+        Returns:
+            List of SFT examples (dicts with 'messages' key)
+        """
+        examples = []
+
+        for trace in traces:
+            example = {
+                "messages": [
+                    {"role": m.role, "content": m.content} for m in trace.messages
+                ]
+            }
+
+            if self.include_metadata:
+                example["metadata"] = {
+                    "scenario": trace.scenario.description,
+                    "category": trace.scenario.category,
+                    "grade": trace.grade.model_dump() if trace.grade else None,
+                }
+
+            examples.append(example)
+
+        return examples
+
+    def save(self, traces: list["Trace"], path: str | Path) -> None:
+        """
+        Save formatted traces to a JSONL file.
+
+        Args:
+            traces: List of traces to save
+            path: Output file path (should end in .jsonl)
+        """
+        path = Path(path)
+        examples = self.format(traces)
+
+        with open(path, "w") as f:
+            for example in examples:
+                f.write(json.dumps(example) + "\n")
+
+    def to_jsonl(self, traces: list["Trace"]) -> str:
+        """
+        Convert traces to JSONL string.
+
+        Args:
+            traces: List of traces to convert
+
+        Returns:
+            JSONL formatted string
+        """
+        examples = self.format(traces)
+        return "\n".join(json.dumps(e) for e in examples)
+

synkro/formatters/tool_call.py

@@ -0,0 +1,127 @@
+"""Tool Call formatter for training data."""
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synkro.types.core import Trace
+
+
+class ToolCallFormatter:
+    """
+    Format traces with tool calls for fine-tuning.
+    
+    Outputs OpenAI function calling format compatible with most fine-tuning platforms.
+    
+    Example output:
+        {
+          "messages": [
+            {"role": "system", "content": "You have access to: web_search(query)"},
+            {"role": "user", "content": "What's the weather in NYC?"},
+            {"role": "assistant", "content": null, "tool_calls": [
+              {"id": "call_1", "type": "function", "function": {"name": "web_search", "arguments": "{\\"query\\": \\"weather NYC\\"}"}}
+            ]},
+            {"role": "tool", "tool_call_id": "call_1", "content": "NYC: 72°F, sunny"},
+            {"role": "assistant", "content": "The weather in NYC is currently 72°F and sunny."}
+          ]
+        }
+    """
+
+    def __init__(self, include_metadata: bool = False):
+        """
+        Initialize the ToolCallFormatter.
+        
+        Args:
+            include_metadata: If True, include trace metadata in output
+        """
+        self.include_metadata = include_metadata
+
+    def format(self, traces: list["Trace"]) -> list[dict]:
+        """
+        Format traces as tool-calling training examples.
+        
+        Args:
+            traces: List of traces to format
+            
+        Returns:
+            List of formatted examples with tool calls
+        """
+        examples = []
+        
+        for trace in traces:
+            messages = []
+            
+            for m in trace.messages:
+                msg = {"role": m.role}
+                
+                # Handle content (can be None for tool-calling assistant messages)
+                if m.content is not None:
+                    msg["content"] = m.content
+                elif m.role == "assistant" and m.tool_calls:
+                    msg["content"] = None
+                else:
+                    msg["content"] = ""
+                
+                # Handle tool calls
+                if m.tool_calls:
+                    msg["tool_calls"] = [
+                        {
+                            "id": tc.id,
+                            "type": tc.type,
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments,
+                            }
+                        }
+                        for tc in m.tool_calls
+                    ]
+                
+                # Handle tool response
+                if m.tool_call_id:
+                    msg["tool_call_id"] = m.tool_call_id
+                
+                messages.append(msg)
+            
+            example = {"messages": messages}
+            
+            if self.include_metadata:
+                example["metadata"] = {
+                    "scenario": trace.scenario.description,
+                    "category": trace.scenario.category,
+                    "grade": trace.grade.model_dump() if trace.grade else None,
+                    "has_tool_calls": trace.has_tool_calls,
+                }
+            
+            examples.append(example)
+        
+        return examples
+
+    def save(self, traces: list["Trace"], path: str | Path) -> None:
+        """
+        Save formatted traces to a JSONL file.
+        
+        Args:
+            traces: List of traces to save
+            path: Output file path (should end in .jsonl)
+        """
+        path = Path(path)
+        examples = self.format(traces)
+        
+        with open(path, "w") as f:
+            for example in examples:
+                f.write(json.dumps(example) + "\n")
+
+    def to_jsonl(self, traces: list["Trace"]) -> str:
+        """
+        Convert traces to JSONL string.
+        
+        Args:
+            traces: List of traces to convert
+            
+        Returns:
+            JSONL formatted string
+        """
+        examples = self.format(traces)
+        return "\n".join(json.dumps(e) for e in examples)
+

synkro/generation/__init__.py

@@ -0,0 +1,9 @@
+"""Generation components for creating training data."""
+
+from synkro.generation.generator import Generator
+from synkro.generation.scenarios import ScenarioGenerator
+from synkro.generation.responses import ResponseGenerator
+from synkro.generation.planner import Planner
+
+__all__ = ["Generator", "ScenarioGenerator", "ResponseGenerator", "Planner"]
+