synkro 0.4.5__py3-none-any.whl

synkro/types/__init__.py

@@ -0,0 +1,41 @@
+"""Type definitions for Synkro.
+
+Usage:
+    from synkro.types import DatasetType, Message, Trace
+    from synkro.types import ToolDefinition, ToolCall, ToolFunction
+"""
+
+from synkro.types.core import (
+    Role,
+    Message,
+    Scenario,
+    Trace,
+    GradeResult,
+    Plan,
+    Category,
+)
+from synkro.types.dataset_type import DatasetType
+from synkro.types.tool import (
+    ToolDefinition,
+    ToolCall,
+    ToolFunction,
+    ToolResult,
+)
+
+__all__ = [
+    # Dataset type
+    "DatasetType",
+    # Core types
+    "Role",
+    "Message",
+    "Scenario",
+    "Trace",
+    "GradeResult",
+    "Plan",
+    "Category",
+    # Tool types
+    "ToolDefinition",
+    "ToolCall",
+    "ToolFunction",
+    "ToolResult",
+]

synkro/types/core.py

@@ -0,0 +1,113 @@
+"""Core Pydantic models for Synkro."""
+
+from typing import Literal, Any
+from pydantic import BaseModel, Field
+
+
+Role = Literal["system", "user", "assistant", "tool"]
+
+
+class Message(BaseModel):
+    """
+    A single message in a conversation.
+    
+    Supports both regular chat messages and tool-calling messages.
+    
+    Examples:
+        >>> # Regular message
+        >>> Message(role="user", content="Hello")
+        
+        >>> # Assistant with tool call (tool_calls is list of dicts or ToolCall objects)
+        >>> Message(role="assistant", content=None, tool_calls=[...])
+        
+        >>> # Tool response
+        >>> Message(role="tool", content="Result", tool_call_id="call_123")
+    """
+
+    role: Role
+    content: str | None = None
+    tool_calls: list[Any] | None = Field(
+        default=None,
+        description="Tool calls made by the assistant (list of ToolCall or dicts)"
+    )
+    tool_call_id: str | None = Field(
+        default=None,
+        description="ID of the tool call this message responds to (for tool role)"
+    )
+    
+    def model_post_init(self, __context) -> None:
+        """Validate message structure based on role."""
+        # For backwards compatibility, ensure content is string for non-tool roles
+        if self.role in ("system", "user") and self.content is None:
+            self.content = ""
+
+
+class Scenario(BaseModel):
+    """A test scenario for trace generation."""
+
+    description: str = Field(description="The scenario description")
+    context: str = Field(description="Additional context and background")
+    category: str | None = Field(default=None, description="Category this scenario belongs to")
+
+
+class GradeResult(BaseModel):
+    """Result of grading a trace."""
+
+    passed: bool = Field(description="Whether the trace passes quality checks")
+    issues: list[str] = Field(default_factory=list, description="List of issues found")
+    feedback: str = Field(default="", description="Summary feedback for improvement")
+
+
+class Trace(BaseModel):
+    """A complete training trace with messages and metadata."""
+
+    messages: list[Message] = Field(description="The conversation messages")
+    scenario: Scenario = Field(description="The scenario this trace was generated from")
+    grade: GradeResult | None = Field(default=None, description="Grading result if graded")
+
+    @property
+    def system_message(self) -> str | None:
+        """Get the system message content."""
+        for m in self.messages:
+            if m.role == "system":
+                return m.content
+        return None
+
+    @property
+    def user_message(self) -> str:
+        """Get the first user message content."""
+        for m in self.messages:
+            if m.role == "user":
+                return m.content or ""
+        return ""
+
+    @property
+    def assistant_message(self) -> str:
+        """Get the last assistant message content."""
+        for m in reversed(self.messages):
+            if m.role == "assistant":
+                return m.content or ""
+        return ""
+    
+    @property
+    def has_tool_calls(self) -> bool:
+        """Check if this trace contains any tool calls."""
+        for m in self.messages:
+            if m.tool_calls:
+                return True
+        return False
+
+
+class Category(BaseModel):
+    """A category for organizing scenarios."""
+
+    name: str = Field(description="Category name")
+    description: str = Field(description="What this category tests")
+    count: int = Field(description="Number of traces to generate for this category")
+
+
+class Plan(BaseModel):
+    """A generation plan with categories."""
+
+    categories: list[Category] = Field(description="Categories with trace allocations")
+    reasoning: str = Field(description="Explanation of why these categories were chosen")

synkro/types/dataset_type.py

