yamlgraph 0.1.1__py3-none-any.whl

yamlgraph/utils/langsmith.py

@@ -0,0 +1,308 @@
+"""LangSmith Utilities - Tracing and observability helpers.
+
+Provides functions for interacting with LangSmith traces,
+printing execution trees, and logging run information.
+"""
+
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from yamlgraph.config import WORKING_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def get_client() -> Any | None:
+    """Get a LangSmith client if available.
+
+    Returns:
+        LangSmith Client instance or None if not configured
+    """
+    try:
+        from langsmith import Client
+
+        # Support both LANGCHAIN_* and LANGSMITH_* env vars
+        api_key = os.environ.get("LANGCHAIN_API_KEY") or os.environ.get(
+            "LANGSMITH_API_KEY"
+        )
+        if not api_key:
+            return None
+
+        endpoint = (
+            os.environ.get("LANGCHAIN_ENDPOINT")
+            or os.environ.get("LANGSMITH_ENDPOINT")
+            or "https://api.smith.langchain.com"
+        )
+        return Client(api_url=endpoint, api_key=api_key)
+    except ImportError:
+        logger.debug("LangSmith package not installed, client unavailable")
+        return None
+
+
+def get_project_name() -> str:
+    """Get the current LangSmith project name.
+
+    Returns:
+        Project name from environment or default
+    """
+    return (
+        os.environ.get("LANGCHAIN_PROJECT")
+        or os.environ.get("LANGSMITH_PROJECT")
+        or "yamlgraph"
+    )
+
+
+def is_tracing_enabled() -> bool:
+    """Check if LangSmith tracing is enabled.
+
+    Returns:
+        True if tracing is enabled
+    """
+    # Support both env var names and values
+    tracing_v2 = os.environ.get("LANGCHAIN_TRACING_V2", "").lower()
+    tracing = os.environ.get("LANGSMITH_TRACING", "").lower()
+    return tracing_v2 == "true" or tracing == "true"
+
+
+def get_latest_run_id(project_name: str | None = None) -> str | None:
+    """Get the ID of the most recent run.
+
+    Args:
+        project_name: Optional project name (uses default if not provided)
+
+    Returns:
+        Run ID string or None
+    """
+    client = get_client()
+    if not client:
+        return None
+
+    project = project_name or get_project_name()
+
+    try:
+        runs = list(client.list_runs(project_name=project, limit=1))
+        if runs:
+            return str(runs[0].id)
+    except Exception as e:
+        logger.warning("Could not get latest run: %s", e)
+
+    return None
+
+
+def share_run(run_id: str | None = None) -> str | None:
+    """Create a public share link for a run.
+
+    Args:
+        run_id: Run ID (uses latest if not provided)
+
+    Returns:
+        Public URL string or None if failed
+
+    Example:
+        >>> url = share_run()
+        >>> print(url)
+        https://eu.smith.langchain.com/public/abc123.../r
+    """
+    client = get_client()
+    if not client:
+        return None
+
+    if not run_id:
+        run_id = get_latest_run_id()
+
+    if not run_id:
+        return None
+
+    try:
+        # Use the share_run method from LangSmith SDK
+        return client.share_run(run_id)
+    except Exception as e:
+        logger.warning("Could not share run: %s", e)
+        return None
+
+
+def read_run_shared_link(run_id: str) -> str | None:
+    """Get existing share link for a run if it exists.
+
+    Args:
+        run_id: The run ID to check
+
+    Returns:
+        Public URL string or None if not shared
+    """
+    client = get_client()
+    if not client:
+        return None
+
+    try:
+        return client.read_run_shared_link(run_id)
+    except Exception as e:
+        logger.debug("Could not read run shared link for %s: %s", run_id, e)
+        return None
+
+
+def print_run_tree(run_id: str | None = None, verbose: bool = False) -> None:
+    """Print an execution tree for a run.
+
+    Args:
+        run_id: Specific run ID (uses latest if not provided)
+        verbose: Include timing and status details
+    """
+    client = get_client()
+    if not client:
+        logger.warning("LangSmith client not available")
+        return
+
+    if not run_id:
+        run_id = get_latest_run_id()
+
+    if not run_id:
+        logger.warning("No run found")
+        return
+
+    try:
+        run = client.read_run(run_id)
+        _print_run_node(run, client, verbose=verbose, indent=0)
+    except Exception as e:
+        logger.warning("Error reading run: %s", e)
+
+
+def _print_run_node(
+    run,
+    client,
+    verbose: bool = False,
+    indent: int = 0,
+    is_last: bool = True,
+    prefix: str = "",
+):
+    """Recursively print a run node and its children in tree format.
+
+    Args:
+        run: The LangSmith run object
+        client: LangSmith client
+        verbose: Include timing details
+        indent: Current indentation level
+        is_last: Whether this is the last sibling
+        prefix: Prefix string for tree drawing
+    """
+    # Status emoji
+    if run.status == "success":
+        status = "✅"
+    elif run.status == "error":
+        status = "❌"
+    else:
+        status = "⏳"
+
+    # Timing
+    timing = ""
+    if run.end_time and run.start_time:
+        duration = (run.end_time - run.start_time).total_seconds()
+        timing = f" ({duration:.1f}s)"
+
+    # Tree connectors
+    if indent == 0:
+        connector = "📊 "
+        new_prefix = ""
+    else:
+        connector = "└─ " if is_last else "├─ "
+        new_prefix = prefix + ("   " if is_last else "│  ")
+
+    # Clean up run name for display
+    display_name = run.name
+    if display_name.startswith("Chat"):
+        display_name = f"🤖 {display_name}"
+    elif "generate" in display_name.lower():
+        display_name = f"📝 {display_name}"
+    elif "analyze" in display_name.lower():
+        display_name = f"🔍 {display_name}"
+    elif "summarize" in display_name.lower():
+        display_name = f"📊 {display_name}"
+
+    logger.info("%s%s%s%s %s", prefix, connector, display_name, timing, status)
+
+    # Get child runs
+    try:
+        children = list(
+            client.list_runs(
+                parent_run_id=run.id,
+                limit=50,
+            )
+        )
+        # Sort by start time to show in execution order
+        children.sort(key=lambda r: r.start_time or datetime.min)
+
+        for i, child in enumerate(children):
+            child_is_last = i == len(children) - 1
+            _print_run_node(
+                child,
+                client,
+                verbose=verbose,
+                indent=indent + 1,
+                is_last=child_is_last,
+                prefix=new_prefix,
+            )
+    except Exception as e:
+        logger.debug("Could not fetch child runs for %s: %s", run.id, e)
+
+
+def log_execution(
+    step_name: str,
+    inputs: dict | None = None,
+    outputs: dict | None = None,
+    log_dir: str | Path | None = None,
+) -> None:
+    """Log execution details to a file.
+
+    Args:
+        step_name: Name of the pipeline step
+        inputs: Input data for the step
+        outputs: Output data from the step
+        log_dir: Directory for log files (default: outputs/logs)
+    """
+    import json
+
+    if log_dir is None:
+        log_dir = WORKING_DIR / "outputs" / "logs"
+    log_path = Path(log_dir)
+    log_path.mkdir(parents=True, exist_ok=True)
+
+    log_file = log_path / f"{datetime.now().strftime('%Y%m%d')}_execution.jsonl"
+
+    entry = {
+        "timestamp": datetime.now().isoformat(),
+        "step": step_name,
+        "inputs": inputs or {},
+        "outputs": outputs or {},
+    }
+
+    with open(log_file, "a") as f:
+        f.write(json.dumps(entry, default=str) + "\n")
+
+
+def get_run_url(run_id: str | None = None) -> str | None:
+    """Get the LangSmith URL for a run.
+
+    Args:
+        run_id: Run ID (uses latest if not provided)
+
+    Returns:
+        URL string or None
+    """
+    if not run_id:
+        run_id = get_latest_run_id()
+
+    if not run_id:
+        return None
+
+    endpoint = os.environ.get("LANGCHAIN_ENDPOINT", "https://api.smith.langchain.com")
+    project = get_project_name()
+
+    # Convert API endpoint to web URL
+    web_url = endpoint.replace("api.", "").replace("/api", "")
+    if "smith.langchain" in web_url:
+        return f"{web_url}/o/default/projects/p/{project}/runs/{run_id}"
+
+    return f"{web_url}/projects/{project}/runs/{run_id}"

