attune-ai 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

attune/memory/short_term/working.py

@@ -0,0 +1,252 @@
+"""Working memory operations - stash and retrieve.
+
+This module provides the primary interface for storing and retrieving
+agent working memory:
+- Stash: Store data with optional TTL and metadata
+- Retrieve: Get data by key
+- Clear: Remove all working memory for an agent
+
+Key Prefix: PREFIX_WORKING = "empathy:working:"
+
+Classes:
+    WorkingMemory: Core stash/retrieve operations
+
+Example:
+    >>> from attune.memory.short_term.working import WorkingMemory
+    >>> from attune.memory.types import AgentCredentials, AccessTier
+    >>> # Typically composed into RedisShortTermMemory facade
+    >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+    >>> working = WorkingMemory(base_ops, security_sanitizer)
+    >>> working.stash("key", {"data": 123}, creds)
+    >>> result = working.retrieve("key", creds)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+    TTLStrategy,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+    from attune.memory.short_term.security import DataSanitizer
+
+logger = structlog.get_logger(__name__)
+
+
+class WorkingMemory:
+    """Working memory operations for agent data storage.
+
+    Provides stash (store) and retrieve operations with:
+    - Access control based on agent credentials
+    - Optional PII scrubbing and secrets detection
+    - Configurable TTL strategies
+    - Agent-scoped key namespacing
+
+    The class is designed to be composed with BaseOperations and
+    DataSanitizer for dependency injection.
+
+    Attributes:
+        PREFIX_WORKING: Key prefix for working memory namespace
+
+    Example:
+        >>> working = WorkingMemory(base_ops, sanitizer)
+        >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+        >>> working.stash("analysis", {"score": 95}, creds)
+        True
+        >>> working.retrieve("analysis", creds)
+        {'score': 95}
+    """
+
+    PREFIX_WORKING = "empathy:working:"
+
+    def __init__(
+        self,
+        base: BaseOperations,
+        sanitizer: DataSanitizer | None = None,
+    ) -> None:
+        """Initialize working memory operations.
+
+        Args:
+            base: BaseOperations instance for storage access
+            sanitizer: Optional DataSanitizer for PII/secrets handling
+        """
+        self._base = base
+        self._sanitizer = sanitizer
+
+    def stash(
+        self,
+        key: str,
+        data: Any,
+        credentials: AgentCredentials,
+        ttl: TTLStrategy = TTLStrategy.WORKING_RESULTS,
+        skip_sanitization: bool = False,
+    ) -> bool:
+        """Stash data in short-term memory.
+
+        Stores data with automatic TTL expiration and optional
+        security sanitization (PII scrubbing, secrets detection).
+
+        Args:
+            key: Unique key for the data
+            data: Data to store (will be JSON serialized)
+            credentials: Agent credentials for access control
+            ttl: Time-to-live strategy (default: WORKING_RESULTS)
+            skip_sanitization: Skip PII scrubbing and secrets detection
+
+        Returns:
+            True if successful
+
+        Raises:
+            ValueError: If key is empty or invalid
+            PermissionError: If credentials lack write access
+            SecurityError: If secrets are detected (when enabled)
+
+        Note:
+            PII (emails, SSNs, etc.) is automatically scrubbed unless
+            skip_sanitization=True. Secrets block storage by default.
+
+        Example:
+            >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+            >>> working.stash("analysis_v1", {"findings": [...]}, creds)
+            True
+        """
+        # Pattern 1: String ID validation
+        if not key or not key.strip():
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
+
+        if not credentials.can_stage():
+            raise PermissionError(
+                f"Agent {credentials.agent_id} (Tier {credentials.tier.name}) "
+                "cannot write to memory. Requires CONTRIBUTOR or higher.",
+            )
+
+        # Sanitize data (PII scrubbing + secrets detection)
+        pii_count = 0
+        if not skip_sanitization and self._sanitizer is not None:
+            data, pii_count = self._sanitizer.sanitize(data)
+            if pii_count > 0:
+                logger.info(
+                    "stash_pii_scrubbed",
+                    key=key,
+                    agent_id=credentials.agent_id,
+                    pii_count=pii_count,
+                )
+
+        full_key = f"{self.PREFIX_WORKING}{credentials.agent_id}:{key}"
+        payload = {
+            "data": data,
+            "agent_id": credentials.agent_id,
+            "stashed_at": datetime.now().isoformat(),
+        }
+        return self._base._set(full_key, json.dumps(payload), ttl.value)
+
+    def retrieve(
+        self,
+        key: str,
+        credentials: AgentCredentials,
+        agent_id: str | None = None,
+    ) -> Any | None:
+        """Retrieve data from short-term memory.
+
+        Args:
+            key: Key to retrieve
+            credentials: Agent credentials
+            agent_id: Owner agent ID (defaults to credentials agent)
+
+        Returns:
+            Retrieved data or None if not found
+
+        Raises:
+            ValueError: If key is empty or invalid
+
+        Example:
+            >>> data = working.retrieve("analysis_v1", creds)
+            >>> if data:
+            ...     print(f"Found: {data}")
+        """
+        # Pattern 1: String ID validation
+        if not key or not key.strip():
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
+
+        owner = agent_id or credentials.agent_id
+        full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
+        raw = self._base._get(full_key)
+
+        if raw is None:
+            return None
+
+        payload = json.loads(raw)
+        return payload.get("data")
+
+    def clear(self, credentials: AgentCredentials) -> int:
+        """Clear all working memory for an agent.
+
+        Removes all keys in the working memory namespace for
+        the given agent.
+
+        Args:
+            credentials: Agent credentials (must own the memory or be Steward)
+
+        Returns:
+            Number of keys deleted
+
+        Example:
+            >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+            >>> deleted = working.clear(creds)
+            >>> print(f"Deleted {deleted} keys")
+        """
+        pattern = f"{self.PREFIX_WORKING}{credentials.agent_id}:*"
+        keys = self._base._keys(pattern)
+        count = 0
+        for key in keys:
+            if self._base._delete(key):
+                count += 1
+        return count
+
+    def exists(
+        self,
+        key: str,
+        credentials: AgentCredentials,
+        agent_id: str | None = None,
+    ) -> bool:
+        """Check if a key exists in working memory.
+
+        Args:
+            key: Key to check
+            credentials: Agent credentials
+            agent_id: Owner agent ID (defaults to credentials agent)
+
+        Returns:
+            True if key exists
+        """
+        if not key or not key.strip():
+            return False
+
+        owner = agent_id or credentials.agent_id
+        full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
+        return self._base._get(full_key) is not None
+
+    def list_keys(self, credentials: AgentCredentials) -> list[str]:
+        """List all working memory keys for an agent.
+
+        Args:
+            credentials: Agent credentials
+
+        Returns:
+            List of key names (without prefix)
+        """
+        pattern = f"{self.PREFIX_WORKING}{credentials.agent_id}:*"
+        keys = self._base._keys(pattern)
+        prefix_len = len(f"{self.PREFIX_WORKING}{credentials.agent_id}:")
+        return [k[prefix_len:] for k in keys]

attune/meta_workflows/cli_commands/__init__.py

@@ -6,6 +6,9 @@ Copyright 2025 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
+# ruff: noqa: E402
+# Typer app must be created before importing commands that use it
+
 import typer
 
 # Create Typer app for meta-workflow commands

attune/meta_workflows/cli_commands/agent_commands.py

@@ -6,7 +6,6 @@ Copyright 2025 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
-
 import typer
 from rich.console import Console
 from rich.panel import Panel
@@ -151,7 +150,6 @@ def create_agent(
     console.print(f"   {costs.get(tier, costs['capable'])} per execution[/dim]\n")
 
 
-
 @meta_workflow_app.command("create-team")
 def create_team(
     interactive: bool = typer.Option(
@@ -317,5 +315,3 @@ def create_team(
 
 if __name__ == "__main__":
     meta_workflow_app()
-
-

attune/meta_workflows/cli_commands/analytics_commands.py

@@ -139,7 +139,6 @@ def show_analytics(
 # =============================================================================
 
 
-
 @meta_workflow_app.command("list-runs")
 def list_runs(
     template_id: str | None = typer.Option(
@@ -233,7 +232,6 @@ def list_runs(
         raise typer.Exit(code=1)
 
 
-
 @meta_workflow_app.command("show")
 def show_execution(
     run_id: str = typer.Argument(..., help="Run ID to display"),
@@ -322,7 +320,6 @@ def show_execution(
 # =============================================================================
 
 
-
 @meta_workflow_app.command("cleanup")
 def cleanup_executions(
     older_than_days: int = typer.Option(
@@ -437,6 +434,3 @@ def cleanup_executions(
 # =============================================================================
 # Memory Search Commands
 # =============================================================================
-
-
-

attune/meta_workflows/cli_commands/config_commands.py

@@ -6,7 +6,6 @@ Copyright 2025 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
-
 import typer
 from rich.console import Console
 from rich.table import Table
@@ -115,7 +114,6 @@ def suggest_defaults_cmd(
 # =============================================================================
 
 
-
 @meta_workflow_app.command("migrate")
 def show_migration_guide(
     crew_name: str | None = typer.Argument(
@@ -227,6 +225,3 @@ def show_migration_guide(
 # =============================================================================
 # Dynamic Agent/Team Creation Commands (v4.4)
 # =============================================================================
-
-
-

attune/meta_workflows/cli_commands/memory_commands.py

@@ -6,7 +6,6 @@ Copyright 2025 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
-
 import typer
 from rich.console import Console
 from rich.panel import Panel
@@ -103,7 +102,6 @@ def search_memory(
 # =============================================================================
 
 
-
 @meta_workflow_app.command("session-stats")
 def show_session_stats(
     session_id: str | None = typer.Option(
@@ -177,6 +175,3 @@ def show_session_stats(
     except Exception as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(code=1)
-
-
-

attune/meta_workflows/cli_commands/template_commands.py

@@ -108,7 +108,6 @@ def list_templates(
         raise typer.Exit(code=1)
 
 
-
 @meta_workflow_app.command("inspect")
 def inspect_template(
     template_id: str = typer.Argument(..., help="Template ID to inspect"),
@@ -207,7 +206,6 @@ def inspect_template(
 # =============================================================================
 
 
-
 @meta_workflow_app.command("plan")
 def generate_plan_cmd(
     template_id: str = typer.Argument(..., help="Template ID to generate plan for"),
@@ -349,6 +347,3 @@ def generate_plan_cmd(
 # =============================================================================
 # Execution Commands
 # =============================================================================
-
-
-

attune/meta_workflows/cli_commands/workflow_commands.py

@@ -6,7 +6,6 @@ Copyright 2025 Smart-AI-Memory
 Licensed under Fair Source License 0.9
 """
 
