synkro 0.4.12__py3-none-any.whl

synkro/__init__.py

@@ -0,0 +1,179 @@
+"""
+Synkro - Generate high-quality training datasets from any document.
+
+Quick Start:
+    >>> import synkro
+    >>> dataset = synkro.generate("Your policy text...")
+    >>> dataset.save("training.jsonl")
+
+Pipeline Usage (more control):
+    >>> from synkro import create_pipeline, DatasetType
+    >>> pipeline = create_pipeline(dataset_type=DatasetType.SFT)
+    >>> dataset = pipeline.generate("policy text", traces=50)
+
+Access Logic Map (for inspection):
+    >>> result = pipeline.generate("policy text", return_logic_map=True)
+    >>> print(result.logic_map.rules)  # See extracted rules
+    >>> dataset = result.dataset
+
+Silent Mode:
+    >>> from synkro import SilentReporter, create_pipeline
+    >>> pipeline = create_pipeline(reporter=SilentReporter())
+
+Progress Callbacks:
+    >>> from synkro import CallbackReporter, create_pipeline
+    >>> reporter = CallbackReporter(
+    ...     on_progress=lambda event, data: print(f"{event}: {data}")
+    ... )
+    >>> pipeline = create_pipeline(reporter=reporter)
+
+Tool Call Dataset:
+    >>> from synkro import create_pipeline, ToolDefinition, DatasetType
+    >>> tools = [ToolDefinition(name="search", description="...", parameters={})]
+    >>> pipeline = create_pipeline(dataset_type=DatasetType.TOOL_CALL, tools=tools)
+
+Advanced Usage (power users):
+    >>> from synkro.advanced import LogicExtractor, TraceVerifier, LogicMap
+    >>> # Full access to Golden Trace internals
+"""
+
+# Dynamic version from package metadata
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("synkro")
+except Exception:
+    __version__ = "0.4.6"  # Fallback
+
+# =============================================================================
+# PRIMARY API - What most developers need
+# =============================================================================
+
+from synkro.pipelines import create_pipeline
+from synkro.models import OpenAI, Anthropic, Google
+from synkro.types import DatasetType
+from synkro.core.policy import Policy
+from synkro.core.dataset import Dataset
+from synkro.reporting import SilentReporter, RichReporter, CallbackReporter
+
+# Tool types (needed for TOOL_CALL dataset type)
+from synkro.types import ToolDefinition
+
+# =============================================================================
+# SECONDARY API - Less commonly needed
+# =============================================================================
+
+from synkro.types import Message, Scenario, Trace, GradeResult, Plan, Category
+from synkro.types import ToolCall, ToolFunction, ToolResult
+from synkro.reporting import ProgressReporter
+
+# GenerationResult for return_logic_map=True
+from synkro.pipeline.runner import GenerationResult
+
+__all__ = [
+    # Primary API
+    "create_pipeline",
+    "generate",
+    "DatasetType",
+    "Policy",
+    "Dataset",
+    "ToolDefinition",
+    # Reporters
+    "SilentReporter",
+    "RichReporter",
+    "CallbackReporter",
+    "ProgressReporter",
+    # Models
+    "OpenAI",
+    "Anthropic",
+    "Google",
+    # Result types
+    "GenerationResult",
+    # Data types (less common)
+    "Trace",
+    "Scenario",
+    "Message",
+    "GradeResult",
+    "Plan",
+    "Category",
+    "ToolCall",
+    "ToolFunction",
+    "ToolResult",
+]
+
+
+# Note: For advanced usage (LogicMap, TraceVerifier, etc.), use:
+# from synkro.advanced import ...
+
+
+def generate(
+    policy: str | Policy,
+    traces: int = 20,
+    turns: int | str = "auto",
+    dataset_type: DatasetType = DatasetType.SFT,
+    generation_model: OpenAI | Anthropic | Google | str = OpenAI.GPT_5_MINI,
+    grading_model: OpenAI | Anthropic | Google | str = OpenAI.GPT_52,
+    max_iterations: int = 3,
+    skip_grading: bool = False,
+    reporter: ProgressReporter | None = None,
+    return_logic_map: bool = False,
+    enable_hitl: bool = True,
+) -> Dataset | GenerationResult:
+    """
+    Generate training traces from a policy document.
+
+    This is a convenience function. For more control, use create_pipeline().
+
+    Args:
+        policy: Policy text or Policy object
+        traces: Number of traces to generate (default: 20)
+        turns: Conversation turns per trace. Use int for fixed turns, or "auto"
+            for policy complexity-driven turns (Simple=1-2, Conditional=3, Complex=5+)
+        dataset_type: Type of dataset - SFT (default) or QA
+        generation_model: Model for generating (default: gpt-5-mini)
+        grading_model: Model for grading (default: gpt-5.2)
+        max_iterations: Max refinement iterations per trace (default: 3)
+        skip_grading: Skip grading phase for faster generation (default: False)
+        reporter: Progress reporter (default: RichReporter for console output)
+        return_logic_map: If True, return GenerationResult with Logic Map access
+        enable_hitl: Enable Human-in-the-Loop Logic Map editing (default: False)
+
+    Returns:
+        Dataset (default) or GenerationResult if return_logic_map=True
+
+    Example:
+        >>> import synkro
+        >>> dataset = synkro.generate("All expenses over $50 require approval")
+        >>> dataset.save("training.jsonl")
+
+        >>> # Access Logic Map
+        >>> result = synkro.generate(policy, return_logic_map=True)
+        >>> print(result.logic_map.rules)
+        >>> dataset = result.dataset
+
+        >>> # Multi-turn with fixed 3 turns
+        >>> dataset = synkro.generate(policy, turns=3)
+
+        >>> # Interactive Logic Map editing
+        >>> dataset = synkro.generate(policy, enable_hitl=True)
+
+        >>> # Silent mode
+        >>> from synkro import SilentReporter
+        >>> dataset = synkro.generate(policy, reporter=SilentReporter())
+    """
+    from synkro.generation.generator import Generator
+
+    if isinstance(policy, str):
+        policy = Policy(text=policy)
+
+    generator = Generator(
+        dataset_type=dataset_type,
+        generation_model=generation_model,
+        grading_model=grading_model,
+        max_iterations=max_iterations,
+        skip_grading=skip_grading,
+        reporter=reporter,
+        turns=turns,
+        enable_hitl=enable_hitl,
+    )
+
+    return generator.generate(policy, traces=traces, return_logic_map=return_logic_map)

