@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/attestations/1b_grant_researcher.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+1b_grant_researcher.py - Reusable Capability Grant (Researcher)
+
+A researcher needs admin approval to use web_search.
+- First invocation: BLOCKS until admin approves
+- Second+ invocations: IMMEDIATE (reuses existing approval)
+
+The key difference from Example 1a is: one_time=False
+
+This demonstrates:
+- Reusable grants: approve once, use many times
+- time_to_live: how long the grant lasts
+- attestation_accessed audit event on reuse
+
+NOTE: This example requires interactive approval and is not suitable
+for automated test harnesses.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - Identity Provider configured (Console -> Settings -> Identity Bridge)
+    - Test users: alice/Alice123!, bob/Bob@123! (bob needs admin role)
+
+Run:
+    # Terminal 1: Run researcher request (will block waiting)
+    python 1b_grant_researcher.py
+
+    # Terminal 2: Run admin approval
+    python 1b_grant_admin.py
+"""
+
+import json
+import time
+
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+
+def web_search_handler(params):
+    """Simulate web search."""
+    query = params.get('query', '')
+    print(f"\n  [TOOL] web_search invoked!")
+    print(f"  [TOOL] Query: {query}")
+
+    # Simulate search results
+    result = {
+        "status": "success",
+        "query": query,
+        "results": [
+            {"title": f"Result 1 for '{query}'", "url": "https://example.com/1"},
+            {"title": f"Result 2 for '{query}'", "url": "https://example.com/2"},
+        ]
+    }
+    print(f"  [TOOL] Returning {len(result['results'])} results")
+    return result
+
+
+def main():
+    print("=" * 60)
+    print("Example 1b: Reusable Capability Grant - Researcher")
+    print("=" * 60)
+
+    # Step 1: Create Search Service
+    print("\n[Step 1] Creating Search Service...")
+
+    try:
+        search_service = MACAWClient(
+            app_name="search",
+            agent_type="service",
+            tools={
+                "tool:search/web_search": {
+                    "handler": web_search_handler,
+                    "description": "Search the web for information"
+                }
+            }
+        )
+
+        if not search_service.register():
+            print("  ERROR: Failed to register Search Service")
+            return 1
+
+        print(f"  Service ID: {search_service.agent_id}")
+        print(f"  Provides: tool:search/web_search")
+
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        return 1
+
+    # Step 2: Authenticate as researcher (using alice credentials)
+    print("\n[Step 2] Authenticating as researcher...")
+    try:
+        jwt_token, _ = RemoteIdentityProvider().login("alice", "Alice123!")
+        print("  Got JWT token")
+    except Exception as e:
+        print(f"  ERROR: Failed to authenticate: {e}")
+        search_service.unregister()
+        return 1
+
+    # Step 3: Create researcher agent with REUSABLE attestation (one_time=False)
+    print("\n[Step 3] Creating researcher agent...")
+    try:
+        researcher = MACAWClient(
+            user_name="researcher",
+            iam_token=jwt_token,
+            agent_type="user",
+            app_name="research-app",
+            intent_policy={
+                "resources": ["tool:search/web_search"],
+                # Attestation always required for this tool
+                "attestations": ["capability_web_search"],
+                # Attestation metadata - REUSABLE
+                "constraints": {
+                    "attestations": {
+                        "capability_web_search": {
+                            "approval_criteria": "role:admin",
+                            "timeout": 300,       # 5 min to approve
+                            "one_time": False,    # KEY: Reusable!
+                            "time_to_live": 3600  # Valid for 1 hour (or None for forever)
+                        }
+                    }
+                }
+            }
+        )
+
+        if not researcher.register():
+            print("  ERROR: Failed to register researcher agent")
+            search_service.unregister()
+            return 1
+
+        print(f"  Agent ID: {researcher.agent_id}")
+        print(f"  one_time=False (REUSABLE capability)")
+
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        search_service.unregister()
+        return 1
+
+    # Step 4: First invocation - should BLOCK for approval
+    print("\n" + "=" * 60)
+    print("FIRST INVOCATION - Will block for admin approval")
+    print("=" * 60)
+    print("\n  >>> Run 1b_grant_admin.py in another terminal <<<")
+    print("-" * 60)
+
+    start_time = time.time()
+    try:
+        result = researcher.invoke_tool(
+            tool_name="tool:search/web_search",
+            target_agent=search_service.agent_id,
+            parameters={"query": "MACAW security framework"}
+        )
+        elapsed = time.time() - start_time
+        print(f"\n  FIRST SEARCH COMPLETED! (took {elapsed:.1f}s)")
+        print(f"  Result: {json.dumps(result, indent=2)}")
+
+    except Exception as e:
+        print(f"\n  ERROR on first invocation: {e}")
+        researcher.unregister()
+        search_service.unregister()
+        return 1
+
+    # Step 5: Second invocation - should be IMMEDIATE (no blocking!)
+    print("\n" + "=" * 60)
+    print("SECOND INVOCATION - Should be IMMEDIATE (reusing approval)")
+    print("=" * 60)
+
+    start_time = time.time()
+    try:
+        result = researcher.invoke_tool(
+            tool_name="tool:search/web_search",
+            target_agent=search_service.agent_id,
+            parameters={"query": "AI agent governance"}
+        )
+        elapsed = time.time() - start_time
+        print(f"\n  SECOND SEARCH COMPLETED! (took {elapsed:.1f}s)")
+        if elapsed < 2.0:
+            print("  *** REUSED EXISTING APPROVAL - NO BLOCKING! ***")
+        print(f"  Result: {json.dumps(result, indent=2)}")
+
+    except Exception as e:
+        print(f"\n  ERROR on second invocation: {e}")
+
+    # Step 6: Third invocation - also immediate
+    print("\n" + "=" * 60)
+    print("THIRD INVOCATION - Also immediate")
+    print("=" * 60)
+
+    start_time = time.time()
+    try:
+        result = researcher.invoke_tool(
+            tool_name="tool:search/web_search",
+            target_agent=search_service.agent_id,
+            parameters={"query": "enterprise AI security"}
+        )
+        elapsed = time.time() - start_time
+        print(f"\n  THIRD SEARCH COMPLETED! (took {elapsed:.1f}s)")
+        if elapsed < 2.0:
+            print("  *** REUSED EXISTING APPROVAL - NO BLOCKING! ***")
+
+    except Exception as e:
+        print(f"\n  ERROR on third invocation: {e}")
+
+    # Cleanup
+    print("\n[Cleanup] Unregistering agents...")
+    researcher.unregister()
+    search_service.unregister()
+
+    print("\n" + "=" * 60)
+    print("Example 1b Complete!")
+    print("First invocation required approval, subsequent were immediate.")
+    print("=" * 60)
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    try:
+        sys.exit(main())
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "Local provider does not support" in err:
+            print("ERROR: Identity Provider not configured")
+            print("Fix: Console -> Settings -> Identity Bridge")
+        elif "Connection refused" in err or "connect" in err.lower():
+            print("ERROR: Cannot connect to MACAW")
+            print("Fix: Ensure LocalAgent is running")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)

package/payload/secureAI/examples/attestations/README.md

@@ -0,0 +1,128 @@
+# External Attestations Examples
+
+These examples demonstrate **human-in-the-loop approval workflows** using MACAW's external attestation system.
+
+## What Are External Attestations?
+
+External attestations require a **third party** (manager, admin, compliance officer) to approve an operation before it can proceed. The request **blocks** while waiting for approval.
+
+**Use cases:**
+- High-value trades requiring manager sign-off
+- Sensitive operations needing compliance review
+- Capability grants for elevated access
+- Time-boxed permissions
+
+## Examples
+
+### Example 1a: One-Time Trade Approval
+
+A high-value trade ($15,000) requires manager approval. Each trade needs fresh approval.
+
+| File | Role | What It Does |
+|------|------|--------------|
+| `1a_trade_alice.py` | Requester | Requests trade, blocks waiting for approval |
+| `1a_trade_bob.py` | Approver | Lists pending requests, approves/denies |
+
+**Key concepts:**
+- Conditional attestation: `trade-approved::{params.amount > 10000}`
+- Role-based approval: `approval_criteria: "role:manager"`
+- One-time use: `one_time: True` (consumed after single use)
+
+**Run:**
+```bash
+# Terminal 1: Alice requests trade (blocks)
+python 1a_trade_alice.py
+
+# Terminal 2: Bob approves (while Alice waits)
+python 1a_trade_bob.py
+```
+
+### Example 1b: Reusable Capability Grant
+
+A researcher needs admin approval for web search capability. Approve once, use many times.
+
+| File | Role | What It Does |
+|------|------|--------------|
+| `1b_grant_researcher.py` | Requester | First call blocks, subsequent calls instant |
+| `1b_grant_admin.py` | Approver | Grants reusable capability |
+
+**Key concepts:**
+- Reusable grant: `one_time: False`
+- Time-to-live: `time_to_live: 3600` (1 hour)
+- First call blocks, second+ calls immediate
+
+**Run:**
+```bash
+# Terminal 1: Researcher requests (blocks on first call)
+python 1b_grant_researcher.py
+
+# Terminal 2: Admin approves (while researcher waits)
+python 1b_grant_admin.py
+
+# Watch Terminal 1: First call completes, then 2nd and 3rd are instant!
+```
+
+## Prerequisites
+
+1. **MACAW LocalAgent running:**
+   ```bash
+   python3 -m macaw_agent.main
+   ```
+
+2. **Identity provider configured** (Keycloak or Auth0)
+   - See `demos/tutorial-1/setup/` for setup scripts
+
+3. **Users created in IDP:**
+   - `alice` - trader/researcher
+   - `bob` - manager/admin with appropriate role
+
+## Key APIs
+
+### Requester Side
+
+```python
+from macaw_client import MACAWClient
+
+# Define attestation in policy
+intent_policy = {
+    "attestations": ["trade-approved::{params.amount > 10000}"],
+    "constraints": {
+        "attestations": {
+            "trade-approved": {
+                "approval_criteria": "role:manager",
+                "timeout": 300,       # Block up to 5 minutes
+                "one_time": True      # Or False for reusable
+            }
+        }
+    }
+}
+
+# invoke_tool blocks until approved/denied/timeout
+result = client.invoke_tool("tool:trading/execute", params)
+```
+
+### Approver Side
+
+```python
+from macaw_client import MACAWClient
+
+# List pending attestations you can approve
+attestations = client.list_attestations(status="pending")
+
+# Approve or deny
+client.approve_attestation(att, reason="Approved for Q4")
+client.deny_attestation(att, reason="Budget exceeded")
+```
+
+## One-Time vs Reusable
+
+| Setting | Behavior | Use Case |
+|---------|----------|----------|
+| `one_time: True` | Consumed after single use | High-value trades |
+| `one_time: False` | Reusable until TTL expires | Capability grants |
+
+## Learn More
+
+- **MAPL Policy Guide**: Full attestation syntax and semantics
+- **Dev Hub Tutorials**: Step-by-step walkthrough with diagrams
+- **Console > Activity**: View attestation audit events

package/payload/secureAI/examples/langchain/langchain_1a_dropin_simple.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+langchain_1a_dropin_simple.py - Drop-in replacement for LangChain agents
+
+The simplest integration path - replace your LangChain imports and add policy.
+No Identity Provider needed.
+
+Prerequisites:
+    - MACAW SDK installed (pip install macaw-client macaw-adapters)
+    - OPENAI_API_KEY environment variable (for ChatOpenAI)
+
+Run:
+    export OPENAI_API_KEY=sk-...
+    python langchain_1a_dropin_simple.py
+"""
+
+import os
+import sys
+
+# BEFORE: from langchain.agents import create_react_agent, AgentExecutor
+# AFTER:
+from macaw_adapters.langchain import create_react_agent, AgentExecutor, cleanup
+
+from langchain_openai import ChatOpenAI
+from langchain.tools import Tool
+from langchain.prompts import PromptTemplate
+
+
+# Define some tools
+def calculator(expression: str) -> str:
+    """Evaluate a math expression."""
+    try:
+        result = eval(expression)
+        return f"Result: {result}"
+    except Exception as e:
+        return f"Error: {e}"
+
+
+def get_weather(city: str) -> str:
+    """Get weather for a city (mock)."""
+    # Mock weather data
+    weather_data = {
+        "new york": "72°F, Sunny",
+        "london": "58°F, Cloudy",
+        "tokyo": "68°F, Clear"
+    }
+    return weather_data.get(city.lower(), f"Weather for {city}: 65°F, Partly cloudy")
+
+
+def admin_tool(command: str) -> str:
+    """Execute admin command (dangerous!)."""
+    return f"Executed admin command: {command}"
+
+
+# Create tools list
+TOOLS = [
+    Tool(
+        name="calculator",
+        func=calculator,
+        description="Useful for math calculations. Input should be a math expression."
+    ),
+    Tool(
+        name="weather",
+        func=get_weather,
+        description="Get current weather for a city. Input should be a city name."
+    ),
+    Tool(
+        name="admin",
+        func=admin_tool,
+        description="Execute admin commands. Input should be a command string."
+    ),
+]
+
+
+# Simple ReAct prompt template
+REACT_PROMPT = PromptTemplate.from_template("""Answer the following questions as best you can. You have access to the following tools:
+
+{tools}
+
+Use the following format:
+
+Question: the input question you must answer
+Thought: you should always think about what to do
+Action: the action to take, should be one of [{tool_names}]
+Action Input: the input to the action
+Observation: the result of the action
+... (this Thought/Action/Action Input/Observation can repeat N times)
+Thought: I now know the final answer
+Final Answer: the final answer to the original input question
+
+Begin!
+
+Question: {input}
+Thought:{agent_scratchpad}""")
+
+
+def main():
+    # Check for API key
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY environment variable")
+        print("  export OPENAI_API_KEY=sk-...")
+        return
+
+    print("=" * 60)
+    print("Example 1a: Drop-in Replacement (LangChain)")
+    print("=" * 60)
+    print("\nPath: Direct agent with security_policy")
+    print("Use when: Single app, need tool access control")
+
+    # Create LLM
+    llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
+
+    # Create agent WITH security policy
+    # - Only "calculator" and "weather" are allowed
+    # - "admin" tool is blocked
+    # - Queries containing "password" are blocked
+    print("\n--- Creating secure agent ---")
+    print("Policy: Allow calculator & weather, block admin")
+    print("        Block queries with '*password*'")
+
+    # MAPL format policy - direct, no conversion layer
+    policy = {
+        "resources": ["tool:calculator", "tool:weather"],  # Allowed tools
+        "denied_resources": ["tool:admin"],                 # Blocked tools
+        "constraints": {
+            "denied_parameters": {
+                "tool:*": {"input": ["*password*", "*secret*"]}  # Block sensitive queries
+            }
+        }
+    }
+
+    agent = create_react_agent(
+        llm=llm,
+        tools=TOOLS,
+        prompt=REACT_PROMPT,
+        security_policy=policy
+    )
+
+    # Create executor with same policy
+    executor = AgentExecutor(
+        agent=agent,
+        tools=TOOLS,
+        security_policy=policy,
+        verbose=True,
+        handle_parsing_errors=True,
+        max_iterations=3
+    )
+
+    # Test 1: Allowed tool (calculator)
+    print("\n--- Test 1: Allowed tool (calculator) ---")
+    try:
+        result = executor.invoke({"input": "What is 15 * 7 + 23?"})
+        print(f"Result: {result.get('output', result)}")
+    except Exception as e:
+        print(f"Error: {e}")
+
+    # Test 2: Allowed tool (weather)
+    print("\n--- Test 2: Allowed tool (weather) ---")
+    try:
+        result = executor.invoke({"input": "What's the weather in Tokyo?"})
+        print(f"Result: {result.get('output', result)}")
+    except Exception as e:
+        print(f"Error: {e}")
+
+    # Test 3: Blocked tool (admin) - should be denied
+    print("\n--- Test 3: Blocked tool (admin) - SHOULD BE DENIED ---")
+    try:
+        result = executor.invoke({"input": "Run admin command: list users"})
+        print(f"Result: {result.get('output', result)}")
+        # If agent can't use admin tool, it should say it can't do this
+    except Exception as e:
+        error_msg = str(e).lower()
+        if "denied" in error_msg or "blocked" in error_msg or "policy" in error_msg:
+            print(f"Correctly blocked: {e}")
+        else:
+            print(f"Error: {e}")
+
+    # Cleanup
+    print("\n--- Cleanup ---")
+    cleanup()
+
+    print("\n" + "=" * 60)
+    print("Example complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        err = str(e)
+        print("\n" + "=" * 60)
+        if "OPENAI_API_KEY" in err or "api_key" in err.lower():
+            print("ERROR: OpenAI API key not configured")
+            print("Fix: export OPENAI_API_KEY=sk-...")
+        else:
+            print(f"ERROR: {e}")
+        print("=" * 60)
+        sys.exit(1)