contextagent 0.1.0__py3-none-any.whl

agentz/artifacts/reporter.py

@@ -0,0 +1,235 @@
+"""Shared data models and RunReporter facade for pipeline runs."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+from rich.console import Console
+
+from agentz.artifacts.artifact_writer import ArtifactWriter
+from agentz.artifacts.terminal_writer import TerminalWriter
+
+
+@dataclass
+class PanelRecord:
+    """Representation of a panel rendered during the run."""
+
+    title: Optional[str]
+    content: str
+    border_style: Optional[str]
+    iteration: Optional[int]
+    group_id: Optional[str]
+    recorded_at: str
+
+
+@dataclass
+class AgentStepRecord:
+    """Runtime information captured per agent execution."""
+
+    agent_name: str
+    span_name: str
+    iteration: Optional[int]
+    group_id: Optional[str]
+    started_at: str
+    finished_at: Optional[str] = None
+    duration_seconds: Optional[float] = None
+    status: str = "running"
+    error: Optional[str] = None
+
+
+class RunReporter:
+    """Facade combining terminal display and artifact persistence."""
+
+    def __init__(
+        self,
+        *,
+        base_dir: Path,
+        pipeline_slug: str,
+        workflow_name: str,
+        experiment_id: str,
+        console: Optional[Console] = None,
+    ) -> None:
+        self.base_dir = base_dir
+        self.pipeline_slug = pipeline_slug
+        self.workflow_name = workflow_name
+        self.experiment_id = experiment_id
+        self.console = console
+
+        self.run_dir = base_dir / pipeline_slug / experiment_id
+        self.terminal_md_path = self.run_dir / "terminal_log.md"
+        self.terminal_html_path = self.run_dir / "terminal_log.html"
+        self.final_report_md_path = self.run_dir / "final_report.md"
+        self.final_report_html_path = self.run_dir / "final_report.html"
+
+        self._lock = threading.RLock()
+
+        # Delegate to specialized reporters
+        self._artifact_writer = ArtifactWriter(
+            base_dir=base_dir,
+            pipeline_slug=pipeline_slug,
+            workflow_name=workflow_name,
+            experiment_id=experiment_id,
+        )
+        self._terminal_writer = TerminalWriter(
+            run_dir=self.run_dir,
+            console=console,
+        )
+
+    # ------------------------------------------------------------------ basics
+
+    def start(self, config: Any) -> None:
+        """Prepare filesystem layout and capture start metadata."""
+        with self._lock:
+            self._artifact_writer.start(config)
+
+    def set_final_result(self, result: Any) -> None:
+        """Store pipeline result for later persistence."""
+        with self._lock:
+            self._artifact_writer.set_final_result(result)
+
+    # ----------------------------------------------------------------- logging
+
+    def record_status_update(
+        self,
+        *,
+        item_id: str,
+        content: str,
+        is_done: bool,
+        title: Optional[str],
+        border_style: Optional[str],
+        group_id: Optional[str],
+    ) -> None:
+        """Currently unused; maintained for interface compatibility."""
+        with self._lock:
+            self._artifact_writer.record_status_update(
+                item_id=item_id,
+                content=content,
+                is_done=is_done,
+                title=title,
+                border_style=border_style,
+                group_id=group_id,
+            )
+
+    def record_group_start(
+        self,
+        *,
+        group_id: str,
+        title: Optional[str],
+        border_style: Optional[str],
+        iteration: Optional[int] = None,
+    ) -> None:
+        """Record the start of an iteration/group."""
+        with self._lock:
+            self._artifact_writer.record_group_start(
+                group_id=group_id,
+                title=title,
+                border_style=border_style,
+                iteration=iteration,
+            )
+
+    def record_group_end(
+        self,
+        *,
+        group_id: str,
+        is_done: bool = True,
+        title: Optional[str] = None,
+    ) -> None:
+        """Record the end of an iteration/group."""
+        with self._lock:
+            self._artifact_writer.record_group_end(
+                group_id=group_id,
+                is_done=is_done,
+                title=title,
+            )
+
+    def record_agent_step_start(
+        self,
+        *,
+        step_id: str,
+        agent_name: str,
+        span_name: str,
+        iteration: Optional[int],
+        group_id: Optional[str],
+        printer_title: Optional[str],
+    ) -> None:
+        """Capture metadata when an agent step begins."""
+        with self._lock:
+            self._artifact_writer.record_agent_step_start(
+                step_id=step_id,
+                agent_name=agent_name,
+                span_name=span_name,
+                iteration=iteration,
+                group_id=group_id,
+                printer_title=printer_title,
+            )
+
+    def record_agent_step_end(
+        self,
+        *,
+        step_id: str,
+        status: str,
+        duration_seconds: float,
+        error: Optional[str] = None,
+    ) -> None:
+        """Update agent step telemetry on completion."""
+        with self._lock:
+            self._artifact_writer.record_agent_step_end(
+                step_id=step_id,
+                status=status,
+                duration_seconds=duration_seconds,
+                error=error,
+            )
+
+    def record_panel(
+        self,
+        *,
+        title: str,
+        content: str,
+        border_style: Optional[str],
+        iteration: Optional[int],
+        group_id: Optional[str],
+    ) -> None:
+        """Persist panel meta for terminal & HTML artefacts."""
+        with self._lock:
+            # Create panel record
+            from agentz.artifacts.artifact_writer import _utc_timestamp
+            record = PanelRecord(
+                title=title,
+                content=content,
+                border_style=border_style,
+                iteration=iteration,
+                group_id=group_id,
+                recorded_at=_utc_timestamp(),
+            )
+            # Record in both reporters
+            self._artifact_writer.record_panel(
+                title=title,
+                content=content,
+                border_style=border_style,
+                iteration=iteration,
+                group_id=group_id,
+            )
+            self._terminal_writer.record_panel(record)
+
+    # ------------------------------------------------------------- finalisation
+
+    def finalize(self) -> None:
+        """Persist markdown + HTML artefacts."""
+        with self._lock:
+            self._artifact_writer.finalize()
+
+    # ---------------------------------------------------------- terminal flush
+
+    def print_terminal_report(self) -> None:
+        """Stream captured panel content back to the console."""
+        self._terminal_writer.print_terminal_report()
+
+    # ----------------------------------------------------------------- helpers
+
+    def ensure_started(self) -> None:
+        """Raise if reporter not initialised."""
+        self._artifact_writer.ensure_started()
+

agentz/artifacts/terminal_writer.py

@@ -0,0 +1,100 @@
+"""TerminalWriter handles real-time console output and panel display."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from agentz.artifacts.reporter import PanelRecord
+
+
+class TerminalWriter:
+    """Handles real-time terminal display of panels and run information."""
+
+    def __init__(
+        self,
+        *,
+        run_dir: Path,
+        console: Optional[Console] = None,
+    ) -> None:
+        self.run_dir = run_dir
+        self.console = console
+        self._panels: List[PanelRecord] = []
+
+    def record_panel(self, record: PanelRecord) -> None:
+        """Store panel for later terminal display."""
+        self._panels.append(record)
+
+    def print_terminal_report(self) -> None:
+        """Stream captured panel content back to the console."""
+        if not self.console or not self._panels:
+            return
+
+        panels = self._select_terminal_panels()
+        if not panels:
+            return
+
+        self.console.print(
+            Text(f"Run artefacts saved to {self.run_dir}", style="bold cyan")
+        )
+        for record in panels:
+            renderable = self._panel_renderable(record.content)
+            panel = Panel(
+                renderable,
+                title=record.title,
+                border_style=record.border_style or "cyan",
+                padding=(1, 2),
+            )
+            self.console.print(panel)
+
+    # ----------------------------------------------------------------- helpers
+
+    def _select_terminal_panels(self) -> List[PanelRecord]:
+        """Return only final panels for terminal replay."""
+        final_panels = [
+            record for record in self._panels if self._is_final_panel(record)
+        ]
+        if final_panels:
+            return final_panels
+        # Fallback: display only the most recent panel
+        return self._panels[-1:]
+
+    @staticmethod
+    def _is_final_panel(record: PanelRecord) -> bool:
+        """Heuristic for identifying final report panels."""
+        if record.group_id and "final" in record.group_id.lower():
+            return True
+        if record.title:
+            title = record.title.lower()
+            if "final" in title or "writer" in title:
+                return True
+        return False
+
+    def _panel_renderable(self, content: str):
+        """Render Markdown panels using rich, otherwise plain text."""
+        if self._looks_like_markdown(content):
+            return Markdown(content)
+        return Text(content)
+
+    @staticmethod
+    def _looks_like_markdown(content: str) -> bool:
+        """Rudimentary detection of Markdown content."""
+        if not content:
+            return False
+        markdown_patterns = (
+            r"^#{1,6}\s",           # headings
+            r"^\s*[-*+]\s+\S",      # bullet lists
+            r"^\s*\d+\.\s+\S",      # numbered lists
+            r"`{1,3}.+?`{1,3}",     # inline or fenced code
+            r"\*\*.+\*\*",          # bold text
+            r"_{1,2}.+_{1,2}",      # italic/underline emphasis
+        )
+        return any(re.search(pattern, content, re.MULTILINE) for pattern in markdown_patterns)
+

