aiecs 1.5.1__py3-none-any.whl

aiecs/domain/agent/prompts/__init__.py

@@ -0,0 +1,29 @@
+"""
+Prompt Templates Module
+
+Native prompt template system replacing LangChain templates.
+"""
+
+from .template import (
+    PromptTemplate,
+    ChatPromptTemplate,
+    MessageTemplate,
+    TemplateMissingVariableError,
+)
+from .builder import MessageBuilder
+from .formatters import (
+    format_conversation_history,
+    format_tool_result,
+    truncate_context,
+)
+
+__all__ = [
+    "PromptTemplate",
+    "ChatPromptTemplate",
+    "MessageTemplate",
+    "TemplateMissingVariableError",
+    "MessageBuilder",
+    "format_conversation_history",
+    "format_tool_result",
+    "truncate_context",
+]

aiecs/domain/agent/prompts/builder.py

@@ -0,0 +1,161 @@
+"""
+Message Builder
+
+Helper for constructing LLMMessage lists.
+"""
+
+from typing import List, Dict, Any, Optional
+from aiecs.llm import LLMMessage
+
+
+class MessageBuilder:
+    """
+    Builder for constructing LLM message sequences.
+
+    Example:
+        builder = MessageBuilder()
+        builder.add_system("You are a helpful assistant")
+        builder.add_user("What is AI?")
+        messages = builder.build()
+    """
+
+    def __init__(self):
+        """Initialize message builder."""
+        self.messages: List[LLMMessage] = []
+
+    def add_system(self, content: str) -> "MessageBuilder":
+        """
+        Add system message.
+
+        Args:
+            content: Message content
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.append(LLMMessage(role="system", content=content))
+        return self
+
+    def add_user(self, content: str) -> "MessageBuilder":
+        """
+        Add user message.
+
+        Args:
+            content: Message content
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.append(LLMMessage(role="user", content=content))
+        return self
+
+    def add_assistant(self, content: str) -> "MessageBuilder":
+        """
+        Add assistant message.
+
+        Args:
+            content: Message content
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.append(LLMMessage(role="assistant", content=content))
+        return self
+
+    def add_message(self, role: str, content: str) -> "MessageBuilder":
+        """
+        Add message with custom role.
+
+        Args:
+            role: Message role
+            content: Message content
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.append(LLMMessage(role=role, content=content))
+        return self
+
+    def add_messages(self, messages: List[LLMMessage]) -> "MessageBuilder":
+        """
+        Add multiple messages.
+
+        Args:
+            messages: List of messages to add
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.extend(messages)
+        return self
+
+    def add_context(self, context: Dict[str, Any], prefix: str = "Context:") -> "MessageBuilder":
+        """
+        Add context as a system message.
+
+        Args:
+            context: Context dictionary
+            prefix: Prefix for context message
+
+        Returns:
+            Self for chaining
+        """
+        context_str = self._format_context(context)
+        if context_str:
+            self.add_system(f"{prefix}\n{context_str}")
+        return self
+
+    def add_conversation_history(
+        self, history: List[Dict[str, str]], max_messages: Optional[int] = None
+    ) -> "MessageBuilder":
+        """
+        Add conversation history.
+
+        Args:
+            history: List of {role, content} dicts
+            max_messages: Optional limit on number of messages
+
+        Returns:
+            Self for chaining
+        """
+        if max_messages:
+            history = history[-max_messages:]
+
+        for msg in history:
+            self.add_message(msg.get("role", "user"), msg.get("content", ""))
+
+        return self
+
+    def clear(self) -> "MessageBuilder":
+        """
+        Clear all messages.
+
+        Returns:
+            Self for chaining
+        """
+        self.messages.clear()
+        return self
+
+    def build(self) -> List[LLMMessage]:
+        """
+        Build and return message list.
+
+        Returns:
+            List of LLMMessage instances
+        """
+        return self.messages.copy()
+
+    def _format_context(self, context: Dict[str, Any]) -> str:
+        """Format context dictionary as string."""
+        lines = []
+        for key, value in context.items():
+            if not key.startswith("_") and value is not None:
+                lines.append(f"{key}: {value}")
+        return "\n".join(lines) if lines else ""
+
+    def __len__(self) -> int:
+        """Get number of messages."""
+        return len(self.messages)
+
+    def __repr__(self) -> str:
+        return f"MessageBuilder(messages={len(self.messages)})"

aiecs/domain/agent/prompts/formatters.py

@@ -0,0 +1,189 @@
+"""
+Prompt Formatters
+
+Utilities for formatting prompts with context.
+"""
+
+from typing import List, Dict, Any, Optional
+from aiecs.llm import LLMMessage
+
+
+def format_conversation_history(
+    history: List[LLMMessage],
+    max_messages: Optional[int] = None,
+    format_style: str = "compact",
+) -> str:
+    """
+    Format conversation history as string.
+
+    Args:
+        history: List of LLMMessage instances
+        max_messages: Optional limit on number of messages
+        format_style: "compact" or "detailed"
+
+    Returns:
+        Formatted conversation string
+    """
+    if max_messages:
+        history = history[-max_messages:]
+
+    if format_style == "compact":
+        lines = []
+        for msg in history:
+            lines.append(f"{msg.role.upper()}: {msg.content}")
+        return "\n".join(lines)
+
+    elif format_style == "detailed":
+        lines = []
+        for i, msg in enumerate(history):
+            lines.append(f"[{i+1}] {msg.role.upper()}")
+            lines.append(msg.content)
+            lines.append("")  # Empty line between messages
+        return "\n".join(lines)
+
+    else:
+        raise ValueError(f"Unknown format_style: {format_style}")
+
+
+def format_tool_result(
+    tool_name: str,
+    result: Any,
+    success: bool = True,
+    error: Optional[str] = None,
+) -> str:
+    """
+    Format tool execution result.
+
+    Args:
+        tool_name: Tool name
+        result: Tool result (if successful)
+        success: Whether execution succeeded
+        error: Error message (if failed)
+
+    Returns:
+        Formatted tool result string
+    """
+    if success:
+        return f"Tool '{tool_name}' returned:\n{result}"
+    else:
+        return f"Tool '{tool_name}' failed: {error}"
+
+
+def truncate_context(
+    text: str,
+    max_length: int,
+    strategy: str = "middle",
+    placeholder: str = "...",
+) -> str:
+    """
+    Truncate text to fit within max_length.
+
+    Args:
+        text: Text to truncate
+        max_length: Maximum length
+        strategy: "start", "middle", or "end"
+        placeholder: Placeholder for truncated content
+
+    Returns:
+        Truncated text
+    """
+    if len(text) <= max_length:
+        return text
+
+    if strategy == "end":
+        # Keep start, truncate end
+        return text[: max_length - len(placeholder)] + placeholder
+
+    elif strategy == "start":
+        # Truncate start, keep end
+        return placeholder + text[-(max_length - len(placeholder)) :]
+
+    elif strategy == "middle":
+        # Keep start and end, truncate middle
+        half = (max_length - len(placeholder)) // 2
+        return text[:half] + placeholder + text[-half:]
+
+    else:
+        raise ValueError(f"Unknown strategy: {strategy}")
+
+
+def format_list_items(items: List[str], style: str = "bullets") -> str:
+    """
+    Format list items.
+
+    Args:
+        items: List of items
+        style: "bullets", "numbered", or "compact"
+
+    Returns:
+        Formatted list string
+    """
+    if style == "bullets":
+        return "\n".join(f"• {item}" for item in items)
+
+    elif style == "numbered":
+        return "\n".join(f"{i+1}. {item}" for i, item in enumerate(items))
+
+    elif style == "compact":
+        return ", ".join(items)
+
+    else:
+        raise ValueError(f"Unknown style: {style}")
+
+
+def format_key_value_pairs(
+    data: Dict[str, Any],
+    separator: str = ": ",
+    exclude_keys: Optional[List[str]] = None,
+) -> str:
+    """
+    Format dictionary as key-value pairs.
+
+    Args:
+        data: Dictionary to format
+        separator: Separator between key and value
+        exclude_keys: Keys to exclude
+
+    Returns:
+        Formatted string
+    """
+    exclude_keys = exclude_keys or []
+    lines = []
+
+    for key, value in data.items():
+        if key in exclude_keys or key.startswith("_"):
+            continue
+        lines.append(f"{key}{separator}{value}")
+
+    return "\n".join(lines)
+
+
+def inject_context_in_prompt(
+    prompt: str, context: Dict[str, Any], context_marker: str = "{context}"
+) -> str:
+    """
+    Inject context into prompt at marker position.
+
+    Args:
+        prompt: Prompt template with context marker
+        context: Context dictionary
+        context_marker: Marker to replace with context
+
+    Returns:
+        Prompt with context injected
+    """
+    context_str = format_key_value_pairs(context)
+    return prompt.replace(context_marker, context_str)
+
+
+def estimate_token_count(text: str) -> int:
+    """
+    Rough estimation of token count.
+
+    Args:
+        text: Text to estimate
+
+    Returns:
+        Estimated token count (4 chars ≈ 1 token)
+    """
+    return len(text) // 4

aiecs/domain/agent/prompts/template.py

@@ -0,0 +1,255 @@
+"""
+Prompt Templates
+
+Native template system with variable substitution.
+"""
+
+import re
+from typing import Dict, List, Optional
+from dataclasses import dataclass
+
+from aiecs.llm import LLMMessage
+
+
+class TemplateMissingVariableError(Exception):
+    """Raised when required template variable is missing."""
+
+
+class PromptTemplate:
+    """
+    String-based prompt template with {variable} substitution.
+
+    Example:
+        template = PromptTemplate(
+            "Hello {name}, you are a {role}.",
+            required_variables=["name", "role"]
+        )
+        result = template.format(name="Alice", role="developer")
+    """
+
+    def __init__(
+        self,
+        template: str,
+        required_variables: Optional[List[str]] = None,
+        defaults: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize prompt template.
+
+        Args:
+            template: Template string with {variable} placeholders
+            required_variables: List of required variable names
+            defaults: Default values for optional variables
+        """
+        self.template = template
+        self.required_variables = required_variables or []
+        self.defaults = defaults or {}
+
+        # Extract all variables from template
+        self._extract_variables()
+
+    def _extract_variables(self) -> None:
+        """Extract variable names from template."""
+        # Find all {variable_name} patterns
+        pattern = r"\{(\w+)\}"
+        self.variables = set(re.findall(pattern, self.template))
+
+    def format(self, **kwargs) -> str:
+        """
+        Format template with provided variables.
+
+        Args:
+            **kwargs: Variable values
+
+        Returns:
+            Formatted string
+
+        Raises:
+            TemplateMissingVariableError: If required variable missing
+        """
+        # Check required variables
+        for var in self.required_variables:
+            if var not in kwargs and var not in self.defaults:
+                raise TemplateMissingVariableError(f"Required variable '{var}' not provided")
+
+        # Merge with defaults
+        values = {**self.defaults, **kwargs}
+
+        # Format template
+        try:
+            return self.template.format(**values)
+        except KeyError as e:
+            raise TemplateMissingVariableError(f"Variable {e} not provided and has no default")
+
+    def partial(self, **kwargs) -> "PromptTemplate":
+        """
+        Create a partial template with some variables pre-filled.
+
+        Args:
+            **kwargs: Variable values to pre-fill
+
+        Returns:
+            New PromptTemplate with updated defaults
+        """
+        new_defaults = {**self.defaults, **kwargs}
+        return PromptTemplate(
+            template=self.template,
+            required_variables=self.required_variables,
+            defaults=new_defaults,
+        )
+
+    def __repr__(self) -> str:
+        return f"PromptTemplate(variables={self.variables})"
+
+
+@dataclass
+class MessageTemplate:
+    """Template for a single message."""
+
+    role: str
+    content: str
+
+
+class ChatPromptTemplate:
+    """
+    Multi-message chat template.
+
+    Example:
+        template = ChatPromptTemplate([
+            MessageTemplate("system", "You are a {role}."),
+            MessageTemplate("user", "{task}"),
+        ])
+        messages = template.format_messages(role="assistant", task="Help me")
+    """
+
+    def __init__(
+        self,
+        messages: List[MessageTemplate],
+        required_variables: Optional[List[str]] = None,
+        defaults: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize chat template.
+
+        Args:
+            messages: List of message templates
+            required_variables: List of required variable names
+            defaults: Default values for optional variables
+        """
+        self.messages = messages
+        self.required_variables = required_variables or []
+        self.defaults = defaults or {}
+
+        # Extract all variables
+        self._extract_variables()
+
+    def _extract_variables(self) -> None:
+        """Extract variables from all message templates."""
+        self.variables = set()
+        pattern = r"\{(\w+)\}"
+
+        for msg in self.messages:
+            vars_in_msg = set(re.findall(pattern, msg.content))
+            self.variables.update(vars_in_msg)
+
+    def format_messages(self, **kwargs) -> List[LLMMessage]:
+        """
+        Format all messages with provided variables.
+
+        Args:
+            **kwargs: Variable values
+
+        Returns:
+            List of LLMMessage instances
+
+        Raises:
+            TemplateMissingVariableError: If required variable missing
+        """
+        # Check required variables
+        for var in self.required_variables:
+            if var not in kwargs and var not in self.defaults:
+                raise TemplateMissingVariableError(f"Required variable '{var}' not provided")
+
+        # Merge with defaults
+        values = {**self.defaults, **kwargs}
+
+        # Format each message
+        formatted_messages = []
+        for msg_template in self.messages:
+            try:
+                content = msg_template.content.format(**values)
+                formatted_messages.append(LLMMessage(role=msg_template.role, content=content))
+            except KeyError as e:
+                raise TemplateMissingVariableError(f"Variable {e} not provided and has no default")
+
+        return formatted_messages
+
+    def partial(self, **kwargs) -> "ChatPromptTemplate":
+        """
+        Create a partial template with some variables pre-filled.
+
+        Args:
+            **kwargs: Variable values to pre-fill
+
+        Returns:
+            New ChatPromptTemplate with updated defaults
+        """
+        new_defaults = {**self.defaults, **kwargs}
+        return ChatPromptTemplate(
+            messages=self.messages,
+            required_variables=self.required_variables,
+            defaults=new_defaults,
+        )
+
+    def add_message(self, role: str, content: str) -> "ChatPromptTemplate":
+        """
+        Add a message to the template.
+
+        Args:
+            role: Message role
+            content: Message content template
+
+        Returns:
+            New ChatPromptTemplate with added message
+        """
+        new_messages = self.messages + [MessageTemplate(role, content)]
+        return ChatPromptTemplate(
+            messages=new_messages,
+            required_variables=self.required_variables,
+            defaults=self.defaults,
+        )
+
+    def __repr__(self) -> str:
+        return f"ChatPromptTemplate(messages={len(self.messages)}, variables={self.variables})"
+
+
+def create_system_prompt(content: str) -> ChatPromptTemplate:
+    """
+    Helper to create a chat template with system message.
+
+    Args:
+        content: System message content
+
+    Returns:
+        ChatPromptTemplate with system message
+    """
+    return ChatPromptTemplate([MessageTemplate("system", content)])
+
+
+def create_basic_chat(system: str, user: str) -> ChatPromptTemplate:
+    """
+    Helper to create a basic system + user chat template.
+
+    Args:
+        system: System message content
+        user: User message content
+
+    Returns:
+        ChatPromptTemplate with system and user messages
+    """
+    return ChatPromptTemplate(
+        [
+            MessageTemplate("system", system),
+            MessageTemplate("user", user),
+        ]
+    )