chore: import upstream snapshot with attribution

python/samples/05-end-to-end/purview_agent/README.md

@@ -0,0 +1,168 @@
+## Purview Policy Enforcement Sample (Python)
+
+This getting-started sample shows how to attach Microsoft Purview policy evaluation to an Agent Framework `Agent` using the **middleware** approach.
+
+**What this sample demonstrates:**
+1. Configure a Foundry chat client
+2. Add Purview policy enforcement middleware (`PurviewPolicyMiddleware`)
+3. Add Purview policy enforcement at the chat client level (`PurviewChatPolicyMiddleware`)
+4. Implement a custom cache provider for advanced caching scenarios
+5. Run conversations and observe prompt / response blocking behavior
+
+**Note:** Caching is **automatic** and enabled by default with sensible defaults (30-minute TTL, 200MB max size).
+
+---
+## 1. Setup
+### Required Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `FOUNDRY_PROJECT_ENDPOINT` | Yes | Azure AI Foundry project endpoint, for example `https://<resource>.services.ai.azure.com/api/projects/<project>` |
+| `FOUNDRY_MODEL` | Optional | Model deployment name (defaults to `gpt-4o-mini`) |
+| `PURVIEW_CLIENT_APP_ID` | Yes* | Client (application) ID used for Purview authentication |
+| `PURVIEW_USE_CERT_AUTH` | Optional (`true`/`false`) | Switch between certificate and interactive auth |
+| `PURVIEW_TENANT_ID` | Yes (when cert auth on) | Tenant ID for certificate authentication |
+| `PURVIEW_CERT_PATH` | Yes (when cert auth on) | Path to your .pfx certificate |
+| `PURVIEW_CERT_PASSWORD` | Optional | Password for encrypted certs |
+
+### 2. Auth Modes Supported
+
+#### A. Interactive Browser Authentication (default)
+Opens a browser on first run to sign in.
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"
+$env:FOUNDRY_MODEL = "gpt-4o-mini"
+$env:PURVIEW_CLIENT_APP_ID = "00000000-0000-0000-0000-000000000000"
+```
+
+#### B. Certificate Authentication
+For headless / CI scenarios.
+
+```powershell
+$env:PURVIEW_USE_CERT_AUTH = "true"
+$env:PURVIEW_TENANT_ID = "<tenant-guid>"
+$env:PURVIEW_CERT_PATH = "C:\path\to\cert.pfx"
+$env:PURVIEW_CERT_PASSWORD = "optional-password"
+```
+
+Certificate steps (summary): create / register entra app, generate certificate, upload public key, export .pfx with private key, grant required Graph / Purview permissions.
+
+---
+
+## 3. Run the Sample
+
+From repo root:
+
+```powershell
+cd python/samples/05-end-to-end/purview_agent
+python sample_purview_agent.py
+```
+
+If interactive auth is used, a browser window will appear the first time.
+
+---
+
+## 4. How It Works
+
+The sample demonstrates four integration scenarios. Each scenario runs the same three-message sequence via `run_policy_flow(...)`:
+
+1. **good (cold cache)** - a benign prompt that exercises the cold-cache parallel ProtectionScopes warmup + foreground ProcessContent path.
+2. **expected block** - a sensitive prompt containing the Visa test credit card number `4111 1111 1111 1111`. If the tenant has a DLP policy for `Microsoft 365 Copilot and AI apps` targeting the Credit Card sensitive info type with a Block action, this prompt returns the configured `blocked_prompt_message` (default: `Prompt blocked by policy`). If no DLP policy applies, the prompt is allowed (the LLM may still decline on its own, but that is a model-level response, not a Purview block).
+3. **good (warm cache)** - a second benign prompt that exercises the warm-cache path. The custom cache provider scenario prints `Cache HIT` for the same protection-scopes key, confirming the cache and middleware state survive a prior block.
+
+### A. Agent Middleware (`run_with_agent_middleware`)
+1. Builds a Foundry chat client (using the environment project endpoint / deployment)
+2. Chooses credential mode (certificate vs interactive)
+3. Creates `PurviewPolicyMiddleware` with `PurviewSettings`
+4. Injects middleware into the agent at construction
+5. Runs the three-message `good -> block -> good` orchestration
+6. Prints `ALLOWED` or `BLOCKED` per message, plus the model response
+7. Uses default caching automatically
+
+### B. Chat Client Middleware (`run_with_chat_middleware`)
+1. Creates a chat client with `PurviewChatPolicyMiddleware` attached directly
+2. Policy evaluation happens at the chat client level rather than agent level
+3. Demonstrates an alternative integration point for Purview policies
+4. Runs the same `good -> block -> good` orchestration
+5. Uses default caching automatically
+
+### C. Custom Cache Provider (`run_with_custom_cache_provider`)
+1. Implements the `CacheProvider` protocol with a custom class (`SimpleDictCacheProvider`)
+2. Shows how to add custom logging and metrics to cache operations
+3. The custom provider must implement three async methods:
+   - `async def get(self, key: str) -> Any | None`
+   - `async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None`
+   - `async def remove(self, key: str) -> None`
+4. Runs the `good -> block -> good` orchestration and prints `Cache MISS`/`Cache HIT` traces alongside policy outcomes, showing the cold-cache warmup populating the cache and warm-cache requests skipping ProtectionScopes.
+
+### D. Default Cache (`run_with_default_cache`)
+1. Same as the agent middleware path but with explicit cache TTL and size limits in `PurviewSettings`
+2. Uses the default in-memory `CacheProvider`
+3. Runs the `good -> block -> good` orchestration
+
+**Policy Behavior:**
+Prompt blocks substitute the configured `blocked_prompt_message` (default `Prompt blocked by policy`) and terminate the agent run early. Response blocks substitute `blocked_response_message`. The LLM is never called for a blocked prompt.
+
+**Seeing a real `BLOCKED` outcome:**
+The middle prompt only returns `BLOCKED` if the tenant actually has a Purview DLP policy that matches the request. Specifically, all of the following must be true:
+
+1. The Entra app id used by `PURVIEW_CLIENT_APP_ID` (the same id Agent Framework sends as `policyLocationApplication.value`) is registered as an integrated AI app in Purview (Settings -> AI app and agent locations).
+2. A DLP policy in the tenant targets the location `Microsoft 365 Copilot and AI apps`, scoped to that app id (or `All apps`).
+3. The policy has a rule with the condition `Content contains -> Sensitive info types -> Credit Card Number` and an action of `Restrict access to Microsoft 365 Copilot and AI apps -> Block`.
+4. The policy is `On` (not `Test mode without notifications`).
+5. The signed-in user is in the policy's user scope.
+6. Required Graph delegated permissions are admin-consented: `ProtectionScopes.Compute.All`, `Content.Process.All`, `ContentActivity.Write`.
+
+If any of those are missing, the credit card prompt is allowed at the Purview layer. The model itself may still decline on its own; that response is a model-level refusal, not a Purview block. The cold/warm cache orchestration is still demonstrated either way - the `Cache MISS -> Cache HIT` trace from the custom cache scenario does not depend on a block firing.
+
+---
+
+## 5. Code Snippets
+
+### Agent Middleware Injection
+
+```python
+agent = Agent(
+	client=client,
+	instructions="You are good at telling jokes.",
+	name="Joker",
+	middleware=[
+		PurviewPolicyMiddleware(credential, PurviewSettings(app_name="Sample App"))
+	],
+)
+```
+
+### Custom Cache Provider Implementation
+
+This is only needed if you want to integrate with external caching systems.
+
+```python
+class SimpleDictCacheProvider:
+    """Custom cache provider that implements the CacheProvider protocol."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, Any] = {}
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value from the cache."""
+        return self._cache.get(key)
+
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Set a value in the cache."""
+        self._cache[key] = value
+
+    async def remove(self, key: str) -> None:
+        """Remove a value from the cache."""
+        self._cache.pop(key, None)
+
+# Use the custom cache provider
+custom_cache = SimpleDictCacheProvider()
+middleware = PurviewPolicyMiddleware(
+    credential,
+    PurviewSettings(app_name="Sample App"),
+    cache_provider=custom_cache,
+)
+```
+
+---

python/samples/05-end-to-end/purview_agent/sample_purview_agent.py

@@ -0,0 +1,312 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""Purview policy enforcement sample (Python).
+
+Shows:
+1. Creating a basic chat agent
+2. Adding Purview policy evaluation via AGENT middleware (agent-level)
+3. Adding Purview policy evaluation via CHAT middleware (chat-client level)
+4. Implementing a custom cache provider for advanced caching scenarios
+5. Running threaded conversations and printing results
+
+Note: Caching is automatic and enabled by default.
+
+Environment variables:
+- FOUNDRY_PROJECT_ENDPOINT (required) - Azure AI Foundry project endpoint URL
+- FOUNDRY_MODEL (optional, defaults to gpt-4o-mini)
+- PURVIEW_CLIENT_APP_ID (required)
+- PURVIEW_USE_CERT_AUTH (optional, set to "true" for certificate auth)
+- PURVIEW_TENANT_ID (required if certificate auth)
+- PURVIEW_CERT_PATH (required if certificate auth)
+- PURVIEW_CERT_PASSWORD (optional)
+- PURVIEW_DEFAULT_USER_ID (optional, user ID for Purview evaluation)
+"""
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import Agent, AgentResponse, Message
+from agent_framework.foundry import FoundryChatClient
+from agent_framework.microsoft import (
+    PurviewChatPolicyMiddleware,
+    PurviewPolicyMiddleware,
+    PurviewSettings,
+)
+from azure.identity import (
+    AzureCliCredential,
+    CertificateCredential,
+    InteractiveBrowserCredential,
+)
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+JOKER_NAME = "Joker"
+JOKER_INSTRUCTIONS = "You are good at telling jokes. Keep responses concise."
+
+# Sequential prompts to demonstrate good -> block -> good orchestration.
+# The sensitive prompt contains a Visa test credit card number that matches Purview's
+# built-in Credit Card sensitive information type. If the tenant has a DLP policy that
+# blocks credit card content for Microsoft 365 Copilot and AI apps, the second message
+# will be blocked and the third will verify that subsequent calls still flow normally
+# after a block.
+GOOD_PROMPT_PRIMARY = "Tell me a joke about a pirate."
+SENSITIVE_PROMPT = "My corporate credit card is 4111 1111 1111 1111. Please confirm receipt."
+GOOD_PROMPT_FOLLOWUP = "Another light joke please."
+
+
+async def run_policy_flow(
+    label: str,
+    agent: Agent,
+    user_id: str | None,
+    blocked_text: str,
+) -> None:
+    """Run a good -> block candidate -> good sequence and report each outcome."""
+    blocked_marker = blocked_text.lower()
+    prompts = [
+        ("good (cold cache)", GOOD_PROMPT_PRIMARY),
+        ("expected block", SENSITIVE_PROMPT),
+        ("good (warm cache)", GOOD_PROMPT_FOLLOWUP),
+    ]
+    for tag, text in prompts:
+        response: AgentResponse = await agent.run(Message("user", [text], additional_properties={"user_id": user_id}))
+        outcome = "BLOCKED" if blocked_marker in str(response).lower() else "ALLOWED"
+        print(f"[{label}] {tag}: {outcome}\n{response}\n")
+
+
+# Custom Cache Provider Implementation
+class SimpleDictCacheProvider:
+    """A simple custom cache provider that stores everything in a dictionary.
+
+    This example demonstrates how to implement the CacheProvider protocol.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the simple dictionary cache."""
+        self._cache: dict[str, Any] = {}
+        self._access_count: dict[str, int] = {}
+
+    async def get(self, key: str) -> Any | None:
+        """Get a value from the cache.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            The cached value or None if not found.
+        """
+        value = self._cache.get(key)
+        if value is not None:
+            self._access_count[key] = self._access_count.get(key, 0) + 1
+            print(f"[CustomCache] Cache HIT for key: {key[:50]}... (accessed {self._access_count[key]} times)")
+        else:
+            print(f"[CustomCache] Cache MISS for key: {key[:50]}...")
+        return value
+
+    async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
+        """Set a value in the cache.
+
+        Args:
+            key: The cache key.
+            value: The value to cache.
+            ttl_seconds: Time to live in seconds (ignored in this simple implementation).
+        """
+        self._cache[key] = value
+        print(f"[CustomCache] Cached value for key: {key[:50]}... (TTL: {ttl_seconds}s)")
+
+    async def remove(self, key: str) -> None:
+        """Remove a value from the cache.
+
+        Args:
+            key: The cache key.
+        """
+        if key in self._cache:
+            del self._cache[key]
+            self._access_count.pop(key, None)
+            print(f"[CustomCache] Removed key: {key[:50]}...")
+
+
+def _get_env(name: str, *, required: bool = True, default: str | None = None) -> str:
+    val = os.environ.get(name, default)
+    if required and not val:
+        raise RuntimeError(f"Environment variable {name} is required")
+    return val  # type: ignore[return-value]
+
+
+def build_credential() -> Any:
+    """Select an Azure credential for Purview authentication.
+
+    Supported modes:
+    1. CertificateCredential (if PURVIEW_USE_CERT_AUTH=true)
+    2. InteractiveBrowserCredential (requires PURVIEW_CLIENT_APP_ID)
+    """
+    client_id = _get_env("PURVIEW_CLIENT_APP_ID", required=True)
+    use_cert_auth = _get_env("PURVIEW_USE_CERT_AUTH", required=False, default="false").lower() == "true"
+
+    if not client_id:
+        raise RuntimeError(
+            "PURVIEW_CLIENT_APP_ID is required for interactive browser authentication; "
+            "set PURVIEW_USE_CERT_AUTH=true for certificate mode instead."
+        )
+
+    if use_cert_auth:
+        tenant_id = _get_env("PURVIEW_TENANT_ID")
+        cert_path = _get_env("PURVIEW_CERT_PATH")
+        cert_password = _get_env("PURVIEW_CERT_PASSWORD", required=False, default=None)
+        print(f"Using Certificate Authentication (tenant: {tenant_id}, cert: {cert_path})")
+        return CertificateCredential(
+            tenant_id=tenant_id,
+            client_id=client_id,
+            certificate_path=cert_path,
+            password=cert_password,
+        )
+
+    print(f"Using Interactive Browser Authentication (client_id: {client_id})")
+    return InteractiveBrowserCredential(client_id=client_id)
+
+
+async def run_with_agent_middleware() -> None:
+    endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
+    if not endpoint:
+        print("Skipping run: FOUNDRY_PROJECT_ENDPOINT not set")
+        return
+
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+    user_id = os.environ.get("PURVIEW_DEFAULT_USER_ID")
+    client = FoundryChatClient(model=deployment, project_endpoint=endpoint, credential=AzureCliCredential())
+
+    settings = PurviewSettings(app_name="Agent Framework Sample App")
+    purview_agent_middleware = PurviewPolicyMiddleware(build_credential(), settings)
+
+    agent = Agent(
+        client=client,
+        instructions=JOKER_INSTRUCTIONS,
+        name=JOKER_NAME,
+        middleware=[purview_agent_middleware],
+    )
+
+    print("-- Agent MiddlewareTypes Path --")
+    blocked_text = settings.get("blocked_prompt_message") or "Prompt blocked by policy"
+    await run_policy_flow("agent middleware", agent, user_id, blocked_text)
+
+
+async def run_with_chat_middleware() -> None:
+    endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
+    if not endpoint:
+        print("Skipping chat middleware run: FOUNDRY_PROJECT_ENDPOINT not set")
+        return
+
+    deployment = os.environ.get("FOUNDRY_MODEL", default="gpt-4o-mini")
+    user_id = os.environ.get("PURVIEW_DEFAULT_USER_ID")
+
+    settings = PurviewSettings(app_name="Agent Framework Sample App (Chat)")
+    client = FoundryChatClient(
+        model=deployment,
+        project_endpoint=endpoint,
+        credential=AzureCliCredential(),
+        middleware=[PurviewChatPolicyMiddleware(build_credential(), settings)],
+    )
+
+    agent = Agent(
+        client=client,
+        instructions=JOKER_INSTRUCTIONS,
+        name=JOKER_NAME,
+    )
+
+    print("-- Chat MiddlewareTypes Path --")
+    blocked_text = settings.get("blocked_prompt_message") or "Prompt blocked by policy"
+    await run_policy_flow("chat middleware", agent, user_id, blocked_text)
+
+
+async def run_with_custom_cache_provider() -> None:
+    """Demonstrate implementing and using a custom cache provider."""
+    endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
+    if not endpoint:
+        print("Skipping custom cache provider run: FOUNDRY_PROJECT_ENDPOINT not set")
+        return
+
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+    user_id = os.environ.get("PURVIEW_DEFAULT_USER_ID")
+    client = FoundryChatClient(model=deployment, project_endpoint=endpoint, credential=AzureCliCredential())
+
+    custom_cache = SimpleDictCacheProvider()
+
+    settings = PurviewSettings(app_name="Agent Framework Sample App (Custom Provider)")
+    purview_agent_middleware = PurviewPolicyMiddleware(
+        build_credential(),
+        settings,
+        cache_provider=custom_cache,
+    )
+
+    agent = Agent(
+        client=client,
+        instructions=JOKER_INSTRUCTIONS,
+        name=JOKER_NAME,
+        middleware=[purview_agent_middleware],
+    )
+
+    print("-- Custom Cache Provider Path --")
+    print("Using SimpleDictCacheProvider")
+    blocked_text = settings.get("blocked_prompt_message") or "Prompt blocked by policy"
+    await run_policy_flow("custom cache", agent, user_id, blocked_text)
+
+
+async def run_with_default_cache() -> None:
+    """Demonstrate using the default built-in cache."""
+    endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
+    if not endpoint:
+        print("Skipping default cache run: FOUNDRY_PROJECT_ENDPOINT not set")
+        return
+
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+    user_id = os.environ.get("PURVIEW_DEFAULT_USER_ID")
+    client = FoundryChatClient(model=deployment, project_endpoint=endpoint, credential=AzureCliCredential())
+
+    # No cache_provider specified - uses default InMemoryCacheProvider
+    settings = PurviewSettings(
+        app_name="Agent Framework Sample App (Default Cache)",
+        cache_ttl_seconds=3600,
+        max_cache_size_bytes=100 * 1024 * 1024,  # 100MB
+    )
+    purview_agent_middleware = PurviewPolicyMiddleware(build_credential(), settings)
+
+    agent = Agent(
+        client=client,
+        instructions=JOKER_INSTRUCTIONS,
+        name=JOKER_NAME,
+        middleware=[purview_agent_middleware],
+    )
+
+    print("-- Default Cache Path --")
+    print("Using default InMemoryCacheProvider with settings-based configuration")
+    blocked_text = settings.get("blocked_prompt_message") or "Prompt blocked by policy"
+    await run_policy_flow("default cache", agent, user_id, blocked_text)
+
+
+async def main() -> None:
+    print("== Purview Agent Sample (MiddlewareTypes with Automatic Caching) ==")
+
+    try:
+        await run_with_agent_middleware()
+    except Exception as ex:  # pragma: no cover - demo resilience
+        print(f"Agent middleware path failed: {ex}")
+
+    try:
+        await run_with_chat_middleware()
+    except Exception as ex:  # pragma: no cover - demo resilience
+        print(f"Chat middleware path failed: {ex}")
+
+    try:
+        await run_with_custom_cache_provider()
+    except Exception as ex:  # pragma: no cover - demo resilience
+        print(f"Custom cache provider path failed: {ex}")
+
+    try:
+        await run_with_default_cache()
+    except Exception as ex:  # pragma: no cover - demo resilience
+        print(f"Default cache path failed: {ex}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())