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

aip_agents/context/preparation.py

@@ -0,0 +1,196 @@
+"""Context preparation facade that composes compaction primitives.
+
+Composes #791 (budget/state), #792 (offload/prune/repair),
+and #793 (compaction) into a single pipeline.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.context.budget import (
+    CompactionDecision,
+    ContextBudgetConfig,
+    decide_compaction,
+    estimate_message_token_counts,
+)
+from aip_agents.context.compaction import (
+    CompactionSummary,
+    CompressionResult,
+    ContextCompressor,
+)
+from aip_agents.context.offload import (
+    OffloadedPayloadRef,
+    offload_oversized_payloads,
+    prune_duplicate_tool_outputs,
+    repair_tool_result_pairing,
+)
+from aip_agents.context.state import CompactionState
+
+if TYPE_CHECKING:
+    from aip_agents.context.prompt import PromptBuildContext
+
+
+_SUMMARY_MESSAGE_ROLE = "assistant"
+
+_ADMIN_TAG = "compact_summary"
+
+
+@dataclass(frozen=True)
+class ContextPreparationResult:
+    """Single output of the context preparation pipeline.
+
+    Composes all compaction primitives into one result object
+    so runtime code calls one facade instead of orchestrating
+    budget, offload, prune, repair, and summary individually.
+
+    Attributes:
+        messages: Provider-ready messages after context preparation.
+        prompt_context: Prompt assembly context used to build the system prompt.
+        decision: Budget decision that determined whether compaction was needed.
+        state: Safe compaction metadata for logging and observability.
+        offloaded_refs: Payload references produced by lossless offloading.
+        summary: Reference-only compaction summary inserted into context, if any.
+    """
+
+    messages: list[Any]
+    prompt_context: PromptBuildContext | None = None
+    decision: CompactionDecision | None = None
+    state: CompactionState | None = None
+    offloaded_refs: tuple[OffloadedPayloadRef, ...] = field(default_factory=tuple)
+    summary: CompactionSummary | None = None
+
+
+def _build_summary_message(summary: CompactionSummary) -> dict[str, Any]:
+    """Build a replacement message from a compaction summary."""
+    return {
+        "role": _SUMMARY_MESSAGE_ROLE,
+        "content": f"[Previous conversation context summarized: {summary.body}]",
+        "type": _ADMIN_TAG,
+        "summary_id": summary.summary_id,
+    }
+
+
+def prepare_context(
+    messages: Sequence[Any],
+    *,
+    config: ContextBudgetConfig | None = None,
+    backend: Any | None = None,
+    model_context_tokens: int | None = None,
+    summarizer: Any | None = None,
+    previous_summary: CompactionSummary | None = None,
+    focus_topic: str | None = None,
+    preserve_topic: str | None = None,
+    provider_overflow: bool = False,
+) -> ContextPreparationResult:
+    """Run the full context preparation pipeline.
+
+    Args:
+        messages: Full message sequence to prepare for model invocation.
+        config: Budget configuration for compaction decisions.
+        backend: Optional backend for offloading oversized payloads.
+        model_context_tokens: Provider model context window size, if known.
+        summarizer: Optional external summarizer client.
+        previous_summary: Previous compaction summary for incremental update.
+        focus_topic: Optional focus topic for manual/guided compaction.
+        preserve_topic: Alias for focus_topic (overrides focus_topic when set).
+        provider_overflow: If True, force compaction for provider-overflow retry
+            even when the local estimator is below the normal threshold.
+
+    Returns:
+        ContextPreparationResult with processed messages and metadata.
+
+    Order of operations:
+    1. Budget decision (estimate tokens, decide if compaction needed)
+    2. Lossless offload (oversized payloads to backend, if backend provided)
+    3. Prune duplicate tool outputs
+    4. Repair tool-result pairing
+    5. Generate compaction summary (if should_compact)
+    6. Assemble final messages (head + summary + tail)
+    """
+    cfg = config or ContextBudgetConfig()
+
+    effective_focus_topic = preserve_topic if preserve_topic is not None else focus_topic
+
+    # 1. Budget decision
+    token_counts = list(estimate_message_token_counts(messages))
+    estimated_prompt_tokens = sum(token_counts)
+
+    decision = decide_compaction(
+        messages,
+        config=cfg,
+        model_context_tokens=model_context_tokens,
+        provider_overflow=provider_overflow,
+    )
+
+    # 2-4: Always apply offload/prune/repair
+    transformed = list(messages)
+
+    offloaded_refs: tuple[OffloadedPayloadRef, ...] = ()
+    if backend is not None:
+        transformed, offloaded_refs = offload_oversized_payloads(
+            transformed,
+            backend=backend,
+        )
+
+    protected_tail_start = (
+        decision.summary_insertion_point.protected_tail_start_index
+        if decision.summary_insertion_point is not None
+        else len(transformed)
+    )
+    transformed = prune_duplicate_tool_outputs(
+        transformed,
+        protected_tail_start_index=protected_tail_start,
+    )
+    transformed = repair_tool_result_pairing(transformed)
+
+    # 5-6: Compaction summary + assembly
+    summary: CompactionSummary | None = None
+    state = CompactionState()
+
+    if decision.should_compact:
+        compressor = ContextCompressor(summarizer=summarizer)
+        try:
+            compression_result: CompressionResult = compressor.compress(
+                transformed,
+                focus_topic=decision.focus_topic or effective_focus_topic,
+                previous_summary=previous_summary,
+            )
+            summary = compression_result.summary
+
+            sip = decision.summary_insertion_point
+            if sip is not None:
+                summary_message = _build_summary_message(summary)
+                head = list(transformed[: sip.replace_start_index])
+                tail = list(transformed[sip.replace_end_index :])
+                transformed = head + [summary_message] + tail
+
+            post_compact_tokens = sum(estimate_message_token_counts(transformed))
+            state = CompactionState(
+                compaction_count=1,
+                last_summary_status="succeeded",
+                offloaded_ref_count=len(offloaded_refs),
+                estimated_token_savings=estimated_prompt_tokens - post_compact_tokens,
+                last_reason=decision.reason,
+            )
+        except Exception as exc:
+            state = CompactionState(
+                compaction_count=1,
+                last_summary_status="failed",
+                offloaded_ref_count=len(offloaded_refs),
+                last_reason=decision.reason,
+                last_error_code=str(type(exc).__name__),
+            )
+
+    return ContextPreparationResult(
+        messages=transformed,
+        decision=decision,
+        state=state,
+        offloaded_refs=offloaded_refs,
+        summary=summary,
+    )

aip_agents/context/prompt.py

@@ -0,0 +1,61 @@
+"""Prompt assembly utilities for agent system instructions.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PromptBuildContext:
+    """Typed context for deterministic system prompt assembly.
+
+    The field order encodes the canonical layer order. Empty or None values are
+    skipped during rendering.
+    """
+
+    base_instruction: str
+    date_time_context: str | None = None
+    runtime_platform_hints: str | None = None
+    durable_memory_guidance: str | None = None
+    session_recall_guidance: str | None = None
+    project_context: str | None = None
+    compaction_summary: str | None = None
+    model_steering: str | None = None
+    middleware_prompts: tuple[str, ...] = ()
+
+
+def build_system_prompt(context: PromptBuildContext) -> str:
+    """Build a system prompt from ordered context layers.
+
+    Args:
+        context: Prompt context containing ordered optional layers.
+
+    Returns:
+        Combined system prompt with non-empty layers joined by double newlines.
+    """
+    parts: list[str] = []
+
+    for layer in (
+        context.date_time_context,
+        context.base_instruction,
+        context.runtime_platform_hints,
+        context.durable_memory_guidance,
+        context.session_recall_guidance,
+        context.project_context,
+        context.compaction_summary,
+        context.model_steering,
+    ):
+        normalized = layer.strip() if isinstance(layer, str) else layer
+        if normalized:
+            parts.append(normalized)
+
+    for middleware_prompt in context.middleware_prompts:
+        normalized = middleware_prompt.strip() if isinstance(middleware_prompt, str) else middleware_prompt
+        if normalized:
+            parts.append(normalized)
+
+    return "\n\n".join(parts)

