synkro 0.4.12__py3-none-any.whl

synkro/interactive/logic_map_editor.py

@@ -0,0 +1,173 @@
+"""Logic Map Editor - LLM-powered interactive refinement of Logic Maps."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from synkro.llm.client import LLM
+from synkro.models import Model, OpenAI
+from synkro.schemas import RefinedLogicMapOutput
+from synkro.types.logic_map import LogicMap, Rule, RuleCategory
+from synkro.prompts.interactive_templates import LOGIC_MAP_REFINEMENT_PROMPT
+
+if TYPE_CHECKING:
+    pass
+
+
+class LogicMapEditor:
+    """
+    LLM-powered Logic Map editor that interprets natural language feedback.
+
+    The editor takes user feedback in natural language (e.g., "add a rule for...",
+    "remove R005", "merge R002 and R003") and uses an LLM to interpret and apply
+    the changes to the Logic Map.
+
+    Examples:
+        >>> editor = LogicMapEditor(llm=LLM(model=OpenAI.GPT_4O))
+        >>> new_logic_map = await editor.refine(
+        ...     logic_map=current_map,
+        ...     user_feedback="Add a rule for overtime approval",
+        ...     policy_text=policy.text
+        ... )
+    """
+
+    def __init__(
+        self,
+        llm: LLM | None = None,
+        model: Model = OpenAI.GPT_4O,
+    ):
+        """
+        Initialize the Logic Map Editor.
+
+        Args:
+            llm: LLM client to use (creates one if not provided)
+            model: Model to use if creating LLM (default: GPT-4O for accuracy)
+        """
+        self.llm = llm or LLM(model=model, temperature=0.3)
+
+    async def refine(
+        self,
+        logic_map: LogicMap,
+        user_feedback: str,
+        policy_text: str,
+    ) -> tuple[LogicMap, str]:
+        """
+        Refine the Logic Map based on natural language feedback.
+
+        Args:
+            logic_map: Current Logic Map to refine
+            user_feedback: Natural language instruction from user
+            policy_text: Original policy text for context
+
+        Returns:
+            Tuple of (refined LogicMap, changes summary string)
+
+        Raises:
+            ValueError: If refinement produces invalid DAG
+        """
+        # Format current Logic Map as string for prompt
+        current_map_str = self._format_logic_map_for_prompt(logic_map)
+
+        # Format the prompt
+        prompt = LOGIC_MAP_REFINEMENT_PROMPT.format(
+            current_logic_map=current_map_str,
+            policy_text=policy_text,
+            user_feedback=user_feedback,
+        )
+
+        # Generate structured output
+        result = await self.llm.generate_structured(prompt, RefinedLogicMapOutput)
+
+        # Convert to domain model
+        refined_map = self._convert_to_logic_map(result)
+
+        # Validate DAG properties
+        if not refined_map.validate_dag():
+            raise ValueError(
+                "Refined Logic Map contains circular dependencies. "
+                "Please try a different modification."
+            )
+
+        return refined_map, result.changes_summary
+
+    def _format_logic_map_for_prompt(self, logic_map: LogicMap) -> str:
+        """Format a Logic Map as a string for the LLM prompt."""
+        lines = []
+        lines.append(f"Total Rules: {len(logic_map.rules)}")
+        lines.append(f"Root Rules: {', '.join(logic_map.root_rules)}")
+        lines.append("")
+        lines.append("Rules:")
+
+        for rule in logic_map.rules:
+            deps = f" -> {', '.join(rule.dependencies)}" if rule.dependencies else ""
+            lines.append(f"  {rule.rule_id}: {rule.text}")
+            lines.append(f"    Category: {rule.category.value}")
+            lines.append(f"    Condition: {rule.condition}")
+            lines.append(f"    Action: {rule.action}")
+            if deps:
+                lines.append(f"    Dependencies: {', '.join(rule.dependencies)}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _convert_to_logic_map(self, output: RefinedLogicMapOutput) -> LogicMap:
+        """Convert schema output to domain model."""
+        rules = []
+        for rule_out in output.rules:
+            # Convert category string to enum
+            category = RuleCategory(rule_out.category)
+
+            rule = Rule(
+                rule_id=rule_out.rule_id,
+                text=rule_out.text,
+                condition=rule_out.condition,
+                action=rule_out.action,
+                dependencies=rule_out.dependencies,
+                category=category,
+            )
+            rules.append(rule)
+
+        return LogicMap(
+            rules=rules,
+            root_rules=output.root_rules,
+        )
+
+    def validate_refinement(
+        self,
+        original: LogicMap,
+        refined: LogicMap,
+    ) -> tuple[bool, list[str]]:
+        """
+        Validate that refinement maintains DAG properties and is sensible.
+
+        Args:
+            original: Original Logic Map
+            refined: Refined Logic Map
+
+        Returns:
+            Tuple of (is_valid, list of issue descriptions)
+        """
+        issues = []
+
+        # Check DAG validity
+        if not refined.validate_dag():
+            issues.append("Refined Logic Map has circular dependencies")
+
+        # Check that all dependencies reference existing rules
+        rule_ids = {r.rule_id for r in refined.rules}
+        for rule in refined.rules:
+            for dep in rule.dependencies:
+                if dep not in rule_ids:
+                    issues.append(f"Rule {rule.rule_id} depends on non-existent rule {dep}")
+
+        # Check root_rules consistency
+        for root_id in refined.root_rules:
+            if root_id not in rule_ids:
+                issues.append(f"Root rule {root_id} does not exist")
+
+        # Check that rules with no dependencies are in root_rules
+        for rule in refined.rules:
+            if not rule.dependencies and rule.rule_id not in refined.root_rules:
+                issues.append(f"Rule {rule.rule_id} has no dependencies but is not in root_rules")
+
+        return len(issues) == 0, issues

synkro/interactive/rich_ui.py

@@ -0,0 +1,205 @@
+"""Rich UI components for Human-in-the-Loop interaction."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synkro.types.logic_map import LogicMap
+
+
+class LogicMapDisplay:
+    """Rich-based display for Logic Maps."""
+
+    def __init__(self) -> None:
+        from rich.console import Console
+
+        self.console = Console()
+
+    def display_full(self, logic_map: "LogicMap") -> None:
+        """Display the complete Logic Map with all details."""
+        from rich.panel import Panel
+        from rich.tree import Tree
+
+        # Build tree view of rules by category
+        tree = Tree("[bold cyan]Logic Map[/bold cyan]")
+
+        # Group rules by category
+        categories: dict[str, list] = {}
+        for rule in logic_map.rules:
+            cat = rule.category.value if hasattr(rule.category, "value") else str(rule.category)
+            if cat not in categories:
+                categories[cat] = []
+            categories[cat].append(rule)
+
+        # Add each category as a branch
+        for category, rules in sorted(categories.items()):
+            branch = tree.add(f"[bold]{category}[/bold] ({len(rules)} rules)")
+            for rule in rules:
+                rule_text = f"[cyan]{rule.rule_id}[/cyan]: {rule.text[:60]}..."
+                if rule.dependencies:
+                    rule_text += f" [dim]→ {', '.join(rule.dependencies)}[/dim]"
+                branch.add(rule_text)
+
+        # Show root rules
+        root_info = f"[dim]Root rules: {', '.join(logic_map.root_rules)}[/dim]"
+
+        self.console.print()
+        self.console.print(
+            Panel(
+                tree,
+                title=f"[bold]📜 Logic Map ({len(logic_map.rules)} rules)[/bold]",
+                subtitle=root_info,
+                border_style="cyan",
+            )
+        )
+
+    def display_diff(self, before: "LogicMap", after: "LogicMap") -> None:
+        """Display all rules with changes highlighted in different colors."""
+        from rich.panel import Panel
+        from rich.tree import Tree
+
+        before_ids = {r.rule_id for r in before.rules}
+        after_ids = {r.rule_id for r in after.rules}
+
+        added = after_ids - before_ids
+        removed = before_ids - after_ids
+        common = before_ids & after_ids
+
+        # Check for modifications in common rules
+        modified: set[str] = set()
+        before_map = {r.rule_id: r for r in before.rules}
+        after_map = {r.rule_id: r for r in after.rules}
+
+        for rule_id in common:
+            if before_map[rule_id].text != after_map[rule_id].text:
+                modified.add(rule_id)
+            elif before_map[rule_id].dependencies != after_map[rule_id].dependencies:
+                modified.add(rule_id)
+
+        if not added and not removed and not modified:
+            self.console.print("[dim]No changes detected[/dim]")
+            return
+
+        # Build tree view of rules by category (like display_full but with colors)
+        tree = Tree("[bold cyan]Logic Map[/bold cyan]")
+
+        # Group rules by category
+        categories: dict[str, list] = {}
+        for rule in after.rules:
+            cat = rule.category.value if hasattr(rule.category, "value") else str(rule.category)
+            if cat not in categories:
+                categories[cat] = []
+            categories[cat].append(rule)
+
+        # Add each category as a branch
+        for category, rules in sorted(categories.items()):
+            branch = tree.add(f"[bold]{category}[/bold] ({len(rules)} rules)")
+            for rule in rules:
+                # Determine style based on change type
+                if rule.rule_id in added:
+                    prefix = "[green]+ "
+                    style_close = "[/green]"
+                    id_style = "[green]"
+                elif rule.rule_id in modified:
+                    prefix = "[yellow]~ "
+                    style_close = "[/yellow]"
+                    id_style = "[yellow]"
+                else:
+                    prefix = ""
+                    style_close = ""
+                    id_style = "[cyan]"
+
+                rule_text = f"{prefix}{id_style}{rule.rule_id}[/]: {rule.text[:60]}...{style_close}"
+                if rule.dependencies:
+                    rule_text += f" [dim]→ {', '.join(rule.dependencies)}[/dim]"
+                branch.add(rule_text)
+
+        # Add removed rules section at the bottom
+        if removed:
+            removed_branch = tree.add("[red][bold]REMOVED[/bold][/red]")
+            for rule_id in sorted(removed):
+                rule = before_map[rule_id]
+                removed_branch.add(f"[red][strike]- {rule_id}: {rule.text[:60]}...[/strike][/red]")
+
+        # Build legend
+        legend = "[dim]Legend: [green]+ Added[/green] | [yellow]~ Modified[/yellow] | [red][strike]- Removed[/strike][/red][/dim]"
+
+        self.console.print()
+        self.console.print(
+            Panel(
+                tree,
+                title=f"[bold]📜 Logic Map ({len(after.rules)} rules)[/bold]",
+                subtitle=legend,
+                border_style="cyan",
+            )
+        )
+
+    def display_rule(self, rule_id: str, logic_map: "LogicMap") -> None:
+        """Display details of a specific rule."""
+        from rich.panel import Panel
+
+        rule = logic_map.get_rule(rule_id)
+        if not rule:
+            self.console.print(f"[red]Rule {rule_id} not found[/red]")
+            return
+
+        content = f"""[bold]ID:[/bold] {rule.rule_id}
+[bold]Text:[/bold] {rule.text}
+[bold]Category:[/bold] {rule.category}
+[bold]Condition:[/bold] {rule.condition or 'N/A'}
+[bold]Action:[/bold] {rule.action or 'N/A'}
+[bold]Dependencies:[/bold] {', '.join(rule.dependencies) if rule.dependencies else 'None (root rule)'}"""
+
+        self.console.print(Panel(content, title=f"Rule {rule_id}", border_style="cyan"))
+
+    def show_error(self, message: str) -> None:
+        """Display an error message."""
+        self.console.print(f"[red]Error:[/red] {message}")
+
+    def show_success(self, message: str) -> None:
+        """Display a success message."""
+        self.console.print(f"[green]✓[/green] {message}")
+
+
+class InteractivePrompt:
+    """Handles user input for HITL sessions."""
+
+    def __init__(self) -> None:
+        from rich.console import Console
+
+        self.console = Console()
+
+    def show_instructions(self) -> None:
+        """Display instructions for the HITL session."""
+        from rich.panel import Panel
+
+        instructions = """[bold]Commands:[/bold]
+  • Type feedback to modify the Logic Map (e.g., "add a rule for...", "remove R005")
+  • [cyan]done[/cyan] - Continue with current Logic Map
+  • [cyan]undo[/cyan] - Revert last change
+  • [cyan]reset[/cyan] - Restore original Logic Map
+  • [cyan]show R001[/cyan] - Show details of a specific rule
+  • [cyan]help[/cyan] - Show this message"""
+
+        self.console.print()
+        self.console.print(
+            Panel(
+                instructions,
+                title="[bold cyan]Interactive Logic Map Editor[/bold cyan]",
+                border_style="cyan",
+            )
+        )
+
+    def get_feedback(self) -> str:
+        """Prompt user for feedback on the Logic Map."""
+        from rich.prompt import Prompt
+
+        self.console.print()
+        return Prompt.ask("[cyan]Enter feedback[/cyan]")
+
+    def confirm_continue(self) -> bool:
+        """Ask user if they want to continue with current Logic Map."""
+        from rich.prompt import Confirm
+
+        return Confirm.ask("Continue with this Logic Map?", default=True)

