agent-runtime-core 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

agent_runtime_core/privacy.py

@@ -0,0 +1,250 @@
+"""
+Privacy and user isolation abstractions for agent_runtime_core.
+
+This module provides framework-agnostic definitions for:
+
+1. **PrivacyConfig** - Settings that control what data is persisted and when.
+   Defaults to maximum privacy (auth required for all persistent data).
+
+2. **UserContext** - Represents the current user (authenticated or anonymous).
+   Used to scope data access and enforce privacy rules.
+
+3. **MemoryScope** - Defines how memory is scoped (conversation, user, system).
+
+These abstractions are designed to be implemented by framework-specific code
+(e.g., django_agent_runtime) while providing consistent privacy guarantees.
+
+Example:
+    from agent_runtime_core.privacy import PrivacyConfig, UserContext, MemoryScope
+
+    # Maximum privacy (default)
+    config = PrivacyConfig()
+    assert config.require_auth_for_memory == True
+    assert config.require_auth_for_conversations == True
+
+    # Authenticated user
+    user = UserContext(
+        user_id="user-123",
+        is_authenticated=True,
+    )
+
+    # Anonymous user (no persistent data allowed by default)
+    anon = UserContext.anonymous()
+    assert anon.is_authenticated == False
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class MemoryScope(str, Enum):
+    """
+    Defines how memory is scoped.
+
+    CONVERSATION: Memory is scoped to a single conversation.
+                  Lost when conversation ends. Safest option.
+
+    USER: Memory persists across conversations for a user.
+          Requires authentication. Good for preferences, learned facts.
+
+    SYSTEM: Memory is shared across all agents in a system for a user.
+            Requires authentication. Good for cross-agent knowledge sharing.
+    """
+    CONVERSATION = "conversation"
+    USER = "user"
+    SYSTEM = "system"
+
+
+@dataclass
+class PrivacyConfig:
+    """
+    Configuration for privacy and data persistence.
+
+    All settings default to maximum privacy (auth required for everything).
+    Framework implementations should respect these settings.
+
+    Attributes:
+        require_auth_for_memory: If True, memory is only stored for authenticated users.
+                                 Anonymous users get no persistent memory. Default: True.
+
+        require_auth_for_conversations: If True, conversations are only persisted for
+                                        authenticated users. Anonymous conversations
+                                        are ephemeral. Default: True.
+
+        require_auth_for_tool_tracking: If True, tool calls are only logged for
+                                        authenticated users. Default: True.
+
+        default_memory_scope: Default scope for new memories. Default: CONVERSATION.
+
+        allow_cross_agent_memory: If True, agents in a system can share memories
+                                  about a user. Requires SYSTEM scope. Default: True.
+
+        memory_retention_days: How long to retain user memories. None = forever.
+                               Default: None.
+
+        conversation_retention_days: How long to retain conversations. None = forever.
+                                     Default: None.
+
+        metadata: Additional configuration metadata.
+
+    Example:
+        # Maximum privacy (default)
+        config = PrivacyConfig()
+
+        # Allow anonymous conversations but not memory
+        config = PrivacyConfig(
+            require_auth_for_conversations=False,
+            require_auth_for_memory=True,
+        )
+
+        # Strict retention policy
+        config = PrivacyConfig(
+            memory_retention_days=30,
+            conversation_retention_days=90,
+        )
+    """
+    require_auth_for_memory: bool = True
+    require_auth_for_conversations: bool = True
+    require_auth_for_tool_tracking: bool = True
+    default_memory_scope: MemoryScope = MemoryScope.CONVERSATION
+    allow_cross_agent_memory: bool = True
+    memory_retention_days: Optional[int] = None
+    conversation_retention_days: Optional[int] = None
+    metadata: dict = field(default_factory=dict)
+
+    def allows_memory(self, user: "UserContext") -> bool:
+        """Check if memory storage is allowed for this user."""
+        if self.require_auth_for_memory:
+            return user.is_authenticated
+        return True
+
+    def allows_conversation_persistence(self, user: "UserContext") -> bool:
+        """Check if conversation persistence is allowed for this user."""
+        if self.require_auth_for_conversations:
+            return user.is_authenticated
+        return True
+
+    def allows_tool_tracking(self, user: "UserContext") -> bool:
+        """Check if tool call tracking is allowed for this user."""
+        if self.require_auth_for_tool_tracking:
+            return user.is_authenticated
+        return True
+
+    def to_dict(self) -> dict:
+        """Serialize to dictionary."""
+        return {
+            "require_auth_for_memory": self.require_auth_for_memory,
+            "require_auth_for_conversations": self.require_auth_for_conversations,
+            "require_auth_for_tool_tracking": self.require_auth_for_tool_tracking,
+            "default_memory_scope": self.default_memory_scope.value,
+            "allow_cross_agent_memory": self.allow_cross_agent_memory,
+            "memory_retention_days": self.memory_retention_days,
+            "conversation_retention_days": self.conversation_retention_days,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PrivacyConfig":
+        """Deserialize from dictionary."""
+        return cls(
+            require_auth_for_memory=data.get("require_auth_for_memory", True),
+            require_auth_for_conversations=data.get("require_auth_for_conversations", True),
+            require_auth_for_tool_tracking=data.get("require_auth_for_tool_tracking", True),
+            default_memory_scope=MemoryScope(data.get("default_memory_scope", "conversation")),
+            allow_cross_agent_memory=data.get("allow_cross_agent_memory", True),
+            memory_retention_days=data.get("memory_retention_days"),
+            conversation_retention_days=data.get("conversation_retention_days"),
+            metadata=data.get("metadata", {}),
+        )
+
+
+@dataclass
+class UserContext:
+    """
+    Represents the current user for privacy and data isolation.
+
+    This is a framework-agnostic representation of a user. Framework
+    implementations (e.g., Django) should create UserContext from their
+    native user objects.
+
+    Attributes:
+        user_id: Unique identifier for the user. None for anonymous users.
+        is_authenticated: Whether the user is authenticated.
+        username: Optional username for display purposes.
+        email: Optional email address.
+        metadata: Additional user metadata (roles, permissions, etc.)
+
+    Example:
+        # From Django user
+        user_ctx = UserContext(
+            user_id=str(request.user.id),
+            is_authenticated=request.user.is_authenticated,
+            username=request.user.username,
+            email=request.user.email,
+        )
+
+        # Anonymous user
+        user_ctx = UserContext.anonymous()
+
+        # Check permissions
+        if privacy_config.allows_memory(user_ctx):
+            store.save_memory(...)
+    """
+    user_id: Optional[str] = None
+    is_authenticated: bool = False
+    username: Optional[str] = None
+    email: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+
+    @classmethod
+    def anonymous(cls) -> "UserContext":
+        """Create an anonymous user context."""
+        return cls(
+            user_id=None,
+            is_authenticated=False,
+            username=None,
+            email=None,
+            metadata={"anonymous": True},
+        )
+
+    @classmethod
+    def from_user_id(cls, user_id: str, **kwargs) -> "UserContext":
+        """Create an authenticated user context from a user ID."""
+        return cls(
+            user_id=user_id,
+            is_authenticated=True,
+            **kwargs,
+        )
+
+    def to_dict(self) -> dict:
+        """Serialize to dictionary."""
+        return {
+            "user_id": self.user_id,
+            "is_authenticated": self.is_authenticated,
+            "username": self.username,
+            "email": self.email,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "UserContext":
+        """Deserialize from dictionary."""
+        return cls(
+            user_id=data.get("user_id"),
+            is_authenticated=data.get("is_authenticated", False),
+            username=data.get("username"),
+            email=data.get("email"),
+            metadata=data.get("metadata", {}),
+        )
+
+    def __str__(self) -> str:
+        if self.is_authenticated:
+            return f"User({self.username or self.user_id})"
+        return "AnonymousUser"
+
+
+# Default instances for convenience
+DEFAULT_PRIVACY_CONFIG = PrivacyConfig()
+ANONYMOUS_USER = UserContext.anonymous()
+

{agent_runtime_core-0.8.0.dist-info → agent_runtime_core-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.8.0
+Version: 0.9.0
 Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
 Project-URL: Homepage, https://github.com/makemore/agent-runtime-core
 Project-URL: Repository, https://github.com/makemore/agent-runtime-core
@@ -92,6 +92,7 @@ A lightweight, framework-agnostic Python library for building AI agent systems.
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **0.9.0** | 2026-01-28 | **Multi-Agent & Debug** - Shared memory with privacy controls, journey mode, structured handback protocol, stuck/loop detection, fallback routing, cost/context tracking in debug mode |
 | **0.8.0** | 2026-01-28 | **File Ingestion** - Pluggable file processors (PDF, images, DOCX, XLSX, CSV), OCR providers (Tesseract, Google Vision, AWS Textract, Azure), AI vision (OpenAI, Anthropic, Gemini), file read/write tools |
 | **0.7.1** | 2026-01-24 | RAG module, vector stores (sqlite-vec, Vertex AI), memory system, multi-agent support, agentic loop, JSON runtime |
 | **0.6.0** | 2025-01-23 | Enhanced registry with factory functions and class registration |

{agent_runtime_core-0.8.0.dist-info → agent_runtime_core-0.9.0.dist-info}/RECORD

@@ -1,11 +1,12 @@
-agent_runtime_core/__init__.py,sha256=Vn-32GMh-6S5k6e4fiejAbNxjnbsoskf-Um1Ni2dgog,7117
-agent_runtime_core/agentic_loop.py,sha256=DJ3RXaQLFlHMf-icQjpTJkAvdfjkPBSGN1S_iy3mf64,9635
-agent_runtime_core/config.py,sha256=WVfcIluFvf2zC_NKk2WuJhhPIGQNcuxmZV9TCg4t13o,7297
+agent_runtime_core/__init__.py,sha256=80m5og5XW2cGvFlU2dQ4aj8RZ_Z0gQdswstmkhxVleM,8656
+agent_runtime_core/agentic_loop.py,sha256=vEfC4UVfTZ06Ec00Dl7azqP6mbx7Lk7oyvvrXuZJksI,21763
+agent_runtime_core/config.py,sha256=tYJam_EbLBZW7wW07RTn3A7xF1TWKsBKGxOp02KRudU,7426
 agent_runtime_core/config_schema.py,sha256=1t2ZF5Rk2oRbeYpRATMdFgbvgTPtedIQO6xej4cELh0,10576
-agent_runtime_core/contexts.py,sha256=41UVkSqRJ3E9yIxfCQ-BQ7-wetUfSnDNGdr5-dQOWiY,11349
+agent_runtime_core/contexts.py,sha256=ws4St30698DR6E-ce9ou0wJwFxUE3S_pPXNcXrlDB-Q,14474
 agent_runtime_core/interfaces.py,sha256=QvRFPRc2Fwqv_sv-3nExCoaiqwBf_HsQo9yzCYE_Hm0,15498
 agent_runtime_core/json_runtime.py,sha256=b1BnGAQMORB4YULsKcCR0hEaCvln3Bz2dP228yq5BIQ,17358
-agent_runtime_core/multi_agent.py,sha256=UleIFocGW0GZFeoa_bPfYGLZZH-NYiEsiG2BBTGdKyA,18409
+agent_runtime_core/multi_agent.py,sha256=Lq5Brjan-alJPNkhLtBEaN9PWPG3QoDbGHagBBMYrzA,68091
+agent_runtime_core/privacy.py,sha256=47b_5FrUBhNrONaziLlVvUOxtmzaMSYGkrVN6krFDjw,8983
 agent_runtime_core/registry.py,sha256=QmazCAcHTsPt236Z_xEBJjdppm6jUuufE-gfvcGMUCk,3959
 agent_runtime_core/runner.py,sha256=ydzyGJHCyz1wjs-sN5dx4RlJsYK0U-Or12BL_Fg8-aQ,19595
 agent_runtime_core/steps.py,sha256=XpVFK7P-ZOpr7NwaP7XFygduIpjrKld-OIig7dHNMKE,11994
@@ -24,16 +25,16 @@ agent_runtime_core/files/processors.py,sha256=KudeacTDxaVyUtCjBpIg1OuByi4_71WP9R
 agent_runtime_core/files/tools.py,sha256=Dky2CxFLUL8GICIwU1kbNV-IwnszWr1WXhJ3FItGRd4,10856
 agent_runtime_core/files/vision.py,sha256=nM8xKx-yEblwPFr5tM9JRrFkitTPLDkLU1fSDHLvuW8,10119
 agent_runtime_core/llm/__init__.py,sha256=7-tA1FmPkhY1l-lHhzd84MQf2bjs26bcgb8oAlglc58,4605
-agent_runtime_core/llm/anthropic.py,sha256=AX2QJoQf-4uLDCxWFs71XfD11IMN6iI3gMPA25F3KrM,12239
+agent_runtime_core/llm/anthropic.py,sha256=vHnTsByHze6nTxt89o5rNOdG4YI7uHZBQzyJyEp6LNI,15679
 agent_runtime_core/llm/litellm_client.py,sha256=c-O-lE08cT3ne0xSOvSDezPL6hCiA69p3HnB451Ipe4,5193
 agent_runtime_core/llm/models_config.py,sha256=i275wtsWeR-LHdFrObPI19PtCIGvMDKTEKpue5TuYIk,5342
 agent_runtime_core/llm/openai.py,sha256=qBZkkndDgYQ6LG-9bHS2za5KJTGSgL-c_7h0bD3_5lg,6862
 agent_runtime_core/memory/__init__.py,sha256=7dgoXMr3IIjKsKKbxVgQBrrhZHqmJRIx64mcbF8jgUM,2178
 agent_runtime_core/memory/manager.py,sha256=ba8ZKb1aF9Pc-zZB4O_22b6zb6ELpvo_LhpSs959L5U,18474
 agent_runtime_core/memory/mixin.py,sha256=Afq7rhW1SmZgii6b3gUbM3peDzMwfMxQ0DstHzGfuDM,9683
-agent_runtime_core/persistence/__init__.py,sha256=HdkGW5hnLjBRE0QcUWVjL2xsIkMyKPpqJKpamPbFh0s,2822
-agent_runtime_core/persistence/base.py,sha256=k0wuzTCffPJ609dj9hIhnaqnNI1Qr3pCzJ-6E1YkSRU,21616
-agent_runtime_core/persistence/file.py,sha256=uZxl3W405jeX1H6f0Xj_pZOQFTpZOYbpIdJ98rZabBI,28712
+agent_runtime_core/persistence/__init__.py,sha256=TeGcQSfNGGBAc_aEWmSkxh6U-rG_Gbelyk2CAke8Lwg,3008
+agent_runtime_core/persistence/base.py,sha256=zyKQDTKMX9rHucota1RI6zWQzmiOd_R6qHCaLZfyvXk,32015
+agent_runtime_core/persistence/file.py,sha256=QfhRdPI4bEDJJaKogG-kYdD0HkWpNEOE2-3oEtMlUZQ,36005
 agent_runtime_core/persistence/manager.py,sha256=UL_eFsFM28nXM6O9PTHdzKX9Qxh9v2gBGd1m9Bs0vog,14309
 agent_runtime_core/queue/__init__.py,sha256=m8gapXACPGApLj0RIDpVe5cQYuvKq1QsY2_mXzZcULQ,1527
 agent_runtime_core/queue/base.py,sha256=QW1eWbwBX_tmVD8yJobFJtlxLd_RtUWHTuXGessuxy8,3959
@@ -57,7 +58,7 @@ agent_runtime_core/vectorstore/base.py,sha256=y1ZZCbAMkFkbHwOqzaK0JUBAVjbnNwwdSn
 agent_runtime_core/vectorstore/embeddings.py,sha256=WTTiId9Q6I7cxHuiInYHEV8EWS2HyRYRW1YDPALGUVY,7749
 agent_runtime_core/vectorstore/sqlite_vec.py,sha256=B4KPYdSkm-af-uqltqMga1uXslC19Uaeuy1sXfKOjyo,10552
 agent_runtime_core/vectorstore/vertex.py,sha256=a1Ps_gMYqTlWUkNALpgMVEX6r6Zw_8gN5pZ59-vH7Ww,9695
-agent_runtime_core-0.8.0.dist-info/METADATA,sha256=nC_KSql_QyKBPfaGxyakWQhTR_z15gj3X068l7viqqY,32431
-agent_runtime_core-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-agent_runtime_core-0.8.0.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
-agent_runtime_core-0.8.0.dist-info/RECORD,,
+agent_runtime_core-0.9.0.dist-info/METADATA,sha256=GPWqR2T9BOXyN9ZSC-wO6lFtbuiAoFHo24pL5Zw9sCA,32643
+agent_runtime_core-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_runtime_core-0.9.0.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
+agent_runtime_core-0.9.0.dist-info/RECORD,,