aip_agents/context/runtime.py

@@ -0,0 +1,149 @@
+"""Runtime integration helpers for context compaction.
+
+Provides overflow detection, session recall derivation,
+and compact-and-retry orchestration for the agent loop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Sequence
+from typing import TYPE_CHECKING, Any, Protocol
+
+from aip_agents.context.session_recall import (
+    SessionRecallSnapshot,
+)
+
+if TYPE_CHECKING:
+    from aip_agents.context.preparation import ContextPreparationResult
+
+
+class ModelInvoke(Protocol):
+    """Async model invocation callable used by compact_and_retry()."""
+
+    def __call__(self, messages: Sequence[Any]) -> Awaitable[Any]:
+        """Invoke a model with prepared messages."""
+
+
+class PrepareContext(Protocol):
+    """Callable shape for context preparation."""
+
+    def __call__(
+        self,
+        messages: Sequence[Any],
+        *,
+        focus_topic: str | None = None,
+        provider_overflow: bool = False,
+        **kwargs: Any,
+    ) -> ContextPreparationResult:
+        """Prepare messages for model invocation."""
+
+
+_OVERFLOW_KEYWORDS = [
+    "context_length_exceeded",
+    "maximum context length",
+    "max tokens exceeded",
+    "context window full",
+    "too many tokens",
+    "token limit reached",
+]
+
+
+def detect_context_overflow(error: Exception | str) -> bool:
+    """Return True when an error appears to be a context-window overflow.
+
+    Args:
+        error: Exception or error message string to classify.
+
+    Returns:
+        True if the error matches known overflow patterns.
+    """
+    error_text = str(error).lower()
+    return any(keyword in error_text for keyword in _OVERFLOW_KEYWORDS)
+
+
+def derive_session_recall(
+    messages: Sequence[dict[str, Any]],
+    tool_metadata: dict[str, Any] | None = None,
+) -> SessionRecallSnapshot:
+    """Derive a SessionRecallSnapshot from current loop state.
+
+    Args:
+        messages: Current message sequence in the agent loop.
+        tool_metadata: Optional metadata about recent tool activity.
+
+    Returns:
+        Populated SessionRecallSnapshot with supported fields derived from state.
+    """
+    active_task = _derive_active_task(messages)
+    changed_files = _derive_changed_files(tool_metadata)
+    return SessionRecallSnapshot(
+        active_task=active_task,
+        recent_decisions=(),
+        changed_files=changed_files,
+        blockers=(),
+        handoff_summary=None,
+        stale=False,
+    )
+
+
+def _derive_active_task(messages: Sequence[dict[str, Any]]) -> str | None:
+    if not messages:
+        return None
+    for message in reversed(messages):
+        role = message.get("role", "")
+        if role not in ("user", "human"):
+            continue
+        content = message.get("content", "")
+        if isinstance(content, str) and content.strip():
+            return content.strip()[:200]
+    return None
+
+
+def _derive_changed_files(
+    tool_metadata: dict[str, Any] | None,
+) -> tuple[str, ...]:
+    if not tool_metadata:
+        return ()
+    files = tool_metadata.get("changed_files")
+    if isinstance(files, list | tuple):
+        return tuple(str(f) for f in files if f)
+    return ()
+
+
+async def compact_and_retry(
+    messages: Sequence[dict[str, Any]],
+    model_invoke: ModelInvoke,
+    *,
+    prepare_context: PrepareContext,
+    recall: SessionRecallSnapshot | None = None,
+) -> tuple[Any, ContextPreparationResult | None]:
+    """Run prepare_context and invoke the model, with one overflow retry.
+
+    Args:
+        messages: Current message sequence.
+        model_invoke: Async callable that invokes the model.
+        prepare_context: The prepare_context function from preparation module.
+        recall: Optional SessionRecallSnapshot for prompt context.
+
+    Returns:
+        Tuple of (model_output, preparation_result).
+    """
+    prep_result = prepare_context(
+        messages,
+        focus_topic=recall.active_task if recall else None,
+    )
+    first_messages = prep_result.messages if prep_result is not None else list(messages)
+
+    try:
+        output = await model_invoke(first_messages)
+        return output, prep_result
+    except Exception as exc:
+        if detect_context_overflow(exc):
+            retry_result = prepare_context(
+                first_messages,
+                focus_topic=recall.active_task if recall else None,
+                provider_overflow=True,
+            )
+            retry_output = await model_invoke(retry_result.messages)
+            return retry_output, retry_result
+        raise

aip_agents/context/session_recall.py

@@ -0,0 +1,69 @@
+"""Session recall seam contracts.
+
+This module defines lightweight contracts for short-lived session/task recall
+without coupling them to durable memory persistence.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class SessionRecallSnapshot:
+    """Snapshot of short-lived task/session state.
+
+    This snapshot is intentionally scoped to active work context and should not
+    be treated as durable memory by default.
+    """
+
+    active_task: str | None = None
+    recent_decisions: tuple[str, ...] = field(default_factory=tuple)
+    changed_files: tuple[str, ...] = field(default_factory=tuple)
+    blockers: tuple[str, ...] = field(default_factory=tuple)
+    handoff_summary: str | None = None
+    stale: bool = False
+
+
+def build_session_recall_guidance(snapshot: SessionRecallSnapshot | None) -> str | None:
+    """Render session recall guidance text from a snapshot.
+
+    Args:
+        snapshot: Optional session recall snapshot.
+
+    Returns:
+        A guidance block describing short-lived task/session context, or None
+        when no snapshot is available.
+    """
+    if snapshot is None:
+        return None
+
+    active_task = snapshot.active_task.strip() if snapshot.active_task else None
+    handoff_summary = snapshot.handoff_summary.strip() if snapshot.handoff_summary else None
+    recent_decisions = tuple(d.strip() for d in snapshot.recent_decisions if d.strip())
+    changed_files = tuple(f.strip() for f in snapshot.changed_files if f.strip())
+    blockers = tuple(b.strip() for b in snapshot.blockers if b.strip())
+
+    lines = ["Session Recall Snapshot:"]
+    if active_task:
+        lines.append(f"- Active task: {active_task}")
+    if recent_decisions:
+        lines.append("- Recent decisions:")
+        lines.extend(f"  - {decision}" for decision in recent_decisions)
+    if changed_files:
+        lines.append("- Changed files:")
+        lines.extend(f"  - {path}" for path in changed_files)
+    if blockers:
+        lines.append("- Blockers:")
+        lines.extend(f"  - {blocker}" for blocker in blockers)
+    if handoff_summary:
+        lines.append(f"- Handoff summary: {handoff_summary}")
+    if snapshot.stale:
+        lines.append("- Recall freshness: stale")
+
+    if len(lines) == 1:
+        return None
+    return "\n".join(lines)

