@macaw-ai/client 0.0.0-stage → 0.9.11

package/payload/secureAI/examples/pydantic_ai/pydanticai_1d_multiuser_bind.py

@@ -0,0 +1,104 @@
+"""
+Per-user policy on a shared agent.
+
+One SecureAgent is built once for the service. bind_to_user() returns an agent
+that issues every invocation as that user, so MACAW evaluates alice's and bob's
+policies against the same application resources.
+
+    service = SecureAgent(model, app_name="pydantic-agent", tools=[...])
+    alice_agent = service.bind_to_user(alice_client)
+
+The registration and the tools are shared; only the caller identity differs.
+
+Prerequisites:
+    export OPENAI_API_KEY=sk-...
+    MACAW LocalAgent running
+    Identity provider running with the demo users (Keycloak or Auth0)
+    Workspace policies for user:alice and user:bob covering tool:pydantic-agent/*
+
+Run:
+    python pydanticai_1d_multiuser_bind.py
+"""
+
+import os
+import sys
+
+from macaw_client import MACAWClient, PermissionDenied, RemoteIdentityProvider
+from pydantic_ai.models.openai import OpenAIChatModel
+
+from macaw_adapters.pydantic_ai import SecureAgent
+
+APP_NAME = "pydantic-agent"
+GENERATE = f"tool:{APP_NAME}/generate"
+
+USERS = [("alice", "Alice123!"), ("bob", "Bob@123!")]
+
+
+def query_catalog(table: str, limit: int = 10) -> str:
+    """Query the data catalog for rows from a table."""
+    return f"{limit} rows from {table}"
+
+
+def export_dataset(table: str) -> str:
+    """Export a full dataset to external storage."""
+    return f"exported {table}"
+
+
+def login(username: str, password: str):
+    """Authenticate against the identity provider and register a user agent."""
+    jwt_token, _ = RemoteIdentityProvider().login(username, password)
+    user = MACAWClient(
+        user_name=username,
+        iam_token=jwt_token,
+        agent_type="user",
+        app_name=APP_NAME,
+    )
+    if not user.register():
+        raise RuntimeError(f"Failed to register user agent for {username}")
+    return user
+
+
+def main() -> int:
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY first:")
+        print("  export OPENAI_API_KEY=sk-...")
+        return 1
+
+    # One service agent, shared by every user.
+    service = SecureAgent(
+        OpenAIChatModel("gpt-4o-mini"),
+        app_name=APP_NAME,
+        tools=[query_catalog, export_dataset],
+        intent_policy={"resources": [GENERATE, f"tool:{APP_NAME}/*"]},
+    )
+    print(f"Service registered: {service._macaw.server_id}")
+
+    for username, password in USERS:
+        print(f"\n=== {username} ===")
+        try:
+            user = login(username, password)
+        except Exception as e:
+            print(f"  login failed: {e}")
+            print("  Is the identity provider running? See demos/tutorial-1/setup/")
+            continue
+
+        agent = service.bind_to_user(user)
+
+        for prompt in (
+            "Use query_catalog on the customers table with limit 3.",
+            "Export the customers table using export_dataset.",
+        ):
+            try:
+                result = agent.run_sync(prompt)
+                print(f"  {result.output}")
+            except PermissionDenied as e:
+                print(f"  denied by MACAW: {e}")
+
+        user.unregister()
+
+    print("\nSame agent, same tools. The difference is whose policy was resolved.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/payload/secureAI/examples/pydantic_ai/pydanticai_1e_mcp_compose.py

@@ -0,0 +1,92 @@
+"""
+Local tools and an MCP server in one agent.
+
+A Pydantic AI agent can mix tools it owns with tools reached over MCP. Both are
+governed, but at different boundaries:
+
+    local functions   registered with MACAW and dispatched by it
+                      -> tool:pydantic-agent/<name>
+
+    MCP tools         authorized here under the caller's identity, then executed
+                      by the server, which SecureMCP governs on its own side
+                      -> tool:pydantic-agent/<name>   (this agent)
+                      -> tool:securemcp-calculator/<name>  (the server)
+
+The agent-side check is the one that carries the user's identity, because an MCP
+connection has none of its own.
+
+This example runs examples/mcp/securemcp_calculator.py as a subprocess over
+stdio, the same way examples/mcp/3a_native_mcp_client.py does.
+
+Prerequisites:
+    export OPENAI_API_KEY=sk-...
+    MACAW LocalAgent running
+    Workspace policy allowing tool:pydantic-agent/*
+
+Run:
+    python pydanticai_1e_mcp_compose.py
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from pydantic_ai.mcp import MCPToolset, StdioTransport
+from pydantic_ai.models.openai import OpenAIChatModel
+
+from macaw_adapters.pydantic_ai import SecureAgent
+
+APP_NAME = "pydantic-agent"
+GENERATE = f"tool:{APP_NAME}/generate"
+
+CALCULATOR = Path(__file__).resolve().parents[1] / "mcp" / "securemcp_calculator.py"
+
+
+def describe_result(value: str) -> str:
+    """Write a one-line description of a calculation result."""
+    return f"result recorded: {value}"
+
+
+async def main() -> int:
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("Set OPENAI_API_KEY first:")
+        print("  export OPENAI_API_KEY=sk-...")
+        return 1
+
+    if not CALCULATOR.exists():
+        print(f"Calculator server not found: {CALCULATOR}")
+        return 1
+
+    # env is passed through so the server subprocess can import macaw_adapters
+    # when running from a source checkout rather than an installed package.
+    calculator = MCPToolset(
+        StdioTransport(
+            command=sys.executable,
+            args=[str(CALCULATOR), "stdio"],
+            env=dict(os.environ),
+        )
+    )
+
+    agent = SecureAgent(
+        OpenAIChatModel("gpt-4o-mini"),
+        app_name=APP_NAME,
+        tools=[describe_result],          # owned: MACAW dispatches these
+        toolsets=[calculator],            # MCP: MACAW authorizes, server executes
+        intent_policy={"resources": [GENERATE, f"tool:{APP_NAME}/*"]},
+    )
+    print(f"Registered: {agent._macaw.server_id}")
+    print(f"Local tools: describe_result")
+    print(f"MCP server : {CALCULATOR.name}")
+
+    result = await agent.run(
+        "Add 17 and 25 using the calculator, then describe the result."
+    )
+    print(f"\n{result.output}")
+    print("\nBoth tools were invoked through MACAW under this agent's identity.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

package/payload/secureAI/macaw_adapters/__init__.py

@@ -0,0 +1,55 @@
+"""
+MACAW Adapters - Secure AI Adapters for Enterprise
+
+Security adapters for popular AI frameworks including OpenAI, Anthropic,
+LangChain, LiteLLM (100+ providers), and MCP (Model Context Protocol).
+
+Usage:
+    from macaw_adapters.openai import SecureOpenAI
+    from macaw_adapters.anthropic import SecureAnthropic
+    from macaw_adapters.langchain.agents import create_react_agent, AgentExecutor
+    from macaw_adapters.mcp import SecureMCP
+
+    # LiteLLM - drop-in replacement supporting 100+ providers
+    from macaw_adapters import litellm
+    response = litellm.completion(model="groq/llama3-70b", messages=[...])
+
+Prerequisites:
+    - MACAW Client Library: Download from https://macawsecurity.ai
+    - Free Account: Create at https://console.macawsecurity.ai
+
+For more information, visit: https://macawsecurity.ai
+"""
+
+__version__ = "0.9.10.1"
+__author__ = "MACAW Security"
+__license__ = "Apache-2.0"
+
+# Lazy imports - only load adapters when explicitly imported
+# This allows using one adapter without installing dependencies for others
+# e.g., `from macaw_adapters.mcp import SecureMCP` works without openai installed
+
+__all__ = [
+    "openai",
+    "anthropic",
+    "langchain",
+    "litellm",
+    "mcp",
+    "pydantic_ai",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    """
+    Lazy import adapters only when accessed.
+
+    Imported by full module path: an adapter shares its name with the package it
+    wraps (openai, mcp, pydantic_ai, ...), and `from macaw_adapters import <name>`
+    falls back to this function for those, which recurses.
+    """
+    if name in ("openai", "anthropic", "langchain", "litellm", "mcp", "pydantic_ai"):
+        import importlib
+
+        return importlib.import_module(f"macaw_adapters.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

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

@@ -0,0 +1,374 @@
+# SecureAnthropic Reference
+
+Drop-in replacement for Anthropic Claude client with MACAW security. Supports three usage paths for different scenarios.
+
+## Installation
+
+```python
+from macaw_adapters.anthropic import SecureAnthropic
+```
+
+Install the package:
+```bash
+pip install -e /path/to/secureAI
+```
+
+---
+
+## When to Use Each Path
+
+| Scenario | Path | Example |
+|----------|------|---------|
+| Simple app, no user distinction | Direct on service | `client.messages.create()` |
+| Multi-user, per-user policies | bind_to_user | `service.bind_to_user(user_client)` |
+| A2A communication, explicit control | invoke_tool | `user.invoke_tool("tool:xxx/generate", ...)` |
+| CLI tool, single operator | Direct on service | `client.messages.create()` |
+| SaaS with user accounts | bind_to_user | Different users = different permissions |
+
+### Why bind_to_user?
+
+Without `bind_to_user`, everyone uses the **service's identity**. With `bind_to_user`, each user's **JWT identity flows through** for policy evaluation.
+
+This enables scenarios like:
+- Alice: Claude Haiku only, max 500 tokens
+- Bob: Claude Haiku/Sonnet/Opus, max 2000 tokens
+
+Same service, different permissions based on WHO is calling.
+
+---
+
+## Path 1: Direct on Service (Simplest)
+
+```python
+from macaw_adapters.anthropic import SecureAnthropic
+
+# Just like using regular Anthropic client
+client = SecureAnthropic(
+    app_name="my-app",
+    intent_policy={"purpose": "financial analysis"}
+)
+
+# Same API as Anthropic
+response = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=500,
+    messages=[{"role": "user", "content": "What is compound interest?"}]
+)
+
+print(response.content[0].text)
+```
+
+**Use when**: Single app, no user distinction, app-level policies.
+
+---
+
+## Path 2: bind_to_user (Multi-user)
+
+```python
+from macaw_adapters.anthropic import SecureAnthropic
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+# 1. Create SINGLE service (shared across all users)
+service = SecureAnthropic(app_name="financial-service")
+
+# 2. User login -> JWT -> MACAWClient
+jwt_token, _ = RemoteIdentityProvider().login("alice", "Alice123!")
+user = MACAWClient(
+    user_name="alice",
+    iam_token=jwt_token,
+    agent_type="user",
+    app_name="financial-app"
+)
+user.register()
+
+# 3. Bind user to service
+user_anthropic = service.bind_to_user(user)
+
+# 4. Same API, user's identity flows through for policy evaluation
+response = user_anthropic.messages.create(
+    model="claude-3-haiku-20240307",
+    max_tokens=500,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+
+# 5. Cleanup when user session ends
+user_anthropic.unbind()
+```
+
+**Use when**: SaaS app, different users need different permissions.
+
+---
+
+## Path 3: invoke_tool (A2A)
+
+```python
+from macaw_adapters.anthropic import SecureAnthropic
+from macaw_client import MACAWClient, RemoteIdentityProvider
+
+# 1. Create Anthropic service
+service = SecureAnthropic(app_name="anthropic-service")
+
+# 2. Create user agent
+jwt_token, _ = RemoteIdentityProvider().login("alice", "Alice123!")
+user = MACAWClient(
+    user_name="alice",
+    iam_token=jwt_token,
+    agent_type="user",
+    app_name="my-agent"
+)
+user.register()
+
+# 3. Explicit invoke_tool - you control everything
+result = user.invoke_tool(
+    tool_name="tool:anthropic-service/generate",  # MAPL tool name
+    parameters={
+        "model": "claude-3-haiku-20240307",
+        "max_tokens": 500,
+        "messages": [{"role": "user", "content": "What is compound interest?"}]
+    },
+    target_agent=service.server_id  # Explicit routing
+)
+
+# Result is raw dict
+content = result["content"][0]["text"]
+```
+
+**Use when**: Building agent systems, need explicit control, cross-service communication.
+
+---
+
+## SecureAnthropic Class
+
+```python
+client = SecureAnthropic(
+    api_key="sk-ant-...",       # Optional: uses ANTHROPIC_API_KEY env var
+    app_name="my-app",          # Application name for MACAW registration
+    intent_policy={...},        # Application-defined security policy (MAPL format)
+    jwt_token="...",            # Optional: creates user-mode client
+    user_name="alice"           # Optional: user name for user mode
+)
+```
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | str | env var | Anthropic API key |
+| `app_name` | str | `"secure-anthropic-app"` | Application name for MACAW |
+| `intent_policy` | dict | `{}` | Security policy (MAPL format) |
+| `jwt_token` | str | None | JWT token for user mode |
+| `user_name` | str | None | User name for user mode |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client.server_id` | str | Agent ID after registration |
+| `client.macaw_client` | MACAWClient | MACAW client instance |
+| `client.anthropic_client` | Anthropic | Underlying Anthropic client |
+| `client._mode` | str | "service" or "user" |
+
+### Methods
+
+#### bind_to_user(user_client) -> BoundSecureAnthropic
+
+Bind service to a user's MACAW client for per-user identity.
+
+```python
+user_anthropic = service.bind_to_user(user_client)
+```
+
+Only valid in service mode. Returns `BoundSecureAnthropic` wrapper.
+
+#### register_tool(name, handler) -> SecureAnthropic
+
+Register a tool that Claude can call.
+
+```python
+client.register_tool("get_weather", get_weather_fn)
+```
+
+---
+
+## BoundSecureAnthropic Class
+
+Per-user wrapper created via `bind_to_user()`.
+
+```python
+user_anthropic = service.bind_to_user(user_client)
+
+# Same API as SecureAnthropic
+response = user_anthropic.messages.create(...)
+
+# Check binding status
+if user_anthropic.is_bound:
+    ...
+
+# Cleanup
+user_anthropic.unbind()
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `is_bound` | bool | Whether wrapper is still bound |
+| `service` | SecureAnthropic | The bound service (raises if unbound) |
+| `user_client` | MACAWClient | The bound user client (raises if unbound) |
+
+### Methods
+
+#### unbind()
+
+Invalidate this binding. All future calls will raise `RuntimeError`.
+
+---
+
+## API Surface
+
+SecureAnthropic mirrors the Anthropic API structure:
+
+```python
+# Messages API (primary)
+response = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "..."}],
+    tools=[...]  # Optional: auto-discovered
+)
+
+# Completions API (legacy)
+response = client.completions.create(
+    model="claude-2.1",
+    prompt="..."
+)
+```
+
+---
+
+## MAPL Tool Names
+
+SecureAnthropic uses MAPL-compliant tool names:
+
+| Operation | Tool Name |
+|-----------|-----------|
+| Messages | `tool:{app_name}/generate` |
+| Completions | `tool:{app_name}/complete` |
+
+Example: If `app_name="anthropic-service"`, the generate tool is `tool:anthropic-service/generate`.
+
+---
+
+## Tool Auto-Discovery
+
+SecureAnthropic automatically discovers tool implementations from the caller's scope:
+
+```python
+# Define tools in your code
+def get_weather(location: str) -> str:
+    return f"Weather in {location}: Sunny, 72F"
+
+# Define tool schemas for Claude
+tools = [
+    {
+        "name": "get_weather",  # Must match function name
+        "description": "Get weather for a location",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "City name"}
+            },
+            "required": ["location"]
+        }
+    }
+]
+
+# Tools are auto-discovered and routed through MACAW PEP
+response = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
+    tools=tools
+)
+```
+
+---
+
+## Intent Policy Format (MAPL)
+
+```python
+intent_policy = {
+    # Deny access to sensitive resources
+    "denied_resources": ["*password*", "*credential*", "*secret*"],
+
+    # Allow specific resources
+    "resources": ["tool:get_weather", "tool:search_files"],
+
+    # Parameter constraints
+    "constraints": {
+        "parameters": {
+            "tool:search_files": {
+                "path": ["*public*", "*reports*"]
+            }
+        },
+        "denied_parameters": {
+            "tool:*": {
+                "query": ["*password*"]
+            }
+        }
+    },
+
+    # Application metadata
+    "purpose": "weather and file search app"
+}
+```
+
+---
+
+## Authenticated Prompts
+
+SecureAnthropic supports authenticated prompts for cryptographic proof of prompt origin:
+
+```python
+# Tools declare which parameters are prompts
+self.tools = {
+    f"tool:{self.app_name}/generate": {
+        "handler": self._handle_generate,
+        "prompts": ["messages"]  # messages param is authenticated
+    }
+}
+```
+
+Authenticated prompts are auto-created when `agent.authenticate_prompts` is enabled.
+
+---
+
+## Migration from Anthropic
+
+```python
+# Before
+from anthropic import Anthropic
+client = Anthropic()
+
+# After (drop-in replacement)
+from macaw_adapters.anthropic import SecureAnthropic
+client = SecureAnthropic(
+    app_name="my-app",
+    intent_policy={"denied_resources": ["*sensitive*"]}
+)
+
+# Same API - no other code changes needed
+response = client.messages.create(...)
+```
+
+---
+
+## Key Differences from OpenAI Adapter
+
+| Feature | SecureAnthropic | SecureOpenAI |
+|---------|-----------------|--------------|
+| Tool Schema | `input_schema` | `parameters` in `function` |
+| Tool Type | Direct name | `type: "function"` wrapper |
+| Response | `content` blocks | `message.tool_calls` |
+| Continuation | `tool_result` in user message | `tool` role message |
+| Primary API | `messages.create()` | `chat.completions.create()` |

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

@@ -0,0 +1,22 @@
+"""
+MACAW Anthropic Adapter - Secure drop-in replacement for Anthropic client.
+
+Usage:
+    # Before
+    from anthropic import Anthropic
+    client = Anthropic()
+
+    # After (one line change!)
+    from macaw_adapters.anthropic import SecureAnthropic
+    client = SecureAnthropic()
+
+Features:
+    - Drop-in replacement for Anthropic client
+    - Policy-enforced tool execution
+    - Cryptographic audit trail
+    - Multi-user identity binding
+"""
+
+from macaw_adapters.anthropic.secure_anthropic import SecureAnthropic
+
+__all__ = ["SecureAnthropic"]