dao-ai 0.0.35__py3-none-any.whl → 0.1.0__py3-none-any.whl

dao_ai/state.py

@@ -1,41 +1,159 @@
-from langchain_core.messages import AnyMessage
+"""
+State definitions for DAO AI agents.
+
+This module defines the state schemas used by DAO AI agents,
+compatible with both LangChain v1's create_agent and LangGraph's StateGraph.
+
+State Schema:
+- AgentState: Primary state schema for all agent operations
+- Context: Runtime context passed via ToolRuntime[Context] or Runtime[Context]
+- GenieSpaceState: Per-space state for Genie conversations
+- SessionState: Accumulated state that flows between requests
+"""
+
+from datetime import datetime
+from typing import Any, Optional
+
 from langgraph.graph import MessagesState
-from langgraph.managed import RemainingSteps
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+from typing_extensions import NotRequired
+
 
+class GenieSpaceState(BaseModel):
+    """State for a single Genie space/conversation.
 
-class IncomingState(MessagesState): ...
+    This tracks the conversation state and metadata for a Genie space,
+    allowing multi-turn conversations and caching information to be preserved.
+    """
 
+    conversation_id: str = Field(description="Genie conversation ID for this space")
+    cache_hit: bool = Field(
+        default=False, description="Whether the last query was a cache hit"
+    )
+    cache_key: Optional[str] = Field(default=None, description="Cache key if cached")
+    follow_up_questions: list[str] = Field(
+        default_factory=list, description="Suggested follow-up questions from Genie"
+    )
+    last_query: Optional[str] = Field(
+        default=None, description="The last query sent to Genie"
+    )
+    last_query_time: Optional[datetime] = Field(
+        default=None, description="When the last query was made"
+    )
 
-class OutgoingState(MessagesState):
-    is_valid: bool
-    message_error: str
 
+class GenieState(BaseModel):
+    """State for all Genie spaces.
 
-class SharedState(MessagesState):
+    Maps space_id to GenieSpaceState for each Genie space the user has interacted with.
     """
-    State representation for the DAO AI agent conversation workflow.
 
-    Extends LangGraph's MessagesState to maintain the conversation history while
-    adding additional state fields specific to the DAO domain. This state is
-    passed between nodes in the agent graph and modified during execution.
+    spaces: dict[str, GenieSpaceState] = Field(
+        default_factory=dict, description="Map of space_id to space state"
+    )
+
+    def get_conversation_id(self, space_id: str) -> Optional[str]:
+        """Get conversation ID for a space, if it exists."""
+        if space_id in self.spaces:
+            return self.spaces[space_id].conversation_id
+        return None
+
+    def update_space(
+        self,
+        space_id: str,
+        conversation_id: str,
+        cache_hit: bool = False,
+        cache_key: Optional[str] = None,
+        follow_up_questions: Optional[list[str]] = None,
+        last_query: Optional[str] = None,
+    ) -> None:
+        """Update or create state for a Genie space."""
+        self.spaces[space_id] = GenieSpaceState(
+            conversation_id=conversation_id,
+            cache_hit=cache_hit,
+            cache_key=cache_key,
+            follow_up_questions=follow_up_questions or [],
+            last_query=last_query,
+            last_query_time=datetime.now() if last_query else None,
+        )
+
+
+class SessionState(BaseModel):
+    """Accumulated state that flows between requests.
+
+    This is the "paste from previous output" portion of the request.
+    Users can copy the session from custom_outputs and paste it back
+    as custom_inputs.session to restore state.
     """
 
-    context: str  # short term/long term memory
+    genie: GenieState = Field(
+        default_factory=GenieState, description="Genie conversation state per space"
+    )
 
-    active_agent: str  # langgraph-swarm
-    remaining_steps: RemainingSteps  # langgraph-supervisor
+    # Future: Add other stateful tool state here
+    # other_tool_state: OtherToolState = Field(default_factory=OtherToolState)
 