yamlgraph/utils/llm_factory.py

@@ -0,0 +1,118 @@
+"""LLM Factory - Multi-provider abstraction for language models.
+
+This module provides a simple factory pattern for creating LLM instances
+across different providers (Anthropic, Mistral, OpenAI).
+"""
+
+import logging
+import os
+import threading
+from typing import Literal
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from yamlgraph.config import DEFAULT_MODELS
+
+logger = logging.getLogger(__name__)
+
+# Type alias for supported providers
+ProviderType = Literal["anthropic", "mistral", "openai"]
+
+# Thread-safe cache for LLM instances
+_llm_cache: dict[tuple, BaseChatModel] = {}
+_cache_lock = threading.Lock()
+
+
+def create_llm(
+    provider: ProviderType | None = None,
+    model: str | None = None,
+    temperature: float = 0.7,
+) -> BaseChatModel:
+    """Create an LLM instance with multi-provider support.
+
+    Supports Anthropic (default), Mistral, and OpenAI providers.
+    Provider can be specified via parameter or PROVIDER environment variable.
+    Model can be specified via parameter or {PROVIDER}_MODEL environment variable.
+
+    LLM instances are cached by (provider, model, temperature) to improve performance.
+
+    Args:
+        provider: LLM provider ("anthropic", "mistral", "openai").
+                 Defaults to PROVIDER env var or "anthropic".
+        model: Model name. Defaults to {PROVIDER}_MODEL env var or provider default.
+        temperature: Temperature for generation (0.0-1.0).
+
+    Returns:
+        Configured LLM instance.
+
+    Raises:
+        ValueError: If provider is invalid.
+
+    Examples:
+        >>> # Use default Anthropic
+        >>> llm = create_llm(temperature=0.7)
+
+        >>> # Override provider
+        >>> llm = create_llm(provider="mistral", temperature=0.8)
+
+        >>> # Custom model
+        >>> llm = create_llm(provider="openai", model="gpt-4o-mini")
+    """
+    # Determine provider (parameter > env var > default)
+    selected_provider = provider or os.getenv("PROVIDER") or "anthropic"
+
+    # Validate provider
+    if selected_provider not in DEFAULT_MODELS:
+        raise ValueError(
+            f"Invalid provider: {selected_provider}. "
+            f"Must be one of: {', '.join(DEFAULT_MODELS.keys())}"
+        )
+
+    # Determine model (parameter > env var > default)
+    # Note: DEFAULT_MODELS already handles env var via config.py
+    selected_model = model or DEFAULT_MODELS[selected_provider]
+
+    # Create cache key
+    cache_key = (selected_provider, selected_model, temperature)
+
+    # Thread-safe cache access
+    with _cache_lock:
+        # Return cached instance if available
+        if cache_key in _llm_cache:
+            logger.debug(
+                f"Using cached LLM: {selected_provider}/{selected_model} (temp={temperature})"
+            )
+            return _llm_cache[cache_key]
+
+        # Create new LLM instance
+        logger.info(
+            f"Creating LLM: {selected_provider}/{selected_model} (temp={temperature})"
+        )
+
+        if selected_provider == "mistral":
+            from langchain_mistralai import ChatMistralAI
+
+            llm = ChatMistralAI(model=selected_model, temperature=temperature)
+        elif selected_provider == "openai":
+            from langchain_openai import ChatOpenAI
+
+            llm = ChatOpenAI(model=selected_model, temperature=temperature)
+        else:  # anthropic (default)
+            from langchain_anthropic import ChatAnthropic
+
+            llm = ChatAnthropic(model=selected_model, temperature=temperature)
+
+        # Cache the instance
+        _llm_cache[cache_key] = llm
+
+        return llm
+
+
+def clear_cache() -> None:
+    """Clear the LLM instance cache.
+
+    Useful for testing or when you want to force recreation of LLM instances.
+    """
+    with _cache_lock:
+        _llm_cache.clear()
+    logger.debug("LLM cache cleared")