agentz/context/__init__.py

@@ -0,0 +1,6 @@
+"""Context engine for managing conversation state and agent I/O."""
+
+from .conversation import create_conversation_state
+from .context import Context
+
+__all__ = ["Context", "create_conversation_state"]

agentz/context/context.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple, Union
+
+from agentz.context.conversation import BaseIterationRecord, ConversationState, create_conversation_state
+from agentz.profiles.base import Profile, load_all_profiles
+
+
+class Context:
+    """Central coordinator for conversation state and iteration management."""
+
+    # Constants for iteration group IDs
+    ITERATION_GROUP_PREFIX = "iter"
+    FINAL_GROUP_ID = "iter-final"
+
+    def __init__(
+        self,
+        components: Union[ConversationState, List[str]]
+    ) -> None:
+        """Initialize context engine with conversation state.
+
+        Args:
+            components: Either a ConversationState object (for backward compatibility)
+                       or a list of component names to automatically initialize:
+                       - "profiles": loads all profiles via load_all_profiles()
+                       - "states": creates conversation state via create_conversation_state()
+
+        Examples:
+            # Automatic initialization
+            context = Context(["profiles", "states"])
+
+            # Manual initialization (backward compatible)
+            state = create_conversation_state(profiles)
+            context = Context(state)
+        """
+        self.profiles: Optional[Dict[str, Profile]] = None
+
+        if isinstance(components, ConversationState):
+            # Backward compatible: direct state initialization
+            self._state = components
+        elif isinstance(components, list):
+            # Automatic initialization from component list
+            if "profiles" in components:
+                self.profiles = load_all_profiles()
+
+            if "states" in components:
+                if self.profiles is None:
+                    raise ValueError("'states' requires 'profiles' to be initialized first. Include 'profiles' in the component list.")
+                self._state = create_conversation_state(self.profiles)
+            elif not hasattr(self, '_state'):
+                # If no state requested, create empty state
+                self._state = ConversationState()
+        else:
+            raise TypeError(f"components must be ConversationState or list, got {type(components)}")
+
+    @property
+    def state(self) -> ConversationState:
+        return self._state
+
+    def begin_iteration(self) -> Tuple[BaseIterationRecord, str]:
+        """Start a new iteration and return its record with group_id.
+
+        Automatically starts the conversation state timer on first iteration.
+
+        Returns:
+            Tuple of (iteration_record, group_id) where group_id follows the pattern "iter-{index}"
+        """
+        # Lazy timer start: start on first iteration if not already started
+        if self._state.started_at is None:
+            self._state.start_timer()
+
+        iteration = self._state.begin_iteration()
+        group_id = f"{self.ITERATION_GROUP_PREFIX}-{iteration.index}"
+
+        return iteration, group_id
+
+    def mark_iteration_complete(self) -> None:
+        """Mark the current iteration as complete."""
+        self._state.mark_iteration_complete()
+
+    def begin_final_report(self) -> Tuple[None, str]:
+        """Begin final report phase and return group_id.
+
+        Returns:
+            Tuple of (None, group_id) where group_id is the final report group ID
+        """
+        return None, self.FINAL_GROUP_ID
+
+    def mark_final_complete(self) -> None:
+        """Mark final report as complete."""
+        pass  # No state change needed for final report

