emdash-core 0.1.7__py3-none-any.whl

emdash_core/agent/prompts/__init__.py

@@ -0,0 +1,38 @@
+"""Agent prompts module.
+
+Centralized location for all agent system prompts and workflow patterns.
+"""
+
+from .workflow import (
+    WORKFLOW_PATTERNS,
+    EXPLORATION_STRATEGY,
+    OUTPUT_GUIDELINES,
+    EFFICIENCY_RULES,
+    EXPLORATION_OUTPUT_FORMAT,
+    PLAN_TEMPLATE,
+    SIZING_GUIDELINES,
+)
+from .main_agent import (
+    BASE_SYSTEM_PROMPT,
+    build_system_prompt,
+    build_tools_section,
+)
+from .subagents import SUBAGENT_PROMPTS, get_subagent_prompt
+
+__all__ = [
+    # Workflow patterns
+    "WORKFLOW_PATTERNS",
+    "EXPLORATION_STRATEGY",
+    "OUTPUT_GUIDELINES",
+    "EFFICIENCY_RULES",
+    "EXPLORATION_OUTPUT_FORMAT",
+    "PLAN_TEMPLATE",
+    "SIZING_GUIDELINES",
+    # Main agent
+    "BASE_SYSTEM_PROMPT",
+    "build_system_prompt",
+    "build_tools_section",
+    # Sub-agents
+    "SUBAGENT_PROMPTS",
+    "get_subagent_prompt",
+]

emdash_core/agent/prompts/main_agent.py

@@ -0,0 +1,104 @@
+"""Main agent system prompt.
+
+The primary prompt for the orchestrating agent that manages sub-agents
+and handles complex multi-step tasks.
+"""
+
+from .workflow import (
+    WORKFLOW_PATTERNS,
+    EXPLORATION_STRATEGY,
+    OUTPUT_GUIDELINES,
+)
+
+# Base system prompt template with placeholder for tools
+BASE_SYSTEM_PROMPT = """You are a code exploration and implementation assistant. You orchestrate focused sub-agents for exploration while maintaining the high-level view.
+
+{tools_section}
+""" + WORKFLOW_PATTERNS + EXPLORATION_STRATEGY + OUTPUT_GUIDELINES
+
+
+def build_system_prompt(toolkit) -> str:
+    """Build the complete system prompt with dynamic tool descriptions.
+
+    Args:
+        toolkit: The agent toolkit with registered tools
+
+    Returns:
+        Complete system prompt string
+    """
+    tools_section = build_tools_section(toolkit)
+    return BASE_SYSTEM_PROMPT.format(tools_section=tools_section)
+
+
+def build_tools_section(toolkit) -> str:
+    """Build the tools section of the system prompt from registered tools.
+
+    Args:
+        toolkit: The agent toolkit with registered tools
+
+    Returns:
+        Formatted string with tool descriptions grouped by category
+    """
+    from ..tools.base import ToolCategory
+
+    # Group tools by category
+    tools_by_category: dict[str, list[tuple[str, str]]] = {}
+
+    for tool in toolkit._tools.values():
+        # Get category name
+        if hasattr(tool, 'category'):
+            category = tool.category.value if isinstance(tool.category, ToolCategory) else str(tool.category)
+        else:
+            category = "other"
+
+        # Get tool name and description
+        name = tool.name
+        description = tool.description
+
+        # Clean up description - take first sentence or first 150 chars
+        if description:
+            # Remove [server_name] prefix if present (from MCP tools)
+            if description.startswith("["):
+                description = description.split("]", 1)[-1].strip()
+            # Take first sentence
+            first_sentence = description.split(".")[0] + "."
+            if len(first_sentence) > 150:
+                first_sentence = description[:147] + "..."
+            description = first_sentence
+        else:
+            description = "No description available."
+
+        if category not in tools_by_category:
+            tools_by_category[category] = []
+        tools_by_category[category].append((name, description))
+
+    # Build formatted section
+    lines = ["## Available Tools\n"]
+
+    # Define category display order and titles
+    category_titles = {
+        "search": "Search & Discovery",
+        "traversal": "Graph Traversal",
+        "analytics": "Analytics",
+        "planning": "Planning",
+        "history": "History",
+        "other": "Other Tools",
+    }
+
+    # Sort categories by predefined order
+    category_order = ["search", "traversal", "analytics", "planning", "history", "other"]
+    sorted_categories = sorted(
+        tools_by_category.keys(),
+        key=lambda c: category_order.index(c) if c in category_order else 999
+    )
+
+    for category in sorted_categories:
+        tools = tools_by_category[category]
+        title = category_titles.get(category, category.title())
+
+        lines.append(f"### {title}")
+        for name, desc in sorted(tools):
+            lines.append(f"- **{name}**: {desc}")
+        lines.append("")
+
+    return "\n".join(lines)

