contextagent 0.1.0__py3-none-any.whl

agentz/profiles/mcp/chrome.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class InstructionsInput(BaseModel):
+    """Input schema for instructions-based runtime template."""
+    instructions: str = Field(description="The instructions to follow")
+
+
+# Profile instance for chrome agent
+chrome_profile = Profile(
+    instructions="You are a chrome agent. Your task is to interact with the chrome browser following the instructions provided.",
+    runtime_template="[[INSTRUCTIONS]]",
+    output_schema=None,
+    input_schema=InstructionsInput,
+    tools=None,
+    model=None
+)

agentz/profiles/mcp/notion.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from agentz.profiles.base import Profile
+
+
+class InstructionsInput(BaseModel):
+    """Input schema for instructions-based runtime template."""
+    instructions: str = Field(description="The instructions to follow")
+
+
+# Profile instance for notion agent
+notion_profile = Profile(
+    instructions="You are a notion agent. Your task is to interact with the notion MCP server following the instructions provided.",
+    runtime_template="[[INSTRUCTIONS]]",
+    output_schema=None,
+    input_schema=InstructionsInput,
+    tools=None,
+    model=None
+)

agentz/runner/__init__.py

@@ -0,0 +1,74 @@
+"""Agent runtime execution module.
+
+This module provides the complete agent runtime infrastructure:
+
+Base Runners:
+- Runner: Base runner from agents library (re-exported)
+- ContextRunner: Context-aware runner with output parsing
+
+Runtime Infrastructure:
+- RuntimeTracker: Manages runtime state (tracing, printing, reporting, iteration tracking, data store)
+- AgentExecutor: High-level agent execution with full pipeline infrastructure
+- AgentStep: Abstraction for a single agent execution step
+
+Pipeline Infrastructure:
+- HookRegistry: Event-driven hook system for pipeline lifecycle
+- IterationManager: Iteration management for iterative workflows
+- WorkflowHelpers: Control flow helpers (loops, conditionals, parallel execution)
+
+High-Level Patterns:
+- execute_tool_plan: Execute tool agents from routing plans
+- execute_tools: Execute tools based on routing plan
+- run_manager_tool_loop: Standard manager-tool iterative pattern
+
+Utilities:
+- record_structured_payload: Record payloads to state
+- serialize_output: Serialize agent outputs
+
+Runtime Access:
+- get_current_tracker: Access the current RuntimeTracker from anywhere
+- get_current_data_store: Convenience for accessing the data store
+
+"""
+
+from agentz.runner.base import Runner, ContextRunner
+from agentz.runner.tracker import (
+    RuntimeTracker,
+    get_current_tracker,
+    get_current_data_store,
+)
+from agentz.runner.executor import AgentExecutor, AgentStep, PrinterConfig
+from agentz.runner.hooks import HookRegistry
+from agentz.runner.iteration import IterationManager
+from agentz.runner.workflow import WorkflowHelpers
+from agentz.runner.patterns import (
+    execute_tool_plan,
+    execute_tools,
+    run_manager_tool_loop,
+)
+from agentz.runner.utils import record_structured_payload, serialize_output
+
+__all__ = [
+    # Base runners
+    "Runner",
+    "ContextRunner",
+    # Runtime infrastructure
+    "RuntimeTracker",
+    "AgentExecutor",
+    "AgentStep",
+    "PrinterConfig",
+    # Pipeline infrastructure
+    "HookRegistry",
+    "IterationManager",
+    "WorkflowHelpers",
+    # High-level patterns
+    "execute_tool_plan",
+    "execute_tools",
+    "run_manager_tool_loop",
+    # Utilities
+    "record_structured_payload",
+    "serialize_output",
+    # Runtime access
+    "get_current_tracker",
+    "get_current_data_store",
+]

agentz/runner/base.py

@@ -0,0 +1,28 @@
+"""Base runner classes for agent execution.
+
+This module provides the foundational runner classes:
+- Runner: Base runner from agents library (re-exported for convenience)
+- ContextRunner: Context-aware runner that applies output parsing
+"""
+
+from typing import Any
+
+from agents import Runner, RunResult
+
+__all__ = ["Runner", "ContextRunner"]
+
+
+class ContextRunner(Runner):
+    """Runner shim that invokes ContextAgent.parse_output after execution."""
+
+    @classmethod
+    async def run(cls, *args: Any, **kwargs: Any) -> RunResult:
+        result = await Runner.run(*args, **kwargs)
+        starting_agent = kwargs.get("starting_agent") or (args[0] if args else None)
+
+        # Import here to avoid circular dependency
+        from agentz.agent.base import ContextAgent
+
+        if isinstance(starting_agent, ContextAgent):
+            return await starting_agent.parse_output(result)
+        return result

