aip-agents-binary 0.5.20__py3-none-any.whl

aip_agents/utils/metadata/activity_narrative/constants.py

@@ -0,0 +1,51 @@
+"""Shared constants for activity narrative generation.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from aip_agents.schema.hitl import ApprovalDecisionType
+
+SYSTEM_PROMPT = """You summarize agent activity for operator dashboards.
+- Describe what happened in short, factual sentences that highlight the most relevant arguments or outputs.
+- Do not mention execution time, latency, token counts, or other operational metrics.
+- Never mention internal IDs, UUIDs, or opaque agent identifiers. Prefer tool/delegate display names.
+- Mention errors only when an actual error is present; never say that no errors occurred.
+- Summaries should avoid quoting raw JSON unless necessary."""
+
+DELEGATE_PREFIX = "delegate_to_"
+OUTPUT_EXCERPT_MAX_CHARS = 512  # no specific reason, just a guess
+
+HITL_PENDING_TITLE = "**Awaiting Review**"
+HITL_PENDING_DESCRIPTION = (
+    "This action requires human verification. The agent is paused until a reviewer approves or rejects the request."
+)
+HITL_DECISION_MESSAGES: dict[ApprovalDecisionType, tuple[str, str]] = {
+    ApprovalDecisionType.APPROVED: (
+        "**Request Approved**",
+        "The reviewer approved this action. Execution will continue as planned.",
+    ),
+    ApprovalDecisionType.REJECTED: (
+        "**Request Rejected**",
+        "The reviewer rejected this action. The workflow moves to the next applicable step.",
+    ),
+    ApprovalDecisionType.SKIPPED: (
+        "**Request Skipped**",
+        "The reviewer skipped this action. Execution proceeds without performing it.",
+    ),
+    ApprovalDecisionType.TIMEOUT_SKIP: (
+        "**Request Timed Out**",
+        "No decision arrived before the timeout so the request was skipped automatically.",
+    ),
+}
+
+__all__ = [
+    "SYSTEM_PROMPT",
+    "DELEGATE_PREFIX",
+    "OUTPUT_EXCERPT_MAX_CHARS",
+    "HITL_PENDING_TITLE",
+    "HITL_PENDING_DESCRIPTION",
+    "HITL_DECISION_MESSAGES",
+]

aip_agents/utils/metadata/activity_narrative/context.py

@@ -0,0 +1,49 @@
+"""Context objects describing activity-builder inputs.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from aip_agents.schema.hitl import ApprovalDecisionType, HitlMetadata
+
+
+class ActivityPhase(StrEnum):
+    """Lifecycle phases for tool, delegate, and HITL events."""
+
+    TOOL_START = "tool_start"
+    TOOL_END = "tool_end"
+    DELEGATE_START = "delegate_start"
+    DELEGATE_END = "delegate_end"
+    HITL_PENDING = "hitl_pending"
+    HITL_RESOLVED = "hitl_resolved"
+
+
+JSONScalar = str | int | float | bool | None
+JSONValue = JSONScalar | dict[str, "JSONValue"] | list["JSONValue"]
+
+
+@dataclass
+class ActivityContext:
+    """Structured representation of an activity event."""
+
+    phase: ActivityPhase
+    agent_name: str | None
+    subject_name: str | None
+    sanitized_args: dict[str, JSONValue] | None
+    sanitized_output: JSONValue | None
+    arguments_excerpt: str | None
+    output_excerpt: str | None
+    error_excerpt: str | None
+    step_id: str | None = None
+    is_delegate: bool = False
+    hitl_metadata: HitlMetadata | None = None
+    hitl_decision: ApprovalDecisionType | None = None
+    default_heading: str | None = None
+
+
+__all__ = ["ActivityContext", "ActivityPhase"]

aip_agents/utils/metadata/activity_narrative/formatters.py