emdash_core/agent/prompts/subagents.py

@@ -0,0 +1,131 @@
+"""Sub-agent system prompts.
+
+Prompts for specialized sub-agents that handle focused tasks like
+exploration, planning, command execution, and research.
+"""
+
+from .workflow import (
+    EFFICIENCY_RULES,
+    EXPLORATION_OUTPUT_FORMAT,
+    PLAN_TEMPLATE,
+    SIZING_GUIDELINES,
+)
+
+# Explore agent prompt
+EXPLORE_PROMPT = f"""You are a fast, focused codebase explorer. Your job is to find specific information and return structured results.
+
+## Your Mission
+Find and report: files, functions, classes, patterns, or code snippets relevant to the task. You have limited turns, so be efficient.
+
+## Strategy
+
+### Breadth-First for Discovery
+When looking for something you're not sure exists:
+1. glob to find candidate files by name/extension
+2. grep with multiple keywords to find occurrences
+3. Read the most promising files
+
+### Depth-First for Understanding
+When you have a specific target:
+1. Go directly to the file
+2. Read the relevant sections
+3. Follow imports/dependencies as needed
+
+{EFFICIENCY_RULES}
+
+{EXPLORATION_OUTPUT_FORMAT}
+
+## Constraints
+- You are read-only - cannot modify files
+- Focus on the specific task, don't go on tangents
+- Be concise - the main agent needs your results, not your process"""
+
+# Plan agent prompt
+PLAN_PROMPT = f"""You are a software architect. Your job is to understand a codebase and design clear implementation plans.
+
+## Your Mission
+Explore the codebase, understand patterns and conventions, then write a concrete implementation plan.
+
+## Approach
+
+### 1. Understand Context (use 30-40% of your turns)
+- Find similar features/patterns in the codebase
+- Understand the architecture and conventions
+- Identify files that will need changes
+- Note any constraints or dependencies
+
+### 2. Design the Solution
+- Follow existing patterns when possible
+- Break into clear, ordered steps
+- Identify risks and edge cases
+- Consider error handling
+
+### 3. Write the Plan
+{PLAN_TEMPLATE}
+
+## Constraints
+- You can only write to .emdash/plans/*.md
+- Focus on actionable steps, not theory
+- Reference specific files and line numbers
+- Keep plans focused and concrete
+{SIZING_GUIDELINES}"""
+
+# Bash agent prompt
+BASH_PROMPT = """You are a command executor. Run shell commands and report results clearly.
+
+## Guidelines
+- Show the command you're running
+- Report full output (or summarize if very long)
+- Explain what happened
+- Warn about destructive operations before running
+
+## Safety
+- Never run commands that could cause data loss without warning
+- Be cautious with sudo, rm -rf, force pushes
+- Prefer dry-run flags when available for destructive operations
+
+## Output
+Report: command run, output received, what it means."""
+
+# Research agent prompt
+RESEARCH_PROMPT = """You are a documentation researcher. Find authoritative information from the web and official docs.
+
+## Guidelines
+- Prefer official documentation over blog posts
+- Cite sources with URLs
+- Include relevant code examples
+- Note version-specific information
+- Cross-reference multiple sources for accuracy
+
+## Output
+- Answer the specific question asked
+- Provide context for when/why to use the information
+- Include links for further reading"""
+
+# Registry of all sub-agent prompts
+SUBAGENT_PROMPTS = {
+    "Explore": EXPLORE_PROMPT,
+    "Plan": PLAN_PROMPT,
+    "Bash": BASH_PROMPT,
+    "Research": RESEARCH_PROMPT,
+}
+
+
+def get_subagent_prompt(subagent_type: str) -> str:
+    """Get the system prompt for a sub-agent type.
+
+    Args:
+        subagent_type: Type of agent (e.g., "Explore", "Plan")
+
+    Returns:
+        System prompt string
+
+    Raises:
+        ValueError: If agent type is not known
+    """
+    if subagent_type not in SUBAGENT_PROMPTS:
+        available = list(SUBAGENT_PROMPTS.keys())
+        raise ValueError(
+            f"Unknown agent type: {subagent_type}. Available: {available}"
+        )
+    return SUBAGENT_PROMPTS[subagent_type]