agentz/runner/executor.py

@@ -0,0 +1,320 @@
+"""Core agent execution primitives."""
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional, Union
+
+from agentz.runner.base import ContextRunner as Runner
+from agents.tracing.create import agent_span, function_span
+from pydantic import BaseModel
+
+from agentz.runner.tracker import RuntimeTracker
+
+
+@dataclass
+class PrinterConfig:
+    """Configuration for printer updates during step execution."""
+    key: Optional[str] = None
+    title: Optional[str] = None
+    start_message: Optional[str] = None
+    done_message: Optional[str] = None
+
+
+@dataclass
+class AgentStep:
+    """Represents a single agent execution step.
+
+    This encapsulates all the information needed to execute an agent:
+    - The agent instance
+    - Instructions (static or dynamic via callable)
+    - Span configuration for tracing
+    - Output model for parsing
+    - Printer configuration for status updates
+    """
+
+    agent: Any
+    instructions: Union[str, Callable[[], str]]
+    span_name: str
+    span_type: str = "agent"
+    output_model: Optional[type[BaseModel]] = None
+    sync: bool = False
+    printer_config: Optional[PrinterConfig] = None
+    span_kwargs: Dict[str, Any] = field(default_factory=dict)
+
+    def get_instructions(self) -> str:
+        """Get instructions, evaluating callable if needed.
+
+        Returns:
+            Instructions string
+        """
+        if callable(self.instructions):
+            return self.instructions()
+        return self.instructions
+
+    def get_printer_key(self, iteration: int = 0) -> Optional[str]:
+        """Get the printer key, adding iteration prefix if configured.
+
+        Args:
+            iteration: Current iteration number
+
+        Returns:
+            Printer key with iteration prefix, or None if not configured
+        """
+        if not self.printer_config or not self.printer_config.key:
+            return None
+        return f"iter:{iteration}:{self.printer_config.key}"
+
+
+class AgentExecutor:
+    """Core agent execution primitive.
+
+    Handles the low-level mechanics of running agents with:
+    - Span tracking and output capture
+    - Optional output model parsing
+    - Printer status updates
+    - Sync/async execution
+    """
+
+    def __init__(self, context: RuntimeTracker):
+        """Initialize executor with runtime tracker.
+
+        Args:
+            context: RuntimeTracker for tracing, printing, etc.
+        """
+        self.context = context
+
+    async def execute_step(self, step: AgentStep) -> Any:
+        """Execute an AgentStep.
+
+        Args:
+            step: AgentStep to execute
+
+        Returns:
+            Parsed output if output_model provided, otherwise Runner result
+        """
+        instructions = step.get_instructions()
+
+        return await self.agent_step(
+            agent=step.agent,
+            instructions=instructions,
+            span_name=step.span_name,
+            span_type=step.span_type,
+            output_model=step.output_model,
+            sync=step.sync,
+            printer_key=step.printer_config.key if step.printer_config else None,
+            printer_title=step.printer_config.title if step.printer_config else None,
+            **step.span_kwargs
+        )
+
+    async def agent_step(
+        self,
+        agent,
+        instructions: str,
+        span_name: Optional[str] = None,
+        span_type: str = "agent",
+        output_model: Optional[type[BaseModel]] = None,
+        sync: bool = False,
+        printer_key: Optional[str] = None,
+        printer_title: Optional[str] = None,
+        group_id: Optional[str] = None,
+        printer_group_id: Optional[str] = None,
+        printer_border_style: Optional[str] = None,
+        **span_kwargs
+    ) -> Any:
+        """Run an agent with span tracking and optional output parsing.
+
+        Args:
+            agent: The agent to run
+            instructions: Instructions/prompt for the agent
+            span_name: Name for the span (auto-detected from agent.name if not provided)
+            span_type: Type of span - "agent" or "function"
+            output_model: Optional pydantic model to parse output
+            sync: Whether to run synchronously
+            printer_key: Optional key for printer updates (auto-detected from agent.name if not provided)
+            printer_title: Optional title for printer display (auto-detected from agent.name if not provided)
+            group_id: Optional group to nest this item in (alias for printer_group_id)
+            printer_group_id: Optional group to nest this item in (deprecated, use group_id)
+            printer_border_style: Optional border color
+            **span_kwargs: Additional kwargs for span (e.g., tools, input)
+
+        Returns:
+            Parsed output if output_model provided, otherwise Runner result
+        """
+        # Extract agent name for auto-detection
+        agent_name = getattr(agent, "name", getattr(agent, "__class__", type("obj", (), {})).__name__)
+
+        # Auto-detect span_name from agent if not provided
+        if span_name is None:
+            span_name = str(agent_name)
+
+        # Auto-detect printer_key from agent if not provided
+        if printer_key is None:
+            printer_key = str(agent_name)
+
+        # Auto-detect printer_title from agent if not provided
+        if printer_title is None:
+            # Capitalize first letter and add "ing" suffix
+            title_base = str(agent_name).capitalize()
+            printer_title = f"{title_base}"
+
+        # Support both group_id and printer_group_id (group_id takes precedence)
+        if group_id is not None:
+            printer_group_id = group_id
+
+        span_factory = agent_span if span_type == "agent" else function_span
+
+        reporter = self.context.reporter
+        step_id: Optional[str] = None
+        if reporter:
+            step_id = f"{self.context.iteration}-{span_name}-{time.time_ns()}"
+            reporter.record_agent_step_start(
+                step_id=step_id,
+                agent_name=str(agent_name),
+                span_name=span_name,
+                iteration=self.context.iteration,
+                group_id=printer_group_id,
+                printer_title=printer_title,
+            )
+
+        full_printer_key: Optional[str] = None
+        if printer_key:
+            full_printer_key = f"iter:{self.context.iteration}:{printer_key}"
+            self.context.update_printer(
+                full_printer_key,
+                "Working...",
+                title=printer_title or printer_key,
+                border_style=printer_border_style,
+                group_id=printer_group_id,
+            )
+
+        status = "success"
+        error_message: Optional[str] = None
+        start_time = time.perf_counter()
+
+        try:
+            with self.context.span_context(span_factory, name=span_name, **span_kwargs) as span:
+                # Activate context so tools can access it
+                with self.context.activate():
+                    if sync:
+                        result = Runner.run_sync(agent, instructions, context=self.context.data_store)
+                    else:
+                        result = await Runner.run(agent, instructions, context=self.context.data_store)
+
+                raw_output = getattr(result, "final_output", result)
+
+                # Update printer status and emit detailed output as a standalone panel
+                if full_printer_key:
+                    self.context.update_printer(
+                        full_printer_key,
+                        "Completed",
+                        is_done=True,
+                        title=printer_title or printer_key,
+                        group_id=printer_group_id,
+                        border_style=printer_border_style,
+                    )
+
+                    # Extract content from raw_output
+                    if hasattr(raw_output, 'output'):
+                        panel_content = str(raw_output.output)
+                    elif isinstance(raw_output, BaseModel):
+                        panel_content = raw_output.model_dump_json(indent=2)
+                    elif isinstance(raw_output, dict):
+                        panel_content = json.dumps(raw_output, indent=2)
+                    else:
+                        panel_content = str(raw_output)
+
+                    if panel_content.strip():
+                        self.context.log_panel(
+                            printer_title or printer_key,
+                            panel_content,
+                            border_style=printer_border_style,
+                            iteration=self.context.iteration,
+                            group_id=printer_group_id,
+                        )
+
+                if output_model:
+                    if isinstance(raw_output, output_model):
+                        output = raw_output
+                    elif isinstance(raw_output, BaseModel):
+                        output = output_model.model_validate(raw_output.model_dump())
+                    elif isinstance(raw_output, (dict, list)):
+                        output = output_model.model_validate(raw_output)
+                    elif isinstance(raw_output, (str, bytes, bytearray)):
+                        output = output_model.model_validate_json(raw_output)
+                    else:
+                        output = output_model.model_validate(raw_output)
+                    if span and hasattr(span, "set_output"):
+                        span.set_output(output.model_dump())
+                    return output
+                else:
+                    if span and hasattr(span, "set_output"):
+                        span.set_output({"output_preview": str(getattr(result, "final_output", result))[:200]})
+                    return result
+        except Exception as exc:  # noqa: BLE001 - propagate after logging
+            status = "error"
+            error_message = str(exc)
+            raise
+        finally:
+            if reporter and step_id is not None:
+                reporter.record_agent_step_end(
+                    step_id=step_id,
+                    status=status,
+                    duration_seconds=time.perf_counter() - start_time,
+                    error=error_message,
+                )
+
+    async def run_span_step(
+        self,
+        step_key: str,
+        callable_or_coro: Union[Callable, Any],
+        span_name: str,
+        span_type: str = "function",
+        start_message: Optional[str] = None,
+        done_message: Optional[str] = None,
+        **span_kwargs
+    ) -> Any:
+        """Execute a step with span context and printer updates.
+
+        Args:
+            step_key: Printer status key
+            callable_or_coro: Callable or coroutine to execute
+            span_name: Name for the span
+            span_type: Type of span - "agent" or "function"
+            start_message: Optional start message for printer
+            done_message: Optional completion message for printer
+            **span_kwargs: Additional kwargs for span (e.g., tools, input)
+
+        Returns:
+            Result from callable_or_coro
+        """
+        span_factory = agent_span if span_type == "agent" else function_span
+
+        if start_message:
+            self.context.update_printer(step_key, start_message)
+
+        with self.context.span_context(span_factory, name=span_name, **span_kwargs) as span:
+            # Execute callable or await coroutine
+            if asyncio.iscoroutine(callable_or_coro):
+                result = await callable_or_coro
+            elif callable(callable_or_coro):
+                result = callable_or_coro()
+            else:
+                result = callable_or_coro
+
+            # Set span output if available
+            if span and hasattr(span, "set_output"):
+                if isinstance(result, dict):
+                    span.set_output(result)
+                elif isinstance(result, str):
+                    span.set_output({"output_preview": result[:200]})
+                elif hasattr(result, "model_dump"):
+                    span.set_output(result.model_dump())
+                else:
+                    span.set_output({"result": str(result)[:200]})
+
+            if done_message:
+                self.context.update_printer(step_key, done_message, is_done=True)
+
+            return result

