@macaw-ai/client 0.0.0-stage → 0.9.10

package/payload/secureAI/macaw_adapters/langchain/REFERENCE.md

@@ -0,0 +1,234 @@
+# SecureLangChain Reference
+
+Drop-in replacements for LangChain functions with optional MACAW security. Security is transparent - no code changes required beyond adding a `security_policy` parameter.
+
+## Installation
+
+```python
+from macaw_adapters.langchain.agents import (
+    create_react_agent,
+    create_openai_functions_agent,
+    AgentExecutor,
+    cleanup
+)
+```
+
+Install the package:
+```bash
+pip install -e /path/to/secureAI
+```
+
+## Functions
+
+### create_react_agent
+
+Drop-in replacement for LangChain's `create_react_agent`.
+
+```python
+agent = create_react_agent(
+    llm,                        # Language model
+    tools,                      # List of tools
+    prompt,                     # Prompt template
+    security_policy={...}       # Optional: security policy
+)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `llm` | BaseLLM | Yes | Language model to use |
+| `tools` | List[BaseTool] | Yes | Available tools |
+| `prompt` | PromptTemplate | Yes | Agent prompt template |
+| `security_policy` | dict | No | Simple security policy format |
+| `**kwargs` | dict | No | Additional args for original function |
+
+### create_openai_functions_agent
+
+Drop-in replacement for LangChain's `create_openai_functions_agent`.
+
+```python
+agent = create_openai_functions_agent(
+    llm,                        # OpenAI-compatible model
+    tools,                      # List of tools
+    prompt,                     # Prompt template
+    security_policy={...}       # Optional: security policy
+)
+```
+
+### AgentExecutor
+
+Drop-in replacement for LangChain's `AgentExecutor`.
+
+```python
+executor = AgentExecutor(
+    agent,                      # Agent instance
+    tools,                      # List of tools
+    security_policy={...}       # Optional: security policy
+)
+
+result = executor.invoke({"input": "What's the weather?"})
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent` | Runnable | Yes | The agent to use |
+| `tools` | List[BaseTool] | Yes | Available tools |
+| `security_policy` | dict | No | Simple security policy format |
+| `**kwargs` | dict | No | Additional args for original class |
+
+### cleanup
+
+Clean up all active MACAW clients.
+
+```python
+cleanup()
+```
+
+## Security Policy Format (Simple)
+
+The adapter accepts a simplified policy format and converts it to MAPL:
+
+```python
+security_policy = {
+    # Allowed tools (whitelist)
+    "allowed_tools": ["calculator", "search", "weather"],
+
+    # Blocked tools (blacklist)
+    "blocked_tools": ["dangerous_tool", "admin_tool"],
+
+    # Allowed file paths (patterns)
+    "allowed_files": ["*reports*", "*public*", "*temp*"],
+
+    # Blocked query patterns
+    "blocked_queries": ["*password*", "*credentials*", "*secret*"]
+}
+```
+
+### Policy Conversion
+
+The simple format is automatically converted to MAPL:
+
+| Simple Format | MAPL Format |
+|---------------|-------------|
+| `allowed_tools: ["calc"]` | `resources: ["tool:calc"]` |
+| `blocked_tools: ["admin"]` | `denied_resources: ["tool:admin"]` |
+| `allowed_files: ["*public*"]` | `constraints.parameters.tool:file_reader.path` |
+| `blocked_queries: ["*pass*"]` | `constraints.denied_parameters.tool:*.query` |
+
+## Examples
+
+### Basic Usage (No Security)
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.tools import Tool
+from langchain.agents import create_react_agent
+from langchain import hub
+
+# Same as original LangChain - no security
+llm = ChatOpenAI()
+tools = [Tool(name="calculator", func=lambda x: eval(x), description="Calculator")]
+prompt = hub.pull("hwchase17/react")
+
+agent = create_react_agent(llm, tools, prompt)
+```
+
+### With Security Policy
+
+```python
+from macaw_adapters.langchain.agents import create_react_agent, AgentExecutor
+
+llm = ChatOpenAI()
+tools = [
+    Tool(name="calculator", func=lambda x: eval(x), description="Calculator"),
+    Tool(name="search", func=lambda q: f"Results for {q}", description="Search")
+]
+prompt = hub.pull("hwchase17/react")
+
+# Add security - just one parameter
+agent = create_react_agent(
+    llm, tools, prompt,
+    security_policy={
+        "allowed_tools": ["calculator", "search"],
+        "blocked_queries": ["*password*", "*admin*"]
+    }
+)
+
+executor = AgentExecutor(
+    agent, tools,
+    security_policy={
+        "allowed_tools": ["calculator", "search"],
+        "blocked_queries": ["*password*", "*admin*"]
+    }
+)
+
+# Tool calls now routed through MACAW PEP
+result = executor.invoke({"input": "Calculate 2+2"})
+```
+
+### Authenticated Prompts
+
+LLM prompts are automatically authenticated when security is enabled:
+
+```python
+# When security_policy is provided:
+# 1. LLM is invisibly wrapped with authenticated prompt creation
+# 2. All prompts get cryptographic signatures
+# 3. Audit trail captures prompt lineage
+```
+
+## Security Features
+
+### Tool Wrapping
+
+When `security_policy` is provided:
+
+1. **SecureToolWrapper**: Each tool is wrapped with MACAW routing
+2. **PEP Enforcement**: Tool calls go through Policy Enforcement Point
+3. **Audit Logging**: All tool invocations are logged
+4. **Policy Violations**: Blocked calls return "Access denied by security policy"
+
+### LLM Wrapping
+
+When `security_policy` is provided:
+
+1. **_AuthenticatedLLMWrapper**: LLM invisibly wrapped
+2. **Prompt Authentication**: All prompts get authenticated
+3. **Security Context**: Policy and agent ID bound to prompts
+4. **Transparent**: LLM interface unchanged
+
+## Migration Guide
+
+```python
+# Before (original LangChain)
+from langchain.agents import create_react_agent, AgentExecutor
+
+agent = create_react_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools)
+
+# After (with security)
+from macaw_adapters.langchain.agents import create_react_agent, AgentExecutor
+
+agent = create_react_agent(
+    llm, tools, prompt,
+    security_policy={"blocked_queries": ["*password*"]}
+)
+executor = AgentExecutor(
+    agent=agent, tools=tools,
+    security_policy={"blocked_queries": ["*password*"]}
+)
+
+# Same API - security is optional and transparent
+```
+
+## Cleanup
+
+Always clean up MACAW clients when done:
+
+```python
+from macaw_adapters.langchain.agents import cleanup
+
+# Manual cleanup
+cleanup()
+
+# Auto-cleanup on module exit is registered via atexit
+```

