aury-agent 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

aury/agents/react/context.py

@@ -0,0 +1,309 @@
+"""Context and message building helpers for ReactAgent."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from ..core.logging import react_logger as logger
+from ..context_providers import AgentContext
+from ..llm import LLMMessage
+
+if TYPE_CHECKING:
+    from ..core.context import InvocationContext
+    from ..core.types import PromptInput
+    from ..context_providers import ContextProvider
+    from ..middleware import MiddlewareChain
+    from ..core.types.tool import BaseTool
+
+
+async def fetch_agent_context(
+    ctx: "InvocationContext",
+    input: "PromptInput",
+    context_providers: list["ContextProvider"],
+    direct_tools: list["BaseTool"],
+    delegate_tool_class: type | None,
+    middleware_chain: "MiddlewareChain | None",
+) -> AgentContext:
+    """Fetch context from all providers and merge with direct tools.
+    
+    Process:
+    1. Fetch from all providers and merge
+    2. Add direct tools (from create())
+    3. If providers returned subagents, create DelegateTool
+    
+    Args:
+        ctx: InvocationContext
+        input: User prompt input
+        context_providers: List of context providers
+        direct_tools: Direct tools from create()
+        delegate_tool_class: Custom DelegateTool class
+        middleware_chain: Middleware chain for DelegateTool
+        
+    Returns:
+        Merged AgentContext with all tools
+    """
+    from ..tool.builtin import DelegateTool
+    from ..backends.subagent import ListSubAgentBackend
+    
+    # Set input on context for providers to access
+    ctx.input = input
+    
+    # Fetch from all context_providers
+    outputs: list[AgentContext] = []
+    for provider in context_providers:
+        try:
+            output = await provider.fetch(ctx)
+            outputs.append(output)
+        except Exception as e:
+            logger.warning(f"Provider {provider.name} fetch failed: {e}")
+    
+    # Merge all provider outputs
+    merged = AgentContext.merge(outputs)
+    
+    # Add direct tools (from create())
+    all_tools = list(direct_tools)  # Copy direct tools
+    seen_names = {t.name for t in all_tools}
+    
+    # Add tools from providers (deduplicate)
+    for tool in merged.tools:
+        if tool.name not in seen_names:
+            seen_names.add(tool.name)
+            all_tools.append(tool)
+    
+    # If providers returned subagents, create DelegateTool
+    if merged.subagents:
+        # Check if we already have a delegate tool
+        has_delegate = any(t.name == "delegate" for t in all_tools)
+        if not has_delegate:
+            backend = ListSubAgentBackend(merged.subagents)
+            tool_cls = delegate_tool_class or DelegateTool
+            delegate_tool = tool_cls(backend, middleware=middleware_chain)
+            all_tools.append(delegate_tool)
+    
+    # Return merged context with combined tools
+    return AgentContext(
+        system_content=merged.system_content,
+        user_content=merged.user_content,
+        tools=all_tools,
+        messages=merged.messages,
+        subagents=merged.subagents,
+        skills=merged.skills,
+    )
+
+
+def _parse_content(content):
+    """Parse content, handling stringified JSON."""
+    if isinstance(content, str):
+        # Try to parse if it looks like JSON array
+        if content.startswith("["):
+            try:
+                import json
+                return json.loads(content)
+            except json.JSONDecodeError:
+                pass
+    return content
+
+
+def fix_incomplete_tool_calls(messages: list[dict]) -> list[dict]:
+    """Fix incomplete tool_use/tool_result pairs in history.
+    
+    If an assistant message has tool_use blocks without corresponding
+    tool_result messages, add placeholder tool_result messages.
+    
+    This handles cases where execution was interrupted between
+    saving assistant message and saving tool results.
+    
+    Supports both formats:
+    - OpenAI format: assistant message with tool_calls field
+    - Claude format: assistant message with content containing tool_use blocks
+    
+    Args:
+        messages: List of message dicts from history
+        
+    Returns:
+        Fixed message list with placeholder tool_results added
+    """
+    if not messages:
+        return messages
+    
+    result = []
+    i = 0
+    
+    while i < len(messages):
+        msg = messages[i]
+        result.append(msg)
+        
+        # Check if this is an assistant message with tool_use
+        if msg.get("role") == "assistant":
+            tool_use_ids = []
+            
+            # Format 1: OpenAI format - tool_calls as separate field
+            tool_calls = msg.get("tool_calls")
+            if tool_calls and isinstance(tool_calls, list):
+                for tc in tool_calls:
+                    if isinstance(tc, dict):
+                        tool_id = tc.get("id")
+                        if tool_id:
+                            tool_use_ids.append(tool_id)
+            
+            # Format 2: Claude format - tool_use in content
+            if not tool_use_ids:
+                content = _parse_content(msg.get("content"))
+                if isinstance(content, list):
+                    for part in content:
+                        if isinstance(part, dict) and part.get("type") == "tool_use":
+                            tool_id = part.get("id")
+                            if tool_id:
+                                tool_use_ids.append(tool_id)
+            
+            if tool_use_ids:
+                # Collect tool_result ids from following messages
+                tool_result_ids = set()
+                j = i + 1
+                while j < len(messages):
+                    next_msg = messages[j]
+                    if next_msg.get("role") == "tool":
+                        # Check tool_call_id or content for tool_use_id
+                        tcid = next_msg.get("tool_call_id")
+                        if tcid:
+                            tool_result_ids.add(tcid)
+                        # Also check content if it's a list with tool_result
+                        nc = _parse_content(next_msg.get("content"))
+                        if isinstance(nc, list):
+                            for part in nc:
+                                if isinstance(part, dict) and part.get("type") == "tool_result":
+                                    tuid = part.get("tool_use_id")
+                                    if tuid:
+                                        tool_result_ids.add(tuid)
+                        j += 1
+                    elif next_msg.get("role") in ("user", "assistant"):
+                        # Stop at next user/assistant message
+                        break
+                    else:
+                        j += 1
+                
+                # Add placeholder for missing tool_results
+                for tool_id in tool_use_ids:
+                    if tool_id not in tool_result_ids:
+                        logger.warning(
+                            f"Found incomplete tool_use without tool_result: {tool_id}, adding placeholder"
+                        )
+                        result.append({
+                            "role": "tool",
+                            "content": "[执行被中断]",
+                            "tool_call_id": tool_id,
+                        })
+        
+        i += 1
+    
+    return result
+
+
+async def build_messages(
+    input: "PromptInput",
+    agent_context: AgentContext,
+    system_prompt: str | None,
+) -> list[LLMMessage]:
+    """Build message history for LLM.
+    
+    Uses AgentContext from providers for system content, messages, etc.
+    
+    Args:
+        input: User prompt input
+        agent_context: Merged context from providers
+        system_prompt: System prompt from config (or default)
+        
+    Returns:
+        List of LLMMessage for LLM call
+    """
+    messages = []
+    
+    # System message: config.system_prompt + agent_context.system_content
+    final_system_prompt = system_prompt or default_system_prompt(agent_context.tools)
+    
+    # Format system_prompt with dynamic variables
+    now = datetime.now()
+    
+    # Build template variables: datetime + custom vars from input
+    template_vars = {
+        "current_date": now.strftime("%Y-%m-%d"),
+        "current_time": now.strftime("%H:%M:%S"),
+        "current_datetime": now.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    
+    # Add custom variables from PromptInput (user_name, tenant, etc.)
+    if hasattr(input, 'vars') and input.vars:
+        template_vars.update(input.vars)
+    
+    try:
+        final_system_prompt = final_system_prompt.format(**template_vars)
+    except KeyError as e:
+        # Log missing variable but continue
+        logger.debug(f"System prompt template variable not found: {e}")
+        pass
+    
+    if agent_context.system_content:
+        final_system_prompt = final_system_prompt + "\n\n" + agent_context.system_content
+    messages.append(LLMMessage(role="system", content=final_system_prompt))
+    
+    # Historical messages from AgentContext (provided by MessageContextProvider)
+    # Fix incomplete tool_use/tool_result pairs first
+    history_messages = fix_incomplete_tool_calls(agent_context.messages)
+    for i, msg in enumerate(history_messages):
+        raw_content = msg.get("content", "")
+        content = _parse_content(raw_content)
+        logger.info(
+            f"[build_messages] msg[{i}] role={msg.get('role')}, "
+            f"raw_content_type={type(raw_content).__name__}, "
+            f"raw_content_preview={str(raw_content)[:200]}, "
+            f"parsed_content_type={type(content).__name__}"
+        )
+        messages.append(LLMMessage(
+            role=msg.get("role", "user"),
+            content=content,
+            tool_call_id=msg.get("tool_call_id"),
+        ))
+
+    # User content prefix (from providers) + current user message
+    content = input.text
+    if agent_context.user_content:
+        content = agent_context.user_content + "\n\n" + content
+    
+    if input.attachments:
+        # Build multimodal content
+        content_parts = [{"type": "text", "text": content}]
+        for attachment in input.attachments:
+            content_parts.append(attachment)
+        content = content_parts
+
+    messages.append(LLMMessage(role="user", content=content))
+
+    return messages
+
+
+def default_system_prompt(tools: list["BaseTool"]) -> str:
+    """Generate default system prompt with tool descriptions.
+    
+    Args:
+        tools: List of available tools
+        
+    Returns:
+        Default system prompt string
+    """
+    tool_list = []
+    for tool in tools:
+        info = tool.get_info()
+        tool_list.append(f"- {info.name}: {info.description}")
+
+    tools_desc = "\n".join(tool_list) if tool_list else "No tools available."
+
+    return f"""You are a helpful AI assistant with access to tools.
+
+Available tools:
+{tools_desc}
+
+When you need to use a tool, make a tool call. After receiving the tool result, continue reasoning or provide your final response.
+
+Think step by step and use tools when necessary to complete the user's request."""