-    summarized_messages: list[AnyMessage]
 
-    is_valid: bool  # message validation node
-    message_error: str
+class AgentState(MessagesState, total=False):
+    """
+    Primary state schema for DAO AI agents.
 
-    # A mapping of genie space_id to conversation_id
-    genie_conversation_ids: dict[str, str]  # Genie
+    Extends MessagesState to include the messages channel with proper
+    add_messages reducer, plus additional fields for DAO AI functionality.
+
+    Used for:
+    - state_schema in create_agent calls
+    - state_schema in StateGraph for orchestration
+    - Type parameter in ToolRuntime[Context, AgentState]
+    - Type parameter in AgentMiddleware[AgentState, Context]
+    - API input/output contracts
+
+    Fields:
+        messages: Conversation history with add_messages reducer (from MessagesState)
+        context: Short/long term memory context
+        active_agent: Name of currently active agent in multi-agent workflows
+        is_valid: Message validation status
+        message_error: Error message if validation failed
+        session: Accumulated session state (genie conversations, etc.)
+        structured_response: Structured output from response_format (populated by LangChain)
+    """
+
+    context: NotRequired[str]
+    active_agent: NotRequired[str]
+    is_valid: NotRequired[bool]
+    message_error: NotRequired[str]
+    session: NotRequired[SessionState]
+    structured_response: NotRequired[Any]
 
 
 class Context(BaseModel):
+    """
+    Runtime context for DAO AI agents.
+
+    This is passed to tools and middleware via the runtime parameter.
+    Access via ToolRuntime[Context] in tools or Runtime[Context] in middleware.
+
+    The `custom` dict allows application-specific context values that can be:
+    - Used as template parameters in prompts (all keys are applied)
+    - Validated by middleware (check for specific keys like "store_num")
+
+    Example:
+        @tool
+        def my_tool(runtime: ToolRuntime[Context]) -> str:
+            user_id = runtime.context.user_id
+            store_num = runtime.context.custom.get("store_num")
+            return f"Hello, {user_id} at store {store_num}!"
+
+        class MyMiddleware(AgentMiddleware[AgentState, Context]):
+            def before_model(
+                self,
+                state: AgentState,
+                runtime: Runtime[Context]
+            ) -> dict[str, Any] | None:
+                user_id = runtime.context.user_id
+                return None
+    """
+
     user_id: str | None = None
     thread_id: str | None = None
-    store_num: int | None = None
+    custom: dict[str, Any] = Field(default_factory=dict)

dao_ai/tools/__init__.py

@@ -1,12 +1,13 @@
+from dao_ai.genie.cache import LRUCacheService, SemanticCacheService
 from dao_ai.hooks.core import create_hooks
 from dao_ai.tools.agent import create_agent_endpoint_tool
-from dao_ai.tools.core import (
-    create_tools,
-    search_tool,
-)
+from dao_ai.tools.core import create_tools, say_hello_tool
+from dao_ai.tools.email import create_send_email_tool
 from dao_ai.tools.genie import create_genie_tool
 from dao_ai.tools.mcp import create_mcp_tools
+from dao_ai.tools.memory import create_search_memory_tool
 from dao_ai.tools.python import create_factory_tool, create_python_tool