synkro/advanced.py

@@ -0,0 +1,186 @@
+"""Advanced components for power users.
+
+This module exposes internal components for developers who need fine-grained
+control over the generation pipeline.
+
+Usage:
+    from synkro.advanced import (
+        # Golden Trace components
+        LogicExtractor,
+        GoldenScenarioGenerator,
+        GoldenResponseGenerator,
+        TraceVerifier,
+        GoldenRefiner,
+
+        # Types
+        LogicMap,
+        Rule,
+        GoldenScenario,
+        VerificationResult,
+        GenerationResult,
+
+        # Pipeline internals
+        GenerationPipeline,
+        ComponentFactory,
+    )
+
+Examples:
+    >>> # Extract Logic Map manually
+    >>> from synkro.advanced import LogicExtractor, LLM
+    >>> extractor = LogicExtractor(llm=LLM(model="gpt-4o"))
+    >>> logic_map = await extractor.extract(policy_text)
+    >>> print(logic_map.rules)
+
+    >>> # Verify a trace against Logic Map
+    >>> from synkro.advanced import TraceVerifier
+    >>> verifier = TraceVerifier()
+    >>> result = await verifier.verify(trace, logic_map, scenario)
+    >>> if not result.passed:
+    ...     print(f"Failed: {result.issues}")
+"""
+
+# Golden Trace components (The 4 Stages)
+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
+
+# Logic Map types
+from synkro.types.logic_map import (
+    LogicMap,
+    Rule,
+    RuleCategory,
+    GoldenScenario,
+    ScenarioType,
+    ReasoningStep,
+    VerificationResult,
+)
+
+# Pipeline internals
+from synkro.pipeline.runner import GenerationPipeline, GenerationResult
+from synkro.factory import ComponentFactory
+
+# Pipeline phases
+from synkro.pipeline.phases import (
+    PlanPhase,
+    LogicExtractionPhase,
+    GoldenScenarioPhase,
+    GoldenTracePhase,
+    GoldenToolCallPhase,
+    VerificationPhase,
+)
+
+# Low-level generators
+from synkro.generation.generator import Generator
+from synkro.generation.scenarios import ScenarioGenerator
+from synkro.generation.responses import ResponseGenerator
+from synkro.generation.planner import Planner
+from synkro.generation.follow_ups import FollowUpGenerator
+from synkro.generation.multiturn_responses import MultiTurnResponseGenerator
+
+# Quality components
+from synkro.quality.grader import Grader
+from synkro.quality.refiner import Refiner
+from synkro.quality.tool_grader import ToolCallGrader
+from synkro.quality.tool_refiner import ToolCallRefiner
+from synkro.quality.multiturn_grader import MultiTurnGrader
+
+# LLM client
+from synkro.llm.client import LLM
+
+# Prompts (for customization)
+from synkro.prompts import SystemPrompt, ScenarioPrompt, ResponsePrompt, GradePrompt
+from synkro.prompts.golden_templates import (
+    LOGIC_EXTRACTION_PROMPT,
+    GOLDEN_SCENARIO_PROMPT,
+    GOLDEN_TRACE_PROMPT,
+    VERIFICATION_PROMPT,
+    GOLDEN_REFINE_PROMPT,
+    GOLDEN_TOOL_TRACE_PROMPT,
+)
+
+# Formatters
+from synkro.formatters.sft import SFTFormatter
+from synkro.formatters.qa import QAFormatter
+from synkro.formatters.tool_call import ToolCallFormatter
+
+# Schemas (for structured output)
+from synkro.schemas import (
+    RuleExtraction,
+    LogicMapOutput,
+    GoldenScenarioOutput,
+    GoldenScenariosArray,
+    ReasoningStepOutput,
+    GoldenTraceOutput,
+    VerificationOutput,
+)
+
+
+__all__ = [
+    # Golden Trace components
+    "LogicExtractor",
+    "GoldenScenarioGenerator",
+    "GoldenResponseGenerator",
+    "GoldenToolCallResponseGenerator",
+    "TraceVerifier",
+    "GoldenRefiner",
+    # Logic Map types
+    "LogicMap",
+    "Rule",
+    "RuleCategory",
+    "GoldenScenario",
+    "ScenarioType",
+    "ReasoningStep",
+    "VerificationResult",
+    # Pipeline
+    "GenerationPipeline",
+    "GenerationResult",
+    "ComponentFactory",
+    # Phases
+    "PlanPhase",
+    "LogicExtractionPhase",
+    "GoldenScenarioPhase",
+    "GoldenTracePhase",
+    "GoldenToolCallPhase",
+    "VerificationPhase",
+    # Generators
+    "Generator",
+    "ScenarioGenerator",
+    "ResponseGenerator",
+    "Planner",
+    "FollowUpGenerator",
+    "MultiTurnResponseGenerator",
+    # Quality
+    "Grader",
+    "Refiner",
+    "ToolCallGrader",
+    "ToolCallRefiner",
+    "MultiTurnGrader",
+    # LLM
+    "LLM",
+    # Prompts
+    "SystemPrompt",
+    "ScenarioPrompt",
+    "ResponsePrompt",
+    "GradePrompt",
+    "LOGIC_EXTRACTION_PROMPT",
+    "GOLDEN_SCENARIO_PROMPT",
+    "GOLDEN_TRACE_PROMPT",
+    "VERIFICATION_PROMPT",
+    "GOLDEN_REFINE_PROMPT",
+    "GOLDEN_TOOL_TRACE_PROMPT",
+    # Formatters
+    "SFTFormatter",
+    "QAFormatter",
+    "ToolCallFormatter",
+    # Schemas
+    "RuleExtraction",
+    "LogicMapOutput",
+    "GoldenScenarioOutput",
+    "GoldenScenariosArray",
+    "ReasoningStepOutput",
+    "GoldenTraceOutput",
+    "VerificationOutput",
+]

