synkro 0.4.36__py3-none-any.whl

synkro/types/core.py

@@ -0,0 +1,153 @@
+"""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")
+
+    # Evaluation fields (populated from GoldenScenario)
+    scenario_type: str | None = Field(default=None, description="Type: positive, negative, edge_case, irrelevant")
+    target_rule_ids: list[str] | None = Field(default=None, description="Rule IDs this scenario tests")
+    expected_outcome: str | None = Field(default=None, description="Expected behavior based on rules")
+
+
+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")
+
+    # Golden Trace metadata (for verification)
+    reasoning_chain: list[Any] | None = Field(default=None, description="Chain-of-thought reasoning steps with rule citations")
+    rules_applied: list[str] | None = Field(default=None, description="Rule IDs that were applied in the response")
+    rules_excluded: list[str] | None = Field(default=None, description="Rule IDs that were explicitly excluded")
+
+    @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 EvalScenario(BaseModel):
+    """
+    A scenario for evaluation with ground truth labels.
+
+    Used by generate_scenarios() for eval dataset generation.
+    Contains the test input and expected behavior, but no synthetic response.
+
+    Examples:
+        >>> scenarios = synkro.generate_scenarios(policy, count=100)
+        >>> for s in scenarios:
+        ...     response = my_model(s.user_message)
+        ...     grade = synkro.grade(response, s, policy)
+    """
+
+    user_message: str = Field(description="The user's request or question (test input)")
+    expected_outcome: str = Field(description="Expected behavior based on policy rules")
+    target_rule_ids: list[str] = Field(default_factory=list, description="Rule IDs this scenario tests")
+    scenario_type: str = Field(description="Type: positive, negative, edge_case, irrelevant")
+    category: str = Field(default="", description="Policy category this scenario belongs to")
+    context: str = Field(default="", description="Additional context for the scenario")
+
+
+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 and complexity analysis."""
+
+    categories: list[Category] = Field(description="Categories with trace allocations")
+    reasoning: str = Field(description="Explanation of why these categories were chosen")
+    recommended_turns: int = Field(
+        default=1,
+        description="Recommended conversation turns based on policy complexity"
+    )
+    complexity_level: Literal["simple", "conditional", "complex"] = Field(
+        default="simple",
+        description="Policy complexity level: simple (1-2 turns), conditional (3 turns), complex (5+ turns)"
+    )

synkro/types/dataset_type.py

@@ -0,0 +1,33 @@
+"""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
+    - Conversation turns (INSTRUCTION/EVALUATION forces 1 turn)
+    - Output format and schema
+
+    Examples:
+        >>> from synkro import DatasetType
+        >>> synkro.generate(policy, dataset_type=DatasetType.CONVERSATION)  # Multi-turn
+        >>> synkro.generate(policy, dataset_type=DatasetType.INSTRUCTION)   # Single-turn
+        >>> synkro.generate(policy, dataset_type=DatasetType.EVALUATION)    # Q&A with ground truth
+        >>> synkro.generate(policy, dataset_type=DatasetType.TOOL_CALL, tools=[...])
+    """
+
+    CONVERSATION = "conversation"
+    """Multi-turn conversation: {messages: [{role, content}, ...]} with multiple exchanges"""
+
+    INSTRUCTION = "instruction"
+    """Single-turn instruction-following: {messages: [{role: "user"}, {role: "assistant"}]}"""
+
+    EVALUATION = "evaluation"
+    """Q&A evaluation dataset: {question, answer, expected_answer, ground_truth_rules, difficulty}"""
+
+    TOOL_CALL = "tool_call"
+    """Tool Calling: {messages: [..., {tool_calls: [...]}, {role: tool}, ...]}"""

synkro/types/logic_map.py

@@ -0,0 +1,348 @@
+"""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, preserving eval fields."""
+        from synkro.types.core import Scenario
+        return Scenario(
+            description=self.description,
+            context=self.context,
+            category=self.category,
+            scenario_type=self.scenario_type.value if self.scenario_type else None,
+            target_rule_ids=self.target_rule_ids,
+            expected_outcome=self.expected_outcome,
+        )
+
+
+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"]
+