synkro 0.4.12__py3-none-any.whl

synkro/core/policy.py

@@ -0,0 +1,337 @@
+"""Policy document handling with multi-format support."""
+
+from pathlib import Path
+from typing import Sequence
+
+from pydantic import BaseModel, Field
+
+from synkro.errors import FileNotFoundError as SynkroFileNotFoundError, PolicyTooShortError
+
+
+MIN_POLICY_WORDS = 10  # Minimum words for meaningful generation
+
+# Supported file extensions
+SUPPORTED_EXTENSIONS = {".txt", ".md", ".pdf", ".docx"}
+
+
+class Policy(BaseModel):
+    """
+    A policy document to generate training data from.
+
+    Supports loading from multiple formats:
+    - Plain text (.txt, .md)
+    - PDF documents (.pdf) - via marker-pdf
+    - Word documents (.docx) - via mammoth
+
+    Can load from:
+    - Single file: Policy.from_file("compliance.pdf")
+    - Folder of files: Policy.from_file("policies/")
+    - Multiple files: Policy.from_files(["doc1.pdf", "doc2.docx"])
+    - URL: Policy.from_url("https://example.com/policy")
+
+    Examples:
+        >>> # From text
+        >>> policy = Policy(text="All expenses over $50 require approval")
+
+        >>> # From single file
+        >>> policy = Policy.from_file("compliance.pdf")
+
+        >>> # From folder (loads all supported files)
+        >>> policy = Policy.from_file("policies/")
+
+        >>> # From multiple files
+        >>> policy = Policy.from_files(["doc1.pdf", "doc2.docx", "doc3.txt"])
+
+        >>> # From URL
+        >>> policy = Policy.from_url("https://example.com/policy")
+    """
+
+    text: str = Field(description="Full policy text in markdown format")
+    source: str | None = Field(default=None, description="Source file path or URL")
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "Policy":
+        """
+        Load policy from a file or folder.
+
+        Supports: .txt, .md, .pdf, .docx
+        
+        If path is a directory, loads all supported files from that directory.
+        If path is a file, loads that single file.
+
+        Args:
+            path: Path to the policy file or folder containing policy files
+
+        Returns:
+            Policy object with extracted text (combined if multiple files)
+
+        Examples:
+            >>> # Single file
+            >>> policy = Policy.from_file("compliance.pdf")
+            >>> len(policy.text) > 0
+            True
+            
+            >>> # Folder of documents
+            >>> policy = Policy.from_file("policies/")
+            >>> len(policy.text) > 0
+            True
+        """
+        path = Path(path)
+
+        if not path.exists():
+            # Find similar files to suggest
+            similar = []
+            if path.parent.exists():
+                for ext in SUPPORTED_EXTENSIONS:
+                    similar.extend(path.parent.glob(f"*{ext}"))
+            similar_names = [str(f.name) for f in similar[:5]]
+            raise SynkroFileNotFoundError(str(path), similar_names if similar_names else None)
+
+        # If it's a directory, load all supported files
+        if path.is_dir():
+            return cls._from_folder(path)
+        
+        # Otherwise, load single file
+        return cls._load_single_file(path)
+
+    @classmethod
+    def _load_single_file(cls, path: Path) -> "Policy":
+        """
+        Load a single policy file.
+        
+        Args:
+            path: Path to a single file
+            
+        Returns:
+            Policy object with extracted text
+        """
+        suffix = path.suffix.lower()
+
+        if suffix in (".txt", ".md"):
+            return cls(text=path.read_text(), source=str(path))
+
+        if suffix == ".pdf":
+            return cls._from_pdf(path)
+
+        if suffix == ".docx":
+            return cls._from_docx(path)
+
+        raise ValueError(f"Unsupported file type: {suffix}. Use .txt, .md, .pdf, or .docx")
+
+    @classmethod
+    def _from_folder(cls, folder_path: Path) -> "Policy":
+        """
+        Load all supported files from a folder.
+        
+        Args:
+            folder_path: Path to folder containing policy files
+            
+        Returns:
+            Policy object with combined text from all files
+            
+        Raises:
+            ValueError: If no supported files found in folder
+        """
+        # Find all supported files in folder (non-recursive)
+        files = [
+            f for f in folder_path.iterdir()
+            if f.is_file() and f.suffix.lower() in SUPPORTED_EXTENSIONS
+        ]
+        
+        if not files:
+            raise ValueError(
+                f"No supported policy files found in {folder_path}. "
+                f"Supported formats: {', '.join(SUPPORTED_EXTENSIONS)}"
+            )
+        
+        # Sort files for consistent ordering
+        files.sort(key=lambda f: f.name)
+        
+        # Load each file and combine
+        return cls.from_files(files, source_prefix=str(folder_path))
+
+    @classmethod
+    def from_files(
+        cls,
+        paths: Sequence[str | Path],
+        separator: str = "\n\n---\n\n",
+        source_prefix: str | None = None,
+    ) -> "Policy":
+        """
+        Load and combine multiple policy documents.
+
+        Args:
+            paths: List of paths to policy files
+            separator: String to separate documents (default: "\\n\\n---\\n\\n")
+            source_prefix: Optional prefix for source description (e.g., folder path)
+
+        Returns:
+            Policy object with combined text from all files
+
+        Raises:
+            ValueError: If paths list is empty
+            FileNotFoundError: If any file doesn't exist
+
+        Examples:
+            >>> # Multiple files
+            >>> policy = Policy.from_files(["doc1.pdf", "doc2.docx", "doc3.txt"])
+            >>> len(policy.text) > 0
+            True
+            
+            >>> # With custom separator
+            >>> policy = Policy.from_files(
+            ...     ["part1.txt", "part2.txt"],
+            ...     separator="\\n\\n=== NEXT DOCUMENT ===\\n\\n"
+            ... )
+        """
+        if not paths:
+            raise ValueError("paths list cannot be empty")
+
+        texts: list[str] = []
+        sources: list[str] = []
+        
+        for path in paths:
+            path_obj = Path(path)
+            
+            if not path_obj.exists():
+                raise SynkroFileNotFoundError(str(path_obj), None)
+            
+            if not path_obj.is_file():
+                raise ValueError(f"Path is not a file: {path_obj}")
+            
+            # Load the file
+            policy = cls._load_single_file(path_obj)
+            texts.append(policy.text)
+            sources.append(str(path_obj))
+        
+        # Combine texts
+        combined_text = separator.join(texts)
+        
+        # Create source description
+        if source_prefix:
+            combined_source = f"{source_prefix} ({len(sources)} files: {', '.join(Path(s).name for s in sources)})"
+        else:
+            combined_source = f"multiple_files ({len(sources)} files: {', '.join(Path(s).name for s in sources)})"
+        
+        return cls(text=combined_text, source=combined_source)
+
+    @classmethod
+    def _from_pdf(cls, path: Path) -> "Policy":
+        """
+        Parse PDF to markdown using marker-pdf.
+
+        Args:
+            path: Path to PDF file
+
+        Returns:
+            Policy with extracted markdown text
+        """
+        try:
+            from marker.convert import convert_single_pdf
+            from marker.models import load_all_models
+
+            models = load_all_models()
+            markdown, _, _ = convert_single_pdf(str(path), models)
+            return cls(text=markdown, source=str(path))
+        except ImportError:
+            raise ImportError(
+                "marker-pdf is required for PDF support. "
+                "Install with: pip install marker-pdf"
+            )
+
+    @classmethod
+    def _from_docx(cls, path: Path) -> "Policy":
+        """
+        Parse DOCX to markdown using mammoth.
+
+        Args:
+            path: Path to DOCX file
+
+        Returns:
+            Policy with extracted markdown text
+        """
+        try:
+            import mammoth
+
+            with open(path, "rb") as f:
+                result = mammoth.convert_to_markdown(f)
+                return cls(text=result.value, source=str(path))
+        except ImportError:
+            raise ImportError(
+                "mammoth is required for DOCX support. "
+                "Install with: pip install mammoth"
+            )
+
+    @classmethod
+    def from_url(cls, url: str) -> "Policy":
+        """
+        Fetch and parse policy from a URL.
+
+        Extracts main content and converts to markdown.
+
+        Args:
+            url: URL to fetch
+
+        Returns:
+            Policy with extracted content
+
+        Example:
+            >>> policy = Policy.from_url("https://example.com/terms")
+        """
+        try:
+            import httpx
+            from bs4 import BeautifulSoup
+            import html2text
+
+            response = httpx.get(url, follow_redirects=True)
+            response.raise_for_status()
+
+            soup = BeautifulSoup(response.text, "html.parser")
+
+            # Remove scripts, styles, nav, footer
+            for tag in soup(["script", "style", "nav", "footer", "header"]):
+                tag.decompose()
+
+            # Convert to markdown
+            h = html2text.HTML2Text()
+            h.ignore_links = False
+            h.ignore_images = True
+            markdown = h.handle(str(soup))
+
+            return cls(text=markdown, source=url)
+        except ImportError as e:
+            missing = str(e).split("'")[1] if "'" in str(e) else "required packages"
+            raise ImportError(
+                f"{missing} is required for URL support. "
+                "This should be installed automatically with synkro. "
+                "If you see this error, try: pip install --upgrade synkro"
+            )
+
+    @property
+    def word_count(self) -> int:
+        """Get the word count of the policy."""
+        return len(self.text.split())
+
+    @property
+    def char_count(self) -> int:
+        """Get the character count of the policy."""
+        return len(self.text)
+
+    def validate_length(self) -> None:
+        """
+        Validate that the policy has enough content for meaningful generation.
+        
+        Raises:
+            PolicyTooShortError: If policy is too short
+        """
+        if self.word_count < MIN_POLICY_WORDS:
+            raise PolicyTooShortError(self.word_count)
+
+    def __str__(self) -> str:
+        """String representation showing source and length."""
+        source = self.source or "inline"
+        return f"Policy(source={source}, words={self.word_count})"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+

