agent-runtime-core 0.8.0__py3-none-any.whl → 0.9.1__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/tool_calling_agent.py

@@ -75,8 +75,10 @@ class ToolCallingAgent(AgentRuntime):
         Maximum number of tool-calling iterations.
 
         Override to change the default limit.
+        Default uses the value from config (default: 50).
         """
-        return 15
+        from agent_runtime_core.config import get_config
+        return get_config().max_iterations
 
     @property
     def model(self) -> Optional[str]:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.8.0
+Version: 0.9.1
 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.1.dist-info}/RECORD

@@ -1,16 +1,17 @@
-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=nphrM0uvf41n9e9s4elxlObel02uuXsd-lrSny_3Cpc,22050
+agent_runtime_core/config.py,sha256=7v3NPuE6LQcNLb0MpgpnelEW13ZinXflaCOwYTKdcWQ,7587
 agent_runtime_core/config_schema.py,sha256=1t2ZF5Rk2oRbeYpRATMdFgbvgTPtedIQO6xej4cELh0,10576
-agent_runtime_core/contexts.py,sha256=41UVkSqRJ3E9yIxfCQ-BQ7-wetUfSnDNGdr5-dQOWiY,11349
-agent_runtime_core/interfaces.py,sha256=QvRFPRc2Fwqv_sv-3nExCoaiqwBf_HsQo9yzCYE_Hm0,15498
+agent_runtime_core/contexts.py,sha256=ws4St30698DR6E-ce9ou0wJwFxUE3S_pPXNcXrlDB-Q,14474
+agent_runtime_core/interfaces.py,sha256=rjA8KsbyyKpkVmJvjYQbmIcdoDjt8l3z1FsYFXZkN1A,16263
 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=k8OlPY2AQ5G0eXl53QgcBglUFK7i2f4bahhLy1Nt2Fs,68536
+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
 agent_runtime_core/testing.py,sha256=ordECGprBappLBMWxlETvuf2AoIPNomJFeSedXaY30E,11131
-agent_runtime_core/tool_calling_agent.py,sha256=kyPTwHlYGaqUo0HJ7ycYCCQMFHD_AmPZMsyjxaKpJVc,5967
+agent_runtime_core/tool_calling_agent.py,sha256=CCtGXSh2iLHksY1PodMVIxCMYN5OntfYvhO7vXpus7Q,6107
 agent_runtime_core/tools.py,sha256=SSbiViOJe7raSijwV_TSHI60F5ReHy43Vd_QrAkKgAk,5620
 agent_runtime_core/events/__init__.py,sha256=Gg7cMQHWfLTQ4Xik09KSg7cWbQDmW_MuF5_jl-yZkHU,1575
 agent_runtime_core/events/base.py,sha256=NfHYyoczxr40Er5emROi_aY_07m5hDrKsn31pdWY2DY,1950
@@ -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=icxQa4BtNg8rOV4B187YKSgutscfT12NXNwaay4rSqA,18474
 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/llm/models_config.py,sha256=_jOi60N9cA3PvVOFvCj1rHSlFN5ue8oI9zO_k1d_J2Y,6816
+agent_runtime_core/llm/openai.py,sha256=Ib4FjpcIq3GPTgC0rqvn9zXBdOEfKlMxkTBAFdE__as,8843
 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.1.dist-info/METADATA,sha256=xG7r5bvo-7DxmsFv22N8DkNvt0mVfT4PnFiBGVzgvoA,32643
+agent_runtime_core-0.9.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_runtime_core-0.9.1.dist-info/licenses/LICENSE,sha256=eWG1BdmVdl1LpUaXNfUwEHIGm8qFT5UzSB08LhYyLTo,3850
+agent_runtime_core-0.9.1.dist-info/RECORD,,

agent_runtime_core-0.9.1.dist-info/licenses/LICENSE

@@ -0,0 +1,83 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Chris Barry
+Licensed Work:        agent-runtime-core
+                      The Licensed Work is (c) 2025 Chris Barry
+Additional Use Grant: You may use the Licensed Work for non-production purposes,
+                      including development, testing, and evaluation. Production
+                      use requires a commercial license from the Licensor.
+Change Date:          2029-01-24
+Change License:       MIT
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+

agent_runtime_core-0.8.0.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Chris Barry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.