synkro 0.4.5__py3-none-any.whl

synkro/__init__.py

@@ -0,0 +1,165 @@
+"""
+Synkro - Generate high-quality training datasets from any document.
+
+Modular Usage (recommended):
+    >>> from synkro.pipelines import create_pipeline
+    >>> from synkro.models.openai import OpenAI
+    >>> from synkro.types import DatasetType
+    >>>
+    >>> pipeline = create_pipeline(
+    ...     model=OpenAI.GPT_5_MINI,
+    ...     dataset_type=DatasetType.SFT,
+    ... )
+    >>> dataset = pipeline.generate("policy text", traces=50)
+    >>> dataset.save("training.jsonl")
+
+Simple Usage:
+    >>> import synkro
+    >>> dataset = synkro.generate("Your policy text...")
+    >>> dataset.save("training.jsonl")
+
+Silent Mode (for embedding/testing):
+    >>> from synkro import SilentReporter, create_pipeline
+    >>> pipeline = create_pipeline(reporter=SilentReporter())
+    >>> dataset = pipeline.generate("policy text")  # No console output
+
+Tool Call Dataset:
+    >>> from synkro import create_pipeline, ToolDefinition, DatasetType
+    >>> web_search = ToolDefinition(
+    ...     name="web_search",
+    ...     description="Search the web",
+    ...     parameters={"type": "object", "properties": {"query": {"type": "string"}}}
+    ... )
+    >>> pipeline = create_pipeline(
+    ...     dataset_type=DatasetType.TOOL_CALL,
+    ...     tools=[web_search],
+    ... )
+    >>> dataset = pipeline.generate("Search guidelines", traces=50)
+"""
+
+from synkro.pipelines import create_pipeline
+from synkro.models import OpenAI, Anthropic, Google
+from synkro.types import DatasetType, Message, Scenario, Trace, GradeResult, Plan, Category
+from synkro.types import ToolDefinition, ToolCall, ToolFunction, ToolResult
+from synkro.core.policy import Policy
+from synkro.core.dataset import Dataset
+from synkro.llm.client import LLM
+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.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.formatters.sft import SFTFormatter
+from synkro.formatters.qa import QAFormatter
+from synkro.formatters.tool_call import ToolCallFormatter
+from synkro.prompts import SystemPrompt, ScenarioPrompt, ResponsePrompt, GradePrompt
+from synkro.reporting import ProgressReporter, RichReporter, SilentReporter
+
+__version__ = "0.4.5"
+
+__all__ = [
+    # Pipeline creation
+    "create_pipeline",
+    # Quick function
+    "generate",
+    # Dataset type enum
+    "DatasetType",
+    # Core classes
+    "Policy",
+    "Dataset",
+    "Trace",
+    "Scenario",
+    "Message",
+    "GradeResult",
+    "Plan",
+    "Category",
+    # Tool types
+    "ToolDefinition",
+    "ToolCall",
+    "ToolFunction",
+    "ToolResult",
+    # Generation
+    "Generator",
+    "ScenarioGenerator",
+    "ResponseGenerator",
+    "Planner",
+    # Quality
+    "Grader",
+    "Refiner",
+    "ToolCallGrader",
+    "ToolCallRefiner",
+    # LLM
+    "LLM",
+    # Prompts
+    "SystemPrompt",
+    "ScenarioPrompt",
+    "ResponsePrompt",
+    "GradePrompt",
+    # Formatters
+    "SFTFormatter",
+    "QAFormatter",
+    "ToolCallFormatter",
+    # Reporters
+    "ProgressReporter",
+    "RichReporter",
+    "SilentReporter",
+    # Model enums (OpenAI, Anthropic, Google supported)
+    "OpenAI",
+    "Anthropic",
+    "Google",
+]
+
+
+def generate(
+    policy: str | Policy,
+    traces: int = 20,
+    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,
+) -> Dataset:
+    """
+    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)
+        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)
+
+    Returns:
+        Dataset object with generated traces
+
+    Example:
+        >>> import synkro
+        >>> dataset = synkro.generate("All expenses over $50 require approval")
+        >>> dataset.save("training.jsonl")
+        
+        >>> # Silent mode
+        >>> from synkro import SilentReporter
+        >>> dataset = synkro.generate(policy, reporter=SilentReporter())
+    """
+    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,
+    )
+
+    return generator.generate(policy, traces=traces)

synkro/cli.py