package/payload/secureAI/macaw_adapters/langchain/__init__.py

@@ -0,0 +1,100 @@
+"""
+MACAW LangChain Adapter - Drop-in replacements for LangChain with MACAW protection.
+
+Usage:
+    # LLM providers (mirrors langchain_openai / langchain_anthropic)
+    from macaw_adapters.langchain import ChatOpenAI, ChatAnthropic
+
+    # Or use explicit "Secure" names
+    from macaw_adapters.langchain import SecureChatOpenAI, SecureChatAnthropic
+
+    # Memory classes (mirrors langchain.memory)
+    from macaw_adapters.langchain.memory import ConversationBufferMemory
+
+    # Agent functions (mirrors langchain.agents)
+    from macaw_adapters.langchain.agents import create_react_agent, AgentExecutor
+
+    # Tool wrappers
+    from macaw_adapters.langchain.tools import SecureToolWrapper, wrap_tools
+
+Features:
+    - Drop-in replacement for LangChain components
+    - Policy-enforced LLM calls via SecureOpenAI/SecureAnthropic internally
+    - Policy-enforced tool execution via invoke_tool
+    - Per-user identity propagation via bind_to_user
+    - Cryptographic audit trail
+"""
+
+# Submodules (enable namespace imports)
+from . import openai
+from . import anthropic
+from . import memory
+from . import agents
+from . import tools
+from . import callbacks
+
+# Convenience re-exports
+from .openai import ChatOpenAI
+from .anthropic import ChatAnthropic
+
+# Explicit "Secure" aliases (same classes, clearer naming)
+SecureChatOpenAI = ChatOpenAI
+SecureChatAnthropic = ChatAnthropic
+from .memory import (
+    ConversationBufferMemory,
+    ConversationBufferWindowMemory,
+    ConversationSummaryMemory
+)
+from .agents import (
+    create_react_agent,
+    create_openai_functions_agent,
+    AgentExecutor
+)
+from .tools import SecureToolWrapper, wrap_tools, secure_tool
+from .callbacks import MACAWCallbackHandler
+from ._utils import cleanup_all
+
+
+def cleanup():
+    """Clean up all MACAW resources."""
+    cleanup_all()
+
+
+__all__ = [
+    # Submodules
+    'openai',
+    'anthropic',
+    'memory',
+    'agents',
+    'tools',
+    'callbacks',
+
+    # LLM classes (drop-in names)
+    'ChatOpenAI',
+    'ChatAnthropic',
+
+    # LLM classes (explicit Secure names - same classes)
+    'SecureChatOpenAI',
+    'SecureChatAnthropic',
+
+    # Memory classes
+    'ConversationBufferMemory',
+    'ConversationBufferWindowMemory',
+    'ConversationSummaryMemory',
+
+    # Agent functions
+    'create_react_agent',
+    'create_openai_functions_agent',
+    'AgentExecutor',
+
+    # Tool wrappers
+    'SecureToolWrapper',
+    'wrap_tools',
+    'secure_tool',
+
+    # Callback handler
+    'MACAWCallbackHandler',
+
+    # Cleanup
+    'cleanup'
+]