aip_agents/context/state.py

@@ -0,0 +1,48 @@
+"""State contracts for context compaction decisions.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class SummaryInsertionPoint:
+    """Index metadata describing where a reference summary can be inserted.
+
+    Attributes:
+        protected_head_indexes: Initial message indexes preserved unchanged.
+        protected_tail_start_index: First recent-tail message index preserved unchanged.
+        replace_start_index: First message index replaced by the reference summary.
+        replace_end_index: Last message index replaced by the reference summary.
+    """
+
+    protected_head_indexes: tuple[int, ...]
+    protected_tail_start_index: int
+    replace_start_index: int
+    replace_end_index: int
+
+
+@dataclass(frozen=True)
+class CompactionState:
+    """Observed compaction metadata tracked outside mutable agent state.
+
+    Attributes:
+        compaction_count: Number of compaction attempts observed for the current scope.
+        last_summary_status: Outcome of the latest summary attempt.
+        offloaded_ref_count: Number of payload references produced by offloading.
+        estimated_token_savings: Estimated token reduction from the latest compaction.
+        last_reason: Stable reason code from the latest compaction decision.
+        last_error_code: Safe error code for the latest failed compaction step.
+    """
+
+    compaction_count: int = 0
+    last_summary_status: Literal["none", "succeeded", "failed", "skipped"] = "none"
+    offloaded_ref_count: int = 0
+    estimated_token_savings: int | None = None
+    last_reason: str | None = None
+    last_error_code: str | None = None

aip_agents/context/utils.py

@@ -0,0 +1,44 @@
+"""Shared context utilities for token estimation, redaction, and safe preview.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def estimate_tokens(text: str, chars_per_token: int = 4) -> int:
+    """Estimate token count for a text string."""
+    if not text:
+        return 0
+    safe_ratio = max(chars_per_token, 1)
+    return max(1, (len(text) + safe_ratio - 1) // safe_ratio)
+
+
+_secret_kv_pattern = re.compile(r"(?i)(api[_-]?key|token|password|secret)\s*[:=]\s*[^\s]+")
+_long_base64_pattern = re.compile(r"(?=[^+/=]*[+/=])[A-Za-z0-9+/=]{120,}")
+_auth_header_pattern = re.compile(r"(?i)(Authorization|X-API-Key|Cookie)\s*:\s*[^\n]+")
+_credential_query_pattern = re.compile(r"(?i)(api_key|token|secret|key|password|signature)=[^\s&]+")
+_signed_url_pattern = re.compile(r"(?i)\b(x-amz-signature|sig|signature)\s*=\s*[^\s&]+")
+
+
+def redact_sensitive(text: str) -> tuple[str, bool]:
+    """Redact sensitive content from text."""
+    redacted = _secret_kv_pattern.sub(lambda m: f"{m.group(1)}=[REDACTED]", text)
+    redacted = _long_base64_pattern.sub("[BASE64_REDACTED]", redacted)
+    redacted = _auth_header_pattern.sub(r"\1: [REDACTED]", redacted)
+    redacted = _credential_query_pattern.sub(r"\1=[REDACTED]", redacted)
+    redacted = _signed_url_pattern.sub(lambda m: f"{m.group(1)}=[REDACTED]", redacted)
+    redaction_applied = redacted != text
+    return redacted, redaction_applied
+
+
+def safe_preview(content: str, *, max_chars: int) -> tuple[str, bool]:
+    """Create a redacted preview of content."""
+    redacted, redaction_applied = redact_sensitive(content)
+    clipped = redacted[:max_chars]
+    if len(redacted) > max_chars:
+        clipped += "..."
+    return clipped, redaction_applied