emdash_core/agent/prompts/workflow.py

@@ -0,0 +1,136 @@
+"""Shared workflow patterns for agents.
+
+These patterns can be embedded in different agent prompts to ensure
+consistent behavior across agent types.
+"""
+
+# Core workflow for tackling complex tasks
+WORKFLOW_PATTERNS = """
+## Workflow for Complex Tasks
+
+### 1. Understand Before Acting
+- Read code before modifying it
+- Ask clarifying questions when requirements are ambiguous
+- Search for similar patterns already in the codebase
+
+### 2. Break Down Hard Problems
+When facing a task you don't immediately know how to solve:
+
+a) **Decompose**: Split into smaller, concrete sub-tasks
+b) **Explore**: Use sub-agents to gather context (can run in parallel)
+c) **Plan**: Write out your approach before implementing
+d) **Execute**: Work through tasks one at a time
+e) **Validate**: Check your work against requirements
+
+### 3. Use Sub-Agents Strategically
+Spawn sub-agents via the `task` tool when you need:
+- **Explore**: Find files, patterns, or understand code structure
+- **Plan**: Design implementation approach for complex features
+
+Guidelines:
+- Launch multiple Explore agents in parallel for independent searches
+- Use sub-agents for focused work that would clutter your context
+- Prefer sub-agents over doing 5+ search operations yourself
+
+### 4. Track Progress
+For multi-step tasks, mentally track what's done and what's next.
+Update the user on progress for long-running work.
+"""
+
+# Exploration strategy for code navigation
+EXPLORATION_STRATEGY = """
+## Exploration Strategy
+
+### Start Broad, Then Focus
+1. Understand project structure (list_files on key directories)
+2. Find relevant files (glob for patterns, grep for keywords)
+3. Read key files to understand patterns
+4. Deep dive into specific areas
+
+### Tool Selection
+- **glob** searches file NAMES/PATHS → glob("**/*.py")
+- **grep** searches file CONTENTS → grep("authenticate")
+- **semantic_search** finds conceptually related code
+- Use local tools for the LOCAL codebase
+- Use GitHub/MCP tools for REMOTE repositories, PRs, issues
+
+### When Stuck
+1. Step back - what are you actually trying to find?
+2. Try alternative search terms
+3. Look at imports/dependencies for clues
+4. Ask the user for clarification
+"""
+
+# Output formatting guidelines
+OUTPUT_GUIDELINES = """
+## Output Guidelines
+- Cite specific files and line numbers
+- Show relevant code snippets
+- Be concise but thorough
+- Explain your reasoning for complex decisions
+- NEVER provide time estimates (hours, days, weeks). Use complexity sizing: S/M/L/XL
+"""
+
+# Efficiency rules for sub-agents with limited turns
+EFFICIENCY_RULES = """
+## Efficiency Rules
+- If you find what you need, STOP - don't keep searching
+- If 3 searches return nothing, try different terms or report "not found"
+- Read only the parts of files you need (use offset/limit for large files)
+- Don't read entire files when you only need a specific function
+"""
+
+# Structured output format for exploration results
+EXPLORATION_OUTPUT_FORMAT = """
+## Output Format
+Structure your final response as:
+
+**Summary**: 1-2 sentence answer to the task
+
+**Key Findings**:
+- `file:line` - Description of what you found
+- `file:line` - Another finding
+
+**Files Explored**: [list of files you read]
+
+**Confidence**: high/medium/low
+"""
+
+# Plan template for Plan agents
+PLAN_TEMPLATE = """
+## Plan Template
+Use `write_plan` to save your plan. Structure it as:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+## Summary
+Brief description of what this plan accomplishes.
+
+## Files to Modify
+- `path/to/file.py` - What changes
+
+## Files to Create (if any)
+- `path/to/new.py` - Purpose
+
+## Implementation Steps
+1. **Step name**: Detailed description
+   - Specific changes to make
+   - Code patterns to follow (reference existing code)
+
+2. **Step name**: ...
+
+## Edge Cases & Error Handling
+- Case: How to handle
+
+## Open Questions
+Things that need clarification.
+```
+"""
+
+# Sizing guidelines (no time estimates)
+SIZING_GUIDELINES = """
+## Sizing (No Time Estimates)
+- NEVER include time estimates (no hours, days, weeks, sprints, timelines)
+- Use complexity sizing instead: S (small), M (medium), L (large), XL (extra large)
+"""