agentz/context/conversation.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import time
+from typing import Any, ClassVar, Dict, List, Optional, Set, Tuple, Type
+from pydantic import BaseModel, Field, PrivateAttr, ValidationError, create_model
+from agentz.profiles.base import Profile, ToolAgentOutput
+
+
+class BaseIterationRecord(BaseModel):
+    """State captured for a single iteration of the research loop."""
+
+    index: int
+    observation: Optional[str] = None
+    tools: List[ToolAgentOutput] = Field(default_factory=list)
+    payloads: List[Any] = Field(default_factory=list)
+    status: str = Field(default="pending", description="Iteration status: pending or complete")
+    summarized: bool = Field(default=False, description="Whether this iteration has been summarised")
+    _output_union: ClassVar[Optional[Type[BaseModel]]] = None  # type: ignore[var-annotated]
+
+    def mark_complete(self) -> None:
+        self.status = "complete"
+
+    def is_complete(self) -> bool:
+        return self.status == "complete"
+
+    def mark_summarized(self) -> None:
+        self.summarized = True
+
+    def history_block(self) -> str:
+        """Render this iteration as a formatted history block for prompts."""
+        lines: List[str] = [f"[ITERATION {self.index}]"]
+
+        if self.observation:
+            lines.append(f"<thought>\n{self.observation}\n</thought>")
+
+        # Render structured payloads generically
+        if self.payloads:
+            payload_lines = []
+            for payload in self.payloads:
+                if isinstance(payload, BaseModel):
+                    payload_lines.append(payload.model_dump_json(indent=2))
+                else:
+                    payload_lines.append(str(payload))
+            if payload_lines:
+                lines.append(f"<payloads>\n{chr(10).join(payload_lines)}\n</payloads>")
+
+        # Render tool execution results
+        if self.tools:
+            tool_lines = [tool.output for tool in self.tools]
+            lines.append(f"<findings>\n{chr(10).join(tool_lines)}\n</findings>")
+
+        return "\n\n".join(lines).strip()
+
+    def add_payload(self, value: Any) -> BaseModel:
+        expected_union = getattr(self.__class__, "_output_union", None)
+        union_args: Tuple[Type[BaseModel], ...] = ()
+        if expected_union is not None:
+            union_args = getattr(expected_union, "__args__", ()) or ()
+
+        if isinstance(value, BaseModel):
+            payload = value
+            if union_args and not isinstance(payload, union_args):
+                data = payload.model_dump()
+            else:
+                self.payloads.append(payload)
+                return payload
+        elif isinstance(value, dict):
+            data = value
+        else:
+            if union_args:
+                raise TypeError(
+                    f"Payload type {type(value)!r} is incompatible with expected schemas {union_args}"
+                )
+            raise TypeError(f"Payload type {type(value)!r} is not supported")
+
+        if not union_args:
+            raise TypeError("No output schemas are registered for payload coercion")
+
+        errors: List[ValidationError] = []
+        for candidate in union_args:
+            try:
+                payload = candidate.model_validate(data)
+                self.payloads.append(payload)
+                return payload
+            except ValidationError as exc:
+                errors.append(exc)
+
+        raise ValidationError.from_exception_data(
+            title="Iteration payload validation failed",
+            line_errors=[err for exc in errors for err in exc.errors()],
+        ) from (errors[-1] if errors else None)
+
+
+
+class ConversationState(BaseModel):
+    iterations: List[BaseIterationRecord] = Field(default_factory=list)
+    final_report: Optional[str] = None
+    started_at: Optional[float] = None
+    complete: bool = False
+    summary: Optional[str] = None
+    query: Optional[str] = None
+
+    _iteration_model: Type[BaseIterationRecord] = PrivateAttr()
+
+    def start_timer(self) -> None:
+        self.started_at = time.time()
+
+    def elapsed_minutes(self) -> float:
+        if self.started_at is None:
+            return 0.0
+        return (time.time() - self.started_at) / 60
+
+    def begin_iteration(self) -> BaseIterationRecord:
+        iteration = self._iteration_model(index=len(self.iterations) + 1)
+        self.iterations.append(iteration)
+        return iteration
+
+    @property
+    def current_iteration(self) -> BaseIterationRecord:
+        if not self.iterations:
+            raise ValueError("No iteration has been started yet.")
+        return self.iterations[-1]
+
+    def mark_iteration_complete(self) -> None:
+        self.current_iteration.mark_complete()
+
+    def mark_research_complete(self) -> None:
+        self.complete = True
+        self.current_iteration.mark_complete()
+
+    def get_history_blocks(self, include_current: bool, only_unsummarized: bool = False) -> str:
+        relevant = [
+            iteration
+            for iteration in self.iterations
+            if (iteration.is_complete() or include_current and iteration is self.current_iteration)
+            and (not only_unsummarized or not iteration.summarized)
+        ]
+        blocks = [iteration.history_block() for iteration in relevant if iteration.history_block()]
+        return "\n\n".join(blocks).strip()
+
+    def iteration_history(self, include_current: bool = False) -> str:
+        return self.get_history_blocks(include_current, only_unsummarized=False)
+
+    def unsummarized_history(self, include_current: bool = True) -> str:
+        return self.get_history_blocks(include_current, only_unsummarized=True)
+
+    def set_query(self, query: str) -> None:
+        self.query = query
+
+    def record_payload(self, payload: Any) -> BaseModel:
+        """Attach a structured payload to the current iteration."""
+        iteration = self.current_iteration if self.iterations else self.begin_iteration()
+        return iteration.add_payload(payload)
+
+    def all_findings(self) -> List[str]:
+        findings: List[str] = []
+        for iteration in self.iterations:
+            findings.extend(tool.output for tool in iteration.tools)
+        return findings
+
+    def findings_text(self) -> str:
+        findings = self.all_findings()
+        return "\n\n".join(findings).strip() if findings else ""
+
+    def update_summary(self, summary: str) -> None:
+        self.summary = summary
+        for iteration in self.iterations:
+            iteration.mark_summarized()
+
+
+def create_conversation_state(profiles: Dict[str, Profile]) -> "ConversationState":
+    models: List[Type[BaseModel]] = []
+    seen: Set[str] = set()
+
+    for profile in profiles.values():
+        model = getattr(profile, "output_schema", None)
+        if model is not None and isinstance(model, type) and issubclass(model, BaseModel):
+            key = f"{model.__module__}.{model.__qualname__}"
+            if key not in seen:
+                seen.add(key)
+                models.append(model)
+
+    if not models:
+        models = [ToolAgentOutput]
+
+    iterator = iter(models)
+    union_type: Type[BaseModel] = next(iterator)
+    for model in iterator:
+        union_type = union_type | model  # type: ignore[operator]
+
+    field_definitions = {
+        "payloads": (List[union_type], Field(default_factory=list)),
+    }
+
+    iteration_model: Type[BaseIterationRecord] = create_model(
+        "IterationRecord",
+        __base__=BaseIterationRecord,
+        __module__=BaseIterationRecord.__module__,
+        **field_definitions,
+    )
+    iteration_model._output_union = union_type  # type: ignore[attr-defined]
+
+    state = ConversationState()
+    object.__setattr__(state, "_iteration_model", iteration_model)
+    return state