yamlgraph/utils/llm_factory_async.py

@@ -0,0 +1,105 @@
+"""Async LLM Factory - Async versions of LLM creation.
+
+This module provides async-compatible LLM creation with support for
+non-blocking I/O operations in async contexts.
+
+Note: This module is a foundation for future async support. Currently,
+LangChain's LLM implementations use sync HTTP clients internally, so
+this wraps them for use in async contexts via run_in_executor.
+"""
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from functools import partial
+from typing import TypeVar
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import BaseMessage
+from pydantic import BaseModel
+
+from yamlgraph.utils.llm_factory import ProviderType, create_llm
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+# Shared executor for running sync LLM calls
+_executor: ThreadPoolExecutor | None = None
+
+
+def get_executor() -> ThreadPoolExecutor:
+    """Get or create the shared thread pool executor."""
+    global _executor
+    if _executor is None:
+        _executor = ThreadPoolExecutor(max_workers=4)
+    return _executor
+
+
+async def create_llm_async(
+    provider: ProviderType | None = None,
+    model: str | None = None,
+    temperature: float = 0.7,
+) -> BaseChatModel:
+    """Create an LLM instance asynchronously.
+
+    Currently wraps the sync create_llm. Future versions may use
+    native async LLM implementations.
+
+    Args:
+        provider: LLM provider ("anthropic", "mistral", "openai")
+        model: Model name
+        temperature: Temperature for generation
+
+    Returns:
+        Configured LLM instance
+    """
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(
+        get_executor(),
+        partial(create_llm, provider=provider, model=model, temperature=temperature),
+    )
+
+
+async def invoke_async(
+    llm: BaseChatModel,
+    messages: list[BaseMessage],
+    output_model: type[T] | None = None,
+) -> T | str:
+    """Invoke LLM asynchronously.
+
+    Runs the sync invoke in a thread pool to avoid blocking.
+
+    Args:
+        llm: The LLM instance
+        messages: Messages to send
+        output_model: Optional Pydantic model for structured output
+
+    Returns:
+        LLM response (parsed model or string)
+    """
+    loop = asyncio.get_event_loop()
+
+    def sync_invoke() -> T | str:
+        if output_model:
+            structured_llm = llm.with_structured_output(output_model)
+            return structured_llm.invoke(messages)
+        else:
+            response = llm.invoke(messages)
+            return response.content
+
+    return await loop.run_in_executor(get_executor(), sync_invoke)
+
+
+def shutdown_executor() -> None:
+    """Shutdown the thread pool executor.
+
+    Call this during application shutdown to clean up resources.
+    """
+    global _executor
+    if _executor is not None:
+        _executor.shutdown(wait=True)
+        _executor = None
+
+
+__all__ = ["create_llm_async", "invoke_async", "shutdown_executor"]