@@ -0,0 +1,30 @@
+"""Dataset type enum for steering generation pipeline."""
+
+from enum import Enum
+
+
+class DatasetType(str, Enum):
+    """
+    Type of dataset to generate.
+
+    The dataset type determines:
+    - Prompts used for scenario and response generation
+    - Grading criteria
+    - Output format and schema
+
+    Examples:
+        >>> from synkro import DatasetType
+        >>> synkro.generate(policy, dataset_type=DatasetType.QA)
+        >>> synkro.generate(policy, dataset_type=DatasetType.SFT)
+        >>> synkro.generate(policy, dataset_type=DatasetType.TOOL_CALL, tools=[...])
+    """
+
+    QA = "qa"
+    """Question-Answer pairs: {question, answer, context}"""
+
+    SFT = "sft"
+    """Supervised Fine-Tuning: {messages: [system, user, assistant]}"""
+
+    TOOL_CALL = "tool_call"
+    """Tool Calling: {messages: [..., {tool_calls: [...]}, {role: tool}, ...]}"""
+

synkro/types/tool.py

@@ -0,0 +1,94 @@
+"""Tool-related types for tool call trace generation."""
+
+from pydantic import BaseModel, Field
+
+
+class ToolFunction(BaseModel):
+    """Function details within a tool call."""
+    
+    name: str = Field(description="Name of the function to call")
+    arguments: str = Field(description="JSON string of function arguments")
+
+
+class ToolCall(BaseModel):
+    """A tool call made by the assistant."""
+    
+    id: str = Field(description="Unique identifier for this tool call")
+    type: str = Field(default="function", description="Type of tool call")
+    function: ToolFunction = Field(description="Function details")
+
+
+class ToolResult(BaseModel):
+    """Result from a tool execution."""
+    
+    tool_call_id: str = Field(description="ID of the tool call this responds to")
+    content: str = Field(description="The tool's response content")
+
+
+class ToolDefinition(BaseModel):
+    """
+    Definition of a tool that an agent can use.
+    
+    Examples:
+        >>> web_search = ToolDefinition(
+        ...     name="web_search",
+        ...     description="Search the web for current information",
+        ...     parameters={
+        ...         "type": "object",
+        ...         "properties": {
+        ...             "query": {"type": "string", "description": "Search query"}
+        ...         },
+        ...         "required": ["query"]
+        ...     },
+        ...     examples=[{"query": "weather in NYC"}],
+        ...     mock_responses=["NYC: 72°F, sunny"]
+        ... )
+    """
+    
+    name: str = Field(description="Name of the tool")
+    description: str = Field(description="What the tool does")
+    parameters: dict = Field(
+        description="JSON Schema for the tool's parameters",
+        default_factory=lambda: {"type": "object", "properties": {}}
+    )
+    examples: list[dict] = Field(
+        default_factory=list,
+        description="Example tool calls for few-shot learning"
+    )
+    mock_responses: list[str] = Field(
+        default_factory=list,
+        description="Example responses for simulation"
+    )
+    
+    def to_openai_format(self) -> dict:
+        """Convert to OpenAI function calling format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            }
+        }
+    
+    def to_system_prompt(self) -> str:
+        """Generate a system prompt description of this tool."""
+        params_desc = []
+        props = self.parameters.get("properties", {})
+        required = self.parameters.get("required", [])
+        
+        for param_name, param_info in props.items():
+            param_type = param_info.get("type", "any")
+            param_desc = param_info.get("description", "")
+            req_marker = " (required)" if param_name in required else ""
+            params_desc.append(f"    - {param_name}: {param_type}{req_marker} - {param_desc}")
+        
+        params_str = "\n".join(params_desc) if params_desc else "    (no parameters)"
+        
+        return f"""**{self.name}**: {self.description}
+  Parameters:
+{params_str}"""
+
+
+__all__ = ["ToolDefinition", "ToolCall", "ToolFunction", "ToolResult"]
+

synkro-0.4.5.data/data/examples/__init__.py

@@ -0,0 +1,148 @@
+"""Built-in example policies for instant demos."""
+
+EXPENSE_POLICY = """# Company Expense Policy
+
+## Approval Thresholds
+- Expenses under $50: No approval required
+- Expenses $50-$500: Manager approval required
+- Expenses over $500: VP approval required
+
+## Receipt Requirements
+- All expenses over $25 must have a receipt
+- Digital receipts are acceptable
+- Missing receipts require written justification within 48 hours
+
+## Categories
+- Travel: Flights, hotels, ground transportation, meals while traveling
+- Meals: Client meals, team events (max $75/person)
+- Software: Must be on pre-approved list, exceptions need IT approval
+- Equipment: Must be on asset tracking list if over $200
+- Office Supplies: Under $100 can be purchased directly
+
+## Reimbursement Timeline
+- Submit expenses within 30 days of purchase
+- Reimbursements processed within 14 business days
+- Late submissions require manager exception approval
+"""
+
+HR_HANDBOOK = """# Employee Handbook
+
+## Work Hours
+- Standard work week is 40 hours, Monday through Friday
+- Core hours are 10am to 3pm when all employees should be available
+- Flexible scheduling allowed with manager approval
+
+## Time Off
+- Full-time employees receive 15 days PTO per year
+- PTO accrues monthly (1.25 days per month)
+- Unused PTO can roll over up to 5 days
+- PTO requests must be submitted 2 weeks in advance for 3+ days
+
+## Remote Work
+- Hybrid schedule: minimum 2 days in office per week
+- Fully remote requires director approval
+- Home office stipend of $500 for remote workers
+
+## Performance Reviews
+- Annual reviews conducted in December
+- Mid-year check-ins in June
+- Goals set at start of fiscal year
+- Promotions considered during annual review cycle only
+"""
+
+REFUND_POLICY = """# Return and Refund Policy
+
+## Eligibility
+- Items can be returned within 30 days of purchase
+- Items must be unused and in original packaging
+- Receipt or proof of purchase required
+
+## Exceptions
+- Final sale items cannot be returned
+- Personalized items cannot be returned
+- Perishable goods cannot be returned after 7 days
+
+## Refund Process
+- Refunds issued to original payment method
+- Processing takes 5-10 business days
+- Shipping costs are non-refundable unless item was defective
+
+## Exchanges
+- Exchanges available within 30 days
+- Size exchanges free of charge
+- Different item exchanges treated as return + new purchase
+
+## Defective Items
+- Report defects within 14 days
+- Photos required for defect claims
+- Replacement or full refund offered for confirmed defects
+"""
+
+SUPPORT_GUIDELINES = """# Customer Support Guidelines
+
+## Response Times
+- Chat: Respond within 2 minutes
+- Email: Respond within 4 hours during business hours
+- Phone: Answer within 30 seconds, max hold time 3 minutes
+
+## Escalation Tiers
+- Tier 1: General questions, password resets, basic troubleshooting
+- Tier 2: Technical issues, billing disputes, account problems
+- Tier 3: Complex technical issues, executive escalations
+
+## Refund Authority
+- Tier 1 can issue refunds up to $50
+- Tier 2 can issue refunds up to $200
+- Tier 3 or manager approval needed for refunds over $200
+
+## Documentation
+- Log all customer interactions in CRM
+- Include customer sentiment and issue category
+- Note any promised follow-ups with deadlines
+"""
+
+SECURITY_POLICY = """# Information Security Policy
+
+## Password Requirements
+- Minimum 12 characters
+- Must include uppercase, lowercase, number, and symbol
+- Change every 90 days
+- Cannot reuse last 10 passwords
+
+## Access Control
+- Principle of least privilege applies
+- Access requests require manager approval
+- Quarterly access reviews mandatory
+- Terminate access within 24 hours of employee departure
+
+## Data Classification
+- Public: Marketing materials, job postings
+- Internal: Company announcements, policies
+- Confidential: Customer data, financials
+- Restricted: PII, payment info, credentials
+
+## Incident Response
+- Report security incidents within 1 hour
+- Do not attempt to investigate independently
+- Preserve evidence (don't delete logs or files)
+- Security team leads all incident response
+"""
+
+# All policies available as a list
+ALL_POLICIES = [
+    ("expense", EXPENSE_POLICY),
+    ("hr", HR_HANDBOOK),
+    ("refund", REFUND_POLICY),
+    ("support", SUPPORT_GUIDELINES),
+    ("security", SECURITY_POLICY),
+]
+
+__all__ = [
+    "EXPENSE_POLICY",
+    "HR_HANDBOOK", 
+    "REFUND_POLICY",
+    "SUPPORT_GUIDELINES",
+    "SECURITY_POLICY",
+    "ALL_POLICIES",
+]
+

synkro-0.4.5.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: synkro
+Version: 0.4.5
+Summary: Generate training datasets from any document
+Author: Murtaza Meerza
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dataset-generation,fine-tuning,llm,synthetic-data,training-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: html2text>=2020.1
+Requires-Dist: httpx>=0.25
+Requires-Dist: litellm>=1.40
+Requires-Dist: mammoth>=1.6
+Requires-Dist: marker-pdf>=0.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Synkro
+
+Turn policies, handbooks, and documentation into high-quality training data for fine-tuning LLMs.
+
+## Features
+
+- **Quality Evaluation** - Each response is graded and automatically refined if it fails
+- **Multiple Formats** - SFT (chat), QA (question-answer), and Tool Calling
+- **Tool Call Training** - Generate OpenAI function calling format for teaching models to use custom tools
+- **Top LLM Providers** - OpenAI, Anthropic, and Google
+- **File Support** - PDF, DOCX, TXT, Markdown, URLs
+- **CLI Included** - Generate datasets from the command line
+
+## Installation
+
+```bash
+pip install synkro
+```
+
+## Quick Start
+
+```python
+from synkro.pipelines import create_pipeline
+from synkro.models.google import Google
+from synkro.types import DatasetType
+
+pipeline = create_pipeline(
+    model=Google.GEMINI_25_FLASH,          # Fast generation
+    grading_model=Google.GEMINI_25_PRO,    # Quality grading
+    dataset_type=DatasetType.SFT,
+)
+
+dataset = pipeline.generate(
+    "All expenses over $50 require manager approval.",
+    traces=50,
+)
+dataset.save("training.jsonl")
+```
+
+### From Files
+
+```python
+from synkro.pipelines import create_pipeline
+from synkro.core.policy import Policy
+
+policy = Policy.from_file("handbook.pdf")  # PDF, DOCX, TXT, MD
+pipeline = create_pipeline()
+dataset = pipeline.generate(policy, traces=100)
+dataset.save()
+```
+
+### From URLs
+
+```python
+from synkro.core.policy import Policy
+
+policy = Policy.from_url("https://example.com/terms")
+dataset = pipeline.generate(policy)
+```
+
+## Dataset Types
+
+| Format | Output | Best For |
+|--------|--------|----------|
+| **SFT** | Chat messages | Fine-tuning chat models |
+| **QA** | Question-answer pairs | RAG systems, knowledge bases |
+| **TOOL_CALL** | Function calling format | Training models to use custom tools |
+
+### SFT (Default)
+
+```python
+from synkro.types import DatasetType
+
+pipeline = create_pipeline(dataset_type=DatasetType.SFT)
+dataset = pipeline.generate(policy)
+```
+
+Output:
+```json
+{"messages": [
+  {"role": "system", "content": "You are a policy expert..."},
+  {"role": "user", "content": "What's the approval process for $350?"},
+  {"role": "assistant", "content": "For a $350 expense, you need..."}
+]}
+```
+
+### QA
+
+```python
+pipeline = create_pipeline(dataset_type=DatasetType.QA)
+```
+
+Output:
+```json
+{"question": "What's the approval process?", "answer": "You need...", "context": "..."}
+```
+
+### Tool Calling
+
+Generate training data for teaching models when and how to use your custom tools:
+
+```python
+from synkro import create_pipeline, ToolDefinition, DatasetType
+
+# Define your tools
+web_search = ToolDefinition(
+    name="web_search",
+    description="Search the web for current information",
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Search query"}
+        },
+        "required": ["query"]
+    },
+    mock_responses=["NYC: 72°F, sunny", "BTC: $67,234"]
+)
+
+# Create pipeline with tools
+pipeline = create_pipeline(
+    dataset_type=DatasetType.TOOL_CALL,
+    tools=[web_search],
+)
+
+# Generate from tool usage guidelines
+dataset = pipeline.generate("""
+Use web_search for real-time data like weather, prices.
+Answer general questions directly without tools.
+""", traces=20)
+
+dataset.save("tool_training.jsonl", format="tool_call")
+```
+
+Output (OpenAI function calling format):
+```json
+{"messages": [
+  {"role": "system", "content": "You have access to: web_search..."},
+  {"role": "user", "content": "What's the weather in NYC?"},
+  {"role": "assistant", "content": null, "tool_calls": [
+    {"id": "call_abc", "type": "function", "function": {"name": "web_search", "arguments": "{\"query\": \"weather NYC\"}"}}
+  ]},
+  {"role": "tool", "tool_call_id": "call_abc", "content": "NYC: 72°F, sunny"},
+  {"role": "assistant", "content": "The weather in NYC is 72°F and sunny."}
+]}
+```
+
+## Evaluation & Grading
+
+Every response is graded on policy compliance, citations, and reasoning. Failed responses are automatically refined (up to N iterations).
+
+```python
+from synkro.pipelines import create_pipeline
+from synkro.models.openai import OpenAI
+
+pipeline = create_pipeline(
+    model=OpenAI.GPT_4O_MINI,       # Fast generation
+    grading_model=OpenAI.GPT_4O,    # Quality grading
+    max_iterations=3,               # Refinement attempts
+)
+
+dataset = pipeline.generate(policy, traces=100)
+
+# Check quality
+print(f"Pass rate: {dataset.passing_rate:.1%}")
+
+# Filter to only passing traces
+high_quality = dataset.filter(passed=True)
+high_quality.save("training.jsonl")
+```
+
+## CLI
+
+```bash
+# From file
+synkro generate policy.pdf --traces 50 --format sft
+
+# From text
+synkro generate "All expenses over $50 need approval" -n 20
+
+# From URL
+synkro generate https://example.com/policy -o training.jsonl
+```
+
+**Options:**
+- `--traces, -n` - Number of traces (default: 20)
+- `--format, -f` - Output format: sft, qa, or tool_call (default: sft)
+- `--output, -o` - Output file path
+- `--model, -m` - Model for generation