@@ -0,0 +1,120 @@
+"""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)",
+    ),
+):
+    """
+    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
+    """
+    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,
+    )
+
+    # 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"]
+

synkro/core/dataset.py

@@ -0,0 +1,233 @@
+"""Dataset class for managing generated traces."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Iterator
+
+from pydantic import BaseModel, Field
+from rich.console import Console
+
+from synkro.types.core import Trace
+
+console = Console()
+
+
+class Dataset(BaseModel):
+    """
+    A collection of generated training traces.
+
+    Provides methods for filtering, saving, and exporting traces
+    in various formats.
+
+    Examples:
+        >>> dataset = generator.generate(policy, traces=100)
+
+        >>> # Filter to only passing traces
+        >>> passing = dataset.filter(passed=True)
+
+        >>> # Save to JSONL
+        >>> dataset.save("training.jsonl")
+
+        >>> # Push to HuggingFace
+        >>> dataset.to_huggingface().push_to_hub("my-org/dataset")
+    """
+
+    traces: list[Trace] = Field(default_factory=list)
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __len__(self) -> int:
+        return len(self.traces)
+
+    def __iter__(self) -> Iterator[Trace]:
+        return iter(self.traces)
+
+    def __getitem__(self, idx: int) -> Trace:
+        return self.traces[idx]
+
+    def filter(
+        self,
+        passed: bool | None = None,
+        category: str | None = None,
+        min_length: int | None = None,
+    ) -> "Dataset":
+        """
+        Filter traces by criteria.
+
+        Args:
+            passed: Filter by grade pass/fail status
+            category: Filter by scenario category
+            min_length: Minimum response length in characters
+
+        Returns:
+            New Dataset with filtered traces
+        """
+        filtered = self.traces
+
+        if passed is not None:
+            filtered = [
+                t for t in filtered if t.grade and t.grade.passed == passed
+            ]
+
+        if category is not None:
+            filtered = [
+                t for t in filtered if t.scenario.category == category
+            ]
+
+        if min_length is not None:
+            filtered = [
+                t for t in filtered if len(t.assistant_message) >= min_length
+            ]
+
+        return Dataset(traces=filtered)
+
+    @property
+    def passing_rate(self) -> float:
+        """Get the percentage of traces that passed grading."""
+        if not self.traces:
+            return 0.0
+
+        passed = sum(1 for t in self.traces if t.grade and t.grade.passed)
+        return passed / len(self.traces)
+
+    @property
+    def categories(self) -> list[str]:
+        """Get unique categories in the dataset."""
+        return list(set(t.scenario.category for t in self.traces if t.scenario.category))
+
+    def save(self, path: str | Path | None = None, format: str = "sft") -> "Dataset":
+        """
+        Save dataset to a JSONL file.
+
+        Args:
+            path: Output file path (auto-generated if not provided)
+            format: Output format - "sft", "qa", or "tool_call"
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> dataset.save()  # Auto-names: synkro_sft_2024-01-15.jsonl
+            >>> dataset.save("training.jsonl")
+            >>> dataset.save("qa_data.jsonl", format="qa")
+            >>> dataset.save("tools.jsonl", format="tool_call")
+        """
+        from synkro.formatters import SFTFormatter, QAFormatter, ToolCallFormatter
+
+        # Auto-generate filename if not provided
+        if path is None:
+            timestamp = datetime.now().strftime("%Y-%m-%d_%H%M")
+            path = f"synkro_{format}_{timestamp}.jsonl"
+        
+        path = Path(path)
+
+        if format == "sft":
+            SFTFormatter().save(self.traces, path)
+        elif format == "qa":
+            QAFormatter().save(self.traces, path)
+        elif format == "tool_call":
+            ToolCallFormatter().save(self.traces, path)
+        else:
+            raise ValueError(f"Unknown format: {format}. Use 'sft', 'qa', or 'tool_call'")
+        
+        # Print confirmation
+        file_size = path.stat().st_size
+        size_str = f"{file_size / 1024:.1f} KB" if file_size < 1024 * 1024 else f"{file_size / 1024 / 1024:.1f} MB"
+        console.print(f"[green]📁 Saved:[/green] {path} ({size_str})")
+        
+        return self
+
+    def to_jsonl(self, format: str = "sft") -> str:
+        """
+        Convert dataset to JSONL string.
+
+        Args:
+            format: Output format - "sft", "qa", or "tool_call"
+
+        Returns:
+            JSONL formatted string
+        """
+        from synkro.formatters import SFTFormatter, QAFormatter, ToolCallFormatter
+
+        if format == "sft":
+            return SFTFormatter().to_jsonl(self.traces)
+        elif format == "qa":
+            return QAFormatter().to_jsonl(self.traces)
+        elif format == "tool_call":
+            return ToolCallFormatter().to_jsonl(self.traces)
+        else:
+            raise ValueError(f"Unknown format: {format}. Use 'sft', 'qa', or 'tool_call'")
+
+    def to_huggingface(self):
+        """
+        Convert to HuggingFace Dataset.
+
+        Returns:
+            HuggingFace Dataset object
+
+        Example:
+            >>> hf_dataset = dataset.to_huggingface()
+            >>> hf_dataset.push_to_hub("my-org/policy-traces")
+        """
+        try:
+            from datasets import Dataset as HFDataset
+
+            # Convert to SFT format for HF
+            from synkro.formatters import SFTFormatter
+
+            examples = SFTFormatter(include_metadata=True).format(self.traces)
+            return HFDataset.from_list(examples)
+        except ImportError:
+            raise ImportError(
+                "datasets is required for HuggingFace export. "
+                "Install with: pip install datasets"
+            )
+
+    def to_dict(self) -> dict:
+        """
+        Convert dataset to a dictionary.
+
+        Returns:
+            Dictionary with trace data
+        """
+        return {
+            "traces": [t.model_dump() for t in self.traces],
+            "stats": {
+                "total": len(self.traces),
+                "passing_rate": self.passing_rate,
+                "categories": self.categories,
+            },
+        }
+
+    def summary(self) -> str:
+        """
+        Get a summary of the dataset.
+
+        Returns:
+            Human-readable summary string
+        """
+        lines = [
+            f"Dataset Summary",
+            f"===============",
+            f"Total traces: {len(self.traces)}",
+            f"Passing rate: {self.passing_rate:.1%}",
+            f"Categories: {len(self.categories)}",
+        ]
+
+        if self.categories:
+            lines.append("")
+            lines.append("By category:")
+            for cat in self.categories:
+                count = sum(1 for t in self.traces if t.scenario.category == cat)
+                lines.append(f"  - {cat}: {count}")
+
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        return f"Dataset(traces={len(self.traces)}, passing={self.passing_rate:.1%})"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+