synkro 0.4.12__py3-none-any.whl

synkro/types/logic_map.py

@@ -0,0 +1,345 @@
+"""Logic Map types for Golden Trace generation.
+
+The Logic Map represents a policy as a directed acyclic graph (DAG) of rules,
+enabling grounded reasoning and verification of generated traces.
+"""
+
+import json
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class ScenarioType(str, Enum):
+    """Types of scenarios for balanced dataset generation."""
+
+    POSITIVE = "positive"      # Happy path - user meets all criteria
+    NEGATIVE = "negative"      # Violation - user fails one criterion
+    EDGE_CASE = "edge_case"    # Boundary - user at exact limit
+    IRRELEVANT = "irrelevant"  # Not covered by policy
+
+
+class RuleCategory(str, Enum):
+    """Categories of rules extracted from policy."""
+
+    CONSTRAINT = "constraint"      # Must/must not conditions
+    PERMISSION = "permission"      # Allowed/can do
+    PROCEDURE = "procedure"        # Step-by-step processes
+    EXCEPTION = "exception"        # Special cases/overrides
+
+
+class Rule(BaseModel):
+    """
+    A single rule extracted from the policy document.
+
+    Rules form nodes in the Logic Map DAG, with dependencies
+    indicating which rules must be evaluated first.
+
+    Examples:
+        >>> rule = Rule(
+        ...     rule_id="R001",
+        ...     text="Refunds are allowed within 30 days of purchase",
+        ...     condition="purchase date is within 30 days",
+        ...     action="allow refund",
+        ...     dependencies=[],
+        ...     category=RuleCategory.PERMISSION,
+        ... )
+    """
+
+    rule_id: str = Field(
+        description="Unique identifier (e.g., 'R001', 'R002')"
+    )
+    text: str = Field(
+        description="Exact rule text from the policy"
+    )
+    condition: str = Field(
+        description="The 'if' part - when this rule applies"
+    )
+    action: str = Field(
+        description="The 'then' part - what happens when rule applies"
+    )
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs that must be evaluated before this rule"
+    )
+    category: RuleCategory = Field(
+        description="Type of rule (constraint, permission, procedure, exception)"
+    )
+
+    def __hash__(self) -> int:
+        return hash(self.rule_id)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Rule):
+            return False
+        return self.rule_id == other.rule_id
+
+
+class LogicMap(BaseModel):
+    """
+    Directed Acyclic Graph (DAG) of rules extracted from a policy.
+
+    The Logic Map is the "Map of Truth" that enables:
+    - Grounded scenario generation with rule references
+    - Chain-of-thought reasoning with rule citations
+    - Verification that traces don't skip or hallucinate rules
+
+    Examples:
+        >>> logic_map = LogicMap(
+        ...     rules=[rule1, rule2, rule3],
+        ...     root_rules=["R001"],  # Entry points
+        ... )
+        >>> print(logic_map.get_rule("R001"))
+    """
+
+    rules: list[Rule] = Field(
+        description="All rules extracted from the policy"
+    )
+    root_rules: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs with no dependencies (entry points)"
+    )
+
+    def get_rule(self, rule_id: str) -> Rule | None:
+        """Get a rule by its ID."""
+        for rule in self.rules:
+            if rule.rule_id == rule_id:
+                return rule
+        return None
+
+    def get_dependents(self, rule_id: str) -> list[Rule]:
+        """Get all rules that depend on the given rule."""
+        return [r for r in self.rules if rule_id in r.dependencies]
+
+    def get_dependencies(self, rule_id: str) -> list[Rule]:
+        """Get all rules that the given rule depends on."""
+        rule = self.get_rule(rule_id)
+        if not rule:
+            return []
+        return [r for r in self.rules if r.rule_id in rule.dependencies]
+
+    def get_chain(self, rule_id: str) -> list[Rule]:
+        """
+        Get the full dependency chain for a rule (topologically sorted).
+
+        Returns all rules that must be evaluated before the given rule,
+        in the order they should be evaluated.
+        """
+        visited = set()
+        chain = []
+
+        def visit(rid: str):
+            if rid in visited:
+                return
+            visited.add(rid)
+            rule = self.get_rule(rid)
+            if rule:
+                for dep_id in rule.dependencies:
+                    visit(dep_id)
+                chain.append(rule)
+
+        visit(rule_id)
+        return chain
+
+    def validate_dag(self) -> bool:
+        """Verify the rules form a valid DAG (no cycles)."""
+        # Track visit state: 0=unvisited, 1=visiting, 2=visited
+        state = {r.rule_id: 0 for r in self.rules}
+
+        def has_cycle(rule_id: str) -> bool:
+            if state.get(rule_id, 0) == 1:  # Currently visiting = cycle
+                return True
+            if state.get(rule_id, 0) == 2:  # Already visited = ok
+                return False
+
+            state[rule_id] = 1  # Mark as visiting
+            rule = self.get_rule(rule_id)
+            if rule:
+                for dep_id in rule.dependencies:
+                    if has_cycle(dep_id):
+                        return True
+            state[rule_id] = 2  # Mark as visited
+            return False
+
+        for rule in self.rules:
+            if has_cycle(rule.rule_id):
+                return False
+        return True
+
+    def get_rules_by_category(self, category: RuleCategory) -> list[Rule]:
+        """Get all rules of a specific category."""
+        return [r for r in self.rules if r.category == category]
+
+    def to_display_string(self) -> str:
+        """Generate a human-readable representation of the Logic Map."""
+        lines = [f"Logic Map ({len(self.rules)} rules)"]
+        lines.append("=" * 40)
+
+        # Show root rules first
+        lines.append("\nRoot Rules (Entry Points):")
+        for rid in self.root_rules:
+            rule = self.get_rule(rid)
+            if rule:
+                lines.append(f"  {rid}: {rule.text[:60]}...")
+
+        # Show dependency chains
+        lines.append("\nDependency Chains:")
+        processed = set()
+        for rule in self.rules:
+            if rule.rule_id not in processed and rule.dependencies:
+                chain = " -> ".join(r.rule_id for r in self.get_chain(rule.rule_id))
+                lines.append(f"  {chain}")
+                processed.update(r.rule_id for r in self.get_chain(rule.rule_id))
+
+        return "\n".join(lines)
+
+    def save(self, path: str | Path) -> None:
+        """
+        Save the Logic Map to a JSON file.
+
+        Args:
+            path: File path to save to (e.g., "logic_map.json")
+
+        Examples:
+            >>> logic_map.save("logic_map.json")
+            >>> # Later, reload it
+            >>> logic_map = LogicMap.load("logic_map.json")
+        """
+        path = Path(path)
+        with open(path, "w") as f:
+            json.dump(self.model_dump(), f, indent=2)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "LogicMap":
+        """
+        Load a Logic Map from a JSON file.
+
+        Args:
+            path: File path to load from
+
+        Returns:
+            LogicMap instance
+
+        Examples:
+            >>> logic_map = LogicMap.load("logic_map.json")
+            >>> print(f"Loaded {len(logic_map.rules)} rules")
+        """
+        path = Path(path)
+        with open(path) as f:
+            data = json.load(f)
+        return cls.model_validate(data)
+
+
+class ReasoningStep(BaseModel):
+    """
+    A single step in the Chain-of-Thought reasoning.
+
+    Each step references exactly one rule and explains how it applies
+    (or doesn't apply) to the current scenario.
+    """
+
+    rule_id: str = Field(
+        description="The rule being evaluated in this step"
+    )
+    rule_text: str = Field(
+        description="The text of the rule"
+    )
+    applies: bool = Field(
+        description="Whether this rule applies to the scenario"
+    )
+    reasoning: str = Field(
+        description="Explanation of why the rule does/doesn't apply"
+    )
+    exclusions: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs that are excluded because this rule applies"
+    )
+
+
+class GoldenScenario(BaseModel):
+    """
+    A scenario with explicit type and rule targeting.
+
+    Extends the base Scenario concept with:
+    - Explicit scenario type (positive, negative, edge_case, irrelevant)
+    - Target rule IDs that this scenario is designed to test
+    - Expected outcome based on the rules
+    """
+
+    description: str = Field(
+        description="The user's request or question"
+    )
+    context: str = Field(
+        default="",
+        description="Additional context for the scenario"
+    )
+    category: str = Field(
+        default="",
+        description="The policy category this scenario belongs to"
+    )
+    scenario_type: ScenarioType = Field(
+        description="Type of scenario (positive, negative, edge_case, irrelevant)"
+    )
+    target_rule_ids: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs this scenario is designed to test"
+    )
+    expected_outcome: str = Field(
+        default="",
+        description="Expected response behavior based on rules"
+    )
+
+    def to_base_scenario(self) -> "Scenario":
+        """Convert to base Scenario type for compatibility."""
+        from synkro.types.core import Scenario
+        return Scenario(
+            description=self.description,
+            context=self.context,
+            category=self.category,
+        )
+
+
+class VerificationResult(BaseModel):
+    """
+    Result of verifying a trace against the Logic Map.
+
+    The Auditor produces this to indicate whether a trace
+    correctly applies all relevant rules without hallucination.
+    """
+
+    passed: bool = Field(
+        description="Whether the trace passed verification"
+    )
+    issues: list[str] = Field(
+        default_factory=list,
+        description="List of issues found (if any)"
+    )
+    skipped_rules: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs that should have been applied but weren't"
+    )
+    hallucinated_rules: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs cited that don't exist or don't apply"
+    )
+    contradictions: list[str] = Field(
+        default_factory=list,
+        description="Logical contradictions found in the trace"
+    )
+    rules_verified: list[str] = Field(
+        default_factory=list,
+        description="Rule IDs that were correctly applied"
+    )
+
+
+__all__ = [
+    "ScenarioType",
+    "RuleCategory",
+    "Rule",
+    "LogicMap",
+    "ReasoningStep",
+    "GoldenScenario",
+    "VerificationResult",
+]

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.12.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",
+]
+