synkro/llm/__init__.py

@@ -0,0 +1,7 @@
+"""LLM client wrapper for multiple providers via LiteLLM."""
+
+from synkro.llm.client import LLM
+from synkro.llm.rate_limits import auto_workers, get_provider
+
+__all__ = ["LLM", "auto_workers", "get_provider"]
+

synkro/llm/client.py

@@ -0,0 +1,235 @@
+"""Type-safe LLM wrapper using LiteLLM."""
+
+from typing import TypeVar, Type, overload
+
+import litellm
+from litellm import acompletion, supports_response_schema
+from pydantic import BaseModel
+
+# Configure litellm
+litellm.suppress_debug_info = True
+litellm.enable_json_schema_validation=True
+
+from synkro.models import OpenAI, Model, get_model_string
+
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LLM:
+    """
+    Type-safe LLM wrapper using LiteLLM for universal provider support.
+
+    Supports structured outputs via native JSON mode for reliable responses.
+
+    Supported providers: OpenAI, Anthropic, Google (Gemini)
+
+    Examples:
+        >>> from synkro import LLM, OpenAI, Anthropic, Google
+
+        # Use OpenAI
+        >>> llm = LLM(model=OpenAI.GPT_4O_MINI)
+        >>> response = await llm.generate("Hello!")
+
+        # Use Anthropic
+        >>> llm = LLM(model=Anthropic.CLAUDE_35_SONNET)
+
+        # Use Google Gemini
+        >>> llm = LLM(model=Google.GEMINI_25_FLASH)
+
+        # Structured output
+        >>> class Output(BaseModel):
+        ...     answer: str
+        ...     confidence: float
+        >>> result = await llm.generate_structured("What is 2+2?", Output)
+        >>> result.answer
+        '4'
+    """
+
+    def __init__(
+        self,
+        model: Model = OpenAI.GPT_4O_MINI,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        api_key: str | None = None,
+    ):
+        """
+        Initialize the LLM client.
+
+        Args:
+            model: Model to use (enum or string)
+            temperature: Sampling temperature (0.0-2.0)
+            max_tokens: Maximum tokens to generate (default: None = model's max)
+            api_key: Optional API key override
+        """
+        self.model = get_model_string(model)
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self._api_key = api_key
+
+    async def generate(self, prompt: str, system: str | None = None) -> str:
+        """
+        Generate a text response.
+
+        Args:
+            prompt: The user prompt
+            system: Optional system prompt
+
+        Returns:
+            Generated text response
+        """
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        kwargs = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+            "api_key": self._api_key,
+        }
+        if self.max_tokens is not None:
+            kwargs["max_tokens"] = self.max_tokens
+
+        response = await acompletion(**kwargs)
+        return response.choices[0].message.content
+
+    async def generate_batch(
+        self, prompts: list[str], system: str | None = None
+    ) -> list[str]:
+        """
+        Generate responses for multiple prompts in parallel.
+
+        Args:
+            prompts: List of user prompts
+            system: Optional system prompt for all
+
+        Returns:
+            List of generated responses
+        """
+        import asyncio
+
+        tasks = [self.generate(p, system) for p in prompts]
+        return await asyncio.gather(*tasks)
+
+    @overload
+    async def generate_structured(
+        self,
+        prompt: str,
+        response_model: Type[T],
+        system: str | None = None,
+    ) -> T: ...
+
+    @overload
+    async def generate_structured(
+        self,
+        prompt: str,
+        response_model: Type[list[T]],
+        system: str | None = None,
+    ) -> list[T]: ...
+
+    async def generate_structured(
+        self,
+        prompt: str,
+        response_model: Type[T] | Type[list[T]],
+        system: str | None = None,
+    ) -> T | list[T]:
+        """
+        Generate a structured response matching a Pydantic model.
+
+        Uses LiteLLM's native JSON mode with response_format for
+        reliable structured outputs.
+
+        Args:
+            prompt: The user prompt
+            response_model: Pydantic model class for the response
+            system: Optional system prompt
+
+        Returns:
+            Parsed response matching the model
+
+        Example:
+            >>> class Analysis(BaseModel):
+            ...     sentiment: str
+            ...     score: float
+            >>> result = await llm.generate_structured(
+            ...     "Analyze: I love this product!",
+            ...     Analysis
+            ... )
+            >>> result.sentiment
+            'positive'
+        """
+        # Check if model supports structured outputs
+        if not supports_response_schema(model=self.model, custom_llm_provider=None):
+            raise ValueError(
+                f"Model '{self.model}' does not support structured outputs (response_format). "
+                f"Use a model that supports JSON schema like GPT-4o, Gemini 1.5+, or Claude 3.5+."
+            )
+
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        # Use LiteLLM's native response_format with Pydantic model
+        kwargs = {
+            "model": self.model,
+            "messages": messages,
+            "response_format": response_model,
+            "temperature": self.temperature,
+            "api_key": self._api_key,
+        }
+        if self.max_tokens is not None:
+            kwargs["max_tokens"] = self.max_tokens
+
+        response = await acompletion(**kwargs)
+        return response_model.model_validate_json(response.choices[0].message.content)
+
+    async def generate_chat(
+        self, messages: list[dict], response_model: Type[T] | None = None
+    ) -> str | T:
+        """
+        Generate a response for a full conversation.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            response_model: Optional Pydantic model for structured output
+
+        Returns:
+            Generated response (string or structured)
+        """
+        if response_model:
+            # Check if model supports structured outputs
+            if not supports_response_schema(model=self.model, custom_llm_provider=None):
+                raise ValueError(
+                    f"Model '{self.model}' does not support structured outputs (response_format). "
+                    f"Use a model that supports JSON schema like GPT-4o, Gemini 1.5+, or Claude 3.5+."
+                )
+
+            # Use LiteLLM's native response_format with Pydantic model
+            kwargs = {
+                "model": self.model,
+                "messages": messages,
+                "response_format": response_model,
+                "temperature": self.temperature,
+                "api_key": self._api_key,
+            }
+            if self.max_tokens is not None:
+                kwargs["max_tokens"] = self.max_tokens
+
+            response = await acompletion(**kwargs)
+            return response_model.model_validate_json(response.choices[0].message.content)
+
+        kwargs = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+            "api_key": self._api_key,
+        }
+        if self.max_tokens is not None:
+            kwargs["max_tokens"] = self.max_tokens
+
+        response = await acompletion(**kwargs)
+        return response.choices[0].message.content
+