yamlgraph 0.3.9__py3-none-any.whl

yamlgraph/tools/websearch.py

@@ -0,0 +1,242 @@
+"""Web search tool for LLM agents.
+
+This module provides web search functionality using DuckDuckGo,
+allowing agents to search the internet for current information.
+
+No API key required for DuckDuckGo. Results include title, URL, and snippet.
+
+Example usage in graph YAML:
+    tools:
+      search_web:
+        type: websearch
+        provider: duckduckgo
+        max_results: 5
+        description: "Search the web for information"
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+# Import DuckDuckGo - try new package name first, fallback to old
+try:
+    from ddgs import DDGS
+
+    DUCKDUCKGO_AVAILABLE = True
+except ImportError:
+    try:
+        from duckduckgo_search import DDGS
+
+        DUCKDUCKGO_AVAILABLE = True
+    except ImportError:
+        DDGS = None  # type: ignore[assignment, misc]
+        DUCKDUCKGO_AVAILABLE = False
+
+
+@dataclass
+class WebSearchToolConfig:
+    """Configuration for a web search tool.
+
+    Attributes:
+        provider: Search provider (currently only 'duckduckgo' supported)
+        max_results: Maximum number of results to return
+        description: Human-readable description for LLM tool selection
+        timeout: Max seconds before search is cancelled
+    """
+
+    provider: str = "duckduckgo"
+    max_results: int = 5
+    description: str = ""
+    timeout: int = 30
+
+
+@dataclass
+class WebSearchResult:
+    """Result from executing a web search.
+
+    Attributes:
+        success: Whether the search succeeded
+        results: List of search result dicts with title, href, body
+        query: The search query used
+        error: Error message if failed
+    """
+
+    success: bool
+    results: list[dict[str, str]]
+    query: str
+    error: str | None = None
+
+
+def execute_web_search(query: str, config: WebSearchToolConfig) -> WebSearchResult:
+    """Execute a web search using the configured provider.
+
+    Args:
+        query: Search query string
+        config: WebSearchToolConfig with provider settings
+
+    Returns:
+        WebSearchResult with search results or error
+    """
+    if not query or not query.strip():
+        return WebSearchResult(
+            success=False,
+            results=[],
+            query=query,
+            error="Search query is empty",
+        )
+
+    if config.provider != "duckduckgo":
+        return WebSearchResult(
+            success=False,
+            results=[],
+            query=query,
+            error=f"Unsupported provider: {config.provider}",
+        )
+
+    if not DUCKDUCKGO_AVAILABLE:
+        return WebSearchResult(
+            success=False,
+            results=[],
+            query=query,
+            error="duckduckgo-search package not installed. Run: pip install duckduckgo-search",
+        )
+
+    try:
+        with DDGS() as ddgs:
+            results = list(ddgs.text(query, max_results=config.max_results))
+
+        logger.debug(f"Web search for '{query}' returned {len(results)} results")
+
+        return WebSearchResult(
+            success=True,
+            results=results,
+            query=query,
+        )
+
+    except Exception as e:
+        logger.warning(f"Web search failed: {e}")
+        return WebSearchResult(
+            success=False,
+            results=[],
+            query=query,
+            error=str(e),
+        )
+
+
+def format_search_results(result: WebSearchResult) -> str:
+    """Format search results as readable text for LLM consumption.
+
+    Args:
+        result: WebSearchResult from execute_web_search
+
+    Returns:
+        Formatted string with results or error message
+    """
+    if not result.success:
+        return f"Search error: {result.error}"
+
+    if not result.results:
+        return f"No results found for query: '{result.query}'"
+
+    lines = [f"Search results for '{result.query}':\n"]
+
+    for i, item in enumerate(result.results, 1):
+        title = item.get("title", "No title")
+        url = item.get("href", item.get("url", "No URL"))
+        body = item.get("body", item.get("snippet", ""))
+
+        lines.append(f"{i}. {title}")
+        lines.append(f"   URL: {url}")
+        if body:
+            lines.append(f"   {body}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+class WebSearchInput(BaseModel):
+    """Input schema for web search tool."""
+
+    query: str = Field(description="The search query to look up on the web")
+
+
+def create_web_search_tool(name: str, config: WebSearchToolConfig) -> StructuredTool:
+    """Create a LangChain-compatible web search tool.
+
+    Args:
+        name: Tool name for LLM to reference
+        config: WebSearchToolConfig with settings
+
+    Returns:
+        StructuredTool that can be used with LangChain agents
+    """
+
+    def search_func(query: str) -> str:
+        """Execute web search and return formatted results."""
+        result = execute_web_search(query, config)
+        return format_search_results(result)
+
+    description = (
+        config.description or "Search the web for current information on any topic"
+    )
+
+    return StructuredTool.from_function(
+        func=search_func,
+        name=name,
+        description=description,
+        args_schema=WebSearchInput,
+    )
+
+
+def create_websearch_tool_from_config(
+    name: str, tool_config: dict[str, Any]
+) -> StructuredTool:
+    """Create a web search tool from YAML config dict.
+
+    This is the entry point used by the graph loader when parsing
+    tool definitions from YAML.
+
+    Args:
+        name: Tool name
+        tool_config: Dict with provider, max_results, description, etc.
+
+    Returns:
+        StructuredTool for use in agent nodes
+    """
+    config = WebSearchToolConfig(
+        provider=tool_config.get("provider", "duckduckgo"),
+        max_results=tool_config.get("max_results", 5),
+        description=tool_config.get("description", ""),
+        timeout=tool_config.get("timeout", 30),
+    )
+
+    return create_web_search_tool(name, config)
+
+
+def parse_websearch_tools(tools_config: dict[str, Any]) -> dict[str, Any]:
+    """Parse tools: section from YAML for websearch tools.
+
+    Only parses tools with type: websearch.
+
+    Args:
+        tools_config: Dict from YAML tools: section
+
+    Returns:
+        Registry mapping tool names to LangChain StructuredTool objects
+    """
+    registry: dict[str, Any] = {}
+
+    for name, config in tools_config.items():
+        if config.get("type") != "websearch":
+            continue
+
+        registry[name] = create_websearch_tool_from_config(name, config)
+
+    return registry

yamlgraph/utils/__init__.py

@@ -0,0 +1,48 @@
+"""Utility functions for observability and logging."""
+
+from yamlgraph.utils.conditions import evaluate_condition
+from yamlgraph.utils.expressions import (
+    resolve_state_expression,
+    resolve_state_path,
+    resolve_template,
+)
+from yamlgraph.utils.json_extract import extract_json
+from yamlgraph.utils.langsmith import (
+    get_client,
+    get_latest_run_id,
+    get_project_name,
+    get_run_url,
+    is_tracing_enabled,
+    print_run_tree,
+)
+from yamlgraph.utils.logging import get_logger, setup_logging
+from yamlgraph.utils.prompts import load_prompt, load_prompt_path, resolve_prompt_path
+from yamlgraph.utils.template import extract_variables, validate_variables
+
+__all__ = [
+    # Conditions
+    "evaluate_condition",
+    # Expression resolution (consolidated)
+    "resolve_state_path",
+    "resolve_state_expression",
+    "resolve_template",
+    # JSON extraction
+    "extract_json",
+    # LangSmith
+    "get_client",
+    "get_project_name",
+    "is_tracing_enabled",
+    "get_latest_run_id",
+    "print_run_tree",
+    "get_run_url",
+    # Logging
+    "get_logger",
+    "setup_logging",
+    # Prompts
+    "resolve_prompt_path",
+    "load_prompt",
+    "load_prompt_path",
+    # Template utilities
+    "extract_variables",
+    "validate_variables",
+]

yamlgraph/utils/conditions.py

@@ -0,0 +1,157 @@
+"""Condition expression evaluation for graph routing.
+
+Provides safe evaluation of condition expressions without using eval().
+Supports comparisons and compound boolean expressions.
+
+Examples:
+    >>> evaluate_condition("score < 0.8", {"score": 0.5})
+    True
+    >>> evaluate_condition("a > 1 and b < 2", {"a": 2, "b": 1})
+    True
+"""
+
+import re
+from typing import Any
+
+from yamlgraph.utils.expressions import resolve_state_path
+
+# Regex patterns for expression parsing
+# Valid operators: <=, >=, ==, !=, <, > (strict matching)
+COMPARISON_PATTERN = re.compile(
+    r"^\s*([a-zA-Z_][\w.]*)\s*(<=|>=|==|!=|<(?!<)|>(?!>))\s*(.+?)\s*$"
+)
+COMPOUND_AND_PATTERN = re.compile(r"\s+and\s+", re.IGNORECASE)
+COMPOUND_OR_PATTERN = re.compile(r"\s+or\s+", re.IGNORECASE)
+
+
+def resolve_value(path: str, state: dict) -> Any:
+    """Resolve a dotted path to a value from state.
+
+    Delegates to consolidated resolve_state_path in expressions module.
+
+    Args:
+        path: Dotted path like "critique.score"
+        state: State dictionary
+
+    Returns:
+        Resolved value or None if not found
+    """
+    return resolve_state_path(path, state)
+
+
+def parse_literal(value_str: str) -> Any:
+    """Parse a literal value from expression.
+
+    Args:
+        value_str: String representation of value
+
+    Returns:
+        Parsed Python value
+    """
+    value_str = value_str.strip()
+
+    # Handle quoted strings
+    if (value_str.startswith('"') and value_str.endswith('"')) or (
+        value_str.startswith("'") and value_str.endswith("'")
+    ):
+        return value_str[1:-1]
+
+    # Handle special keywords
+    if value_str.lower() == "true":
+        return True
+    if value_str.lower() == "false":
+        return False
+    if value_str.lower() == "null" or value_str.lower() == "none":
+        return None
+
+    # Handle numbers
+    try:
+        if "." in value_str:
+            return float(value_str)
+        return int(value_str)
+    except ValueError:
+        # Return as string if not a number
+        return value_str
+
+
+def evaluate_comparison(
+    left_path: str, operator: str, right_str: str, state: dict[str, Any]
+) -> bool:
+    """Evaluate a single comparison expression.
+
+    Args:
+        left_path: Dotted path to left value
+        operator: Comparison operator
+        right_str: String representation of right value
+        state: State dictionary
+
+    Returns:
+        Boolean result of comparison
+    """
+    left_value = resolve_value(left_path, state)
+    right_value = parse_literal(right_str)
+
+    # Handle missing left value
+    if left_value is None and operator not in ("==", "!="):
+        return False
+
+    try:
+        if operator == "<":
+            return left_value < right_value
+        elif operator == ">":
+            return left_value > right_value
+        elif operator == "<=":
+            return left_value <= right_value
+        elif operator == ">=":
+            return left_value >= right_value
+        elif operator == "==":
+            return left_value == right_value
+        elif operator == "!=":
+            return left_value != right_value
+        else:
+            raise ValueError(f"Unknown operator: {operator}")
+    except TypeError:
+        # Comparison failed (e.g., comparing None with number)
+        return False
+
+
+def evaluate_condition(expr: str, state: dict) -> bool:
+    """Safely evaluate a condition expression against state.
+
+    Uses pattern matching - no eval() for security.
+
+    Args:
+        expr: Condition expression like "score < 0.8" or "a > 1 and b < 2"
+        state: State dictionary to evaluate against
+
+    Returns:
+        Boolean result of evaluation
+
+    Raises:
+        ValueError: If expression is malformed
+
+    Examples:
+        >>> evaluate_condition("score < 0.8", {"score": 0.5})
+        True
+        >>> evaluate_condition("critique.score >= 0.8", {"critique": obj})
+        True
+    """
+    expr = expr.strip()
+
+    # Handle compound OR (lower precedence)
+    if COMPOUND_OR_PATTERN.search(expr):
+        parts = COMPOUND_OR_PATTERN.split(expr)
+        return any(evaluate_condition(part, state) for part in parts)
+
+    # Handle compound AND
+    if COMPOUND_AND_PATTERN.search(expr):
+        parts = COMPOUND_AND_PATTERN.split(expr)
+        return all(evaluate_condition(part, state) for part in parts)
+
+    # Parse single comparison
+    match = COMPARISON_PATTERN.match(expr)
+    if not match:
+        raise ValueError(f"Invalid condition expression: {expr}")
+
+    left_path, operator, right_str = match.groups()
+    return evaluate_comparison(left_path, operator, right_str, state)

yamlgraph/utils/expressions.py

@@ -0,0 +1,245 @@
+"""Expression resolution utilities for YAML graphs.
+
+Consolidated module for all state path/expression resolution.
+Use these functions instead of duplicating resolution logic elsewhere.
+"""
+
+import re
+from typing import Any
+
+# Pattern for arithmetic expressions: {state.field + 1} or {state.a + state.b}
+ARITHMETIC_PATTERN = re.compile(r"^\{(state\.[a-zA-Z_][\w.]*)\s*([+\-*/])\s*(.+)\}$")
+
+
+def resolve_state_path(path: str, state: dict[str, Any]) -> Any:
+    """Resolve a dotted path to a value from state.
+
+    Core resolution function - handles nested dict access and object attributes.
+    This is the single source of truth for path resolution.
+
+    Args:
+        path: Dotted path like "critique.score" or "story.panels"
+        state: State dictionary
+
+    Returns:
+        Resolved value or None if not found
+    """
+    if not path:
+        return None
+
+    parts = path.split(".")
+    value = state
+
+    for part in parts:
+        if value is None:
+            return None
+        if isinstance(value, dict):
+            value = value.get(part)
+        else:
+            # Try attribute access for objects (Pydantic models, etc.)
+            value = getattr(value, part, None)
+
+    return value
+
+
+def resolve_state_expression(expr: str | Any, state: dict[str, Any]) -> Any:
+    """Resolve {state.path.to.value} expressions.
+
+    Supports expressions like:
+        - "{name}" -> state["name"]
+        - "{state.story.panels}" -> state["story"]["panels"]
+        - "{story.title}" -> state["story"]["title"]
+
+    Non-expression values (no braces) pass through unchanged.
+
+    Args:
+        expr: Expression string like "{state.story.panels}" or any value
+        state: Current graph state dict
+
+    Returns:
+        Resolved value from state, or original value if not an expression
+
+    Raises:
+        KeyError: If path cannot be resolved in state
+    """
+    if not isinstance(expr, str):
+        return expr
+
+    if not (expr.startswith("{") and expr.endswith("}")):
+        return expr
+
+    path = expr[1:-1]  # Remove braces
+
+    # Handle "state." prefix (optional)
+    if path.startswith("state."):
+        path = path[6:]  # Remove "state."
+
+    # Navigate nested path
+    value = state
+    for key in path.split("."):
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        elif hasattr(value, key):
+            # Support object attribute access (Pydantic models, etc.)
+            value = getattr(value, key)
+        else:
+            raise KeyError(f"Cannot resolve '{key}' in path '{expr}'")
+
+    return value
+
+
+def _parse_operand(operand_str: str, state: dict[str, Any]) -> Any:
+    """Parse an operand - either a state reference or a literal.
+
+    Args:
+        operand_str: String like "state.counter", "1", "[state.item]", etc.
+        state: Current pipeline state
+
+    Returns:
+        Resolved value
+    """
+    operand_str = operand_str.strip()
+
+    # State reference: state.field
+    if operand_str.startswith("state."):
+        path = operand_str[6:]  # Remove "state."
+        return resolve_state_path(path, state)
+
+    # List literal with state reference: [state.item]
+    if operand_str.startswith("[") and operand_str.endswith("]"):
+        inner = operand_str[1:-1].strip()
+        if inner.startswith("state."):
+            item = resolve_state_path(inner[6:], state)
+            return [item]
+        # Try to parse as literal
+        return [_parse_literal(inner)]
+
+    # Dict literal: {'key': state.value}
+    if operand_str.startswith("{") and operand_str.endswith("}"):
+        # Simple dict parsing - limited support
+        inner = operand_str[1:-1].strip()
+        result = {}
+        # Parse simple key-value pairs
+        for pair in inner.split(","):
+            if ":" not in pair:
+                continue
+            key_part, val_part = pair.split(":", 1)
+            key = key_part.strip().strip("'\"")
+            val = val_part.strip()
+            if val.startswith("state."):
+                result[key] = resolve_state_path(val[6:], state)
+            else:
+                result[key] = _parse_literal(val)
+        return result
+
+    # Literal value
+    return _parse_literal(operand_str)
+
+
+def _parse_literal(value_str: str) -> Any:
+    """Parse a literal value.
+
+    Args:
+        value_str: String representation
+
+    Returns:
+        Parsed Python value
+    """
+    value_str = value_str.strip()
+
+    # Quoted string
+    if (value_str.startswith('"') and value_str.endswith('"')) or (
+        value_str.startswith("'") and value_str.endswith("'")
+    ):
+        return value_str[1:-1]
+
+    # Boolean
+    if value_str.lower() == "true":
+        return True
+    if value_str.lower() == "false":
+        return False
+
+    # None
+    if value_str.lower() in ("null", "none"):
+        return None
+
+    # Number
+    try:
+        if "." in value_str:
+            return float(value_str)
+        return int(value_str)
+    except ValueError:
+        return value_str
+
+
+def _apply_operator(left: Any, operator: str, right: Any) -> Any:
+    """Apply an arithmetic operator.
+
+    Args:
+        left: Left operand
+        operator: One of +, -, *, /
+        right: Right operand
+
+    Returns:
+        Result of operation
+    """
+    if operator == "+":
+        # List concatenation or addition
+        if isinstance(left, list):
+            if isinstance(right, list):
+                return left + right
+            return left + [right]
+        return left + right
+    elif operator == "-":
+        return left - right
+    elif operator == "*":
+        return left * right
+    elif operator == "/":
+        return left / right
+    else:
+        raise ValueError(f"Unknown operator: {operator}")
+
+
+def resolve_template(template: str | Any, state: dict[str, Any]) -> Any:
+    """Resolve a {state.field} template to its value.
+
+    Supports:
+    - Simple paths: {state.field}
+    - Arithmetic: {state.counter + 1}
+    - List operations: {state.history + [state.item]}
+
+    Args:
+        template: Template string like "{state.field}" or "{state.a + 1}"
+        state: Current pipeline state
+
+    Returns:
+        Resolved value or None if not found
+    """
+    if not isinstance(template, str):
+        return template
+
+    if not (template.startswith("{") and template.endswith("}")):
+        return template
+
+    # Check for arithmetic expression first
+    match = ARITHMETIC_PATTERN.match(template)
+    if match:
+        left_ref = match.group(1)  # e.g., "state.counter"
+        operator = match.group(2)  # e.g., "+"
+        right_str = match.group(3)  # e.g., "1" or "state.other"
+
+        left = _parse_operand(left_ref, state)
+        right = _parse_operand(right_str, state)
+
+        if left is None:
+            return None
+
+        return _apply_operator(left, operator, right)
+
+    # Simple state path
+    STATE_PREFIX = "{state."
+    if template.startswith(STATE_PREFIX) and template.endswith("}"):
+        path = template[len(STATE_PREFIX) : -1]
+        return resolve_state_path(path, state)
+
+    return template