yamlgraph/utils/logging.py

@@ -0,0 +1,127 @@
+"""Structured logging configuration for yamlgraph.
+
+Provides consistent logging across all modules with JSON-formatted
+output for production environments.
+"""
+
+import logging
+import os
+import sys
+from typing import Any
+
+
+class StructuredFormatter(logging.Formatter):
+    """Formatter that outputs structured log messages.
+
+    In production (LOG_FORMAT=json), outputs JSON lines.
+    In development, outputs human-readable format.
+    """
+
+    def __init__(self, use_json: bool = False):
+        super().__init__()
+        self.use_json = use_json
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record."""
+        if self.use_json:
+            import json
+
+            log_data = {
+                "timestamp": self.formatTime(record),
+                "level": record.levelname,
+                "logger": record.name,
+                "message": record.getMessage(),
+            }
+            # Add extra fields if present
+            if hasattr(record, "extra"):
+                log_data.update(record.extra)
+            if record.exc_info:
+                log_data["exception"] = self.formatException(record.exc_info)
+            return json.dumps(log_data)
+        else:
+            # Human-readable format
+            base = f"{self.formatTime(record)} [{record.levelname}] {record.name}: {record.getMessage()}"
+            if record.exc_info:
+                base += f"\n{self.formatException(record.exc_info)}"
+            return base
+
+
+def setup_logging(
+    level: str | None = None,
+    use_json: bool | None = None,
+) -> logging.Logger:
+    """Configure logging for yamlgraph.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR).
+               Defaults to LOG_LEVEL env var or INFO.
+        use_json: If True, output JSON lines.
+                  Defaults to LOG_FORMAT=json env var.
+
+    Returns:
+        Root logger for the yamlgraph package
+    """
+    if level is None:
+        level = os.getenv("LOG_LEVEL", "INFO")
+
+    if use_json is None:
+        use_json = os.getenv("LOG_FORMAT", "").lower() == "json"
+
+    # Get the yamlgraph logger
+    logger = logging.getLogger("yamlgraph")
+    logger.setLevel(getattr(logging, level.upper()))
+
+    # Remove existing handlers
+    logger.handlers.clear()
+
+    # Add handler with formatter
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(StructuredFormatter(use_json=use_json))
+    logger.addHandler(handler)
+
+    # Don't propagate to root logger
+    logger.propagate = False
+
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger for a specific module.
+
+    Args:
+        name: Module name (typically __name__)
+
+    Returns:
+        Logger instance
+
+    Example:
+        >>> logger = get_logger(__name__)
+        >>> logger.info("Processing started", extra={"topic": "AI"})
+    """
+    return logging.getLogger(name)
+
+
+def log_with_context(
+    logger: logging.Logger,
+    level: int,
+    message: str,
+    **context: Any,
+) -> None:
+    """Log a message with additional context fields.
+
+    Args:
+        logger: Logger instance
+        level: Log level (logging.INFO, etc.)
+        message: Log message
+        **context: Additional context fields
+
+    Example:
+        >>> log_with_context(logger, logging.INFO, "Node completed",
+        ...                  node="generate", duration=1.5)
+    """
+    extra = {"extra": context} if context else {}
+    logger.log(level, message, extra=extra)
+
+
+# Initialize logging on import
+_root_logger = setup_logging()