synkro/cli.py

@@ -0,0 +1,128 @@
+"""Synkro CLI - Generate training data from the command line."""
+
+import typer
+from pathlib import Path
+from typing import Optional
+
+app = typer.Typer(
+    name="synkro",
+    help="Generate training datasets from documents.",
+    no_args_is_help=True,
+)
+
+
+@app.command()
+def generate(
+    source: str = typer.Argument(
+        ...,
+        help="Policy text, file path (.pdf, .docx, .txt, .md), folder path, or URL",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output", "-o",
+        help="Output file path (auto-generated if not specified)",
+    ),
+    traces: int = typer.Option(
+        20,
+        "--traces", "-n",
+        help="Number of traces to generate",
+    ),
+    format: str = typer.Option(
+        "sft",
+        "--format", "-f",
+        help="Output format: sft or qa",
+    ),
+    model: str = typer.Option(
+        "gpt-4o-mini",
+        "--model", "-m",
+        help="Model for generation (e.g., gpt-4o-mini, claude-3-5-sonnet, gemini-2.5-flash)",
+    ),
+    interactive: bool = typer.Option(
+        True,
+        "--interactive/--no-interactive", "-i/-I",
+        help="Enable interactive Logic Map editing before generation (enabled by default)",
+    ),
+):
+    """
+    Generate training data from a policy document.
+
+    Examples:
+
+        synkro generate policy.pdf
+
+        synkro generate policies/  # Load all files from folder
+
+        synkro generate "All expenses over $50 need approval" --traces 50
+
+        synkro generate handbook.docx -o training.jsonl -n 100
+
+        synkro generate policy.pdf --interactive  # Review and edit Logic Map
+    """
+    import synkro
+    from synkro import Policy
+
+    # Determine if source is text, file, or URL
+    source_path = Path(source)
+    
+    if source_path.exists():
+        # It's a file
+        policy = Policy.from_file(source_path)
+    elif source.startswith(("http://", "https://")):
+        # It's a URL
+        policy = Policy.from_url(source)
+    else:
+        # Treat as raw text
+        policy = Policy(text=source)
+
+    # Generate
+    dataset = synkro.generate(
+        policy,
+        traces=traces,
+        generation_model=model,
+        enable_hitl=interactive,
+    )
+
+    # Save
+    if output:
+        dataset.save(output, format=format)
+    else:
+        dataset.save(format=format)
+
+
+@app.command()
+def demo():
+    """
+    Run a quick demo with a built-in example policy.
+    """
+    import synkro
+    from synkro.examples import EXPENSE_POLICY
+    from rich.console import Console
+    
+    console = Console()
+    console.print("\n[cyan]Running demo with built-in expense policy...[/cyan]\n")
+    
+    dataset = synkro.generate(EXPENSE_POLICY, traces=5)
+    dataset.save("demo_output.jsonl")
+    
+    console.print("\n[green]Demo complete![/green]")
+    console.print("[dim]Check demo_output.jsonl for the generated training data.[/dim]\n")
+
+
+@app.command()
+def version():
+    """Show version information."""
+    import synkro
+    from rich.console import Console
+    
+    console = Console()
+    console.print(f"[cyan]synkro[/cyan] v{synkro.__version__}")
+
+
+def main():
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()
+

synkro/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core classes for policy and dataset management."""
+
+from synkro.core.policy import Policy
+from synkro.core.dataset import Dataset
+
+__all__ = ["Policy", "Dataset"]
+