worker-agent 1.0.3__py3-none-any.whl

config.yaml

@@ -0,0 +1,54 @@
+# =============================================================================
+# Worker Agent Configuration
+# Clone this file to create a new specialized worker — no code changes needed.
+# =============================================================================
+
+agent:
+  name: "WorkerAgent"
+  version: "1.0.0"
+  description: |
+    Run the Worker Agent's internal ReAct loop to complete a sub-task.
+    Args:
+        instruction: A clear, self-contained description of the task to perform.
+
+    Returns:
+        The final result produced by the agent after it has finished reasoning
+        and using its tools. A log file path is appended for traceability.
+
+  system_prompt: |
+    You are a diligent, autonomous worker agent. 
+    Your job is to complete the sub-task given to you as precisely and efficiently as possible.
+    You have access to a set of tools. Think step-by-step, use the tools you need, 
+    self-correct on errors, and only respond once the task is fully complete.
+    Do NOT ask for clarification — make your best effort with the information provided.
+
+model:
+  provider: "ollama" # Supported: "ollama", "openai", "gemini"
+  model_name: "qwen3-coder:480b-cloud"
+  temperature: 0.0
+  base_url: "http://localhost:11434" # Uncomment if using openai or gemini (or set API_KEY env var) https://api.openai.com/v1 ollma local (http://localhost:11434)
+  # api_key: "your-api-key-here" # Uncomment if using openai or gemini (or set API_KEY env var)
+
+# MCP Servers this worker connects TO as a CLIENT to get its tools.
+# Each entry starts a subprocess and connects via stdio.
+mcp_clients:
+  # - name: "filesystem-server"
+  #   command: "npx"
+  #   args: ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Dev/Project"]
+  #
+  # - name: "brave-search"
+  #   command: "npx"
+  #   args: ["-y", "@modelcontextprotocol/server-brave-search"]
+  #
+  - name: "shell_execution"
+    command: "D:\\DEV\\ML\\Seeker\\.venv\\Scripts\\python.exe"
+    args: ["-m", "mcp_server_shell", "--shell", "powershell"]
+    env:
+      CWD: "D:\\DEV\\ML\\Seeker"
+
+# How this worker exposes ITSELF as an MCP server.
+server:
+  name: "worker-agent-server"
+  port: 8001 # HTTP/SSE transport port
+  transport: "stdio" # "stdio" or "sse"
+  host: "0.0.0.0"

core/__init__.py

@@ -0,0 +1,3 @@
+"""
+core/__init__.py
+"""

core/agent.py