aury/agents/react/factory.py

@@ -0,0 +1,301 @@
+"""Factory functions for ReactAgent creation and restoration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..core.base import AgentConfig
+from ..core.context import InvocationContext
+from ..core.types.session import Session, generate_id
+
+if TYPE_CHECKING:
+    from ..llm import LLMProvider
+    from ..tool import ToolSet
+    from ..core.types.tool import BaseTool
+    from ..backends import Backends
+    from ..backends.snapshot import SnapshotBackend
+    from ..backends.subagent import AgentConfig as SubAgentConfig
+    from ..core.event_bus import Bus
+    from ..middleware import MiddlewareChain, Middleware
+    from ..memory import MemoryManager
+    from ..context_providers import ContextProvider
+
+
+class SessionNotFoundError(Exception):
+    """Raised when session is not found in storage."""
+    pass
+
+
+def create_react_agent(
+    llm: "LLMProvider",
+    tools: "ToolSet | list[BaseTool] | None" = None,
+    config: AgentConfig | None = None,
+    *,
+    backends: "Backends | None" = None,
+    session: "Session | None" = None,
+    bus: "Bus | None" = None,
+    middlewares: "list[Middleware] | None" = None,
+    subagents: "list[SubAgentConfig] | None" = None,
+    memory: "MemoryManager | None" = None,
+    snapshot: "SnapshotBackend | None" = None,
+    # ContextProvider system
+    context_providers: "list[ContextProvider] | None" = None,
+    enable_history: bool = True,
+    history_limit: int = 50,
+    # Tool customization
+    delegate_tool_class: "type[BaseTool] | None" = None,
+) -> "ReactAgent":
+    """Create ReactAgent with minimal boilerplate.
+    
+    This is the recommended way to create a ReactAgent for simple use cases.
+    Session, Storage, and Bus are auto-created if not provided.
+    
+    Args:
+        llm: LLM provider (required)
+        tools: Tool registry or list of tools (optional)
+        config: Agent configuration (optional)
+        backends: Backends container (recommended, auto-created if None)
+        session: Session object (auto-created if None)
+        bus: Event bus (auto-created if None)
+        middlewares: List of middlewares (auto-creates chain)
+        subagents: List of sub-agent configs (auto-creates SubAgentManager)
+        memory: Memory manager (optional)
+        snapshot: Snapshot backend (optional)
+        context_providers: Additional custom context providers (optional)
+        enable_history: Enable message history (default True)
+        history_limit: Max conversation turns to keep (default 50)
+        delegate_tool_class: Custom DelegateTool class (optional)
+        
+    Returns:
+        Configured ReactAgent ready to run
+        
+    Example:
+        # Minimal
+        agent = create_react_agent(llm=my_llm)
+        
+        # With backends
+        agent = create_react_agent(
+            llm=my_llm,
+            backends=Backends.create_default(),
+        )
+        
+        # With tools and middlewares
+        agent = create_react_agent(
+            llm=my_llm,
+            tools=[tool1, tool2],
+            middlewares=[MessageContainerMiddleware()],
+        )
+        
+        # With sub-agents
+        agent = create_react_agent(
+            llm=my_llm,
+            subagents=[
+                AgentConfig(key="researcher", agent=researcher_agent),
+            ],
+        )
+        
+        # With custom context providers
+        agent = create_react_agent(
+            llm=my_llm,
+            tools=[tool1],
+            context_providers=[MyRAGProvider(), MyProjectProvider()],
+        )
+    """
+    from .agent import ReactAgent
+    from ..core.event_bus import EventBus
+    from ..backends import Backends
+    from ..backends.subagent import ListSubAgentBackend
+    from ..tool import ToolSet
+    from ..tool.builtin import DelegateTool
+    from ..middleware import MiddlewareChain, MessageBackendMiddleware
+    from ..context_providers import MessageContextProvider
+    
+    # Auto-create backends if not provided
+    if backends is None:
+        backends = Backends.create_default()
+    
+    # Auto-create missing components
+    if session is None:
+        session = Session(id=generate_id("sess"))
+    if bus is None:
+        bus = EventBus()
+    
+    # Create middleware chain (add MessageBackendMiddleware if history enabled)
+    middleware_chain: MiddlewareChain | None = None
+    if middlewares or enable_history:
+        middleware_chain = MiddlewareChain()
+        # Add message persistence middleware first (uses backends.message)
+        if enable_history and backends.message is not None:
+            middleware_chain.use(MessageBackendMiddleware(max_history=history_limit))
+        # Add user middlewares
+        if middlewares:
+            for mw in middlewares:
+                middleware_chain.use(mw)
+    
+    # === Build tools list (direct, no provider) ===
+    tool_list: list["BaseTool"] = []
+    if tools is not None:
+        if isinstance(tools, ToolSet):
+            tool_list = list(tools.all())
+        else:
+            tool_list = list(tools)
+    
+    # Handle subagents - create DelegateTool directly
+    if subagents:
+        backend = ListSubAgentBackend(subagents)
+        tool_cls = delegate_tool_class or DelegateTool
+        delegate_tool = tool_cls(backend, middleware=middleware_chain)
+        tool_list.append(delegate_tool)
+    
+    # === Build providers ===
+    default_providers: list["ContextProvider"] = []
+    
+    # MessageContextProvider - for fetching history (uses backends.message)
+    if enable_history:
+        message_provider = MessageContextProvider(max_messages=history_limit * 2)
+        default_providers.append(message_provider)
+    
+    # Combine default + custom context_providers
+    all_providers = default_providers + (context_providers or [])
+    
+    # Build context
+    ctx = InvocationContext(
+        session=session,
+        invocation_id=generate_id("inv"),
+        agent_id=config.name if config else "react_agent",
+        backends=backends,
+        bus=bus,
+        llm=llm,
+        middleware=middleware_chain,
+        memory=memory,
+        snapshot=snapshot,
+    )
+    
+    agent = ReactAgent(ctx, config)
+    agent._tools = tool_list  # Direct tools (not from context_provider)
+    agent._context_providers = all_providers
+    agent._delegate_tool_class = delegate_tool_class or DelegateTool
+    agent._middleware_chain = middleware_chain
+    return agent
+
+
+async def restore_react_agent(
+    session_id: str,
+    llm: "LLMProvider",
+    *,
+    backends: "Backends | None" = None,
+    tools: "ToolSet | list[BaseTool] | None" = None,
+    config: AgentConfig | None = None,
+    bus: "Bus | None" = None,
+    middleware: "MiddlewareChain | None" = None,
+    memory: "MemoryManager | None" = None,
+    snapshot: "SnapshotBackend | None" = None,
+) -> "ReactAgent":
+    """Restore agent from persisted state.
+    
+    Use this to resume an agent after:
+    - Page refresh
+    - Process restart
+    - Cross-process recovery
+    
+    Args:
+        session_id: Session ID to restore
+        llm: LLM provider
+        backends: Backends container (recommended, auto-created if None)
+        tools: Tool registry or list of tools
+        config: Agent configuration
+        bus: Event bus (auto-created if None)
+        middleware: Middleware chain
+        memory: Memory manager
+        snapshot: Snapshot backend
+        
+    Returns:
+        Restored ReactAgent ready to continue
+        
+    Raises:
+        SessionNotFoundError: If session not found
+        
+    Example:
+        agent = await restore_react_agent(
+            session_id="sess_xxx",
+            backends=my_backends,
+            llm=my_llm,
+        )
+        
+        # Check if waiting for HITL response
+        if agent.is_suspended:
+            print(f"Waiting for: {agent.pending_request}")
+        else:
+            # Continue conversation
+            await agent.run("Continue...")
+    """
+    from .agent import ReactAgent
+    from ..core.event_bus import Bus
+    from ..core.types.session import Session, Invocation, InvocationState, generate_id
+    from ..core.state import State
+    from ..tool import ToolSet
+    from ..backends import Backends
+    
+    # Auto-create backends if not provided
+    if backends is None:
+        backends = Backends.create_default()
+    
+    # Validate storage backend is available
+    if backends.state is None:
+        raise ValueError("Cannot restore: no storage backend available (backends.state is None)")
+    
+    storage = backends.state
+    
+    # 1. Load session
+    session_data = await storage.get("sessions", session_id)
+    if not session_data:
+        raise SessionNotFoundError(f"Session not found: {session_id}")
+    session = Session.from_dict(session_data)
+    
+    # 2. Load current invocation
+    invocation: Invocation | None = None
+    if session_data.get("current_invocation_id"):
+        inv_data = await storage.get("invocations", session_data["current_invocation_id"])
+        if inv_data:
+            invocation = Invocation.from_dict(inv_data)
+    
+    # 3. Load state
+    state = State(storage, session_id)
+    await state.restore()
+    
+    # 4. Handle tools
+    tool_set: ToolSet | None = None
+    if tools is not None:
+        if isinstance(tools, ToolSet):
+            tool_set = tools
+        else:
+            tool_set = ToolSet()
+            for tool in tools:
+                tool_set.add(tool)
+    else:
+        tool_set = ToolSet()
+    
+    # 5. Create bus if needed
+    if bus is None:
+        bus = Bus()
+    
+    # 6. Build context
+    ctx = InvocationContext(
+        session=session,
+        invocation_id=invocation.id if invocation else generate_id("inv"),
+        agent_id=config.name if config else "react_agent",
+        backends=backends,
+        bus=bus,
+        llm=llm,
+        tools=tool_set,
+        middleware=middleware,
+        memory=memory,
+        snapshot=snapshot,
+    )
+    
+    # 7. Create agent
+    agent = ReactAgent(ctx, config)
+    agent._restored_invocation = invocation
+    agent._state = state
+    
+    return agent