+from dao_ai.tools.search import create_search_tool
 from dao_ai.tools.slack import create_send_slack_message_tool
 from dao_ai.tools.time import (
     add_time_tool,
@@ -28,6 +29,9 @@ __all__ = [
     "create_hooks",
     "create_mcp_tools",
     "create_python_tool",
+    "create_search_memory_tool",
+    "create_search_tool",
+    "create_send_email_tool",
     "create_send_slack_message_tool",
     "create_tools",
     "create_uc_tools",
@@ -35,7 +39,9 @@ __all__ = [
     "current_time_tool",
     "format_time_tool",
     "is_business_hours_tool",
-    "search_tool",
+    "LRUCacheService",
+    "say_hello_tool",
+    "SemanticCacheService",
     "time_difference_tool",
     "time_in_timezone_tool",
     "time_until_tool",

dao_ai/tools/core.py

@@ -1,7 +1,19 @@
+"""
+Core tool creation infrastructure for DAO AI.
+
+This module provides the foundational tool creation and registration system:
+- Tool registry for caching created tools
+- Factory function for creating tools from configuration
+- Example tools demonstrating runtime context usage
+
+This is "core" because it contains the essential infrastructure that all
+tool creation flows through, not because it contains all tools.
+"""
+
 from collections import OrderedDict
 from typing import Sequence
 
-from langchain_community.tools import DuckDuckGoSearchRun
+from langchain.tools import ToolRuntime, tool
 from langchain_core.runnables.base import RunnableLike
 from loguru import logger
 
@@ -10,7 +22,9 @@ from dao_ai.config import (
     ToolModel,
 )
 from dao_ai.hooks.core import create_hooks
+from dao_ai.state import Context
 
+# Module-level tool registry for caching created tools
 tool_registry: dict[str, Sequence[RunnableLike]] = {}
 
 
@@ -54,6 +68,45 @@ def create_tools(tool_models: Sequence[ToolModel]) -> Sequence[RunnableLike]:
     return all_tools
 
 
-def search_tool() -> RunnableLike:
-    logger.debug("search_tool")
-    return DuckDuckGoSearchRun(output_format="list")
+# =============================================================================
+# Example Tools
+# =============================================================================
+# The following tools serve as examples and are included here because they
+# demonstrate core patterns (like ToolRuntime usage) rather than because they
+# are fundamental infrastructure. They're simple enough to colocate with the
+# core tool creation logic.
+
+
+@tool
+def say_hello_tool(
+    name: str | None = None,
+    runtime: ToolRuntime[Context] = None,
+) -> str:
+    """
+    Say hello to someone by name.
+
+    This is an example tool demonstrating how to use ToolRuntime to access
+    runtime context (like user_id) within a tool.
+
+    If no name is provided, uses the user_id from the runtime context.
+
+    Args:
+        name: Optional name of the person to greet. If not provided,
+              uses user_id from context.
+        runtime: Runtime context (automatically injected, not provided by user)
+
+    Returns:
+        A greeting string
+    """
+    # Use provided name, or fall back to user_id from context
+    if name is None:
+        if runtime and runtime.context:
+            user_id = runtime.context.user_id
+            if user_id:
+                name = user_id
+            else:
+                name = "there"  # Default fallback
+        else:
+            name = "there"  # Default fallback
+
+    return f"Hello, {name}!"

dao_ai/tools/email.py

@@ -0,0 +1,280 @@
+"""Email tool for sending emails via SMTP."""
+
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any, Callable, Optional
+
+from langchain_core.tools import tool
+from loguru import logger
+from pydantic import BaseModel, ConfigDict, Field
+
+from dao_ai.config import AnyVariable, value_of
+
+
+class SMTPConfigModel(BaseModel):
+    """Configuration model for SMTP email settings."""
+
+    model_config = ConfigDict(use_enum_values=True, extra="forbid")
+
+    host: AnyVariable = Field(
+        default="smtp.gmail.com",
+        description="SMTP server hostname",
+    )
+    port: AnyVariable = Field(
+        default=587,
+        description="SMTP server port",
+    )
+    username: AnyVariable = Field(
+        description="SMTP username for authentication",
+    )
+    password: AnyVariable = Field(
+        description="SMTP password for authentication",
+    )
+    sender_email: Optional[AnyVariable] = Field(
+        default=None,
+        description="Email address to use as sender (defaults to username)",
+    )
+    use_tls: bool = Field(
+        default=True,
+        description="Whether to use TLS encryption",
+    )
+
+
+def create_send_email_tool(
+    smtp_config: SMTPConfigModel | dict[str, Any],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+) -> Callable[[str, str, str, Optional[str]], str]:
+    """
+    Create a tool that sends emails via SMTP.
+
+    This factory function creates a tool for sending emails with configurable SMTP settings.
+    All configuration values support AnyVariable types, allowing use of environment variables,
+    secrets, and composite variables.
+
+    Args:
+        smtp_config: SMTP configuration (SMTPConfigModel or dict). Supports:
+            - host: SMTP server hostname (supports variables/secrets)
+            - port: SMTP server port (supports variables/secrets)
+            - username: SMTP username (supports variables/secrets)
+            - password: SMTP password (supports variables/secrets)
+            - sender_email: Sender email address, defaults to username (supports variables/secrets)
+            - use_tls: Whether to use TLS encryption (default: True)
+        name: Custom tool name (default: 'send_email')
+        description: Custom tool description
+
+    Returns:
+        A tool function that sends emails via SMTP
+
+    Example:
+        Basic usage with environment variables:
+        ```yaml
+        tools:
+          send_email:
+            name: send_email
+            function:
+              type: factory
+              name: dao_ai.tools.email.create_send_email_tool
+              args:
+                smtp_config:
+                  host: smtp.gmail.com
+                  port: 587
+                  username: ${SMTP_USER}
+                  password: ${SMTP_PASSWORD}
+                  sender_email: bot@example.com
+        ```
+
+        With secrets:
+        ```yaml
+        tools:
+          send_email:
+            name: send_email
+            function:
+              type: factory
+              name: dao_ai.tools.email.create_send_email_tool
+              args:
+                smtp_config:
+                  host: smtp.gmail.com
+                  port: 587
+                  username:
+                    type: secret
+                    scope: email
+                    key: smtp_user
+                  password:
+                    type: secret
+                    scope: email
+                    key: smtp_password
+        ```
+    """
+    logger.info("=== Creating send_email_tool ===")
+    logger.debug(
+        f"Factory called with config type: {type(smtp_config).__name__}, "
+        f"name={name}, description={description}"
+    )
+
+    # Convert dict to SMTPConfigModel if needed
+    if isinstance(smtp_config, dict):
+        logger.debug("Converting dict config to SMTPConfigModel")
+        smtp_config = SMTPConfigModel(**smtp_config)
+    else:
+        logger.debug("Config already is SMTPConfigModel")
+
+    # Resolve all variable values
+    logger.debug("Resolving SMTP configuration variables...")
+
+    logger.debug("  - Resolving host")
+    host: str = value_of(smtp_config.host)
+    logger.debug(f"    Host resolved: {host}")
+
+    logger.debug("  - Resolving port")
+    port: int = int(value_of(smtp_config.port))
+    logger.debug(f"    Port resolved: {port}")
+
+    logger.debug("  - Resolving username")
+    username: str = value_of(smtp_config.username)
+    logger.debug(f"    Username resolved: {username}")
+
+    logger.debug("  - Resolving password")
+    password: str = value_of(smtp_config.password)
+    logger.debug(
+        f"    Password resolved: {'*' * len(password) if password else 'None'}"
+    )
+
+    logger.debug("  - Resolving sender_email")
+    sender_email: str = (
+        value_of(smtp_config.sender_email) if smtp_config.sender_email else username
+    )
+    logger.debug(
+        f"    Sender email resolved: {sender_email} "
+        f"({'from sender_email' if smtp_config.sender_email else 'defaulted to username'})"
+    )
+
+    use_tls: bool = smtp_config.use_tls
+    logger.debug(f"  - TLS enabled: {use_tls}")
+
+    logger.info(
+        f"SMTP configuration resolved - host={host}, port={port}, "
+        f"sender={sender_email}, use_tls={use_tls}"
+    )
+
+    if name is None:
+        name = "send_email"
+        logger.debug(f"Tool name defaulted to: {name}")
+    else:
+        logger.debug(f"Tool name set to: {name}")
+
+    if description is None:
+        description = "Send an email to a recipient with subject and body content"
+        logger.debug("Tool description using default")
+    else:
+        logger.debug(f"Tool description set to: {description}")
+
+    logger.info(f"Creating tool '{name}' with @tool decorator")
+
+    @tool(
+        name_or_callable=name,
+        description=description,
+    )
+    def send_email(
+        to: str,
+        subject: str,
+        body: str,
+        cc: Optional[str] = None,
+    ) -> str:
+        """
+        Send an email via SMTP.
+
+        Args:
+            to: Recipient email address
+            subject: Email subject line
+            body: Email body content (plain text)
+            cc: Optional CC recipients (comma-separated email addresses)
+
+        Returns:
+            str: Success or error message
+        """
+        logger.info("=== send_email tool invoked ===")
+        logger.info(f"  To: {to}")
+        logger.info(f"  Subject: {subject}")
+        logger.info(f"  Body length: {len(body)} characters")
+        logger.info(f"  CC: {cc if cc else 'None'}")
+
+        try:
+            logger.debug("Constructing email message...")
+
+            # Create message
+            msg = MIMEMultipart()
+            msg["From"] = sender_email
+            msg["To"] = to
+            msg["Subject"] = subject
+            logger.debug(f"  From: {sender_email}")
+            logger.debug(f"  To: {to}")
+            logger.debug(f"  Subject: {subject}")
+
+            if cc:
+                msg["Cc"] = cc
+                logger.debug(f"  CC: {cc}")
+
+            # Attach body as plain text
+            msg.attach(MIMEText(body, "plain"))
+            logger.debug(f"  Body attached ({len(body)} chars)")
+
+            # Send email
+            logger.info(f"Connecting to SMTP server {host}:{port}...")
+            with smtplib.SMTP(host, port) as server:
+                logger.debug("SMTP connection established")
+
+                if use_tls:
+                    logger.debug("Upgrading connection to TLS...")
+                    server.starttls()
+                    logger.debug("TLS upgrade successful")
+
+                logger.debug(f"Authenticating with username: {username}")
+                server.login(username, password)
+                logger.info("SMTP authentication successful")
+
+                # Build recipient list
+                recipients = [to]
+                if cc:
+                    cc_addresses = [addr.strip() for addr in cc.split(",")]
+                    recipients.extend(cc_addresses)
+                    logger.debug(f"Total recipients: {len(recipients)} ({recipients})")
+                else:
+                    logger.debug(f"Single recipient: {to}")
+
+                logger.info(f"Sending message to {len(recipients)} recipient(s)...")
+                server.send_message(msg)
+                logger.info("Message sent successfully via SMTP")
+
+            success_msg = f"✓ Email sent successfully to {to}"
+            if cc:
+                success_msg += f" (cc: {cc})"
+
+            logger.info(success_msg)
+            logger.info("=== send_email completed successfully ===")
+            return success_msg
+
+        except smtplib.SMTPAuthenticationError as e:
+            error_msg = f"✗ SMTP authentication failed: {str(e)}"
+            logger.error(error_msg)
+            logger.error(f"  Server: {host}:{port}")
+            logger.error(f"  Username: {username}")
+            logger.error("=== send_email failed (authentication) ===")
+            return error_msg
+        except smtplib.SMTPException as e:
+            error_msg = f"✗ SMTP error: {str(e)}"
+            logger.error(error_msg)
+            logger.error(f"  Server: {host}:{port}")
+            logger.error("=== send_email failed (SMTP error) ===")
+            return error_msg
+        except Exception as e:
+            error_msg = f"✗ Failed to send email: {str(e)}"
+            logger.error(error_msg)
+            logger.error(f"  Error type: {type(e).__name__}")
+            logger.error("=== send_email failed (unexpected error) ===")
+            return error_msg
+
+    logger.info(f"Tool '{name}' created successfully")
+    logger.info("=== send_email_tool creation complete ===")
+    return send_email