-
 import typer
 from rich.console import Console
 from rich.panel import Panel
@@ -208,7 +207,6 @@ def run_workflow(
         raise typer.Exit(code=1)
 
 
-
 @meta_workflow_app.command("ask")
 def natural_language_run(
     request: str = typer.Argument(..., help="Natural language description of what you need"),
@@ -317,7 +315,6 @@ def natural_language_run(
         raise typer.Exit(code=1)
 
 
-
 @meta_workflow_app.command("detect")
 def detect_intent(
     request: str = typer.Argument(..., help="Natural language request to analyze"),
@@ -377,6 +374,3 @@ def detect_intent(
 # =============================================================================
 # Analytics Commands
 # =============================================================================
-
-
-

attune/models/adaptive_routing.py

@@ -30,6 +30,7 @@ def _get_registry():
     global _model_registry
     if _model_registry is None:
         from .registry import MODEL_REGISTRY
+
         _model_registry = MODEL_REGISTRY
     return _model_registry
 
@@ -241,9 +242,7 @@ class AdaptiveModelRouter:
 
         return best.model_id
 
-    def recommend_tier_upgrade(
-        self, workflow: str, stage: str
-    ) -> tuple[bool, str]:
+    def recommend_tier_upgrade(self, workflow: str, stage: str) -> tuple[bool, str]:
         """Check if tier should be upgraded based on failure rate.
 
         Analyzes recent telemetry (last 20 calls) for this workflow/stage.
@@ -335,8 +334,7 @@ class AdaptiveModelRouter:
             performance_by_model[model] = {
                 "calls": len(model_entries),
                 "success_rate": model_successes / len(model_entries),
-                "avg_cost": sum(e.get("cost", 0.0) for e in model_entries)
-                / len(model_entries),
+                "avg_cost": sum(e.get("cost", 0.0) for e in model_entries) / len(model_entries),
                 "avg_latency_ms": sum(e.get("duration_ms", 0) for e in model_entries)
                 / len(model_entries),
             }
@@ -385,9 +383,7 @@ class AdaptiveModelRouter:
             successes = sum(1 for e in model_entries if e.get("success", True))
             success_rate = successes / total
 
-            avg_latency = (
-                sum(e.get("duration_ms", 0) for e in model_entries) / total
-            )
+            avg_latency = sum(e.get("duration_ms", 0) for e in model_entries) / total
             avg_cost = sum(e.get("cost", 0.0) for e in model_entries) / total
 
             # Analyze recent failures (last 20 calls)

attune/models/auth_cli.py

@@ -123,9 +123,7 @@ def cmd_auth_status(args: Any) -> int:
                 "✅ Yes\n" if strategy.setup_completed else "❌ No (run 'empathy auth setup')\n"
             )
 
-            console.print(
-                Panel(config_text, title="Authentication Strategy", border_style="blue")
-            )
+            console.print(Panel(config_text, title="Authentication Strategy", border_style="blue"))
 
             # Module size thresholds
             threshold_table = Table(title="Module Size Thresholds", show_header=True)
@@ -353,9 +351,7 @@ def cmd_auth_recommend(args: Any) -> int:
             if cost_estimate["mode"] == "subscription":
                 print("Monetary Cost: $0.00")
                 print(f"Quota Cost: {cost_estimate['quota_cost']}")
-                print(
-                    f"Fits in 200K: {'Yes' if cost_estimate['fits_in_context'] else 'No'}"
-                )
+                print(f"Fits in 200K: {'Yes' if cost_estimate['fits_in_context'] else 'No'}")
             else:
                 print(f"Monetary Cost: ${cost_estimate['monetary_cost']:.4f}")
                 print("Quota Cost: None")
@@ -396,9 +392,7 @@ Examples:
     subparsers.add_parser("setup", help="Run interactive authentication strategy setup")
 
     # Status command
-    status_parser = subparsers.add_parser(
-        "status", help="Show current authentication strategy"
-    )
+    status_parser = subparsers.add_parser("status", help="Show current authentication strategy")
     status_parser.add_argument(
         "--json", action="store_true", help="Output as JSON instead of formatted table"
     )

attune/models/auth_strategy.py

@@ -335,7 +335,7 @@ def configure_auth_interactive(module_lines: int = 1000) -> AuthStrategy:
 
     comparison = strategy.get_pros_cons(module_lines)
 
-    for mode_key, mode_data in comparison.items():
+    for _mode_key, mode_data in comparison.items():
         print(f"\n### {mode_data['name']}")
         print(f"Cost: {mode_data['cost']}")
         print("\nPros:")
@@ -374,9 +374,7 @@ def configure_auth_interactive(module_lines: int = 1000) -> AuthStrategy:
     # Show recommendation
     print(f"\n✓ Using {default_mode.value} mode")
     if default_mode == AuthMode.AUTO:
-        print(
-            f"   Small/medium modules (< {strategy.medium_module_threshold} LOC) → Subscription"
-        )
+        print(f"   Small/medium modules (< {strategy.medium_module_threshold} LOC) → Subscription")
         print(f"   Large modules (> {strategy.medium_module_threshold} LOC) → API")
 
     return strategy

attune/models/telemetry/analytics.py

@@ -590,5 +590,3 @@ class TelemetryAnalytics:
 
 # Singleton for global telemetry
 _telemetry_store: TelemetryStore | None = None
-
-

attune/models/telemetry/backend.py

@@ -42,7 +42,6 @@ def _parse_timestamp(timestamp_str: str) -> datetime:
     return dt
 
 
-
 class TelemetryBackend(Protocol):
     """Protocol for telemetry storage backends.
 
@@ -192,5 +191,3 @@ def _parse_timestamp(timestamp_str: str) -> datetime:
         dt = dt.replace(tzinfo=None)
 
     return dt
-
-

attune/models/telemetry/storage.py

@@ -485,5 +485,3 @@ class TelemetryStore:
             results.append(record)
 
         return results
-
-

attune/orchestration/_strategies/__init__.py

@@ -0,0 +1,156 @@
+"""Execution strategies for agent composition patterns.
+
+This submodule implements the grammar rules for composing agents:
+1. Sequential (A → B → C)
+2. Parallel (A || B || C)
+3. Debate (A ⇄ B ⇄ C → Synthesis)
+4. Teaching (Junior → Expert validation)
+5. Refinement (Draft → Review → Polish)
+6. Adaptive (Classifier → Specialist)
+7. Conditional (if X then A else B) - branching based on gates
+
+This package provides modular organization of execution strategies:
+- data_classes: AgentResult, StrategyResult
+- conditions: ConditionType, Condition, Branch, ConditionEvaluator
+- nesting: WorkflowReference, InlineWorkflow, NestingContext, WorkflowDefinition
+- base: ExecutionStrategy ABC
+- core_strategies: Sequential, Parallel, Debate, Teaching, Refinement, Adaptive
+- conditional_strategies: Conditional, MultiConditional, Nested, NestedSequential
+- advanced: ToolEnhanced, PromptCached, etc. (TODO)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+# Base strategy class
+from .base import ExecutionStrategy
+
+# Conditional and nested strategies
+from .conditional_strategies import (
+    ConditionalStrategy,
+    MultiConditionalStrategy,
+    NestedSequentialStrategy,
+    NestedStrategy,
+    StepDefinition,
+)
+
+# Condition types and evaluator
+from .conditions import Branch, Condition, ConditionEvaluator, ConditionType
+
+# Core strategies
+from .core_strategies import (
+    AdaptiveStrategy,
+    DebateStrategy,
+    ParallelStrategy,
+    RefinementStrategy,
+    SequentialStrategy,
+    TeachingStrategy,
+)
+
+# Data classes
+from .data_classes import AgentResult, StrategyResult
+
+# Nesting support
+from .nesting import (
+    WORKFLOW_REGISTRY,
+    InlineWorkflow,
+    NestingContext,
+    WorkflowDefinition,
+    WorkflowReference,
+    get_workflow,
+    register_workflow,
+)
+
+# Strategy registry for lookup by name (partial - advanced strategies added in main module)
+_STRATEGY_REGISTRY: dict[str, type[ExecutionStrategy]] = {
+    # Core patterns (1-6)
+    "sequential": SequentialStrategy,
+    "parallel": ParallelStrategy,
+    "debate": DebateStrategy,
+    "teaching": TeachingStrategy,
+    "refinement": RefinementStrategy,
+    "adaptive": AdaptiveStrategy,
+    # Conditional patterns (7+)
+    "conditional": ConditionalStrategy,
+    "multi_conditional": MultiConditionalStrategy,
+    "nested": NestedStrategy,
+    "nested_sequential": NestedSequentialStrategy,
+}
+
+
+def get_strategy(strategy_name: str) -> ExecutionStrategy:
+    """Get strategy instance by name.
+
+    Args:
+        strategy_name: Strategy name (e.g., "sequential", "parallel")
+
+    Returns:
+        ExecutionStrategy instance
+
+    Raises:
+        ValueError: If strategy name is invalid
+
+    Example:
+        >>> strategy = get_strategy("sequential")
+        >>> isinstance(strategy, SequentialStrategy)
+        True
+    """
+    if strategy_name not in _STRATEGY_REGISTRY:
+        raise ValueError(
+            f"Unknown strategy: {strategy_name}. Available: {list(_STRATEGY_REGISTRY.keys())}"
+        )
+
+    strategy_class = _STRATEGY_REGISTRY[strategy_name]
+    return strategy_class()
+
+
+def register_strategy(name: str, strategy_class: type[ExecutionStrategy]) -> None:
+    """Register a strategy class by name.
+
+    Used by main module to add advanced strategies.
+
+    Args:
+        name: Strategy name
+        strategy_class: Strategy class
+    """
+    _STRATEGY_REGISTRY[name] = strategy_class
+
+
+__all__ = [
+    # Data classes
+    "AgentResult",
+    "StrategyResult",
+    # Conditions
+    "Branch",
+    "Condition",
+    "ConditionEvaluator",
+    "ConditionType",
+    # Nesting
+    "InlineWorkflow",
+    "NestingContext",
+    "WORKFLOW_REGISTRY",
+    "WorkflowDefinition",
+    "WorkflowReference",
+    "get_workflow",
+    "register_workflow",
+    # Base strategy
+    "ExecutionStrategy",
+    # Core strategies
+    "AdaptiveStrategy",
+    "DebateStrategy",
+    "ParallelStrategy",
+    "RefinementStrategy",
+    "SequentialStrategy",
+    "TeachingStrategy",
+    # Conditional strategies
+    "ConditionalStrategy",
+    "MultiConditionalStrategy",
+    "NestedSequentialStrategy",
+    "NestedStrategy",
+    "StepDefinition",
+    # Functions
+    "get_strategy",
+    "register_strategy",
+]