@@ -0,0 +1,230 @@
+"""Formatting and sanitization helpers for activity narratives.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.metadata.activity_narrative.constants import OUTPUT_EXCERPT_MAX_CHARS
+
+logger = get_logger(__name__)
+
+JSONScalar = str | int | float | bool | None
+JSONValue = JSONScalar | dict[str, "JSONValue"] | list["JSONValue"]
+
+
+class SensitiveInfoFilter:
+    """Redact sensitive argument/output values before rendering or sending to LLMs."""
+
+    REDACTED = "<redacted>"
+    SENSITIVE_KEY_PATTERNS = (
+        "token",
+        "secret",
+        "password",
+        "api_key",
+        "apikey",
+        "credential",
+        "auth",
+    )
+
+    def __init__(self) -> None:
+        """Initialize the sensitive info filter."""
+        self._logger = logger
+
+    def sanitize(
+        self,
+        args: dict[str, JSONValue] | None,
+        output: JSONValue | None,
+        tool_sanitizer: Callable[[dict[str, JSONValue] | None, JSONValue | None], dict[str, JSONValue]] | None = None,
+    ) -> tuple[dict[str, JSONValue] | None, JSONValue | None]:
+        """Return sanitized arguments/output with optional tool overrides.
+
+        Args:
+            args: Raw arguments dictionary emitted by the tool.
+            output: Raw tool output which may be nested JSON.
+            tool_sanitizer: Optional callable that can override sanitized values.
+
+        Returns:
+            tuple: Sanitized args and output payloads.
+        """
+        sanitized_args = self._sanitize_structure(args)
+        sanitized_output = self._sanitize_structure(output)
+
+        if callable(tool_sanitizer):
+            try:
+                replacement = tool_sanitizer(args, output) or {}
+                if isinstance(replacement, dict):
+                    if "args" in replacement:
+                        sanitized_args = replacement.get("args")
+                    if "output" in replacement:
+                        sanitized_output = replacement.get("output")
+            except Exception as exc:  # pragma: no cover - defensive
+                self._logger.warning("activity sanitizer hook failed: %s", exc)
+
+        return sanitized_args, sanitized_output
+
+    def _sanitize_structure(self, value: JSONValue) -> JSONValue:
+        """Recursively sanitize nested structures by redacting sensitive data.
+
+        Args:
+            value: Arbitrary nested JSON-esque payload.
+
+        Returns:
+            JSONValue: Sanitized structure with sensitive values redacted.
+        """
+        if value is None:
+            return None
+        if isinstance(value, dict):
+            sanitized: dict[str, JSONValue] = {}
+            for key, val in value.items():
+                sanitized[key] = self.REDACTED if self._is_sensitive_key(key) else self._sanitize_structure(val)
+            return sanitized
+        if isinstance(value, list):
+            return [self._sanitize_structure(item) for item in value]
+        if isinstance(value, str):
+            return self._sanitize_string(value)
+        return value
+
+    def _sanitize_string(self, value: str) -> str:
+        """Sanitize a string value by checking if it looks like a secret.
+
+        Args:
+            value: Raw string to inspect.
+
+        Returns:
+            str: Either the original trimmed string or ``<redacted>``.
+        """
+        stripped = value.strip()
+        if self._looks_like_secret(stripped):
+            return self.REDACTED
+        return stripped
+
+    def _is_sensitive_key(self, key: str) -> bool:
+        """Check if a key name indicates sensitive data.
+
+        Args:
+            key: Key name from the argument/output structure.
+
+        Returns:
+            bool: True when the key hints at credentials or tokens.
+        """
+        lowered = key.lower()
+        return any(pattern in lowered for pattern in self.SENSITIVE_KEY_PATTERNS)
+
+    def _looks_like_secret(self, value: str) -> bool:
+        """Check if a string value looks like a secret or API key.
+
+        Args:
+            value: Text candidate to evaluate.
+
+        Returns:
+            bool: True when the string matches secret heuristics.
+        """
+        if not value:
+            return False
+        if value.startswith("sk-") or value.startswith("rk-"):
+            return True
+        if len(value) >= 64 and re.fullmatch(r"[A-Za-z0-9+/=_-]+", value):
+            return True
+        return False
+
+
+class ArgsFormatter:
+    """Simple formatter that surfaces at most two argument key/value pairs."""
+
+    def format(self, args: dict[str, JSONValue] | None) -> str | None:
+        """Format tool arguments into a short excerpt.
+
+        Args:
+            args: Tool arguments dictionary.
+
+        Returns:
+            str | None: Concise representation of up to two key/value pairs.
+        """
+        if not args:
+            return None
+        parts: list[str] = []
+        for key in sorted(args.keys()):
+            if len(parts) >= 2:
+                break
+            value = self._stringify(args[key])
+            if value:
+                parts.append(f"{key}: {value}")
+        return "; ".join(parts) if parts else None
+
+    def _stringify(self, value: JSONValue) -> str | None:
+        """Convert a value to a string representation.
+
+        Args:
+            value: Value lifted from the arguments dictionary.
+
+        Returns:
+            str | None: Stringified value truncated when overly long.
+        """
+        if value is None:
+            return None
+        if isinstance(value, str):
+            value = value.strip()
+            return value or None
+        try:
+            text = json.dumps(value, ensure_ascii=False)
+        except Exception:
+            text = str(value)
+        text = text.strip()
+        if not text:
+            return None
+        if len(text) > 200:
+            return text[:199].rstrip() + "…"
+        return text
+
+
+class OutputFormatter:
+    """Lightweight formatter that truncates serialized output."""
+
+    def format(self, output: JSONValue | None) -> str | None:
+        """Format tool output into a readable excerpt.
+
+        Args:
+            output: Raw tool output.
+
+        Returns:
+            str | None: Truncated representation suitable for logs.
+        """
+        if output is None:
+            return None
+        if isinstance(output, str):
+            text = output.strip()
+            if not text:
+                return None
+            return self._truncate(text)
+        try:
+            text = json.dumps(output, ensure_ascii=False)
+        except Exception:
+            text = str(output)
+        text = text.strip()
+        if not text:
+            return None
+        return self._truncate(text)
+
+    def _truncate(self, text: str, limit: int = OUTPUT_EXCERPT_MAX_CHARS) -> str:
+        """Truncate text to a maximum length with ellipsis.
+
+        Args:
+            text: Text value to truncate.
+            limit: Maximum permitted character count.
+
+        Returns:
+            str: Text clipped to the configured limit.
+        """
+        if len(text) <= limit:
+            return text
+        return text[: limit - 1].rstrip() + "…"
+
+
+__all__ = ["ArgsFormatter", "OutputFormatter", "SensitiveInfoFilter"]

aip_agents/utils/metadata/activity_narrative/utils.py

@@ -0,0 +1,35 @@
+"""Helper utilities used across the activity narrative package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import re
+
+from aip_agents.utils.metadata.activity_narrative.constants import DELEGATE_PREFIX
+
+
+def _format_tool_or_subagent_name(name: str, remove_delegate_prefix: bool = False) -> str:
+    """Format tool/agent names to 'Camel Case' consistently.
+
+    Args:
+        name: Raw tool or sub-agent identifier.
+        remove_delegate_prefix: Whether to strip the ``delegate::`` prefix before formatting.
+
+    Returns:
+        str: Display-friendly tool or agent name.
+    """
+    clean_name = name.replace(DELEGATE_PREFIX, "") if remove_delegate_prefix else name
+    s = clean_name.replace("_", " ")
+
+    if s == s.lower():
+        return " ".join(w.capitalize() for w in s.split())
+
+    s = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", s)
+    s = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", " ", s)
+    return " ".join(word if word.isupper() else (word[:1].upper() + word[1:].lower()) for word in s.split())
+
+
+__all__ = ["_format_tool_or_subagent_name"]

