tsugite-cli 0.3.3__py3-none-any.whl

tsugite/benchmark/utils.py

@@ -0,0 +1,288 @@
+"""Common utilities for benchmark framework."""
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from .config import TEST_CATEGORIES
+
+
+def extract_inline_field(content: str, label: str) -> Optional[str]:
+    """Extract single-line field values like Prompt or Expected Output.
+
+    Args:
+        content: Markdown content to search
+        label: Field label to extract (e.g., "Prompt", "Expected Output")
+
+    Returns:
+        Extracted field value or None if not found
+    """
+    pattern_label = re.escape(label)
+
+    # Try quoted format first
+    quoted = re.search(rf"\*\*{pattern_label}:\*\*\s*\"([^\"]+)\"", content)
+    if quoted:
+        return quoted.group(1).strip()
+
+    # Try block format
+    block = re.search(rf"\*\*{pattern_label}:\*\*\s*(.+?)(?=\n\*\*|$)", content, re.DOTALL)
+    if block:
+        return block.group(1).strip()
+
+    return None
+
+
+def extract_block(content: str, label: str) -> Optional[str]:
+    """Extract multi-line blocks introduced by a bold label.
+
+    Args:
+        content: Markdown content to search
+        label: Block label (e.g., "Expected Behaviors")
+
+    Returns:
+        Block content or None if not found
+    """
+    pattern_label = re.escape(label)
+    match = re.search(rf"\*\*{pattern_label}:\*\*\n(.*?)(?=\n\*\*|\Z)", content, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def parse_bullet_list(block: Optional[str]) -> List[str]:
+    """Parse a bullet list from a markdown block.
+
+    Args:
+        block: Block containing bullet list
+
+    Returns:
+        List of bullet items (without leading "- ")
+    """
+    if not block:
+        return []
+    items = []
+    for line in block.splitlines():
+        line = line.strip()
+        if line.startswith("- "):
+            items.append(line[2:].strip())
+    return items
+
+
+def coerce_value(value: str) -> Any:
+    """Convert string value to appropriate Python type.
+
+    Args:
+        value: String value to convert
+
+    Returns:
+        Converted value (bool, None, number, or string)
+    """
+    raw = value.strip()
+    lowered = raw.lower()
+
+    # Check for boolean
+    if lowered in {"true", "false"}:
+        return lowered == "true"
+
+    # Check for null
+    if lowered == "null":
+        return None
+
+    # Try JSON parsing first
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        pass
+
+    # Try numeric conversion
+    try:
+        if "." in raw:
+            return float(raw)
+        return int(raw)
+    except ValueError:
+        # Return as string, removing quotes
+        return raw.strip("'\"")
+
+
+def parse_key_value_block(block: Optional[str]) -> Dict[str, Any]:
+    """Parse a key-value block from markdown.
+
+    Supports both simple key-value pairs and nested YAML structures:
+    - simple_key: value
+    - nested_key:
+        sub_key: value
+        another: value
+
+    Args:
+        block: Block containing key-value pairs (bullet list format)
+
+    Returns:
+        Dictionary of parsed key-value pairs
+    """
+    if not block:
+        return {}
+
+    result: Dict[str, Any] = {}
+    lines = block.splitlines()
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        # Skip non-bullet lines
+        if not stripped.startswith("- ") or ":" not in stripped:
+            i += 1
+            continue
+
+        # Extract key from bullet item
+        key_part = stripped[2:]  # Remove "- "
+        key, raw_value = key_part.split(":", 1)
+        key = key.strip()
+        raw_value = raw_value.strip()
+
+        # Check if this is a nested structure (value is empty or whitespace)
+        if not raw_value:
+            # Collect indented lines that follow
+            nested_lines = []
+            indent_level = None
+            i += 1
+
+            while i < len(lines):
+                next_line = lines[i]
+
+                # Check if line is indented (part of nested structure)
+                if next_line and not next_line[0].isspace():
+                    # Not indented, end of nested structure
+                    break
+
+                if next_line.strip():  # Non-empty indented line
+                    # Determine indent level from first indented line
+                    if indent_level is None:
+                        indent_level = len(next_line) - len(next_line.lstrip())
+
+                    # Remove the base indent level to get relative indentation
+                    if len(next_line) - len(next_line.lstrip()) >= indent_level:
+                        nested_lines.append(next_line[indent_level:])
+                    else:
+                        nested_lines.append(next_line.lstrip())
+
+                i += 1
+
+            # Parse nested structure as YAML
+            if nested_lines:
+                import yaml
+
+                nested_yaml = "\n".join(nested_lines)
+                try:
+                    result[key] = yaml.safe_load(nested_yaml)
+                except yaml.YAMLError:
+                    # If YAML parsing fails, store as string
+                    result[key] = nested_yaml
+            else:
+                result[key] = ""
+        else:
+            # Simple key-value pair on same line
+            result[key] = coerce_value(raw_value)
+            i += 1
+
+    return result
+
+
+def get_test_category(test_id: str) -> str:
+    """Extract category from test ID.
+
+    Args:
+        test_id: Test identifier
+
+    Returns:
+        Category name (e.g., "basic", "tools", "unknown")
+    """
+    return TEST_CATEGORIES.get_category(test_id)
+
+
+def extract_prompt_from_markdown(markdown_content: str) -> str:
+    """Derive a prompt from markdown content when none is provided explicitly.
+
+    Args:
+        markdown_content: Markdown content
+
+    Returns:
+        Extracted prompt or default message
+    """
+    for line in markdown_content.splitlines():
+        stripped = line.strip()
+        # Skip empty lines and headers
+        if not stripped or stripped.startswith("#"):
+            continue
+        return stripped
+    return "Describe the required task in detail."
+
+
+def normalize_code(code: str) -> str:
+    """Normalize code for comparison by removing comments and extra whitespace.
+
+    Args:
+        code: Source code
+
+    Returns:
+        Normalized code
+    """
+    lines = []
+    for line in code.split("\n"):
+        # Remove comments (simplified - handles # and //)
+        line = re.sub(r"#.*$", "", line)
+        line = re.sub(r"//.*$", "", line)
+        line = line.strip()
+        if line:
+            lines.append(line)
+
+    return "\n".join(lines)
+
+
+def json_similarity(obj1: Any, obj2: Any) -> float:
+    """Calculate similarity between JSON objects recursively.
+
+    Args:
+        obj1: First object
+        obj2: Second object
+
+    Returns:
+        Similarity score from 0.0 to 1.0
+    """
+    # Type mismatch
+    if type(obj1) is not type(obj2):
+        return 0.0
+
+    # Dictionary comparison
+    if isinstance(obj1, dict):
+        if not obj1 and not obj2:
+            return 1.0
+
+        all_keys = set(obj1.keys()) | set(obj2.keys())
+        if not all_keys:
+            return 1.0
+
+        key_scores = []
+        for key in all_keys:
+            if key in obj1 and key in obj2:
+                key_scores.append(json_similarity(obj1[key], obj2[key]))
+            else:
+                key_scores.append(0.0)
+
+        return sum(key_scores) / len(key_scores)
+
+    # List comparison
+    elif isinstance(obj1, list):
+        if len(obj1) != len(obj2):
+            return 0.5 if obj1 == obj2 else 0.0
+
+        if not obj1:
+            return 1.0
+
+        scores = [json_similarity(a, b) for a, b in zip(obj1, obj2)]
+        return sum(scores) / len(scores)
+
+    # Primitive comparison
+    else:
+        return 1.0 if obj1 == obj2 else 0.0

tsugite/builtin_agents/chat-assistant.md

@@ -0,0 +1,53 @@
+---
+name: chat-assistant
+description: A conversational assistant that can respond naturally or use tools when needed
+extends: none
+text_mode: true
+max_turns: 10
+tools:
+  - read_file
+  - write_file
+  - list_files
+  - web_search
+  - fetch_text
+  - run
+---
+
+You are a helpful conversational assistant with access to tools.
+
+## How to respond:
+
+**For simple conversational questions:** Respond directly with just your Thought:
+```
+Thought: Your answer here
+```
+
+**When you need to use tools or get information:** Write a code block:
+```
+Thought: I'll use [tool] to [action]
+```python
+result = list_files(path=".")
+final_answer(result)
+```
+```
+
+## Available tools you can use:
+
+- `list_files(path=".", pattern="*")` - List files in a directory
+- `read_file(path="file.txt")` - Read file contents
+- `write_file(path="file.txt", content="...")` - Write to a file
+- `web_search(query="...", max_results=5)` - Search the web and get a list of results
+  - Returns: `[{"title": "...", "url": "...", "snippet": "..."}]`
+  - **Important:** Format results nicely for the user! Extract relevant info from snippets and present clearly.
+  - Example for weather: Read the snippets and summarize the current conditions/forecast
+- `fetch_text(url="...")` - Fetch full content from a webpage as text
+  - Use this when search snippets aren't enough and you need the full page
+- `run(command="...")` - Run shell commands
+
+**Important:** When the user asks about files, directories, or anything requiring system information, ALWAYS use the appropriate tool with a code block!
+
+**Note:** When continuing a conversation, previous messages are automatically included in your context. You don't need to reference them explicitly - they're part of the conversation history.
+
+## Current Request
+
+{{ user_prompt }}

tsugite/builtin_agents/default.md

@@ -0,0 +1,140 @@
+---
+name: default
+description: Default base agent with sensible defaults
+extends: none
+max_turns: 10
+tools:
+  - spawn_agent
+  - read_file
+  - list_files
+  - task_*
+  - write_file
+  - edit_file
+prefetch:
+  - tool: list_agents
+    args: {}
+    assign: available_agents
+instructions: |
+  You are a helpful AI assistant running in the Tsugite agent framework.
+
+  Follow these guidelines:
+  - Be concise and direct in your responses
+  - Use available tools when they help accomplish the task
+  - Use task tracking tools (task_add, task_update, task_complete) to organize your work
+  - Complete all required tasks (optional tasks marked with ✨ are nice-to-have)
+  - Break down complex tasks into clear steps
+  - Ask clarifying questions when the task is ambiguous
+  {% if text_mode %}
+  - For simple responses: respond directly with ONLY "Thought: [answer]" - no additional explanation
+  - When using tools: write Python code blocks and call final_answer(result)
+  {% else %}
+  - Write Python code to accomplish tasks
+  - Call final_answer(result) when you've completed the task
+  {% endif %}
+
+  **IMPORTANT - Seeing Tool Results:**
+  - Tool results are NOT automatically visible to you in the next turn
+  - You MUST print() results if you want to see and use them later
+  - Example:
+    ```python
+    content = read_file("file.txt")
+    print(content)  # Now you can see it in your next reasoning turn
+    ```
+  - Or use final_answer() to see and return the result immediately
+---
+# Context
+
+{% if is_interactive %}
+**Interactive Mode**: You are currently in an interactive session with the user, you can ask questions to clarify the task.
+{% else %}
+**Non-Interactive Mode**: You are in a headless/non-interactive session. You cannot ask the user questions.
+{% endif %}
+
+{% if subagent_instructions is defined and subagent_instructions %}
+{{ subagent_instructions }}
+{% endif %}
+
+**Note:** When continuing a conversation, previous messages are automatically included in your context as part of the conversation history. You don't need to reference them explicitly.
+
+{% if step_number is defined %}
+
+## Multi-Step Execution
+
+You are in step {{ step_number }} of {{ total_steps }} ({{ step_name }}).
+
+**IMPORTANT Step Completion**:
+
+- Complete ONLY the task assigned in this step
+{% if text_mode %}- After completing the task, call final_answer(result) with your result
+{% else %}- After completing the task, write a Python code block with final_answer(result)
+- Example: ```python
+final_answer("step result")
+
+```
+{% endif %}- Do NOT generate additional conversational text after calling final_answer()
+- The framework will automatically present the next step - you do not need to ask or wait
+- Each step is independent - focus on this step's goal only
+
+{% endif %}
+
+{% if available_agents %}
+## Available Specialized Agents
+
+You can delegate to these specialized agents when they match the task:
+
+{{ available_agents }}
+
+To delegate a task, use: `spawn_agent(agent_path, prompt)`
+
+Only delegate when:
+1. A specialized agent clearly matches the task requirements
+2. The task would benefit from specialized knowledge or tools
+3. You can provide a clear, specific prompt for the agent
+
+**CRITICAL: When a subagent fully completes the task, return its result immediately:**
+```python
+result = spawn_agent("agents/code_review.md", "Review app.py for security issues")
+final_answer(result)  # STOP HERE - task is done, return the result
+```
+
+**Example 2: Only process results further if the subagent output needs additional work**
+
+```python
+# Spawn agent and store result
+review = spawn_agent("agents/code_review.md", "Review app.py")
+print(review)  # IMPORTANT: Print so you can see it in your next turn!
+# DON'T call final_answer() here - let the agent continue thinking
+```
+
+Then in the next turn, you can:
+
+- Analyze the review results (you'll see them because you printed)
+- Spawn additional agents
+- Combine data from multiple sources
+- Finally call `final_answer()` when truly done
+
+**Key principles:**
+
+- **If the subagent result fully answers the user's request → call final_answer(result) immediately**
+- Only process results further if you genuinely need to combine/transform them
+- Don't waste turns analyzing results that already answer the question
+- Tool/agent results are NOT automatically visible unless printed or passed to final_answer()
+
+{% endif %}
+{% if 'web_search' in tools %}
+
+## Web Search Guidelines
+
+When searching the web:
+
+- Use `web_search(query="...", max_results=5)` to get search results
+- Returns: `[{"title": "...", "url": "...", "snippet": "..."}]`
+- **Important:** Format results nicely for the user! Extract and summarize relevant information from snippets
+- Use `fetch_text(url="...")` to get full page content when snippets aren't enough
+{% endif %}
+
+{{ task_summary }}
+
+# Task
+
+{{ user_prompt }}

tsugite/builtin_agents.py

@@ -0,0 +1,5 @@
+"""Package-provided agent utilities.
+
+Package-provided agents are stored as .md files in the builtin_agents/ directory
+and are discovered automatically through the agent resolution system.
+"""

tsugite/cache.py

@@ -0,0 +1,195 @@
+"""Cache management for attachment content."""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional
+
+from tsugite.xdg import get_xdg_cache_path
+
+
+def get_cache_key(source: str) -> str:
+    """Generate cache key from source URL or path.
+
+    Args:
+        source: URL or file path to cache
+
+    Returns:
+        16-character hex string (first 16 chars of SHA256)
+    """
+    return hashlib.sha256(source.encode()).hexdigest()[:16]
+
+
+def get_cache_file_path(source: str) -> Path:
+    """Get cache file path for a source.
+
+    Args:
+        source: URL or file path
+
+    Returns:
+        Path to cache file
+    """
+    cache_dir = get_xdg_cache_path("attachments")
+    cache_key = get_cache_key(source)
+    return cache_dir / f"{cache_key}.txt"
+
+
+def get_cached_content(source: str) -> Optional[str]:
+    """Get cached content if exists.
+
+    Args:
+        source: URL or file path
+
+    Returns:
+        Cached content if exists, None otherwise
+    """
+    cache_file = get_cache_file_path(source)
+    if cache_file.exists():
+        return cache_file.read_text(encoding="utf-8")
+    return None
+
+
+def save_to_cache(source: str, content: str) -> None:
+    """Save content to cache.
+
+    Args:
+        source: URL or file path
+        content: Content to cache
+
+    Raises:
+        RuntimeError: If cache save fails
+    """
+    cache_file = get_cache_file_path(source)
+
+    # Ensure cache directory exists
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        cache_file.write_text(content, encoding="utf-8")
+
+        # Update metadata
+        _update_cache_metadata(source, cache_file)
+    except IOError as e:
+        raise RuntimeError(f"Failed to save cache for {source}: {e}") from e
+
+
+def _update_cache_metadata(source: str, cache_file: Path) -> None:
+    """Update cache metadata file.
+
+    Args:
+        source: Original source URL/path
+        cache_file: Path to cache file
+    """
+    metadata_file = get_xdg_cache_path("attachments") / "metadata.json"
+
+    # Load existing metadata
+    if metadata_file.exists():
+        try:
+            with open(metadata_file, "r", encoding="utf-8") as f:
+                metadata = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            metadata = {}
+    else:
+        metadata = {}
+
+    # Update entry
+    cache_key = get_cache_key(source)
+    metadata[cache_key] = {
+        "source": source,
+        "cached_at": datetime.now(timezone.utc).isoformat(),
+        "size": cache_file.stat().st_size,
+    }
+
+    # Save metadata
+    metadata_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with open(metadata_file, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2, ensure_ascii=False)
+    except IOError:
+        # Metadata update failure is not critical
+        pass
+
+
+def clear_cache(source: Optional[str] = None) -> int:
+    """Clear cache for source, or entire cache if source is None.
+
+    Args:
+        source: URL or file path to clear, or None to clear all
+
+    Returns:
+        Number of cache files deleted
+    """
+    cache_dir = get_xdg_cache_path("attachments")
+
+    if not cache_dir.exists():
+        return 0
+
+    count = 0
+
+    if source:
+        # Clear specific cache entry
+        cache_file = get_cache_file_path(source)
+        if cache_file.exists():
+            cache_file.unlink()
+            count = 1
+
+        # Update metadata
+        metadata_file = cache_dir / "metadata.json"
+        if metadata_file.exists():
+            try:
+                with open(metadata_file, "r", encoding="utf-8") as f:
+                    metadata = json.load(f)
+
+                cache_key = get_cache_key(source)
+                if cache_key in metadata:
+                    del metadata[cache_key]
+
+                with open(metadata_file, "w", encoding="utf-8") as f:
+                    json.dump(metadata, f, indent=2, ensure_ascii=False)
+            except (json.JSONDecodeError, IOError):
+                pass
+    else:
+        # Clear all cache files
+        for cache_file in cache_dir.glob("*.txt"):
+            cache_file.unlink()
+            count += 1
+
+        # Clear metadata
+        metadata_file = cache_dir / "metadata.json"
+        if metadata_file.exists():
+            metadata_file.unlink()
+
+    return count
+
+
+def list_cache() -> Dict[str, Dict[str, any]]:
+    """List all cached entries with metadata.
+
+    Returns:
+        Dictionary mapping cache keys to metadata
+    """
+    metadata_file = get_xdg_cache_path("attachments") / "metadata.json"
+
+    if not metadata_file.exists():
+        return {}
+
+    try:
+        with open(metadata_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def get_cache_info(source: str) -> Optional[Dict[str, any]]:
+    """Get cache metadata for a specific source.
+
+    Args:
+        source: URL or file path
+
+    Returns:
+        Metadata dict if cached, None otherwise
+    """
+    metadata = list_cache()
+    cache_key = get_cache_key(source)
+    return metadata.get(cache_key)