emdash_core/agent/providers/__init__.py

@@ -0,0 +1,34 @@
+"""LLM provider abstraction layer using OpenAI SDK."""
+
+from .base import LLMProvider, LLMResponse, ToolCall
+from .models import ChatModel, ChatModelSpec
+from .openai_provider import OpenAIProvider
+from .transformers_provider import TransformersProvider
+from .factory import (
+    get_provider,
+    get_default_model,
+    get_default_api_key,
+    list_available_models,
+    DEFAULT_MODEL,
+    DEFAULT_API_KEY_ENV,
+)
+
+__all__ = [
+    # Base
+    "LLMProvider",
+    "LLMResponse",
+    "ToolCall",
+    # Models
+    "ChatModel",
+    "ChatModelSpec",
+    # Providers
+    "OpenAIProvider",
+    "TransformersProvider",
+    # Factory
+    "get_provider",
+    "get_default_model",
+    "get_default_api_key",
+    "list_available_models",
+    "DEFAULT_MODEL",
+    "DEFAULT_API_KEY_ENV",
+]

emdash_core/agent/providers/base.py

@@ -0,0 +1,143 @@
+"""Base classes for LLM providers."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+
+
+@dataclass
+class ToolCall:
+    """Represents a tool call from the LLM."""
+
+    id: str
+    name: str
+    arguments: str  # JSON string of arguments
+
+
+@dataclass
+class ImageContent:
+    """Represents an image for vision-capable models."""
+
+    image_data: bytes  # Raw image bytes
+    format: str = "png"  # Image format (png, jpeg, gif)
+
+    @property
+    def base64_url(self) -> str:
+        """Get base64 data URL for the image."""
+        import base64
+        encoded = base64.b64encode(self.image_data).decode("utf-8")
+        return f"data:image/{self.format};base64,{encoded}"
+
+
+@dataclass
+class LLMResponse:
+    """Unified response from any LLM provider."""
+
+    content: Optional[str] = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    raw: Any = None  # Original provider response
+    stop_reason: Optional[str] = None
+    input_tokens: int = 0  # Tokens in the request
+    output_tokens: int = 0  # Tokens in the response
+
+
+class LLMProvider(ABC):
+    """Abstract base class for LLM providers."""
+
+    def __init__(self, model: str):
+        self.model = model
+
+    @abstractmethod
+    def chat(
+        self,
+        messages: list[dict],
+        tools: Optional[list[dict]] = None,
+        system: Optional[str] = None,
+        reasoning: bool = False,
+        images: Optional[list[ImageContent]] = None,
+    ) -> LLMResponse:
+        """Send a chat completion request.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            tools: Optional list of tool schemas
+            system: Optional system prompt (will be prepended or handled per provider)
+            reasoning: Enable reasoning mode (for models that support it)
+            images: Optional list of images for vision-capable models
+
+        Returns:
+            LLMResponse with content and/or tool calls
+        """
+        pass
+
+    @abstractmethod
+    def get_context_limit(self) -> int:
+        """Get the context window size for this model."""
+        pass
+
+    @abstractmethod
+    def get_max_image_size(self) -> int:
+        """Get maximum image size in bytes for this model."""
+        return 5 * 1024 * 1024  # Default 5MB
+
+    @abstractmethod
+    def supports_vision(self) -> bool:
+        """Check if this model supports image input."""
+        return False
+
+    @abstractmethod
+    def format_tool_result(self, tool_call_id: str, result: str) -> dict:
+        """Format a tool result message for this provider.
+
+        Args:
+            tool_call_id: ID of the tool call being responded to
+            result: JSON string result from the tool
+
+        Returns:
+            Message dict in provider's expected format
+        """
+        pass
+
+    @abstractmethod
+    def format_assistant_message(self, response: LLMResponse) -> dict:
+        """Format an assistant response to add back to messages.
+
+        Args:
+            response: The LLMResponse from a chat call
+
+        Returns:
+            Message dict in provider's expected format
+        """
+        pass
+
+    def format_content_with_images(
+        self,
+        text: str,
+        images: Optional[list[ImageContent]] = None
+    ) -> Union[str, list[dict]]:
+        """Format message content with optional images.
+
+        For vision models, returns a list of content blocks.
+        For non-vision models, returns text only (images stripped).
+
+        Args:
+            text: Text content
+            images: Optional list of images
+
+        Returns:
+            Content formatted for this provider
+        """
+        if not images:
+            return text
+
+        if self.supports_vision():
+            content = [{"type": "text", "text": text}]
+            for img in images:
+                content.append({
+                    "type": "image_url",
+                    "image_url": {"url": img.base64_url}
+                })
+            return content
+
+        # Non-vision model: strip images, warn
+        return text

emdash_core/agent/providers/factory.py

@@ -0,0 +1,80 @@
+"""Factory for creating LLM providers."""
+
+import os
+from typing import Union
+
+from .base import LLMProvider
+from .models import ChatModel
+from .openai_provider import OpenAIProvider
+from .transformers_provider import TransformersProvider
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Configuration - Single source of truth
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Default model alias
+DEFAULT_MODEL = "fireworks:accounts/fireworks/models/minimax-m2p1"
+
+# Default API key environment variable (used by default model)
+DEFAULT_API_KEY_ENV = "FIREWORKS_API_KEY"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Factory functions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def get_provider(model: Union[str, ChatModel] = DEFAULT_MODEL) -> LLMProvider:
+    """
+    Get an LLM provider for the specified model.
+
+    Uses OpenAI SDK with provider-specific base URLs for OpenAI, Anthropic, and Fireworks.
+    For local models, uses HuggingFace Transformers.
+
+    Args:
+        model: Model specification - ChatModel enum or alias
+            Examples:
+                - ChatModel.ANTHROPIC_CLAUDE_HAIKU_4
+                - "haiku", "sonnet", "opus"
+                - "gpt-4o-mini"
+                - "minimax"
+                - "local:Qwen/Qwen2.5-1.5B-Instruct"
+                - "transformers:microsoft/Phi-3-mini-4k-instruct"
+
+    Returns:
+        LLMProvider instance
+
+    Raises:
+        ValueError: If model string not recognized
+    """
+    # Handle local/transformers prefix for local models
+    if isinstance(model, str) and (model.startswith("local:") or model.startswith("transformers:")):
+        return TransformersProvider(model)
+
+    # Handle ChatModel enum directly
+    if isinstance(model, ChatModel):
+        return OpenAIProvider(model)
+
+    # Try to parse as ChatModel
+    parsed = ChatModel.from_string(model)
+    if parsed:
+        return OpenAIProvider(parsed)
+
+    # Assume it's a raw model string
+    return OpenAIProvider(model)
+
+
+def get_default_model() -> ChatModel:
+    """Get the default model."""
+    return ChatModel.from_string(DEFAULT_MODEL) or ChatModel.get_default()
+
+
+def get_default_api_key() -> str | None:
+    """Get the default API key from environment."""
+    return os.environ.get(DEFAULT_API_KEY_ENV)
+
+
+def list_available_models() -> list[dict]:
+    """List all available models."""
+    return ChatModel.list_all()