synkro 0.4.36__py3-none-any.whl

synkro-0.4.36.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.36.dist-info/METADATA

@@ -0,0 +1,507 @@
+Metadata-Version: 2.4
+Name: synkro
+Version: 0.4.36
+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: pydantic>=2.0
+Requires-Dist: pymupdf>=1.24
+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** - Conversation (multi-turn), Instruction (single-turn), Evaluation (Q&A), and Tool Calling
+- **Eval Platform Support** - Export to LangSmith, Langfuse, or generic Q&A format
+- **Tool Call Training** - Generate OpenAI function calling format for teaching models to use custom tools
+- **Top LLM Providers** - OpenAI, Anthropic, Google, and local models (Ollama, vLLM)
+- **File Support** - PDF, DOCX, TXT, Markdown, URLs
+- **CLI Included** - Generate datasets from the command line
+- **Cost Tracking** - See total cost and LLM call breakdown after each generation
+
+## 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.CONVERSATION,
+)
+
+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
+
+| Type | Turns | Output Formats | Best For |
+|------|-------|----------------|----------|
+| **CONVERSATION** | Multi | sft, chatml | Fine-tuning chat models |
+| **INSTRUCTION** | 1 | sft, chatml | Instruction-following models |
+| **EVALUATION** | 1 | qa, langsmith, langfuse | LLM evaluation & benchmarks |
+| **TOOL_CALL** | Multi | tool_call, chatml | Teaching tool use |
+
+### Conversation (Default)
+
+```python
+from synkro.types import DatasetType
+
+pipeline = create_pipeline(dataset_type=DatasetType.CONVERSATION)
+dataset = pipeline.generate(policy)
+```
+
+Output (multi-turn):
+```json
+{"messages": [
+  {"role": "user", "content": "What's the approval process for $350?"},
+  {"role": "assistant", "content": "For a $350 expense, you need manager approval..."},
+  {"role": "user", "content": "What if my manager is unavailable?"},
+  {"role": "assistant", "content": "You can request approval from..."}
+]}
+```
+
+### Instruction
+
+```python
+pipeline = create_pipeline(dataset_type=DatasetType.INSTRUCTION)
+dataset = pipeline.generate(policy)
+```
+
+Output (single-turn):
+```json
+{"messages": [
+  {"role": "user", "content": "What's the approval process for $350?"},
+  {"role": "assistant", "content": "For a $350 expense, you need manager approval. Submit the expense report with receipt..."}
+]}
+```
+
+### Evaluation
+
+Generate Q&A datasets for LLM evaluation with ground truth:
+
+```python
+pipeline = create_pipeline(dataset_type=DatasetType.EVALUATION)
+dataset = pipeline.generate(policy, traces=50)
+
+# Save in different formats
+dataset.save("eval.jsonl", format="qa")         # Generic Q&A
+dataset.save("eval.jsonl", format="langsmith")  # LangSmith format
+dataset.save("eval.jsonl", format="langfuse")   # Langfuse format
+```
+
+Output (`format="qa"`):
+```json
+{
+  "question": "Can I submit a $200 expense without a receipt?",
+  "answer": "All expenses require receipts per policy...",
+  "expected_outcome": "Deny - missing receipt violates R003",
+  "ground_truth_rules": ["R003", "R005"],
+  "difficulty": "negative",
+  "category": "Receipt Requirements"
+}
+```
+
+Output (`format="langsmith"`):
+```json
+{
+  "inputs": {"question": "...", "context": "..."},
+  "outputs": {"answer": "..."},
+  "metadata": {"expected_outcome": "...", "ground_truth_rules": [...]}
+}
+```
+
+Output (`format="langfuse"`):
+```json
+{
+  "input": {"question": "...", "context": "..."},
+  "expectedOutput": {"answer": "...", "expected_outcome": "..."},
+  "metadata": {"ground_truth_rules": [...], "difficulty": "..."}
+}
+```
+
+### 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")  # OpenAI format
+dataset.save("tool_training.jsonl", format="chatml")     # ChatML with XML tags
+```
+
+**Output Formats:**
+
+OpenAI function calling (`format="tool_call"`):
+```json
+{"messages": [
+  {"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."}
+]}
+```
+
+ChatML with XML tags (`format="chatml"`):
+```json
+{"messages": [
+  {"role": "user", "content": "What's the weather in NYC?"},
+  {"role": "assistant", "content": "<tool_call>\n{\"name\": \"web_search\", \"arguments\": {\"query\": \"weather NYC\"}}\n</tool_call>"},
+  {"role": "tool", "content": "<tool_response>\nNYC: 72°F, sunny\n</tool_response>"},
+  {"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")
+```
+
+## Eval API
+
+Generate test scenarios and grade your own model's responses against policy compliance.
+
+```python
+import synkro
+
+# Generate scenarios with ground truth (no synthetic responses)
+result = synkro.generate_scenarios(
+    policy="Expenses over $50 require manager approval...",
+    count=100,
+)
+
+# Each scenario has ground truth labels
+for scenario in result.scenarios:
+    print(scenario.user_message)       # "Can I expense a $200 dinner?"
+    print(scenario.expected_outcome)   # "Requires manager approval per R001"
+    print(scenario.target_rule_ids)    # ["R001", "R003"]
+    print(scenario.scenario_type)      # "positive" | "negative" | "edge_case"
+
+# Grade YOUR model's responses
+for scenario in result.scenarios:
+    response = my_model(scenario.user_message)  # Your model
+    grade = synkro.grade(response, scenario, policy)
+
+    if not grade.passed:
+        print(f"Failed: {grade.feedback}")
+```
+
+### When to Use
+
+| Use Case | API |
+|----------|-----|
+| Generate training data | `synkro.generate()` |
+| Generate eval scenarios | `synkro.generate_scenarios()` |
+| Grade external model | `synkro.grade()` |
+
+### Scenario Types
+
+Scenarios are generated with balanced coverage:
+
+| Type | % | Description |
+|------|---|-------------|
+| `positive` | 35% | Happy path - user meets all criteria |
+| `negative` | 30% | Violations - user fails one criterion |
+| `edge_case` | 25% | Boundary conditions at exact limits |
+| `irrelevant` | 10% | Outside policy scope |
+
+### EvalScenario Fields
+
+```python
+scenario.user_message      # The test input
+scenario.expected_outcome  # Ground truth behavior
+scenario.target_rule_ids   # Rules being tested
+scenario.scenario_type     # positive/negative/edge_case/irrelevant
+scenario.category          # Policy category
+scenario.context           # Additional context
+```
+
+### Temperature
+
+Use `temperature` to control output diversity:
+
+```python
+# High temp for diverse scenario coverage
+result = synkro.generate_scenarios(policy, temperature=0.8)
+
+# Low temp for deterministic training data
+dataset = synkro.generate(policy, temperature=0.2)
+```
+
+## Cost & Performance
+
+Approximate costs using Gemini 2.5 Flash (multi-turn conversations):
+
+| Traces | LLM Calls | Time | Cost |
+|--------|-----------|------|------|
+| 100 | ~335 | ~13 min | ~$3 |
+| 500 | ~1,675 | ~1 hour | ~$14 |
+| 1000 | ~3,350 | ~2 hours | ~$28 |
+
+*Based on ~3.3 LLM calls per trace (generation + grading) with max_iterations=3. Actual costs vary by policy complexity and turn count.*
+
+## Local LLMs
+
+Run with Ollama, vLLM, or any OpenAI-compatible endpoint:
+
+```python
+from synkro import create_pipeline
+from synkro.models import Local
+
+# Ollama
+pipeline = create_pipeline(model=Local.OLLAMA("llama3.2"))
+
+# vLLM
+pipeline = create_pipeline(model=Local.VLLM("mistral-7b"))
+
+# Custom endpoint
+pipeline = create_pipeline(model=Local.CUSTOM("my-model", endpoint="http://localhost:8080"))
+```
+
+**CLI:**
+```bash
+synkro generate policy.pdf --provider ollama --model llama3.2
+synkro generate policy.pdf --provider vllm --endpoint http://localhost:8000
+```
+
+## CLI
+
+```bash
+# From file
+synkro generate policy.pdf --traces 50
+
+# From text
+synkro generate "All expenses over $50 need approval" -n 20
+
+# From URL
+synkro generate https://example.com/policy -o training.jsonl
+
+# Skip interactive mode
+synkro generate policy.pdf --no-interactive
+
+# Quick demo with built-in policy
+synkro demo
+```
+
+**Options:**
+- `--traces, -n` - Number of traces (default: 20)
+- `--output, -o` - Output file path
+- `--model, -m` - Model for generation
+- `--format, -f` - Output format: `sft`, `qa`, `langsmith`, `langfuse`, `tool_call`, `chatml`
+- `--provider, -p` - LLM provider for local models (`ollama`, `vllm`)
+- `--endpoint, -e` - Custom API endpoint URL
+- `--interactive/-i, --no-interactive/-I` - Review/edit extracted rules before generation (default: on)
+
+## Interactive Mode
+
+By default, synkro extracts policy rules into a Logic Map and lets you review/edit them before generation. The interactive session also shows the recommended conversation turns based on policy complexity:
+
+```
+╭─────────────────────────── Conversation Settings ────────────────────────────╮
+│  Complexity:  Conditional                                                    │
+│  Turns:       3                                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+╭────────────────────────── 📜 Logic Map (3 rules) ────────────────────────────╮
+│ ├── R001: Expenses over $50 require manager approval                         │
+│ ├── R002: Client meals limited to $75/person                                 │
+│ └── R003: Receipts required for all expenses                                 │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+Enter feedback: shorter conversations
+✓ Set to 2 turns (User requested shorter/simpler conversations)
+
+Enter feedback: add a rule for travel expenses
+✓ Added R004: Travel expenses over $500 require VP approval
+
+Enter feedback: done
+✅ Session complete - 1 rule change(s), 2 turns
+```
+
+You can adjust both **conversation turns** and **rules** using natural language:
+
+| Input | Action |
+|-------|--------|
+| `"shorter conversations"` | Reduce turns (1-2) |
+| `"I want 5 turns"` | Set specific turn count |
+| `"more thorough"` | Increase turns (5-6) |
+| `"remove R002"` | Delete a rule |
+| `"add a rule for..."` | Add new rule |
+
+Commands: `done`, `undo`, `reset`, `show R001`, `help`
+
+## Advanced Features
+
+### Checkpointing
+
+Resume interrupted generations:
+
+```python
+pipeline = create_pipeline(checkpoint_dir="./checkpoints")
+dataset = pipeline.generate(policy, traces=100)  # Resumes from checkpoint
+```
+
+### Dataset Operations
+
+```python
+# Filter by quality
+high_quality = dataset.filter(passed=True)
+
+# Remove duplicates
+unique = dataset.dedupe(threshold=0.85)
+
+# Check pass rate
+print(f"Pass rate: {dataset.passing_rate:.1%}")
+```
+
+### Folder Loading
+
+Generate from multiple documents at once:
+
+```python
+from synkro.core.policy import Policy
+
+policy = Policy.from_file("policies/")  # Loads all PDF, DOCX, TXT, MD files
+dataset = pipeline.generate(policy, traces=100)
+```
+
+### Thinking Mode
+
+Generate training data with explicit reasoning in `<think>` tags, compatible with Qwen3 and DeepSeek-R1:
+
+```python
+pipeline = create_pipeline(thinking=True)
+dataset = pipeline.generate(policy, traces=50)
+```
+
+Output:
+```json
+{"messages": [
+  {"role": "user", "content": "Can I expense a $350 team dinner?"},
+  {"role": "assistant", "content": "<think>\nLet me check the expense policy...\n- Rule: Expenses over $50 require manager approval\n- $350 exceeds the $50 threshold\n- Manager approval is required\n</think>\n\nFor a $350 team dinner, you'll need manager approval since it exceeds the $50 threshold. Please submit your expense report with the receipt and request approval from your manager."}
+]}
+```
+
+Works with all dataset types (`CONVERSATION`, `INSTRUCTION`, `TOOL_CALL`).
+
+## Logic Map Inspection
+
+Access the extracted rules programmatically:
+
+```python
+result = pipeline.generate(policy, traces=50, return_logic_map=True)
+
+# Inspect extracted rules
+for rule in result.logic_map.rules:
+    print(f"{rule.rule_id}: {rule.text}")
+
+# Get the dataset
+dataset = result.dataset
+```