ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/tools/mcp.py

@@ -0,0 +1,108 @@
+"""MCP client for tool integration."""
+
+from typing import Any, Optional
+from dataclasses import dataclass
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+@dataclass
+class MCPTool:
+    """MCP tool definition."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    server_name: str
+
+
+class MCPClient:
+    """Client for MCP server communication."""
+
+    def __init__(self, server_config: dict[str, Any]):
+        """
+        Initialize MCP client.
+
+        Args:
+            server_config: Server configuration with command, args, env
+        """
+        self.server_name = server_config.get("name", "unknown")
+        self.server_params = StdioServerParameters(
+            command=server_config["command"][0],
+            args=server_config["command"][1:],
+            env=server_config.get("env"),
+        )
+        self.session: Optional[ClientSession] = None
+        self.read = None
+        self.write = None
+        self._exit_stack: Optional[AsyncExitStack] = None
+
+    async def start(self) -> None:
+        """Start MCP server and initialize session."""
+        self._exit_stack = AsyncExitStack()
+
+        # Enter the stdio_client context and keep it alive
+        streams = await self._exit_stack.enter_async_context(
+            stdio_client(self.server_params)  # type: ignore[arg-type]
+        )
+        self.read, self.write = streams
+
+        # Initialize session
+        self.session = ClientSession(self.read, self.write)  # type: ignore[arg-type]
+        await self.session.initialize()
+
+    async def stop(self) -> None:
+        """Stop MCP server and close session."""
+        if self._exit_stack:
+            await self._exit_stack.aclose()
+            self._exit_stack = None
+        self.session = None
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        """
+        Execute tool via MCP protocol.
+
+        Args:
+            name: Tool name
+            arguments: Tool arguments
+
+        Returns:
+            Tool result
+        """
+        if not self.session:
+            raise RuntimeError("MCP session not initialized")
+
+        result = await self.session.call_tool(name, arguments)
+        return result.content
+
+    async def list_tools(self) -> list[MCPTool]:
+        """
+        Get available tools from server.
+
+        Returns:
+            List of available tools
+        """
+        if not self.session:
+            raise RuntimeError("MCP session not initialized")
+
+        tools_result = await self.session.list_tools()
+        return [
+            MCPTool(
+                name=tool.name,
+                description=tool.description or "",
+                input_schema=tool.inputSchema,
+                server_name=self.server_name,
+            )
+            for tool in tools_result.tools
+        ]
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.stop()

ctrlcode/tools/observability.py

@@ -0,0 +1,561 @@
+"""Observability tools for Executor agent."""
+
+import json
+import logging
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ObservabilityTools:
+    """Observability tools for log and metrics analysis."""
+
+    def __init__(self, log_dir: str | Path | None = None):
+        """
+        Initialize observability tools.
+
+        Args:
+            log_dir: Directory containing log files (defaults to .ctrlcode/logs/)
+        """
+        if log_dir is None:
+            log_dir = Path.cwd() / ".ctrlcode" / "logs"
+        self.log_dir = Path(log_dir)
+
+    def query_logs(
+        self,
+        query: str | None = None,
+        time_range: str = "1h",
+        log_dir: str | None = None,
+        max_results: int = 100,
+    ) -> dict[str, Any]:
+        """
+        Query application logs with LogQL-style filtering.
+
+        Supports simple LogQL-style queries for filtering logs:
+        - `{key="value"}` - Filter by key-value pairs
+        - `|= "text"` - Contains text
+        - `!= "text"` - Doesn't contain text
+
+        Args:
+            query: LogQL-style query string (e.g., '{level="ERROR"} |= "database"')
+            time_range: Time range to search (e.g., "1h", "30m", "1d")
+            log_dir: Directory containing log files (defaults to .ctrlcode/logs/)
+            max_results: Maximum number of log entries to return
+
+        Returns:
+            Dict with:
+                - matches: List of matching log entries
+                - count: Number of matches
+                - query: Original query
+                - time_range: Time range searched
+
+        Examples:
+            # Find all errors
+            query_logs('{level="ERROR"}')
+
+            # Find failed login attempts
+            query_logs('{event="auth.login.failed"}')
+
+            # Find database errors in last 30 minutes
+            query_logs('{level="ERROR"} |= "database"', time_range="30m")
+
+            # Find logs for specific user
+            query_logs('{user_id="123"}', time_range="1d")
+        """
+        # Determine log directory
+        if log_dir is None:
+            log_path = self.log_dir
+        else:
+            log_path = Path(log_dir)
+
+        if not log_path.exists():
+            logger.warning(f"Log directory not found: {log_path}")
+            return {
+                "matches": [],
+                "count": 0,
+                "query": query,
+                "time_range": time_range,
+                "error": f"Log directory not found: {log_path}"
+            }
+
+        # Parse time range
+        try:
+            cutoff_time = _parse_time_range(time_range)
+        except ValueError as e:
+            return {
+                "matches": [],
+                "count": 0,
+                "query": query,
+                "time_range": time_range,
+                "error": str(e)
+            }
+
+        # Find log files
+        log_files = sorted(log_path.glob("*.log"), key=lambda p: p.stat().st_mtime, reverse=True)
+
+        if not log_files:
+            return {
+                "matches": [],
+                "count": 0,
+                "query": query,
+                "time_range": time_range,
+                "error": "No log files found"
+            }
+
+        # Parse query
+        filters = _parse_query(query) if query else {}
+
+        # Search logs
+        matches = []
+        for log_file in log_files:
+            try:
+                with open(log_file) as f:
+                    for line in f:
+                        line = line.strip()
+                        if not line:
+                            continue
+
+                        # Try to parse as JSON (structured log)
+                        try:
+                            entry = json.loads(line)
+                        except json.JSONDecodeError:
+                            # Fallback: treat as plain text
+                            entry = {
+                                "timestamp": None,
+                                "level": "UNKNOWN",
+                                "message": line
+                            }
+
+                        # Check time range
+                        if cutoff_time and "timestamp" in entry:
+                            try:
+                                log_time = datetime.fromisoformat(entry["timestamp"].replace("Z", "+00:00"))
+                                if log_time < cutoff_time:
+                                    continue
+                            except (ValueError, AttributeError):
+                                pass  # Include logs with unparseable timestamps
+
+                        # Apply filters
+                        if _matches_filters(entry, filters):
+                            matches.append(entry)
+
+                            if len(matches) >= max_results:
+                                break
+
+                if len(matches) >= max_results:
+                    break
+
+            except Exception as e:
+                logger.warning(f"Error reading log file {log_file}: {e}")
+
+        return {
+            "matches": matches,
+            "count": len(matches),
+            "query": query,
+            "time_range": time_range,
+            "searched_files": len(log_files),
+        }
+
+    def query_metrics(
+        self,
+        query: str | None = None,
+        time_range: str = "1h",
+        metrics_file: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Query performance metrics with PromQL-style filtering.
+
+        Simplified PromQL support for basic metric queries:
+        - Metric name selection
+        - Rate calculations
+        - Aggregations (avg, sum, max, min)
+
+        Args:
+            query: PromQL-style query (e.g., 'rate(http_requests_total[5m])')
+            time_range: Time range to query (e.g., "1h", "30m")
+            metrics_file: Path to metrics file (defaults to .ctrlcode/logs/metrics.jsonl)
+
+        Returns:
+            Dict with:
+                - values: List of metric values
+                - aggregates: Summary statistics
+                - query: Original query
+                - time_range: Time range queried
+
+        Examples:
+            # Get request rate
+            query_metrics(query='rate(http_requests_total[5m])')
+
+            # Get average latency
+            query_metrics(query='avg(http_request_duration_ms)')
+
+            # Get p95 latency (if pre-calculated)
+            query_metrics(query='http_request_duration_ms_p95')
+        """
+        # Determine metrics file
+        if metrics_file is None:
+            metrics_path = self.log_dir / "metrics.jsonl"
+        else:
+            metrics_path = Path(metrics_file)
+
+        if not metrics_path.exists():
+            # Try to extract metrics from test output or benchmarks
+            return self._extract_metrics_from_output(query, time_range)
+
+        # Parse time range
+        try:
+            cutoff_time = _parse_time_range(time_range)
+        except ValueError as e:
+            return {
+                "values": [],
+                "aggregates": {},
+                "query": query,
+                "time_range": time_range,
+                "error": str(e)
+            }
+
+        # Parse query
+        metric_name, operation = _parse_metric_query(query) if query else (None, None)
+
+        # Read metrics
+        values = []
+        try:
+            with open(metrics_path) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    try:
+                        entry = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    # Check time range
+                    if "timestamp" in entry:
+                        try:
+                            metric_time = datetime.fromisoformat(entry["timestamp"].replace("Z", "+00:00"))
+                            if metric_time < cutoff_time:
+                                continue
+                        except (ValueError, AttributeError):
+                            pass
+
+                    # Extract metric value
+                    if metric_name and metric_name in entry:
+                        values.append(float(entry[metric_name]))
+                    elif not metric_name:
+                        # No specific metric, collect all numeric values
+                        for key, value in entry.items():
+                            if isinstance(value, (int, float)) and key != "timestamp":
+                                values.append(float(value))
+
+        except Exception as e:
+            return {
+                "values": [],
+                "aggregates": {},
+                "query": query,
+                "time_range": time_range,
+                "error": f"Error reading metrics: {e}"
+            }
+
+        # Calculate aggregates
+        aggregates = {}
+        if values:
+            aggregates = {
+                "count": len(values),
+                "avg": sum(values) / len(values),
+                "min": min(values),
+                "max": max(values),
+                "sum": sum(values),
+            }
+
+            # Calculate percentiles if enough data
+            if len(values) >= 10:
+                sorted_values = sorted(values)
+                aggregates["p50"] = sorted_values[len(sorted_values) // 2]
+                aggregates["p95"] = sorted_values[int(len(sorted_values) * 0.95)]
+                aggregates["p99"] = sorted_values[int(len(sorted_values) * 0.99)]
+
+        return {
+            "values": values,
+            "aggregates": aggregates,
+            "query": query,
+            "time_range": time_range,
+            "metric_name": metric_name,
+            "operation": operation,
+        }
+
+    def _extract_metrics_from_output(self, query: str | None, time_range: str) -> dict[str, Any]:
+        """
+        Extract metrics from test output or benchmark results as fallback.
+
+        When no metrics file exists, try to parse from:
+        - pytest output
+        - benchmark results
+        - load test output (ab, wrk)
+        """
+        # Try to find recent test output or benchmark files
+        possible_files = [
+            self.log_dir / "test_output.log",
+            self.log_dir / "benchmark.txt",
+            self.log_dir.parent / "test_output.log",
+        ]
+
+        for file_path in possible_files:
+            if file_path.exists():
+                try:
+                    content = file_path.read_text()
+
+                    # Parse latency from wrk output
+                    latency_match = re.search(r"Latency\s+(\d+\.?\d*)ms", content)
+                    if latency_match:
+                        return {
+                            "values": [float(latency_match.group(1))],
+                            "aggregates": {"latency_ms": float(latency_match.group(1))},
+                            "query": query,
+                            "time_range": time_range,
+                            "source": "wrk_output"
+                        }
+
+                    # Parse from ab (Apache Bench) output
+                    ab_time_match = re.search(r"Time per request:\s+(\d+\.?\d*)", content)
+                    if ab_time_match:
+                        return {
+                            "values": [float(ab_time_match.group(1))],
+                            "aggregates": {"time_per_request_ms": float(ab_time_match.group(1))},
+                            "query": query,
+                            "time_range": time_range,
+                            "source": "ab_output"
+                        }
+
+                except Exception:
+                    continue
+
+        return {
+            "values": [],
+            "aggregates": {},
+            "query": query,
+            "time_range": time_range,
+            "error": "No metrics file found and could not extract from test output"
+        }
+
+
+def _parse_time_range(time_range: str) -> datetime:
+    """
+    Parse time range string to cutoff datetime.
+
+    Args:
+        time_range: String like "1h", "30m", "1d", "2w"
+
+    Returns:
+        Datetime representing cutoff (now - range)
+
+    Raises:
+        ValueError: If time_range format invalid
+    """
+    match = re.match(r"(\d+)([smhdw])", time_range)
+    if not match:
+        raise ValueError(f"Invalid time range format: {time_range}. Expected format: <number><unit> (e.g., 1h, 30m)")
+
+    amount = int(match.group(1))
+    unit = match.group(2)
+
+    units = {
+        "s": "seconds",
+        "m": "minutes",
+        "h": "hours",
+        "d": "days",
+        "w": "weeks",
+    }
+
+    if unit not in units:
+        raise ValueError(f"Invalid time unit: {unit}. Supported: s, m, h, d, w")
+
+    delta = timedelta(**{units[unit]: amount})
+    return datetime.now() - delta
+
+
+def _parse_query(query: str) -> dict[str, Any]:
+    """
+    Parse LogQL-style query into filters.
+
+    Supports:
+    - {key="value"} - Equality filters
+    - |= "text" - Contains text
+    - != "text" - Doesn't contain text
+
+    Args:
+        query: LogQL-style query string
+
+    Returns:
+        Dict with filter criteria
+    """
+    filters = {
+        "equals": {},      # {key: value}
+        "contains": [],    # [text1, text2]
+        "excludes": [],    # [text1, text2]
+    }
+
+    # Extract {key="value"} filters
+    label_pattern = r'\{([^}]+)\}'
+    label_matches = re.findall(label_pattern, query)
+
+    for label_match in label_matches:
+        # Parse key="value" pairs
+        pairs = re.findall(r'(\w+)="([^"]+)"', label_match)
+        for key, value in pairs:
+            filters["equals"][key] = value
+
+    # Extract |= "text" (contains)
+    contains_pattern = r'\|=\s*"([^"]+)"'
+    contains_matches = re.findall(contains_pattern, query)
+    filters["contains"].extend(contains_matches)
+
+    # Extract != "text" (excludes)
+    excludes_pattern = r'!=\s*"([^"]+)"'
+    excludes_matches = re.findall(excludes_pattern, query)
+    filters["excludes"].extend(excludes_matches)
+
+    return filters
+
+
+def _matches_filters(entry: dict[str, Any], filters: dict[str, Any]) -> bool:
+    """
+    Check if log entry matches filter criteria.
+
+    Args:
+        entry: Log entry (dict)
+        filters: Filter criteria from _parse_query
+
+    Returns:
+        True if entry matches all filters
+    """
+    # Check equality filters
+    for key, expected_value in filters.get("equals", {}).items():
+        if key not in entry:
+            return False
+        if str(entry[key]) != expected_value:
+            return False
+
+    # Convert entry to string for text matching
+    entry_str = json.dumps(entry).lower()
+
+    # Check contains filters
+    for text in filters.get("contains", []):
+        if text.lower() not in entry_str:
+            return False
+
+    # Check excludes filters
+    for text in filters.get("excludes", []):
+        if text.lower() in entry_str:
+            return False
+
+    return True
+
+
+def _parse_metric_query(query: str) -> tuple[str | None, str | None]:
+    """
+    Parse simple PromQL-style query into metric name and operation.
+
+    Supports basic patterns:
+    - metric_name
+    - rate(metric_name[5m])
+    - avg(metric_name)
+
+    Args:
+        query: PromQL-style query string
+
+    Returns:
+        Tuple of (metric_name, operation)
+    """
+    # Pattern: rate(metric_name[time_window])
+    rate_match = re.match(r'rate\((\w+)\[[\w\d]+\]\)', query)
+    if rate_match:
+        return rate_match.group(1), "rate"
+
+    # Pattern: aggregation(metric_name)
+    agg_match = re.match(r'(avg|sum|max|min)\((\w+)\)', query)
+    if agg_match:
+        return agg_match.group(2), agg_match.group(1)
+
+    # Simple metric name
+    if query and re.match(r'^\w+$', query):
+        return query, None
+
+    return None, None
+
+
+OBSERVABILITY_TOOL_SCHEMAS = [
+    {
+        "name": "query_logs",
+        "description": """Query application logs with LogQL-style filtering.
+
+Supports queries like:
+- {level="ERROR"} - Find error logs
+- {event="auth.login.failed"} - Find failed login attempts
+- {user_id="123"} - Find logs for specific user
+- {level="ERROR"} |= "database" - Find error logs containing "database"
+
+Time ranges: 1h (1 hour), 30m (30 minutes), 1d (1 day), 1w (1 week)
+
+Returns structured log entries with timestamp, level, event, and context fields.""",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": 'LogQL-style query (e.g., \'{level="ERROR"} |= "database"\')'
+                },
+                "time_range": {
+                    "type": "string",
+                    "description": "Time range to search (e.g., 1h, 30m, 1d)",
+                    "default": "1h"
+                },
+                "log_dir": {
+                    "type": "string",
+                    "description": "Directory containing log files (optional)"
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return",
+                    "default": 100
+                }
+            },
+        }
+    },
+    {
+        "name": "query_metrics",
+        "description": """Query performance metrics with PromQL-style filtering.
+
+Supports queries like:
+- rate(http_requests_total[5m]) - Request rate over 5 minutes
+- avg(http_request_duration_ms) - Average request latency
+- http_request_duration_ms_p95 - 95th percentile latency
+
+Time ranges: 1h (1 hour), 30m (30 minutes), 1d (1 day), 1w (1 week)
+
+Returns metric values and aggregates (avg, min, max, p50, p95, p99).
+Falls back to extracting metrics from test output if no metrics file exists.""",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": 'PromQL-style query (e.g., "rate(http_requests_total[5m])")'
+                },
+                "time_range": {
+                    "type": "string",
+                    "description": "Time range to query (e.g., 1h, 30m, 1d)",
+                    "default": "1h"
+                },
+                "metrics_file": {
+                    "type": "string",
+                    "description": "Path to metrics file (optional)"
+                }
+            },
+        }
+    }
+]