Add application file

Dockerfile

@@ -0,0 +1,18 @@
+#Base image
+FROM python:3.11-slim
+
+#Set work directory
+WORKDIR /app
+
+#Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+#Copy project files
+COPY . .
+
+#Expose the port Hugging Face expects
+EXPOSE 7860
+
+#Command to run FastAPI with uvicorn
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

ai_server_admin/Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=ai_server_admin
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

ai_server_admin/README.md

@@ -0,0 +1,255 @@
+---
+title: Ai Server Admin Environment Server
+emoji: 📽️
+colorFrom: pink
+colorTo: yellow
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+---
+
+# Ai Server Admin Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Ai Server Admin environment is through the `AiServerAdminEnv` class:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+
+try:
+    # Create environment from Docker image
+    ai_server_adminenv = AiServerAdminEnv.from_docker_image("ai_server_admin-env:latest")
+
+    # Reset
+    result = ai_server_adminenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = ai_server_adminenv.step(AiServerAdminAction(message=msg))
+        print(f"Sent: '{msg}'")
+        print(f"  → Echoed: '{result.observation.echoed_message}'")
+        print(f"  → Length: {result.observation.message_length}")
+        print(f"  → Reward: {result.reward}")
+
+finally:
+    # Always clean up
+    ai_server_adminenv.close()
+```
+
+That's it! The `AiServerAdminEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t ai_server_admin-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**AiServerAdminAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**AiServerAdminObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Ai Server Admin environment server running, you can connect directly:
+
+```python
+from ai_server_admin import AiServerAdminEnv
+
+# Connect to existing server
+ai_server_adminenv = AiServerAdminEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = ai_server_adminenv.reset()
+result = ai_server_adminenv.step(AiServerAdminAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `ai_server_adminenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+
+# Connect with context manager (auto-connects and closes)
+with AiServerAdminEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(AiServerAdminAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    AiServerAdminEnvironment,  # Pass class, not instance
+    AiServerAdminAction,
+    AiServerAdminObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from ai_server_admin import AiServerAdminAction, AiServerAdminEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with AiServerAdminEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(AiServerAdminAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/ai_server_admin_environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+ai_server_admin/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # AiServerAdminEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── ai_server_admin_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

ai_server_admin/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Ai Server Admin Environment."""
+
+from .client import AiServerAdminEnv
+from .models import AiServerAdminAction, AiServerAdminObservation
+
+__all__ = [
+    "AiServerAdminAction",
+    "AiServerAdminObservation",
+    "AiServerAdminEnv",
+]

ai_server_admin/client.py

@@ -0,0 +1,99 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Ai Server Admin Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import AiServerAdminAction, AiServerAdminObservation
+
+
+class AiServerAdminEnv(
+    EnvClient[AiServerAdminAction, AiServerAdminObservation, State]
+):
+    """
+    Client for the Ai Server Admin Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with AiServerAdminEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(AiServerAdminAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = AiServerAdminEnv.from_docker_image("ai_server_admin-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(AiServerAdminAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: AiServerAdminAction) -> Dict:
+        """
+        Convert AiServerAdminAction to JSON payload for step message.
+
+        Args:
+            action: AiServerAdminAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[AiServerAdminObservation]:
+        """
+        Parse server response into StepResult[AiServerAdminObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with AiServerAdminObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = AiServerAdminObservation(
+            echoed_message=obs_data.get("echoed_message", ""),
+            message_length=obs_data.get("message_length", 0),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

ai_server_admin/models.py

@@ -0,0 +1,27 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Ai Server Admin Environment.
+
+The ai_server_admin environment is a simple test environment that echoes back messages.
+"""
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class AiServerAdminAction(Action):
+    """Action for the Ai Server Admin environment - just a message to echo."""
+
+    message: str = Field(..., description="Message to echo back")
+
+
+class AiServerAdminObservation(Observation):
+    """Observation from the Ai Server Admin environment - the echoed message."""
+
+    echoed_message: str = Field(default="", description="The echoed message")
+    message_length: int = Field(default=0, description="Length of the echoed message")

ai_server_admin/openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: ai_server_admin
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

ai_server_admin/pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-ai_server_admin"
+version = "0.1.0"
+description = "Ai Server Admin environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m ai_server_admin.server.app
+server = "ai_server_admin.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["ai_server_admin", "ai_server_admin.server"]
+package-dir = { "ai_server_admin" = ".", "ai_server_admin.server" = "server" }

ai_server_admin/server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Ai Server Admin environment server components."""
+
+from .ai_server_admin_environment import AiServerAdminEnvironment
+
+__all__ = ["AiServerAdminEnvironment"]

ai_server_admin/server/ai_server_admin_environment.py

@@ -0,0 +1,104 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Ai Server Admin Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import AiServerAdminAction, AiServerAdminObservation
+except ImportError:
+    from models import AiServerAdminAction, AiServerAdminObservation
+
+
+class AiServerAdminEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = AiServerAdminEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Ai Server Admin environment ready!"
+        >>>
+        >>> obs = env.step(AiServerAdminAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    # Enable concurrent WebSocket sessions.
+    # Set to True if your environment isolates state between instances.
+    # When True, multiple WebSocket clients can connect simultaneously, each
+    # getting their own environment instance (when using factory mode in app.py).
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        """Initialize the ai_server_admin environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> AiServerAdminObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            AiServerAdminObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return AiServerAdminObservation(
+            echoed_message="Ai Server Admin environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: AiServerAdminAction) -> AiServerAdminObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: AiServerAdminAction containing the message to echo
+
+        Returns:
+            AiServerAdminObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return AiServerAdminObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state

ai_server_admin/server/app.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Ai Server Admin Environment.
+
+This module creates an HTTP server that exposes the AiServerAdminEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import AiServerAdminAction, AiServerAdminObservation
+    from .ai_server_admin_environment import AiServerAdminEnvironment
+except ModuleNotFoundError:
+    from models import AiServerAdminAction, AiServerAdminObservation
+    from server.ai_server_admin_environment import AiServerAdminEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    AiServerAdminEnvironment,
+    AiServerAdminAction,
+    AiServerAdminObservation,
+    env_name="ai_server_admin",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m ai_server_admin.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn ai_server_admin.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

ai_server_admin/server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

app.py

@@ -0,0 +1,114 @@
+"""
+app.py — Gradio Web Interface for Hugging Face Spaces
+=====================================================
+Provides an interactive demo of the Email Gatekeeper RL environment.
+Hugging Face Spaces serves this on port 7860 automatically.
+"""
+
+import gradio as gr
+import numpy as np
+from env import (
+    EmailTriageEnv, TASK_SPLITS,
+    URGENCY_LABELS, ROUTING_LABELS, RESOLUTION_LABELS,
+)
+
+_LEGAL_SECURITY_KW   = {"lawsuit", "attorney", "sue", "ransomware", "extortion"}
+_BILLING_ESCALATE_KW = {"refund"}
+
+
+def _classify(email: dict) -> np.ndarray:
+    kw      = set(email.get("keywords", []))
+    context = email.get("context", "").lower()
+    if context == "legal" or kw & {"lawsuit", "attorney", "sue"}:
+        return np.array([2, 2, 2], dtype=np.int64)
+    if context == "security":
+        if kw & _LEGAL_SECURITY_KW or ("hacked" in kw and "breach" in kw):
+            return np.array([2, 2, 2], dtype=np.int64)
+        return np.array([2, 1, 2], dtype=np.int64)
+    if context == "billing":
+        return np.array([1, 2, 2] if kw & _BILLING_ESCALATE_KW
+                        else [1, 0, 1], dtype=np.int64)
+    if context == "tech" or kw & {"crash", "error", "bug", "slow"}:
+        return np.array([0, 1, 1], dtype=np.int64)
+    return np.array([0, 0, 0], dtype=np.int64)
+
+
+def run_task_demo(task: str) -> str:
+    env = EmailTriageEnv(task=task, shuffle=False)
+    env.reset(seed=42)
+    email_queue = list(env._queue)
+
+    lines        = []
+    cumulative   = 0.0
+    terminated   = False
+    step         = 0
+
+    while not terminated:
+        email  = email_queue[step]
+        action = _classify(email)
+        _, norm_reward, terminated, _, info = env.step(action)
+        cumulative += norm_reward
+
+        raw = info["raw_reward"]
+        ca  = info["correct_actions"]
+
+        verdict = ("✅ EXACT" if raw >= 1.0 else
+                   "🔶 PARTIAL" if raw > 0 else
+                   "🚨 SECURITY MISS" if raw < 0 else "❌ WRONG")
+
+        lines.append(
+            f"#{step+1:02d} [{email['difficulty'].upper()}] "
+            f"{email['description'][:40]}\n"
+            f"     Predicted : {URGENCY_LABELS[action[0]]} | "
+            f"{ROUTING_LABELS[action[1]]} | {RESOLUTION_LABELS[action[2]]}\n"
+            f"     Correct   : {URGENCY_LABELS[ca[0]]} | "
+            f"{ROUTING_LABELS[ca[1]]} | {RESOLUTION_LABELS[ca[2]]}\n"
+            f"     Reward    : {raw:+.1f}  {verdict}\n"
+        )
+        step += 1
+
+    final = max(0.0, min(1.0, cumulative))
+    lines.append(f"\n{'─'*50}")
+    lines.append(f"Final Score : {final:.3f} / 1.0")
+    return "\n".join(lines)
+
+
+with gr.Blocks(title="Email Gatekeeper RL") as demo:
+    gr.Markdown("""
+# 📧 Email Gatekeeper — RL Environment Demo
+**Meta x PyTorch Hackathon** | Gymnasium-based email triage agent
+
+The agent classifies each email across **3 simultaneous dimensions**:
+`Urgency` × `Department` × `Resolution Action`
+""")
+
+    with gr.Row():
+        task_dropdown = gr.Dropdown(
+            choices=["easy", "medium", "hard"],
+            value="easy",
+            label="Select Task",
+        )
+        run_btn = gr.Button("▶ Run Episode", variant="primary")
+
+    output_box = gr.Textbox(
+        label="Episode Results",
+        lines=30,
+        max_lines=50,
+    )
+
+    run_btn.click(fn=run_task_demo, inputs=task_dropdown, outputs=output_box)
+
+    gr.Markdown("""
+### Reward Function
+| Result | Reward |
+|---|---|
+| ✅ Exact Match (all 3 correct) | +1.0 |
+| 🔶 Partial (urgency correct, 1 wrong) | +0.2 |
+| 🔶 Partial (urgency correct, 2 wrong) | +0.1 |
+| 🚨 Security Miss | **-2.0** |
+| ❌ Wrong urgency | 0.0 |
+""")
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

cdk/app.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+app.py — CDK application entry point.
+
+Usage:
+    cd cdk
+    pip install aws-cdk-lib constructs
+    cdk bootstrap        # first time only
+    cdk synth            # preview CloudFormation template
+    cdk deploy           # deploy to AWS
+    cdk destroy          # tear down all resources
+"""
+
+import aws_cdk as cdk
+from email_gatekeeper_stack import EmailGatekeeperStack
+
+app = cdk.App()
+
+EmailGatekeeperStack(
+    app,
+    "EmailGatekeeperStack",
+    # Pin to a specific account + region to avoid environment-agnostic limitations
+    # (required for SES receipt rules and S3 bucket policies).
+    # Replace with your actual AWS account ID and preferred region.
+    env=cdk.Environment(
+        account="123456789012",     # ← replace with your AWS account ID
+        region="us-east-1",         # ← SES inbound is only available in us-east-1,
+    ),                              #   us-west-2, and eu-west-1
+)
+
+app.synth()

cdk/email_gatekeeper_stack.py

@@ -0,0 +1,144 @@
+"""
+email_gatekeeper_stack.py — AWS CDK Stack for the Email Gatekeeper.
+
+Resources created:
+  - S3 bucket          : receives raw .eml files from SES
+  - Lambda function    : classifies each email using the rule-based engine
+  - DynamoDB table     : stores every triage result (email_id as partition key)
+  - SNS topic          : fires an alert whenever a Security Breach is detected
+  - SES receipt rule   : routes inbound email → S3 bucket  (requires verified domain)
+  - IAM roles/policies : least-privilege access for Lambda → S3, DynamoDB, SNS
+
+Deploy:
+  cd cdk
+  pip install aws-cdk-lib constructs
+  cdk bootstrap          # first time only per account/region
+  cdk deploy
+"""
+
+import aws_cdk as cdk
+from aws_cdk import (
+    Stack,
+    Duration,
+    RemovalPolicy,
+    aws_s3 as s3,
+    aws_lambda as lambda_,
+    aws_dynamodb as dynamodb,
+    aws_sns as sns,
+    aws_sns_subscriptions as sns_subs,
+    aws_s3_notifications as s3n,
+    aws_ses as ses,
+    aws_ses_actions as ses_actions,
+    aws_iam as iam,
+)
+from constructs import Construct
+
+
+class EmailGatekeeperStack(Stack):
+    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
+        super().__init__(scope, construct_id, **kwargs)
+
+        # ── 1. S3 bucket — stores raw .eml files delivered by SES ─────────────
+        email_bucket = s3.Bucket(
+            self, "EmailBucket",
+            bucket_name=f"email-gatekeeper-inbox-{self.account}",
+            # Block all public access — emails are private
+            block_public_access=s3.BlockPublicAccess.BLOCK_ALL,
+            encryption=s3.BucketEncryption.S3_MANAGED,
+            # Auto-delete raw emails after 30 days to control storage costs
+            lifecycle_rules=[
+                s3.LifecycleRule(expiration=Duration.days(30))
+            ],
+            removal_policy=RemovalPolicy.RETAIN,    # keep emails if stack is deleted
+        )
+
+        # ── 2. DynamoDB table — persists every triage decision ─────────────────
+        results_table = dynamodb.Table(
+            self, "EmailResultsTable",
+            table_name="EmailTriageResults",
+            partition_key=dynamodb.Attribute(
+                name="email_id",
+                type=dynamodb.AttributeType.STRING,
+            ),
+            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,  # serverless billing
+            removal_policy=RemovalPolicy.RETAIN,
+        )
+
+        # ── 3. SNS topic — security breach alerts ─────────────────────────────
+        security_topic = sns.Topic(
+            self, "SecurityAlertTopic",
+            topic_name="EmailGatekeeperSecurityAlerts",
+            display_name="Email Gatekeeper — Security Breach Alerts",
+        )
+
+        # Add your alert email here — replace with a real address
+        security_topic.add_subscription(
+            sns_subs.EmailSubscription("security-team@your-domain.com")
+        )
+
+        # ── 4. Lambda function ─────────────────────────────────────────────────
+        classifier_fn = lambda_.Function(
+            self, "EmailClassifierFn",
+            function_name="EmailGatekeeperClassifier",
+            runtime=lambda_.Runtime.PYTHON_3_12,
+            # Points to the ../lambda/ directory — CDK zips it automatically
+            code=lambda_.Code.from_asset("../lambda"),
+            handler="handler.lambda_handler",
+            timeout=Duration.seconds(30),
+            memory_size=256,                        # classifier is CPU-light
+            environment={
+                "EMAIL_RESULTS_TABLE":      results_table.table_name,
+                "SECURITY_ALERT_TOPIC_ARN": security_topic.topic_arn,
+            },
+        )
+
+        # Grant Lambda least-privilege access to each resource
+        email_bucket.grant_read(classifier_fn)
+        results_table.grant_write_data(classifier_fn)
+        security_topic.grant_publish(classifier_fn)
+
+        # ── 5. S3 → Lambda trigger ─────────────────────────────────────────────
+        # Fires whenever SES drops a new .eml into the bucket
+        email_bucket.add_event_notification(
+            s3.EventType.OBJECT_CREATED,
+            s3n.LambdaDestination(classifier_fn),
+        )
+
+        # ── 6. SES receipt rule — routes inbound email to S3 ──────────────────
+        # IMPORTANT: your domain must be verified in SES before this works.
+        # Replace "mail.your-domain.com" with your actual verified domain.
+        rule_set = ses.ReceiptRuleSet(
+            self, "EmailRuleSet",
+            rule_set_name="EmailGatekeeperRuleSet",
+        )
+
+        rule_set.add_rule(
+            "StoreInS3Rule",
+            recipients=["inbox@mail.your-domain.com"],  # ← replace with your address
+            actions=[
+                ses_actions.S3(
+                    bucket=email_bucket,
+                    object_key_prefix="incoming/",      # all emails land under incoming/
+                )
+            ],
+            scan_enabled=True,                          # enable SES spam/virus scanning
+        )
+
+        # ── 7. Allow SES to write to the S3 bucket ────────────────────────────
+        email_bucket.add_to_resource_policy(
+            iam.PolicyStatement(
+                sid="AllowSESPuts",
+                principals=[iam.ServicePrincipal("ses.amazonaws.com")],
+                actions=["s3:PutObject"],
+                resources=[email_bucket.arn_for_objects("incoming/*")],
+                conditions={
+                    "StringEquals": {"aws:SourceAccount": self.account}
+                },
+            )
+        )
+
+        # ── 8. CloudFormation outputs — useful after deploy ────────────────────
+        cdk.CfnOutput(self, "BucketName",      value=email_bucket.bucket_name)
+        cdk.CfnOutput(self, "TableName",       value=results_table.table_name)
+        cdk.CfnOutput(self, "LambdaArn",       value=classifier_fn.function_arn)
+        cdk.CfnOutput(self, "SecurityTopicArn",value=security_topic.topic_arn)

cdk/requirements.txt

@@ -0,0 +1,2 @@
+aws-cdk-lib>=2.100.0
+constructs>=10.0.0

env.py

@@ -0,0 +1,405 @@
+"""
+env.py — Email Gatekeeper RL Environment (OpenEnv Specification)
+================================================================
+Gymnasium environment for intelligent email triage.
+Wraps the core EmailTriageEnv logic with:
+  - Pydantic typed Action and Observation models
+  - state() method returning current environment state
+  - Three task splits: easy / medium / hard
+  - Full OpenEnv-compatible interface
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import gymnasium as gym
+from gymnasium import spaces
+from pydantic import BaseModel, Field
+from typing import Optional
+
+# ── Vocabulary & encoding (canonical — must not change between versions) ──────
+
+KEYWORD_VOCAB = [
+    "invoice", "payment", "overdue", "refund",
+    "hacked",  "breach",  "unauthorized", "password",
+    "crash",   "error",   "bug",   "slow",
+    "lawsuit", "legal",   "attorney", "sue",
+    "spam",    "offer",   "win",   "free",
+    "urgent",  "critical","angry", "threat",
+]
+
+SENTIMENT_MAP = {"positive": 0, "neutral": 1, "negative": 2}
+CONTEXT_MAP   = {"spam": 0, "billing": 1, "tech": 2, "security": 3, "legal": 4}
+OBS_DIM       = len(KEYWORD_VOCAB) + len(SENTIMENT_MAP) + len(CONTEXT_MAP)  # 32
+
+# ── Label maps ────────────────────────────────────────────────────────────────
+URGENCY_LABELS    = {0: "General",       1: "Billing",      2: "Security Breach"}
+ROUTING_LABELS    = {0: "AI Auto-Reply", 1: "Tech Support", 2: "Legal"}
+RESOLUTION_LABELS = {0: "Archive",       1: "Draft Reply",  2: "Escalate"}
+
+# ── Reward weights ────────────────────────────────────────────────────────────
+REWARD_EXACT           =  1.0
+REWARD_PARTIAL_1_WRONG =  0.2
+REWARD_PARTIAL_2_WRONG =  0.1
+PENALTY_SECURITY_MISS  = -2.0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Pydantic Typed Models
+# ─────────────────────────────────────────────────────────────────────────────
+
+class EmailAction(BaseModel):
+    """
+    The agent's triage decision for one email.
+    All three dimensions must be predicted simultaneously.
+    """
+    urgency: int = Field(
+        ..., ge=0, le=2,
+        description="0=General | 1=Billing | 2=Security Breach"
+    )
+    routing: int = Field(
+        ..., ge=0, le=2,
+        description="0=AI Auto-Reply | 1=Tech Support | 2=Legal"
+    )
+    resolution: int = Field(
+        ..., ge=0, le=2,
+        description="0=Archive | 1=Draft Reply | 2=Escalate"
+    )
+
+    def to_array(self) -> np.ndarray:
+        return np.array([self.urgency, self.routing, self.resolution],
+                        dtype=np.int64)
+
+    @classmethod
+    def from_array(cls, arr: np.ndarray) -> "EmailAction":
+        return cls(urgency=int(arr[0]), routing=int(arr[1]),
+                   resolution=int(arr[2]))
+
+
+class EmailObservation(BaseModel):
+    """
+    The agent's view of the current email.
+    Encoded as a flat float32 vector of length 32.
+    """
+    keyword_flags: list[float] = Field(
+        ..., description=f"Binary flags for {len(KEYWORD_VOCAB)} vocab keywords"
+    )
+    sentiment_onehot: list[float] = Field(
+        ..., description="One-hot: [positive, neutral, negative]"
+    )
+    context_onehot: list[float] = Field(
+        ..., description="One-hot: [spam, billing, tech, security, legal]"
+    )
+    # Human-readable metadata (not used by the agent, useful for logging)
+    description: str = ""
+    difficulty:  str = ""
+    context_str: str = ""
+    sentiment_str: str = ""
+    keywords:    list[str] = Field(default_factory=list)
+
+    def to_array(self) -> np.ndarray:
+        return np.array(
+            self.keyword_flags + self.sentiment_onehot + self.context_onehot,
+            dtype=np.float32,
+        )
+
+
+class EnvironmentState(BaseModel):
+    """Current snapshot of the environment — returned by state()."""
+    step_index:    int
+    total_emails:  int
+    emails_remaining: int
+    current_email: dict
+    cumulative_reward: float
+    task:          str   # "easy" | "medium" | "hard" | "all"
+    terminated:    bool
+
+
+class StepResult(BaseModel):
+    """Typed return value from step()."""
+    observation:  EmailObservation
+    reward:       float
+    normalised_reward: float
+    terminated:   bool
+    truncated:    bool
+    info:         dict
+
+
+# ──────────────────────────────────────────────────────��──────────────────────
+# Dataset
+# ─────────────────────────────────────────────────────────────────────────────
+
+EMAIL_DATASET: list[dict] = [
+    # ── Easy: Spam detection ─────────────────────────────────────────────────
+    {"description": "Spam promo",          "keywords": ["spam","offer","win","free"],
+     "sentiment": "positive", "context": "spam",    "difficulty": "easy",
+     "correct_actions": (0, 0, 0)},
+    {"description": "Spam lottery",        "keywords": ["free","win","offer"],
+     "sentiment": "positive", "context": "spam",    "difficulty": "easy",
+     "correct_actions": (0, 0, 0)},
+    {"description": "Routine support",     "keywords": ["slow","error"],
+     "sentiment": "neutral",  "context": "tech",    "difficulty": "easy",
+     "correct_actions": (0, 1, 1)},
+    {"description": "General billing",     "keywords": ["invoice","payment"],
+     "sentiment": "neutral",  "context": "billing", "difficulty": "easy",
+     "correct_actions": (1, 0, 1)},
+    # ── Medium: Support routing ───────────────────────────────────────────────
+    {"description": "Overdue invoice",     "keywords": ["invoice","overdue","payment","angry"],
+     "sentiment": "negative", "context": "billing", "difficulty": "medium",
+     "correct_actions": (1, 0, 1)},
+    {"description": "Refund dispute",      "keywords": ["refund","payment","angry"],
+     "sentiment": "negative", "context": "billing", "difficulty": "medium",
+     "correct_actions": (1, 2, 2)},
+    {"description": "App crash report",    "keywords": ["crash","bug","error"],
+     "sentiment": "negative", "context": "tech",    "difficulty": "medium",
+     "correct_actions": (0, 1, 1)},
+    {"description": "Persistent login bug","keywords": ["bug","password","error"],
+     "sentiment": "negative", "context": "tech",    "difficulty": "medium",
+     "correct_actions": (0, 1, 1)},
+    {"description": "Polite legal ultimatum","keywords": ["refund","legal","angry","threat"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "medium",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Attorney CC warning", "keywords": ["invoice","overdue","attorney","legal","payment","threat"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "medium",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Regulatory complaint","keywords": ["angry","threat","legal"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "medium",
+     "correct_actions": (2, 2, 2)},
+    {"description": "SLA breach legal",    "keywords": ["breach","legal","threat","angry"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "medium",
+     "correct_actions": (2, 2, 2)},
+    # ── Hard: Phishing & security threats ────────────────────────────────────
+    {"description": "IT audit phish",      "keywords": ["password","unauthorized","critical","urgent","threat"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Fake invoice portal", "keywords": ["invoice","payment","password","unauthorized","urgent"],
+     "sentiment": "neutral",  "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "HR credential phish", "keywords": ["password","urgent","critical"],
+     "sentiment": "neutral",  "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Fake suspension",     "keywords": ["unauthorized","password","breach","urgent","threat"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "BEC vendor reply",    "keywords": ["password","unauthorized","urgent"],
+     "sentiment": "neutral",  "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Sign-in alert phish", "keywords": ["unauthorized","password","hacked","breach","urgent"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Payroll phish",       "keywords": ["payment","password","urgent","threat"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "License renewal BEC", "keywords": ["password","critical","urgent","error"],
+     "sentiment": "neutral",  "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "GDPR phish",          "keywords": ["breach","hacked","password","legal","threat","urgent","unauthorized"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Ransomware audit",    "keywords": ["hacked","breach","unauthorized","lawsuit","legal","threat","critical","urgent"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Data extortion",      "keywords": ["hacked","breach","unauthorized","attorney","threat","critical","urgent"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Fake law firm",       "keywords": ["unauthorized","breach","attorney","lawsuit","legal","threat"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "hard",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Account hacked",      "keywords": ["hacked","unauthorized","password","urgent","angry"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Data breach notice",  "keywords": ["breach","unauthorized","critical","threat"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 1, 2)},
+    {"description": "Legal lawsuit threat","keywords": ["lawsuit","legal","attorney","threat","angry"],
+     "sentiment": "negative", "context": "legal",   "difficulty": "hard",
+     "correct_actions": (2, 2, 2)},
+    {"description": "Ransomware threat",   "keywords": ["hacked","threat","critical","urgent","breach"],
+     "sentiment": "negative", "context": "security","difficulty": "hard",
+     "correct_actions": (2, 2, 2)},
+]
+
+# Task splits — used by inference.py for per-task scoring
+TASK_SPLITS: dict[str, list[dict]] = {
+    "easy":   [e for e in EMAIL_DATASET if e["difficulty"] == "easy"],
+    "medium": [e for e in EMAIL_DATASET if e["difficulty"] == "medium"],
+    "hard":   [e for e in EMAIL_DATASET if e["difficulty"] == "hard"],
+    "all":    EMAIL_DATASET,
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Core Environment
+# ─────────────────────────────────────────────────────────────────────────────
+
+class EmailTriageEnv(gym.Env):
+    """
+    OpenEnv-compliant Gymnasium environment for email triage.
+
+    The agent receives one email per step as a 32-dim observation vector
+    and must output three simultaneous discrete decisions.
+
+    Parameters
+    ----------
+    task : str
+        "easy" | "medium" | "hard" | "all"  — which email subset to use.
+    shuffle : bool
+        Shuffle emails on each reset (default True).
+    """
+
+    metadata = {"render_modes": ["human"]}
+
+    def __init__(self, task: str = "all", shuffle: bool = True):
+        super().__init__()
+
+        if task not in TASK_SPLITS:
+            raise ValueError(f"task must be one of {list(TASK_SPLITS)}. Got '{task}'.")
+
+        self.task          = task
+        self.shuffle       = shuffle
+        self.email_batch   = TASK_SPLITS[task]
+
+        # Gymnasium spaces
+        self.action_space = spaces.MultiDiscrete([3, 3, 3])
+        self.observation_space = spaces.Box(
+            low=0.0, high=1.0, shape=(OBS_DIM,), dtype=np.float32
+        )
+
+        # Internal state
+        self._queue:          list[dict] = []
+        self._current_email:  dict       = {}
+        self._step_idx:       int        = 0
+        self._cumulative_reward: float   = 0.0
+        self._max_episode_reward: float  = len(self.email_batch) * REWARD_EXACT
+
+    # ── Encoding helpers ──────────────────────────────────────────────────────
+
+    def _encode_to_obs(self, email: dict) -> EmailObservation:
+        """Convert an email dict into a typed EmailObservation."""
+        kw_flags = [1.0 if kw in email["keywords"] else 0.0
+                    for kw in KEYWORD_VOCAB]
+
+        sentiment_vec = [0.0] * len(SENTIMENT_MAP)
+        sentiment_vec[SENTIMENT_MAP[email["sentiment"]]] = 1.0
+
+        context_vec = [0.0] * len(CONTEXT_MAP)
+        context_vec[CONTEXT_MAP[email["context"]]] = 1.0
+
+        return EmailObservation(
+            keyword_flags=kw_flags,
+            sentiment_onehot=sentiment_vec,
+            context_onehot=context_vec,
+            description=email.get("description", ""),
+            difficulty=email.get("difficulty", ""),
+            context_str=email["context"],
+            sentiment_str=email["sentiment"],
+            keywords=email["keywords"],
+        )
+
+    def _compute_reward(self, action: np.ndarray, email: dict) -> float:
+        """
+        Reward function — same logic as environment.py, priority order:
+          1. Security miss  → -2.0  (correct urgency=2, predicted otherwise)
+          2. Exact match    → +1.0
+          3. Partial-1      → +0.2  (urgency correct, 1 other wrong)
+          4. Partial-2      → +0.1  (urgency correct, both others wrong)
+          5. Wrong          →  0.0
+        """
+        u, r, res   = int(action[0]), int(action[1]), int(action[2])
+        c           = email["correct_actions"]
+
+        if c[0] == 2 and u != 2:
+            return PENALTY_SECURITY_MISS
+        if (u, r, res) == c:
+            return REWARD_EXACT
+        if u == c[0]:
+            wrong = sum([r != c[1], res != c[2]])
+            return REWARD_PARTIAL_1_WRONG if wrong == 1 else REWARD_PARTIAL_2_WRONG
+        return 0.0
+
+    # ── OpenEnv API ───────────────────────────────────────────────────────────
+
+    def reset(
+        self,
+        *,
+        seed: Optional[int] = None,
+        options: Optional[dict] = None,
+    ) -> tuple[np.ndarray, dict]:
+        super().reset(seed=seed)
+
+        self._queue = list(self.email_batch)
+        if self.shuffle:
+            self.np_random.shuffle(self._queue)
+
+        self._step_idx          = 0
+        self._cumulative_reward = 0.0
+        self._current_email     = self._queue[0]
+
+        obs = self._encode_to_obs(self._current_email)
+        info = {
+            "description": self._current_email["description"],
+            "difficulty":  self._current_email["difficulty"],
+            "task":        self.task,
+            "total_steps": len(self._queue),
+        }
+        return obs.to_array(), info
+
+    def step(
+        self, action: np.ndarray
+    ) -> tuple[np.ndarray, float, bool, bool, dict]:
+        # Capture current email BEFORE advancing pointer
+        scored_email = self._current_email
+        raw_reward   = self._compute_reward(action, scored_email)
+        norm_reward  = raw_reward / self._max_episode_reward
+
+        self._cumulative_reward += norm_reward
+        self._step_idx          += 1
+        terminated               = self._step_idx >= len(self._queue)
+
+        if not terminated:
+            self._current_email = self._queue[self._step_idx]
+            obs = self._encode_to_obs(self._current_email)
+        else:
+            obs = self._encode_to_obs(scored_email)
+
+        # Decode action for info dict
+        typed_action = EmailAction.from_array(action)
+        correct      = scored_email["correct_actions"]
+
+        info = {
+            "raw_reward":       raw_reward,
+            "correct_actions":  correct,
+            "predicted":        (typed_action.urgency,
+                                 typed_action.routing,
+                                 typed_action.resolution),
+            "difficulty":       scored_email["difficulty"],
+            "description":      scored_email.get("description", ""),
+            "urgency_label":    URGENCY_LABELS[typed_action.urgency],
+            "routing_label":    ROUTING_LABELS[typed_action.routing],
+            "resolution_label": RESOLUTION_LABELS[typed_action.resolution],
+            "cumulative_score": self._cumulative_reward,
+        }
+        return obs.to_array(), norm_reward, terminated, False, info
+
+    def state(self) -> EnvironmentState:
+        """
+        Return a typed snapshot of the current environment state.
+        Required by the OpenEnv specification.
+        """
+        return EnvironmentState(
+            step_index=self._step_idx,
+            total_emails=len(self._queue),
+            emails_remaining=max(0, len(self._queue) - self._step_idx),
+            current_email=self._current_email,
+            cumulative_reward=self._cumulative_reward,
+            task=self.task,
+            terminated=self._step_idx >= len(self._queue),
+        )
+
+    def render(self, mode: str = "human") -> None:
+        e = self._current_email
+        print(
+            f"[{self.task.upper()} | Step {self._step_idx}/{len(self._queue)}] "
+            f"{e['description']} | {e['difficulty']} | "
+            f"sentiment={e['sentiment']} context={e['context']}"
+        )

environment.py

@@ -0,0 +1,501 @@
+"""
+EmailTriageEnv — Intelligent Email Gatekeeper RL Environment
+============================================================
+Observation : flat Box vector encoding keywords, sentiment, and context.
+Action      : MultiDiscrete([3, 3, 3])
+              [0] Urgency   — 0=General, 1=Billing, 2=Security Breach
+              [1] Routing   — 0=AI Auto-Reply, 1=Tech Support, 2=Legal
+              [2] Resolution— 0=Archive, 1=Draft Reply, 2=Escalate to Human
+Reward      : +0.5 fully correct | -0.4 wrong priority on crisis email
+              Cumulative ideal score over one episode ≈ 1.0 (normalised).
+Episode     : one email per step; done after all emails in the batch.
+"""
+
+import numpy as np
+import gymnasium as gym
+from gymnasium import spaces
+
+# ---------------------------------------------------------------------------
+# Vocabulary & encoding helpers
+# ---------------------------------------------------------------------------
+
+# Fixed keyword vocabulary — extend freely.
+KEYWORD_VOCAB = [
+    "invoice", "payment", "overdue", "refund",          # billing
+    "hacked", "breach", "unauthorized", "password",     # security
+    "crash", "error", "bug", "slow",                    # tech
+    "lawsuit", "legal", "attorney", "sue",              # legal
+    "spam", "offer", "win", "free",                     # spam
+    "urgent", "critical", "angry", "threat",            # sentiment signals
+]
+
+# Sentiment classes  → index
+SENTIMENT_MAP = {"positive": 0, "neutral": 1, "negative": 2}
+
+# Context classes    → index
+CONTEXT_MAP = {"spam": 0, "billing": 1, "tech": 2, "security": 3, "legal": 4}
+
+# Observation vector length: keyword flags + one-hot sentiment + one-hot context
+OBS_DIM = len(KEYWORD_VOCAB) + len(SENTIMENT_MAP) + len(CONTEXT_MAP)
+
+# ---------------------------------------------------------------------------
+# Mock email dataset
+# ---------------------------------------------------------------------------
+# Each entry:
+#   keywords    : list[str]  — subset of KEYWORD_VOCAB
+#   sentiment   : str        — key in SENTIMENT_MAP
+#   context     : str        — key in CONTEXT_MAP
+#   difficulty  : str        — "easy" | "medium" | "hard"
+#   correct_actions: tuple   — (urgency, routing, resolution)
+#   description : str        — human-readable label (for debugging)
+
+EMAIL_DATASET = [
+    # ── Easy: Spam vs Real ──────────────────────────────────────────────────
+    {
+        "description": "Spam promo",
+        "keywords": ["spam", "offer", "win", "free"],
+        "sentiment": "positive",
+        "context": "spam",
+        "difficulty": "easy",
+        "correct_actions": (0, 0, 0),   # General | AI Auto-Reply | Archive
+    },
+    {
+        "description": "Spam lottery",
+        "keywords": ["free", "win", "offer"],
+        "sentiment": "positive",
+        "context": "spam",
+        "difficulty": "easy",
+        "correct_actions": (0, 0, 0),
+    },
+    {
+        "description": "Routine support request",
+        "keywords": ["slow", "error"],
+        "sentiment": "neutral",
+        "context": "tech",
+        "difficulty": "easy",
+        "correct_actions": (0, 1, 1),   # General | Tech Support | Draft Reply
+    },
+    {
+        "description": "General billing inquiry",
+        "keywords": ["invoice", "payment"],
+        "sentiment": "neutral",
+        "context": "billing",
+        "difficulty": "easy",
+        "correct_actions": (1, 0, 1),   # Billing | AI Auto-Reply | Draft Reply
+    },
+    # ── Medium: Billing / Tech context ──────────────────────────────────────
+    {
+        "description": "Overdue invoice complaint",
+        "keywords": ["invoice", "overdue", "payment", "angry"],
+        "sentiment": "negative",
+        "context": "billing",
+        "difficulty": "medium",
+        "correct_actions": (1, 0, 1),   # Billing | AI Auto-Reply | Draft Reply
+    },
+    {
+        "description": "Refund dispute",
+        "keywords": ["refund", "payment", "angry"],
+        "sentiment": "negative",
+        "context": "billing",
+        "difficulty": "medium",
+        "correct_actions": (1, 2, 2),   # Billing | Legal | Escalate
+    },
+    {
+        "description": "App crash report",
+        "keywords": ["crash", "bug", "error"],
+        "sentiment": "negative",
+        "context": "tech",
+        "difficulty": "medium",
+        "correct_actions": (0, 1, 1),   # General | Tech Support | Draft Reply
+    },
+    {
+        "description": "Persistent login bug",
+        "keywords": ["bug", "password", "error"],
+        "sentiment": "negative",
+        "context": "tech",
+        "difficulty": "medium",
+        "correct_actions": (0, 1, 1),
+    },
+    # ── Medium: Passive-Aggressive Legal Threats ────────────────────────────
+    {
+        "id": "TC-M-01",
+        "description": "Polite refund ultimatum with implied legal action",
+        "keywords": ["refund", "legal", "angry", "threat"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-02",
+        "description": "Overdue invoice with attorney CC warning",
+        "keywords": ["invoice", "overdue", "attorney", "legal", "payment", "threat"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-03",
+        "description": "Disappointed customer implying regulatory complaint",
+        "keywords": ["angry", "threat", "legal"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-04",
+        "description": "SLA breach complaint with legal remedy language",
+        "keywords": ["breach", "legal", "threat", "angry"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-05",
+        "description": "Billing dispute with small claims court mention",
+        "keywords": ["refund", "payment", "angry", "lawsuit", "urgent"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-06",
+        "description": "GDPR deletion request with legal consequence warning",
+        "keywords": ["legal", "breach", "threat", "angry"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-07",
+        "description": "Subscription cancellation with chargeback and CFPB threat",
+        "keywords": ["payment", "refund", "angry", "threat", "legal"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-M-08",
+        "description": "Vendor threatening IP infringement claim",
+        "keywords": ["unauthorized", "legal", "attorney", "threat"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "medium",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    # ── Hard: Subtle Phishing Attempts ──────────────────────────────────────
+    {
+        "id": "TC-H-01",
+        "description": "IT password reset disguised as routine security audit",
+        "keywords": ["password", "unauthorized", "critical", "urgent", "threat"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-02",
+        "description": "Fake invoice payment portal redirect — credential harvest",
+        "keywords": ["invoice", "payment", "password", "unauthorized", "urgent"],
+        "sentiment": "neutral",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-03",
+        "description": "HR benefits enrollment with credential capture",
+        "keywords": ["password", "urgent", "critical"],
+        "sentiment": "neutral",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-04",
+        "description": "Fake account suspension notice with login link",
+        "keywords": ["unauthorized", "password", "breach", "urgent", "threat"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-05",
+        "description": "Vendor onboarding BEC — admin credentials via reply",
+        "keywords": ["password", "unauthorized", "urgent"],
+        "sentiment": "neutral",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-06",
+        "description": "Fake new sign-in alert — was this you? phish",
+        "keywords": ["unauthorized", "password", "hacked", "breach", "urgent"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-07",
+        "description": "Payroll migration phish — salary interruption fear",
+        "keywords": ["payment", "password", "urgent", "threat"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "id": "TC-H-08",
+        "description": "Software license renewal — admin credential request",
+        "keywords": ["password", "critical", "urgent", "error"],
+        "sentiment": "neutral",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    # ── Hard: Phishing + Legal Threat Overlay ───────────────────────────────
+    {
+        "id": "TC-H-09",
+        "description": "Fake GDPR breach notice — credential harvest via legal fear",
+        "keywords": ["breach", "hacked", "password", "legal", "threat", "urgent", "unauthorized"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+        # NOTE: legal language is the deception layer; credential harvest = Tech Support
+    },
+    {
+        "id": "TC-H-10",
+        "description": "Ransomware disguised as software compliance audit",
+        "keywords": ["hacked", "breach", "unauthorized", "lawsuit", "legal", "threat", "critical", "urgent"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-H-11",
+        "description": "Extortion — threatening to publish stolen data",
+        "keywords": ["hacked", "breach", "unauthorized", "attorney", "threat", "critical", "urgent"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "id": "TC-H-12",
+        "description": "Fake law firm letter claiming evidence of data misuse",
+        "keywords": ["unauthorized", "breach", "attorney", "lawsuit", "legal", "threat"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "hard",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    # ── Hard: Crisis / Security threats ─────────────────────────────────────
+    {
+        "description": "Account hacked — urgent",
+        "keywords": ["hacked", "unauthorized", "password", "urgent", "angry"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),   # Security | Tech Support | Escalate
+    },
+    {
+        "description": "Data breach notification",
+        "keywords": ["breach", "unauthorized", "critical", "threat"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 1, 2),
+    },
+    {
+        "description": "Legal threat — lawsuit",
+        "keywords": ["lawsuit", "legal", "attorney", "threat", "angry"],
+        "sentiment": "negative",
+        "context": "legal",
+        "difficulty": "hard",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+    {
+        "description": "Ransomware / extortion threat",
+        "keywords": ["hacked", "threat", "critical", "urgent", "breach"],
+        "sentiment": "negative",
+        "context": "security",
+        "difficulty": "hard",
+        "correct_actions": (2, 2, 2),   # Security | Legal | Escalate
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Reward weights — adjust freely
+# ---------------------------------------------------------------------------
+REWARD_CORRECT_FULL      =  1.0   # teeno actions bilkul sahi
+REWARD_PARTIAL_ONE_WRONG =  0.2   # urgency sahi + sirf ek dimension galat
+REWARD_PARTIAL_BOTH_WRONG=  0.1   # urgency sahi lekin routing aur resolution dono galat
+PENALTY_MISSED_SECURITY  = -2.0   # security breach email miss kiya
+
+
+# ---------------------------------------------------------------------------
+# Environment
+# ---------------------------------------------------------------------------
+
+class EmailTriageEnv(gym.Env):
+    """
+    Single-email-per-step triage environment.
+
+    Parameters
+    ----------
+    batch : list[dict] | None
+        Custom email batch. Defaults to the full EMAIL_DATASET.
+    shuffle : bool
+        Shuffle the batch on each reset (default True).
+    """
+
+    metadata = {"render_modes": ["human"]}
+
+    def __init__(self, batch: list | None = None, shuffle: bool = True):
+        super().__init__()
+
+        self.email_batch = batch if batch is not None else EMAIL_DATASET
+        self.shuffle = shuffle
+
+        # Action space: [urgency(3), routing(3), resolution(3)]
+        self.action_space = spaces.MultiDiscrete([3, 3, 3])
+
+        # Observation space: binary keyword flags + one-hot sentiment + one-hot context
+        self.observation_space = spaces.Box(
+            low=0.0, high=1.0, shape=(OBS_DIM,), dtype=np.float32
+        )
+
+        # Internal state (populated by reset)
+        self._queue: list[dict] = []
+        self._current_email: dict = {}
+        self._step_idx: int = 0
+
+        # Normalisation constant: max possible reward per episode
+        self._max_episode_reward = len(self.email_batch) * REWARD_CORRECT_FULL
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _encode(self, email: dict) -> np.ndarray:
+        """Convert an email dict into a flat float32 observation vector."""
+        # Keyword flags (binary)
+        kw_flags = np.array(
+            [1.0 if kw in email["keywords"] else 0.0 for kw in KEYWORD_VOCAB],
+            dtype=np.float32,
+        )
+        # One-hot sentiment
+        sentiment_vec = np.zeros(len(SENTIMENT_MAP), dtype=np.float32)
+        sentiment_vec[SENTIMENT_MAP[email["sentiment"]]] = 1.0
+
+        # One-hot context
+        context_vec = np.zeros(len(CONTEXT_MAP), dtype=np.float32)
+        context_vec[CONTEXT_MAP[email["context"]]] = 1.0
+
+        return np.concatenate([kw_flags, sentiment_vec, context_vec])
+
+    def _compute_reward(self, action: np.ndarray, email: dict) -> float:
+        """
+        Strict reward rules (priority order mein check hote hain):
+          -2.0  — security breach email ko urgency=2 nahi diya (sabse bada penalty)
+          +1.0  — teeno actions bilkul sahi (exact match)
+          +0.2  — sirf urgency sahi, routing AUR resolution dono sahi (2 out of 3)
+          +0.1  — sirf urgency sahi, baaki ek galat (1 dimension wrong)
+           0.0  — urgency hi galat hai (non-security email)
+        """
+        urgency    = int(action[0])
+        routing    = int(action[1])
+        resolution = int(action[2])
+        correct    = email["correct_actions"]
+
+        # Priority 1: Security breach miss — sabse bada crime
+        if correct[0] == 2 and urgency != 2:
+            return PENALTY_MISSED_SECURITY
+
+        # Priority 2: Perfect match
+        if (urgency, routing, resolution) == correct:
+            return REWARD_CORRECT_FULL
+
+        # Priority 3: Urgency sahi hai — partial credit
+        if urgency == correct[0]:
+            # Dono routing aur resolution galat hain
+            routing_ok    = (routing    == correct[1])
+            resolution_ok = (resolution == correct[2])
+            if routing_ok and not resolution_ok:
+                return REWARD_PARTIAL_ONE_WRONG   # sirf resolution galat
+            if resolution_ok and not routing_ok:
+                return REWARD_PARTIAL_ONE_WRONG   # sirf routing galat
+            return REWARD_PARTIAL_BOTH_WRONG      # dono galat
+
+        return 0.0
+
+    # ------------------------------------------------------------------
+    # gymnasium API
+    # ------------------------------------------------------------------
+
+    def reset(self, *, seed: int | None = None, options: dict | None = None):
+        super().reset(seed=seed)
+
+        self._queue = list(self.email_batch)
+        if self.shuffle:
+            self.np_random.shuffle(self._queue)  # uses gymnasium's seeded RNG
+
+        self._step_idx = 0
+        self._current_email = self._queue[self._step_idx]
+
+        obs = self._encode(self._current_email)
+        info = {"description": self._current_email["description"],
+                "difficulty": self._current_email["difficulty"]}
+        return obs, info
+
+    def step(self, action: np.ndarray):
+        """
+        Process one email triage decision.
+
+        Returns
+        -------
+        obs, reward, terminated, truncated, info
+        """
+        # ── Bug Fix: correct_actions PEHLE save karo, PHIR pointer badlao ──
+        # Pehle current email ka ground truth capture karo reward ke saath
+        scored_email    = self._current_email
+        reward          = self._compute_reward(action, scored_email)
+        normalised_reward = reward / self._max_episode_reward
+
+        # Ab pointer aage badhao
+        self._step_idx += 1
+        terminated = self._step_idx >= len(self._queue)
+
+        if not terminated:
+            self._current_email = self._queue[self._step_idx]
+            obs = self._encode(self._current_email)
+        else:
+            obs = self._encode(scored_email)  # terminal step pe last obs return karo
+
+        # info mein SCORED email ka data — agli email ka nahi
+        info = {
+            "raw_reward":      reward,
+            "correct_actions": scored_email["correct_actions"],
+            "difficulty":      scored_email["difficulty"],
+            "description":     scored_email.get("description", ""),
+        }
+        return obs, normalised_reward, terminated, False, info
+
+    def render(self, mode: str = "human"):
+        """Print current email details to stdout."""
+        e = self._current_email
+        print(f"[Step {self._step_idx}] {e['description']} "
+              f"| difficulty={e['difficulty']} "
+              f"| sentiment={e['sentiment']} "
+              f"| context={e['context']}")

inference.py

@@ -0,0 +1,189 @@
+"""
+inference.py — OpenEnv Baseline Inference Script
+=================================================
+Runs the rule-based classifier against all three tasks defined in
+openenv.yaml and reports per-task scores in the 0.0 → 1.0 range.
+
+This script proves reproducibility for the hackathon submission.
+Run it with:
+    python inference.py
+
+Expected output:
+    Task 1 [EASY]   — Spam Detection          : 1.000  ✅
+    Task 2 [MEDIUM] — Support Routing         : 0.950  ✅
+    Task 3 [HARD]   — Phishing / Security     : 0.900  ✅
+    Overall Score                             : 0.950
+"""
+
+import numpy as np
+from env import (
+    EmailTriageEnv,
+    EmailAction,
+    TASK_SPLITS,
+    URGENCY_LABELS,
+    ROUTING_LABELS,
+    RESOLUTION_LABELS,
+)
+
+# ── Rule-based classifier (your 95%-accuracy agent) ───────────────────────────
+
+_LEGAL_SECURITY_KW   = {"lawsuit", "attorney", "sue", "ransomware", "extortion"}
+_BILLING_ESCALATE_KW = {"refund"}
+
+
+def _classify(email: dict) -> np.ndarray:
+    """
+    Deterministic rule-based classifier.
+    Returns np.ndarray([urgency, routing, resolution]).
+    """
+    kw      = set(email.get("keywords", []))
+    context = email.get("context", "").lower()
+
+    if context == "legal" or kw & {"lawsuit", "attorney", "sue"}:
+        return np.array([2, 2, 2], dtype=np.int64)
+
+    if context == "security":
+        if kw & _LEGAL_SECURITY_KW or ("hacked" in kw and "breach" in kw):
+            return np.array([2, 2, 2], dtype=np.int64)
+        return np.array([2, 1, 2], dtype=np.int64)
+
+    if context == "billing":
+        if kw & _BILLING_ESCALATE_KW:
+            return np.array([1, 2, 2], dtype=np.int64)
+        return np.array([1, 0, 1], dtype=np.int64)
+
+    if context == "tech" or kw & {"crash", "error", "bug", "slow"}:
+        return np.array([0, 1, 1], dtype=np.int64)
+
+    return np.array([0, 0, 0], dtype=np.int64)
+
+
+# ── Per-task runner ───────────────────────────────────────────────────────────
+
+def run_task(task: str, verbose: bool = False) -> float:
+    """
+    Run one full episode on the given task using the rule-based classifier.
+    Returns the normalised cumulative score in [0.0, 1.0].
+    """
+    env = EmailTriageEnv(task=task, shuffle=False)
+    obs, info = env.reset(seed=42)
+
+    email_queue      = list(env._queue)   # snapshot before any steps
+    cumulative_score = 0.0
+    step             = 0
+    terminated       = False
+
+    task_labels = {
+        "easy":   "Task 1 [EASY]   — Spam Detection         ",
+        "medium": "Task 2 [MEDIUM] — Support Routing        ",
+        "hard":   "Task 3 [HARD]   — Phishing / Security    ",
+    }
+
+    if verbose:
+        print(f"\n  {'─' * 58}")
+        print(f"  {task_labels.get(task, task.upper())}")
+        print(f"  {'─' * 58}")
+
+    while not terminated:
+        current_email = email_queue[step]
+        action        = _classify(current_email)
+
+        obs, norm_reward, terminated, _, info = env.step(action)
+        cumulative_score += norm_reward
+
+        if verbose:
+            ca  = info["correct_actions"]
+            raw = info["raw_reward"]
+
+            pred_str = (f"{URGENCY_LABELS[action[0]]} | "
+                        f"{ROUTING_LABELS[action[1]]} | "
+                        f"{RESOLUTION_LABELS[action[2]]}")
+            corr_str = (f"{URGENCY_LABELS[ca[0]]} | "
+                        f"{ROUTING_LABELS[ca[1]]} | "
+                        f"{RESOLUTION_LABELS[ca[2]]}")
+
+            if raw >= 1.0:
+                verdict = "✅ EXACT"
+            elif raw > 0:
+                verdict = "🔶 PARTIAL"
+            elif raw < 0:
+                verdict = "🚨 SECURITY MISS"
+            else:
+                verdict = "❌ WRONG"
+
+            print(f"  #{step+1:02d} [{current_email['difficulty'].upper():<6}] "
+                  f"{current_email['description'][:35]:<35} "
+                  f"reward={raw:+.1f}  {verdict}")
+            if raw < 1.0:
+                print(f"       Predicted : {pred_str}")
+                print(f"       Correct   : {corr_str}")
+
+        step += 1
+
+    # Clamp to [0.0, 1.0] — penalties can push below 0
+    final_score = max(0.0, min(1.0, cumulative_score))
+
+    env_state = env.state()
+    assert env_state.terminated, "Episode should be terminated after all steps"
+
+    return final_score
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+def main():
+    print(f"\n{'═' * 62}")
+    print("  EMAIL GATEKEEPER — OpenEnv Baseline Inference")
+    print("  Meta x PyTorch Hackathon | Reproducibility Report")
+    print(f"{'═' * 62}")
+
+    tasks = [
+        ("easy",   "Task 1 [EASY]   — Spam Detection         "),
+        ("medium", "Task 2 [MEDIUM] — Support Routing        "),
+        ("hard",   "Task 3 [HARD]   — Phishing / Security    "),
+    ]
+
+    scores      = {}
+    all_correct = 0
+    all_total   = 0
+
+    for task_id, label in tasks:
+        score = run_task(task_id, verbose=True)
+        scores[task_id] = score
+
+        n = len(TASK_SPLITS[task_id])
+        all_total += n
+
+        icon = "✅" if score >= 0.8 else ("⚠️ " if score >= 0.5 else "❌")
+        print(f"\n  {label}: {score:.3f}  {icon}")
+
+    # Overall score = weighted average by number of emails per task
+    weights      = {t: len(TASK_SPLITS[t]) for t in scores}
+    total_weight = sum(weights.values())
+    overall      = sum(scores[t] * weights[t] / total_weight for t in scores)
+
+    print(f"\n{'─' * 62}")
+    print(f"  {'Overall Score (weighted avg)':<42}: {overall:.3f}")
+    print(f"  {'Total Emails Evaluated':<42}: {total_weight}")
+
+    # Per-task summary table
+    print(f"\n  {'Task':<10} {'Emails':>7} {'Score':>8} {'Status':>10}")
+    print(f"  {'─'*10} {'─'*7} {'─'*8} {'─'*10}")
+    for task_id, label in tasks:
+        n      = len(TASK_SPLITS[task_id])
+        s      = scores[task_id]
+        status = "PASS ✅" if s >= 0.8 else ("WARN ⚠️ " if s >= 0.5 else "FAIL ❌")
+        print(f"  {task_id:<10} {n:>7} {s:>8.3f} {status:>10}")
+
+    print(f"\n{'═' * 62}\n")
+
+    # Return scores dict for programmatic use (e.g. CI pipelines)
+    return {
+        "task_scores": scores,
+        "overall":     round(overall, 4),
+        "total_emails": total_weight,
+    }
+
+
+if __name__ == "__main__":
+    results = main()

lambda/classifier.py

@@ -0,0 +1,118 @@
+"""
+classifier.py — Portable rule-based email classifier for AWS Lambda.
+Extracted from inference.py with zero heavy dependencies (no numpy/gymnasium).
+All logic is identical to the local rule engine.
+"""
+
+# ── Label maps (mirrors environment.py) ─────────────────────────────────────
+URGENCY_LABELS    = {0: "General",       1: "Billing",      2: "Security Breach"}
+ROUTING_LABELS    = {0: "AI Auto-Reply", 1: "Tech Support", 2: "Legal"}
+RESOLUTION_LABELS = {0: "Archive",       1: "Draft Reply",  2: "Escalate"}
+
+# Keywords that push a security email to Legal (ransomware / extortion level).
+_LEGAL_SECURITY_KW  = {"lawsuit", "attorney", "sue", "ransomware", "extortion", "legal"}
+
+# Only "refund" escalates a billing email to Legal — "overdue" stays routine.
+_BILLING_ESCALATE_KW = {"refund"}
+
+# Full keyword vocabulary used for feature extraction from raw email text.
+KEYWORD_VOCAB = [
+    "invoice", "payment", "overdue", "refund",
+    "hacked", "breach", "unauthorized", "password",
+    "crash", "error", "bug", "slow",
+    "lawsuit", "legal", "attorney", "sue",
+    "spam", "offer", "win", "free",
+    "urgent", "critical", "angry", "threat",
+]
+
+
+def extract_features(subject: str, body: str) -> dict:
+    """
+    Parse raw email text into the feature dict expected by classify().
+    Returns: {keywords, sentiment, context}
+    """
+    text = (subject + " " + body).lower()
+    tokens = set(text.split())
+
+    keywords = [kw for kw in KEYWORD_VOCAB if kw in tokens]
+
+    # Simple sentiment: negative words outweigh positive
+    neg_words = {"angry", "threat", "hacked", "breach", "lawsuit", "overdue",
+                 "unauthorized", "ransomware", "critical", "urgent", "error",
+                 "crash", "bug", "refund"}
+    pos_words = {"win", "free", "offer", "congratulations", "prize"}
+
+    neg_hits = len(tokens & neg_words)
+    pos_hits = len(tokens & pos_words)
+
+    if neg_hits > pos_hits:
+        sentiment = "negative"
+    elif pos_hits > 0:
+        sentiment = "positive"
+    else:
+        sentiment = "neutral"
+
+    # Context: first strong signal wins
+    kw_set = set(keywords)
+    if kw_set & {"hacked", "breach", "unauthorized", "ransomware"}:
+        context = "security"
+    elif kw_set & {"lawsuit", "attorney", "sue"}:
+        context = "legal"
+    elif kw_set & {"invoice", "payment", "overdue", "refund"}:
+        context = "billing"
+    elif kw_set & {"crash", "error", "bug", "slow", "password"}:
+        context = "tech"
+    elif kw_set & {"spam", "offer", "win", "free"}:
+        context = "spam"
+    else:
+        context = "general"
+
+    return {"keywords": keywords, "sentiment": sentiment, "context": context}
+
+
+def classify(email: dict) -> tuple[int, int, int]:
+    """
+    Rule-based classifier. Accepts a feature dict (keywords, context).
+    Returns (urgency, routing, resolution) as plain ints.
+
+    Priority order (first match wins):
+      1. Legal context / legal keywords  → (2, 2, 2)
+      2. Security + legal signal         → (2, 2, 2)
+      2. Security account-level          → (2, 1, 2)
+      3. Billing dispute (refund)        → (1, 2, 2)
+      4. Billing routine                 → (1, 0, 1)
+      5. Tech support                    → (0, 1, 1)
+      6. Spam / default                  → (0, 0, 0)
+    """
+    kw      = set(email.get("keywords", []))
+    context = email.get("context", "").lower()
+
+    if context == "legal" or kw & {"lawsuit", "attorney", "sue"}:
+        return (2, 2, 2)
+
+    if context == "security":
+        if kw & _LEGAL_SECURITY_KW or ("hacked" in kw and "breach" in kw):
+            return (2, 2, 2)
+        return (2, 1, 2)
+
+    if context == "billing":
+        if kw & _BILLING_ESCALATE_KW:
+            return (1, 2, 2)
+        return (1, 0, 1)
+
+    if context == "tech" or kw & {"crash", "error", "bug", "slow"}:
+        return (0, 1, 1)
+
+    return (0, 0, 0)
+
+
+def decode(urgency: int, routing: int, resolution: int) -> dict:
+    """Convert integer action tuple to human-readable label dict."""
+    return {
+        "urgency_code":    urgency,
+        "routing_code":    routing,
+        "resolution_code": resolution,
+        "urgency":         URGENCY_LABELS[urgency],
+        "routing":         ROUTING_LABELS[routing],
+        "resolution":      RESOLUTION_LABELS[resolution],
+    }

lambda/handler.py

@@ -0,0 +1,156 @@
+"""
+handler.py — AWS Lambda entry point for the Email Gatekeeper.
+
+Trigger paths:
+  A) S3 Event    : SES stores raw .eml → S3 → Lambda (s3:ObjectCreated)
+  B) Direct JSON : {"subject": "...", "body": "..."} for testing / API Gateway
+
+On each invocation:
+  1. Parse the email (S3 object or direct payload)
+  2. Extract features  (classifier.extract_features)
+  3. Classify          (classifier.classify)
+  4. Persist result    → DynamoDB table  (EMAIL_RESULTS_TABLE env var)
+  5. Alert on breach   → SNS topic       (SECURITY_ALERT_TOPIC_ARN env var)
+  6. Return JSON result
+"""
+
+import json
+import os
+import email
+import uuid
+import logging
+from datetime import datetime, timezone
+
+import boto3
+
+from classifier import classify, decode, extract_features
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+# AWS clients — initialised once at cold-start for connection reuse
+_s3       = boto3.client("s3")
+_dynamodb = boto3.resource("dynamodb")
+_sns      = boto3.client("sns")
+
+# Environment variables injected by CDK
+_TABLE_NAME  = os.environ.get("EMAIL_RESULTS_TABLE", "")
+_TOPIC_ARN   = os.environ.get("SECURITY_ALERT_TOPIC_ARN", "")
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _parse_eml(raw_bytes: bytes) -> tuple[str, str]:
+    """Extract subject and plain-text body from a raw .eml byte string."""
+    msg = email.message_from_bytes(raw_bytes)
+    subject = msg.get("Subject", "")
+
+    body = ""
+    if msg.is_multipart():
+        for part in msg.walk():
+            if part.get_content_type() == "text/plain":
+                body = part.get_payload(decode=True).decode("utf-8", errors="replace")
+                break
+    else:
+        body = msg.get_payload(decode=True).decode("utf-8", errors="replace")
+
+    return subject, body
+
+
+def _fetch_from_s3(bucket: str, key: str) -> tuple[str, str]:
+    """Download a raw .eml from S3 and return (subject, body)."""
+    logger.info("Fetching s3://%s/%s", bucket, key)
+    obj = _s3.get_object(Bucket=bucket, Key=key)
+    raw = obj["Body"].read()
+    return _parse_eml(raw)
+
+
+def _save_to_dynamodb(record: dict) -> None:
+    """Persist the triage result to DynamoDB (best-effort, non-blocking)."""
+    if not _TABLE_NAME:
+        return
+    try:
+        table = _dynamodb.Table(_TABLE_NAME)
+        table.put_item(Item=record)
+    except Exception as exc:
+        logger.error("DynamoDB write failed: %s", exc)
+
+
+def _alert_security(record: dict) -> None:
+    """Publish an SNS alert when a Security Breach is detected."""
+    if not _TOPIC_ARN:
+        return
+    try:
+        _sns.publish(
+            TopicArn=_TOPIC_ARN,
+            Subject="🚨 Security Breach Email Detected",
+            Message=json.dumps(record, indent=2),
+        )
+        logger.info("SNS alert published for email_id=%s", record.get("email_id"))
+    except Exception as exc:
+        logger.error("SNS publish failed: %s", exc)
+
+
+# ── Main handler ─────────────────────────────────────────────────────────────
+
+def lambda_handler(event: dict, context) -> dict:
+    """
+    Unified entry point for S3-triggered and direct-invocation events.
+
+    S3 event shape (from SES → S3 → Lambda notification):
+      {"Records": [{"s3": {"bucket": {"name": "..."}, "object": {"key": "..."}}}]}
+
+    Direct invocation shape (for testing or API Gateway):
+      {"subject": "Your invoice is overdue", "body": "Please pay immediately."}
+    """
+    logger.info("Event received: %s", json.dumps(event)[:500])
+
+    # ── Determine input source ────────────────────────────────────────────────
+    records = event.get("Records", [])
+
+    if records and records[0].get("eventSource") == "aws:s3":
+        # Path A: triggered by S3 object creation (SES-delivered email)
+        s3_info = records[0]["s3"]
+        bucket  = s3_info["bucket"]["name"]
+        key     = s3_info["object"]["key"]
+        subject, body = _fetch_from_s3(bucket, key)
+        source_ref = f"s3://{bucket}/{key}"
+    else:
+        # Path B: direct JSON invocation (testing / API Gateway)
+        subject    = event.get("subject", "")
+        body       = event.get("body", "")
+        source_ref = "direct-invocation"
+
+    if not subject and not body:
+        return {"statusCode": 400, "body": "No email content found in event."}
+
+    # ── Classify ──────────────────────────────────────────────────────────────
+    features              = extract_features(subject, body)
+    urgency, routing, res = classify(features)
+    result                = decode(urgency, routing, res)
+
+    # ── Build persistence record ──────────────────────────────────────────────
+    email_id = str(uuid.uuid4())
+    record = {
+        "email_id":        email_id,
+        "timestamp":       datetime.now(timezone.utc).isoformat(),
+        "source":          source_ref,
+        "subject":         subject[:500],           # cap to avoid DDB item size issues
+        "detected_keywords": features["keywords"],
+        "sentiment":       features["sentiment"],
+        "context":         features["context"],
+        **result,                                   # urgency/routing/resolution labels + codes
+    }
+
+    logger.info("Classification result: %s", json.dumps(result))
+
+    # ── Persist & alert ───────────────────────────────────────────────────────
+    _save_to_dynamodb(record)
+
+    if urgency == 2:                                # Security Breach
+        _alert_security(record)
+
+    return {
+        "statusCode": 200,
+        "body": json.dumps(record),
+    }

openenv.yaml

@@ -0,0 +1,176 @@
+# openenv.yaml — Email Gatekeeper RL Environment
+# OpenEnv Specification v1.0
+# Meta x PyTorch Hackathon Submission
+# ============================================================
+
+name: email-gatekeeper
+version: "1.0.0"
+description: >
+  Intelligent Email Gatekeeper — a Gymnasium-based Reinforcement Learning
+  environment where an agent learns to triage emails by simultaneously
+  predicting three dimensions: Urgency Category, Department Routing,
+  and Resolution Action. Covers 32 scenarios across spam detection,
+  support routing, and phishing/security threat identification.
+
+author: zerogravity
+license: MIT
+framework: gymnasium
+python_requires: ">=3.10"
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+entry_point: "env:EmailTriageEnv"
+
+# ── Observation space ─────────────────────────────────────────────────────────
+observation_space:
+  type: Box
+  shape: [32]
+  dtype: float32
+  low: 0.0
+  high: 1.0
+  description: >
+    Flat vector of 32 floats encoding:
+      [0:24]  Binary keyword flags (24 vocab words)
+      [24:27] One-hot sentiment    (positive / neutral / negative)
+      [27:32] One-hot context      (spam / billing / tech / security / legal)
+
+# ── Action space ──────────────────────────────────────────────────────────────
+action_space:
+  type: MultiDiscrete
+  nvec: [3, 3, 3]
+  dimensions:
+    - name: urgency
+      index: 0
+      values:
+        0: General
+        1: Billing
+        2: Security Breach
+    - name: routing
+      index: 1
+      values:
+        0: AI Auto-Reply
+        1: Tech Support
+        2: Legal
+    - name: resolution
+      index: 2
+      values:
+        0: Archive
+        1: Draft Reply
+        2: Escalate
+
+# ── Reward function ───────────────────────────────────────────────────────────
+reward:
+  description: >
+    Strict penalty-based reward. Security breach misses are penalised
+    at 4x the magnitude of a correct answer to reflect real-world risk.
+  rules:
+    - condition: "correct urgency=2 but predicted urgency != 2"
+      reward: -2.0
+      label: SECURITY_MISS
+    - condition: "all three dimensions exactly correct"
+      reward: +1.0
+      label: EXACT
+    - condition: "urgency correct, exactly one other dimension wrong"
+      reward: +0.2
+      label: PARTIAL_1
+    - condition: "urgency correct, both other dimensions wrong"
+      reward: +0.1
+      label: PARTIAL_2
+    - condition: "urgency wrong on non-security email"
+      reward: 0.0
+      label: WRONG
+  normalisation: >
+    Each raw reward is divided by (num_emails * 1.0) so the ideal
+    cumulative episode score = 1.0
+
+# ── Tasks ─────────────────────────────────────────────────────────────────────
+tasks:
+
+  - id: easy
+    name: "Task 1 — Spam vs Real Email Detection"
+    difficulty: easy
+    description: >
+      Agent must distinguish promotional spam from legitimate emails
+      and assign correct General/Billing urgency with appropriate routing.
+    num_emails: 4
+    email_types:
+      - Spam promotional
+      - Spam lottery
+      - Routine tech support
+      - General billing inquiry
+    target_score: 1.0
+    baseline_score: 1.0
+    success_threshold: 0.8
+
+  - id: medium
+    name: "Task 2 — Support Routing & Passive-Aggressive Legal Threats"
+    difficulty: medium
+    description: >
+      Agent must correctly route billing disputes, tech issues, and
+      passive-aggressive legal threats that use polite language to
+      disguise escalation intent.
+    num_emails: 8
+    email_types:
+      - Overdue invoice complaint
+      - Refund dispute
+      - App crash report
+      - Persistent login bug
+      - Polite legal ultimatum
+      - Attorney CC warning
+      - Regulatory complaint
+      - SLA breach legal notice
+    target_score: 1.0
+    baseline_score: 0.95
+    success_threshold: 0.75
+
+  - id: hard
+    name: "Task 3 — Phishing Detection & Security Threat Classification"
+    difficulty: hard
+    description: >
+      Agent must identify subtle phishing attempts disguised as IT notices,
+      HR emails, and vendor requests, plus classify ransomware and extortion
+      threats that combine security and legal signals.
+    num_emails: 16
+    email_types:
+      - IT audit phishing
+      - Fake invoice portal redirect
+      - HR credential capture
+      - Fake account suspension
+      - Business Email Compromise (BEC)
+      - Sign-in alert phishing
+      - Payroll migration phish
+      - License renewal BEC
+      - GDPR phishing with legal overlay
+      - Ransomware disguised as audit
+      - Data extortion threat
+      - Fake law firm letter
+      - Account hacked urgent
+      - Data breach notification
+      - Legal lawsuit threat
+      - Ransomware extortion
+    target_score: 1.0
+    baseline_score: 0.90
+    success_threshold: 0.70
+
+# ── Environment parameters ────────────────────────────────────────────────────
+parameters:
+  shuffle:
+    type: bool
+    default: true
+    description: Shuffle email order on each reset for training variety
+  task:
+    type: str
+    default: all
+    choices: [easy, medium, hard, all]
+    description: Which difficulty subset to load
+
+# ── Dependencies ──────────────────────────────────────────────────────────────
+dependencies:
+  - gymnasium>=0.29.0
+  - numpy>=1.24.0
+  - pydantic>=2.0.0
+
+# ── Reproducibility ───────────────────────────────────────────────────────────
+reproducibility:
+  seed: 42
+  deterministic: true
+  baseline_script: inference.py

requirements.txt

@@ -0,0 +1,8 @@
+fastapi
+uvicorn
+gymnasium
+numpy>
+pydantic
+gradio
+pyyaml
+google-generativeai

sagemaker/classifier.py

@@ -0,0 +1,158 @@
+"""
+classifier.py — Production Rule-Based Email Classifier
+=======================================================
+Shared by SageMaker inference.py and Lambda handler.py.
+Zero heavy dependencies — no numpy, no gymnasium.
+
+Key fix vs lambda/classifier.py:
+  "legal" removed from _LEGAL_SECURITY_KW — it is a deception keyword
+  in phishing emails (TC-H-09), not a routing signal. Context field
+  is the authoritative source for legal routing.
+"""
+
+# ── Label maps ────────────────────────────────────────────────────────────────
+URGENCY_LABELS    = {0: "General",       1: "Billing",      2: "Security Breach"}
+ROUTING_LABELS    = {0: "AI Auto-Reply", 1: "Tech Support", 2: "Legal"}
+RESOLUTION_LABELS = {0: "Archive",       1: "Draft Reply",  2: "Escalate"}
+
+# Security emails that need Legal routing (ransomware / extortion / IP theft).
+# NOTE: "legal" intentionally excluded — it appears in phishing deception text.
+_LEGAL_SECURITY_KW   = {"lawsuit", "attorney", "sue", "ransomware", "extortion"}
+
+# Only "refund" escalates billing to Legal — "overdue" stays routine.
+_BILLING_ESCALATE_KW = {"refund"}
+
+# Canonical keyword vocabulary (must match environment.py KEYWORD_VOCAB)
+KEYWORD_VOCAB = [
+    "invoice",  "payment",      "overdue",  "refund",
+    "hacked",   "breach",       "unauthorized", "password",
+    "crash",    "error",        "bug",      "slow",
+    "lawsuit",  "legal",        "attorney", "sue",
+    "spam",     "offer",        "win",      "free",
+    "urgent",   "critical",     "angry",    "threat",
+]
+
+# Words used for sentiment scoring
+_NEG_WORDS = {
+    "angry", "threat", "hacked", "breach", "lawsuit", "overdue",
+    "unauthorized", "ransomware", "critical", "urgent", "error",
+    "crash", "bug", "refund",
+}
+_POS_WORDS = {"win", "free", "offer", "congratulations", "prize"}
+
+
+# ── Feature extraction ────────────────────────────────────────────────────────
+
+def extract_features(subject: str, body: str) -> dict:
+    """
+    Parse raw email text → feature dict {keywords, sentiment, context}.
+    Used when the caller does not supply pre-computed features.
+    """
+    text   = (subject + " " + body).lower()
+    tokens = set(text.split())
+
+    keywords = [kw for kw in KEYWORD_VOCAB if kw in tokens]
+    kw_set   = set(keywords)
+
+    # Sentiment
+    neg_hits = len(tokens & _NEG_WORDS)
+    pos_hits = len(tokens & _POS_WORDS)
+    if neg_hits > pos_hits:
+        sentiment = "negative"
+    elif pos_hits > 0:
+        sentiment = "positive"
+    else:
+        sentiment = "neutral"
+
+    # Context — priority order matches the classifier decision tree
+    if kw_set & {"hacked", "breach", "unauthorized", "ransomware"}:
+        context = "security"
+    elif kw_set & {"lawsuit", "attorney", "sue"}:
+        context = "legal"
+    elif kw_set & {"invoice", "payment", "overdue", "refund"}:
+        context = "billing"
+    elif kw_set & {"crash", "error", "bug", "slow", "password"}:
+        context = "tech"
+    elif kw_set & {"spam", "offer", "win", "free"}:
+        context = "spam"
+    else:
+        context = "general"
+
+    return {"keywords": keywords, "sentiment": sentiment, "context": context}
+
+
+# ── Classifier ────────────────────────────────────────────────────────────────
+
+def classify(email: dict) -> tuple[int, int, int]:
+    """
+    Deterministic rule-based classifier.
+    Returns (urgency, routing, resolution) as plain ints.
+
+    Decision tree — first match wins:
+      Rule 1  legal context OR lawsuit/attorney/sue keywords → (2, 2, 2)
+      Rule 2a security + ransomware/extortion/hacked+breach  → (2, 2, 2)
+      Rule 2b security (account-level attack)                → (2, 1, 2)
+      Rule 3  billing + refund keyword                       → (1, 2, 2)
+      Rule 4  billing routine                                → (1, 0, 1)
+      Rule 5  tech context or crash/error/bug/slow           → (0, 1, 1)
+      Rule 6  spam / default                                 → (0, 0, 0)
+    """
+    kw      = set(email.get("keywords", []))
+    context = email.get("context", "").lower()
+
+    # Rule 1 — Legal
+    if context == "legal" or kw & {"lawsuit", "attorney", "sue"}:
+        return (2, 2, 2)
+
+    # Rule 2 — Security
+    if context == "security":
+        if kw & _LEGAL_SECURITY_KW or ("hacked" in kw and "breach" in kw):
+            return (2, 2, 2)   # ransomware / extortion → Legal
+        return (2, 1, 2)       # account-level attack   → Tech Support
+
+    # Rule 3 & 4 — Billing
+    if context == "billing":
+        return (1, 2, 2) if kw & _BILLING_ESCALATE_KW else (1, 0, 1)
+
+    # Rule 5 — Tech
+    if context == "tech" or kw & {"crash", "error", "bug", "slow"}:
+        return (0, 1, 1)
+
+    # Rule 6 — Spam / default
+    return (0, 0, 0)
+
+
+# ── Decoder ───────────────────────────────────────────────────────────────────
+
+def decode(urgency: int, routing: int, resolution: int) -> dict:
+    """Convert integer action codes to human-readable label dict."""
+    return {
+        "urgency":    URGENCY_LABELS[urgency],
+        "routing":    ROUTING_LABELS[routing],
+        "resolution": RESOLUTION_LABELS[resolution],
+    }
+
+
+# ── Batch helper ─────────────────────────────────────────────────────────────
+
+def classify_batch(emails: list[dict]) -> list[dict]:
+    """
+    Classify a list of email dicts in one call.
+    Each dict may contain pre-computed features OR raw subject+body.
+    Returns a list of decode() dicts with codes attached.
+    """
+    results = []
+    for email in emails:
+        if not email.get("context"):
+            features = extract_features(
+                email.get("subject", ""),
+                email.get("body", ""),
+            )
+        else:
+            features = email
+
+        u, r, res = classify(features)
+        result    = decode(u, r, res)
+        result.update({"urgency_code": u, "routing_code": r, "resolution_code": res})
+        results.append(result)
+    return results

sagemaker/deploy.py

@@ -0,0 +1,285 @@
+"""
+deploy.py — SageMaker Endpoint Deployment Script
+=================================================
+Packages the rule-based classifier and deploys it as a real-time
+SageMaker endpoint with full CloudWatch monitoring support.
+
+Prerequisites:
+    pip install boto3 sagemaker
+
+Usage:
+    python deploy.py                         # deploy only
+    python deploy.py --test                  # deploy + smoke tests
+    python deploy.py --monitor               # deploy + smoke tests + CW dashboard
+    python deploy.py --delete                # tear down endpoint
+
+AWS permissions required on your IAM user/role:
+    sagemaker:CreateModel, CreateEndpointConfig, CreateEndpoint
+    sagemaker:InvokeEndpoint, DeleteEndpoint
+    s3:PutObject          (SageMaker default bucket)
+    iam:PassRole          (SageMaker execution role)
+    iam:PutRolePolicy     (to attach CW policy to execution role)
+    cloudwatch:PutDashboard
+"""
+
+import argparse
+import json
+import os
+import tarfile
+import tempfile
+
+import boto3
+import sagemaker
+from sagemaker.sklearn.model import SKLearnModel
+
+# ── Configuration — edit these ────────────────────────────────────────────────
+ENDPOINT_NAME   = "email-gatekeeper-v1"
+INSTANCE_TYPE   = "ml.t2.medium"        # cheapest real-time; upgrade for prod
+SKLEARN_VERSION = "1.2-1"
+CW_NAMESPACE    = "EmailGatekeeper/Inference"   # must match inference.py
+REGION          = boto3.session.Session().region_name or "us-east-1"
+
+_MODEL_FILES = [
+    os.path.join(os.path.dirname(__file__), "inference.py"),
+    os.path.join(os.path.dirname(__file__), "classifier.py"),
+]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _build_model_tar(s3_client, bucket: str, prefix: str) -> str:
+    """Bundle inference.py + classifier.py → model.tar.gz → S3, return URI."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tar_path = os.path.join(tmpdir, "model.tar.gz")
+        with tarfile.open(tar_path, "w:gz") as tar:
+            for fpath in _MODEL_FILES:
+                tar.add(fpath, arcname=os.path.basename(fpath))
+            # config.json lets model_fn read runtime overrides without redeploying
+            config_path = os.path.join(tmpdir, "config.json")
+            with open(config_path, "w") as f:
+                json.dump({"version": "1.0.0", "cw_namespace": CW_NAMESPACE}, f)
+            tar.add(config_path, arcname="config.json")
+
+        s3_key = f"{prefix}/model.tar.gz"
+        s3_client.upload_file(tar_path, bucket, s3_key)
+        s3_uri = f"s3://{bucket}/{s3_key}"
+        print(f"  ✅ model.tar.gz → {s3_uri}")
+        return s3_uri
+
+
+def _ensure_cloudwatch_policy(role_name: str) -> None:
+    """
+    Attach an inline IAM policy to the SageMaker execution role so the
+    container can call cloudwatch:PutMetricData. Idempotent.
+    Scoped to CW_NAMESPACE only — least-privilege.
+    """
+    iam = boto3.client("iam", region_name=REGION)
+    policy = {
+        "Version": "2012-10-17",
+        "Statement": [{
+            "Sid":      "EmailGatekeeperCWMetrics",
+            "Effect":   "Allow",
+            "Action":   ["cloudwatch:PutMetricData"],
+            "Resource": "*",
+            "Condition": {
+                "StringEquals": {"cloudwatch:namespace": CW_NAMESPACE}
+            },
+        }],
+    }
+    iam.put_role_policy(
+        RoleName=role_name,
+        PolicyName="EmailGatekeeperCloudWatchMetrics",
+        PolicyDocument=json.dumps(policy),
+    )
+    print(f"  ✅ CloudWatch IAM policy attached → role: {role_name}")
+
+
+def _create_cloudwatch_dashboard() -> None:
+    """
+    Create (or overwrite) a 6-widget CloudWatch dashboard:
+      Row 1 — ExactMatch rate        | PartialMatch rate
+      Row 2 — SecurityMiss count     | WrongClassification count
+      Row 3 — Avg RewardScore        | SecurityBreachFlag count
+    """
+    cw = boto3.client("cloudwatch", region_name=REGION)
+
+    def _widget(title, metric, stat="Sum", color="#1f77b4"):
+        return {
+            "type": "metric",
+            "width": 12,
+            "height": 6,
+            "properties": {
+                "title":   title,
+                "metrics": [[CW_NAMESPACE, metric,
+                              "EndpointName", ENDPOINT_NAME]],
+                "stat":    stat,
+                "period":  300,
+                "view":    "timeSeries",
+                "color":   color,
+                "region":  REGION,
+            },
+        }
+
+    dashboard_body = {
+        "widgets": [
+            _widget("✅ Exact Matches (5-min)",       "ExactMatch",          color="#2ca02c"),
+            _widget("🔶 Partial Matches (5-min)",     "PartialMatch",        color="#ff7f0e"),
+            _widget("🚨 Security Misses (5-min)",     "SecurityMiss",        color="#d62728"),
+            _widget("❌ Wrong Classifications",        "WrongClassification", color="#9467bd"),
+            _widget("📈 Avg Reward Score",            "RewardScore",
+                    stat="Average",                                           color="#8c564b"),
+            _widget("🔒 Security Breach Flags",       "SecurityBreachFlag",  color="#e377c2"),
+        ]
+    }
+
+    cw.put_dashboard(
+        DashboardName="EmailGatekeeper-Inference",
+        DashboardBody=json.dumps(dashboard_body),
+    )
+    print("  ✅ CloudWatch dashboard created: EmailGatekeeper-Inference")
+    print(f"     https://{REGION}.console.aws.amazon.com/cloudwatch/home"
+          f"?region={REGION}#dashboards:name=EmailGatekeeper-Inference")
+
+
+def _smoke_test(sm_runtime) -> None:
+    """Run 3 labelled test cases — one per urgency level — against the live endpoint."""
+    test_cases = [
+        {
+            "name": "Security Breach",
+            "payload": {
+                "subject": "Your account has been hacked",
+                "body":    "Unauthorized access detected. Reset your password immediately.",
+                # ground_truth triggers CW metric emission during smoke test
+                "ground_truth": {"urgency": 2, "routing": 1, "resolution": 2},
+            },
+            "expected_category": "Security Breach",
+        },
+        {
+            "name": "Billing Dispute",
+            "payload": {
+                "subject": "Refund not received",
+                "body":    "I requested a refund 3 weeks ago and have not received it.",
+                "ground_truth": {"urgency": 1, "routing": 2, "resolution": 2},
+            },
+            "expected_category": "Billing",
+        },
+        {
+            "name": "Spam",
+            "payload": {
+                "subject": "You won a free prize!",
+                "body":    "Claim your free offer now. Win big today!",
+                "ground_truth": {"urgency": 0, "routing": 0, "resolution": 0},
+            },
+            "expected_category": "General",
+        },
+    ]
+
+    print("\n  Running smoke tests...")
+    all_passed = True
+
+    for tc in test_cases:
+        response = sm_runtime.invoke_endpoint(
+            EndpointName=ENDPOINT_NAME,
+            ContentType="application/json",
+            Accept="application/json",
+            Body=json.dumps(tc["payload"]),
+        )
+        result   = json.loads(response["Body"].read())
+        category = result["triage"]["category"]
+        match    = result.get("match_result", {})
+        passed   = category == tc["expected_category"]
+        icon     = "✅" if passed else "❌"
+        all_passed = all_passed and passed
+
+        print(f"  {icon} [{tc['name']}]  "
+              f"category='{category}'  "
+              f"match={match.get('status','?')}  "
+              f"reward={match.get('reward','?')}")
+
+    print(f"\n  Smoke tests: {'ALL PASSED ✅' if all_passed else 'SOME FAILED ❌'}")
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+def deploy(create_dashboard: bool = False) -> object:
+    sess      = sagemaker.Session()
+    bucket    = sess.default_bucket()
+    role      = sagemaker.get_execution_role()
+    role_name = role.split("/")[-1]
+    s3_client = boto3.client("s3", region_name=REGION)
+
+    print(f"\n{'═' * 62}")
+    print("  Email Gatekeeper — SageMaker + CloudWatch Deployment")
+    print(f"  Endpoint     : {ENDPOINT_NAME}")
+    print(f"  Instance     : {INSTANCE_TYPE}")
+    print(f"  Region       : {REGION}")
+    print(f"  CW Namespace : {CW_NAMESPACE}")
+    print(f"{'═' * 62}\n")
+
+    # 1. Attach CloudWatch IAM policy to execution role
+    print("  Attaching CloudWatch IAM policy...")
+    _ensure_cloudwatch_policy(role_name)
+
+    # 2. Package and upload model artifacts
+    print("  Packaging model artifacts...")
+    model_uri = _build_model_tar(s3_client, bucket, "email-gatekeeper/model")
+
+    # 3. Create SageMaker SKLearn model
+    #    env passes ENDPOINT_NAME into the container so model_fn can read it
+    model = SKLearnModel(
+        model_data=model_uri,
+        role=role,
+        entry_point="inference.py",
+        framework_version=SKLEARN_VERSION,
+        sagemaker_session=sess,
+        name=f"{ENDPOINT_NAME}-model",
+        env={"SAGEMAKER_ENDPOINT_NAME": ENDPOINT_NAME},
+    )
+
+    # 4. Deploy real-time endpoint
+    print("  Deploying endpoint (~5 min)...")
+    predictor = model.deploy(
+        initial_instance_count=1,
+        instance_type=INSTANCE_TYPE,
+        endpoint_name=ENDPOINT_NAME,
+    )
+    print(f"\n  ✅ Endpoint live: {ENDPOINT_NAME}")
+
+    # 5. Optional CloudWatch dashboard
+    if create_dashboard:
+        print("  Creating CloudWatch dashboard...")
+        _create_cloudwatch_dashboard()
+
+    return predictor
+
+
+def delete_endpoint() -> None:
+    sm = boto3.client("sagemaker", region_name=REGION)
+    print(f"  Deleting endpoint: {ENDPOINT_NAME}")
+    sm.delete_endpoint(EndpointName=ENDPOINT_NAME)
+    print("  ✅ Endpoint deleted")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--delete",  action="store_true", help="Delete the endpoint")
+    parser.add_argument("--test",    action="store_true", help="Run smoke tests after deploy")
+    parser.add_argument("--monitor", action="store_true", help="Create CloudWatch dashboard")
+    args = parser.parse_args()
+
+    if args.delete:
+        delete_endpoint()
+    else:
+        predictor  = deploy(create_dashboard=args.monitor)
+        sm_runtime = boto3.client("sagemaker-runtime", region_name=REGION)
+        if args.test or args.monitor:
+            _smoke_test(sm_runtime)
+        print(
+            f"\n  Invoke example (with ground_truth for CW metrics):\n"
+            f"  aws sagemaker-runtime invoke-endpoint \\\n"
+            f"    --endpoint-name {ENDPOINT_NAME} \\\n"
+            f"    --content-type application/json \\\n"
+            f"    --body '{{\"subject\":\"hacked\",\"body\":\"unauthorized access\","
+            f"\"ground_truth\":{{\"urgency\":2,\"routing\":1,\"resolution\":2}}}}' \\\n"
+            f"    response.json && cat response.json\n"
+        )

sagemaker/inference.py

@@ -0,0 +1,357 @@
+"""
+inference.py  —  SageMaker Entry Point  |  Email Gatekeeper  |  Phase 1
+========================================================================
+
+Think of this file like a circuit board with 4 connectors.
+SageMaker plugs into each one in order, every time a request arrives:
+
+  [1] model_fn   → Power-on.  Runs ONCE when the server starts.
+  [2] input_fn   → Input pin.  Reads the raw HTTP request bytes.
+  [3] predict_fn → Logic gate. Runs your classifier, scores the result.
+  [4] output_fn  → Output pin. Sends the JSON response back.
+
+Your classifier lives in classifier.py (same folder).
+No GPU, no heavy ML libraries needed — pure Python logic.
+"""
+
+import json
+import os
+import uuid
+import logging
+from datetime import datetime, timezone
+
+# classifier.py must be in the same folder as this file
+from classifier import classify, decode, extract_features
+
+# SageMaker streams all logger.info() calls to CloudWatch Logs automatically
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# ── Reward weights (must match environment.py exactly) ────────────────────────
+# These are the scores your RL agent learned against.
+# They are used here only for logging — not for routing decisions.
+_REWARDS = {
+    "EXACT":         1.0,   # all 3 dimensions correct
+    "PARTIAL_1":     0.2,   # urgency correct, 1 other dimension wrong
+    "PARTIAL_2":     0.1,   # urgency correct, both other dimensions wrong
+    "SECURITY_MISS": -2.0,  # security email but urgency was NOT flagged as 2
+    "WRONG":         0.0,   # urgency wrong on a non-security email
+}
+
+# ── SLA table: urgency code → response time target ───────────────────────────
+_SLA = {
+    0: {"priority": "P3", "respond_within_minutes": 1440},  # General  — 24 h
+    1: {"priority": "P2", "respond_within_minutes": 240},   # Billing  —  4 h
+    2: {"priority": "P1", "respond_within_minutes": 15},    # Security — 15 min
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: Partial-match scorer
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _score_match(predicted: tuple, ground_truth: dict) -> dict:
+    """
+    Compare the 3 predicted dimensions against the known correct answer.
+
+    Only called when the request includes a "ground_truth" field.
+    Useful for:
+      - Offline evaluation / batch testing
+      - Logging accuracy metrics to CloudWatch
+
+    Returns a dict with:
+      status       — one of EXACT / PARTIAL_1 / PARTIAL_2 / SECURITY_MISS / WRONG
+      reward       — float score matching your RL reward function
+      wrong_fields — list of dimension names that were predicted incorrectly
+    """
+    p_urgency, p_routing, p_resolution = predicted
+
+    g_urgency    = int(ground_truth["urgency"])
+    g_routing    = int(ground_truth["routing"])
+    g_resolution = int(ground_truth["resolution"])
+
+    # Which of the 3 dimensions are correct?
+    correct = {
+        "urgency":    p_urgency    == g_urgency,
+        "routing":    p_routing    == g_routing,
+        "resolution": p_resolution == g_resolution,
+    }
+    wrong = [dim for dim, ok in correct.items() if not ok]
+
+    # ── Decision tree (same priority order as environment.py) ─────────────────
+    # Rule 1: Security email that was NOT flagged as security → worst outcome
+    if g_urgency == 2 and p_urgency != 2:
+        status = "SECURITY_MISS"
+
+    # Rule 2: All 3 correct → perfect
+    elif not wrong:
+        status = "EXACT"
+
+    # Rule 3: Urgency correct but 1 other dimension wrong → partial credit
+    elif correct["urgency"] and len(wrong) == 1:
+        status = "PARTIAL_1"
+
+    # Rule 4: Urgency correct but both other dimensions wrong → small credit
+    elif correct["urgency"] and len(wrong) == 2:
+        status = "PARTIAL_2"
+
+    # Rule 5: Urgency itself wrong → no credit
+    else:
+        status = "WRONG"
+
+    logger.info(
+        "MATCH_EVAL | status=%s reward=%.1f wrong_fields=%s",
+        status, _REWARDS[status], wrong
+    )
+
+    return {
+        "status":       status,
+        "reward":       _REWARDS[status],
+        "correct_dims": correct,
+        "wrong_fields": wrong,
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [1] model_fn  —  Power-on. Runs ONCE at container start.
+# ───────────────��─────────────────────────────────────────────────────────────
+
+def model_fn(model_dir: str) -> dict:
+    """
+    SageMaker calls this once when the container boots up.
+    model_dir is the folder where SageMaker unpacks your model.tar.gz.
+
+    For a rule-based classifier there are no weights to load.
+    We just return a config dict that predict_fn will use.
+    """
+    logger.info("model_fn | model_dir=%s", model_dir)
+
+    # Optional: load a config.json from your model.tar.gz to override defaults
+    # at runtime without redeploying (e.g. change SLA targets).
+    config_path = os.path.join(model_dir, "config.json")
+    config = {}
+    if os.path.exists(config_path):
+        with open(config_path) as f:
+            config = json.load(f)
+        logger.info("Config loaded: %s", config)
+
+    model = {
+        "version":       config.get("version", "1.0.0"),
+        "sla":           config.get("sla", _SLA),
+        # SageMaker injects the endpoint name as an env var
+        "endpoint_name": os.environ.get("SAGEMAKER_ENDPOINT_NAME", "local"),
+    }
+
+    logger.info("Model ready | version=%s endpoint=%s",
+                model["version"], model["endpoint_name"])
+    return model
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [2] input_fn  —  Input pin. Deserialise the raw HTTP request.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def input_fn(request_body: str | bytes, content_type: str) -> dict:
+    """
+    Converts the raw bytes from the HTTP POST body into a Python dict.
+
+    Accepted request formats:
+
+    Format A — JSON with raw email text (most common):
+        {
+            "subject": "Your account was hacked",
+            "body":    "We detected unauthorized access..."
+        }
+
+    Format B — JSON with pre-extracted features (faster, skips NLP):
+        {
+            "keywords": ["hacked", "password"],
+            "sentiment": "negative",
+            "context":   "security"
+        }
+
+    Format C — Add ground_truth to either format above for accuracy scoring:
+        {
+            "subject": "...",
+            "body":    "...",
+            "ground_truth": {"urgency": 2, "routing": 1, "resolution": 2}
+        }
+    """
+    logger.info("input_fn | content_type=%s", content_type)
+
+    ct = content_type.lower().split(";")[0].strip()
+
+    if ct == "application/json":
+        if isinstance(request_body, bytes):
+            request_body = request_body.decode("utf-8")
+        payload = json.loads(request_body)
+
+    elif ct == "text/plain":
+        # Accept raw email text directly — treat entire body as email body
+        text    = request_body.decode("utf-8") if isinstance(request_body, bytes) else request_body
+        payload = {"subject": "", "body": text}
+
+    else:
+        raise ValueError(
+            f"Unsupported content type: '{content_type}'. "
+            "Send 'application/json' or 'text/plain'."
+        )
+
+    # Must have at least something to classify
+    if not any([payload.get("subject"), payload.get("body"),
+                payload.get("keywords"), payload.get("context")]):
+        raise ValueError(
+            "Request must include 'subject', 'body', 'keywords', or 'context'."
+        )
+
+    return payload
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [3] predict_fn  —  Logic gate. Run the classifier.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def predict_fn(data: dict, model: dict) -> dict:
+    """
+    The main classification step. Runs on every request.
+
+    Step 1: Extract features from raw text  (or use pre-supplied features)
+    Step 2: Classify → 3 integer codes      (urgency, routing, resolution)
+    Step 3: Decode codes → human labels     ("Security Breach", "Escalate", ...)
+    Step 4: Score against ground_truth      (only if ground_truth is in request)
+    Step 5: Return everything as a dict     (output_fn will format it as JSON)
+    """
+    logger.info("predict_fn | keys=%s", list(data.keys()))
+
+    # ── Step 1: Feature extraction ────────────────────────────────────────────
+    # Fast path: caller already extracted features
+    if data.get("context"):
+        features = {
+            "keywords":  data.get("keywords", []),
+            "sentiment": data.get("sentiment", "neutral"),
+            "context":   data["context"],
+        }
+    # NLP path: extract from raw subject + body text
+    else:
+        features = extract_features(
+            subject=data.get("subject", ""),
+            body=data.get("body", ""),
+        )
+
+    # ── Step 2: Classify → 3 codes ────────────────────────────────────────────
+    urgency, routing, resolution = classify(features)
+
+    # ── Step 3: Decode to human-readable labels ───────────────────────────────
+    labels = decode(urgency, routing, resolution)
+
+    logger.info(
+        "CLASSIFIED | category=%s dept=%s action=%s | context=%s keywords=%s",
+        labels["urgency"], labels["routing"], labels["resolution"],
+        features["context"], features["keywords"],
+    )
+
+    # ── Step 4: Score against ground_truth (optional) ─────────────────────────
+    ground_truth = data.get("ground_truth")
+    if ground_truth:
+        match = _score_match((urgency, routing, resolution), ground_truth)
+    else:
+        # No ground_truth supplied — this is a live production request
+        match = {"status": "UNVERIFIED", "reward": None,
+                 "correct_dims": {}, "wrong_fields": []}
+
+    # ── Step 5: Return raw prediction dict ────────────────────────────────────
+    return {
+        "urgency_code":    urgency,
+        "routing_code":    routing,
+        "resolution_code": resolution,
+        "labels":          labels,
+        "features":        features,
+        "match":           match,
+        "sla":             model["sla"][urgency],
+        "endpoint":        model["endpoint_name"],
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [4] output_fn  —  Output pin. Format and send the response.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def output_fn(prediction: dict, accept: str) -> tuple[str, str]:
+    """
+    Converts the prediction dict into the final HTTP response body.
+
+    Default response format: application/json
+    Optional CSV format:     text/csv  (useful for batch jobs writing to S3)
+
+    JSON response shape:
+    {
+        "request_id":   "uuid",
+        "timestamp":    "2024-01-15T10:30:00Z",
+
+        "triage": {
+            "category":   "Security Breach",   ← urgency label
+            "department": "Tech Support",       ← routing label
+            "action":     "Escalate"            ← resolution label
+        },
+
+        "codes": {
+            "urgency": 2, "routing": 1, "resolution": 2
+        },
+
+        "match_result": {
+            "status":  "EXACT",     ← or PARTIAL_1 / PARTIAL_2 / SECURITY_MISS / WRONG
+            "reward":  1.0,         ← RL reward score
+            "wrong_fields": []      ← which dimensions were wrong
+        },
+
+        "sla": {
+            "priority": "P1",
+            "respond_within_minutes": 15
+        }
+    }
+    """
+    accept_type = (accept or "application/json").lower().split(";")[0].strip()
+
+    response = {
+        "request_id": str(uuid.uuid4()),
+        "timestamp":  datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "triage": {
+            "category":   prediction["labels"]["urgency"],
+            "department": prediction["labels"]["routing"],
+            "action":     prediction["labels"]["resolution"],
+        },
+        "codes": {
+            "urgency":    prediction["urgency_code"],
+            "routing":    prediction["routing_code"],
+            "resolution": prediction["resolution_code"],
+        },
+        "features": {
+            "keywords":  prediction["features"]["keywords"],
+            "sentiment": prediction["features"]["sentiment"],
+            "context":   prediction["features"]["context"],
+        },
+        "match_result": {
+            "status":       prediction["match"]["status"],
+            "reward":       prediction["match"]["reward"],
+            "wrong_fields": prediction["match"]["wrong_fields"],
+        },
+        "sla": prediction["sla"],
+    }
+
+    # ── CSV output (for SageMaker Batch Transform jobs) ───────────────────────
+    if accept_type == "text/csv":
+        row = ",".join([
+            response["request_id"],
+            response["triage"]["category"],
+            response["triage"]["department"],
+            response["triage"]["action"],
+            str(response["codes"]["urgency"]),
+            str(response["codes"]["routing"]),
+            str(response["codes"]["resolution"]),
+            str(response["match_result"]["status"]),
+            str(response["match_result"]["reward"] or ""),
+            response["sla"]["priority"],
+        ])
+        return row, "text/csv"
+
+    return json.dumps(response, ensure_ascii=False), "application/json"

sagemaker/model.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1b5f5f36441ff75a3014c21ff9e85dcbada8f33fc888d8458459ae3b5cc1fdc
+size 6319

sagemaker/package.py

@@ -0,0 +1,71 @@
+"""
+package.py  —  Build model.tar.gz for SageMaker
+================================================
+Run this script once before deploying.
+It bundles your code/ folder into the exact archive structure SageMaker expects.
+
+Usage:
+    cd "RL Envir"
+    python sagemaker/package.py
+
+Output:
+    sagemaker/model.tar.gz   ← upload this to S3, then point SageMaker at it
+
+What goes inside model.tar.gz:
+    code/
+    ├── inference.py     ← SageMaker entry point  (the 4 handlers)
+    └── classifier.py    ← your rule-based classifier logic
+
+SageMaker unpacks the archive and looks for code/inference.py automatically
+when you use the SKLearn or generic Python containers.
+"""
+
+import os
+import tarfile
+
+# ── Paths — all relative to this script's location ───────────────────────────
+HERE        = os.path.dirname(os.path.abspath(__file__))
+OUTPUT_TAR  = os.path.join(HERE, "model.tar.gz")
+
+# Files to include — add more here if you create extra helper modules
+FILES_TO_PACK = {
+    "code/inference.py":  os.path.join(HERE, "inference.py"),
+    "code/classifier.py": os.path.join(HERE, "classifier.py"),
+}
+
+
+def build():
+    print("\n  Building model.tar.gz ...")
+    print(f"  Output → {OUTPUT_TAR}\n")
+
+    # Verify all source files exist before starting
+    missing = [src for src in FILES_TO_PACK.values() if not os.path.exists(src)]
+    if missing:
+        print("  ❌ Missing files:")
+        for f in missing:
+            print(f"       {f}")
+        raise FileNotFoundError("Fix missing files then re-run.")
+
+    # Build the archive
+    with tarfile.open(OUTPUT_TAR, "w:gz") as tar:
+        for archive_name, source_path in FILES_TO_PACK.items():
+            tar.add(source_path, arcname=archive_name)
+            size_kb = os.path.getsize(source_path) / 1024
+            print(f"  + {archive_name:<30}  ({size_kb:.1f} KB)")
+
+    # Verify and report
+    tar_size_kb = os.path.getsize(OUTPUT_TAR) / 1024
+    print(f"\n  ✅ Done!  model.tar.gz = {tar_size_kb:.1f} KB")
+
+    # Show contents as confirmation
+    print("\n  Contents of model.tar.gz:")
+    with tarfile.open(OUTPUT_TAR, "r:gz") as tar:
+        for member in tar.getmembers():
+            print(f"     {member.name:<35}  {member.size / 1024:.1f} KB")
+
+    print(f"\n  Next step — upload to S3:")
+    print(f"  aws s3 cp {OUTPUT_TAR} s3://YOUR-BUCKET/email-gatekeeper/model.tar.gz\n")
+
+
+if __name__ == "__main__":
+    build()

sagemaker/requirements.txt

@@ -0,0 +1,10 @@
+# SageMaker inference container dependencies
+# The SKLearn container already includes: boto3, numpy, scikit-learn
+# Only add packages your inference.py actually imports beyond stdlib
+
+# No additional packages needed for the rule-based classifier.
+# Uncomment below if you switch to an ML model later:
+
+# torch==2.1.0
+# transformers==4.35.0
+# huggingface_hub==0.19.0

sagemaker/upload_to_hf.py

@@ -0,0 +1,79 @@
+"""
+upload_to_hf.py  —  Upload model.tar.gz to Hugging Face
+=========================================================
+Handles large files (200MB+) using the huggingface_hub library,
+which automatically uses Git LFS for files over 10MB.
+
+Usage:
+    python sagemaker/upload_to_hf.py
+
+Prerequisites:
+    pip install huggingface_hub
+    huggingface-cli login        ← run once, saves token to ~/.cache/huggingface
+"""
+
+import os
+from huggingface_hub import HfApi, login
+
+# ── Configuration — edit these 3 lines ───────────────────────────────────────
+HF_REPO_ID  = "YOUR-USERNAME/YOUR-REPO-NAME"   # e.g. "zerogravity/email-gatekeeper"
+HF_TOKEN    = os.getenv("HF_TOKEN")            # set env var  OR  paste token below
+# HF_TOKEN  = "hf_xxxxxxxxxxxxxxxxxxxx"        # ← dev only, never commit this
+
+LOCAL_FILE  = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)),
+    "model.tar.gz"
+)
+REPO_FILE   = "model.tar.gz"                   # path inside the HF repo
+REPO_TYPE   = "model"                          # "model" | "dataset" | "space"
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def upload():
+    # ── Validate local file exists ────────────────────────────────────────────
+    if not os.path.exists(LOCAL_FILE):
+        raise FileNotFoundError(
+            f"model.tar.gz not found at:\n  {LOCAL_FILE}\n"
+            "Run  python sagemaker/package.py  first to build it."
+        )
+
+    size_mb = os.path.getsize(LOCAL_FILE) / (1024 * 1024)
+    print(f"\n  File     : {LOCAL_FILE}")
+    print(f"  Size     : {size_mb:.1f} MB")
+    print(f"  Repo     : {HF_REPO_ID}")
+    print(f"  Dest     : {REPO_FILE}\n")
+
+    # ── Authenticate ──────────────────────────────────────────────────────────
+    if HF_TOKEN:
+        login(token=HF_TOKEN, add_to_git_credential=False)
+    else:
+        # Falls back to cached token from  huggingface-cli login
+        print("  No HF_TOKEN env var found — using cached login credentials.")
+
+    # ── Upload ────────────────────────────────────────────────────────────────
+    api = HfApi()
+
+    print("  Uploading... (large files use Git LFS automatically)\n")
+
+    url = api.upload_file(
+        path_or_fileobj=LOCAL_FILE,
+        path_in_repo=REPO_FILE,
+        repo_id=HF_REPO_ID,
+        repo_type=REPO_TYPE,
+        commit_message="Upload model.tar.gz — Email Gatekeeper RL Agent",
+    )
+
+    print(f"\n  ✅ Upload complete!")
+    print(f"  View : https://huggingface.co/{HF_REPO_ID}")
+    print(f"  File : {url}\n")
+
+    # ── Print the download URL for use in deploy.py ───────────────────────────
+    download_url = (
+        f"https://huggingface.co/{HF_REPO_ID}/resolve/main/{REPO_FILE}"
+    )
+    print(f"  Direct download URL (use in deploy.py):")
+    print(f"  {download_url}\n")
+
+
+if __name__ == "__main__":
+    upload()

test_cases_advanced.json

@@ -0,0 +1,377 @@
+[
+  {
+    "_comment": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "_section": "MEDIUM — Passive-Aggressive Legal Threats (polite tone, legal intent)",
+    "_comment_end": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  },
+  {
+    "id": "TC-M-01",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Polite refund ultimatum with implied legal action",
+    "raw_email": {
+      "subject": "Following Up on My Refund Request — Third Attempt",
+      "body": "Dear Support Team, I have now contacted you three times regarding my refund of $340. I have been patient, but I want to make it clear that I am aware of my consumer rights and have already spoken with a legal advisor about my options. I would strongly prefer to resolve this amicably before I am forced to take further steps. Please process my refund within 48 hours. Regards, A. Chen"
+    },
+    "keywords": ["refund", "legal", "angry", "threat"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Polite tone masks explicit legal advisor mention and ultimatum deadline",
+    "classifier_trap": "Reads like a billing complaint — 'refund' + 'legal advisor' pushes it to legal escalation",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "urgency=2 because legal advisor + threat combo; routing=Legal; resolution=Escalate"
+  },
+  {
+    "id": "TC-M-02",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Overdue invoice with attorney CC warning",
+    "raw_email": {
+      "subject": "Invoice #4821 — Final Notice Before Referral",
+      "body": "Hi, This is a courtesy reminder that Invoice #4821 for $1,200 remains overdue by 45 days. We have CC'd our attorney on this correspondence as a precautionary measure. We remain open to resolving this without formal proceedings, but require payment or a written payment plan by Friday. Thank you."
+    },
+    "keywords": ["invoice", "overdue", "attorney", "legal", "payment", "threat"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Framed as a 'courtesy reminder' — attorney CC buried mid-sentence",
+    "classifier_trap": "Surface keywords look like billing; 'attorney' CC elevates to legal",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "attorney keyword present → legal context wins over billing"
+  },
+  {
+    "id": "TC-M-03",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Disappointed customer implying regulatory complaint",
+    "raw_email": {
+      "subject": "Extremely Disappointed — Will Be Escalating This Matter",
+      "body": "To Whom It May Concern, I am writing to express my deep dissatisfaction with how my case has been handled. I have documented every interaction and intend to escalate this to the relevant regulatory authority if I do not receive a satisfactory response within 5 business days. I trust you understand the implications. Sincerely, M. Okafor"
+    },
+    "keywords": ["angry", "threat", "legal"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "No explicit 'lawsuit' word — uses 'regulatory authority' and 'implications' as proxies",
+    "classifier_trap": "Vague enough to be misclassified as general complaint; 'escalate' + 'legal' intent is clear",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "threat + legal context → (2,2,2)"
+  },
+  {
+    "id": "TC-M-04",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "SLA breach complaint with legal remedy language",
+    "raw_email": {
+      "subject": "SLA Violation — Formal Notice of Breach",
+      "body": "Dear Account Manager, As per our signed service agreement, your platform guarantees 99.9% uptime. Your service has been unavailable for 14 hours this month, constituting a material breach of contract. We are formally notifying you of this breach and reserving all legal remedies available to us under the agreement. Please respond within 2 business days. — Legal Dept, Nexus Corp"
+    },
+    "keywords": ["breach", "legal", "threat", "angry"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Uses contract/SLA language — sounds like a tech complaint but is a formal legal notice",
+    "classifier_trap": "Contains 'breach' which could trigger security; context is contractual/legal",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "breach + legal dept sender + formal notice → (2,2,2)"
+  },
+  {
+    "id": "TC-M-05",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Billing dispute with small claims court mention",
+    "raw_email": {
+      "subject": "Re: Disputed Charge — My Next Step",
+      "body": "Hello, I have disputed the $89 charge on my account twice now with no resolution. I want to be transparent: I have already filed the paperwork for small claims court as a precaution. I am still willing to resolve this directly if you can process my refund this week. Please treat this as urgent. — T. Vasquez"
+    },
+    "keywords": ["refund", "payment", "angry", "lawsuit", "urgent"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Framed as cooperative ('still willing to resolve') while small claims filing already done",
+    "classifier_trap": "Refund + payment looks like billing dispute; 'lawsuit' (small claims) escalates to legal",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "lawsuit keyword present → legal routing regardless of billing surface"
+  },
+  {
+    "id": "TC-M-06",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "GDPR deletion request with legal consequence warning",
+    "raw_email": {
+      "subject": "Data Deletion Request — GDPR Article 17",
+      "body": "Dear Data Controller, I am formally requesting erasure of all my personal data under GDPR Article 17 (Right to Erasure). Failure to comply within 30 days constitutes a violation subject to regulatory fines of up to 4% of annual turnover. I have retained legal counsel and will file a complaint with the supervisory authority if this is not actioned. Please confirm receipt."
+    },
+    "keywords": ["legal", "breach", "threat", "angry"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Sounds like a routine data request — legal counsel + regulatory fine threat is the real signal",
+    "classifier_trap": "Could be misrouted to tech support as a 'data/account request'; it is a legal compliance matter",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "legal counsel + regulatory threat → (2,2,2)"
+  },
+  {
+    "id": "TC-M-07",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Subscription cancellation with chargeback threat",
+    "raw_email": {
+      "subject": "Cancellation and Chargeback Notice",
+      "body": "Hi, I cancelled my subscription 3 weeks ago but was charged again this month. I have already contacted my bank to initiate a chargeback and have documented all correspondence. If this is not refunded within 24 hours, I will also be filing a complaint with the Consumer Financial Protection Bureau. I expect a prompt response."
+    },
+    "keywords": ["payment", "refund", "angry", "threat", "legal"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Chargeback + CFPB complaint = regulatory/legal action disguised as billing complaint",
+    "classifier_trap": "Payment + refund looks like billing; CFPB filing is a legal/regulatory escalation",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "regulatory body complaint + threat → legal routing"
+  },
+  {
+    "id": "TC-M-08",
+    "difficulty": "medium",
+    "category": "Passive-Aggressive Legal Threat",
+    "description": "Vendor threatening IP infringement claim",
+    "raw_email": {
+      "subject": "Unauthorized Use of Proprietary Content",
+      "body": "Dear Sir/Madam, It has come to our attention that content owned by our company is being used on your platform without a valid license. We have documented evidence of this unauthorized use. Our legal team has been instructed to pursue all available remedies, including injunctive relief and damages, unless we receive written confirmation of removal within 72 hours. — IP Counsel, Meridian Media"
+    },
+    "keywords": ["unauthorized", "legal", "attorney", "threat"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Formal legal letter tone — 'injunctive relief' and 'damages' are legal action signals",
+    "classifier_trap": "'Unauthorized' could trigger security breach path; this is IP legal, not account security",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "attorney + legal team + unauthorized use → (2,2,2)"
+  },
+  {
+    "_comment": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "_section": "HARD — Subtle Phishing Attempts (disguised as legitimate IT/billing/HR emails)",
+    "_comment_end": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  },
+  {
+    "id": "TC-H-01",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "IT password reset disguised as routine security audit",
+    "raw_email": {
+      "subject": "Mandatory Annual Security Audit — Action Required",
+      "body": "Dear Employee, As part of our annual security compliance audit, all staff are required to verify their account credentials by clicking the link below and re-entering their password. This process is mandatory and must be completed by EOD Friday. Failure to comply may result in temporary account suspension. IT Security Team."
+    },
+    "keywords": ["password", "unauthorized", "critical", "urgent", "threat"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Impersonates internal IT; 'mandatory audit' creates urgency; credential harvesting via fake link",
+    "classifier_trap": "Reads like a legitimate IT notice — urgency + password request is the phishing signal",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "password + unauthorized access attempt → (2,1,2); no legal keywords so Tech Support not Legal"
+  },
+  {
+    "id": "TC-H-02",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Fake invoice payment portal redirect",
+    "raw_email": {
+      "subject": "Your Invoice #9923 is Ready — Secure Payment Required",
+      "body": "Hello, Your invoice for services rendered is now available. To avoid a late payment fee, please log in to our secure payment portal using your existing credentials to review and pay. Note: your current session has expired and you will need to re-enter your password to access the portal. Click here: http://pay-invoices-secure.net/login"
+    },
+    "keywords": ["invoice", "payment", "password", "unauthorized", "urgent"],
+    "sentiment": "neutral",
+    "context": "security",
+    "deception_tactic": "Billing-themed phish — 'session expired' forces credential re-entry on a fake domain",
+    "classifier_trap": "Invoice + payment looks like billing; password re-entry request on external URL is the phishing signal",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "password harvesting attempt embedded in billing context → security wins"
+  },
+  {
+    "id": "TC-H-03",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "HR benefits enrollment with credential capture",
+    "raw_email": {
+      "subject": "Open Enrollment Closes Friday — Update Your Benefits Now",
+      "body": "Hi Team, The annual benefits open enrollment window closes this Friday. To update your selections, please log in to the HR portal at the link below. You will be asked to verify your identity by entering your employee ID and current password. This is a one-time verification step. Don't miss the deadline — benefits cannot be changed until next year."
+    },
+    "keywords": ["password", "urgent", "critical"],
+    "sentiment": "neutral",
+    "context": "security",
+    "deception_tactic": "HR impersonation with artificial deadline; password verification step is credential theft",
+    "classifier_trap": "Completely routine-sounding HR email; password verification request is the only red flag",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "password request + impersonation pattern → security breach classification"
+  },
+  {
+    "id": "TC-H-04",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Fake account suspension notice with login link",
+    "raw_email": {
+      "subject": "Your Account Has Been Temporarily Suspended",
+      "body": "We detected unusual activity on your account and have temporarily suspended access as a precaution. To restore your account, please verify your identity by logging in and confirming your password within 24 hours. If you do not take action, your account will be permanently closed. — Account Security Team"
+    },
+    "keywords": ["unauthorized", "password", "breach", "urgent", "threat"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Fear-based urgency — 'permanent closure' threat forces hasty credential submission",
+    "classifier_trap": "Looks like a legitimate security alert from the platform itself; it is an inbound phishing attempt",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "unauthorized + password + breach → (2,1,2); account-level attack pattern"
+  },
+  {
+    "id": "TC-H-05",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Vendor onboarding form requesting system credentials",
+    "raw_email": {
+      "subject": "New Vendor Onboarding — Integration Credentials Needed",
+      "body": "Dear IT Team, We are completing the integration setup for your new vendor account. To finalize the API connection, please reply with your system admin username and current password so we can configure access on our end. This is a standard step in our onboarding process. Please respond by tomorrow to avoid delays."
+    },
+    "keywords": ["password", "unauthorized", "urgent"],
+    "sentiment": "neutral",
+    "context": "security",
+    "deception_tactic": "Business email compromise (BEC) — requests credentials via reply, not a link, to bypass URL filters",
+    "classifier_trap": "No suspicious link — credential request via email reply is the attack vector",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "password request via email reply = credential phishing → (2,1,2)"
+  },
+  {
+    "id": "TC-H-06",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Fake security alert asking to 'confirm' recent login",
+    "raw_email": {
+      "subject": "New Sign-In Detected on Your Account",
+      "body": "We noticed a new sign-in to your account from an unrecognized device in Frankfurt, Germany. If this was you, no action is needed. If this was NOT you, please secure your account immediately by clicking below and resetting your password. Act within 1 hour to prevent unauthorized access."
+    },
+    "keywords": ["unauthorized", "password", "hacked", "breach", "urgent"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Classic 'was this you?' phish — creates panic about unauthorized access to harvest credentials",
+    "classifier_trap": "Indistinguishable from a real security alert; all security keywords present",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "unauthorized + hacked + password reset request → (2,1,2)"
+  },
+  {
+    "id": "TC-H-07",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Payroll system update requiring credential re-verification",
+    "raw_email": {
+      "subject": "Payroll System Migration — Re-verify Your Account",
+      "body": "Dear Staff, We are migrating to a new payroll platform this weekend. To ensure your salary payment is not interrupted, you must re-verify your account credentials before Thursday. Please use the link below to log in with your current username and password. Accounts not verified by the deadline will be temporarily suspended pending manual review. — Payroll Department"
+    },
+    "keywords": ["payment", "password", "urgent", "threat"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Salary interruption fear + deadline + credential request — high-pressure BEC pattern",
+    "classifier_trap": "'Payment' keyword could route to billing; payroll phishing is a security/credential threat",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "password + payment context is phishing not billing → security classification"
+  },
+  {
+    "id": "TC-H-08",
+    "difficulty": "hard",
+    "category": "Subtle Phishing",
+    "description": "Software license renewal with admin credential request",
+    "raw_email": {
+      "subject": "License Renewal — Admin Verification Required",
+      "body": "Your enterprise software license expires in 3 days. To process the renewal without service interruption, our licensing team requires your system administrator credentials to apply the new license key directly. Please reply with your admin username and password at your earliest convenience. — Enterprise Licensing Support"
+    },
+    "keywords": ["password", "critical", "urgent", "error"],
+    "sentiment": "neutral",
+    "context": "security",
+    "deception_tactic": "Legitimate-sounding vendor request; 'apply license key' justification for admin credential theft",
+    "classifier_trap": "Routine renewal framing hides the admin credential request in the body",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "admin password request = credential phishing → (2,1,2)"
+  },
+  {
+    "_comment": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "_section": "HARD — Combined: Phishing with Legal Threat Overlay (most dangerous category)",
+    "_comment_end": "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━��━━━━━━━━━━━━━"
+  },
+  {
+    "id": "TC-H-09",
+    "difficulty": "hard",
+    "category": "Phishing + Legal Threat",
+    "description": "Fake GDPR breach notification demanding immediate credential verification",
+    "raw_email": {
+      "subject": "URGENT: Data Breach Affecting Your Account — Legal Obligation to Act",
+      "body": "Dear Account Holder, We are legally obligated to inform you that your account data may have been exposed in a recent breach. Under GDPR Article 33, you must verify your identity within 72 hours to confirm your data has not been compromised. Please log in immediately using the secure link and re-enter your password to initiate the verification process. Failure to act may result in your account being flagged for regulatory review. — Data Protection Officer"
+    },
+    "keywords": ["breach", "hacked", "password", "legal", "threat", "urgent", "unauthorized"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Weaponizes GDPR compliance language to force credential submission; DPO impersonation",
+    "classifier_trap": "Legal + breach + password all present — legal keywords could misdirect to (2,2,2) but credential harvest = Tech Support response",
+    "correct_actions": [2, 1, 2],
+    "correct_label": "Security Breach | Tech Support | Escalate",
+    "reward_note": "breach+password+hacked = account-level security attack; legal language is the deception layer not the context"
+  },
+  {
+    "id": "TC-H-10",
+    "difficulty": "hard",
+    "category": "Phishing + Legal Threat",
+    "description": "Ransomware demand disguised as a software audit notice",
+    "raw_email": {
+      "subject": "Software Compliance Audit — Unlicensed Software Detected",
+      "body": "Dear IT Administrator, Our automated audit system has detected unlicensed software installations on your network. Under the Software Protection Act, continued use constitutes copyright infringement. To avoid legal proceedings and a fine of $50,000, you must click the link below to download our compliance verification tool and run it with administrator privileges within 24 hours. — BSA Compliance Division"
+    },
+    "keywords": ["hacked", "breach", "unauthorized", "lawsuit", "legal", "threat", "critical", "urgent"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "BSA impersonation + legal fine threat to trick admin into running malware with elevated privileges",
+    "classifier_trap": "Legal fine language could route to (2,2,2); but the attack vector is malware execution = security + legal",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "hacked+breach+lawsuit+legal = ransomware with legal overlay → (2,2,2)"
+  },
+  {
+    "id": "TC-H-11",
+    "difficulty": "hard",
+    "category": "Phishing + Legal Threat",
+    "description": "Extortion email threatening to publish stolen data",
+    "raw_email": {
+      "subject": "We Have Your Data — Read Carefully",
+      "body": "We have obtained a copy of your customer database through a vulnerability in your system. We are prepared to sell this data to your competitors or publish it publicly unless you transfer $15,000 in cryptocurrency within 48 hours. We have also retained an attorney to ensure our anonymity is protected. Do not contact law enforcement. This is your only warning."
+    },
+    "keywords": ["hacked", "breach", "unauthorized", "attorney", "threat", "critical", "urgent"],
+    "sentiment": "negative",
+    "context": "security",
+    "deception_tactic": "Classic extortion with attorney mention to add credibility and deter police contact",
+    "classifier_trap": "Attorney keyword present — but this is a security extortion event requiring both Tech + Legal response",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "hacked+breach+attorney+threat = ransomware/extortion → (2,2,2)"
+  },
+  {
+    "id": "TC-H-12",
+    "difficulty": "hard",
+    "category": "Phishing + Legal Threat",
+    "description": "Fake law firm letter claiming evidence of data misuse",
+    "raw_email": {
+      "subject": "Notice of Pending Legal Action — Hargrove & Associates",
+      "body": "Dear Sir/Madam, This firm represents a class of individuals whose personal data was allegedly misused by your organization. We have obtained forensic evidence of unauthorized data processing and intend to file suit unless we receive a response from your legal counsel within 10 business days. Please ensure this notice is forwarded to your Data Protection Officer and General Counsel immediately. — J. Hargrove, Esq."
+    },
+    "keywords": ["unauthorized", "breach", "attorney", "lawsuit", "legal", "threat"],
+    "sentiment": "negative",
+    "context": "legal",
+    "deception_tactic": "Convincing law firm letterhead format; 'forensic evidence' claim creates panic; may be fake to extract settlement",
+    "classifier_trap": "Looks identical to a real legal notice — all legal keywords present; requires Legal team verification",
+    "correct_actions": [2, 2, 2],
+    "correct_label": "Security Breach | Legal | Escalate",
+    "reward_note": "attorney+lawsuit+legal+breach = legal context confirmed → (2,2,2)"
+  }
+]