package/payload/secureAI/macaw_adapters/langchain/_utils.py

@@ -0,0 +1,83 @@
+"""
+Shared utilities for SecureLangChain adapter.
+"""
+
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+from macaw_client import MACAWClient
+
+logger = logging.getLogger(__name__)
+
+# Global registry of active MACAW clients (for cleanup)
+_active_clients: Dict[str, MACAWClient] = {}
+
+
+def get_or_create_client(
+    client_id: str,
+    intent_policy: Optional[Dict[str, Any]] = None,
+    tools: Optional[Dict[str, Any]] = None
+) -> Optional[MACAWClient]:
+    """
+    Get existing MACAW client or create a new one.
+
+    Args:
+        client_id: Unique identifier for the client
+        intent_policy: Optional policy for the client
+        tools: Optional unified tools config {name: {handler, prompts, ...}}
+
+    Returns:
+        MACAWClient instance or None if registration fails
+    """
+    if client_id not in _active_clients:
+        client = MACAWClient(
+            app_name=client_id,
+            app_version="1.0.0",
+            agent_type="agent",
+            intent_policy=intent_policy,
+            tools=tools
+        )
+        if client.register():
+            _active_clients[client_id] = client
+            logger.debug(f"Created MACAWClient: {client_id}")
+        else:
+            logger.warning(f"Failed to register MACAWClient: {client_id}")
+            return None
+    return _active_clients.get(client_id)
+
+
+def register_client(client_id: str, client: MACAWClient) -> None:
+    """Register an existing client for cleanup tracking."""
+    _active_clients[client_id] = client
+
+
+def _is_shutdown_error(e: Exception) -> bool:
+    """Check if error is due to Python interpreter shutdown."""
+    msg = str(e).lower()
+    return "interpreter shutdown" in msg or "cannot schedule" in msg
+
+
+def cleanup_all() -> None:
+    """Clean up all active MACAW clients."""
+    for client_id, client in list(_active_clients.items()):
+        try:
+            client.unregister()
+            logger.debug(f"Cleaned up MACAWClient: {client_id}")
+        except Exception as e:
+            # Ignore errors during Python shutdown - process is ending anyway
+            if not _is_shutdown_error(e):
+                logger.error(f"Error cleaning up {client_id}: {e}")
+    _active_clients.clear()
+
+
+def cleanup_client(client_id: str) -> None:
+    """Clean up a specific MACAW client."""
+    if client_id in _active_clients:
+        try:
+            _active_clients[client_id].unregister()
+            del _active_clients[client_id]
+            logger.debug(f"Cleaned up MACAWClient: {client_id}")
+        except Exception as e:
+            # Ignore errors during Python shutdown - process is ending anyway
+            if not _is_shutdown_error(e):
+                logger.error(f"Error cleaning up {client_id}: {e}")

package/payload/secureAI/macaw_adapters/langchain/agents.py