agentz/runner/hooks.py

@@ -0,0 +1,110 @@
+"""Hook registry system for event-driven pipeline extensibility."""
+
+import asyncio
+from typing import Any, Callable, Dict, List, Tuple
+
+from loguru import logger
+
+
+class HookRegistry:
+    """Registry for managing pipeline event hooks.
+
+    Supports registering callbacks for various lifecycle events and triggering
+    them with priority ordering.
+    """
+
+    DEFAULT_EVENTS = [
+        "before_execution",
+        "after_execution",
+        "before_iteration",
+        "after_iteration",
+        "before_agent_step",
+        "after_agent_step",
+    ]
+
+    def __init__(self, events: List[str] = None):
+        """Initialize hook registry.
+
+        Args:
+            events: List of event names to support (defaults to DEFAULT_EVENTS)
+        """
+        event_list = events or self.DEFAULT_EVENTS
+        self._hooks: Dict[str, List[Tuple[int, Callable]]] = {
+            event: [] for event in event_list
+        }
+
+    def register(
+        self,
+        event: str,
+        callback: Callable,
+        priority: int = 0
+    ) -> None:
+        """Register a hook callback for an event.
+
+        Args:
+            event: Event name
+            callback: Callable or async callable
+            priority: Execution priority (higher = earlier)
+
+        Raises:
+            ValueError: If event is not recognized
+
+        Example:
+            def log_iteration(pipeline, iteration, group_id):
+                logger.info(f"Starting iteration {iteration.index}")
+
+            registry.register("before_iteration", log_iteration)
+        """
+        if event not in self._hooks:
+            raise ValueError(
+                f"Unknown hook event: {event}. Valid events: {list(self._hooks.keys())}"
+            )
+
+        self._hooks[event].append((priority, callback))
+        # Sort by priority (descending)
+        self._hooks[event].sort(key=lambda x: -x[0])
+
+    async def trigger(self, event: str, context: Any, **kwargs) -> None:
+        """Trigger all registered hooks for an event.
+
+        Args:
+            event: Event name
+            context: Context object to pass to callbacks (typically the pipeline)
+            **kwargs: Additional arguments to pass to hook callbacks
+        """
+        if event not in self._hooks:
+            return
+
+        for priority, callback in self._hooks[event]:
+            try:
+                if asyncio.iscoroutinefunction(callback):
+                    await callback(context, **kwargs)
+                else:
+                    callback(context, **kwargs)
+            except Exception as e:
+                logger.warning(f"Hook {callback.__name__} for {event} failed: {e}")
+
+    def has_hooks(self, event: str) -> bool:
+        """Check if any hooks are registered for an event.
+
+        Args:
+            event: Event name
+
+        Returns:
+            True if hooks are registered, False otherwise
+        """
+        return event in self._hooks and len(self._hooks[event]) > 0
+
+    def clear_event(self, event: str) -> None:
+        """Clear all hooks for a specific event.
+
+        Args:
+            event: Event name
+        """
+        if event in self._hooks:
+            self._hooks[event].clear()
+
+    def clear_all(self) -> None:
+        """Clear all registered hooks."""
+        for event in self._hooks:
+            self._hooks[event].clear()