synkro/errors.py

@@ -0,0 +1,178 @@
+"""Friendly error messages with fix suggestions."""
+
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+class SynkroError(Exception):
+    """Base exception for Synkro errors."""
+    
+    def __init__(self, message: str, suggestion: str = ""):
+        self.message = message
+        self.suggestion = suggestion
+        super().__init__(message)
+    
+    def print_friendly(self):
+        """Print a user-friendly error message."""
+        content = f"[red bold]{self.message}[/red bold]"
+        if self.suggestion:
+            content += f"\n\n[dim]{self.suggestion}[/dim]"
+        console.print(Panel(content, title="[red]Error[/red]", border_style="red"))
+
+
+class APIKeyError(SynkroError):
+    """Raised when API key is missing or invalid."""
+    
+    def __init__(self, provider: str = "OpenAI"):
+        provider_info = {
+            "openai": {
+                "env_var": "OPENAI_API_KEY",
+                "url": "https://platform.openai.com/api-keys",
+            },
+            "anthropic": {
+                "env_var": "ANTHROPIC_API_KEY",
+                "url": "https://console.anthropic.com/settings/keys",
+            },
+            "google": {
+                "env_var": "GEMINI_API_KEY",
+                "url": "https://aistudio.google.com/app/apikey",
+            },
+        }
+        
+        info = provider_info.get(provider.lower(), provider_info["openai"])
+        
+        message = f"{provider} API key not found or invalid"
+        suggestion = f"""To fix this, either:
+
+  1. Set environment variable:
+     export {info['env_var']}="your-key-here"
+
+  2. Pass directly:
+     synkro.generate(..., generation_model=LLM(api_key="..."))
+
+Get an API key at: {info['url']}"""
+        
+        super().__init__(message, suggestion)
+
+
+class FileNotFoundError(SynkroError):
+    """Raised when a policy file cannot be found."""
+    
+    def __init__(self, filepath: str, similar_files: list[str] | None = None):
+        message = f"Could not find file: {filepath}"
+        
+        suggestion_parts = []
+        if similar_files:
+            suggestion_parts.append("Did you mean one of these?")
+            for f in similar_files[:3]:
+                suggestion_parts.append(f"  → {f}")
+            suggestion_parts.append("")
+        
+        suggestion_parts.append("Or pass text directly:")
+        suggestion_parts.append('  synkro.generate("Your policy text here...")')
+        
+        super().__init__(message, "\n".join(suggestion_parts))
+
+
+class RateLimitError(SynkroError):
+    """Raised when hitting API rate limits."""
+    
+    def __init__(self, provider: str = "OpenAI", retry_after: int | None = None):
+        message = f"Rate limited by {provider}"
+        if retry_after:
+            message += f" (retry after {retry_after}s)"
+        
+        suggestion = """Tip: Reduce the number of traces or wait and retry:
+
+  synkro.generate(..., traces=10)
+
+Or use a different provider:
+  synkro.generate(..., generation_model=Google.GEMINI_25_FLASH)"""
+        
+        super().__init__(message, suggestion)
+
+
+class PolicyTooShortError(SynkroError):
+    """Raised when policy text is too short to generate meaningful data."""
+    
+    def __init__(self, word_count: int):
+        message = f"Policy too short ({word_count} words)"
+        suggestion = """Your policy needs more content to generate diverse training data.
+
+Minimum recommended: 50+ words with clear rules or guidelines.
+
+Example:
+  synkro.generate('''
+  All expenses over $50 require manager approval.
+  Expenses over $500 require VP approval.
+  Receipts are required for all purchases over $25.
+  ''')"""
+        
+        super().__init__(message, suggestion)
+
+
+class ModelNotFoundError(SynkroError):
+    """Raised when specified model doesn't exist."""
+    
+    def __init__(self, model: str):
+        message = f"Model not found: {model}"
+        suggestion = """Available models:
+
+  OpenAI:    OpenAI.GPT_4O_MINI, OpenAI.GPT_4O
+  Anthropic: Anthropic.CLAUDE_35_SONNET, Anthropic.CLAUDE_35_HAIKU
+  Google:    Google.GEMINI_25_FLASH, Google.GEMINI_25_PRO
+
+Or pass any model string: "gpt-4o-mini", "claude-3-5-sonnet-20241022", etc."""
+        
+        super().__init__(message, suggestion)
+
+
+def _detect_provider(error_str: str) -> str:
+    """Detect the provider from the error message."""
+    error_lower = error_str.lower()
+    if "gemini" in error_lower or "googleapis" in error_lower or "google" in error_lower:
+        return "Google"
+    if "anthropic" in error_lower or "claude" in error_lower:
+        return "Anthropic"
+    return "OpenAI"
+
+
+def handle_error(func):
+    """Decorator to catch and display friendly errors."""
+    import sys
+    
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except SynkroError as e:
+            e.print_friendly()
+            sys.exit(1)
+        except Exception as e:
+            # Try to convert common errors to friendly ones
+            error_str = str(e)
+            error_lower = error_str.lower()
+            
+            if "api key" in error_lower or "authentication" in error_lower or "unauthorized" in error_lower:
+                provider = _detect_provider(error_str)
+                friendly = APIKeyError(provider)
+                friendly.print_friendly()
+                sys.exit(1)
+            
+            if "rate limit" in error_lower or "429" in error_lower:
+                provider = _detect_provider(error_str)
+                friendly = RateLimitError(provider)
+                friendly.print_friendly()
+                sys.exit(1)
+            
+            if "not found" in error_lower and "model" in error_lower:
+                friendly = ModelNotFoundError(str(e))
+                friendly.print_friendly()
+                sys.exit(1)
+            
+            # Re-raise unknown errors
+            raise
+    
+    return wrapper
+

synkro/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",
+]
+