@@ -0,0 +1,296 @@
+"""
+MACAW Agent Functions - Drop-in replacements for LangChain agent creation.
+
+Usage:
+    # Instead of: from langchain.agents import create_react_agent, AgentExecutor
+    from macaw_adapters.langchain.agents import create_react_agent, AgentExecutor
+
+    agent = create_react_agent(llm, tools, prompt, security_policy={...})
+    executor = AgentExecutor(agent=agent, tools=tools, security_policy={...})
+"""
+
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+from macaw_client import MACAWClient
+from ._utils import get_or_create_client, register_client, cleanup_all
+from .tools import SecureToolWrapper, wrap_tools
+
+logger = logging.getLogger(__name__)
+
+
+class _AuthenticatedLLMWrapper:
+    """
+    Transparent wrapper that routes LLM prompts through MACAW authentication.
+
+    Invisible to developers - presents same interface as original LLM.
+    """
+
+    def __init__(self, original_llm: Any, macaw_client: MACAWClient):
+        self._llm = original_llm
+        self._macaw = macaw_client
+
+        # Copy non-callable attributes
+        for attr in dir(original_llm):
+            if not attr.startswith('_') and not callable(getattr(original_llm, attr)):
+                try:
+                    setattr(self, attr, getattr(original_llm, attr))
+                except AttributeError:
+                    pass
+
+    def invoke(self, prompt, **kwargs):
+        """Intercept and authenticate prompts."""
+        try:
+            auth_prompt = self._macaw.create_authenticated_prompt(
+                prompt_text=str(prompt),
+                metadata={
+                    "agent_id": self._macaw.agent_id,
+                    "source": "langchain_agent"
+                }
+            )
+            logger.debug("[SecureAgent] Created authenticated prompt")
+            return self._llm.invoke(auth_prompt, **kwargs)
+        except Exception as e:
+            logger.warning(f"Auth prompt failed, using original: {e}")
+            return self._llm.invoke(prompt, **kwargs)
+
+    def predict(self, text: str, **kwargs):
+        """Handle predict interface."""
+        try:
+            auth_text = self._macaw.create_authenticated_prompt(
+                prompt_text=text,
+                metadata={"agent_id": self._macaw.agent_id}
+            )
+            return self._llm.predict(auth_text, **kwargs)
+        except Exception as e:
+            logger.warning(f"Auth prompt failed, using original: {e}")
+            return self._llm.predict(text, **kwargs)
+
+    def __getattr__(self, name):
+        """Delegate to original LLM."""
+        return getattr(self._llm, name)
+
+
+def _setup_security(
+    tools: List[Any],
+    security_policy: Optional[Dict[str, Any]]
+) -> tuple:
+    """
+    Set up MACAW security for tools.
+
+    Args:
+        tools: List of LangChain tools
+        security_policy: MAPL format policy dict with resources, denied_resources, constraints
+
+    Returns:
+        (processed_tools, macaw_client) - wrapped tools and client, or originals if no policy
+
+    Example policy (MAPL format):
+        {
+            "resources": ["tool:calculator", "tool:weather"],
+            "denied_resources": ["tool:admin"],
+            "constraints": {
+                "denied_parameters": {"tool:*": {"query": ["*password*"]}}
+            }
+        }
+    """
+    if not security_policy:
+        return tools, None
+
+    # Filter tools based on policy - LLM should only see tools it can use
+    # This prevents wasted iterations on blocked tools
+    allowed_tools = tools
+    if "resources" in security_policy:
+        allowed_names = {r.replace("tool:", "") for r in security_policy["resources"]}
+        allowed_tools = [t for t in tools if t.name in allowed_names]
+        logger.debug(f"Filtered tools to allowed resources: {[t.name for t in allowed_tools]}")
+
+    # Also exclude explicitly denied tools
+    if "denied_resources" in security_policy:
+        denied_names = {r.replace("tool:", "") for r in security_policy["denied_resources"]}
+        allowed_tools = [t for t in allowed_tools if t.name not in denied_names]
+        logger.debug(f"Excluded denied resources: {denied_names}")
+
+    # Build tools dict with handlers and prompts declaration
+    # Following the same pattern as SecureOpenAI
+    tools_config = {}
+    for tool in allowed_tools:
+        handler = None
+        if hasattr(tool, 'func'):
+            # Wrap func to handle params as dict or string
+            def make_handler(func):
+                def handler(params):
+                    if isinstance(params, dict):
+                        # Try 'input' key first (standard), then unpack as kwargs
+                        if 'input' in params:
+                            return func(params['input'])
+                        return func(**params)
+                    return func(params)
+                return handler
+            handler = make_handler(tool.func)
+        elif hasattr(tool, '_run'):
+            def make_run_handler(t):
+                def handler(params):
+                    if isinstance(params, dict):
+                        return t._run(**params)
+                    return t._run(params)
+                return handler
+            handler = make_run_handler(tool)
+
+        if handler:
+            # Check if security_policy specifies prompts for this tool
+            # Default: LangChain tools take 'input' as the prompt parameter
+            tool_prompts = security_policy.get('tool_prompts', {}).get(tool.name, ['input'])
+            tools_config[tool.name] = {
+                "handler": handler,
+                "prompts": tool_prompts
+            }
+
+    # Create MACAW client with unified tools config
+    client = MACAWClient(
+        app_name="secure-langchain-agent",
+        app_version="1.0.0",
+        intent_policy=security_policy,  # MAPL format policy passed directly
+        tools=tools_config  # Unified: {name: {handler, prompts, ...}}
+    )
+
+    if client.register():
+        register_client(client.agent_id, client)
+        logger.info(f"SecureAgent registered: {client.agent_id}")
+        return wrap_tools(allowed_tools, client), client
+    else:
+        logger.error("Failed to register with MACAW")
+        return allowed_tools, None
+
+
+def create_react_agent(
+    llm: Any,
+    tools: List[Any],
+    prompt: Any,
+    security_policy: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> Any:
+    """
+    Drop-in replacement for LangChain's create_react_agent.
+
+    Args:
+        llm: Language model
+        tools: List of tools
+        prompt: Prompt template
+        security_policy: Optional security policy (simple format)
+        **kwargs: Additional arguments for original function
+
+    Returns:
+        Agent runnable
+
+    Example:
+        agent = create_react_agent(
+            llm, tools, prompt,
+            security_policy={"allowed_tools": ["calculator", "weather"]}
+        )
+    """
+    from langchain.agents import create_react_agent as _create_react_agent
+
+    wrapped_tools, client = _setup_security(tools, security_policy)
+
+    # Wrap LLM if we have a client
+    wrapped_llm = _AuthenticatedLLMWrapper(llm, client) if client else llm
+
+    return _create_react_agent(wrapped_llm, wrapped_tools, prompt, **kwargs)
+
+
+def create_openai_functions_agent(
+    llm: Any,
+    tools: List[Any],
+    prompt: Any,
+    security_policy: Optional[Dict[str, Any]] = None,
+    **kwargs
+) -> Any:
+    """
+    Drop-in replacement for LangChain's create_openai_functions_agent.
+
+    Args:
+        llm: Language model
+        tools: List of tools
+        prompt: Prompt template
+        security_policy: Optional security policy
+        **kwargs: Additional arguments
+
+    Returns:
+        Agent runnable
+    """
+    from langchain.agents import create_openai_functions_agent as _create_openai_functions_agent
+
+    wrapped_tools, client = _setup_security(tools, security_policy)
+    wrapped_llm = _AuthenticatedLLMWrapper(llm, client) if client else llm
+
+    return _create_openai_functions_agent(wrapped_llm, wrapped_tools, prompt, **kwargs)
+
+
+class AgentExecutor:
+    """
+    Drop-in replacement for LangChain's AgentExecutor with security support.
+
+    Uses composition to wrap the original while enforcing policies.
+    """
+
+    def __init__(
+        self,
+        agent: Any,
+        tools: List[Any],
+        security_policy: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ):
+        """
+        Initialize with optional security policy.
+
+        Args:
+            agent: The agent to use
+            tools: List of tools
+            security_policy: Optional security policy
+            **kwargs: Arguments for original AgentExecutor
+        """
+        from langchain.agents import AgentExecutor as _AgentExecutor
+
+        wrapped_tools, self._macaw = _setup_security(tools, security_policy)
+
+        # Wrap agent's LLM if present
+        if self._macaw and hasattr(agent, 'llm'):
+            try:
+                agent.llm = _AuthenticatedLLMWrapper(agent.llm, self._macaw)
+            except Exception:
+                pass
+
+        self._executor = _AgentExecutor(agent=agent, tools=wrapped_tools, **kwargs)
+
+    def invoke(self, input_data: Any, **kwargs) -> Any:
+        return self._executor.invoke(input_data, **kwargs)
+
+    def batch(self, inputs: List[Any], **kwargs) -> List:
+        return self._executor.batch(inputs, **kwargs)
+
+    def stream(self, input_data: Any, **kwargs):
+        return self._executor.stream(input_data, **kwargs)
+
+    async def ainvoke(self, input_data: Any, **kwargs) -> Any:
+        return await self._executor.ainvoke(input_data, **kwargs)
+
+    async def abatch(self, inputs: List[Any], **kwargs) -> List:
+        return await self._executor.abatch(inputs, **kwargs)
+
+    async def astream(self, input_data: Any, **kwargs):
+        async for chunk in self._executor.astream(input_data, **kwargs):
+            yield chunk
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._executor, name)
+
+
+def cleanup():
+    """Clean up all MACAW resources."""
+    cleanup_all()
+
+
+# Auto-cleanup on module exit
+import atexit
+atexit.register(cleanup)