aip_agents/utils/metadata/schemas/__init__.py

@@ -0,0 +1,16 @@
+"""Metadata schemas module.
+
+This module contains Pydantic schemas for metadata objects.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.utils.metadata.schemas.activity_schema import Activity, ActivityDataType
+from aip_agents.utils.metadata.schemas.thinking_schema import Thinking
+
+__all__ = [
+    "Activity",
+    "ActivityDataType",
+    "Thinking",
+]

aip_agents/utils/metadata/schemas/activity_schema.py

@@ -0,0 +1,29 @@
+"""Pydantic schemas for activity metadata.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class ActivityDataType(StrEnum):
+    """Enumeration of activity data types."""
+
+    ACTIVITY = "activity"
+
+
+class Activity(BaseModel):
+    """Schema for activity info payload.
+
+    Fields:
+    - data_type: always "activity"
+    - id: UUID string identifying this activity event
+    - data_value: JSON string with additional info (e.g., {"message": "..."})
+    """
+
+    data_type: ActivityDataType = Field(default=ActivityDataType.ACTIVITY)
+    id: str
+    data_value: str

aip_agents/utils/metadata/schemas/thinking_schema.py

@@ -0,0 +1,31 @@
+"""Pydantic schemas for thinking metadata.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class ThinkingDataType(StrEnum):
+    """Enum for thinking data types."""
+
+    THINKING = "thinking"
+    THINKING_START = "thinking_start"
+    THINKING_END = "thinking_end"
+
+
+class Thinking(BaseModel):
+    """Schema for thinking info payload.
+
+    Fields:
+    - data_type: type of thinking event
+    - id: UUID string identifying this thinking event
+    - data_value: JSON string with additional info (e.g., {"message": "..."})
+    """
+
+    data_type: ThinkingDataType = Field(default=ThinkingDataType.THINKING)
+    id: str
+    data_value: str

aip_agents/utils/metadata/thinking_metadata_helper.py

@@ -0,0 +1,38 @@
+"""Thinking metadata helper utilities.
+
+Provides helpers to build thinking messages.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.utils.metadata.schemas.thinking_schema import Thinking, ThinkingDataType
+
+
+def _create_thinking_info(
+    message: str,
+    top_level_id: str = "default_thinking_id",
+    data_type: ThinkingDataType = "thinking",
+) -> dict[str, str]:
+    r"""Create thinking info payload with a customizable ID, data_type, and message.
+
+    Args:
+        message: The message content for the thinking info.
+        top_level_id: The ID for the thinking info. Defaults to "default_thinking_id".
+        data_type: The type of the data. Defaults to "thinking".
+
+    Returns a dict with top-level id and data_value as JSON string:
+      {
+        "data_type": "thinking",
+        "id": "<id>",
+        "data_value": "**title**\n\n..."
+      }
+    """
+    thinking = Thinking(data_type=data_type, id=top_level_id, data_value=message)
+    return thinking.model_dump()
+
+
+# Exported default/terminal thinking info
+FINAL_THINKING_INFO = _create_thinking_info(
+    "**All process has finished**\n\nThe tasks have been finished.", "default_thinking_id"
+)