@@ -0,0 +1,344 @@
+"""
+core/agent.py
+-------------
+The heart of the Worker Agent.
+
+Responsibilities:
+1. Read config to know which MCP servers to connect to.
+2. Dynamically load all tools from those MCP servers (connections stay alive).
+3. Build a LangGraph ReAct loop with those tools + the local Ollama LLM.
+4. Log every single step to a per-job file via JobLogger.
+5. Expose run_agent(task, config) -> str used by main.py.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import traceback
+import warnings
+from contextlib import AsyncExitStack
+
+# Suppress LangGraph deprecation noise
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+from langchain_core.messages import (
+    AIMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from langchain_core.tools import BaseTool
+from langchain_ollama import ChatOllama
+
+try:
+    from langchain_openai import ChatOpenAI
+except ImportError:
+    pass
+try:
+    from langchain_google_genai import ChatGoogleGenerativeAI
+except ImportError:
+    pass
+from langchain_mcp_adapters.tools import load_mcp_tools
+from langgraph.prebuilt import create_react_agent
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from core.config_loader import AppConfig
+from core.job_logger import JobLogger
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _tool_input(tool_call: dict) -> dict:
+    """Extract input args from a LangChain tool call dict."""
+    return tool_call.get("args", {}) or {}
+
+
+def _truncate(text: str, max_chars: int = 800) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + f"\n... [{len(text) - max_chars} chars truncated]"
+
+
+def _unwrap_exception(exc: BaseException) -> BaseException:
+    """Recursively unwrap ExceptionGroups to find the underlying root cause."""
+    # Check if this is an ExceptionGroup (Python 3.11+ built-in)
+    if hasattr(exc, "exceptions") and exc.exceptions:
+        # We recursively unwrap the first exception in the group.
+        # This assumes the most interesting error is the first one (often true for simple TaskGroups).
+        return _unwrap_exception(exc.exceptions[0])
+    return exc
+
+
+# ---------------------------------------------------------------------------
+# Main entry-point — called by main.py for every execute_task() invocation
+# ---------------------------------------------------------------------------
+
+
+async def run_agent(task: str, config: AppConfig) -> str:
+    """
+    Execute a task using the full ReAct loop with per-job structured logging.
+
+    - One JobLogger (= one log file) is created per call.
+    - All MCP connections remain open for the entire loop duration.
+    - Every LLM output, tool call, tool result and error is logged as a step.
+
+    Args:
+        task:   The natural-language instruction for this worker.
+        config: The loaded AppConfig from config.yaml.
+
+    Returns:
+        str: The final answer produced by the agent.
+    """
+    jl = JobLogger(task=task, agent_name=config.agent.name)
+    logger.info("[%s] Job %s started | task: %s", config.agent.name, jl.job_id, task[:80])
+
+    all_tools: list[BaseTool] = []
+    final_answer = ""
+    success = False
+
+    try:
+        # ----------------------------------------------------------------
+        # PHASE 1 — Connect to all MCP tool servers
+        # ----------------------------------------------------------------
+        async with AsyncExitStack() as stack:
+            for client_cfg in config.mcp_clients:
+                server_params = StdioServerParameters(
+                    command=client_cfg.command,
+                    args=client_cfg.args,
+                    env=client_cfg.env or None,
+                )
+                try:
+                    read, write = await stack.enter_async_context(stdio_client(server_params))
+                    session: ClientSession = await stack.enter_async_context(
+                        ClientSession(read, write)
+                    )
+                    await session.initialize()
+                    tools = await load_mcp_tools(session)
+                    tool_names = [t.name for t in tools]
+                    all_tools.extend(tools)
+
+                    jl.log_step(
+                        step_type="MCP_CONNECT",
+                        title=client_cfg.name,
+                        details={
+                            "command": client_cfg.command,
+                            "args": client_cfg.args,
+                            "tools_loaded": tool_names,
+                        },
+                        success=True,
+                    )
+                    logger.info("[%s] Connected | tools: %s", client_cfg.name, tool_names)
+
+                except Exception as exc:
+                    tb = traceback.format_exc()
+                    jl.log_step(
+                        step_type="MCP_CONNECT",
+                        title=client_cfg.name,
+                        details={"command": client_cfg.command, "args": client_cfg.args},
+                        error=f"{exc}\n{tb}",
+                        success=False,
+                    )
+                    logger.error("[%s] Connection failed: %s", client_cfg.name, exc)
+
+            if not all_tools:
+                jl.log_step(
+                    step_type="INFO",
+                    title="No tools available",
+                    details={
+                        "note": "Running with LLM only (no MCP tools configured or all failed to connect)."
+                    },
+                )
+
+            # ----------------------------------------------------------------
+            # PHASE 2 — Build the ReAct agent
+            # ----------------------------------------------------------------
+            tool_descriptions = "\n".join(
+                f"  - {t.name}: {getattr(t, 'description', 'no description')}" for t in all_tools
+            )
+            enriched_prompt = config.agent.system_prompt + (
+                f"\n\nAvailable tools:\n{tool_descriptions}" if tool_descriptions else ""
+            )
+
+            provider = config.model.provider.lower()
+            if provider == "openai":
+                llm = ChatOpenAI(
+                    model=config.model.model_name,
+                    temperature=config.model.temperature,
+                    api_key=config.model.api_key,
+                    base_url=config.model.base_url
+                    if config.model.base_url != "http://localhost:11434"
+                    else None,
+                )
+            elif provider == "gemini":
+                llm = ChatGoogleGenerativeAI(
+                    model=config.model.model_name,
+                    temperature=config.model.temperature,
+                    api_key=config.model.api_key,
+                )
+            else:
+                # default to ollama
+                llm = ChatOllama(
+                    model=config.model.model_name,
+                    temperature=config.model.temperature,
+                    base_url=config.model.base_url,
+                )
+            graph = create_react_agent(model=llm, tools=all_tools)
+
+            jl.log_step(
+                step_type="AGENT_INIT",
+                title="LangGraph ReAct agent ready",
+                details={
+                    "model": config.model.model_name,
+                    "temperature": config.model.temperature,
+                    "tools": [t.name for t in all_tools],
+                },
+            )
+
+            # ----------------------------------------------------------------
+            # PHASE 3 — Run the ReAct loop + log every event
+            # ----------------------------------------------------------------
+            messages = [
+                SystemMessage(content=enriched_prompt),
+                HumanMessage(content=task),
+            ]
+
+            # Track which tool calls we've already logged (by tool call id)
+            _logged_tool_calls: set = set()
+            _llm_step = 0
+
+            async for event in graph.astream(
+                {"messages": messages},
+                stream_mode="values",
+            ):
+                last_msg = event["messages"][-1]
+
+                # ── AIMessage: LLM produced text or tool-call plan ────────
+                if isinstance(last_msg, AIMessage):
+                    tool_calls = getattr(last_msg, "tool_calls", []) or []
+
+                    # Log the text part of the LLM response (if any)
+                    if last_msg.content:
+                        _llm_step += 1
+
+                        # Handle list-based content (e.g., from Gemini's multimodal format)
+                        content_val = last_msg.content
+                        if isinstance(content_val, list):
+                            content_val = "\n".join(
+                                b.get("text", str(b)) if isinstance(b, dict) else str(b)
+                                for b in content_val
+                            )
+                        elif not isinstance(content_val, str):
+                            content_val = str(content_val)
+
+                        jl.log_step(
+                            step_type="LLM_RESPONSE",
+                            title=f"LLM turn {_llm_step}",
+                            output=_truncate(content_val),
+                        )
+                        final_answer = content_val
+
+                    # Log each tool call the LLM decided to make
+                    for tc in tool_calls:
+                        tc_id = tc.get("id", "")
+                        if tc_id in _logged_tool_calls:
+                            continue
+                        _logged_tool_calls.add(tc_id)
+                        jl.log_step(
+                            step_type="TOOL_CALL",
+                            title=tc.get("name", "unknown"),
+                            details={
+                                "tool": tc.get("name"),
+                                "call_id": tc_id,
+                                "input": _tool_input(tc),
+                            },
+                        )
+
+                # ── ToolMessage: result came back from a tool ─────────────
+                elif isinstance(last_msg, ToolMessage):
+                    raw_content = last_msg.content or ""
+                    # Detect error by checking for non-zero return codes or exception text
+                    is_error = (
+                        "error" in str(raw_content).lower()
+                        or "exception" in str(raw_content).lower()
+                        or "traceback" in str(raw_content).lower()
+                    )
+                    jl.log_step(
+                        step_type="TOOL_RESULT",
+                        title=getattr(last_msg, "name", "tool") or "tool",
+                        details={"call_id": getattr(last_msg, "tool_call_id", "")},
+                        output=_truncate(str(raw_content)),
+                        success=not is_error,
+                        error=str(raw_content) if is_error else None,
+                    )
+
+            # ── Done ──────────────────────────────────────────────────────
+            success = True
+
+    except BaseException as root_exc:
+        # We catch BaseException so we can catch BaseExceptionGroup
+        exc = _unwrap_exception(root_exc)
+        tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+
+        # Don't log normal cancellations as fatal errors
+        if isinstance(exc, (asyncio.CancelledError, KeyboardInterrupt)):
+            logger.warning(
+                "[%s] Job %s was cancelled or interrupted.", config.agent.name, jl.job_id
+            )
+            final_answer = "ERROR: Agent task was cancelled or interrupted."
+            success = False
+
+        # Gracefully log familiar LLM provider errors without tracebacks
+        elif type(exc).__name__ in (
+            "RateLimitError",
+            "AuthenticationError",
+            "APIConnectionError",
+            "APIError",
+            "InvalidRequestError",
+        ):
+            jl.log_step(
+                step_type="LLM_API_ERROR",
+                title=type(exc).__name__,
+                error=f"{exc}",
+                success=False,
+            )
+            logger.error(
+                "[%s] Job %s failed with LLM provider API error: %s",
+                config.agent.name,
+                jl.job_id,
+                exc,
+            )
+            final_answer = f"ERROR: LLM Provider Issue ({type(exc).__name__}): {exc}"
+            success = False
+
+        # All other unhandled exceptions get the dreaded Traceback log
+        else:
+            jl.log_step(
+                step_type="FATAL_ERROR",
+                title=type(exc).__name__,
+                error=f"{exc}\n\n{tb}",
+                success=False,
+            )
+            logger.exception(
+                "[%s] Job %s failed with unhandled exception: %s", config.agent.name, jl.job_id, exc
+            )
+            final_answer = f"ERROR: {type(exc).__name__}: {exc}"
+            success = False
+
+    finally:
+        jl.finish(final_answer=final_answer, success=success)
+        logger.info(
+            "[%s] Job %s %s | log: %s",
+            config.agent.name,
+            jl.job_id,
+            "COMPLETE" if success else "FAILED",
+            jl.path,
+        )
+
+    return final_answer or "Agent completed the task but produced no text output."

core/config_loader.py

@@ -0,0 +1,159 @@
+"""
+core/config_loader.py
+---------------------
+Loads and validates config.yaml into typed dataclasses.
+Import and use `load_config()` anywhere in the project.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+# ---------------------------------------------------------------------------
+# Dataclass models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ModelConfig:
+    provider: str = "ollama"  # e.g., "ollama", "openai", "gemini"
+    model_name: str = "llama3.2"
+    temperature: float = 0.0
+    base_url: str = "http://localhost:11434"
+    api_key: str | None = None
+
+
+@dataclass
+class MCPClientConfig:
+    """Represents one external MCP server this worker connects to as a client."""
+
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict = field(default_factory=dict)  # optional extra env vars
+
+
+@dataclass
+class ServerConfig:
+    name: str = "worker-agent-server"
+    port: int = 8001
+    transport: str = "stdio"  # "stdio" | "sse"
+    host: str = "0.0.0.0"
+
+
+DEFAULT_DESCRIPTION = (
+    "Run the Worker Agent's internal ReAct loop to complete a sub-task.\n"
+    "Args:\n"
+    "    instruction: A clear, self-contained description of the task to perform.\n\n"
+    "Returns:\n"
+    "    The final result produced by the agent after it has finished reasoning\n"
+    "    and using its tools. A log file path is appended for traceability."
+)
+
+
+@dataclass
+class AgentConfig:
+    name: str = "WorkerAgent"
+    version: str = "1.0.0"
+    description: str = DEFAULT_DESCRIPTION
+    system_prompt: str = "You are a helpful worker agent."
+
+
+@dataclass
+class AppConfig:
+    agent: AgentConfig = field(default_factory=AgentConfig)
+    model: ModelConfig = field(default_factory=ModelConfig)
+    mcp_clients: list[MCPClientConfig] = field(default_factory=list)
+    server: ServerConfig = field(default_factory=ServerConfig)
+
+
+# ---------------------------------------------------------------------------
+# Loader
+# ---------------------------------------------------------------------------
+
+
+def load_config(config_path: str | None = None) -> AppConfig:
+    """
+    Priority:
+    1. config_path (passed to function)
+    2. WORKER_AGENT_CONFIG (environment variable)
+    3. ./config.yaml (Current Working Directory)
+    4. ../config.yaml (Package Root fallback)
+    """
+
+    # Define potential locations
+    env_path = os.getenv("WORKER_AGENT_CONFIG")
+    cwd_path = Path.cwd() / "config.yaml"
+    package_root_path = Path(__file__).parent.parent / "config.yaml"
+
+    # Select the first one that exists
+    if config_path:
+        final_path = Path(config_path)
+    elif env_path:
+        final_path = Path(env_path)
+    elif cwd_path.exists():
+        final_path = cwd_path
+    else:
+        final_path = package_root_path
+
+    # Final check
+    if not final_path.exists():
+        raise FileNotFoundError(
+            f"Config file not found. Checked:\n"
+            f"- Explicit path: {config_path}\n"
+            f"- Env Var (WORKER_AGENT_CONFIG): {env_path}\n"
+            f"- Current Directory: {cwd_path}\n"
+            f"- Package Fallback: {package_root_path}\n"
+            f"Please ensure a 'config.yaml' exists in your current folder."
+        )
+
+    print(f"[*] Using config: {final_path.absolute()}")
+
+    with open(final_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+
+    # --- Agent ---
+    agent_raw = raw.get("agent", {})
+    agent = AgentConfig(
+        name=agent_raw.get("name", "WorkerAgent"),
+        version=agent_raw.get("version", "1.0.0"),
+        description=agent_raw.get("description", DEFAULT_DESCRIPTION),
+        system_prompt=agent_raw.get("system_prompt", "You are a helpful worker agent."),
+    )
+
+    # --- Model ---
+    model_raw = raw.get("model", {})
+    model = ModelConfig(
+        provider=model_raw.get("provider", "ollama"),
+        model_name=model_raw.get("model_name", "llama3.2"),
+        temperature=float(model_raw.get("temperature", 0.0)),
+        base_url=model_raw.get("base_url", "http://localhost:11434"),
+        api_key=model_raw.get("api_key", os.getenv("API_KEY")),
+    )
+
+    # --- MCP Clients ---
+    mcp_clients = []
+    for entry in raw.get("mcp_clients", []) or []:
+        mcp_clients.append(
+            MCPClientConfig(
+                name=entry["name"],
+                command=entry["command"],
+                args=entry.get("args", []),
+                env=entry.get("env", {}),
+            )
+        )
+
+    # --- Server ---
+    server_raw = raw.get("server", {})
+    server = ServerConfig(
+        name=server_raw.get("name", "worker-agent-server"),
+        port=int(server_raw.get("port", 8001)),
+        transport=server_raw.get("transport", "stdio"),
+        host=server_raw.get("host", "0.0.0.0"),
+    )
+
+    return AppConfig(agent=agent, model=model, mcp_clients=mcp_clients, server=server)