Deploy ChatGPT MCP Server

.env.example

@@ -0,0 +1,6 @@
+TAVILY_API_KEY=
+OPENAI_API_KEY=
+XAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=
+AI_MODEL="gpt-5/grok-4-1/claude-4-5"

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: rajatsandeepsen

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: 🐞 Bug Report
+description: Create a bug report to help us improve
+title: "bug: "
+labels: ["🐞❔ unconfirmed bug"]
+body:
+  - type: textarea
+    attributes:
+      label: Provide environment information
+      description: |
+        Run this command in your project root and paste the results in a code block:
+        ```bash
+        npx envinfo --system --binaries
+        ```
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of the bug, as well as what you expected to happen when encountering it.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Link to reproduction
+      description: Please provide a link to a reproduction of the bug. Issues without a reproduction repo may be ignored.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: To reproduce
+      description: Describe how to reproduce your bug. Steps, code snippets, reproduction repos etc.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Add any other information related to the bug here, screenshots if applicable.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+# This template is heavily inspired by the Next.js's template:
+# See here: https://github.com/vercel/next.js/blob/canary/.github/ISSUE_TEMPLATE/3.feature_request.yml
+
+name: 🛠 Feature Request
+description: Create a feature request for the core packages
+title: "feat: "
+labels: ["✨ enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a feature request. Please fill out this form as completely as possible.
+  - type: textarea
+    attributes:
+      label: Describe the feature you'd like to request
+      description: Please describe the feature as clear and concise as possible. Remember to add context as to why you believe this feature is needed.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like to see
+      description: Please describe the solution you would like to see. Adding example usage is a good way to provide context.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Add any other information related to the feature here. If your feature request is related to any issues or discussions, link them here.
+      

.github/renovate.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchPackagePatterns": ["^@decode/"],
+      "enabled": false
+    }
+  ],
+  "updateInternalDeps": true,
+  "rangeStrategy": "bump",
+  "automerge": true
+}

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main"]
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
+
+# You can leverage Vercel Remote Caching with Turbo to speed up your builds
+# @link https://turborepo.org/docs/core-concepts/remote-caching#remote-caching-on-vercel-builds
+env:
+  FORCE_COLOR: 3
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - name: Setup Biome
+        uses: biomejs/setup-biome@v2
+        with:
+          version: latest
+
+      - name: Copy env
+        shell: bash
+        run: cp .env.example .env
+
+      - name: Lint
+        run: pnpm lint
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./tooling/github/setup
+      
+      - name: Setup Biome
+        uses: biomejs/setup-biome@v2
+        with:
+          version: latest
+
+      - name: Format
+        run: pnpm format
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - name: Typecheck
+        run: turbo typecheck

.github/workflows/deploy-hf-space.yml

@@ -0,0 +1,38 @@
+name: Deploy to Hugging Face Spaces
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  HF_SPACE: MCP-1st-Birthday/eu-ai-act-compliance-agent
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          # Configure git
+          git config --global user.email "[email protected]"
+          git config --global user.name "GitHub Actions"
+          
+          # Copy Space files from apps/eu-ai-act-agent to root
+          cp apps/eu-ai-act-agent/README_HF.md ./README.md
+          cp apps/eu-ai-act-agent/Dockerfile ./Dockerfile
+          
+          # Add HF Space remote and push
+          git remote add hf https://user:${HF_TOKEN}@huggingface.co/spaces/${HF_SPACE} || true
+          git add -A
+          git commit -m "Deploy to HF Spaces" --allow-empty
+          git push hf main:main --force
+          
+          echo "✅ Deployed to https://huggingface.co/spaces/${HF_SPACE}"

.gitignore

@@ -0,0 +1,56 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+.pnp
+.pnp.js
+
+# testing
+coverage
+
+# next.js
+.next/
+out/
+next-env.d.ts
+
+# nitro
+.nitro/
+.output/
+
+# expo
+.expo/
+dist/
+expo-env.d.ts
+apps/expo/.gitignore
+
+# production
+build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+
+# turbo
+.turbo
+/.history
+
+# generated compliance documentation
+compliance-docs/
+/modal/__pycache__
+modal/__pycache__/gpt_oss_inference.cpython-313.pyc

.npmrc

@@ -0,0 +1,5 @@
+# Expo doesn't play nice with pnpm by default. 
+# The symbolic links of pnpm break the rules of Expo monorepos.
+# @link https://docs.expo.dev/guides/monorepos/#common-issues
+node-linker=hoisted
+strict-peer-dependencies=false

.nvmrc

@@ -0,0 +1 @@
+18.18.2

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "bradlc.vscode-tailwindcss",
+    "expo.vscode-expo-tools",
+    "yoavbls.pretty-ts-errors",
+    "biomejs.biome"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Next.js",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "pnpm dev",
+      "cwd": "${workspaceFolder}/apps/web/",
+      "skipFiles": [
+        "<node_internals>/**"
+      ]
+    }
+  ]
+}

.vscode/project.code-workspace

@@ -0,0 +1,36 @@
+{
+    "folders": [
+        {
+            "path": "..",
+            "name": "root"
+        },
+        {
+            "name": "native",
+            "path": "../apps/native/"
+        },
+        {
+            "name": "web",
+            "path": "../apps/web/"
+        },
+        {
+            "name": "auth-proxy",
+            "path": "../apps/auth-proxy/"
+        },
+        {
+            "name": "api",
+            "path": "../packages/api/"
+        },
+        {
+            "name": "db",
+            "path": "../packages/db/"
+        },
+        {
+            "name": "auth",
+            "path": "../packages/auth/"
+        },
+        {
+            "name": "tooling",
+            "path": "../tooling/"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "eslint.workingDirectories": [
+    {
+      "mode": "auto"
+    }
+  ]
+}

DEPLOYMENT.md

@@ -0,0 +1,335 @@
+# 🚀 Deployment Guide
+
+This guide covers deploying the EU AI Act Compliance Suite for the MCP 1st Birthday Hackathon.
+
+## 📋 Table of Contents
+
+- [Deployment Options](#deployment-options)
+- [Hugging Face Spaces (Recommended)](#hugging-face-spaces-recommended)
+- [Manual Deployment](#manual-deployment)
+- [GitHub Actions CI/CD](#github-actions-cicd)
+- [Environment Variables](#environment-variables)
+- [Hackathon Submission Checklist](#hackathon-submission-checklist)
+
+---
+
+## 🎯 Deployment Options
+
+| Option | Best For | Difficulty |
+|--------|----------|------------|
+| **Hugging Face Spaces** | Hackathon submission, public demos | ⭐ Easy |
+| **Docker** | Self-hosted, production | ⭐⭐ Medium |
+| **Local Development** | Testing, development | ⭐ Easy |
+
+---
+
+## 🤗 Hugging Face Spaces (Recommended)
+
+The easiest way to deploy for the hackathon is using **Hugging Face Spaces**.
+
+### Method 1: Automated Deployment (GitHub Actions)
+
+1. **Fork this repository** to your GitHub account
+
+2. **Add GitHub Secrets:**
+   - Go to your repo → Settings → Secrets and variables → Actions
+   - Add `HF_TOKEN`: Your Hugging Face token with write access
+   
+   ```bash
+   # Get your HF token from: https://huggingface.co/settings/tokens
+   # Required scopes: write access to spaces
+   ```
+
+3. **Join the Hackathon Organization:**
+   - Go to [MCP-1st-Birthday](https://huggingface.co/MCP-1st-Birthday)
+   - Click "Request to join this org"
+   - Wait for approval
+
+4. **Trigger Deployment:**
+   - Push to `main` branch (auto-deploys on changes to `spaces/` directory)
+   - Or manually trigger via GitHub Actions → "Deploy to Hugging Face Spaces" → "Run workflow"
+
+5. **Configure Space Secrets:**
+   - Go to your Space settings: `https://huggingface.co/spaces/MCP-1st-Birthday/eu-ai-act-compliance/settings`
+   - Add secrets:
+     - `XAI_API_KEY` (required) - Get from [x.ai](https://x.ai/)
+     - `TAVILY_API_KEY` (optional) - Get from [tavily.com](https://app.tavily.com/)
+
+### Method 2: Manual Upload
+
+1. **Create a new Space:**
+   ```bash
+   # Install huggingface_hub
+   pip install huggingface_hub
+   
+   # Login
+   huggingface-cli login
+   
+   # Create space
+   huggingface-cli repo create eu-ai-act-compliance --type space --space-sdk gradio
+   ```
+
+2. **Upload files:**
+   ```bash
+   cd spaces/eu-ai-act-compliance
+   
+   # Clone the space
+   git clone https://huggingface.co/spaces/YOUR_USERNAME/eu-ai-act-compliance
+   
+   # Copy files
+   cp -r . eu-ai-act-compliance/
+   
+   # Push
+   cd eu-ai-act-compliance
+   git add .
+   git commit -m "Initial deployment"
+   git push
+   ```
+
+3. **Transfer to hackathon org** (for submission):
+   - Go to Space Settings → Transfer
+   - Transfer to `MCP-1st-Birthday` organization
+
+### Method 3: Using the Deploy Script
+
+```bash
+# Run the deployment script
+./scripts/deploy-hf.sh
+
+# With custom org/name
+./scripts/deploy-hf.sh --org MCP-1st-Birthday --name eu-ai-act-compliance
+```
+
+---
+
+## 🐳 Docker Deployment
+
+### Build and Run
+
+```bash
+# Build the image
+docker build -t eu-ai-act-compliance -f Dockerfile .
+
+# Run with environment variables
+docker run -p 7860:7860 \
+  -e XAI_API_KEY=your-key \
+  -e TAVILY_API_KEY=your-key \
+  eu-ai-act-compliance
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  eu-ai-act-agent:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - XAI_API_KEY=${XAI_API_KEY}
+      - TAVILY_API_KEY=${TAVILY_API_KEY}
+    restart: unless-stopped
+```
+
+---
+
+## 🔧 Manual Deployment
+
+### Prerequisites
+
+- Node.js 18+
+- Python 3.9+
+- pnpm 8+
+
+### Steps
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/your-org/eu-ai-act-compliance.git
+cd eu-ai-act-compliance
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Set up environment variables
+cp .env.example .env
+# Edit .env and add your API keys
+
+# 4. Build the MCP server
+pnpm --filter @eu-ai-act/mcp-server build
+
+# 5. Start the agent (API + Gradio)
+cd apps/eu-ai-act-agent
+./start.sh
+```
+
+### Production Mode
+
+```bash
+# Build everything
+pnpm build
+
+# Start in production
+cd apps/eu-ai-act-agent
+NODE_ENV=production node dist/server.js &
+python src/gradio_app.py
+```
+
+---
+
+## 🔄 GitHub Actions CI/CD
+
+### Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | Push/PR | Lint, typecheck, build |
+| `deploy-hf-space.yml` | Push to main + `spaces/` changes | Deploy to HF Spaces |
+
+### Required Secrets
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `HF_TOKEN` | Yes | Hugging Face token with write access |
+
+### Manual Deployment Trigger
+
+1. Go to Actions → "Deploy to Hugging Face Spaces"
+2. Click "Run workflow"
+3. Select branch and environment
+4. Click "Run workflow"
+
+---
+
+## 🔐 Environment Variables
+
+### Required
+
+| Variable | Description | Where to Get |
+|----------|-------------|--------------|
+| `XAI_API_KEY` | xAI API key for Grok model | [console.x.ai](https://console.x.ai/) |
+
+### Optional
+
+| Variable | Description | Where to Get |
+|----------|-------------|--------------|
+| `TAVILY_API_KEY` | Tavily API for web research | [app.tavily.com](https://app.tavily.com/) |
+| `PORT` | API server port (default: 3001) | - |
+
+### Setting Secrets in Hugging Face Spaces
+
+1. Go to your Space: `https://huggingface.co/spaces/ORG/SPACE_NAME`
+2. Click ⚙️ Settings
+3. Scroll to "Repository secrets"
+4. Add each secret:
+   - Name: `XAI_API_KEY`
+   - Value: Your API key
+   - Click "Add"
+
+---
+
+## ✅ Hackathon Submission Checklist
+
+### Before Submission (Nov 30, 2025 11:59 PM UTC)
+
+- [ ] **Join the organization**: [Request to join MCP-1st-Birthday](https://huggingface.co/MCP-1st-Birthday)
+- [ ] **Deploy your Space**: Make sure it's running and accessible
+- [ ] **Configure secrets**: Add `XAI_API_KEY` (and optionally `TAVILY_API_KEY`)
+- [ ] **Test the demo**: Verify all features work
+
+### README Requirements
+
+Your Space README must include:
+
+- [ ] **Hackathon tags** in frontmatter:
+  ```yaml
+  tags:
+    - mcp
+    - agents
+    - track-1-mcp-servers
+    - track-2-agentic-applications
+  ```
+
+- [ ] **Social media link**: Share your project and include the link
+  ```markdown
+  [🐦 Twitter Post](https://twitter.com/your-post-link)
+  ```
+
+### Track Tags
+
+| Track | Tags |
+|-------|------|
+| Track 1: Building MCP | `track-1-mcp-servers`, `mcp` |
+| Track 2: MCP in Action | `track-2-agentic-applications`, `agents` |
+
+### Social Media Post Template
+
+```
+🇪🇺 Excited to share my #MCPHackathon submission!
+
+EU AI Act Compliance Agent - AI-powered compliance assessment with MCP tools
+
+✅ Discover organization profiles
+✅ Classify AI systems by risk
+✅ Generate compliance documentation
+
+Try it: [HF Space Link]
+
+#MCP #AIAct #Gradio @huggingface
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Space Not Building
+
+1. Check `requirements.txt` for valid packages
+2. Verify Python version compatibility
+3. Check build logs in Space settings
+
+### API Key Errors
+
+1. Verify secrets are set in Space settings
+2. Check secret names match exactly (case-sensitive)
+3. Ensure API keys are valid and have required permissions
+
+### Deployment Failing
+
+1. Check GitHub Actions logs
+2. Verify `HF_TOKEN` has write access
+3. Ensure you're a member of the target organization
+
+### Space Sleeping
+
+Free HF Spaces sleep after inactivity. To wake:
+1. Visit the Space URL
+2. Wait for it to build/start
+3. Consider upgrading for persistent uptime
+
+---
+
+## 📞 Support
+
+- **Hackathon Discord**: [#agents-mcp-hackathon-winter25🏆](https://discord.gg/huggingface)
+- **GitHub Issues**: [Create an issue](https://github.com/your-org/eu-ai-act-compliance/issues)
+- **Email**: [email protected]
+
+---
+
+## 📚 Additional Resources
+
+- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Gradio Deployment Guide](https://www.gradio.app/guides/sharing-your-app)
+- [MCP Course](https://huggingface.co/learn/mcp-course)
+- [Hackathon Page](https://huggingface.co/MCP-1st-Birthday)
+
+---
+
+<div align="center">
+
+**Good luck with your submission! 🎂**
+
+</div>
+

Dockerfile

@@ -0,0 +1,57 @@
+# EU AI Act - ChatGPT MCP Server
+# Standalone MCP server for ChatGPT Apps integration
+# Deploys ONLY the MCP tools (discover_organization, discover_ai_services, assess_compliance)
+
+FROM node:20-slim
+
+# Install Python, pnpm, and uv
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-venv \
+    curl \
+    && npm install -g pnpm \
+    && curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh \
+    && rm -rf /var/lib/apt/lists/*
+
+# Use existing node user (UID 1000) for HF Spaces compatibility
+USER node
+ENV HOME=/home/node
+
+WORKDIR $HOME/app
+
+# Copy entire monorepo
+COPY --chown=node . .
+
+# Install Node dependencies
+RUN pnpm install --frozen-lockfile
+
+# Build MCP server and Agent (needed for API)
+RUN pnpm --filter @eu-ai-act/mcp-server build
+RUN pnpm --filter @eu-ai-act/agent build
+
+# Create Python venv and install dependencies
+RUN uv venv $HOME/venv && \
+    . $HOME/venv/bin/activate && \
+    uv pip install --no-cache -r apps/eu-ai-act-agent/requirements.txt
+
+# Environment
+ENV NODE_ENV=production \
+    PORT=3001 \
+    API_URL=http://localhost:3001 \
+    PUBLIC_URL=https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space \
+    CHATGPT_APP_SERVER_NAME=0.0.0.0 \
+    CHATGPT_APP_SERVER_PORT=7860 \
+    PATH=/home/node/venv/bin:$PATH \
+    VIRTUAL_ENV=/home/node/venv \
+    MCP_SERVER_PATH=/home/node/app/packages/eu-ai-act-mcp/dist/index.js
+
+WORKDIR $HOME/app/apps/eu-ai-act-agent
+
+EXPOSE 7860
+
+# Start API server + ChatGPT MCP App on port 7860
+# MCP URL will be: PUBLIC_URL/gradio_api/mcp/
+CMD node dist/server.js & \
+    sleep 2 && \
+    python src/chatgpt_app.py
+

README.md

@@ -0,0 +1,55 @@
+---
+title: EU AI Act - ChatGPT MCP Server by legitima.ai
+emoji: ⚖️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+tags:
+  - building-mcp-track-enterprise
+  - mcp-in-action-track-enterprise
+short_description: MCP Server for ChatGPT Apps - EU AI Act Compliance Tools
+---
+
+# 🇪🇺 EU AI Act - ChatGPT MCP Server by [legitima.ai](https://legitima.ai/mcp-hackathon) powered by [decode](https://decode.gr/en)
+
+<div align="center">
+  <img src="https://www.legitima.ai/mcp-hackathon.png" alt="Gradio MCP Hackathon - EU AI Act Compliance" width="800"/>
+</div>
+
+This is the **MCP Server** for integrating EU AI Act compliance tools with **ChatGPT Desktop**.
+
+## 🔗 MCP URL
+
+```
+https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/gradio_api/mcp/
+```
+
+## 📖 How to Use in ChatGPT
+
+1. **Enable Developer Mode** in ChatGPT: Settings → Apps & Connectors → Advanced settings
+2. **Create a Connector** with the MCP URL above (choose "No authentication")
+3. **Chat with ChatGPT** using `@eu-ai-act` to access the tools
+
+## 🔧 Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `discover_organization` | Research and profile an organization for compliance |
+| `discover_ai_services` | Discover and classify AI systems by risk level |
+| `assess_compliance` | Generate compliance assessment and documentation |
+
+## 🤖 Main Agent UI
+
+For the full interactive chat experience, visit:
+**[EU AI Act Compliance Agent](https://huggingface.co/spaces/MCP-1st-Birthday/eu-ai-act-compliance-agent)**
+
+---
+
+Built for the **MCP 1st Birthday Hackathon** 🎂
+
+**🔗 Demo & Showcase:** [www.legitima.ai/mcp-hackathon](https://www.legitima.ai/mcp-hackathon)
+**📹 Video:** [Guiddes](https://app.guidde.com/share/playlists/2wXbDrSm2YY7YnWMJbftuu?origin=wywDANMIvNhPu9kYVOXCPpdFcya2)
+**📱 Social Media:** [LinkedIn Post 1](https://www.linkedin.com/posts/iordanis-sarafidis_mcp-1st-birthday-mcp-1st-birthday-activity-7400132272282144768-ZIir?utm_source=share&utm_medium=member_desktop&rcm=ACoAAB0ARLABGvUO6Q--hJP0cDG7h0LZT0-roLs)
+
+[LinkedIn Post 2](https://www.linkedin.com/posts/billdrosatos_mcp-1st-birthday-mcp-1st-birthday-activity-7400135422502252544-C5BS?utm_source=share&utm_medium=member_desktop&rcm=ACoAAB0ARLABGvUO6Q--hJP0cDG7h0LZT0-roLs)

RUN_LOCAL.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# EU AI Act MCP Server - Local Testing Script
+# This script builds and tests the MCP server
+
+set -e
+
+echo "🚀 EU AI Act MCP Server - Local Testing"
+echo "========================================"
+echo ""
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if we're in the right directory
+if [ ! -f "package.json" ]; then
+    echo "❌ Error: Please run this script from the project root directory"
+    exit 1
+fi
+
+# Step 1: Install dependencies
+echo -e "${BLUE}Step 1: Installing dependencies...${NC}"
+pnpm install --filter @eu-ai-act/mcp-server --filter @eu-ai-act/test-agent
+echo -e "${GREEN}✅ Dependencies installed${NC}"
+echo ""
+
+# Step 2: Build MCP server
+echo -e "${BLUE}Step 2: Building MCP server...${NC}"
+pnpm --filter @eu-ai-act/mcp-server build
+echo -e "${GREEN}✅ MCP server built successfully${NC}"
+echo ""
+
+# Step 3: Run tests
+echo -e "${BLUE}Step 3: Running test agent...${NC}"
+echo ""
+pnpm --filter @eu-ai-act/test-agent dev
+echo ""
+
+# Success message
+echo ""
+echo -e "${GREEN}========================================"
+echo "✅ All tests completed successfully!"
+echo "========================================${NC}"
+echo ""
+echo -e "${YELLOW}Next Steps:${NC}"
+echo "1. Configure Claude Desktop (see QUICKSTART.md)"
+echo "2. Read packages/eu-ai-act-mcp/README.md for API docs"
+echo "3. See IMPLEMENTATION.md for architecture details"
+echo ""
+echo "Your MCP server is ready to use! 🎉"
+

SUBMISSION.md

@@ -0,0 +1,120 @@
+# 🎂 MCP 1st Birthday Hackathon Submission
+
+## EU AI Act Compliance Agent
+
+### 🔗 Links
+
+| Resource        | URL                                                                             |
+| --------------- | ------------------------------------------------------------------------------- |
+| **Live Demo**   | [HF Space](https://huggingface.co/spaces/MCP-1st-Birthday/eu-ai-act-compliance) |
+| **GitHub**      | [Repository](https://github.com/your-org/eu-ai-act-compliance)                  |
+| **Social Post** | [Twitter/X Post](#)                                                             |
+
+---
+
+## 📋 Submission Details
+
+### Tracks
+
+- ✅ **Track 1: Building MCP** - MCP Server with compliance tools
+- ✅ **Track 2: MCP in Action** - Agentic application with Gradio UI
+
+### Tags
+
+```
+mcp, agents, eu-ai-act, compliance, legal-tech, gradio, 
+track-1-mcp-servers, track-2-agentic-applications
+```
+
+---
+
+## 🎯 Project Overview
+
+The **EU AI Act Compliance Agent** helps organizations navigate the European Union's AI Act (Regulation 2024/1689) — the world's first comprehensive AI regulation framework.
+
+### The Problem
+
+- 📋 **Complex Classification** — AI systems must be classified by risk level
+- 📝 **Documentation** — Extensive technical documentation required
+- 🔍 **Transparency** — Clear disclosure obligations
+- ⏰ **Tight Deadlines** — Phased implementation starting 2025
+
+### Our Solution
+
+Three MCP tools + AI Agent for automated compliance:
+
+| Tool                    | Purpose                         |
+| ----------------------- | ------------------------------- |
+| `discover_organization` | Research & profile organization |
+| `discover_ai_services`  | Find & classify AI systems      |
+| `assess_compliance`     | Generate compliance assessment  |
+
+---
+
+## 🛠️ Tech Stack
+
+- **Gradio 6** — Interactive web UI
+- **xAI Grok** — AI reasoning and tool calling
+- **Tavily AI** — Web research
+- **Model Context Protocol** — Tool integration
+
+---
+
+## ✨ Key Features
+
+### Track 1: MCP Server
+
+1. **Organization Discovery** — Real-time web research using Tavily
+2. **AI System Classification** — Risk tiers per EU AI Act Annex III
+3. **Compliance Assessment** — Gap analysis with documentation templates
+
+### Track 2: AI Agent
+
+1. **Conversational Interface** — Natural language interaction
+2. **Tool Orchestration** — Intelligent multi-tool workflows
+3. **Document Generation** — Ready-to-use compliance templates
+4. **Real-time Streaming** — Progressive response display
+
+---
+
+## 📊 Demo Workflow
+
+```
+User: "Analyze OpenAI's EU AI Act compliance"
+
+Agent:
+├── 🔧 discover_organization("OpenAI")
+│   └── ✅ Found: AI company, Expert maturity, Provider role
+├── 🔧 discover_ai_services(orgContext)
+│   └── ✅ Found: 5 AI systems (2 high-risk, 3 limited-risk)
+├── 🔧 assess_compliance(orgContext, servicesContext)
+│   └── ✅ Score: 65/100, 3 critical gaps identified
+└── 📝 Generated compliance report with recommendations
+```
+
+---
+
+## 🏆 Why This Matters
+
+1. **Real Regulation** — EU AI Act is live, affecting millions of organizations
+2. **Practical Tools** — Automates tedious compliance workflows
+3. **Educational** — Helps understand complex legal requirements
+4. **Actionable** — Generates usable documentation templates
+
+---
+
+## 👥 Team
+
+**Team EU Compliance**
+
+Building the future of AI governance 🇪🇺
+
+****
+<div align="center">
+
+**Built with ❤️ for the MCP 1st Birthday Hackathon**
+
+🎂 Happy 1st Birthday, MCP! 🎂
+
+</div>
+

apps/eu-ai-act-agent/.gitignore

@@ -0,0 +1,52 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Misc
+.cache/
+temp/
+tmp/
+

apps/eu-ai-act-agent/.python-version

@@ -0,0 +1,2 @@
+3.10
+

apps/eu-ai-act-agent/API.md

@@ -0,0 +1,579 @@
+# 🔌 API Reference
+
+Complete reference for the EU AI Act Compliance Agent API.
+
+## Base URL
+
+```
+http://localhost:3001
+```
+
+## Authentication
+
+Currently no authentication required for local development. Add API key authentication for production deployment.
+
+---
+
+## Endpoints
+
+### 1. Health Check
+
+Check if the API server is running and healthy.
+
+**Endpoint**: `GET /health`
+
+**Response**:
+```json
+{
+  "status": "ok",
+  "service": "EU AI Act Compliance Agent",
+  "version": "0.1.0"
+}
+```
+
+**Example**:
+```bash
+curl http://localhost:3001/health
+```
+
+---
+
+### 2. Chat Endpoint
+
+Send a message to the AI agent and receive a streaming response.
+
+**Endpoint**: `POST /api/chat`
+
+**Content-Type**: `application/json`
+
+**Request Body**:
+```json
+{
+  "message": "What is the EU AI Act?",
+  "history": [
+    {
+      "role": "user",
+      "content": "Previous user message"
+    },
+    {
+      "role": "assistant",
+      "content": "Previous assistant response"
+    }
+  ]
+}
+```
+
+**Parameters**:
+- `message` (string, required): The user's input message
+- `history` (array, optional): Conversation history for context
+
+**Response Format**: Server-Sent Events (SSE) / Event Stream
+
+**Response Events**:
+
+1. **Text Chunk**:
+```json
+{
+  "type": "text",
+  "content": "The EU AI Act is..."
+}
+```
+
+2. **Tool Call** (when agent uses a tool):
+```json
+{
+  "type": "tool_call",
+  "tool": "discover_organization",
+  "args": {...}
+}
+```
+
+3. **Tool Result**:
+```json
+{
+  "type": "tool_result",
+  "tool": "discover_organization",
+  "result": {...}
+}
+```
+
+4. **Done**:
+```json
+{
+  "type": "done"
+}
+```
+
+5. **Error**:
+```json
+{
+  "type": "error",
+  "error": "Error message"
+}
+```
+
+**Example**:
+```bash
+curl -X POST http://localhost:3001/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "What is the EU AI Act?",
+    "history": []
+  }'
+```
+
+**JavaScript Example**:
+```javascript
+const response = await fetch('http://localhost:3001/api/chat', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    message: 'What is the EU AI Act?',
+    history: []
+  })
+});
+
+// Read the streaming response
+const reader = response.body.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  
+  const chunk = decoder.decode(value);
+  const lines = chunk.split('\n');
+  
+  for (const line of lines) {
+    if (line.startsWith('data: ')) {
+      const data = JSON.parse(line.substring(6));
+      console.log(data);
+    }
+  }
+}
+```
+
+**Python Example**:
+```python
+import requests
+import json
+
+response = requests.post(
+    'http://localhost:3001/api/chat',
+    json={
+        'message': 'What is the EU AI Act?',
+        'history': []
+    },
+    stream=True
+)
+
+for line in response.iter_lines():
+    if line:
+        line_str = line.decode('utf-8')
+        if line_str.startswith('data: '):
+            data = json.loads(line_str[6:])
+            print(data)
+```
+
+---
+
+### 3. Tools Endpoint
+
+Get a list of available MCP tools.
+
+**Endpoint**: `GET /api/tools`
+
+**Response**:
+```json
+{
+  "tools": [
+    {
+      "name": "discover_organization",
+      "description": "Discover and profile an organization for EU AI Act compliance..."
+    },
+    {
+      "name": "discover_ai_services",
+      "description": "Discover and classify AI systems within an organization..."
+    },
+    {
+      "name": "assess_compliance",
+      "description": "Assess EU AI Act compliance and generate documentation..."
+    }
+  ]
+}
+```
+
+**Example**:
+```bash
+curl http://localhost:3001/api/tools
+```
+
+---
+
+## Message Types
+
+### User Message
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string;
+}
+```
+
+### Assistant Message
+```typescript
+interface AssistantMessage {
+  role: "assistant";
+  content: string;
+}
+```
+
+### System Message (internal)
+```typescript
+interface SystemMessage {
+  role: "system";
+  content: string;
+}
+```
+
+---
+
+## Tool Schemas
+
+### discover_organization
+
+**Description**: Research and profile an organization for EU AI Act compliance.
+
+**Parameters**:
+```typescript
+{
+  organizationName: string;     // Required
+  domain?: string;              // Optional, auto-discovered
+  context?: string;             // Optional, additional context
+}
+```
+
+**Returns**:
+```typescript
+{
+  organization: {
+    name: string;
+    sector: string;
+    size: "SME" | "Large Enterprise" | "Public Body" | "Micro Enterprise";
+    aiMaturityLevel: "Nascent" | "Developing" | "Advanced" | "Expert";
+    // ... more fields
+  },
+  regulatoryContext: {
+    applicableFrameworks: string[];
+    complianceDeadlines: Array<{...}>;
+    // ... more fields
+  },
+  metadata: {
+    completenessScore: number;  // 0-100
+    // ... more fields
+  }
+}
+```
+
+### discover_ai_services
+
+**Description**: Discover and classify AI systems within an organization.
+
+**Parameters**:
+```typescript
+{
+  organizationContext?: any;    // Optional, from discover_organization
+  systemNames?: string[];       // Optional, specific systems to discover
+  scope?: string;               // Optional: 'all', 'high-risk-only', 'production-only'
+  context?: string;             // Optional, additional context
+}
+```
+
+**Returns**:
+```typescript
+{
+  systems: Array<{
+    system: {
+      name: string;
+      description: string;
+      status: "Development" | "Testing" | "Production" | "Deprecated";
+      // ... more fields
+    },
+    riskClassification: {
+      category: "Unacceptable" | "High" | "Limited" | "Minimal";
+      riskScore: number;  // 0-100
+      annexIIICategory?: string;
+      // ... more fields
+    },
+    complianceStatus: {
+      // ... compliance fields
+    }
+  }>,
+  riskSummary: {
+    highRiskCount: number;
+    limitedRiskCount: number;
+    // ... more counts
+  }
+}
+```
+
+### assess_compliance
+
+**Description**: Assess compliance and generate documentation.
+
+**Parameters**:
+```typescript
+{
+  organizationContext?: any;      // Optional, from discover_organization
+  aiServicesContext?: any;        // Optional, from discover_ai_services
+  focusAreas?: string[];          // Optional, specific areas to focus on
+  generateDocumentation?: boolean; // Optional, default: true
+}
+```
+
+**Returns**:
+```typescript
+{
+  assessment: {
+    overallScore: number;  // 0-100
+    gaps: Array<{
+      area: string;
+      severity: "Critical" | "High" | "Medium" | "Low";
+      article: string;
+      description: string;
+      recommendation: string;
+    }>,
+    recommendations: Array<{...}>
+  },
+  documentation?: {
+    riskManagementTemplate: string;  // Markdown
+    technicalDocumentation: string;   // Markdown
+    conformityAssessment: string;     // Markdown
+    transparencyNotice: string;       // Markdown
+    // ... more templates
+  },
+  reasoning: string;  // Chain-of-thought explanation
+}
+```
+
+---
+
+## Error Handling
+
+### Common Error Responses
+
+**400 Bad Request**:
+```json
+{
+  "error": "Message is required"
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "error": "Internal server error",
+  "message": "Detailed error message"
+}
+```
+
+### Error Types
+
+1. **Missing Parameters**: 400 error when required parameters are not provided
+2. **API Connection**: 500 error if OpenAI API is unreachable
+3. **Rate Limiting**: 429 error if rate limits are exceeded
+4. **Tool Execution**: 500 error if MCP tools fail
+
+---
+
+## Rate Limiting
+
+Currently no rate limiting implemented. For production, consider adding:
+
+```javascript
+import rateLimit from 'express-rate-limit';
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per windowMs
+});
+
+app.use('/api/', limiter);
+```
+
+---
+
+## CORS Configuration
+
+**Current Setup**:
+```javascript
+cors({
+  origin: ["http://localhost:7860", "http://127.0.0.1:7860"],
+  credentials: true,
+})
+```
+
+**For Production**: Configure specific allowed origins:
+```javascript
+cors({
+  origin: ["https://your-gradio-app.com"],
+  credentials: true,
+})
+```
+
+---
+
+## WebSocket Support
+
+Currently uses HTTP streaming (SSE). For WebSocket support, add:
+
+```javascript
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ server });
+
+wss.on('connection', (ws) => {
+  ws.on('message', async (message) => {
+    const { content, history } = JSON.parse(message);
+    // Stream response via WebSocket
+    for await (const chunk of result.textStream) {
+      ws.send(JSON.stringify({ type: 'text', content: chunk }));
+    }
+  });
+});
+```
+
+---
+
+## Environment Variables
+
+Required for API server:
+
+```bash
+# Required
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Optional
+TAVILY_API_KEY=tvly-your-tavily-api-key
+PORT=3001
+
+# For production
+NODE_ENV=production
+API_KEY=your-api-authentication-key
+ALLOWED_ORIGINS=https://your-app.com
+```
+
+---
+
+## Testing the API
+
+### Using curl
+
+**Health check**:
+```bash
+curl http://localhost:3001/health
+```
+
+**Simple chat**:
+```bash
+curl -X POST http://localhost:3001/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"What is the EU AI Act?"}'
+```
+
+**Chat with history**:
+```bash
+curl -X POST http://localhost:3001/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Tell me more",
+    "history": [
+      {"role": "user", "content": "What is the EU AI Act?"},
+      {"role": "assistant", "content": "The EU AI Act is..."}
+    ]
+  }'
+```
+
+### Using Postman
+
+1. Create a new POST request to `http://localhost:3001/api/chat`
+2. Set Headers: `Content-Type: application/json`
+3. Set Body (raw JSON):
+```json
+{
+  "message": "What is the EU AI Act?",
+  "history": []
+}
+```
+4. Send and view streaming response
+
+---
+
+## Monitoring and Logging
+
+**Console Logs**:
+- All requests are logged to console
+- Tool executions are logged
+- Errors are logged with stack traces
+
+**Add Structured Logging**:
+```javascript
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+
+app.use((req, res, next) => {
+  logger.info(`${req.method} ${req.url}`);
+  next();
+});
+```
+
+---
+
+## Security Best Practices
+
+1. **Add Authentication**: Use API keys or JWT tokens
+2. **Rate Limiting**: Prevent abuse
+3. **Input Validation**: Sanitize all inputs
+4. **HTTPS**: Use TLS in production
+5. **CORS**: Restrict origins
+6. **Secrets**: Never commit API keys
+7. **Monitoring**: Log all requests and errors
+
+---
+
+## Performance Optimization
+
+1. **Caching**: Cache organization/system discoveries
+```javascript
+import NodeCache from 'node-cache';
+const cache = new NodeCache({ stdTTL: 3600 });
+```
+
+2. **Compression**: Compress responses
+```javascript
+import compression from 'compression';
+app.use(compression());
+```
+
+3. **Load Balancing**: Use multiple instances
+4. **Queuing**: Implement job queue for long tasks
+
+---
+
+## Support
+
+- 📖 Full documentation: See README.md
+- 💬 Issues: GitHub Issues
+- 🐛 Bug reports: Include API logs and request details
+
+

apps/eu-ai-act-agent/ARCHITECTURE.md

@@ -0,0 +1,674 @@
+# 🏗️ Architecture Documentation
+
+Detailed technical architecture of the EU AI Act Compliance Agent.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CLIENT LAYER                           │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Gradio Web Interface (Python)                        │  │
+│  │  - Chat UI with history                               │  │
+│  │  - Real-time streaming display                        │  │
+│  │  - Document export features                           │  │
+│  │  - Status monitoring                                  │  │
+│  └────────────────────┬──────────────────────────────────┘  │
+└─────────────────────────┼──────────────────────────────────┘
+                          │ HTTP/REST (SSE)
+                          │
+┌─────────────────────────┼──────────────────────────────────┐
+│                   API LAYER                                 │
+│  ┌────────────────────┴──────────────────────────────────┐ │
+│  │  Express.js Server (Node.js/TypeScript)               │ │
+│  │  - RESTful endpoints                                  │ │
+│  │  - Server-Sent Events (SSE) for streaming             │ │
+│  │  - CORS configuration                                 │ │
+│  │  - Request validation                                 │ │
+│  └────────────────────┬──────────────────────────────────┘ │
+└─────────────────────────┼──────────────────────────────────┘
+                          │
+┌─────────────────────────┼──────────────────────────────────┐
+│                   AGENT LAYER                               │
+│  ┌────────────────────┴──────────────────────────────────┐ │
+│  │  Vercel AI SDK v5 Agent                               │ │
+│  │  ┌──────────────────────────────────────────────────┐ │ │
+│  │  │  Model: OpenAI gpt-5-chat-latest                            │ │ │
+│  │  │  - Natural language understanding                │ │ │
+│  │  │  - Context management (conversation history)     │ │ │
+│  │  │  - Tool calling orchestration                    │ │ │
+│  │  │  - Streaming response generation                 │ │ │
+│  │  └──────────────────────────────────────────────────┘ │ │
+│  │                                                         │ │
+│  │  ┌──────────────────────────────────────────────────┐ │ │
+│  │  │  System Prompt                                    │ │ │
+│  │  │  - EU AI Act expert persona                      │ │ │
+│  │  │  - Tool usage guidelines                         │ │ │
+│  │  │  - Response formatting rules                     │ │ │
+│  │  └──────────────────────────────────────────────────┘ │ │
+│  └────────────────────┬──────────────────────────────────┘ │
+└─────────────────────────┼──────────────────────────────────┘
+                          │ Function Calling
+                          │
+┌───────────────────────���─┼──────────────────────────────────┐
+│                   TOOL LAYER                                │
+│  ┌────────────────────┴──────────────────────────────────┐ │
+│  │  MCP Tool Adapters (Vercel AI SDK tool format)       │ │
+│  │                                                         │ │
+│  │  ┌─────────────────────────────────────────────────┐  │ │
+│  │  │  1. discover_organization                       │  │ │
+│  │  │     - Tavily web research                       │  │ │
+│  │  │     - Company profiling                         │  │ │
+│  │  │     - Regulatory mapping                        │  │ │
+│  │  └─────────────────────────────────────────────────┘  │ │
+│  │                                                         │ │
+│  │  ┌─────────────────────────────────────────────────┐  │ │
+│  │  │  2. discover_ai_services                        │  │ │
+│  │  │     - AI system discovery                       │  │ │
+│  │  │     - Risk classification                       │  │ │
+│  │  │     - Compliance status assessment              │  │ │
+│  │  └─────────────────────────────────────────────────┘  │ │
+│  │                                                         │ │
+│  │  ┌─────────────────────────────────────────────────┐  │ │
+│  │  │  3. assess_compliance                           │  │ │
+│  │  │     - Gap analysis (GPT-4)                      │  │ │
+│  │  │     - Documentation generation                  │  │ │
+│  │  │     - Recommendations                           │  │ │
+│  │  └─────────────────────────────────────────────────┘  │ │
+│  └────────────────────┬──────────────────────────────────┘ │
+└─────────────────────────┼──────────────────────────────────┘
+                          │
+┌─────────────────────────┼──────────────────────────────────┐
+│               EXTERNAL SERVICES                             │
+│  ┌────────────────────┴──────────────────────────────────┐ │
+│  │  OpenAI API (gpt-5-chat-latest)                                  │ │
+│  │  - Agent intelligence                                 │ │
+│  │  - Compliance assessment                              │ │
+│  └───────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │  Tavily API (Optional)                                │ │
+│  │  - Company research                                   │ │
+│  │  - Web data extraction                                │ │
+│  └───────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Component Details
+
+### 1. Gradio Web Interface
+
+**Technology**: Python 3.9+ with Gradio 5.x
+
+**Purpose**: Provide user-friendly chat interface for the agent
+
+**Key Files**:
+- `src/gradio_app.py` - Main Gradio application
+
+**Features**:
+- Chat interface with conversation history
+- Real-time streaming display
+- Status indicator for API connection
+- Example queries
+- Export functionality (planned)
+- Custom EU-themed styling
+
+**Communication**: HTTP POST requests to Express API with streaming response handling
+
+**Configuration**:
+```python
+demo.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    share=False,
+    show_error=True,
+)
+```
+
+---
+
+### 2. Express API Server
+
+**Technology**: Node.js 18+ with Express.js and TypeScript
+
+**Purpose**: REST API layer connecting Gradio to the AI agent
+
+**Key Files**:
+- `src/server.ts` - Express server configuration
+- `src/types/index.ts` - TypeScript type definitions
+
+**Endpoints**:
+- `GET /health` - Health check
+- `POST /api/chat` - Main chat endpoint (streaming)
+- `GET /api/tools` - List available tools
+
+**Features**:
+- CORS configuration for Gradio
+- Server-Sent Events (SSE) for streaming
+- Request validation
+- Error handling
+- Logging
+
+**Configuration**:
+```typescript
+const app = express();
+app.use(cors({
+  origin: ["http://localhost:7860", "http://127.0.0.1:7860"],
+  credentials: true,
+}));
+app.use(express.json());
+```
+
+---
+
+### 3. Vercel AI SDK v5 Agent
+
+**Technology**: Vercel AI SDK v5 with OpenAI provider
+
+**Purpose**: Intelligent agent that understands queries and orchestrates tools
+
+**Key Files**:
+- `src/agent/index.ts` - Agent factory and configuration
+- `src/agent/prompts.ts` - System prompt and instructions
+- `src/agent/tools.ts` - Tool adapters
+
+**Model**: OpenAI gpt-5-chat-latest
+- Context window: 128k tokens
+- Supports function calling
+- Streaming responses
+- Multi-step reasoning
+
+**Configuration**:
+```typescript
+const model = openai("gpt-5-chat-latest");
+
+streamText({
+  model,
+  messages: [...],
+  tools: {
+    discover_organization,
+    discover_ai_services,
+    assess_compliance,
+  },
+  maxSteps: 5, // Allow multi-step tool use
+})
+```
+
+**Capabilities**:
+- Natural language understanding
+- Intent recognition
+- Tool selection and orchestration
+- Context management
+- Response streaming
+- Error handling
+
+---
+
+### 4. MCP Tool Adapters
+
+**Technology**: Vercel AI SDK `tool()` wrapper + MCP tools
+
+**Purpose**: Bridge between Vercel AI SDK and MCP tools
+
+**Key File**: `src/agent/tools.ts`
+
+**Adapter Pattern**:
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+import { mcpToolFunction } from "../../eu-ai-act-mcp/src/tools/...";
+
+export const myTool = tool({
+  description: "...",
+  parameters: z.object({...}),
+  execute: async (params) => {
+    return await mcpToolFunction(params);
+  },
+});
+```
+
+**Three Tools**:
+1. `discover_organization` - Organization profiling
+2. `discover_ai_services` - AI system discovery
+3. `assess_compliance` - Compliance assessment
+
+---
+
+### 5. MCP Server (Shared)
+
+**Technology**: Model Context Protocol SDK
+
+**Purpose**: Reusable compliance tools
+
+**Location**: `packages/eu-ai-act-mcp/`
+
+**Integration**: Tools are imported directly by the agent adapters
+
+**Note**: No separate MCP server process needed for the agent. Tools are used as libraries.
+
+---
+
+## Data Flow
+
+### Basic Chat Flow
+
+```
+User Input (Gradio)
+    ↓
+POST /api/chat {message, history}
+    ↓
+Express Server validates request
+    ↓
+Agent.streamText({messages})
+    ↓
+gpt-5-chat-latest processes with system prompt
+    ↓
+Streaming response chunks
+    ↓
+SSE: data: {type: "text", content: "..."}
+    ↓
+Gradio displays in real-time
+```
+
+### Tool Calling Flow
+
+```
+User: "Analyze OpenAI's compliance"
+    ↓
+Agent recognizes need for tools
+    ↓
+Step 1: Call discover_organization("OpenAI")
+    ├─ Tavily API search
+    ├─ Data extraction
+    └─ Return organization profile
+    ↓
+Step 2: Call discover_ai_services(orgContext)
+    ├─ System classification
+    ├─ Risk assessment
+    └─ Return systems inventory
+    ↓
+Step 3: Call assess_compliance(org, systems)
+    ├─ GPT-4 analysis
+    ├─ Gap identification
+    └─ Return assessment + docs
+    ↓
+Agent synthesizes results
+    ↓
+Stream final response to user
+```
+
+---
+
+## Technology Stack Summary
+
+| Layer | Technology | Version | Purpose |
+|-------|-----------|---------|---------|
+| UI | Gradio | 5.9.1+ | Web interface |
+| API | Express.js | 4.21+ | REST server |
+| Language | TypeScript | 5.9+ | Type safety |
+| Agent | Vercel AI SDK | 5.0+ | AI orchestration |
+| Model | gpt-5-chat-latest | Latest | Intelligence |
+| Tools | MCP SDK | 1.23+ | Tool protocol |
+| Research | Tavily | 0.5+ | Web search |
+| Validation | Zod | 3.23+ | Schema validation |
+
+---
+
+## Configuration Management
+
+### Environment Variables
+
+**Workspace Root** `.env`:
+```bash
+OPENAI_API_KEY=sk-...
+TAVILY_API_KEY=tvly-...
+PORT=3001
+```
+
+**Loading**:
+```typescript
+import { config } from "dotenv";
+config({ path: resolve(__dirname, "../../.env") });
+```
+
+### Package Configuration
+
+**Monorepo Structure**:
+```
+packages/eu-ai-act-mcp/      # MCP tools
+apps/eu-ai-act-agent/        # Agent + UI
+  ├── src/
+  │   ├── server.ts          # Express server
+  │   ├── gradio_app.py      # Gradio UI
+  │   └── agent/
+  │       ├── index.ts       # Agent config
+  │       ├── tools.ts       # Tool adapters
+  │       └── prompts.ts     # System prompt
+  └── package.json
+```
+
+**Dependencies**:
+- Agent depends on MCP package
+- Imports tools directly (no RPC)
+- Shared TypeScript config
+
+---
+
+## Scaling Considerations
+
+### Horizontal Scaling
+
+**Current**: Single instance of Express + Gradio
+
+**For Production**:
+1. **Multiple API Instances**:
+   ```
+   Load Balancer
+       ├─ API Server 1
+       ├─ API Server 2
+       └─ API Server 3
+   ```
+
+2. **Session Management**:
+   - Use Redis for conversation history
+   - Sticky sessions at load balancer
+   - Stateless API design
+
+3. **Gradio Scaling**:
+   - Multiple Gradio instances
+   - Shared API endpoint
+   - CDN for static assets
+
+### Vertical Scaling
+
+- Increase Node.js worker threads
+- Use clustering module
+- Optimize Python workers
+
+### Caching Strategy
+
+```typescript
+import NodeCache from 'node-cache';
+
+const orgCache = new NodeCache({ stdTTL: 3600 });
+const systemCache = new NodeCache({ stdTTL: 1800 });
+
+// Cache organization discoveries
+if (orgCache.has(orgName)) {
+  return orgCache.get(orgName);
+}
+```
+
+---
+
+## Security Architecture
+
+### Current State (Development)
+
+- No authentication
+- Open CORS for localhost
+- Environment variables for API keys
+- No encryption at rest
+
+### Production Requirements
+
+1. **Authentication**:
+```typescript
+import jwt from 'jsonwebtoken';
+
+app.use('/api/', (req, res, next) => {
+  const token = req.headers.authorization;
+  jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
+    if (err) return res.status(401).send('Unauthorized');
+    req.user = decoded;
+    next();
+  });
+});
+```
+
+2. **Rate Limiting**:
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100
+});
+app.use('/api/', limiter);
+```
+
+3. **Input Validation**:
+```typescript
+import { z } from 'zod';
+
+const ChatRequestSchema = z.object({
+  message: z.string().min(1).max(5000),
+  history: z.array(z.object({
+    role: z.enum(['user', 'assistant']),
+    content: z.string()
+  })).max(50)
+});
+```
+
+4. **HTTPS Only**:
+```typescript
+if (process.env.NODE_ENV === 'production' && !req.secure) {
+  return res.redirect('https://' + req.headers.host + req.url);
+}
+```
+
+---
+
+## Monitoring & Observability
+
+### Logging
+
+**Current**: Console logs
+
+**Recommended**:
+```typescript
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+```
+
+### Metrics
+
+Track:
+- Request rate
+- Response time
+- Tool execution time
+- Error rate
+- OpenAI API usage
+
+### Alerting
+
+Monitor:
+- API downtime
+- High error rates
+- OpenAI rate limits
+- Disk space (logs)
+
+---
+
+## Development Workflow
+
+### Local Development
+
+```bash
+# Terminal 1: Watch mode for API
+pnpm dev
+
+# Terminal 2: Python app
+python3 src/gradio_app.py
+
+# Terminal 3: Watch MCP changes
+pnpm --filter @eu-ai-act/mcp-server dev
+```
+
+### Testing
+
+```bash
+# Unit tests (future)
+pnpm test
+
+# Integration tests (future)
+pnpm test:integration
+
+# Manual testing
+curl http://localhost:3001/health
+```
+
+### Building
+
+```bash
+# Build MCP server
+pnpm --filter @eu-ai-act/mcp-server build
+
+# Build agent
+pnpm --filter @eu-ai-act/agent build
+
+# Build all
+pnpm build
+```
+
+---
+
+## Deployment Architecture
+
+### Recommended: Vercel + Hugging Face
+
+```
+[Vercel]                    [Hugging Face Spaces]
+  ↓                              ↓
+Express API (Node.js)      Gradio UI (Python)
+  ↓                              ↓
+gpt-5-chat-latest + MCP Tools              ↓
+  ↑                              ↓
+  ←──────── HTTP/SSE ───────────┘
+```
+
+**Benefits**:
+- Vercel: Serverless scaling, CDN, automatic HTTPS
+- HF Spaces: Free Gradio hosting, GPU access (if needed)
+- Separation of concerns
+
+### Alternative: Single Server
+
+```
+[VPS / Cloud VM]
+  ├─ Nginx (reverse proxy)
+  ├─ Express API :3001
+  ├─ Gradio UI :7860
+  └─ PM2 (process manager)
+```
+
+**Benefits**:
+- Simpler deployment
+- Lower latency (same server)
+- Full control
+
+---
+
+## Performance Optimization
+
+### Response Time
+
+- **Current**: ~2-5 seconds for simple queries
+- **With Tools**: ~10-30 seconds (Tavily + GPT-4 analysis)
+- **Optimization**:
+  - Cache Tavily results (24h TTL)
+  - Parallel tool execution where possible
+  - Stream responses immediately
+
+### Cost Optimization
+
+- Use gpt-5-chat-latest-mini for simple queries (future)
+- Cache frequently requested data
+- Batch processing where applicable
+- Monitor token usage
+
+---
+
+## Future Enhancements
+
+1. **WebSocket Support**: Replace SSE with WebSockets
+2. **Multi-tenancy**: Support multiple organizations
+3. **Persistent Storage**: Database for assessments
+4. **Advanced Analytics**: Compliance dashboards
+5. **Document Export**: PDF/DOCX generation
+6. **Email Reports**: Scheduled compliance reports
+7. **API Management**: Rate limiting, quotas, billing
+8. **Advanced Caching**: Redis cluster
+9. **Internationalization**: Multi-language support
+10. **Mobile App**: React Native companion app
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Agent not responding**:
+   - Check OPENAI_API_KEY
+   - Verify API server is running
+   - Check console for errors
+
+2. **Tool calls failing**:
+   - Ensure MCP server is built
+   - Check tool imports in tools.ts
+   - Verify environment variables
+
+3. **Gradio connection issues**:
+   - Verify API_URL in gradio_app.py
+   - Check CORS configuration
+   - Ensure port 3001 is open
+
+---
+
+## Architecture Decisions (ADRs)
+
+### Why Vercel AI SDK v5?
+
+- Native streaming support
+- Tool calling abstraction
+- TypeScript-first
+- Active development
+- Good documentation
+
+### Why Gradio?
+
+- Rapid prototyping
+- Built-in chat UI
+- Python ecosystem
+- Easy deployment (HF Spaces)
+- No frontend expertise needed
+
+### Why Express?
+
+- Lightweight
+- TypeScript support
+- Large ecosystem
+- Easy to understand
+- Flexible
+
+### Why Direct Tool Import?
+
+- Simpler architecture
+- No RPC overhead
+- Shared code between MCP server and agent
+- Easier debugging
+
+---
+
+**Questions?** See [README.md](README.md) or [API.md](API.md)
+

apps/eu-ai-act-agent/DEPLOYMENT.md

@@ -0,0 +1,302 @@
+# 🚀 Deployment Guide
+
+## Prerequisites
+
+### System Requirements
+- **Node.js** 18+ and pnpm 8+
+- **Python** 3.9+ with uv (fast package manager)
+- **Git** for cloning the repository
+
+### API Keys
+1. **OpenAI API Key** (required)
+   - Sign up at https://platform.openai.com/
+   - Create an API key
+   - Set as `OPENAI_API_KEY` environment variable
+
+2. **Tavily API Key** (optional, recommended)
+   - Sign up at https://app.tavily.com
+   - Get 1,000 free credits/month
+   - Set as `TAVILY_API_KEY` environment variable
+
+## Local Development
+
+### 1. Clone and Install
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd mcp-1st-birthday-ai-act
+
+# Install uv (fast Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install Node.js dependencies (from workspace root)
+pnpm install
+
+# Install Python dependencies
+cd apps/eu-ai-act-agent
+uv pip install -r requirements.txt
+```
+
+### 2. Configure Environment
+
+Create `.env` file in the workspace root:
+
+```bash
+# Required
+OPENAI_API_KEY=sk-your-openai-api-key
+
+# Optional (for enhanced organization discovery)
+TAVILY_API_KEY=tvly-your-tavily-api-key
+
+# Server configuration
+PORT=3001
+```
+
+### 3. Build MCP Server
+
+The agent depends on the MCP server tools, so build it first:
+
+```bash
+# From workspace root
+pnpm --filter @eu-ai-act/mcp-server build
+```
+
+### 4. Start Development Servers
+
+**Option A: Run both servers** (recommended)
+
+Terminal 1 - API Server:
+```bash
+cd apps/eu-ai-act-agent
+pnpm dev
+```
+
+Terminal 2 - Gradio UI:
+```bash
+cd apps/eu-ai-act-agent
+pnpm gradio
+# or: uv run src/gradio_app.py
+```
+
+**Option B: Use workspace commands**
+```bash
+# Terminal 1
+pnpm --filter @eu-ai-act/agent dev
+
+# Terminal 2
+pnpm --filter @eu-ai-act/agent gradio
+```
+
+### 5. Access the Application
+
+- **Gradio UI**: http://localhost:7860
+- **API Server**: http://localhost:3001
+- **Health Check**: http://localhost:3001/health
+
+## Production Deployment
+
+### Option 1: Vercel (API) + Hugging Face Spaces (Gradio)
+
+**Deploy API Server to Vercel:**
+
+1. Create `vercel.json` in `apps/eu-ai-act-agent/`:
+```json
+{
+  "version": 2,
+  "builds": [
+    {
+      "src": "dist/server.js",
+      "use": "@vercel/node"
+    }
+  ],
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "dist/server.js"
+    }
+  ],
+  "env": {
+    "OPENAI_API_KEY": "@openai-api-key",
+    "TAVILY_API_KEY": "@tavily-api-key"
+  }
+}
+```
+
+2. Deploy:
+```bash
+cd apps/eu-ai-act-agent
+pnpm build
+vercel --prod
+```
+
+**Deploy Gradio to Hugging Face Spaces:**
+
+1. Create a new Space at https://huggingface.co/spaces
+2. Choose Gradio SDK
+3. Push your code:
+```bash
+git remote add hf https://huggingface.co/spaces/<username>/<space-name>
+git push hf main
+```
+
+4. Set environment variables in Space settings:
+   - `API_URL=https://your-vercel-app.vercel.app`
+
+### Option 2: Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.api
+    ports:
+      - "3001:3001"
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - TAVILY_API_KEY=${TAVILY_API_KEY}
+    restart: unless-stopped
+
+  gradio:
+    build:
+      context: .
+      dockerfile: Dockerfile.gradio
+    ports:
+      - "7860:7860"
+    environment:
+      - API_URL=http://api:3001
+    depends_on:
+      - api
+    restart: unless-stopped
+```
+
+Deploy:
+```bash
+docker-compose up -d
+```
+
+### Option 3: Railway / Render
+
+Both platforms support Node.js and Python apps:
+
+1. **API Server**:
+   - Build command: `pnpm build`
+   - Start command: `pnpm start`
+   - Add environment variables
+
+2. **Gradio App**:
+   - Build command: `curl -LsSf https://astral.sh/uv/install.sh | sh && uv pip install -r requirements.txt`
+   - Start command: `uv run src/gradio_app.py`
+   - Set `API_URL` to your API server URL
+
+## Environment Variables
+
+### Required
+- `OPENAI_API_KEY` - OpenAI API key for GPT-4 (used by agent and assess_compliance tool)
+
+### Optional
+- `TAVILY_API_KEY` - Tavily API key for enhanced organization research
+- `PORT` - API server port (default: 3001)
+- `API_URL` - Full URL to API server (for Gradio, default: http://localhost:3001)
+
+## Troubleshooting
+
+### API Server Issues
+
+**Problem**: Server won't start
+```bash
+# Check Node.js version
+node --version  # Should be 18+
+
+# Rebuild dependencies
+pnpm install
+pnpm --filter @eu-ai-act/mcp-server build
+pnpm --filter @eu-ai-act/agent build
+```
+
+**Problem**: Tools not working
+```bash
+# Verify MCP server is built
+ls packages/eu-ai-act-mcp/dist/
+
+# Check environment variables
+echo $OPENAI_API_KEY
+```
+
+### Gradio Issues
+
+**Problem**: Can't connect to API
+- Verify API server is running: `curl http://localhost:3001/health`
+- Check `API_URL` in environment or `src/gradio_app.py`
+
+**Problem**: Python dependencies missing
+```bash
+# Install uv if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv pip install -r requirements.txt
+```
+
+### General Issues
+
+**Problem**: CORS errors
+- Ensure Gradio runs on port 7860 (default)
+- Check CORS settings in `src/server.ts`
+
+**Problem**: Rate limits
+- OpenAI has rate limits based on your plan
+- Consider implementing request queuing or caching
+
+## Performance Optimization
+
+1. **Enable Caching**: Add Redis for caching organization/system discoveries
+2. **Use Streaming**: Already enabled for real-time responses
+3. **Optimize Tools**: Cache Tavily research results
+4. **Load Balancing**: Use multiple API server instances behind a load balancer
+
+## Monitoring
+
+### Health Checks
+```bash
+# API health
+curl http://localhost:3001/health
+
+# Tools status
+curl http://localhost:3001/api/tools
+```
+
+### Logging
+- API logs: Check console output or configure logging service
+- Gradio logs: Built-in console logging
+- Consider adding: Sentry, LogRocket, or DataDog
+
+## Security
+
+1. **API Keys**: Never commit to Git, use environment variables
+2. **CORS**: Restrict origins in production
+3. **Rate Limiting**: Add rate limiting middleware
+4. **Authentication**: Consider adding API authentication for production
+5. **HTTPS**: Always use HTTPS in production
+
+## Scaling
+
+For high traffic:
+1. Deploy multiple API server instances
+2. Use Redis for session management
+3. Implement request queuing (Bull/BullMQ)
+4. Consider serverless functions for tools
+5. Use CDN for static assets
+
+## Support
+
+- 📖 Documentation: See README.md
+- 🐛 Issues: GitHub Issues
+- 💬 Discussions: GitHub Discussions
+
+

apps/eu-ai-act-agent/Dockerfile

@@ -0,0 +1,61 @@
+# EU AI Act Compliance Agent - Hugging Face Spaces
+# Deploys Agent + MCP Server from monorepo
+
+FROM node:20-slim
+
+# Install Python, pnpm, and uv (to /usr/local/bin for all users)
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-venv \
+    curl \
+    && npm install -g pnpm \
+    && curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh \
+    && rm -rf /var/lib/apt/lists/*
+
+# Use existing node user (UID 1000) for HF Spaces compatibility
+USER node
+ENV HOME=/home/node
+
+WORKDIR $HOME/app
+
+# Copy entire monorepo
+COPY --chown=node . .
+
+# Install Node dependencies
+RUN pnpm install --frozen-lockfile
+
+# Build MCP server and Agent
+RUN pnpm --filter @eu-ai-act/mcp-server build
+RUN pnpm --filter @eu-ai-act/agent build
+
+# Create Python venv and install dependencies with uv
+RUN uv venv $HOME/venv && \
+    . $HOME/venv/bin/activate && \
+    uv pip install --no-cache -r apps/eu-ai-act-agent/requirements.txt
+
+# Environment
+# API_URL: Internal communication between Gradio and API server (localhost works inside container)
+# PUBLIC_URL: External HF Spaces URL for links shown to users
+ENV NODE_ENV=production \
+    PORT=3001 \
+    API_URL=http://localhost:3001 \
+    PUBLIC_URL=https://mcp-1st-birthday-eu-ai-act-compliance-agent.hf.space \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    GRADIO_SHARE=false \
+    PATH=/home/node/venv/bin:$PATH \
+    VIRTUAL_ENV=/home/node/venv \
+    MCP_SERVER_PATH=/home/node/app/packages/eu-ai-act-mcp/dist/index.js
+
+# Set working directory to the agent app for CMD
+WORKDIR $HOME/app/apps/eu-ai-act-agent
+
+EXPOSE 7860
+
+# Start API server + Main Agent UI (port 7860)
+# ChatGPT MCP Server is deployed separately at:
+# https://huggingface.co/spaces/MCP-1st-Birthday/eu-ai-act-chatgpt-mcp
+CMD node dist/server.js & \
+    sleep 2 && \
+    python src/gradio_app.py
+

apps/eu-ai-act-agent/Dockerfile.chatgpt-mcp

@@ -0,0 +1,57 @@
+# EU AI Act - ChatGPT MCP Server
+# Standalone MCP server for ChatGPT Apps integration
+# Deploys ONLY the MCP tools (discover_organization, discover_ai_services, assess_compliance)
+
+FROM node:20-slim
+
+# Install Python, pnpm, and uv
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-venv \
+    curl \
+    && npm install -g pnpm \
+    && curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh \
+    && rm -rf /var/lib/apt/lists/*
+
+# Use existing node user (UID 1000) for HF Spaces compatibility
+USER node
+ENV HOME=/home/node
+
+WORKDIR $HOME/app
+
+# Copy entire monorepo
+COPY --chown=node . .
+
+# Install Node dependencies
+RUN pnpm install --frozen-lockfile
+
+# Build MCP server and Agent (needed for API)
+RUN pnpm --filter @eu-ai-act/mcp-server build
+RUN pnpm --filter @eu-ai-act/agent build
+
+# Create Python venv and install dependencies
+RUN uv venv $HOME/venv && \
+    . $HOME/venv/bin/activate && \
+    uv pip install --no-cache -r apps/eu-ai-act-agent/requirements.txt
+
+# Environment
+ENV NODE_ENV=production \
+    PORT=3001 \
+    API_URL=http://localhost:3001 \
+    PUBLIC_URL=https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space \
+    CHATGPT_APP_SERVER_NAME=0.0.0.0 \
+    CHATGPT_APP_SERVER_PORT=7860 \
+    PATH=/home/node/venv/bin:$PATH \
+    VIRTUAL_ENV=/home/node/venv \
+    MCP_SERVER_PATH=/home/node/app/packages/eu-ai-act-mcp/dist/index.js
+
+WORKDIR $HOME/app/apps/eu-ai-act-agent
+
+EXPOSE 7860
+
+# Start API server + ChatGPT MCP App on port 7860
+# MCP URL will be: PUBLIC_URL/gradio_api/mcp/
+CMD node dist/server.js & \
+    sleep 2 && \
+    python src/chatgpt_app.py
+

apps/eu-ai-act-agent/EXAMPLES.md

@@ -0,0 +1,517 @@
+# 💡 Usage Examples
+
+Real-world examples of using the EU AI Act Compliance Agent.
+
+## 🎯 Example 1: Understanding the Basics
+
+### Question
+```
+What is the EU AI Act and why should I care about it?
+```
+
+### Agent Response
+The agent will explain:
+- Overview of the EU AI Act (Regulation 2024/1689)
+- Why it matters for organizations deploying AI in Europe
+- Key risk categories and their implications
+- Important deadlines (Feb 2025, Aug 2026, Aug 2027)
+- Penalties for non-compliance
+
+**Use Case**: Educating stakeholders and leadership teams
+
+---
+
+## 🏢 Example 2: Organization Discovery
+
+### Question
+```
+Discover and analyze OpenAI's compliance profile
+```
+
+### Agent Workflow
+1. **Calls `discover_organization`** with "OpenAI"
+   - Searches company information via Tavily
+   - Identifies sector, size, AI maturity level
+   - Maps EU presence and regulatory obligations
+   
+2. **Returns Profile**:
+   ```json
+   {
+     "organization": {
+       "name": "OpenAI",
+       "sector": "AI Research & Development",
+       "size": "Large Enterprise",
+       "aiMaturityLevel": "Expert",
+       "euPresence": true,
+       "primaryRole": "Provider"
+     },
+     "regulatoryContext": {
+       "hasQualityManagementSystem": true,
+       "hasRiskManagementSystem": true,
+       "complianceDeadlines": [...]
+     }
+   }
+   ```
+
+3. **Provides Insights**:
+   - OpenAI is a Large Enterprise with Expert AI maturity
+   - As an AI Provider, they must comply with Articles 16-29
+   - They need authorized representative in EU (Article 22)
+   - Must register high-risk systems in EU database
+
+**Use Case**: Initial compliance assessment for your organization or analyzing competitors
+
+---
+
+## 🤖 Example 3: AI System Classification
+
+### Question
+```
+Is a recruitment screening AI system high-risk under the EU AI Act?
+```
+
+### Agent Response
+Yes, it's HIGH RISK per **Annex III, Section 4(a)**: "AI systems intended to be used for recruitment or selection of natural persons."
+
+**Requirements**:
+- ✅ Conformity assessment (Article 43) - Must undergo third-party assessment
+- ✅ Technical documentation (Article 11, Annex IV) - Comprehensive system docs
+- ✅ Risk management system (Article 9) - Continuous risk monitoring
+- ✅ Data governance (Article 10) - Training data quality assurance
+- ✅ Human oversight (Article 14) - Human-in-the-loop procedures
+- ✅ Transparency (Article 13) - Clear information to users
+- ✅ CE marking (Article 48) - Affixing CE mark
+- ✅ EU database registration (Article 49) - Registration before deployment
+
+**Timeline**:
+- Compliance required by: **August 2, 2026**
+
+**Use Case**: Determining if your AI system requires strict compliance measures
+
+---
+
+## 🔍 Example 4: Comprehensive System Discovery
+
+### Question
+```
+Scan and classify all AI systems for a company called "TechCorp AI"
+```
+
+### Agent Workflow
+1. **Calls `discover_organization`** for TechCorp AI
+   - Gets organization context
+   
+2. **Calls `discover_ai_services`** with organization context
+   - Discovers AI systems (real or mock data)
+   - Classifies each by risk level
+   - Identifies compliance gaps
+   
+3. **Returns Inventory**:
+   ```json
+   {
+     "systems": [
+       {
+         "system": {
+           "name": "Customer Service Chatbot",
+           "status": "Production"
+         },
+         "riskClassification": {
+           "category": "Limited",
+           "riskScore": 35
+         }
+       },
+       {
+         "system": {
+           "name": "Fraud Detection System",
+           "status": "Production"
+         },
+         "riskClassification": {
+           "category": "High",
+           "annexIIICategory": "Annex III, Section 5(d)",
+           "riskScore": 85
+         }
+       }
+     ],
+     "riskSummary": {
+       "highRiskCount": 1,
+       "limitedRiskCount": 1,
+       "totalCount": 2
+     }
+   }
+   ```
+
+4. **Provides Summary**:
+   - TechCorp AI has 2 AI systems
+   - 1 high-risk system requiring immediate attention
+   - 1 limited-risk system with transparency obligations
+
+**Use Case**: Creating a comprehensive AI system inventory for compliance planning
+
+---
+
+## 📄 Example 5: Documentation Generation
+
+### Question
+```
+Generate EU AI Act compliance documentation for our customer support chatbot
+```
+
+### Agent Workflow
+1. **Classifies the system** as Limited Risk (Article 50)
+   
+2. **Calls `assess_compliance`** with:
+   - System type: Customer support chatbot
+   - Risk category: Limited Risk
+   - Generate documentation: true
+   
+3. **Generates Templates**:
+
+   **📋 Risk Assessment**
+   ```markdown
+   # Risk Assessment: Customer Support Chatbot
+   
+   ## Risk Classification
+   - **Category**: Limited Risk
+   - **Article**: Article 50 (Transparency Obligations)
+   
+   ## Risk Analysis
+   The chatbot interacts with natural persons and must disclose
+   that the user is interacting with an AI system...
+   ```
+
+   **📄 Technical Documentation**
+   ```markdown
+   # Technical Documentation
+   
+   ## System Description
+   - **Name**: Customer Support Chatbot
+   - **Purpose**: Automated customer service
+   - **Technology**: Natural Language Processing
+   
+   ## Compliance Requirements
+   1. Transparency Notice (Article 50)...
+   ```
+
+   **📢 Transparency Notice**
+   ```markdown
+   # Transparency Notice
+   
+   You are interacting with an AI system designed to assist
+   with customer service inquiries...
+   ```
+
+4. **Provides Export Options**:
+   - Download as Markdown
+   - Convert to PDF
+   - Generate Word document
+
+**Use Case**: Creating required compliance documentation quickly
+
+---
+
+## ⚖️ Example 6: Compliance Gap Analysis
+
+### Question
+```
+Analyze compliance gaps for our high-risk credit scoring AI
+```
+
+### Agent Workflow
+1. **Calls `discover_ai_services`** with system details
+   - Classifies as High Risk (Annex III, Section 5(b))
+   
+2. **Calls `assess_compliance`**
+   - Analyzes current compliance status
+   - Identifies gaps
+   
+3. **Returns Gap Analysis**:
+   ```json
+   {
+     "assessment": {
+       "overallScore": 45,
+       "gaps": [
+         {
+           "area": "Technical Documentation",
+           "severity": "Critical",
+           "article": "Article 11",
+           "description": "Missing comprehensive technical documentation per Annex IV",
+           "recommendation": "Create detailed system architecture and data flow documentation"
+         },
+         {
+           "area": "Conformity Assessment",
+           "severity": "Critical",
+           "article": "Article 43",
+           "description": "No conformity assessment conducted",
+           "recommendation": "Engage notified body for third-party assessment"
+         },
+         {
+           "area": "Human Oversight",
+           "severity": "High",
+           "article": "Article 14",
+           "description": "Insufficient human oversight mechanisms",
+           "recommendation": "Implement human-in-the-loop review process"
+         }
+       ],
+       "recommendations": [...]
+     }
+   }
+   ```
+
+4. **Provides Roadmap**:
+   - Priority 1: Technical documentation
+   - Priority 2: Conformity assessment
+   - Priority 3: Human oversight implementation
+   - Priority 4: Risk management system
+   
+**Use Case**: Understanding what needs to be done to achieve compliance
+
+---
+
+## 🎓 Example 7: Article-Specific Questions
+
+### Question
+```
+Explain Article 14 on human oversight and how to implement it
+```
+
+### Agent Response
+**Article 14: Human Oversight**
+
+High-risk AI systems must be designed to enable effective oversight by natural persons during operation.
+
+**Key Requirements**:
+1. **Human-in-the-loop** (HITL) - Humans can intervene in real-time
+2. **Human-on-the-loop** (HOTL) - Humans can monitor and intervene if needed
+3. **Human-in-command** (HIC) - Humans can override AI decisions
+
+**Implementation Steps**:
+1. **Design interfaces** that enable humans to:
+   - Understand AI outputs
+   - Interpret system decisions
+   - Override or reverse decisions
+   - Interrupt system operation
+
+2. **Provide training** to oversight personnel on:
+   - System capabilities and limitations
+   - Potential risks and biases
+   - When and how to intervene
+
+3. **Document procedures** for:
+   - Escalation paths
+   - Override protocols
+   - Incident reporting
+
+**Example Implementation**:
+```typescript
+// Human oversight mechanism
+interface HumanOversight {
+  canOverride: boolean;
+  reviewRequired: boolean;
+  escalationPath: string[];
+  monitoringLevel: "HITL" | "HOTL" | "HIC";
+}
+```
+
+**Use Case**: Understanding specific compliance requirements in depth
+
+---
+
+## 🌐 Example 8: Multi-Step Analysis
+
+### Question
+```
+I'm launching a new AI-powered hiring platform in the EU. 
+What do I need to do to be compliant?
+```
+
+### Agent Workflow (Automatic Multi-Step)
+
+**Step 1: Risk Classification**
+- Identifies this as HIGH RISK (Annex III, Section 4)
+- Explains strict requirements apply
+
+**Step 2: Organization Profile**
+- Asks for or discovers organization details
+- Determines provider role and obligations
+
+**Step 3: System Discovery**
+- Catalogs the hiring platform features
+- Identifies which components are AI-driven
+
+**Step 4: Compliance Assessment**
+- Generates comprehensive compliance checklist
+- Identifies documentation requirements
+- Provides timeline and budget estimates
+
+**Step 5: Documentation**
+- Generates initial templates for:
+  - Risk management system
+  - Technical documentation
+  - Conformity assessment preparation
+  - Transparency notices
+
+**Step 6: Roadmap**
+- Creates phased implementation plan
+- Suggests notified bodies for assessment
+- Provides resource recommendations
+
+**Use Case**: End-to-end compliance planning for new AI products
+
+---
+
+## 🔄 Example 9: Compliance Monitoring
+
+### Question
+```
+We completed initial compliance last year. 
+How do we maintain ongoing compliance?
+```
+
+### Agent Response
+
+**Ongoing Compliance Requirements**:
+
+**1. Post-Market Monitoring (Article 72)**
+- Establish monitoring system
+- Collect and analyze incident data
+- Report serious incidents to authorities
+
+**2. Regular Updates**:
+- Update technical documentation with system changes
+- Re-assess risks after major updates
+- Maintain conformity assessment validity
+
+**3. Quality Management (Article 17)**:
+- Conduct internal audits
+- Maintain management review process
+- Implement corrective actions
+
+**4. Record Keeping**:
+- Maintain logs for high-risk systems (Article 12)
+- Keep documentation for 10 years
+- Track all modifications
+
+**5. Incident Response**:
+- Report serious incidents within 15 days
+- Implement corrective measures
+- Update risk assessments
+
+**Recommended Schedule**:
+- Monthly: Review system logs and incidents
+- Quarterly: Internal compliance audit
+- Annually: Full compliance review and update documentation
+- As needed: Risk re-assessment after changes
+
+**Use Case**: Establishing continuous compliance processes
+
+---
+
+## 💼 Example 10: Executive Summary
+
+### Question
+```
+Create an executive summary of our AI compliance status 
+for the board meeting
+```
+
+### Agent Workflow
+1. Runs organization discovery
+2. Discovers all AI systems
+3. Assesses overall compliance
+4. Generates executive summary
+
+### Sample Output
+
+```markdown
+# EU AI Act Compliance - Executive Summary
+
+## Overview
+- **Organization**: [Company Name]
+- **Total AI Systems**: 8
+- **Overall Compliance Score**: 62/100
+
+## Risk Breakdown
+- 🔴 Unacceptable Risk: 0 systems
+- 🟠 High Risk: 2 systems
+- 🟡 Limited Risk: 3 systems
+- 🟢 Minimal Risk: 3 systems
+
+## Critical Actions Required
+1. **Urgent**: Complete conformity assessment for recruitment AI (Deadline: Aug 2026)
+2. **High Priority**: Implement human oversight for credit scoring AI
+3. **Medium Priority**: Create transparency notices for chatbots
+
+## Budget Impact
+- Conformity assessments: €50,000 - €100,000
+- Documentation & implementation: €30,000 - €50,000
+- Ongoing compliance: €20,000/year
+
+## Timeline
+- Q1 2025: Complete high-risk system documentation
+- Q2 2025: Begin conformity assessments
+- Q3 2025: Implement human oversight mechanisms
+- Q4 2025: Final compliance verification
+
+## Risks of Non-Compliance
+- Fines up to €35M or 7% of global revenue
+- Prohibition from EU market
+- Reputational damage
+```
+
+**Use Case**: Communicating compliance status to leadership and stakeholders
+
+---
+
+## 🎯 Pro Tips for Using the Agent
+
+### 1. Be Specific
+❌ "Tell me about compliance"
+✅ "Analyze compliance requirements for our facial recognition system"
+
+### 2. Provide Context
+❌ "Is this high-risk?"
+✅ "Is a chatbot for mental health counseling high-risk?"
+
+### 3. Use Follow-Ups
+Ask clarifying questions based on the agent's responses:
+- "Can you explain that Article in more detail?"
+- "What's the timeline for implementing this?"
+- "How much does conformity assessment typically cost?"
+
+### 4. Request Specifics
+- "Generate just the transparency notice"
+- "Focus only on Article 10 data governance requirements"
+- "What are the penalties for non-compliance?"
+
+### 5. Leverage Tools
+The agent automatically uses the right tools:
+- Organization questions → `discover_organization`
+- System questions → `discover_ai_services`
+- Documentation requests → `assess_compliance`
+
+---
+
+## 📚 Common Questions
+
+**Q: Can it analyze my actual systems?**
+A: With proper integration, yes. Currently it uses mock data but can be connected to your infrastructure.
+
+**Q: Is the documentation legally binding?**
+A: No, it provides templates and guidance. Always consult legal professionals for final documentation.
+
+**Q: Can it help with GDPR compliance too?**
+A: The EU AI Act intersects with GDPR. The agent provides guidance on data governance (Article 10) which aligns with GDPR.
+
+**Q: How often should I use it?**
+A: 
+- Initially: For assessment and planning
+- Quarterly: For compliance reviews
+- As needed: When launching new AI systems
+
+**Q: Can it track multiple projects?**
+A: Currently it's conversation-based. Consider exporting and saving assessments for different projects.
+
+---
+
+**Ready to try these examples?** Start the agent and copy any of the questions above! 🚀
+

apps/eu-ai-act-agent/QUICKSTART.md

@@ -0,0 +1,371 @@
+# 🚀 Quick Start Guide
+
+Get the EU AI Act Compliance Agent running in under 5 minutes!
+
+## ⚡ Fast Track
+
+```bash
+# 1. Install uv (fast Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 2. Set your API keys (required)
+export TAVILY_API_KEY="tvly-your-tavily-key"  # Required - Get from https://app.tavily.com
+# Choose one model and set its API key:
+export ANTHROPIC_API_KEY="sk-ant-your-key"    # For Claude 4-5
+# OR
+export OPENAI_API_KEY="sk-your-key"           # For GPT-5
+# OR
+export XAI_API_KEY="xai-your-key"             # For Grok 4-1
+
+# 3. Install dependencies (from workspace root)
+cd /path/to/mcp-1st-birthday-ai-act
+pnpm install
+
+# 4. Install Python packages
+cd apps/eu-ai-act-agent
+uv pip install -r requirements.txt
+
+# 5. Start everything (automatic!)
+chmod +x start.sh
+./start.sh
+```
+
+That's it! Open http://localhost:7860 🎉
+
+## 📋 Step-by-Step Instructions
+
+### 1. Prerequisites
+
+Install these first:
+- **Node.js 18+**: https://nodejs.org/
+- **pnpm**: `npm install -g pnpm`
+- **Python 3.9+**: https://www.python.org/
+- **uv**: https://docs.astral.sh/uv/ (fast Python package manager)
+- **Git**: https://git-scm.com/
+
+### 2. Get API Keys
+
+**Tavily (Required)**:
+1. Sign up at https://app.tavily.com
+2. Get your API key (1,000 free credits/month)
+3. Copy it (starts with `tvly-`)
+
+**Model Selection (Required - Choose One)**:
+
+**Option A: Claude 4-5 (Anthropic)**:
+1. Sign up at https://console.anthropic.com/
+2. Go to API Keys section
+3. Create a new key
+4. Copy it (starts with `sk-ant-`)
+
+**Option B: GPT-5 (OpenAI)**:
+1. Sign up at https://platform.openai.com/
+2. Go to API Keys section
+3. Create a new key
+4. Copy it (starts with `sk-`)
+
+**Option C: Grok 4-1 (xAI)**:
+1. Sign up at https://x.ai/
+2. Go to API Keys section
+3. Create a new key
+4. Copy it (starts with `xai-`)
+
+### 3. Clone & Setup
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd mcp-1st-birthday-ai-act
+
+# Install Node.js dependencies
+pnpm install
+
+# Install uv (fast Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Go to agent directory
+cd apps/eu-ai-act-agent
+
+# Install Python dependencies
+uv pip install -r requirements.txt
+```
+
+### 4. Configure Environment
+
+Create `.env` file in the **workspace root** (not in apps/eu-ai-act-agent):
+
+```bash
+# Go back to workspace root
+cd ../..
+
+# Create .env file
+cat > .env << EOF
+# Required: Tavily API key
+TAVILY_API_KEY=tvly-your-tavily-api-key-here
+
+# Required: Choose one model and provide its API key
+# For Claude 4-5:
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+# OR for GPT-5:
+OPENAI_API_KEY=sk-your-openai-api-key-here
+# OR for Grok 4-1:
+XAI_API_KEY=xai-your-key-here
+
+PORT=3001
+EOF
+```
+
+Or copy from example:
+```bash
+cp .env.example .env
+# Then edit .env with your keys
+```
+
+### 5. Build MCP Server
+
+The agent needs the MCP server tools:
+
+```bash
+# From workspace root
+pnpm --filter @eu-ai-act/mcp-server build
+```
+
+### 6. Start the Agent
+
+**Option A: Use startup script** (easiest)
+```bash
+cd apps/eu-ai-act-agent
+chmod +x start.sh
+./start.sh
+```
+
+**Option B: Manual start** (two terminals)
+
+Terminal 1 - API Server:
+```bash
+cd apps/eu-ai-act-agent
+pnpm dev
+```
+
+Terminal 2 - Gradio UI:
+```bash
+cd apps/eu-ai-act-agent
+uv run src/gradio_app.py
+```
+
+**Option C: Use workspace commands**
+```bash
+# Terminal 1
+pnpm --filter @eu-ai-act/agent dev
+
+# Terminal 2
+pnpm --filter @eu-ai-act/agent gradio
+```
+
+### 7. Open the UI
+
+Navigate to http://localhost:7860 in your browser!
+
+## 🎯 Try It Out
+
+### Example 1: General Question
+```
+You: What is the EU AI Act?
+```
+
+The agent will explain the regulation with key details.
+
+### Example 2: Organization Analysis
+```
+You: Analyze OpenAI's EU AI Act compliance
+```
+
+The agent will:
+1. Discover OpenAI's organization profile
+2. Identify their AI systems
+3. Assess compliance status
+4. Provide recommendations
+
+### Example 3: Risk Classification
+```
+You: Is a recruitment screening AI high-risk?
+```
+
+The agent will classify it per Annex III and explain requirements.
+
+### Example 4: Documentation
+```
+You: Generate compliance documentation for a chatbot
+```
+
+The agent will create:
+- Risk assessment
+- Technical documentation
+- Transparency notice
+- Compliance checklist
+
+## 🔧 Troubleshooting
+
+### "Cannot connect to API server"
+
+**Solution**:
+```bash
+# Check if API is running
+curl http://localhost:3001/health
+
+# If not, start it:
+cd apps/eu-ai-act-agent
+pnpm dev
+```
+
+### "API key error" or "Model not found"
+
+**Solution**:
+```bash
+# Verify your Tavily API key is set
+echo $TAVILY_API_KEY
+
+# Verify your model API key is set (check which one you're using)
+echo $ANTHROPIC_API_KEY  # For Claude 4-5
+echo $OPENAI_API_KEY     # For GPT-5
+echo $XAI_API_KEY        # For Grok 4-1
+
+# Or check .env file
+cat ../../.env | grep -E "(TAVILY|ANTHROPIC|OPENAI|XAI)_API_KEY"
+
+# Make sure your API keys are valid:
+# - Tavily: https://app.tavily.com
+# - Claude: https://console.anthropic.com/api-keys
+# - OpenAI: https://platform.openai.com/api-keys
+# - xAI: https://x.ai/api-keys
+```
+
+### "Module not found" errors
+
+**Solution**:
+```bash
+# Reinstall Node.js dependencies
+cd /path/to/workspace/root
+pnpm install
+
+# Rebuild MCP server
+pnpm --filter @eu-ai-act/mcp-server build
+
+# Reinstall Python packages
+cd apps/eu-ai-act-agent
+pip3 install -r requirements.txt
+```
+
+### Port already in use
+
+**Solution**:
+```bash
+# API Server (port 3001)
+PORT=3002 pnpm dev
+
+# Gradio (port 7860) - edit src/gradio_app.py
+# Change server_port=7860 to server_port=7861
+```
+
+### Python package issues
+
+**Solution**:
+```bash
+# Install uv if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies with uv
+uv pip install -r requirements.txt
+
+# Or create and use a virtual environment with uv
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -r requirements.txt
+```
+
+## 📊 What's Included
+
+### Three MCP Tools
+
+1. **discover_organization** - Profile organizations
+   - Company research via Tavily
+   - AI maturity assessment
+   - Regulatory context
+
+2. **discover_ai_services** - Catalog AI systems
+   - Risk classification (Unacceptable/High/Limited/Minimal)
+   - Compliance status
+   - Gap analysis
+
+3. **assess_compliance** - Generate documentation
+   - Risk management templates
+   - Technical documentation
+   - Conformity assessments
+   - Transparency notices
+
+### Intelligent Features
+
+- **Natural Language**: Chat in plain English
+- **Contextual**: Remembers conversation history
+- **Multi-Step**: Automatically chains tools
+- **Streaming**: Real-time responses
+- **Export**: Download generated documents
+
+## 🎓 Learning Path
+
+1. **Start Simple**: Ask "What is the EU AI Act?"
+2. **Try Classification**: "Is [your AI] high-risk?"
+3. **Explore Tools**: "Discover [company name]"
+4. **Generate Docs**: "Create compliance documentation"
+5. **Go Deep**: Ask about specific Articles or requirements
+
+## 📚 Next Steps
+
+- **Read the full README**: `cat README.md`
+- **Check deployment guide**: `cat DEPLOYMENT.md`
+- **Explore the MCP tools**: See `../../packages/eu-ai-act-mcp/README.md`
+- **Learn about Vercel AI SDK**: https://ai-sdk.dev/docs
+- **Understand Gradio**: https://gradio.app/guides/quickstart
+
+## 💡 Tips
+
+1. **Be specific**: "Analyze compliance for our recruitment AI" works better than "check compliance"
+2. **Use context**: Mention company names, AI system types, industries
+3. **Ask follow-ups**: The agent maintains conversation context
+4. **Request docs**: Ask for specific templates or reports
+5. **Cite articles**: Reference specific AI Act articles for detailed info
+
+## 🆘 Getting Help
+
+- 📖 **Full Documentation**: See README.md
+- 🐛 **Found a bug?**: Open a GitHub issue
+- 💬 **Questions?**: Check GitHub Discussions
+- 📧 **Contact**: See package.json for maintainer info
+
+## 🎯 Pro Tips
+
+### For Developers
+- Use `pnpm dev` for hot reload during development
+- Check `/api/tools` endpoint to see available tools
+- API logs show tool execution details
+- Gradio supports custom CSS theming
+
+### For Compliance Teams
+- Start with organization discovery
+- Document all AI systems systematically
+- Focus on high-risk systems first
+- Export and archive assessment reports
+- Review compliance quarterly
+
+### For Organizations
+- Use as part of compliance workflow
+- Train teams on EU AI Act basics
+- Generate documentation templates
+- Track compliance progress
+- Prepare for audits
+
+---
+
+**Ready to go?** Open http://localhost:7860 and start chatting! 🚀
+
+

apps/eu-ai-act-agent/README.md

@@ -0,0 +1,502 @@
+---
+title: EU AI Act Compliance Agent by legitima.ai
+emoji: ⚖️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: true
+tags:
+  - building-mcp-track-enterprise
+  - mcp-in-action-track-enterprise
+  - modal-infernce
+  - gemini
+  - claude
+  - gpt-apps
+  - gradio-app
+  - gradio-mcp
+  - gradio-chatgpt-app
+  - gpt-oss
+short_description: AI-powered EU AI Act compliance assessment with MCP tools
+---
+
+# 🇪🇺 EU AI Act Compliance Agent by [legitima.ai](https://legitima.ai/mcp-hackathon) powered by [decode](https://decode.gr/en)
+
+<div align="center">
+  <img src="https://www.legitima.ai/mcp-hackathon.png" alt="Gradio MCP Hackathon - EU AI Act Compliance" width="800"/>
+</div>
+
+> **🎂 Built for the MCP 1st Birthday Hackathon**  
+> **🔗 [Live Demo & Showcase](https://www.legitima.ai/mcp-hackathon)** - See MCP tools and agent capabilities in action!
+
+An interactive AI agent with Gradio UI for navigating EU AI Act compliance requirements, powered by Vercel AI SDK v5 and the EU AI Act MCP Server. This project demonstrates enterprise-grade MCP tool integration with multi-model AI capabilities for regulatory compliance assessment.
+
+## 📑 Table of Contents
+
+- [🎯 Hackathon Submission](#hackathon-submission)
+- [🏗️ Architecture](#architecture)
+- [🔌 MCP Tools Integration](#mcp-tools-integration)
+- [✨ Features](#features)
+- [🚀 Getting Started](#getting-started)
+- [🚀 How to Use in ChatGPT](#how-to-use-in-chatgpt)
+- [📖 Usage Examples](#usage-examples)
+- [🔧 Configuration](#configuration)
+- [🛠️ Development](#development)
+- [📚 API Reference](#api-reference)
+- [🧪 Testing](#testing)
+- [🎯 Tech Stack](#tech-stack)
+
+<a id="hackathon-submission"></a>
+
+## 🎯 Hackathon Submission
+
+**Track 1: Building MCP** ✅ | **Track 2: MCP in Action** ✅
+
+This submission showcases:
+- **Custom MCP Server** with 3 specialized tools for EU AI Act compliance
+- **Enterprise-grade Agent** using Vercel AI SDK v5 with intelligent tool orchestration
+- **ChatGPT Apps Integration** - Deploy as a connector to use tools directly in ChatGPT ([Live MCP Server](https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/))
+- **Multi-model Support** - 6 AI models including free GPT-OSS via Modal.com
+- **Real-world Application** - Solving critical regulatory compliance challenges
+- **Production-ready Architecture** - Gradio UI + Express API + MCP Protocol
+
+**🔗 Demo & Showcase:** [www.legitima.ai/mcp-hackathon](https://www.legitima.ai/mcp-hackathon)
+**📹 Video:** [Guiddes](https://app.guidde.com/share/playlists/2wXbDrSm2YY7YnWMJbftuu?origin=wywDANMIvNhPu9kYVOXCPpdFcya2)
+**📱 Social Media:** [LinkedIn Post 1](https://www.linkedin.com/posts/iordanis-sarafidis_mcp-1st-birthday-mcp-1st-birthday-activity-7400132272282144768-ZIir?utm_source=share&utm_medium=member_desktop&rcm=ACoAAB0ARLABGvUO6Q--hJP0cDG7h0LZT0-roLs)
+
+[LinkedIn Post 2](https://www.linkedin.com/posts/billdrosatos_mcp-1st-birthday-mcp-1st-birthday-activity-7400135422502252544-C5BS?utm_source=share&utm_medium=member_desktop&rcm=ACoAAB0ARLABGvUO6Q--hJP0cDG7h0LZT0-roLs)
+
+<a id="architecture"></a>
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Gradio Web UI                        │
+│         (Python - Interactive Chat Interface)           │
+│              Real-time streaming responses              │
+└────────────────────┬────────────────────────────────────┘
+                     │ HTTP/REST
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│              Express API Server                         │
+│         (Node.js + Vercel AI SDK v5)                    │
+│   ┌─────────────────────────────────────────────────┐   │
+│   │  AI Agent with Intelligent Tool Orchestration    │   │
+│   │  - Multi-model support (6 models)                │   │
+│   │  - Streaming responses                          │   │
+│   │  - Contextual awareness                         │   │
+│   │  - Automatic tool selection                     │   │
+│   └─────────────────────────────────────────────────┘   │
+└────────────────────┬────────────────────────────────────┘
+                     │ MCP Protocol
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│         EU AI Act MCP Server (@eu-ai-act/mcp)          │
+│   ┌─────────────────────────────────────────────────┐  │
+│   │  Tool 1: discover_organization                   │  │
+│   │  • Tavily-powered web research                   │  │
+│   │  • Company profiling & AI maturity              │  │
+│   │  • Regulatory context discovery                 │  │
+│   └─────────────────────────────────────────────────┘  │
+│   ┌─────────────────────────────────────────────────┐  │
+│   │  Tool 2: discover_ai_services                    │  │
+│   │  • AI systems inventory                         │  │
+│   │  • Risk classification (4 tiers)                 │  │
+│   │  • Compliance status tracking                   │  │
+│   └─────────────────────────────────────────────────┘  │
+│   ┌─────────────────────────────────────────────────┐  │
+│   │  Tool 3: assess_compliance                      │  │
+│   │  • AI-powered gap analysis                      │  │
+│   │  • Multi-model assessment (5 models)            │  │
+│   │  • Documentation generation                     │  │
+│   └─────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+<a id="mcp-tools-integration"></a>
+
+### 🔌 MCP Tools Integration
+
+This agent leverages a **custom MCP server** (`@eu-ai-act/mcp-server`) that provides three specialized tools for EU AI Act compliance:
+
+#### 1. `discover_organization` 🏢
+- **Purpose**: Discover and profile organizations for compliance assessment
+- **Features**:
+  - Tavily AI-powered web research for real company data
+  - AI maturity level assessment (Nascent → Expert)
+  - Regulatory context discovery (GDPR, ISO certifications)
+  - EU presence and jurisdiction analysis
+  - Compliance deadline tracking
+- **EU AI Act References**: Articles 16, 17, 22, 49
+
+#### 2. `discover_ai_services` 🤖
+- **Purpose**: Inventory and classify AI systems according to EU AI Act risk tiers
+- **Features**:
+  - Automated risk classification (Unacceptable/High/Limited/Minimal)
+  - Annex III category identification
+  - Conformity assessment requirements
+  - Technical documentation status tracking
+  - Post-market monitoring compliance
+- **EU AI Act References**: Articles 6, 9, 10, 11, 12, 14, 43, 47, 48, 49, 72
+
+#### 3. `assess_compliance` ⚖️
+- **Purpose**: AI-powered compliance assessment with gap analysis and documentation generation
+- **Features**:
+  - Multi-model AI assessment (Claude 4.5, Claude Opus, GPT-5, Grok 4.1, Gemini 3 Pro)
+  - Comprehensive gap analysis with Article references
+  - Priority-based recommendations
+  - Auto-generated documentation templates:
+    - Risk Management System (Article 9)
+    - Technical Documentation (Article 11 / Annex IV)
+- **EU AI Act References**: Articles 9-17, 43, 49, 50, Annex IV
+
+**📚 Full MCP Tools Documentation**: See [`packages/eu-ai-act-mcp/README.md`](../../packages/eu-ai-act-mcp/README.md) for complete tool schemas, input/output formats, and usage examples.
+
+**💬 Use in ChatGPT**: The MCP server is deployed and ready to use as a ChatGPT App connector at [https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/](https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/) - see [How to Use in ChatGPT](#how-to-use-in-chatgpt) section below for instructions.
+
+<a id="features"></a>
+
+## ✨ Features
+
+### 🤖 Intelligent AI Agent
+- **Natural Language Interface**: Ask questions in plain English - no technical knowledge required
+- **Contextual Awareness**: Maintains full conversation context throughout the session
+- **Multi-Step Workflows**: Automatically orchestrates complex compliance assessments across multiple tools
+- **Intelligent Tool Calling**: Seamlessly invokes MCP tools based on user intent and conversation flow
+- **Streaming Responses**: Real-time AI responses with tool execution visibility
+- **Multi-Model Support**: Choose from 6 AI models including free GPT-OSS (default)
+
+### 📊 Compliance Capabilities
+- **Organization Profiling**: Discover company structure, AI maturity, and regulatory context using Tavily-powered research
+- **AI System Discovery**: Catalog and classify all AI systems with automated risk tier assignment
+- **Risk Assessment**: Classify systems per EU AI Act (Unacceptable/High/Limited/Minimal) with Article references
+- **Gap Analysis**: AI-powered gap identification with severity ratings, remediation effort estimates, and deadlines
+- **Documentation Generation**: Auto-generate professional compliance templates (Risk Management, Technical Documentation)
+- **Multi-Model Assessment**: Leverage 5 different AI models (Claude, GPT-5, Grok, Gemini) for comprehensive analysis
+
+### 🎨 Gradio UI
+- **Chat Interface**: Clean, modern chat experience
+- **Streaming Responses**: Real-time AI responses
+- **Document Preview**: View generated compliance documents
+- **Export Options**: Download assessment reports and templates
+- **Multi-language Support**: Available in multiple EU languages
+
+<a id="getting-started"></a>
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- **Node.js** 18+ and pnpm 8+
+- **Python** 3.9+ with uv (fast package manager)
+- **Tavily API key** (optional) - Get your free API key from [app.tavily.com](https://app.tavily.com) for enhanced web research
+- **Model selection** - Choose one of the following models:
+  - 🆓 **GPT-OSS 20B** (Modal.com) - **FREE!** ✅ **DEFAULT MODEL** - (⚠️ may take up to 60s to start responding)
+  - **Claude 4.5 Sonnet** (Anthropic) - `ANTHROPIC_API_KEY` required - Faster & more precise
+  - **Claude Opus 4** (Anthropic) - `ANTHROPIC_API_KEY` required - Faster & more precise
+  - **GPT-5** (OpenAI) - `OPENAI_API_KEY` required - Faster & more precise
+  - **Grok 4.1** (xAI) - `XAI_API_KEY` required - Faster & more precise
+  - **Gemini 3 Pro** (Google) - `GOOGLE_GENERATIVE_AI_API_KEY` required - Faster & more precise
+
+### 🆓 Free Default Model: GPT-OSS via Modal.com
+
+**GPT-OSS 20B is the default model** - no API key required! The agent automatically uses GPT-OSS unless you select a different model in the UI.
+
+| Feature           | Details                                        |
+| ----------------- | ---------------------------------------------- |
+| **Model**         | OpenAI GPT-OSS 20B (open-source)               |
+| **Cost**          | **FREE** (first $30/month on Modal)            |
+| **Setup**         | Just provide Modal endpoint URL                |
+| **Performance**   | ~$0.76/hr when running (A10G GPU)              |
+| **Response Time** | ⚠️ **May take up to 60s to start** (cold start) |
+| **Default**       | ✅ **YES** - Automatically selected             |
+
+> ⚠️ **Important:** GPT-OSS may take up to **60 seconds** to start responding due to Modal.com's cold start behavior. For **faster responses and better precision**, select another model (Claude, GPT-5, Gemini, or Grok) and provide your API key in the Gradio UI.
+
+See [modal/README.md](../../modal/README.md) for detailed deployment instructions and GPU options.
+
+### Installation
+
+1. **Install Node.js dependencies**:
+```bash
+pnpm install
+```
+
+2. **Install uv and Python dependencies**:
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install Python dependencies
+uv pip install -r requirements.txt
+```
+
+3. **Set up environment variables**:
+```bash
+cp .env.example .env
+# Edit .env and add:
+# - MODAL_ENDPOINT_URL (for FREE GPT-OSS - DEFAULT MODEL) - Deploy via: cd modal && modal deploy gpt_oss_inference.py
+# - TAVILY_API_KEY (optional) - Get from https://app.tavily.com for enhanced web research
+# - Model API key (optional - only if not using GPT-OSS):
+#   * ANTHROPIC_API_KEY (for Claude 4.5 or Claude Opus)
+#   * OPENAI_API_KEY (for GPT-5)
+#   * XAI_API_KEY (for Grok 4.1)
+#   * GOOGLE_GENERATIVE_AI_API_KEY (for Gemini 3 Pro)
+```
+
+> 💡 **Tip:** 
+> - **GPT-OSS is FREE and the default** - just set `MODAL_ENDPOINT_URL` after deploying to Modal.com
+> - API keys and Modal endpoint can also be entered directly in the Gradio UI
+> - Keys are securely stored in encrypted browser cookies and auto-expire after 24 hours
+> - Modal.com offers **$30/month free credit** - perfect for trying out GPT-OSS!
+
+### Running the Agent
+
+**Option 1: Run everything together** (recommended)
+```bash
+# Terminal 1: Start the Express API server
+pnpm dev
+
+# Terminal 2: Start the Gradio UI
+pnpm gradio
+```
+
+**Option 2: Manual start**
+```bash
+# Terminal 1: Start API server
+cd apps/eu-ai-act-agent
+pnpm dev
+
+# Terminal 2: Start Gradio
+cd apps/eu-ai-act-agent
+uv run src/gradio_app.py
+```
+
+The Gradio UI will be available at `http://localhost:7860` 🎉
+
+<a id="how-to-use-in-chatgpt"></a>
+
+## 🚀 How to Use in ChatGPT
+
+The MCP server can be deployed as a **ChatGPT App** (connector) to use EU AI Act compliance tools directly in ChatGPT conversations!
+
+**🌐 Pre-deployed MCP Server:** The MCP server is already deployed and available at [https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/](https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/) - you can use this URL directly as a ChatGPT connector!
+
+### Quick Start
+
+**Option A: Use the Pre-deployed Server** (Recommended)
+1. **Use the deployed MCP server** at [https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/](https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/)
+2. Skip to step 2 below to configure ChatGPT
+
+**Option B: Deploy Your Own**
+1. **Start the ChatGPT App** with `share=True`:
+   ```bash
+   cd apps/eu-ai-act-agent
+   uv run src/chatgpt_app.py
+   ```
+   
+   The app will automatically:
+   - Create a public URL (via Gradio's share feature)
+   - Enable MCP server mode
+   - Display the MCP server URL in the terminal
+
+2. **Enable Developer Mode in ChatGPT**:
+   - Go to **Settings** → **Apps & Connectors** → **Advanced settings**
+   - Enable **Developer Mode**
+
+3. **Create a Connector**:
+   - In ChatGPT, go to **Settings** → **Apps & Connectors**
+   - Click **Create Connector**
+   - Enter the MCP server URL:
+     - **Pre-deployed:** `https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space/`
+     - **Or your own:** The URL from the terminal (e.g., `https://xxxxx.gradio.live`)
+   - Name it `eu-ai-act` (or your preferred name)
+
+4. **Chat with ChatGPT using the connector**:
+   - In any ChatGPT conversation, type `@eu-ai-act` to activate the connector
+   - Ask questions like:
+     - `@eu-ai-act Analyze OpenAI's EU AI Act compliance status`
+     - `@eu-ai-act What risk category is a recruitment screening AI?`
+     - `@eu-ai-act Generate compliance documentation for our chatbot`
+
+### Available Tools in ChatGPT
+
+Once connected, you'll have access to all three MCP tools:
+
+- **`discover_organization`** 🏢 - Discover and profile organizations
+- **`discover_ai_services`** 🤖 - Inventory and classify AI systems
+- **`assess_compliance`** ⚖️ - AI-powered compliance assessment
+
+ChatGPT will automatically call these tools based on your conversation context!
+
+<a id="usage-examples"></a>
+
+## 📖 Usage Examples
+
+### Example 1: Organization Discovery
+```
+You: Analyze OpenAI's EU AI Act compliance status
+
+Agent: I'll help you assess OpenAI's compliance. Let me start by 
+       discovering their organization profile...
+       
+       [Discovering organization details...]
+       [Analyzing AI systems...]
+       [Assessing compliance gaps...]
+       
+       OpenAI operates as a Large Enterprise with Expert AI maturity.
+       They have 4 high-risk AI systems requiring conformity assessment...
+```
+
+### Example 2: AI System Classification
+```
+You: What risk category is a recruitment screening AI?
+
+Agent: Let me check the EU AI Act classification...
+       
+       A recruitment screening AI is classified as HIGH RISK per 
+       Annex III, Section 4(a) - AI systems used for recruitment.
+       
+       Requirements include:
+       - Conformity assessment (Article 43)
+       - Technical documentation (Article 11)
+       - CE marking (Article 48)
+       - EU database registration (Article 49)
+```
+
+### Example 3: Document Generation
+```
+You: Generate compliance documentation for our chatbot
+
+Agent: I'll assess your chatbot and generate the required documents...
+       
+       [Generated documents]:
+       ✓ Risk Management System (Article 9)
+       ✓ Technical Documentation (Article 11)
+       
+       Your chatbot is classified as Limited Risk. The documentation
+       templates are displayed in the chat and saved to the 
+       compliance-docs directory.
+```
+
+> ⚠️ **Note on Documentation Generation:** Currently, only **2 documentation templates** are generated:
+> - ⚡ **Risk Management System** (Article 9)
+> - 📋 **Technical Documentation** (Article 11 / Annex IV)
+>
+> Additional templates (Conformity Assessment, Transparency Notice, Quality Management System, etc.) are **planned but not yet implemented** to optimize API costs and response speed during the hackathon demo.
+
+<a id="configuration"></a>
+
+## 🔧 Configuration
+
+### API Server (`src/server.ts`)
+- **Port**: Configure via `PORT` env var (default: 3001)
+- **Model**: Select between 5 models via UI or `AI_MODEL` env var
+- **Streaming**: Enabled for real-time responses
+- **CORS**: Configured for Gradio origin
+- **Required Environment Variables**:
+  - `TAVILY_API_KEY` (required for web research)
+  - One of the following (based on model selection):
+    - `ANTHROPIC_API_KEY` (for Claude 4.5 or Claude Opus)
+    - `OPENAI_API_KEY` (for GPT-5)
+    - `XAI_API_KEY` (for Grok 4.1)
+    - `GOOGLE_GENERATIVE_AI_API_KEY` (for Gemini 3 Pro)
+
+### Gradio UI (`src/gradio_app.py`)
+- **Theme**: Custom EU-themed design
+- **Chat History**: Maintains full conversation context
+- **Model Selection**: Dropdown to select AI model in real-time
+- **Secure Key Storage**: API keys stored in encrypted browser cookies (24h expiry)
+- **Export**: Supports markdown and PDF export (optional)
+
+<a id="development"></a>
+
+## 🛠️ Development
+
+### Project Structure
+```
+apps/eu-ai-act-agent/
+├── src/
+│   ├── server.ts           # Express API + Vercel AI SDK agent
+│   ├── gradio_app.py       # Gradio web interface
+│   ├── agent/
+│   │   ├── index.ts        # Agent configuration
+│   │   ├── tools.ts        # MCP tool adapters
+│   │   └── prompts.ts      # System prompts
+│   └── types/
+│       └── index.ts        # TypeScript types
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Building for Production
+```bash
+# Build the Node.js server
+pnpm build
+
+# Start production server
+pnpm start
+```
+
+<a id="api-reference"></a>
+
+## 📚 API Reference
+
+### POST `/api/chat`
+Send a chat message to the AI agent.
+
+**Request:**
+```json
+{
+  "message": "Analyze my organization",
+  "history": []
+}
+```
+
+**Response (Stream):**
+```
+data: {"type":"text","content":"Let me analyze..."}
+data: {"type":"tool_call","tool":"discover_organization"}
+data: {"type":"result","data":{...}}
+```
+
+<a id="testing"></a>
+
+## 🧪 Testing
+
+Test the agent with sample queries:
+```bash
+curl -X POST http://localhost:3001/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"What is the EU AI Act?"}'
+```
+
+<a id="tech-stack"></a>
+
+## 🎯 Tech Stack
+
+- **Backend**: Node.js + Express + TypeScript
+- **AI SDK**: Vercel AI SDK v5 (upgraded from v4)
+- **LLM**: 6 models supported (user selectable via UI):
+  - 🆓 **GPT-OSS 20B** (Modal.com) - **FREE!** ✅ **DEFAULT MODEL** - No API key required! (⚠️ may take up to 60s to start)
+  - Claude 4.5 Sonnet & Claude Opus 4 (Anthropic) - Faster & more precise
+  - GPT-5 (OpenAI) - Faster & more precise
+  - Grok 4.1 (xAI) - Faster & more precise
+  - Gemini 3 Pro (Google) - Faster & more precise
+- **Free LLM Hosting**: [Modal.com](https://modal.com) for GPT-OSS deployment
+- **Research**: Tavily AI for web research (optional)
+- **Frontend**: Gradio (Python)
+- **Security**: Encrypted cookie storage for API keys (24h expiry)
+- **MCP**: Model Context Protocol for tool integration
+- **Monorepo**: Turborepo for efficient builds
+
+
+<div align="center">
+
+**Built for the MCP 1st Birthday Hackathon** 🎂
+
+Making EU AI Act compliance accessible through conversational AI
+
+</div>
+

apps/eu-ai-act-agent/biome.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": []
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": false
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  }
+}

apps/eu-ai-act-agent/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@eu-ai-act/agent",
+  "version": "0.1.0",
+  "description": "EU AI Act Compliance Agent with Gradio UI and Vercel AI SDK v5",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsup",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "gradio": "uv run src/gradio_app.py",
+    "chatgpt-app": "uv run src/chatgpt_app.py"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^2.0.50",
+    "@ai-sdk/google": "3.0.0-beta.62",
+    "@ai-sdk/mcp": "^0.0.11",
+    "@ai-sdk/openai": "^2.0.74",
+    "@ai-sdk/provider-utils": "^2.2.8",
+    "@ai-sdk/xai": "^2.0.39",
+    "@eu-ai-act/mcp-server": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "ai": "^5.0.104",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^4.21.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.5",
+    "@types/node": "^22.10.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "eu-ai-act",
+    "compliance",
+    "ai-agent",
+    "gradio",
+    "vercel-ai-sdk"
+  ]
+}

apps/eu-ai-act-agent/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "eu-ai-act-agent"
+version = "0.1.0"
+description = "EU AI Act Compliance Agent with Gradio UI"
+requires-python = ">=3.10"
+dependencies = [
+    "gradio[mcp]>=6.0.0",
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+gradio = "gradio_app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.uv]
+dev-dependencies = []
+

apps/eu-ai-act-agent/requirements.txt

@@ -0,0 +1,7 @@
+# EU AI Act Compliance Agent - Python Dependencies
+# Gradio UI requirements
+
+gradio[mcp]>=6.0.0
+requests>=2.31.0
+python-dotenv>=1.0.0
+

apps/eu-ai-act-agent/src/.mcp_url

@@ -0,0 +1 @@
+https://c93e68e71ab8607092.gradio.live/gradio_api/mcp/

apps/eu-ai-act-agent/src/agent/index.ts

@@ -0,0 +1,819 @@
+/**
+ * EU AI Act Compliance Agent
+ * Vercel AI SDK v5 implementation with MCP tools
+ *
+ * Uses the AI SDK MCP client to connect to the EU AI Act MCP server
+ * and retrieve tools dynamically.
+ *
+ * IMPORTANT: API keys are passed directly from Gradio UI via request headers.
+ * NEVER read API keys from environment variables!
+ *
+ * Supported Models:
+ * - gpt-oss: OpenAI GPT-OSS 20B via Modal.com (FREE - no API key needed!) - DEFAULT
+ * - claude-4.5: Anthropic Claude Sonnet 4.5 (user provides API key)
+ * - claude-opus: Anthropic Claude Opus 4 (user provides API key)
+ * - gpt-5: OpenAI GPT-5 (user provides API key)
+ * - grok-4-1: xAI Grok 4.1 Fast Reasoning (user provides API key)
+ * - gemini-3: Google Gemini 3 Pro (user provides API key)
+ */
+
+import { generateText, stepCountIs, streamText } from "ai";
+import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport as StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { SYSTEM_PROMPT } from "./prompts.js";
+import { getModel, type ApiKeys } from "@eu-ai-act/mcp-server";
+
+// Re-export ApiKeys type for server.ts
+export type { ApiKeys };
+
+/**
+ * Agent configuration passed from server
+ */
+export interface AgentConfig {
+	modelName: string;
+	apiKeys: ApiKeys;
+	tavilyApiKey?: string;
+}
+
+/**
+ * Get the system prompt for the agent
+ */
+function getSystemPrompt(): string {
+	return SYSTEM_PROMPT;
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get path to the MCP server
+ *
+ * In production (Docker/HF Spaces): Use MCP_SERVER_PATH env var
+ * In development (tsx watch): Calculate relative path from source
+ * In local production (node dist/server.js): Calculate relative path from dist
+ */
+function getMCPServerPath(): string {
+	// 1. Use environment variable if set (for Docker/production deployments)
+	if (process.env.MCP_SERVER_PATH) {
+		console.log(
+			`[Agent] Using MCP_SERVER_PATH from env: ${process.env.MCP_SERVER_PATH}`,
+		);
+		return process.env.MCP_SERVER_PATH;
+	}
+
+	// 2. Calculate relative path based on whether we're running from dist or src
+	// - From src/agent/index.ts: need to go up 4 levels (agent -> src -> eu-ai-act-agent -> apps -> root)
+	// - From dist/server.js: need to go up 3 levels (dist -> eu-ai-act-agent -> apps -> root)
+	const isRunningFromDist =
+		__dirname.includes("/dist") || __dirname.endsWith("/dist");
+	const levelsUp = isRunningFromDist ? "../../../" : "../../../../";
+	const relativePath = resolve(
+		__dirname,
+		levelsUp,
+		"packages/eu-ai-act-mcp/dist/index.js",
+	);
+
+	console.log(
+		`[Agent] MCP server path (${isRunningFromDist ? "dist" : "src"}): ${relativePath}`,
+	);
+	return relativePath;
+}
+
+// Path to the built MCP server
+const MCP_SERVER_PATH = getMCPServerPath();
+
+/**
+ * HIGH-RISK KEYWORDS based on EU AI Act Annex III
+ * Source: https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=OJ:L_202401689
+ */
+const HIGH_RISK_KEYWORDS = [
+	// Annex III Point 8(a) - Administration of justice (LEGAL AI)
+	"legal",
+	"law",
+	"lawyer",
+	"attorney",
+	"judicial",
+	"justice",
+	"court",
+	"litigation",
+	"contract",
+	"compliance",
+	"regulatory",
+	"statute",
+	"legal advice",
+	"legal consulting",
+	"legal assistant",
+	"legal research",
+	"dispute resolution",
+	"arbitration",
+	"mediation",
+	// Annex III Point 4 - Employment
+	"recruitment",
+	"hiring",
+	"hr",
+	"human resources",
+	"employee",
+	"workforce",
+	"resume",
+	"cv",
+	"candidate",
+	"job application",
+	"termination",
+	// Annex III Point 5 - Essential services
+	"credit",
+	"scoring",
+	"loan",
+	"insurance",
+	"financial risk",
+	"creditworthiness",
+	"emergency services",
+	// Annex III Point 1 - Biometrics
+	"biometric",
+	"facial recognition",
+	"face recognition",
+	"fingerprint",
+	"identity verification",
+	"remote identification",
+	// Annex III Point 3 - Education
+	"education",
+	"student",
+	"academic",
+	"exam",
+	"grading",
+	"admission",
+	// Annex III Point 6 - Law enforcement
+	"law enforcement",
+	"police",
+	"crime",
+	"profiling",
+	"polygraph",
+	// Annex III Point 2 - Critical infrastructure
+	"critical infrastructure",
+	"safety component",
+	"water supply",
+	"gas supply",
+	"electricity",
+	"transport",
+	// Annex III Point 5(b) - Healthcare
+	"healthcare",
+	"medical",
+	"diagnosis",
+	"clinical",
+	"patient",
+	"health",
+];
+
+/**
+ * Validate risk classification for a system based on EU AI Act Annex III
+ * Ensures legal AI systems are correctly classified as HIGH RISK per Point 8(a)
+ */
+function validateSystemRiskClassification(system: any): any {
+	if (!system) return system;
+
+	const name = (system.system?.name || system.name || "").toLowerCase();
+	const description = (
+		system.system?.description ||
+		system.description ||
+		""
+	).toLowerCase();
+	const purpose = (
+		system.system?.intendedPurpose ||
+		system.intendedPurpose ||
+		""
+	).toLowerCase();
+	const contextString = `${name} ${description} ${purpose}`;
+
+	// Check for legal AI indicators (Annex III Point 8(a))
+	const isLegalAI =
+		contextString.includes("legal") ||
+		contextString.includes("law") ||
+		contextString.includes("lawyer") ||
+		contextString.includes("attorney") ||
+		contextString.includes("judicial") ||
+		contextString.includes("justice") ||
+		contextString.includes("court") ||
+		contextString.includes("litigation") ||
+		contextString.includes("contract review") ||
+		contextString.includes("compliance advi") ||
+		contextString.includes("regulatory advi");
+
+	// Check for other high-risk keywords
+	const matchedHighRiskKeywords = HIGH_RISK_KEYWORDS.filter((keyword) =>
+		contextString.includes(keyword.toLowerCase()),
+	);
+	const hasHighRiskKeywords = matchedHighRiskKeywords.length > 0;
+
+	const rc = system.riskClassification || {};
+	let needsCorrection = false;
+
+	if (isLegalAI && rc.category !== "High" && rc.category !== "Unacceptable") {
+		console.log(
+			`⚠️  [Agent Risk Validation] Legal AI detected - correcting "${rc.category}" to "High"`,
+		);
+		console.log(`   System: ${name}`);
+		console.log(
+			`   Reason: Legal AI per EU AI Act Annex III Point 8(a) - Administration of justice`,
+		);
+		rc.category = "High";
+		rc.annexIIICategory =
+			"Annex III, Point 8(a) - Administration of justice and democratic processes";
+		rc.justification =
+			"AI system providing legal assistance, consulting, or advice. Per EU AI Act Annex III Point 8(a), such systems are HIGH RISK.";
+		rc.riskScore = Math.max(rc.riskScore || 0, 85);
+		rc.conformityAssessmentRequired = true;
+		rc.conformityAssessmentType = "Internal Control";
+		needsCorrection = true;
+	} else if (
+		hasHighRiskKeywords &&
+		rc.category !== "High" &&
+		rc.category !== "Unacceptable"
+	) {
+		console.log(
+			`⚠️  [Agent Risk Validation] High-risk keywords detected - correcting "${rc.category}" to "High"`,
+		);
+		console.log(`   System: ${name}`);
+		console.log(
+			`   Keywords: ${matchedHighRiskKeywords.slice(0, 3).join(", ")}`,
+		);
+		rc.category = "High";
+		rc.riskScore = Math.max(rc.riskScore || 0, 75);
+		rc.conformityAssessmentRequired = true;
+		rc.conformityAssessmentType = "Internal Control";
+		needsCorrection = true;
+	}
+
+	if (needsCorrection) {
+		return {
+			...system,
+			riskClassification: rc,
+		};
+	}
+
+	return system;
+}
+
+/**
+ * Validate all systems in assess_compliance or discover_ai_services results
+ */
+function validateToolResult(toolName: string, result: any): any {
+	if (!result) return result;
+
+	if (toolName === "assess_compliance" || toolName === "discover_ai_services") {
+		// Check if result has systems array
+		if (result.systems && Array.isArray(result.systems)) {
+			result.systems = result.systems.map((s: any) =>
+				validateSystemRiskClassification(s),
+			);
+
+			// Recalculate risk summary
+			if (result.riskSummary) {
+				result.riskSummary = {
+					...result.riskSummary,
+					highRiskCount: result.systems.filter(
+						(s: any) => s.riskClassification?.category === "High",
+					).length,
+					limitedRiskCount: result.systems.filter(
+						(s: any) => s.riskClassification?.category === "Limited",
+					).length,
+					minimalRiskCount: result.systems.filter(
+						(s: any) => s.riskClassification?.category === "Minimal",
+					).length,
+					unacceptableRiskCount: result.systems.filter(
+						(s: any) => s.riskClassification?.category === "Unacceptable",
+					).length,
+				};
+			}
+		}
+
+		// Check assessment for gaps related to legal systems
+		if (result.assessment?.gaps) {
+			// Ensure legal AI systems have appropriate gaps flagged
+		}
+	}
+
+	return result;
+}
+
+// getModel is now imported from @eu-ai-act/mcp-server
+
+/**
+ * Create MCP client and retrieve tools
+ * Passes API keys to the MCP server for tool execution
+ */
+async function createMCPClientWithTools(
+	apiKeys: ApiKeys,
+	modelName: string,
+	tavilyApiKey?: string,
+) {
+	// Pass API keys to MCP server child process via environment
+	// MCP tools need these for Tavily research and AI model calls
+	// IMPORTANT: These come from Gradio UI user input - NEVER from process.env!
+	const env: Record<string, string> = {
+		// Only pass MCP_SERVER_PATH and NODE_ENV, plus API keys
+		NODE_ENV: process.env.NODE_ENV || "production",
+	};
+
+	// Pass MCP server path if set
+	if (process.env.MCP_SERVER_PATH) {
+		env.MCP_SERVER_PATH = process.env.MCP_SERVER_PATH;
+	}
+
+	// Pass model name from Gradio UI
+	env.AI_MODEL = modelName;
+
+	// Pass Tavily API key: User-provided (from Gradio UI) takes priority,
+	// otherwise fallback to server's env var (HF Spaces secret)
+	if (tavilyApiKey) {
+		env.TAVILY_API_KEY = tavilyApiKey;
+		console.log("[Agent] Using Tavily API key from Gradio UI (user-provided)");
+	} else if (process.env.TAVILY_API_KEY) {
+		// Fallback to server's TAVILY_API_KEY (HF Spaces secret)
+		env.TAVILY_API_KEY = process.env.TAVILY_API_KEY;
+		console.log(
+			"[Agent] Using Tavily API key from server env (HF Spaces secret)",
+		);
+	} else {
+		console.log(
+			"[Agent] No Tavily API key available - will use AI model fallback for research",
+		);
+	}
+
+	// Pass API keys from user (via Gradio UI) to MCP server
+	// These are used by MCP tools for Tavily research and AI model calls
+	if (apiKeys.openaiApiKey) env.OPENAI_API_KEY = apiKeys.openaiApiKey;
+	if (apiKeys.anthropicApiKey) env.ANTHROPIC_API_KEY = apiKeys.anthropicApiKey;
+	if (apiKeys.googleApiKey)
+		env.GOOGLE_GENERATIVE_AI_API_KEY = apiKeys.googleApiKey;
+	if (apiKeys.xaiApiKey) env.XAI_API_KEY = apiKeys.xaiApiKey;
+	if (apiKeys.modalEndpointUrl)
+		env.MODAL_ENDPOINT_URL = apiKeys.modalEndpointUrl;
+
+	const transport = new StdioMCPTransport({
+		command: "node",
+		args: [MCP_SERVER_PATH],
+		env,
+	});
+
+	const client = await createMCPClient({ transport });
+	const tools = await client.tools();
+
+	console.log("[Agent] MCP client created");
+
+	return { client, tools };
+}
+
+/**
+ * Create EU AI Act compliance agent
+ *
+ * @param config - Agent configuration with model name and API keys from Gradio UI
+ */
+export function createAgent(config: AgentConfig) {
+	const { modelName, apiKeys, tavilyApiKey } = config;
+
+	// Log the model being used
+	console.log(`[Agent] Creating agent with model: ${modelName}`);
+	const model = getModel(modelName, apiKeys, "agent");
+	console.log(`[Agent] Model instance created: ${model.constructor.name}`);
+	return {
+		/**
+		 * Generate a single response
+		 */
+		async generateText(params: { messages: any[] }) {
+			const { client, tools } = await createMCPClientWithTools(
+				apiKeys,
+				modelName,
+				tavilyApiKey,
+			);
+
+			try {
+				const systemPrompt = getSystemPrompt();
+				const isGptOss = modelName.toLowerCase().includes("gpt-oss");
+
+				// Build provider options based on model
+				// GPT-OSS (vLLM on Modal) doesn't support reasoningEffort parameter
+				const providerOptions = isGptOss
+					? undefined
+					: {
+							anthropic: {
+								thinking: { type: "enabled", budgetTokens: 2000 }, // Minimal thinking budget for Claude
+							},
+							openai: {
+								reasoningEffort: "low", // Low reasoning effort for GPT - faster responses
+							},
+							google: {
+								thinkingConfig: {
+									thinkingLevel: "low", // Low thinking for faster responses
+									includeThoughts: true,
+								},
+							},
+						};
+
+				const result = await generateText({
+					model,
+					messages: [
+						{ role: "system", content: systemPrompt },
+						...params.messages,
+					],
+					// MCP tools are compatible at runtime but have different TypeScript types
+					tools: tools as any,
+					// stop when at least three tools runned and response is generated
+					stopWhen: stepCountIs(3),
+					providerOptions,
+				});
+
+				// Output tool results with detailed information
+				if (result.steps) {
+					for (const step of result.steps) {
+						if (step.toolResults && step.toolResults.length > 0) {
+							for (const toolResult of step.toolResults) {
+								console.log(`\n📋 Tool Result: ${toolResult.toolName}`);
+								console.log("─".repeat(50));
+
+								try {
+									// Access result safely - TypedToolResult may have result in different property
+									const resultValue =
+										(toolResult as any).result ??
+										(toolResult as any).output ??
+										toolResult;
+									let parsed =
+										typeof resultValue === "string"
+											? JSON.parse(resultValue)
+											: resultValue;
+
+									// Validate and correct risk classifications per EU AI Act Annex III
+									parsed = validateToolResult(toolResult.toolName, parsed);
+
+									// Handle assess_compliance results specially to show documentation
+									if (toolResult.toolName === "assess_compliance" && parsed) {
+										if (parsed.assessment) {
+											console.log(
+												`📊 Compliance Score: ${parsed.assessment.overallScore}/100`,
+											);
+											console.log(
+												`⚠️  Risk Level: ${parsed.assessment.riskLevel}`,
+											);
+											console.log(
+												`🔍 Gaps Found: ${parsed.assessment.gaps?.length || 0}`,
+											);
+											console.log(
+												`💡 Recommendations: ${parsed.assessment.recommendations?.length || 0}`,
+											);
+										}
+
+										// Show documentation templates
+										if (parsed.documentation) {
+											console.log(`\n📄 Documentation Templates Generated:`);
+											const docs = parsed.documentation;
+											if (docs.riskManagementTemplate)
+												console.log("   ✓ Risk Management System (Article 9)");
+											if (docs.technicalDocumentation)
+												console.log(
+													"   ✓ Technical Documentation (Article 11)",
+												);
+											if (docs.conformityAssessment)
+												console.log("   ✓ Conformity Assessment (Article 43)");
+											if (docs.transparencyNotice)
+												console.log("   ✓ Transparency Notice (Article 50)");
+											if (docs.qualityManagementSystem)
+												console.log(
+													"   ✓ Quality Management System (Article 17)",
+												);
+											if (docs.humanOversightProcedure)
+												console.log(
+													"   ✓ Human Oversight Procedure (Article 14)",
+												);
+											if (docs.dataGovernancePolicy)
+												console.log("   ✓ Data Governance Policy (Article 10)");
+											if (docs.incidentReportingProcedure)
+												console.log("   ✓ Incident Reporting Procedure");
+										}
+
+										// Show documentation files
+										if (
+											parsed.metadata?.documentationFiles &&
+											parsed.metadata.documentationFiles.length > 0
+										) {
+											console.log(`\n💾 Documentation Files Saved:`);
+											for (const filePath of parsed.metadata
+												.documentationFiles) {
+												console.log(`   📄 ${filePath}`);
+											}
+										}
+
+										if (parsed.metadata) {
+											console.log(
+												`\n🤖 Model Used: ${parsed.metadata.modelUsed}`,
+											);
+										}
+									} else if (
+										toolResult.toolName === "discover_ai_services" &&
+										parsed
+									) {
+										// Validate systems in discovery results
+										if (parsed.riskSummary) {
+											console.log(
+												`🤖 Total Systems: ${parsed.riskSummary.totalCount}`,
+											);
+											console.log(
+												`   High-Risk: ${parsed.riskSummary.highRiskCount}`,
+											);
+											console.log(
+												`   Limited-Risk: ${parsed.riskSummary.limitedRiskCount}`,
+											);
+											console.log(
+												`   Minimal-Risk: ${parsed.riskSummary.minimalRiskCount}`,
+											);
+										}
+										// Show any legal AI systems detected
+										if (parsed.systems) {
+											const legalSystems = parsed.systems.filter((s: any) => {
+												const ctx =
+													`${s.system?.name || ""} ${s.system?.intendedPurpose || ""}`.toLowerCase();
+												return (
+													ctx.includes("legal") ||
+													ctx.includes("law") ||
+													ctx.includes("judicial")
+												);
+											});
+											if (legalSystems.length > 0) {
+												console.log(
+													`\n⚖️  Legal AI Systems (HIGH RISK per Annex III Point 8(a)):`,
+												);
+												for (const sys of legalSystems) {
+													console.log(
+														`   - ${sys.system?.name}: ${sys.riskClassification?.category}`,
+													);
+												}
+											}
+										}
+									} else if (
+										toolResult.toolName === "discover_organization" &&
+										parsed
+									) {
+										if (parsed.organization) {
+											console.log(
+												`🏢 Organization: ${parsed.organization.name}`,
+											);
+											console.log(`📍 Sector: ${parsed.organization.sector}`);
+											console.log(
+												`🌍 EU Presence: ${parsed.organization.euPresence}`,
+											);
+										}
+									}
+								} catch {
+									// If not JSON, just show raw result summary
+									const resultValue =
+										(toolResult as any).result ??
+										(toolResult as any).output ??
+										toolResult;
+									const resultStr = String(resultValue);
+									console.log(
+										`Result: ${resultStr.substring(0, 200)}${resultStr.length > 200 ? "..." : ""}`,
+									);
+								}
+
+								console.log("─".repeat(50));
+							}
+						}
+					}
+				}
+
+				return result;
+			} finally {
+				await client.close();
+			}
+		},
+
+		/**
+		 * Stream a response with MCP tools
+		 */
+		async streamText(params: { messages: any[] }) {
+			const { client, tools } = await createMCPClientWithTools(
+				apiKeys,
+				modelName,
+				tavilyApiKey,
+			);
+			const systemPrompt = getSystemPrompt();
+			const isGptOss = modelName.toLowerCase().includes("gpt-oss");
+
+			// Build provider options based on model
+			// GPT-OSS (vLLM on Modal) doesn't support reasoningEffort parameter
+			const providerOptions = isGptOss
+				? undefined
+				: {
+						anthropic: {
+							thinking: { type: "enabled", budgetTokens: 2000 }, // Minimal thinking budget for Claude
+						},
+						openai: {
+							reasoningEffort: "low", // Low reasoning effort for GPT - faster responses
+						},
+						google: {
+							thinkingConfig: {
+								thinkingLevel: "low", // Low thinking for faster responses
+								includeThoughts: true,
+							},
+						},
+					};
+
+			// For GPT-OSS (vLLM on Modal), we must set explicit maxOutputTokens
+			// The context window is 16k, and the system prompt + tools take ~6-8k tokens
+			// Setting explicit maxOutputTokens prevents vLLM from calculating negative values
+			// 8000 tokens allows for comprehensive compliance reports
+			const maxOutputTokens = isGptOss ? 8000 : undefined;
+
+			const result = streamText({
+				model,
+				maxOutputTokens,
+				messages: [
+					{ role: "system", content: systemPrompt },
+					...params.messages,
+				],
+				// MCP tools are compatible at runtime but have different TypeScript types
+				tools: tools as any,
+				// Increase maxSteps to ensure all 3 tools + final response
+				stopWhen: stepCountIs(3),
+				providerOptions,
+				// Log each step for debugging
+				onStepFinish: async (step) => {
+					// Output tool results with detailed information
+					if (step.toolResults && step.toolResults.length > 0) {
+						for (const toolResult of step.toolResults) {
+							console.log(`\n📋 Tool Result: ${toolResult.toolName}`);
+							console.log("─".repeat(50));
+
+							try {
+								// Access result safely - TypedToolResult may have result in different property
+								const resultValue =
+									(toolResult as any).result ??
+									(toolResult as any).output ??
+									toolResult;
+								let result =
+									typeof resultValue === "string"
+										? JSON.parse(resultValue)
+										: resultValue;
+
+								// Validate and correct risk classifications per EU AI Act Annex III
+								result = validateToolResult(toolResult.toolName, result);
+
+								// Handle assess_compliance results specially to show documentation
+								if (toolResult.toolName === "assess_compliance" && result) {
+									if (result.assessment) {
+										console.log(
+											`📊 Compliance Score: ${result.assessment.overallScore}/100`,
+										);
+										console.log(
+											`⚠️  Risk Level: ${result.assessment.riskLevel}`,
+										);
+										console.log(
+											`🔍 Gaps Found: ${result.assessment.gaps?.length || 0}`,
+										);
+										console.log(
+											`💡 Recommendations: ${result.assessment.recommendations?.length || 0}`,
+										);
+									}
+
+									// Show documentation templates
+									if (result.documentation) {
+										console.log(`\n📄 Documentation Templates Generated:`);
+										const docs = result.documentation;
+										if (docs.riskManagementTemplate)
+											console.log("   ✓ Risk Management System (Article 9)");
+										if (docs.technicalDocumentation)
+											console.log("   ✓ Technical Documentation (Article 11)");
+										if (docs.conformityAssessment)
+											console.log("   ✓ Conformity Assessment (Article 43)");
+										if (docs.transparencyNotice)
+											console.log("   ✓ Transparency Notice (Article 50)");
+										if (docs.qualityManagementSystem)
+											console.log(
+												"   ✓ Quality Management System (Article 17)",
+											);
+										if (docs.humanOversightProcedure)
+											console.log(
+												"   ✓ Human Oversight Procedure (Article 14)",
+											);
+										if (docs.dataGovernancePolicy)
+											console.log("   ✓ Data Governance Policy (Article 10)");
+										if (docs.incidentReportingProcedure)
+											console.log("   ✓ Incident Reporting Procedure");
+									}
+
+									// Show documentation files
+									if (
+										result.metadata?.documentationFiles &&
+										result.metadata.documentationFiles.length > 0
+									) {
+										console.log(`\n💾 Documentation Files Saved:`);
+										for (const filePath of result.metadata.documentationFiles) {
+											console.log(`   📄 ${filePath}`);
+										}
+									}
+
+									if (result.metadata) {
+										console.log(
+											`\n🤖 Model Used: ${result.metadata.modelUsed}`,
+										);
+									}
+								} else if (
+									toolResult.toolName === "discover_ai_services" &&
+									result
+								) {
+									// Validate systems in discovery results
+									if (result.riskSummary) {
+										console.log(
+											`🤖 Total Systems: ${result.riskSummary.totalCount}`,
+										);
+										console.log(
+											`   High-Risk: ${result.riskSummary.highRiskCount}`,
+										);
+										console.log(
+											`   Limited-Risk: ${result.riskSummary.limitedRiskCount}`,
+										);
+										console.log(
+											`   Minimal-Risk: ${result.riskSummary.minimalRiskCount}`,
+										);
+									}
+									// Show any legal AI systems detected
+									if (result.systems) {
+										const legalSystems = result.systems.filter((s: any) => {
+											const ctx =
+												`${s.system?.name || ""} ${s.system?.intendedPurpose || ""}`.toLowerCase();
+											return (
+												ctx.includes("legal") ||
+												ctx.includes("law") ||
+												ctx.includes("judicial")
+											);
+										});
+										if (legalSystems.length > 0) {
+											console.log(
+												`\n⚖️  Legal AI Systems (HIGH RISK per Annex III Point 8(a)):`,
+											);
+											for (const sys of legalSystems) {
+												console.log(
+													`   - ${sys.system?.name}: ${sys.riskClassification?.category}`,
+												);
+											}
+										}
+									}
+								} else if (
+									toolResult.toolName === "discover_organization" &&
+									result
+								) {
+									// Show organization discovery summary
+									if (result.organization) {
+										console.log(`🏢 Organization: ${result.organization.name}`);
+										console.log(`📍 Sector: ${result.organization.sector}`);
+										console.log(
+											`🌍 EU Presence: ${result.organization.euPresence}`,
+										);
+									}
+								}
+							} catch {
+								// If not JSON, just show raw result summary
+								const resultValue =
+									(toolResult as any).result ??
+									(toolResult as any).output ??
+									toolResult;
+								const resultStr = String(resultValue);
+								console.log(
+									`Result: ${resultStr.substring(0, 200)}${resultStr.length > 200 ? "..." : ""}`,
+								);
+							}
+
+							console.log("─".repeat(50));
+						}
+					}
+				},
+				onFinish: async () => {
+					console.log("\n[Agent] Stream finished, closing MCP client");
+					await client.close();
+				},
+				onError: async (error) => {
+					console.error("[Agent] Stream error:", error);
+					await client.close();
+				},
+			});
+
+			return result;
+		},
+
+		/**
+		 * Get available tools from MCP server
+		 */
+		async getTools() {
+			const { client, tools } = await createMCPClientWithTools(
+				apiKeys,
+				modelName,
+				tavilyApiKey,
+			);
+			const toolList = Object.entries(tools).map(([name, t]) => ({
+				name,
+				description: (t as any).description || "No description",
+			}));
+			await client.close();
+			return toolList;
+		},
+	};
+}

apps/eu-ai-act-agent/src/agent/prompts.ts

@@ -0,0 +1,533 @@
+/**
+ * System prompts for EU AI Act Compliance Agent
+ */
+
+export const SYSTEM_PROMPT = `You are an expert EU AI Act Compliance Assistant with deep knowledge of the European Union's AI Act (Regulation (EU) 2024/1689).
+
+## 🚨🚨🚨 ABSOLUTE REQUIREMENT: assess_compliance MUST ALWAYS RUN 🚨🚨🚨
+
+**THE assess_compliance TOOL IS MANDATORY.** You MUST ALWAYS call it when analyzing any organization.
+- It generates the compliance report
+- It creates documentation files saved to disk
+- It provides the compliance score
+- WITHOUT IT, YOUR RESPONSE IS INCOMPLETE AND USELESS
+
+**FAILURE TO RUN assess_compliance = FAILURE TO COMPLETE THE TASK**
+
+## ⚠️ SIMPLE RULE: IF USER ASKS FOR ANY OF THESE → CALL ALL 3 TOOLS ⚠️
+
+**IMMEDIATELY CALL TOOLS if user message contains ANY of these:**
+- "compliance" + any organization or system name
+- "generate" + "documentation" or "report"
+- "risk management" + "documentation"
+- "system compliance"
+- "assess" or "analyze" + company name
+- "EU AI Act" + company/product name
+- Any AI product name (ChatGPT, watsonX, Copilot, Claude, Gemini, etc.)
+
+**DO NOT just respond with text. CALL THE TOOLS FIRST!**
+
+## CRITICAL: When to Use Tools vs. Direct Answers
+
+**ANSWER DIRECTLY (NO TOOLS) for:**
+- General questions about the EU AI Act ("What is the EU AI Act?")
+- Questions about specific Articles ("What does Article 6 say?")
+- Risk category explanations ("What are the risk categories?")
+- Timeline questions ("When does the Act take effect?")
+- Generic compliance questions ("What are high-risk AI requirements?")
+- Any question that does NOT mention a SPECIFIC organization name
+
+**USE ALL THREE TOOLS when:**
+- User explicitly names a SPECIFIC organization (e.g., "Analyze Microsoft's compliance")
+- User asks for compliance analysis OF a specific company
+- User wants organization profiling for a named company
+- User asks for documentation or reports for a company
+- User mentions a specific AI system/product by name (e.g., "ChatGPT", "watsonX", "Copilot", "Claude")
+- User asks for "compliance report" or "compliance assessment"
+- User asks to "generate risk management documentation"
+- User asks for "system compliance" analysis
+- User mentions "EU AI Act compliance" for a company or system
+- User asks for "technical documentation" generation
+- User asks for "gap analysis" for a company
+
+**TRIGGER PHRASES that ALWAYS require tools:**
+- "compliance for [organization/system]"
+- "generate documentation"
+- "risk management documentation"
+- "system compliance"
+- "compliance report"
+- "assess [organization]"
+- "analyze [organization]"
+- "[organization] AI Act compliance"
+
+If no specific organization AND no specific AI system is mentioned, ALWAYS respond directly using your knowledge.
+
+**EXAMPLES of messages that REQUIRE TOOLS (call all 3 tools):**
+- "Generate compliance for IBM watsonX" → CALL TOOLS
+- "Assess OpenAI's ChatGPT compliance" → CALL TOOLS  
+- "System compliance and generate risk management documentation for Microsoft" → CALL TOOLS
+- "EU AI Act compliance report for Google Gemini" → CALL TOOLS
+- "Generate risk management documentation for Anthropic Claude" → CALL TOOLS
+- "Analyze Meta's AI systems" → CALL TOOLS
+
+**EXAMPLES of messages that DO NOT require tools (answer directly):**
+- "What is the EU AI Act?" → Answer directly
+- "What are the risk categories?" → Answer directly
+- "When does Article 5 take effect?" → Answer directly
+
+## 🔴 MANDATORY 3-TOOL WORKFLOW - NO EXCEPTIONS 🔴
+
+When analyzing a specific organization, you MUST complete ALL THREE steps:
+
+**STEP 1**: discover_organization → Get organization profile
+**STEP 2**: discover_ai_services → Discover AI systems  
+**STEP 3**: assess_compliance → **MANDATORY** Generate compliance report & documentation
+
+### 🚨 assess_compliance IS NOT OPTIONAL 🚨
+
+After Steps 1 and 2, you MUST IMMEDIATELY call assess_compliance. DO NOT:
+- ❌ Skip it
+- ❌ Summarize without it
+- ❌ Say you have enough information
+- ❌ Respond to the user before calling it
+
+**STEP 1**: Call discover_organization ONCE with the organization name
+  - This retrieves the organization profile, sector, EU presence, etc.
+  - For well-known companies, ALWAYS provide the domain parameter with the correct website:
+    - Microsoft → domain: "microsoft.com"
+    - IBM → domain: "ibm.com"
+    - Google → domain: "google.com"
+    - OpenAI → domain: "openai.com"
+    - Meta → domain: "meta.com"
+    - Amazon → domain: "amazon.com"
+    - Apple → domain: "apple.com"
+    - Anthropic → domain: "anthropic.com"
+    - SAP → domain: "sap.com"
+    - Oracle → domain: "oracle.com"
+    - Salesforce → domain: "salesforce.com"
+  - ❌ DO NOT call discover_organization again
+
+**STEP 2**: Call discover_ai_services ONCE (NEVER SKIP!)
+  - This discovers and analyzes the organization's AI systems
+  - Pass organizationContext from Step 1
+  - If user mentioned specific systems (e.g., "watsonX", "ChatGPT", "Copilot"), pass them as systemNames array
+  - If no specific systems mentioned, call WITHOUT systemNames to discover ALL AI systems
+  - ❌ DO NOT call discover_ai_services again
+
+**STEP 3**: Call assess_compliance ONCE - ⚠️ THIS IS MANDATORY ⚠️
+  - This generates the compliance report, gap analysis, and documentation templates
+  - This SAVES DOCUMENTATION FILES TO DISK that you MUST report to the user
+  - Pass BOTH organizationContext AND aiServicesContext from previous steps
+  - Set generateDocumentation: true
+  - ❌ DO NOT call assess_compliance again
+  - ❌ DO NOT SKIP THIS STEP UNDER ANY CIRCUMSTANCES
+
+### 🔴 CRITICAL RULES - READ CAREFULLY 🔴
+
+✅ Call each tool EXACTLY ONCE - no duplicates!
+✅ **ALWAYS call assess_compliance** - it's the whole point of the analysis!
+❌ **NEVER call the same tool twice** - you already have the results!
+❌ **NEVER skip discover_ai_services** - Without it, you have no AI systems to assess!
+❌ **NEVER skip assess_compliance** - Without it, you have NO compliance report and NO documentation!
+❌ **NEVER go directly from discover_organization to assess_compliance** - You need AI systems first!
+❌ **NEVER respond to user after only 2 tools** - You MUST call all 3!
+
+### Call assess_compliance with FULL Context
+
+After discover_organization and discover_ai_services complete, YOU MUST call assess_compliance with:
+- organizationContext: Pass the COMPLETE JSON result from discover_organization (the full OrganizationProfile object with organization, regulatoryContext, and metadata fields)
+- aiServicesContext: Pass the COMPLETE JSON result from discover_ai_services (the full AISystemsDiscoveryResponse object with systems array, riskSummary, complianceSummary, etc.)
+- generateDocumentation: true (ALWAYS TRUE!)
+
+⚠️ **DO NOT SIMPLIFY THE CONTEXT** - Pass the ENTIRE JSON objects from the previous tool calls, not just summaries or excerpts. The assess_compliance tool needs ALL the data to generate accurate compliance reports.
+
+The assess_compliance tool is what generates the actual compliance score, gap analysis, and documentation templates. Without the FULL context from BOTH previous tools, it cannot provide accurate analysis.
+
+❌ **NEVER stop after just discover_organization**
+❌ **NEVER stop after just discover_organization and discover_ai_services**
+❌ **NEVER say "No response generated" - always call all tools first**
+❌ **NEVER provide a final response until assess_compliance has been called and returned**
+
+✅ After all 3 tools complete, provide a human-readable summary that INCLUDES the documentation file paths
+
+## EU AI Act Key Concepts
+
+**Risk Categories (Article 6)**:
+- **Unacceptable Risk**: Prohibited AI systems (Article 5)
+- **High Risk**: Subject to strict requirements (Annex III)
+- **Limited Risk**: Transparency obligations (Article 50)
+- **Minimal Risk**: No specific obligations
+
+**Key Articles**:
+- Article 5: Prohibited AI practices
+- Article 6: Classification rules for high-risk AI
+- Article 9: Risk management system
+- Article 10: Data governance
+- Article 11: Technical documentation
+- Article 14: Human oversight
+- Article 16: Provider obligations
+- Article 43: Conformity assessment
+- Article 47-48: CE marking
+- Article 49: EU database registration
+- Article 50: Transparency for limited-risk AI
+
+**Timeline**:
+- February 2, 2025: Prohibited AI bans take effect
+- August 2, 2026: High-risk AI obligations begin
+- August 2, 2027: Full enforcement
+
+---
+
+## 📋 Article 6: Classification Rules for High-Risk AI Systems (CRITICAL)
+
+Reference: https://artificialintelligenceact.eu/article/6/
+
+### Two Pathways to High-Risk Classification
+
+**Pathway 1: Safety Components (Article 6(1))**
+An AI system is HIGH-RISK when BOTH conditions are met:
+- (a) The AI system is intended to be used as a **safety component of a product**, OR the AI system **is itself a product**, covered by Union harmonisation legislation listed in Annex I
+- (b) The product requires **third-party conformity assessment** for placing on the market or putting into service
+
+**Pathway 2: Annex III Categories (Article 6(2))**
+AI systems listed in Annex III are automatically considered HIGH-RISK (see categories below).
+
+### 🚨 Derogation: When Annex III Systems Are NOT High-Risk (Article 6(3))
+
+An AI system in Annex III is **NOT high-risk** if it does NOT pose a significant risk of harm to health, safety, or fundamental rights AND meets **at least ONE** of these conditions:
+
+- **(a) Narrow Procedural Task**: The AI system performs a narrow procedural task only
+- **(b) Human Activity Improvement**: The AI system improves the result of a previously completed human activity
+- **(c) Pattern Detection Without Replacement**: The AI system detects decision-making patterns or deviations from prior patterns and is NOT meant to replace or influence the previously completed human assessment without proper human review
+- **(d) Preparatory Task**: The AI system performs a preparatory task to an assessment relevant for Annex III use cases
+
+### ⚠️ PROFILING EXCEPTION - ALWAYS HIGH-RISK
+
+**CRITICAL RULE**: Notwithstanding the derogation above, an AI system referred to in Annex III shall **ALWAYS be considered HIGH-RISK** where the AI system performs **profiling of natural persons**.
+
+### Documentation Requirement (Article 6(4))
+
+A provider who considers that an AI system referred to in Annex III is NOT high-risk **MUST document their assessment** before that system is placed on the market or put into service. Such providers are subject to the registration obligation in Article 49(2). Upon request of national competent authorities, the provider shall provide the documentation of the assessment.
+
+---
+
+## 📋 High-Risk Categories (Annex III) - Detailed
+
+**1. Biometric Identification and Categorisation**
+- Remote biometric identification systems
+- AI systems for categorizing natural persons based on biometric data
+- Emotion recognition systems in workplace and education
+
+**2. Critical Infrastructure Management**
+- AI systems for managing road traffic, water, gas, heating, electricity supply
+- Safety components of critical infrastructure
+
+**3. Education and Vocational Training**
+- AI systems determining access to educational institutions
+- AI for evaluating learning outcomes
+- AI assessing appropriate level of education
+- AI monitoring prohibited behavior during tests
+
+**4. Employment, Workers Management and Access to Self-Employment**
+- AI for recruitment, screening, filtering applications
+- AI for making decisions affecting employment relationships
+- AI for task allocation, performance monitoring
+- AI for promotions, terminations
+
+**5. Access to and Enjoyment of Essential Private and Public Services**
+- AI systems evaluating creditworthiness (EXCEPT fraud detection)
+- AI for risk assessment in life/health insurance
+- AI assessing eligibility for public assistance benefits
+- AI for emergency services dispatch prioritization
+
+**6. Law Enforcement**
+- AI assessing risk of criminal offending/reoffending
+- AI for polygraphs and similar tools
+- AI for evaluating reliability of evidence
+- AI for profiling in criminal investigations
+
+**7. Migration, Asylum and Border Control Management**
+- AI for polygraphs and similar tools
+- AI assessing irregular migration risk
+- AI examining asylum/visa applications
+- AI for identifying persons
+
+**8. Administration of Justice and Democratic Processes**
+- **AI LEGAL ASSISTANTS ARE HIGH-RISK** ← ALWAYS CLASSIFY AS HIGH-RISK
+- AI systems assisting judicial authorities in researching/interpreting facts and law
+- AI systems applying the law to concrete facts
+- AI systems used in alternative dispute resolution
+- AI influencing outcome of elections/referendums
+
+### 🔴 CRITICAL: AI Legal Assistants Classification
+
+**AI Legal Assistants (e.g., legal research AI, contract analysis AI, legal document generation AI) are HIGH-RISK AI systems under Annex III, Category 8 - Administration of Justice and Democratic Processes.**
+
+When classifying AI legal assistants, ALWAYS apply:
+- **Risk Classification**: HIGH-RISK
+- **Annex III Category**: 8a - Administration of Justice
+- **Article Reference**: Article 6(2) and Annex III, Point 8(a)
+- **Requirements**: Full compliance with Articles 8-15 (risk management, data governance, technical documentation, human oversight, etc.)
+- **Conformity Assessment**: Required under Article 43
+
+Examples of HIGH-RISK legal AI systems:
+- Legal research assistants (researching/interpreting facts and law)
+- Contract analysis and review AI
+- Legal document drafting AI
+- Case outcome prediction AI
+- Due diligence AI tools
+- Legal chatbots providing legal advice
+- AI-powered discovery and e-discovery tools
+- Litigation analytics platforms
+
+**These systems CANNOT use the Article 6(3) derogation** if they:
+- Materially influence legal outcomes
+- Replace or substitute human legal judgment
+- Provide legal advice to natural persons
+- Are used in judicial or quasi-judicial proceedings
+
+---
+
+## Response Style
+
+- Be conversational and explain complex regulations simply
+- Always cite specific Articles when relevant
+- Provide actionable recommendations
+- For general questions, answer immediately without tools
+- Only use tools when analyzing a specific named organization
+
+## 🚨 CRITICAL: After ALL THREE Tools Complete - WRITE COMPLIANCE REPORT 🚨
+
+**ONLY after assess_compliance returns**, you MUST write a comprehensive compliance report based on the tool result.
+
+### 📋 MANDATORY: Use assess_compliance Result to Write Report
+
+The assess_compliance tool returns a structured result with:
+- \`assessment\`: Contains overallScore, riskLevel, gaps[], recommendations[]
+- \`documentation\`: Contains riskManagementTemplate and technicalDocumentation
+- \`reasoning\`: Contains the AI's reasoning for the assessment
+- \`metadata\`: Contains organizationAssessed, systemsAssessed[], documentationFiles[]
+
+**YOU MUST USE ALL OF THIS DATA TO WRITE YOUR COMPLIANCE REPORT!**
+
+### 📊 EU AI Act Compliance Report - REQUIRED STRUCTURE
+
+Write a comprehensive compliance report using this structure:
+
+---
+
+# 📊 EU AI Act Compliance Report
+
+## Executive Summary
+
+**Organization:** [Use metadata.organizationAssessed from assess_compliance result]
+**Assessment Date:** [Use metadata.assessmentDate]
+**Compliance Score:** [Use assessment.overallScore]/100
+**Overall Risk Level:** [Use assessment.riskLevel - CRITICAL/HIGH/MEDIUM/LOW]
+
+**Assessment Reasoning:** [Use reasoning field from assess_compliance result]
+
+---
+
+## 1. Organization Profile
+
+**Organization Information:**
+- Name: [From discover_organization result - organization.name]
+- Sector: [From discover_organization result - organization.sector]
+- Size: [From discover_organization result - organization.size]
+- EU Presence: [From discover_organization result - organization.euPresence - Yes/No]
+- Headquarters: [From discover_organization result - organization.headquarters.country, city]
+- Primary Role: [From discover_organization result - organization.primaryRole]
+
+**Regulatory Context:**
+- Applicable Frameworks: [From discover_organization result - regulatoryContext.applicableFrameworks]
+- AI Maturity Level: [From discover_organization result - organization.aiMaturityLevel]
+
+---
+
+## 2. AI Systems Analyzed
+
+**Total Systems Assessed:** [Use metadata.systemsAssessed.length from assess_compliance result]
+
+**Systems Evaluated:**
+[List ALL systems from metadata.systemsAssessed array. For each system, include:]
+- **System Name:** [Each system from metadata.systemsAssessed]
+- **Risk Classification:** [From aiServicesContext.systems - find matching system and use riskClassification.category]
+- **Annex III Category:** [From aiServicesContext.systems - riskClassification.annexIIICategory if High risk]
+- **Intended Purpose:** [From aiServicesContext.systems - system.intendedPurpose]
+
+[If user specified specific systems, highlight those. If all systems were discovered, list all.]
+
+---
+
+## 3. Compliance Assessment Results
+
+**Overall Compliance Score:** [Use assessment.overallScore]/100
+
+**Risk Level:** [Use assessment.riskLevel]
+- CRITICAL: Immediate action required
+- HIGH: Significant compliance gaps
+- MEDIUM: Moderate compliance issues
+- LOW: Minor compliance gaps
+
+**Assessment Model:** [Use metadata.modelUsed]
+
+---
+
+## 4. Critical Compliance Gaps
+
+[Use assessment.gaps array from assess_compliance result. List ALL gaps with full details:]
+
+For each gap in assessment.gaps:
+- **Gap ID:** [gap.id]
+- **Severity:** [gap.severity - CRITICAL/HIGH/MEDIUM/LOW]
+- **Category:** [gap.category]
+- **Description:** [gap.description]
+- **Affected Systems:** [gap.affectedSystems - list all systems]
+- **Article Reference:** [gap.articleReference]
+- **Current State:** [gap.currentState]
+- **Required State:** [gap.requiredState]
+- **Remediation Effort:** [gap.remediationEffort - L/M/H]
+- **Deadline:** [gap.deadline]
+
+**Total Gaps Identified:** [assessment.gaps.length]
+- Critical: [Count gaps with severity="CRITICAL"]
+- High: [Count gaps with severity="HIGH"]
+- Medium: [Count gaps with severity="MEDIUM"]
+- Low: [Count gaps with severity="LOW"]
+
+---
+
+## 5. Priority Recommendations
+
+[Use assessment.recommendations array from assess_compliance result. List ALL recommendations:]
+
+For each recommendation in assessment.recommendations:
+- **Priority:** [recommendation.priority] (1-10, where 10 is highest)
+- **Title:** [recommendation.title]
+- **Description:** [recommendation.description]
+- **Article Reference:** [recommendation.articleReference]
+- **Implementation Steps:**
+  [List each step from recommendation.implementationSteps array]
+- **Estimated Effort:** [recommendation.estimatedEffort]
+- **Expected Outcome:** [recommendation.expectedOutcome]
+- **Dependencies:** [recommendation.dependencies if any]
+
+---
+
+## 6. Key Compliance Deadlines
+
+Based on EU AI Act timeline:
+- **February 2, 2025:** Prohibited AI practices ban takes effect (Article 5)
+- **August 2, 2026:** High-risk AI system obligations begin (Article 113)
+- **August 2, 2027:** Full enforcement of all provisions
+
+**System-Specific Deadlines:**
+[Extract deadlines from gaps - gap.deadline for each critical/high priority gap]
+
+---
+
+## 7. Documentation Files Generated
+
+**📁 Compliance Documentation Saved:**
+
+The assess_compliance tool has generated and saved the following documentation files:
+
+[EXTRACT AND LIST ALL FILE PATHS from metadata.documentationFiles array]
+
+\`\`\`
+[List each file path from metadata.documentationFiles, one per line]
+\`\`\`
+
+**Documentation Contents:**
+- **Compliance Assessment Report:** [First file - usually 00_Compliance_Report.md]
+  - Contains executive summary, compliance score, gaps, and recommendations
+  
+- **Risk Management System:** [Second file - usually 01_Risk_Management.md]
+  - Article 9 compliance template for risk management system
+  - Includes risk identification, analysis, mitigation, and monitoring sections
+  
+- **Technical Documentation:** [Third file - usually 02_Technical_Docs.md]
+  - Article 11 / Annex IV compliance template
+  - Includes system description, data governance, performance metrics, human oversight
+
+**Next Steps:**
+1. Review all documentation files listed above
+2. Customize the templates with organization-specific details
+3. Complete the risk management system per Article 9
+4. Complete technical documentation per Article 11 and Annex IV
+5. Address critical gaps identified in this report
+6. Begin conformity assessment process (Article 43)
+
+---
+
+## 8. Conclusion
+
+[Write a brief conclusion summarizing:]
+- Overall compliance status
+- Most critical actions needed
+- Timeline for compliance
+- Key risks if not addressed
+
+---
+
+**Report Generated:** [Use metadata.assessmentDate]
+**Assessment Version:** [Use metadata.assessmentVersion]
+**Model Used:** [Use metadata.modelUsed]
+
+## 🔴 FINAL CHECKLIST - YOU MUST COMPLETE ALL 🔴
+
+Before writing your compliance report, verify:
+
+✅ **Tool 1 - discover_organization**: Called? Have result with organization profile?
+✅ **Tool 2 - discover_ai_services**: Called? Have result with systems array?
+✅ **Tool 3 - assess_compliance**: Called? Have result? ← **MANDATORY!**
+
+**After all 3 tools complete, verify you have:**
+
+✅ **From assess_compliance result:**
+  - assessment.overallScore
+  - assessment.riskLevel
+  - assessment.gaps[] (array of all gaps)
+  - assessment.recommendations[] (array of all recommendations)
+  - reasoning (assessment reasoning)
+  - metadata.organizationAssessed
+  - metadata.systemsAssessed[] (array of system names)
+  - metadata.documentationFiles[] (array of file paths) ← **MANDATORY!**
+
+✅ **From discover_organization result:**
+  - organization.name
+  - organization.sector
+  - organization.size
+  - organization.euPresence
+  - organization.headquarters
+  - organization.primaryRole
+  - organization.aiMaturityLevel
+  - regulatoryContext.applicableFrameworks
+
+✅ **From discover_ai_services result:**
+  - systems[] (array with riskClassification and system details for each)
+
+**WRITE YOUR COMPLIANCE REPORT:**
+✅ Use ALL data from assess_compliance result
+✅ Include organization information from discover_organization
+✅ Include systems information from discover_ai_services
+✅ List ALL gaps from assessment.gaps
+✅ List ALL recommendations from assessment.recommendations
+✅ Include ALL documentation file paths from metadata.documentationFiles
+✅ Include the systems the user asked about (from metadata.systemsAssessed)
+
+**IF assess_compliance WAS NOT CALLED → CALL IT NOW BEFORE RESPONDING!**
+**IF documentationFiles ARE NOT IN YOUR RESPONSE → ADD THEM NOW!**
+**IF YOU DON'T USE THE ASSESS_COMPLIANCE RESULT → YOU'RE NOT WRITING THE REPORT CORRECTLY!**
+
+⚠️ **NEVER say "No response generated"**
+⚠️ **NEVER skip assess_compliance**  
+⚠️ **NEVER omit the documentation file paths from your response**
+⚠️ **NEVER respond without completing all 3 tools**
+⚠️ **NEVER write a report without using the assess_compliance result data**
+⚠️ **NEVER omit the organization name or systems that were assessed**
+
+**Remember:** 
+- For GENERAL EU AI Act questions (no specific organization), answer directly without tools
+- For SPECIFIC organization analysis, you MUST write a full compliance report using the assess_compliance result`;

apps/eu-ai-act-agent/src/chatgpt_app.py

@@ -0,0 +1,1410 @@
+#!/usr/bin/env python3
+"""
+EU AI Act Compliance Agent - ChatGPT Apps Integration
+Exposes EU AI Act MCP tools as ChatGPT Apps using Gradio's MCP server capabilities
+
+Based on: https://www.gradio.app/guides/building-chatgpt-apps-with-gradio
+
+To use in ChatGPT:
+1. Run this with: python chatgpt_app.py
+2. Enable "developer mode" in ChatGPT Settings → Apps & Connectors → Advanced settings
+3. Create a new connector with the MCP server URL shown in terminal
+4. Use @eu-ai-act in ChatGPT to interact with the tools
+"""
+
+import gradio as gr
+import requests
+import json
+import os
+import threading
+import time
+from typing import Optional
+from dotenv import load_dotenv
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+
+# Load environment variables from root .env file
+ROOT_DIR = Path(__file__).parent.parent.parent.parent
+load_dotenv(ROOT_DIR / ".env")
+
+# API Configuration - connects to existing Node.js API server
+API_URL = os.getenv("API_URL", "http://localhost:3001")
+PUBLIC_URL = os.getenv("PUBLIC_URL", "")  # HF Spaces public URL (empty for local dev)
+API_TIMEOUT = 600  # seconds for internal API calls
+
+# MCP tool timeout - allow 2 minutes for long-running AI assessments
+# GPT-OSS model can take 1-2 minutes for complex compliance assessments
+CHATGPT_TOOL_TIMEOUT = 120  # seconds (2 minutes) for tool responses
+
+# Thread pool for async API calls with timeout handling
+_executor = ThreadPoolExecutor(max_workers=4)
+
+
+def call_api_with_timeout(endpoint: str, payload: dict, timeout: int = CHATGPT_TOOL_TIMEOUT) -> dict:
+    """
+    Call API with a timeout, returning partial/placeholder response if it takes too long.
+    This prevents ChatGPT from timing out and closing the connection.
+    """
+    result = {"_pending": True}
+    exception = {"error": None}
+    
+    def make_request():
+        try:
+            response = requests.post(
+                f"{API_URL}{endpoint}",
+                json=payload,
+                timeout=API_TIMEOUT,  # Internal timeout for the actual request
+                stream=False
+            )
+            if response.status_code == 200:
+                result.update(response.json())
+                result["_pending"] = False
+            else:
+                result.update({
+                    "error": True,
+                    "message": f"API returned status {response.status_code}",
+                    "details": response.text[:500],
+                    "_pending": False
+                })
+        except requests.exceptions.ConnectionError:
+            result.update({
+                "error": True,
+                "message": "Cannot connect to API server",
+                "_pending": False
+            })
+        except Exception as e:
+            exception["error"] = str(e)
+            result["_pending"] = False
+    
+    # Start the request in a thread
+    future = _executor.submit(make_request)
+    
+    try:
+        # Wait for the request to complete within timeout
+        future.result(timeout=timeout)
+        if exception["error"]:
+            return {"error": True, "message": exception["error"]}
+        return result
+    except FuturesTimeoutError:
+        # Request is still running but we need to return something to ChatGPT
+        # Return a "processing" response that the widget can handle
+        return {
+            "status": "processing",
+            "message": "🕐 Analysis in progress. This assessment requires complex AI analysis which takes longer than ChatGPT's timeout allows. Please try again in 1-2 minutes or use the direct Gradio interface for long-running assessments.",
+            "tip": "For faster results, try using a faster model (claude-4.5, gemini-3) instead of gpt-oss.",
+            "_timeout": True
+        }
+
+
+# ============================================================================
+# MCP TOOLS - Exposed to ChatGPT with OpenAI Apps SDK metadata
+# ============================================================================
+
+@gr.mcp.tool(
+    _meta={
+        "openai/outputTemplate": "ui://widget/organization.html",
+        "openai/resultCanProduceWidget": True,
+        "openai/widgetAccessible": True,
+    }
+)
+def discover_organization(organization_name: str, domain: Optional[str] = None, context: Optional[str] = None) -> dict:
+    """
+    Discover and profile an organization for EU AI Act compliance assessment.
+    
+    Implements EU AI Act Article 16 (Provider Obligations), Article 22 (Authorized Representatives),
+    and Article 49 (Registration Requirements). Uses Tavily AI-powered research to discover
+    organization details and regulatory context. Falls back to AI model when Tavily is not available.
+    
+    This tool researches an organization and creates a comprehensive profile including:
+    - Basic organization information (name, sector, size, location, jurisdiction)
+    - Contact information (email, phone, website) and branding
+    - Regulatory context and compliance deadlines per EU AI Act timeline
+    - AI maturity level assessment (Nascent, Developing, Mature, Leader)
+    - Existing certifications (ISO 27001, SOC 2, GDPR) and compliance status
+    - Quality and Risk Management System status
+    - Authorized representative requirements for non-EU organizations
+    
+    Key EU AI Act Deadlines:
+    - February 2, 2025: Prohibited AI practices ban (Article 5)
+    - August 2, 2025: GPAI model obligations (Article 53)
+    - August 2, 2027: Full AI Act enforcement for high-risk systems (Article 113)
+    
+    Parameters:
+        organization_name (str): Name of the organization to discover (required). Examples: 'IBM', 'Microsoft', 'OpenAI'
+        domain (str): Organization's domain (e.g., 'ibm.com'). Auto-discovered from known companies if not provided.
+        context (str): Additional context about the organization (e.g., 'focus on AI products', 'EU subsidiary')
+    
+    Returns:
+        dict: Organization profile with regulatory context including:
+            - organization: name, sector, size, headquarters, contact, branding, aiMaturityLevel
+            - regulatoryContext: applicableFrameworks, complianceDeadlines, certifications
+            - metadata: createdAt, lastUpdated, completenessScore, dataSource
+    """
+    return call_api_with_timeout(
+        "/api/tools/discover_organization",
+        {
+            "organizationName": organization_name,
+            "domain": domain,
+            "context": context
+        },
+        timeout=CHATGPT_TOOL_TIMEOUT
+    )
+
+
+@gr.mcp.tool(
+    _meta={
+        "openai/outputTemplate": "ui://widget/ai-services.html",
+        "openai/resultCanProduceWidget": True,
+        "openai/widgetAccessible": True,
+    }
+)
+def discover_ai_services(
+    organization_context: Optional[dict] = None,
+    system_names: Optional[list] = None,
+    scope: Optional[str] = None,
+    context: Optional[str] = None
+) -> dict:
+    """
+    Discover and classify AI systems within an organization per EU AI Act requirements.
+    
+    Implements EU AI Act Article 6 (Classification), Article 11 (Technical Documentation),
+    and Annex III (High-Risk AI Systems) requirements. Uses Tavily AI-powered research or
+    falls back to AI model for system discovery and risk classification.
+    
+    EU AI Act Research Integration:
+    - Regulation (EU) 2024/1689, Official Journal L 2024/1689, 12.7.2024
+    - Annex III: High-Risk AI Systems Categories (employment, healthcare, credit, biometric, legal, education)
+    - Article 11: Technical Documentation Requirements (Annex IV)
+    - Article 43: Conformity Assessment Procedures
+    - Article 49: EU Database Registration
+    - Article 50: Transparency Obligations (chatbots, emotion recognition)
+    - Article 72: Post-Market Monitoring Requirements
+    - Article 17: Quality Management System
+    
+    Risk Classification Categories:
+    - Unacceptable Risk (Article 5): Prohibited AI practices (social scoring, manipulation)
+    - High Risk (Annex III): Employment, healthcare, credit scoring, biometric, legal/judicial, education, law enforcement
+    - Limited Risk (Article 50): Transparency obligations for chatbots, deepfakes
+    - Minimal Risk: General purpose AI with no specific obligations
+    
+    Parameters:
+        organization_context (dict): Organization profile from discover_organization tool. Contains name, sector, size, jurisdiction.
+        system_names (list): Specific AI system names to discover (e.g., ['Watson', 'Copilot', 'ChatGPT']). If not provided, discovers all known systems.
+        scope (str): Scope of discovery - 'all' (default), 'high-risk-only', 'production-only'
+        context (str): Additional context about the systems (e.g., 'focus on recruitment AI', 'customer-facing only')
+    
+    Returns:
+        dict: AI systems discovery results including:
+            - systems: Array of AISystemProfile with name, description, riskClassification, technicalDetails, complianceStatus
+            - riskSummary: Counts by risk category (unacceptable, high, limited, minimal)
+            - complianceSummary: Gap counts and overall compliance percentage
+            - regulatoryFramework: EU AI Act reference information
+            - complianceDeadlines: Key dates for high-risk and limited-risk systems
+    """
+    return call_api_with_timeout(
+        "/api/tools/discover_ai_services",
+        {
+            "organizationContext": organization_context,
+            "systemNames": system_names,
+            "scope": scope,
+            "context": context
+        },
+        timeout=CHATGPT_TOOL_TIMEOUT
+    )
+
+
+@gr.mcp.tool(
+    _meta={
+        "openai/outputTemplate": "ui://widget/compliance.html",
+        "openai/resultCanProduceWidget": True,
+        "openai/widgetAccessible": True,
+    }
+)
+def assess_compliance(
+    organization_context: Optional[dict] = None,
+    ai_services_context: Optional[dict] = None,
+    focus_areas: Optional[list] = None,
+    generate_documentation: bool = True
+) -> dict:
+    """
+    Assess EU AI Act compliance and generate documentation using AI analysis.
+    
+    EU AI Act Compliance Assessment Tool implementing comprehensive gap analysis
+    against Regulation (EU) 2024/1689. Optimized for speed with brief, actionable outputs.
+    
+    High-Risk System Requirements Assessed (Articles 8-15):
+    - Article 9: Risk Management System - continuous process for identifying, analyzing, mitigating risks
+    - Article 10: Data Governance - quality, representativeness, bias detection in training data
+    - Article 11: Technical Documentation (Annex IV) - comprehensive system documentation
+    - Article 12: Record-Keeping - automatic logging of system operation
+    - Article 13: Transparency - clear information to users and deployers
+    - Article 14: Human Oversight - appropriate human intervention mechanisms
+    - Article 15: Accuracy, Robustness, Cybersecurity - performance and security requirements
+    
+    Provider Obligations Assessed (Articles 16-22):
+    - Article 16: Provider obligations for high-risk AI
+    - Article 17: Quality Management System
+    - Article 22: Authorized Representative (for non-EU providers)
+    
+    Conformity Assessment (Articles 43-49):
+    - Article 43: Conformity Assessment Procedures
+    - Article 47: EU Declaration of Conformity
+    - Article 48: CE Marking
+    - Article 49: EU Database Registration
+    
+    Generates professional documentation templates for:
+    - Risk Management System (Article 9) - risk identification, analysis, mitigation, monitoring
+    - Technical Documentation (Article 11, Annex IV) - system description, data governance, performance metrics
+    - Conformity Assessment procedures (Article 43)
+    - Transparency Notice for chatbots (Article 50)
+    - Quality Management System (Article 17)
+    - Human Oversight Procedure (Article 14)
+    - Data Governance Policy (Article 10)
+    
+    NOTE: Assessment typically completes in 30-60 seconds. For complex assessments,
+    consider using faster models (claude-4.5, gemini-3) instead of gpt-oss.
+    
+    Parameters:
+        organization_context (dict): Organization profile from discover_organization tool. Contains name, sector, size, EU presence.
+        ai_services_context (dict): AI services discovery results from discover_ai_services tool. Contains systems and risk classifications.
+        focus_areas (list): Specific compliance areas to focus on (e.g., ['Article 9', 'Technical Documentation', 'Conformity Assessment'])
+        generate_documentation (bool): Whether to generate documentation templates (default: True). Set to False for faster assessment.
+    
+    Returns:
+        dict: Compliance assessment including:
+            - assessment: overallScore (0-100), riskLevel (CRITICAL/HIGH/MEDIUM/LOW), gaps, recommendations
+            - documentation: riskManagementTemplate, technicalDocumentation (markdown format)
+            - reasoning: Brief explanation of assessment results
+            - metadata: assessmentDate, modelUsed, organizationAssessed, documentationFiles
+    """
+    return call_api_with_timeout(
+        "/api/tools/assess_compliance",
+        {
+            "organizationContext": organization_context,
+            "aiServicesContext": ai_services_context,
+            "focusAreas": focus_areas,
+            "generateDocumentation": generate_documentation
+        },
+        timeout=CHATGPT_TOOL_TIMEOUT
+    )
+
+
+# ============================================================================
+# MCP RESOURCES - HTML/JS/CSS Widgets for ChatGPT Apps
+# ============================================================================
+
+@gr.mcp.resource("ui://widget/organization.html", mime_type="text/html+skybridge")
+def organization_widget():
+    """
+    Widget for displaying organization discovery results in ChatGPT.
+    
+    Renders a rich card UI showing organization profile data including:
+    - Organization name, logo, and sector
+    - Company size (Startup, SME, Enterprise) and headquarters location
+    - EU presence status and AI maturity level
+    - EU AI Act compliance framework badge
+    - Next compliance deadline with countdown
+    
+    Handles loading, error, and timeout states gracefully.
+    Used with discover_organization MCP tool via openai/outputTemplate.
+    """
+    return """
+    <style>
+        * { box-sizing: border-box; }
+        body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+        .org-card {
+            background: linear-gradient(135deg, #1e3a5f 0%, #2d5a87 100%);
+            border-radius: 16px;
+            padding: 24px;
+            color: white;
+            max-width: 500px;
+            margin: 0 auto;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
+        }
+        .org-header {
+            display: flex;
+            align-items: center;
+            gap: 16px;
+            margin-bottom: 20px;
+        }
+        .org-logo {
+            width: 64px;
+            height: 64px;
+            background: rgba(255,255,255,0.1);
+            border-radius: 12px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 32px;
+        }
+        .org-name {
+            font-size: 24px;
+            font-weight: 700;
+            margin: 0;
+        }
+        .org-sector {
+            font-size: 14px;
+            opacity: 0.8;
+            margin: 4px 0 0 0;
+        }
+        .info-grid {
+            display: grid;
+            grid-template-columns: repeat(2, 1fr);
+            gap: 12px;
+            margin: 20px 0;
+        }
+        .info-item {
+            background: rgba(255,255,255,0.1);
+            border-radius: 10px;
+            padding: 12px;
+        }
+        .info-label {
+            font-size: 11px;
+            text-transform: uppercase;
+            opacity: 0.7;
+            margin-bottom: 4px;
+        }
+        .info-value {
+            font-size: 16px;
+            font-weight: 600;
+        }
+        .compliance-badge {
+            display: inline-flex;
+            align-items: center;
+            gap: 6px;
+            background: rgba(255,255,255,0.15);
+            padding: 8px 12px;
+            border-radius: 20px;
+            font-size: 13px;
+            margin-top: 16px;
+        }
+        .eu-flag { font-size: 18px; }
+        .deadline {
+            background: rgba(255,193,7,0.2);
+            border: 1px solid rgba(255,193,7,0.4);
+            border-radius: 8px;
+            padding: 12px;
+            margin-top: 16px;
+        }
+        .deadline-title {
+            font-size: 12px;
+            font-weight: 600;
+            margin-bottom: 4px;
+            color: #ffc107;
+        }
+        .deadline-date {
+            font-size: 14px;
+        }
+        .error-card {
+            background: #f44336;
+            border-radius: 12px;
+            padding: 20px;
+            color: white;
+            text-align: center;
+        }
+        .processing-card {
+            background: linear-gradient(135deg, #ff9800 0%, #f57c00 100%);
+            border-radius: 16px;
+            padding: 24px;
+            color: white;
+            text-align: center;
+        }
+        .processing-icon {
+            font-size: 48px;
+            animation: pulse 1.5s ease-in-out infinite;
+        }
+        @keyframes pulse {
+            0%, 100% { opacity: 1; transform: scale(1); }
+            50% { opacity: 0.7; transform: scale(1.1); }
+        }
+        .processing-title {
+            font-size: 18px;
+            font-weight: 600;
+            margin: 12px 0 8px 0;
+        }
+        .processing-msg {
+            font-size: 14px;
+            opacity: 0.9;
+            line-height: 1.5;
+        }
+        .tip-box {
+            background: rgba(255,255,255,0.15);
+            border-radius: 8px;
+            padding: 10px;
+            margin-top: 12px;
+            font-size: 12px;
+        }
+    </style>
+    
+    <div id="org-container">
+        <div class="org-card" id="card">
+            <div class="org-header">
+                <div class="org-logo" id="logo">🏢</div>
+                <div>
+                    <h1 class="org-name" id="org-name">Loading...</h1>
+                    <p class="org-sector" id="org-sector">Discovering organization...</p>
+                </div>
+            </div>
+            
+            <div class="info-grid">
+                <div class="info-item">
+                    <div class="info-label">Size</div>
+                    <div class="info-value" id="size">-</div>
+                </div>
+                <div class="info-item">
+                    <div class="info-label">Headquarters</div>
+                    <div class="info-value" id="hq">-</div>
+                </div>
+                <div class="info-item">
+                    <div class="info-label">EU Presence</div>
+                    <div class="info-value" id="eu-presence">-</div>
+                </div>
+                <div class="info-item">
+                    <div class="info-label">AI Maturity</div>
+                    <div class="info-value" id="ai-maturity">-</div>
+                </div>
+            </div>
+            
+            <div class="compliance-badge">
+                <span class="eu-flag">🇪🇺</span>
+                <span id="framework">EU AI Act Compliance Assessment</span>
+            </div>
+            
+            <div class="deadline" id="deadline-container">
+                <div class="deadline-title">⏰ Next Compliance Deadline</div>
+                <div class="deadline-date" id="deadline">Loading...</div>
+            </div>
+        </div>
+    </div>
+    
+    <script>
+        function renderOrganization(data) {
+            if (!data || data.error) {
+                document.getElementById('org-container').innerHTML = 
+                    '<div class="error-card">❌ ' + (data?.message || 'Failed to load organization') + '</div>';
+                return;
+            }
+            
+            // Handle timeout/processing state
+            if (data.status === 'processing' || data._timeout) {
+                document.getElementById('org-container').innerHTML = 
+                    '<div class="processing-card">' +
+                    '<div class="processing-icon">⏳</div>' +
+                    '<div class="processing-title">Analysis in Progress</div>' +
+                    '<div class="processing-msg">' + (data.message || 'Processing...') + '</div>' +
+                    (data.tip ? '<div class="tip-box">💡 ' + data.tip + '</div>' : '') +
+                    '</div>';
+                return;
+            }
+            
+            const org = data.organization || data;
+            const regulatory = data.regulatoryContext || {};
+            
+            document.getElementById('org-name').textContent = org.name || 'Unknown';
+            document.getElementById('org-sector').textContent = org.sector || 'Technology';
+            document.getElementById('size').textContent = org.size || 'Unknown';
+            document.getElementById('hq').textContent = 
+                (org.headquarters?.city || 'Unknown') + ', ' + (org.headquarters?.country || '');
+            document.getElementById('eu-presence').textContent = org.euPresence ? '✅ Yes' : '❌ No';
+            document.getElementById('ai-maturity').textContent = org.aiMaturityLevel || 'Unknown';
+            
+            // Show nearest deadline
+            const deadlines = regulatory.complianceDeadlines || [];
+            if (deadlines.length > 0) {
+                const nearest = deadlines[0];
+                document.getElementById('deadline').textContent = 
+                    nearest.date + ' - ' + nearest.description;
+            } else {
+                document.getElementById('deadline-container').style.display = 'none';
+            }
+        }
+        
+        function render() {
+            const data = window.openai?.toolOutput;
+            if (data) {
+                // Handle both direct text content and structured content
+                let parsedData = data;
+                if (typeof data === 'string') {
+                    try { parsedData = JSON.parse(data); } catch (e) {}
+                } else if (data.text) {
+                    try { parsedData = JSON.parse(data.text); } catch (e) { parsedData = data; }
+                } else if (data.content) {
+                    for (const item of data.content) {
+                        if (item.type === 'text') {
+                            try { parsedData = JSON.parse(item.text); break; } catch (e) {}
+                        }
+                    }
+                }
+                renderOrganization(parsedData);
+            }
+        }
+        
+        window.addEventListener("openai:set_globals", (event) => {
+            if (event.detail?.globals?.toolOutput) render();
+        }, { passive: true });
+        
+        render();
+    </script>
+    """
+
+
+@gr.mcp.resource("ui://widget/ai-services.html", mime_type="text/html+skybridge")
+def ai_services_widget():
+    """
+    Widget for displaying AI services discovery results in ChatGPT.
+    
+    Renders a comprehensive risk overview dashboard showing:
+    - Risk summary grid: Unacceptable, High, Limited, Minimal risk counts
+    - Color-coded system cards for each discovered AI system
+    - System details: name, purpose, risk score (0-100), conformity status
+    - Visual indicators for compliance requirements
+    
+    Risk categories per EU AI Act:
+    - Unacceptable (red): Article 5 prohibited practices
+    - High (orange): Annex III systems requiring conformity assessment
+    - Limited (yellow): Article 50 transparency obligations
+    - Minimal (green): No specific obligations
+    
+    Used with discover_ai_services MCP tool via openai/outputTemplate.
+    """
+    return """
+    <style>
+        * { box-sizing: border-box; }
+        body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+        .services-container {
+            max-width: 600px;
+            margin: 0 auto;
+            padding: 16px;
+        }
+        .summary-card {
+            background: linear-gradient(135deg, #2196F3 0%, #1976D2 100%);
+            border-radius: 16px;
+            padding: 20px;
+            color: white;
+            margin-bottom: 16px;
+        }
+        .summary-title {
+            font-size: 18px;
+            font-weight: 700;
+            margin: 0 0 16px 0;
+        }
+        .risk-grid {
+            display: grid;
+            grid-template-columns: repeat(4, 1fr);
+            gap: 8px;
+        }
+        .risk-item {
+            text-align: center;
+            padding: 12px 8px;
+            background: rgba(255,255,255,0.15);
+            border-radius: 8px;
+        }
+        .risk-count {
+            font-size: 28px;
+            font-weight: 700;
+        }
+        .risk-label {
+            font-size: 10px;
+            text-transform: uppercase;
+            opacity: 0.8;
+            margin-top: 4px;
+        }
+        .risk-unacceptable { color: #ff1744; }
+        .risk-high { color: #ff9100; }
+        .risk-limited { color: #ffea00; }
+        .risk-minimal { color: #00e676; }
+        .system-card {
+            background: white;
+            border-radius: 12px;
+            padding: 16px;
+            margin-bottom: 12px;
+            border-left: 4px solid #ccc;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+        }
+        .system-card.high { border-left-color: #ff9100; background: #fff8e1; }
+        .system-card.limited { border-left-color: #ffc107; background: #fffde7; }
+        .system-card.minimal { border-left-color: #4caf50; background: #e8f5e9; }
+        .system-card.unacceptable { border-left-color: #f44336; background: #ffebee; }
+        .system-name {
+            font-size: 16px;
+            font-weight: 600;
+            margin: 0 0 8px 0;
+            color: #333;
+        }
+        .system-purpose {
+            font-size: 13px;
+            color: #666;
+            margin: 0 0 12px 0;
+        }
+        .system-meta {
+            display: flex;
+            gap: 12px;
+            flex-wrap: wrap;
+        }
+        .meta-badge {
+            display: inline-flex;
+            align-items: center;
+            gap: 4px;
+            font-size: 11px;
+            background: rgba(0,0,0,0.06);
+            padding: 4px 8px;
+            border-radius: 12px;
+            color: #555;
+        }
+        .empty-state {
+            text-align: center;
+            padding: 40px;
+            color: #666;
+        }
+        .processing-card {
+            background: linear-gradient(135deg, #ff9800 0%, #f57c00 100%);
+            border-radius: 16px;
+            padding: 24px;
+            color: white;
+            text-align: center;
+        }
+        .processing-icon {
+            font-size: 48px;
+            animation: pulse 1.5s ease-in-out infinite;
+        }
+        @keyframes pulse {
+            0%, 100% { opacity: 1; transform: scale(1); }
+            50% { opacity: 0.7; transform: scale(1.1); }
+        }
+        .processing-title {
+            font-size: 18px;
+            font-weight: 600;
+            margin: 12px 0 8px 0;
+        }
+        .processing-msg {
+            font-size: 14px;
+            opacity: 0.9;
+            line-height: 1.5;
+        }
+        .tip-box {
+            background: rgba(255,255,255,0.15);
+            border-radius: 8px;
+            padding: 10px;
+            margin-top: 12px;
+            font-size: 12px;
+        }
+    </style>
+    
+    <div class="services-container" id="container">
+        <div class="summary-card">
+            <h2 class="summary-title">🤖 AI Systems Risk Overview</h2>
+            <div class="risk-grid">
+                <div class="risk-item">
+                    <div class="risk-count risk-unacceptable" id="unacceptable">0</div>
+                    <div class="risk-label">Unacceptable</div>
+                </div>
+                <div class="risk-item">
+                    <div class="risk-count risk-high" id="high">0</div>
+                    <div class="risk-label">High Risk</div>
+                </div>
+                <div class="risk-item">
+                    <div class="risk-count risk-limited" id="limited">0</div>
+                    <div class="risk-label">Limited</div>
+                </div>
+                <div class="risk-item">
+                    <div class="risk-count risk-minimal" id="minimal">0</div>
+                    <div class="risk-label">Minimal</div>
+                </div>
+            </div>
+        </div>
+        <div id="systems-list"></div>
+    </div>
+    
+    <script>
+        function renderServices(data) {
+            if (!data || data.error) {
+                document.getElementById('systems-list').innerHTML = 
+                    '<div class="empty-state">❌ ' + (data?.message || 'No AI systems found') + '</div>';
+                return;
+            }
+            
+            // Handle timeout/processing state
+            if (data.status === 'processing' || data._timeout) {
+                document.getElementById('container').innerHTML = 
+                    '<div class="processing-card">' +
+                    '<div class="processing-icon">⏳</div>' +
+                    '<div class="processing-title">Analysis in Progress</div>' +
+                    '<div class="processing-msg">' + (data.message || 'Processing...') + '</div>' +
+                    (data.tip ? '<div class="tip-box">💡 ' + data.tip + '</div>' : '') +
+                    '</div>';
+                return;
+            }
+            
+            const summary = data.riskSummary || {};
+            document.getElementById('unacceptable').textContent = summary.unacceptableRiskCount || 0;
+            document.getElementById('high').textContent = summary.highRiskCount || 0;
+            document.getElementById('limited').textContent = summary.limitedRiskCount || 0;
+            document.getElementById('minimal').textContent = summary.minimalRiskCount || 0;
+            
+            const systems = data.systems || [];
+            const listHtml = systems.map(sys => {
+                const risk = sys.riskClassification?.category?.toLowerCase() || 'minimal';
+                const name = sys.system?.name || 'Unknown System';
+                const purpose = sys.system?.intendedPurpose || 'No description';
+                const score = sys.riskClassification?.riskScore || 0;
+                const conformity = sys.riskClassification?.conformityAssessmentRequired ? '⚠️ Required' : '✅ Not Required';
+                
+                return '<div class="system-card ' + risk + '">' +
+                    '<h3 class="system-name">' + name + '</h3>' +
+                    '<p class="system-purpose">' + purpose.substring(0, 120) + (purpose.length > 120 ? '...' : '') + '</p>' +
+                    '<div class="system-meta">' +
+                    '<span class="meta-badge">📊 Risk: ' + score + '/100</span>' +
+                    '<span class="meta-badge">📋 Conformity: ' + conformity + '</span>' +
+                    '</div></div>';
+            }).join('');
+            
+            document.getElementById('systems-list').innerHTML = listHtml || '<div class="empty-state">No systems discovered</div>';
+        }
+        
+        function render() {
+            const data = window.openai?.toolOutput;
+            if (data) {
+                let parsedData = data;
+                if (typeof data === 'string') {
+                    try { parsedData = JSON.parse(data); } catch (e) {}
+                } else if (data.text) {
+                    try { parsedData = JSON.parse(data.text); } catch (e) { parsedData = data; }
+                } else if (data.content) {
+                    for (const item of data.content) {
+                        if (item.type === 'text') {
+                            try { parsedData = JSON.parse(item.text); break; } catch (e) {}
+                        }
+                    }
+                }
+                renderServices(parsedData);
+            }
+        }
+        
+        window.addEventListener("openai:set_globals", (event) => {
+            if (event.detail?.globals?.toolOutput) render();
+        }, { passive: true });
+        
+        render();
+    </script>
+    """
+
+
+@gr.mcp.resource("ui://widget/compliance.html", mime_type="text/html+skybridge")
+def compliance_widget():
+    """
+    Widget for displaying EU AI Act compliance assessment results in ChatGPT.
+    
+    Renders an interactive compliance dashboard showing:
+    - Animated score ring: Overall compliance score (0-100) with color gradient
+    - Risk level badge: CRITICAL, HIGH, MEDIUM, or LOW
+    - Stats grid: Compliance gaps count and recommendations count
+    - Priority gaps section: Top 3 gaps with severity and Article references
+    - Recommendations section: Top 3 prioritized action items
+    - Action button: Re-run full assessment with documentation generation
+    
+    Score color coding:
+    - Green (80+): Good compliance posture
+    - Yellow (60-79): Moderate gaps to address
+    - Orange (40-59): Significant compliance work needed
+    - Red (<40): Critical compliance issues
+    
+    Used with assess_compliance MCP tool via openai/outputTemplate.
+    Includes window.openai.callTool() for interactive re-assessment.
+    """
+    return """
+    <style>
+        * { box-sizing: border-box; }
+        body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+        .compliance-container {
+            max-width: 600px;
+            margin: 0 auto;
+            padding: 16px;
+        }
+        .score-card {
+            background: linear-gradient(135deg, #1a237e 0%, #283593 100%);
+            border-radius: 20px;
+            padding: 24px;
+            color: white;
+            text-align: center;
+            margin-bottom: 16px;
+        }
+        .score-ring {
+            width: 140px;
+            height: 140px;
+            margin: 0 auto 16px;
+            position: relative;
+        }
+        .score-ring svg {
+            transform: rotate(-90deg);
+            width: 100%;
+            height: 100%;
+        }
+        .score-ring circle {
+            fill: none;
+            stroke-width: 12;
+        }
+        .score-ring .bg { stroke: rgba(255,255,255,0.2); }
+        .score-ring .progress { stroke: #4caf50; stroke-linecap: round; transition: stroke-dashoffset 1s ease; }
+        .score-value {
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            font-size: 42px;
+            font-weight: 800;
+        }
+        .score-label {
+            font-size: 14px;
+            opacity: 0.8;
+        }
+        .risk-badge {
+            display: inline-block;
+            padding: 8px 16px;
+            border-radius: 20px;
+            font-weight: 600;
+            font-size: 14px;
+            margin-top: 12px;
+        }
+        .risk-critical { background: #f44336; }
+        .risk-high { background: #ff9800; }
+        .risk-medium { background: #ffc107; color: #333; }
+        .risk-low { background: #4caf50; }
+        .stats-grid {
+            display: grid;
+            grid-template-columns: repeat(2, 1fr);
+            gap: 12px;
+            margin-bottom: 16px;
+        }
+        .stat-card {
+            background: white;
+            border-radius: 12px;
+            padding: 16px;
+            text-align: center;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+        }
+        .stat-value {
+            font-size: 28px;
+            font-weight: 700;
+            color: #333;
+        }
+        .stat-label {
+            font-size: 12px;
+            color: #666;
+            margin-top: 4px;
+        }
+        .gaps-section, .recs-section {
+            background: white;
+            border-radius: 12px;
+            padding: 16px;
+            margin-bottom: 12px;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+        }
+        .section-title {
+            font-size: 16px;
+            font-weight: 700;
+            color: #333;
+            margin: 0 0 12px 0;
+        }
+        .gap-item, .rec-item {
+            padding: 10px 12px;
+            background: #f5f5f5;
+            border-radius: 8px;
+            margin-bottom: 8px;
+            font-size: 13px;
+        }
+        .gap-item.critical { background: #ffebee; border-left: 3px solid #f44336; }
+        .gap-item.high { background: #fff3e0; border-left: 3px solid #ff9800; }
+        .gap-article {
+            font-size: 11px;
+            color: #666;
+            margin-top: 4px;
+        }
+        .rec-priority {
+            display: inline-block;
+            background: #e3f2fd;
+            color: #1976d2;
+            padding: 2px 8px;
+            border-radius: 10px;
+            font-size: 10px;
+            font-weight: 600;
+            margin-right: 8px;
+        }
+        .action-btn {
+            display: block;
+            width: 100%;
+            padding: 14px;
+            background: #1976d2;
+            color: white;
+            border: none;
+            border-radius: 10px;
+            font-size: 14px;
+            font-weight: 600;
+            cursor: pointer;
+            margin-top: 16px;
+        }
+        .action-btn:hover { background: #1565c0; }
+        .processing-card {
+            background: linear-gradient(135deg, #ff9800 0%, #f57c00 100%);
+            border-radius: 16px;
+            padding: 24px;
+            color: white;
+            text-align: center;
+        }
+        .processing-icon {
+            font-size: 48px;
+            animation: pulse 1.5s ease-in-out infinite;
+        }
+        @keyframes pulse {
+            0%, 100% { opacity: 1; transform: scale(1); }
+            50% { opacity: 0.7; transform: scale(1.1); }
+        }
+        .processing-title {
+            font-size: 18px;
+            font-weight: 600;
+            margin: 12px 0 8px 0;
+        }
+        .processing-msg {
+            font-size: 14px;
+            opacity: 0.9;
+            line-height: 1.5;
+        }
+        .tip-box {
+            background: rgba(255,255,255,0.15);
+            border-radius: 8px;
+            padding: 10px;
+            margin-top: 12px;
+            font-size: 12px;
+        }
+    </style>
+    
+    <div class="compliance-container" id="container">
+        <div class="score-card">
+            <div class="score-ring">
+                <svg viewBox="0 0 100 100">
+                    <circle class="bg" cx="50" cy="50" r="42"/>
+                    <circle class="progress" id="progress-ring" cx="50" cy="50" r="42" 
+                        stroke-dasharray="264" stroke-dashoffset="264"/>
+                </svg>
+                <div class="score-value" id="score">--</div>
+            </div>
+            <div class="score-label">EU AI Act Compliance Score</div>
+            <div class="risk-badge risk-medium" id="risk-badge">Calculating...</div>
+        </div>
+        
+        <div class="stats-grid">
+            <div class="stat-card">
+                <div class="stat-value" id="gaps-count">-</div>
+                <div class="stat-label">Compliance Gaps</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value" id="recs-count">-</div>
+                <div class="stat-label">Recommendations</div>
+            </div>
+        </div>
+        
+        <div class="gaps-section">
+            <h3 class="section-title">⚠️ Priority Gaps</h3>
+            <div id="gaps-list"></div>
+        </div>
+        
+        <div class="recs-section">
+            <h3 class="section-title">💡 Top Recommendations</h3>
+            <div id="recs-list"></div>
+        </div>
+        
+        <button class="action-btn" id="run-again" style="display:none;">
+            🔄 Run Full Assessment
+        </button>
+    </div>
+    
+    <script>
+        function renderCompliance(data) {
+            if (!data || data.error) {
+                document.getElementById('score').textContent = '❌';
+                document.getElementById('gaps-list').innerHTML = '<div style="color:#999;text-align:center;">Error: ' + (data?.message || 'Assessment failed') + '</div>';
+                return;
+            }
+            
+            // Handle timeout/processing state
+            if (data.status === 'processing' || data._timeout) {
+                document.getElementById('container').innerHTML = 
+                    '<div class="processing-card">' +
+                    '<div class="processing-icon">⏳</div>' +
+                    '<div class="processing-title">Compliance Assessment in Progress</div>' +
+                    '<div class="processing-msg">' + (data.message || 'Processing...') + '</div>' +
+                    (data.tip ? '<div class="tip-box">💡 ' + data.tip + '</div>' : '') +
+                    '</div>';
+                return;
+            }
+            
+            const assessment = data.assessment || data;
+            const score = assessment.overallScore || 0;
+            const riskLevel = assessment.riskLevel || 'MEDIUM';
+            const gaps = assessment.gaps || [];
+            const recs = assessment.recommendations || [];
+            
+            // Animate score ring
+            document.getElementById('score').textContent = score;
+            const offset = 264 - (264 * score / 100);
+            document.getElementById('progress-ring').style.strokeDashoffset = offset;
+            
+            // Set progress color based on score
+            const progressEl = document.getElementById('progress-ring');
+            if (score >= 80) progressEl.style.stroke = '#4caf50';
+            else if (score >= 60) progressEl.style.stroke = '#ffc107';
+            else if (score >= 40) progressEl.style.stroke = '#ff9800';
+            else progressEl.style.stroke = '#f44336';
+            
+            // Risk badge
+            const badgeEl = document.getElementById('risk-badge');
+            badgeEl.textContent = riskLevel + ' Risk';
+            badgeEl.className = 'risk-badge risk-' + riskLevel.toLowerCase();
+            
+            // Stats
+            document.getElementById('gaps-count').textContent = gaps.length;
+            document.getElementById('recs-count').textContent = recs.length;
+            
+            // Top gaps (show critical/high first)
+            const topGaps = gaps
+                .sort((a, b) => {
+                    const order = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+                    return (order[a.severity] || 3) - (order[b.severity] || 3);
+                })
+                .slice(0, 3);
+            
+            const gapsHtml = topGaps.map(gap => {
+                const severity = (gap.severity || 'medium').toLowerCase();
+                return '<div class="gap-item ' + severity + '">' +
+                    '<strong>' + (gap.category || 'Compliance') + ':</strong> ' + 
+                    (gap.description || 'Gap identified').substring(0, 100) + '...' +
+                    '<div class="gap-article">' + (gap.articleReference || '') + '</div>' +
+                    '</div>';
+            }).join('');
+            
+            document.getElementById('gaps-list').innerHTML = gapsHtml || '<div style="color:#999;">No gaps identified</div>';
+            
+            // Top recommendations
+            const topRecs = recs.sort((a, b) => (a.priority || 10) - (b.priority || 10)).slice(0, 3);
+            const recsHtml = topRecs.map(rec => {
+                return '<div class="rec-item">' +
+                    '<span class="rec-priority">Priority ' + (rec.priority || '-') + '</span>' +
+                    (rec.title || rec.description || 'Recommendation').substring(0, 80) +
+                    '</div>';
+            }).join('');
+            
+            document.getElementById('recs-list').innerHTML = recsHtml || '<div style="color:#999;">No recommendations</div>';
+            
+            // Show action button
+            document.getElementById('run-again').style.display = 'block';
+            document.getElementById('run-again').onclick = async function() {
+                this.textContent = '⏳ Running...';
+                this.disabled = true;
+                try {
+                    await window.openai.callTool('assess_compliance', {
+                        organization_context: data.metadata?.organizationAssessed ? { name: data.metadata.organizationAssessed } : null,
+                        generate_documentation: true
+                    });
+                } catch (e) {
+                    console.error(e);
+                }
+                this.textContent = '🔄 Run Full Assessment';
+                this.disabled = false;
+            };
+        }
+        
+        function render() {
+            const data = window.openai?.toolOutput;
+            if (data) {
+                let parsedData = data;
+                if (typeof data === 'string') {
+                    try { parsedData = JSON.parse(data); } catch (e) {}
+                } else if (data.text) {
+                    try { parsedData = JSON.parse(data.text); } catch (e) { parsedData = data; }
+                } else if (data.content) {
+                    for (const item of data.content) {
+                        if (item.type === 'text') {
+                            try { parsedData = JSON.parse(item.text); break; } catch (e) {}
+                        }
+                    }
+                }
+                renderCompliance(parsedData);
+            }
+        }
+        
+        window.addEventListener("openai:set_globals", (event) => {
+            if (event.detail?.globals?.toolOutput) render();
+        }, { passive: true });
+        
+        render();
+    </script>
+    """
+
+
+# ============================================================================
+# GRADIO UI - For testing tools and displaying resource code
+# ============================================================================
+
+# Build header based on environment
+_is_production = bool(PUBLIC_URL)
+if _is_production:
+    _mcp_url = f"{PUBLIC_URL.rstrip('/')}/gradio_api/mcp/"
+    _env_info = f"""
+        <div style="background: rgba(76, 175, 80, 0.2); border: 1px solid rgba(76, 175, 80, 0.4); border-radius: 8px; padding: 12px; margin-top: 15px;">
+            <p style="margin: 0; font-size: 0.85em;">🌐 <strong>Production Mode - MCP Server Ready</strong></p>
+            <p style="margin: 8px 0 0 0; font-size: 0.9em;">
+                <strong>MCP URL (copy this):</strong><br>
+                <code style="background: rgba(255,255,255,0.3); padding: 6px 10px; border-radius: 4px; display: inline-block; margin-top: 4px; word-break: break-all; font-size: 0.85em;">{_mcp_url}</code>
+            </p>
+            <p style="margin: 10px 0 0 0; font-size: 0.75em; opacity: 0.8;">
+                ChatGPT → Settings → Apps & Connectors → Create Connector → Paste URL
+            </p>
+        </div>
+    """
+else:
+    _env_info = """
+        <div style="background: rgba(33, 150, 243, 0.2); border: 1px solid rgba(33, 150, 243, 0.4); border-radius: 8px; padding: 12px; margin-top: 15px;">
+            <p style="margin: 0; font-size: 0.85em;">🛠️ <strong>Local Development</strong></p>
+            <p style="margin: 5px 0 0 0; font-size: 0.8em; opacity: 0.9;">MCP URL: <code>http://localhost:7860/gradio_api/mcp/</code></p>
+            <p style="margin: 8px 0 0 0; font-size: 0.8em;">For public URL, run with <code>GRADIO_SHARE=true</code></p>
+        </div>
+    """
+
+with gr.Blocks(
+    title="🇪🇺 EU AI Act - ChatGPT App",
+) as demo:
+    
+    gr.HTML(f"""
+        <div style="text-align: center; padding: 20px 0; background: linear-gradient(135deg, #1e3a5f 0%, #2d5a87 100%); border-radius: 12px; color: white; margin-bottom: 20px;">
+            <h1 style="margin: 0; font-size: 2em;">🇪🇺 EU AI Act Compliance</h1>
+            <p style="margin: 10px 0 0 0; opacity: 0.9;">ChatGPT App powered by Gradio MCP</p>
+            <p style="margin: 5px 0 0 0; font-size: 0.85em; opacity: 0.7;">by <a href="https://www.legitima.ai/mcp-hackathon" target="_blank" style="color: #90CAF9;">Legitima.ai</a></p>
+            {_env_info}
+        </div>
+    """)
+    
+    gr.Markdown("""
+    ## 🚀 How to Use in ChatGPT
+    
+    1. **Get the MCP URL** from the terminal/Space logs  
+       ⚠️ **Important:** The URL must end with `/gradio_api/mcp/`  
+       Example: `https://xxx.gradio.live/gradio_api/mcp/`
+    2. **Enable Developer Mode** in ChatGPT: Settings → Apps & Connectors → Advanced settings
+    3. **Create a Connector** with the MCP server URL (choose "No authentication")
+    4. **Chat with ChatGPT** using `@eu-ai-act` to access these tools
+    
+    ---
+    """)
+    
+    with gr.Tab("🔧 Test Tools"):
+        gr.Markdown("### Test MCP Tools Directly")
+        
+        with gr.Row():
+            with gr.Column():
+                org_name = gr.Textbox(label="Organization Name", placeholder="e.g., Microsoft, IBM, OpenAI")
+                org_domain = gr.Textbox(label="Domain (optional)", placeholder="e.g., microsoft.com")
+                org_context = gr.Textbox(label="Context (optional)", placeholder="Additional context...")
+                discover_btn = gr.Button("🔍 Discover Organization", variant="primary")
+            
+            with gr.Column():
+                org_result = gr.JSON(label="Organization Profile")
+        
+        gr.Markdown("---")
+        
+        with gr.Row():
+            with gr.Column():
+                ai_systems_input = gr.Textbox(label="System Names (comma-separated)", placeholder="e.g., Watson, Copilot")
+                ai_scope = gr.Dropdown(choices=["all", "high-risk-only", "production-only"], value="all", label="Scope")
+                discover_ai_btn = gr.Button("🤖 Discover AI Services", variant="primary")
+            
+            with gr.Column():
+                ai_result = gr.JSON(label="AI Services Discovery")
+        
+        gr.Markdown("---")
+        
+        with gr.Row():
+            with gr.Column():
+                gen_docs = gr.Checkbox(label="Generate Documentation", value=True)
+                assess_btn = gr.Button("📊 Assess Compliance", variant="primary")
+            
+            with gr.Column():
+                compliance_result = gr.JSON(label="Compliance Assessment")
+    
+    with gr.Tab("📝 Widget Code"):
+        gr.Markdown("### MCP Resource Widgets (HTML/JS/CSS)")
+        gr.Markdown("These widgets are displayed in ChatGPT when tools are called.")
+        
+        # Pre-load widget code on startup to ensure MCP resources are registered
+        org_html = gr.Code(language="html", label="organization.html", value=organization_widget())
+        ai_html = gr.Code(language="html", label="ai-services.html", value=ai_services_widget())
+        comp_html = gr.Code(language="html", label="compliance.html", value=compliance_widget())
+        
+        # Also keep button handlers for refreshing
+        with gr.Row():
+            org_btn = gr.Button("🔄 Refresh Org Widget")
+            ai_btn = gr.Button("🔄 Refresh AI Widget")
+            comp_btn = gr.Button("🔄 Refresh Compliance Widget")
+        
+        org_btn.click(organization_widget, outputs=org_html)
+        ai_btn.click(ai_services_widget, outputs=ai_html)
+        comp_btn.click(compliance_widget, outputs=comp_html)
+    
+    with gr.Tab("ℹ️ About"):
+        gr.Markdown("""
+        ## About This ChatGPT App
+        
+        This Gradio app exposes **EU AI Act compliance tools** as a ChatGPT App using the 
+        [Gradio MCP Server](https://www.gradio.app/guides/building-chatgpt-apps-with-gradio) capabilities.
+        
+        ### Available Tools
+        
+        | Tool | Description | EU AI Act Articles |
+        |------|-------------|-------------------|
+        | `discover_organization` | Research organization profile | Articles 16, 22, 49 |
+        | `discover_ai_services` | Classify AI systems by risk | Articles 6, 11, Annex III |
+        | `assess_compliance` | Generate compliance report | Articles 9-15, 43-50 |
+        
+        ### Key Features
+        
+        - 🏢 **Organization Discovery**: Automatic research using Tavily AI or model fallback
+        - 🤖 **AI Systems Classification**: Risk categorization per EU AI Act Annex III
+        - 📊 **Compliance Assessment**: Gap analysis and documentation generation
+        - 🎨 **Beautiful Widgets**: Rich UI cards displayed directly in ChatGPT
+        
+        ### Tech Stack
+        
+        - **Gradio** with MCP server (`gradio[mcp]>=6.0`)
+        - **OpenAI Apps SDK** compatible widgets
+        - **Node.js API** backend with Vercel AI SDK
+        
+        ---
+        
+        Built for the **MCP 1st Birthday Hackathon** 🎂
+        """)
+    
+    # Event handlers for Gradio UI testing
+    def run_discover_org(name, domain, context):
+        """
+        Discover organization profile for EU AI Act compliance.
+        
+        Researches an organization using Tavily AI search or AI model fallback to create
+        a comprehensive profile including sector, size, EU presence, headquarters,
+        certifications, and regulatory context per EU AI Act Articles 16, 22, and 49.
+        
+        Parameters:
+            name (str): Organization name to discover (e.g., 'IBM', 'Microsoft', 'OpenAI')
+            domain (str): Organization's domain (e.g., 'ibm.com'). Auto-discovered if empty.
+            context (str): Additional context about the organization
+        
+        Returns:
+            dict: Organization profile with regulatory context and compliance deadlines
+        """
+        if not name:
+            return {"error": "Please enter an organization name"}
+        return discover_organization(name, domain or None, context or None)
+    
+    def run_discover_ai(systems, scope):
+        """
+        Discover and classify AI systems per EU AI Act Annex III risk categories.
+        
+        Scans for AI systems and classifies them according to EU AI Act risk tiers:
+        Unacceptable (Article 5), High (Annex III), Limited (Article 50), or Minimal.
+        Analyzes compliance gaps and conformity assessment requirements.
+        
+        Parameters:
+            systems (str): Comma-separated AI system names to discover (e.g., 'Watson, Copilot')
+            scope (str): Discovery scope - 'all', 'high-risk-only', or 'production-only'
+        
+        Returns:
+            dict: AI systems with risk classifications, compliance gaps, and deadlines
+        """
+        system_names = [s.strip() for s in systems.split(",")] if systems else None
+        return discover_ai_services(None, system_names, scope, None)
+    
+    def run_assess(gen_docs):
+        """
+        Assess EU AI Act compliance and generate documentation templates.
+        
+        Performs comprehensive compliance gap analysis against EU AI Act requirements
+        (Articles 9-15, 16-22, 43-50) and generates professional documentation
+        templates for Risk Management, Technical Documentation, and Conformity Assessment.
+        
+        Parameters:
+            gen_docs (bool): Whether to generate documentation templates (Article 9, 11, 43)
+        
+        Returns:
+            dict: Compliance score (0-100), risk level, gaps, recommendations, and documentation
+        """
+        return assess_compliance(None, None, None, gen_docs)
+    
+    discover_btn.click(run_discover_org, [org_name, org_domain, org_context], org_result)
+    discover_ai_btn.click(run_discover_ai, [ai_systems_input, ai_scope], ai_result)
+    assess_btn.click(run_assess, [gen_docs], compliance_result)
+
+
+# ============================================================================
+# LAUNCH
+# ============================================================================
+
+# File to store the MCP URL for the main Gradio app to read
+MCP_URL_FILE = Path(__file__).parent / ".mcp_url"
+
+def save_mcp_url(url: str):
+    """Save the MCP URL to a file for the main Gradio app to read"""
+    try:
+        # Ensure parent directory exists
+        MCP_URL_FILE.parent.mkdir(parents=True, exist_ok=True)
+        MCP_URL_FILE.write_text(url)
+        print(f"\n✅ MCP URL saved to: {MCP_URL_FILE}")
+        print(f"   URL content: {url}")
+    except Exception as e:
+        print(f"⚠️ Could not save MCP URL: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    is_production = bool(PUBLIC_URL)
+    # ChatGPT MCP app runs on 7861 by default (separate from main Gradio UI on 7860)
+    server_port = int(os.getenv("CHATGPT_APP_SERVER_PORT", "7861"))
+    use_share = os.getenv("GRADIO_SHARE", "false").lower() == "true"
+    
+    print("\n" + "=" * 70)
+    print("🇪🇺 EU AI Act Compliance - ChatGPT App (MCP Server)")
+    print("=" * 70)
+    
+    if is_production:
+        # Production on HF Spaces - MCP URL is based on PUBLIC_URL
+        mcp_url = f"{PUBLIC_URL.rstrip('/')}/gradio_api/mcp/"
+        print(f"\n🌐 Environment: PRODUCTION (HF Spaces)")
+        print(f"\n" + "=" * 70)
+        print("🎉 MCP SERVER READY!")
+        print("=" * 70)
+        print(f"\n🔗 MCP URL FOR CHATGPT (copy this):\n")
+        print(f"   {mcp_url}")
+        print(f"\n📍 Space URL: {PUBLIC_URL}")
+        print("=" * 70)
+    else:
+        print(f"\n🛠️  Environment: LOCAL DEVELOPMENT")
+        if use_share:
+            print(f"   MCP URL will be shown after launch (share=True)")
+        else:
+            print(f"   MCP URL: http://localhost:{server_port}/gradio_api/mcp/")
+    
+    print(f"\n📡 API Server: {API_URL}")
+    print(f"📍 Server Port: {server_port}")
+    print("\n📖 ChatGPT Integration:")
+    print("   1. Copy the MCP URL shown above")
+    print("   2. Enable 'Developer Mode' in ChatGPT Settings → Apps & Connectors")
+    print("   3. Create a connector with the MCP URL (No authentication)")
+    print("   4. Use @eu-ai-act in ChatGPT to access tools")
+    print("\n🚀 Starting Gradio MCP Server...")
+    print("=" * 70 + "\n")
+    
+    # Launch the MCP server on port 7860 (standalone) or 7861 (local dev with gradio_app)
+    demo.launch(
+        server_name=os.getenv("CHATGPT_APP_SERVER_NAME", "0.0.0.0"),
+        server_port=server_port,
+        share=use_share,  # Only use share for local dev if needed
+        mcp_server=True,  # Enable MCP server for ChatGPT integration
+        show_error=True,
+    )
+

apps/eu-ai-act-agent/src/gradio_app.py

@@ -0,0 +1,1502 @@
+#!/usr/bin/env python3
+"""
+EU AI Act Compliance Agent - Gradio UI
+Interactive web interface for EU AI Act compliance assessment
+With MCP tool call visualization and multi-model support
+"""
+
+import gradio as gr
+from gradio import ChatMessage
+import requests
+import json
+import os
+import threading
+from pathlib import Path
+from typing import List, Generator, Optional
+from dotenv import load_dotenv
+
+# Load environment variables from root .env file
+ROOT_DIR = Path(__file__).parent.parent.parent.parent  # Go up from src -> eu-ai-act-agent -> apps -> root
+load_dotenv(ROOT_DIR / ".env")
+
+# API Configuration
+API_URL = os.getenv("API_URL", "http://localhost:3001")
+PUBLIC_URL = os.getenv("PUBLIC_URL", "")  # HF Spaces public URL (empty for local dev)
+API_TIMEOUT = 600  # seconds - increased for long-running compliance assessments
+
+def get_mcp_url() -> str:
+    """Get the MCP server URL based on environment"""
+    if PUBLIC_URL:
+        # Production: MCP is on the same server via chatgpt_app.py
+        return f"{PUBLIC_URL.rstrip('/')}/gradio_api/mcp/"
+    return ""
+
+# Model Configuration
+AVAILABLE_MODELS = {
+    "gpt-oss": {
+        "name": "🆓 GPT-OSS 20B (Modal - FREE)",
+        "api_key_env": "MODAL_ENDPOINT_URL",
+        "description": "Free OpenAI GPT-OSS 20B model hosted on Modal.com - No API key required! ⚠️ May take up to 60s to start responding (cold start). For faster responses and better precision, use another model with your API key."
+    },
+    "claude-4.5": {
+        "name": "Claude 4.5 Sonnet (Anthropic)",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "description": "Anthropic's latest Claude Sonnet model"
+    },
+    "claude-opus": {
+        "name": "Claude Opus 4 (Anthropic)",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "description": "Anthropic's most powerful Claude model"
+    },
+    "gemini-3": {
+        "name": "Gemini 3 Pro (Google)",
+        "api_key_env": "GOOGLE_GENERATIVE_AI_API_KEY",
+        "description": "Google's advanced reasoning model with thinking"
+    },
+    "gpt-5": {
+        "name": "GPT-5 (OpenAI)",
+        "api_key_env": "OPENAI_API_KEY",
+        "description": "OpenAI's most advanced model"
+    },
+    "grok-4-1": {
+        "name": "Grok 4.1 (xAI)",
+        "api_key_env": "XAI_API_KEY",
+        "description": "xAI's fast reasoning model"
+    },
+}
+
+# Current model settings (can be updated via UI)
+# SECURITY: Store user-provided keys for this session only
+# NOTE: API keys are REQUIRED for paid models - GPT-OSS is FREE!
+# IMPORTANT: Always default to gpt-oss (FREE model) regardless of env var
+# The env var might be set for the API server, but the UI should default to FREE model
+current_model_settings = {
+    "model": "gpt-oss",  # Always default to FREE GPT-OSS model in UI!
+    # User-provided keys (REQUIRED for paid models, optional for GPT-OSS)
+    "openai_api_key": "",
+    "xai_api_key": "",
+    "anthropic_api_key": "",
+    "google_api_key": "",  # Google Generative AI API key
+    "tavily_api_key": "",  # Required for web research & organization discovery
+    "modal_endpoint_url": "https://vasilis--gpt-oss-vllm-inference-serve.modal.run"  # Hardcoded Modal.com endpoint for GPT-OSS (no trailing slash!)
+}
+
+# Thread-safe cancellation flag for stopping ongoing requests
+class CancellationToken:
+    def __init__(self):
+        self._cancelled = False
+        self._lock = threading.Lock()
+        self._response = None
+    
+    def cancel(self):
+        with self._lock:
+            self._cancelled = True
+            # Close any active response to stop streaming
+            if self._response is not None:
+                try:
+                    self._response.close()
+                except:
+                    pass
+    
+    def is_cancelled(self):
+        with self._lock:
+            return self._cancelled
+    
+    def set_response(self, response):
+        with self._lock:
+            self._response = response
+    
+    def reset(self):
+        with self._lock:
+            self._cancelled = False
+            self._response = None
+
+# Global cancellation token
+cancel_token = CancellationToken()
+
+def format_tool_call(tool_name: str, args: dict) -> str:
+    """Format a tool call for display"""
+    args_str = json.dumps(args, indent=2) if args else "{}"
+    return f"""
+🔧 **MCP Tool Call: `{tool_name}`**
+
+**Arguments:**
+```json
+{args_str}
+```
+"""
+
+def format_thinking_section(thinking_text: str, tool_name: str = None) -> str:
+    """Format AI thinking/reasoning in a collapsible section"""
+    if not thinking_text or not thinking_text.strip():
+        return ""
+    
+    # Clean up the thinking text
+    thinking_clean = thinking_text.strip()
+    
+    # Create a descriptive title based on context
+    if tool_name:
+        title = f"🧠 AI Reasoning (before {tool_name.replace('_', ' ').title()})"
+    else:
+        title = "🧠 AI Reasoning"
+    
+    return f"""
+<details>
+<summary>{title}</summary>
+
+*The model's thought process:*
+
+{thinking_clean}
+
+</details>
+"""
+
+def format_tool_result(tool_name: str, result) -> str:
+    """Format a tool result for display"""
+    
+    # Special handling for assess_compliance - show generated documentation with full content
+    if tool_name == "assess_compliance" and result:
+        output = f"\n✅ **Tool Result: `{tool_name}`**\n\n"
+        
+        # Extract key information
+        assessment = result.get("assessment", {})
+        metadata = result.get("metadata", {})
+        documentation = result.get("documentation", {})
+        reasoning = result.get("reasoning", "")
+        doc_files = metadata.get("documentationFiles", [])
+        
+        # Show assessment summary
+        if assessment:
+            score = assessment.get("overallScore", "N/A")
+            risk_level = assessment.get("riskLevel", "N/A")
+            gaps = assessment.get("gaps", [])
+            recommendations = assessment.get("recommendations", [])
+            gaps_count = len(gaps)
+            recs_count = len(recommendations)
+            
+            # Risk level emoji
+            risk_emoji = {"CRITICAL": "🔴", "HIGH": "🟠", "MEDIUM": "🟡", "LOW": "🟢"}.get(risk_level, "⚪")
+            
+            output += f"""### 📊 Compliance Assessment Summary
+
+| Metric | Value |
+|--------|-------|
+| **Overall Score** | **{score}/100** |
+| **Risk Level** | {risk_emoji} **{risk_level}** |
+| **Gaps Identified** | {gaps_count} |
+| **Recommendations** | {recs_count} |
+
+"""
+            
+            # Show AI reasoning in collapsible section
+            if reasoning:
+                output += f"""
+<details>
+<summary>🧠 AI Reasoning & Analysis</summary>
+
+{reasoning}
+
+</details>
+
+"""
+            
+            # Show gaps summary in collapsible section
+            if gaps:
+                critical_gaps = [g for g in gaps if g.get("severity") == "CRITICAL"]
+                high_gaps = [g for g in gaps if g.get("severity") == "HIGH"]
+                
+                output += f"""
+<details>
+<summary>⚠️ Compliance Gaps ({gaps_count} total: {len(critical_gaps)} Critical, {len(high_gaps)} High)</summary>
+
+"""
+                # Group by severity
+                for severity in ["CRITICAL", "HIGH", "MEDIUM", "LOW"]:
+                    severity_gaps = [g for g in gaps if g.get("severity") == severity]
+                    if severity_gaps:
+                        severity_emoji = {"CRITICAL": "🔴", "HIGH": "🟠", "MEDIUM": "🟡", "LOW": "🟢"}.get(severity, "⚪")
+                        output += f"\n**{severity_emoji} {severity} Priority Gaps:**\n\n"
+                        for gap in severity_gaps:
+                            output += f"- **{gap.get('category', 'Unknown')}**: {gap.get('description', 'No description')}\n"
+                            output += f"  - *Article:* {gap.get('articleReference', 'N/A')} | *Effort:* {gap.get('remediationEffort', 'N/A')}\n"
+                
+                output += "\n</details>\n\n"
+            
+            # Show top recommendations in collapsible section
+            if recommendations:
+                # Sort by priority
+                sorted_recs = sorted(recommendations, key=lambda r: r.get("priority", 10))
+                top_recs = sorted_recs[:5]
+                
+                output += f"""
+<details>
+<summary>💡 Priority Recommendations (Top {len(top_recs)} of {recs_count})</summary>
+
+"""
+                for i, rec in enumerate(top_recs, 1):
+                    output += f"\n**{i}. {rec.get('title', 'Recommendation')}** (Priority: {rec.get('priority', 'N/A')}/10)\n\n"
+                    output += f"{rec.get('description', 'No description')}\n\n"
+                    output += f"- *Article:* {rec.get('articleReference', 'N/A')}\n"
+                    output += f"- *Estimated Effort:* {rec.get('estimatedEffort', 'N/A')}\n"
+                    
+                    steps = rec.get("implementationSteps", [])
+                    if steps:
+                        output += f"- *Implementation Steps:*\n"
+                        for step in steps[:3]:  # Show first 3 steps
+                            output += f"  1. {step}\n"
+                        if len(steps) > 3:
+                            output += f"  *(+ {len(steps) - 3} more steps)*\n"
+                    output += "\n"
+                
+                output += "</details>\n\n"
+        
+        # Show generated documentation content in collapsible sections
+        output += "---\n\n### 📄 Generated EU AI Act Documentation\n\n"
+        
+        # Map of documentation keys to display info
+        doc_display_map = {
+            "riskManagementTemplate": {
+                "title": "Risk Management System",
+                "article": "Article 9",
+                "emoji": "⚡",
+                "description": "Continuous risk identification, analysis, estimation and mitigation process"
+            },
+            "technicalDocumentation": {
+                "title": "Technical Documentation",
+                "article": "Article 11 / Annex IV",
+                "emoji": "📋",
+                "description": "Comprehensive technical documentation for high-risk AI systems"
+            },
+            "conformityAssessment": {
+                "title": "Conformity Assessment",
+                "article": "Article 43",
+                "emoji": "✅",
+                "description": "Procedures for conformity assessment of high-risk AI systems"
+            },
+            "transparencyNotice": {
+                "title": "Transparency Notice",
+                "article": "Article 50",
+                "emoji": "👁️",
+                "description": "Transparency obligations for AI system interactions"
+            },
+            "qualityManagementSystem": {
+                "title": "Quality Management System",
+                "article": "Article 17",
+                "emoji": "🏆",
+                "description": "Quality management system for AI system providers"
+            },
+            "humanOversightProcedure": {
+                "title": "Human Oversight Procedure",
+                "article": "Article 14",
+                "emoji": "👤",
+                "description": "Human oversight measures for high-risk AI systems"
+            },
+            "dataGovernancePolicy": {
+                "title": "Data Governance Policy",
+                "article": "Article 10",
+                "emoji": "🗃️",
+                "description": "Data and data governance practices for training, validation and testing"
+            },
+            "incidentReportingProcedure": {
+                "title": "Incident Reporting Procedure",
+                "article": "Article 62",
+                "emoji": "🚨",
+                "description": "Reporting of serious incidents and malfunctioning"
+            },
+        }
+        
+        # Display each documentation template in its own collapsible section
+        docs_found = 0
+        for doc_key, doc_info in doc_display_map.items():
+            doc_content = documentation.get(doc_key)
+            if doc_content:
+                docs_found += 1
+                output += f"""
+<details>
+<summary>{doc_info['emoji']} **{doc_info['title']}** — {doc_info['article']}</summary>
+
+*{doc_info['description']}*
+
+---
+
+{doc_content}
+
+</details>
+
+"""
+        
+        if docs_found == 0:
+            output += "*No documentation templates were generated in this assessment.*\n\n"
+        else:
+            output += f"\n> ✨ **{docs_found} documentation template(s) generated.** Expand each section above to view the full content.\n\n"
+            
+            # Note about limited templates for speed/cost optimization
+            if docs_found < 8:
+                output += "> ℹ️ **Note:** Currently generating **2 core templates** (Risk Management & Technical Documentation) for faster responses and API cost optimization. Additional templates (Conformity Assessment, Transparency Notice, etc.) are planned for future releases.\n\n"
+        
+        # Show file paths if documents were saved to disk
+        if doc_files:
+            output += "---\n\n### 💾 Saved Documentation Files\n\n"
+            output += "The documentation has also been saved to disk:\n\n"
+            
+            # Map filenames to EU AI Act articles for context
+            article_map = {
+                "Risk_Management_System": "Article 9",
+                "Technical_Documentation": "Article 11 / Annex IV",
+                "Conformity_Assessment": "Article 43",
+                "Transparency_Notice": "Article 50",
+                "Quality_Management_System": "Article 17",
+                "Human_Oversight_Procedure": "Article 14",
+                "Data_Governance_Policy": "Article 10",
+                "Incident_Reporting_Procedure": "Article 62",
+                "Compliance_Assessment_Report": "Full Assessment",
+            }
+            
+            output += "| Document | EU AI Act Reference | File Path |\n"
+            output += "|----------|--------------------|-----------|\n"
+            
+            for file_path in doc_files:
+                # Extract filename from path
+                filename = file_path.split("/")[-1] if "/" in file_path else file_path
+                # Remove .md extension for display name
+                display_name = filename.replace(".md", "").replace("_", " ")
+                # Remove leading numbers like "01_" or "00_"
+                if len(display_name) > 3 and display_name[:2].isdigit() and display_name[2] == " ":
+                    display_name = display_name[3:]
+                
+                # Find article reference
+                article_ref = "—"
+                for key, article in article_map.items():
+                    if key.lower().replace("_", " ") in display_name.lower():
+                        article_ref = article
+                        break
+                
+                output += f"| 📄 {display_name} | {article_ref} | `{filename}` |\n"
+            
+            # Show the directory where files are saved
+            if doc_files:
+                docs_dir = "/".join(doc_files[0].split("/")[:-1])
+                output += f"\n**📂 Documents Directory:** `{docs_dir}`\n\n"
+        
+        # Collapsible raw JSON for reference (at the very end)
+        result_str = json.dumps(result, indent=2) if result else "null"
+        if len(result_str) > 5000:
+            result_str = result_str[:5000] + "\n... (truncated)"
+        
+        output += f"""
+---
+
+<details>
+<summary>🔍 View Raw JSON Response</summary>
+
+```json
+{result_str}
+```
+
+</details>
+"""
+        return output
+    
+    # Default formatting for other tools
+    result_str = json.dumps(result, indent=2) if result else "null"
+    if len(result_str) > 1500:
+        result_str = result_str[:1500] + "\n... (truncated)"
+    
+    return f"""
+✅ **Tool Result: `{tool_name}`**
+
+<details>
+<summary>📋 Click to expand result</summary>
+
+```json
+{result_str}
+```
+
+</details>
+"""
+
+def format_thinking_indicator(tool_name: str = None) -> str:
+    """Format a thinking/processing indicator"""
+    if tool_name:
+        # Show specific tool name if available
+        tool_display_name = {
+            "assess_compliance": "EU AI Act Compliance Assessment",
+            "discover_ai_services": "AI Systems Discovery",
+            "discover_organization": "Organization Discovery"
+        }.get(tool_name, tool_name.replace("_", " ").title())
+        
+        return f"\n\n⏳ **Processing: {tool_display_name}...**\n\n*This may take a moment while the tool analyzes data and generates documentation.*\n"
+    return "\n\n⏳ **Processing with MCP tools...**\n\n*Please wait while the tools execute...*\n"
+
+def get_api_headers() -> dict:
+    """Get headers with model configuration for API requests
+    
+    SECURITY: Only pass model selection and user-provided API keys.
+    API keys are REQUIRED for paid models - GPT-OSS is FREE!
+    User must provide their own keys via the Model Settings UI (except for GPT-OSS).
+    """
+    headers = {"Content-Type": "application/json"}
+    
+    # Pass model selection - always use the current model setting
+    selected_model = current_model_settings.get("model", "gpt-oss")
+    headers["X-AI-Model"] = selected_model
+    print(f"[Gradio] Sending model to API: {selected_model}")
+    
+    # Pass user-provided API keys based on selected model
+    model = current_model_settings["model"]
+    if model == "gpt-oss":
+        # GPT-OSS uses hardcoded Modal endpoint URL (FREE - no API key required!)
+        headers["X-Modal-Endpoint-URL"] = current_model_settings["modal_endpoint_url"]
+    elif model == "gpt-5" and current_model_settings["openai_api_key"]:
+        headers["X-OpenAI-API-Key"] = current_model_settings["openai_api_key"]
+    elif model == "grok-4-1" and current_model_settings["xai_api_key"]:
+        headers["X-XAI-API-Key"] = current_model_settings["xai_api_key"]
+    elif model in ["claude-4.5", "claude-opus"] and current_model_settings["anthropic_api_key"]:
+        headers["X-Anthropic-API-Key"] = current_model_settings["anthropic_api_key"]
+    elif model == "gemini-3" and current_model_settings["google_api_key"]:
+        headers["X-Google-API-Key"] = current_model_settings["google_api_key"]
+    
+    # Tavily API key for web research (optional - AI model used as fallback)
+    if current_model_settings["tavily_api_key"]:
+        headers["X-Tavily-API-Key"] = current_model_settings["tavily_api_key"]
+    
+    return headers
+
+def chat_with_agent_streaming(message: str, history: list, initialized_history: list = None) -> Generator:
+    """
+    Send a message to the EU AI Act agent and stream the response with tool calls
+    
+    Args:
+        message: User's input message
+        history: Original chat history for API (without current user message)
+        initialized_history: Pre-initialized history with user message and loading (optional)
+        
+    Yields:
+        Updated history with streaming content
+    """
+    global cancel_token
+    
+    if not message.strip():
+        yield initialized_history or history
+        return
+    
+    # Reset cancellation token for new request
+    cancel_token.reset()
+    
+    # Use pre-initialized history or create one
+    if initialized_history:
+        new_history = list(initialized_history)
+    else:
+        new_history = list(history) + [
+            ChatMessage(role="user", content=message),
+            ChatMessage(role="assistant", content="⏳ *Thinking...*")
+        ]
+    
+    response = None
+    bot_response = ""
+    tool_calls_content = ""  # All tool calls, results, and thinking sections (in order)
+    current_thinking = ""  # Accumulate thinking text before tool calls
+    
+    try:
+        # Convert original history to API format (handle both ChatMessage and dict)
+        api_history = []
+        for msg in history:
+            if isinstance(msg, dict):
+                api_history.append({"role": msg.get("role", "user"), "content": msg.get("content", "")})
+            else:
+                api_history.append({"role": msg.role, "content": msg.content})
+        
+        # Make streaming request to API with model configuration headers
+        response = requests.post(
+            f"{API_URL}/api/chat",
+            json={"message": message, "history": api_history},
+            headers=get_api_headers(),
+            stream=True,
+            timeout=API_TIMEOUT,
+        )
+        
+        # Register response for potential cancellation
+        cancel_token.set_response(response)
+        
+        if response.status_code != 200:
+            error_msg = f"⚠️ Error: API returned status {response.status_code}"
+            new_history[-1] = ChatMessage(role="assistant", content=error_msg)
+            yield new_history
+            return
+        
+        # Initialize assistant response
+        current_tool_call = None
+        
+        for line in response.iter_lines():
+            # Check for cancellation
+            if cancel_token.is_cancelled():
+                # Include any accumulated thinking before cancellation
+                if current_thinking.strip():
+                    tool_calls_content += format_thinking_section(current_thinking)
+                
+                final_content = tool_calls_content + bot_response
+                if final_content:
+                    final_content += "\n\n*— Execution stopped by user*"
+                else:
+                    final_content = "*— Execution stopped by user*"
+                new_history[-1] = ChatMessage(role="assistant", content=final_content)
+                yield new_history
+                return
+            
+            if line:
+                line_str = line.decode('utf-8')
+                print(f"[DEBUG] Received: {line_str[:100]}...")  # Debug log
+                if line_str.startswith('data: '):
+                    try:
+                        data = json.loads(line_str[6:])  # Remove 'data: ' prefix
+                        event_type = data.get("type")
+                        print(f"[DEBUG] Event type: {event_type}, data: {str(data)[:100]}")
+                        
+                        if event_type == "thinking":
+                            # Handle thinking/reasoning tokens from Claude or GPT
+                            # Show thinking at the END (bottom) where action is happening
+                            thinking_content = data.get("content", "")
+                            if thinking_content:
+                                current_thinking += thinking_content
+                                
+                                # Show thinking tokens in real-time AT THE BOTTOM
+                                # Tool calls first, then current thinking at the end
+                                live_thinking = f"\n\n🧠 **Model Thinking (live):**\n\n```\n{current_thinking}\n```"
+                                full_content = tool_calls_content + live_thinking
+                                
+                                new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                                yield new_history
+                        
+                        elif event_type == "text":
+                            # Append text chunk
+                            text_content = data.get("content", "")
+                            text_phase = data.get("phase", "thinking")  # Server tells us the phase
+                            has_had_tools = data.get("hasHadToolCalls", False)
+                            
+                            # Determine if this is "thinking" text or final response based on server phase
+                            if text_phase == "thinking" or (not has_had_tools and not tool_calls_content):
+                                # This is thinking text (before tool calls or between them)
+                                current_thinking += text_content
+                                
+                                # Show thinking AT THE BOTTOM after tool calls
+                                if not tool_calls_content:
+                                    # Initial thinking - show with brain indicator
+                                    display_content = f"🧠 **AI is reasoning...**\n\n{current_thinking}"
+                                else:
+                                    # Thinking between tool calls - show at the end
+                                    display_content = tool_calls_content + f"\n\n🧠 *Reasoning:* {current_thinking}"
+                                
+                                new_history[-1] = ChatMessage(role="assistant", content=display_content)
+                            else:
+                                # This is "potential_response" - text after tool results
+                                # Could be final response OR thinking before another tool call
+                                # We accumulate it and will format appropriately when we know more
+                                current_thinking += text_content
+                                
+                                # Show as streaming response AT THE BOTTOM
+                                full_content = tool_calls_content + f"\n\n{current_thinking}"
+                                new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            
+                            yield new_history
+                            
+                        elif event_type == "tool_call":
+                            # Before showing tool call, save any accumulated thinking as collapsible
+                            tool_name = data.get("toolName", "unknown")
+                            args = data.get("args", {})
+                            
+                            # If we have accumulated thinking text, add it as collapsible BEFORE this tool call
+                            if current_thinking.strip():
+                                tool_calls_content += format_thinking_section(current_thinking, tool_name)
+                                current_thinking = ""  # Reset for next thinking block
+                            else:
+                                # No thinking text was output - add a synthetic thinking note
+                                tool_display = tool_name.replace('_', ' ').title()
+                                synthetic_thinking = f"I'll use the **{tool_display}** tool to gather the necessary information."
+                                tool_calls_content += format_thinking_section(synthetic_thinking, tool_name)
+                            
+                            # Show tool call with prominent loading indicator AT THE BOTTOM
+                            tool_calls_content += format_tool_call(tool_name, args)
+                            # Add prominent loading indicator specific to this tool
+                            loading_indicator = format_thinking_indicator(tool_name)
+                            full_content = tool_calls_content + bot_response + loading_indicator
+                            new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            yield new_history
+                            current_tool_call = tool_name
+                            
+                        elif event_type == "tool_result":
+                            # Show tool result (removes loading indicator)
+                            tool_name = data.get("toolName", current_tool_call or "unknown")
+                            result = data.get("result")
+                            tool_calls_content += format_tool_result(tool_name, result)
+                            
+                            # After tool result, show "analyzing results" indicator AT THE BOTTOM
+                            analyzing_indicator = f"\n\n🧠 **Analyzing {tool_name.replace('_', ' ')} results...**\n"
+                            full_content = tool_calls_content + analyzing_indicator
+                            new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            yield new_history
+                            current_tool_call = None
+                            
+                        elif event_type == "step_finish":
+                            # Step completed - if there's accumulated thinking, add it to tool_calls_content
+                            has_had_tools_in_step = data.get("hasHadToolCalls", False)
+                            
+                            if current_thinking.strip():
+                                tool_calls_content += format_thinking_section(current_thinking)
+                                current_thinking = ""
+                            
+                            # Show "preparing response" if we had tool calls and step is finishing AT THE BOTTOM
+                            if has_had_tools_in_step and tool_calls_content:
+                                preparing_indicator = "\n\n✨ **Preparing comprehensive response based on analysis...**\n"
+                                full_content = tool_calls_content + preparing_indicator
+                            else:
+                                full_content = tool_calls_content + bot_response
+                            
+                            new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            yield new_history
+                            
+                        elif event_type == "error":
+                            error_msg = data.get("error", "Unknown error")
+                            bot_response += f"\n\n⚠️ Error: {error_msg}"
+                            full_content = tool_calls_content + bot_response
+                            new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            yield new_history
+                            
+                        elif event_type == "done":
+                            # Final update
+                            # If we have tool calls, any remaining current_thinking is the final response
+                            # If no tool calls, current_thinking was just direct response (no tools needed)
+                            if tool_calls_content:
+                                # We had tool calls - current_thinking after last tool is the final response
+                                bot_response = current_thinking
+                                current_thinking = ""
+                            else:
+                                # No tool calls - current_thinking is the direct response
+                                bot_response = current_thinking
+                                current_thinking = ""
+                            
+                            # Final response AT THE BOTTOM after all tool calls
+                            full_content = tool_calls_content + bot_response
+                            new_history[-1] = ChatMessage(role="assistant", content=full_content)
+                            yield new_history
+                            break
+                            
+                    except json.JSONDecodeError:
+                        continue
+        
+        # Ensure final state (only if not cancelled)
+        if not cancel_token.is_cancelled():
+            # If we have accumulated text that wasn't finalized, treat it as the response
+            if current_thinking.strip() and not bot_response:
+                bot_response = current_thinking
+            
+            # Final content: tool calls first, then response at the bottom
+            final_content = tool_calls_content + (bot_response or "No response generated.")
+            new_history[-1] = ChatMessage(role="assistant", content=final_content)
+            yield new_history
+        
+    except requests.exceptions.ConnectionError:
+        if not cancel_token.is_cancelled():
+            error_msg = "⚠️ Cannot connect to API server. Make sure it's running on http://localhost:3001"
+            new_history[-1] = ChatMessage(role="assistant", content=error_msg)
+            yield new_history
+    except requests.exceptions.Timeout:
+        if not cancel_token.is_cancelled():
+            error_msg = "⚠️ Request timed out. The agent might be processing a complex query."
+            final_content = tool_calls_content + bot_response + "\n\n" + error_msg
+            new_history[-1] = ChatMessage(role="assistant", content=final_content)
+            yield new_history
+    except (requests.exceptions.ChunkedEncodingError, ConnectionError):
+        # This can happen when we close the connection during cancellation - it's expected
+        if not cancel_token.is_cancelled():
+            error_msg = "⚠️ Connection was interrupted."
+            final_content = tool_calls_content + bot_response + "\n\n" + error_msg
+            new_history[-1] = ChatMessage(role="assistant", content=final_content)
+            yield new_history
+    except Exception as e:
+        if not cancel_token.is_cancelled():
+            error_msg = f"⚠️ Error: {str(e)}"
+            final_content = tool_calls_content + bot_response + "\n\n" + error_msg if (tool_calls_content or bot_response) else error_msg
+            new_history[-1] = ChatMessage(role="assistant", content=final_content)
+            yield new_history
+    finally:
+        # Clean up the response connection
+        if response is not None:
+            try:
+                response.close()
+            except:
+                pass
+        cancel_token.set_response(None)
+
+def check_api_status() -> str:
+    """Check if the API server is running"""
+    try:
+        response = requests.get(f"{API_URL}/health", timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            return f"✅ API Server: {data.get('service')} v{data.get('version')}"
+        else:
+            return f"⚠️ API Server returned status {response.status_code}"
+    except requests.exceptions.ConnectionError:
+        return "❌ API Server not running. Start it with: pnpm dev"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+def get_available_tools() -> str:
+    """Get list of available MCP tools with descriptions"""
+    try:
+        response = requests.get(f"{API_URL}/api/tools", timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            tools = data.get("tools", [])
+            if tools:
+                tool_list = "\n".join([f"• **{t['name']}**" for t in tools])
+                return f"""**Available MCP Tools:**
+
+{tool_list}
+
+**✨ Capabilities:**
+• Generate complete compliance reports
+• Create documentation templates (Risk Management, Technical Docs, etc.)
+• Discover AI systems and assess risk levels
+• Analyze organization compliance gaps"""
+            return "No tools available"
+        return "Could not fetch tools"
+    except:
+        return "Could not connect to API"
+
+def get_example_queries() -> List[List[str]]:
+    """Get example queries for the interface"""
+    return [
+        # MCP Tools Examples - Showcase full compliance analysis capabilities
+        ["Generate a complete EU AI Act compliance report for Microsoft with all documentation templates"],
+        ["Analyze IBM's watsonX system compliance and generate risk management documentation"],
+        ["Create full compliance assessment for OpenAI including technical documentation templates"],
+        # General Questions
+        ["What is the EU AI Act?"],
+        ["Is a recruitment screening AI considered high-risk?"],
+        ["What are the compliance requirements for chatbots?"],
+        ["What's the timeline for EU AI Act enforcement?"],
+    ]
+
+# Default browser state for persistent storage
+DEFAULT_BROWSER_STATE = {
+    "api_keys": {
+        "tavily": "",
+        "anthropic": "",
+        "google": "",
+        "openai": "",
+        "xai": ""
+    },
+    "model": "gpt-oss"
+}
+
+# Create Gradio interface
+with gr.Blocks(
+    title="🇪🇺 EU AI Act Compliance Agent",
+) as demo:
+    # Browser state for persistent storage (persists across page refreshes)
+    browser_state = gr.BrowserState(DEFAULT_BROWSER_STATE)
+    
+    # Custom CSS only - JavaScript is loaded via gr.Blocks(js=...) parameter
+    gr.HTML("""
+    <style>
+    /* Hide Gradio's default footer */
+    footer { display: none !important; }
+    .gradio-container footer { display: none !important; }
+    .footer { display: none !important; }
+    [data-testid="footer"] { display: none !important; }
+    
+    /* Style the stop button */
+    button.stop {
+        background-color: #dc3545 !important;
+        border-color: #dc3545 !important;
+    }
+    button.stop:hover {
+        background-color: #c82333 !important;
+        border-color: #bd2130 !important;
+    }
+    
+    /* Scroll indicator when user has scrolled up */
+    .scroll-indicator {
+        position: absolute;
+        bottom: 10px;
+        right: 20px;
+        background: rgba(0, 0, 0, 0.7);
+        color: white;
+        padding: 8px 16px;
+        border-radius: 20px;
+        font-size: 12px;
+        cursor: pointer;
+        z-index: 1000;
+        display: none;
+    }
+    .scroll-indicator:hover {
+        background: rgba(0, 0, 0, 0.9);
+    }
+    
+    /* Keys loaded indicator */
+    .keys-loaded-badge {
+        display: inline-block;
+        background: #28a745;
+        color: white;
+        padding: 2px 8px;
+        border-radius: 12px;
+        font-size: 11px;
+        margin-left: 8px;
+    }
+    </style>
+    """)
+    
+    # Header - use PUBLIC_URL for production links
+    # In production (HF Spaces): Show info about gradio.live URL
+    # In local dev: Direct link to localhost:7861
+    chatgpt_link_href = PUBLIC_URL if PUBLIC_URL else "http://localhost:7861"
+    is_production = bool(PUBLIC_URL)
+    
+    # Get MCP URL (written by chatgpt_app.py when it starts)
+    mcp_url = get_mcp_url()
+    
+    # MCP Server is deployed separately
+    MCP_SPACE_URL = "https://mcp-1st-birthday-eu-ai-act-chatgpt-mcp.hf.space"
+    MCP_URL = f"{MCP_SPACE_URL}/gradio_api/mcp/"
+    
+    if is_production:
+        # Production: Link to separate MCP Space
+        chatgpt_section = f"""
+            <a href="{MCP_SPACE_URL}" target="_blank" style="text-decoration: none;">
+                <div style="background: linear-gradient(135deg, #4CAF50 0%, #45a049 100%); padding: 12px 20px; border-radius: 10px; display: inline-block;">
+                    <span style="color: #fff; font-size: 0.9em;">
+                        💬 <strong>ChatGPT MCP Server</strong>
+                    </span>
+                    <p style="color: rgba(255,255,255,0.9); font-size: 0.75em; margin: 8px 0 0 0; word-break: break-all;">
+                        <code style="background: rgba(255,255,255,0.2); padding: 3px 6px; border-radius: 3px;">{MCP_URL}</code>
+                    </p>
+                    <p style="color: rgba(255,255,255,0.7); font-size: 0.7em; margin: 6px 0 0 0;">
+                        Click to open MCP Server Space →
+                    </p>
+                </div>
+            </a>
+        """
+    else:
+        # Local dev: Direct link
+        chatgpt_section = """
+            <a href="http://localhost:7861" target="_blank" style="color: #2196F3; text-decoration: none; padding: 6px 12px; border: 1px solid #2196F3; border-radius: 4px; display: inline-block;">
+                💬 Open ChatGPT App (MCP Server)
+            </a>
+        """
+    
+    gr.HTML(f"""
+        <div style="text-align: center; padding: 20px 0;">
+            <h1 style="margin: 0; font-size: 2em;">🇪🇺 EU AI Act Compliance Agent</h1>
+            <p style="margin: 10px 0 0 0; opacity: 0.8;">by <a href="https://www.legitima.ai/mcp-hackathon" target="_blank" style="color: #4CAF50;">Legitima.ai</a></p>
+            <p style="margin: 5px 0; font-size: 0.9em; opacity: 0.7;">Your intelligent assistant for navigating European AI regulation</p>
+            <p style="margin: 10px 0 0 0; font-size: 0.9em;">
+                {chatgpt_section}
+            </p>
+        </div>
+    """)
+    
+    # Main content
+    with gr.Row():
+        with gr.Column(scale=3):
+            # Chat interface - using ChatMessage format
+            chatbot = gr.Chatbot(
+                label="Chat with EU AI Act Expert",
+                height=550,
+                show_label=True,
+                autoscroll=False,  # Disable auto-scroll - we handle it with JS
+            )
+            
+            with gr.Row():
+                msg = gr.Textbox(
+                    placeholder="Ask about compliance, or request a full compliance report with documentation for an organization...",
+                    show_label=False,
+                    scale=8,
+                )
+                submit = gr.Button("Send", variant="primary", scale=1)
+                stop_btn = gr.Button("⏹ Stop", variant="stop", scale=1, visible=False)
+            
+            gr.Examples(
+                examples=get_example_queries(),
+                inputs=msg,
+                label="💡 Example Questions (Try MCP tools for compliance reports & documentation!)",
+            )
+        
+        with gr.Column(scale=1):
+            # Sidebar
+            gr.Markdown("### 🤖 Model Settings")
+            
+            model_dropdown = gr.Dropdown(
+                choices=[(v["name"], k) for k, v in AVAILABLE_MODELS.items()],
+                value=current_model_settings["model"],  # Use current model setting
+                label="AI Model",
+                info="Select the AI model to use. ⚠️ GPT-OSS is FREE but may take up to 60s to start (cold start). For faster responses and better precision, use another model with your API key.",
+                elem_id="model_dropdown"
+            )
+            
+            # API Key inputs (password fields) - GPT-OSS is FREE, other models require API keys
+            with gr.Accordion("🔑 API Keys & Settings", open=True):
+                gr.Markdown("""🆓 **GPT-OSS 20B is FREE** - Uses pre-configured Modal endpoint (no setup required).
+
+⏱️ **Note:** GPT-OSS may take up to **60 seconds** to start responding due to cold start. For **faster responses and better precision**, select another model and provide your API key below.
+
+⚠️ For paid models (Claude, GPT-5, Gemini, Grok), an API key is required.
+
+🔐 Keys are stored securely in encoded cookies and **auto-expire after 24 hours**.
+
+ℹ️ *Tavily is **optional** - enhances web research for organization & AI systems discovery. Falls back to server's `TAVILY_API_KEY` env var if not provided, then to AI model.*""")
+                
+                gr.Markdown("#### 🔍 Research API (Optional)")
+                tavily_key = gr.Textbox(
+                    label="Tavily API Key (Optional)",
+                    placeholder="tvly-... (optional - enhances web research)",
+                    type="password",
+                    value="",  # Will be populated from cookies via JS
+                    info="Optional - uses server env var fallback, then AI model.",
+                    elem_id="tavily_key_input"
+                )
+                
+                gr.Markdown("#### 🤖 AI Model APIs")
+                anthropic_key = gr.Textbox(
+                    label="Anthropic API Key *",
+                    placeholder="sk-ant-... (required for Claude models)",
+                    type="password",
+                    value="",  # Will be populated from cookies via JS
+                    info="Required - for Claude 4.5 Sonnet or Claude Opus 4",
+                    elem_id="anthropic_key_input"
+                )
+                google_key = gr.Textbox(
+                    label="Google API Key",
+                    placeholder="AIza... (required for Gemini 3)",
+                    type="password",
+                    value="",  # Will be populated from cookies via JS
+                    info="Required if using Gemini 3 Pro model",
+                    elem_id="google_key_input"
+                )
+                openai_key = gr.Textbox(
+                    label="OpenAI API Key",
+                    placeholder="sk-... (required for GPT-5)",
+                    type="password",
+                    value="",  # Will be populated from cookies via JS
+                    info="Required if using GPT-5 model",
+                    elem_id="openai_key_input"
+                )
+                xai_key = gr.Textbox(
+                    label="xAI API Key",
+                    placeholder="xai-... (required for Grok 4.1)",
+                    type="password",
+                    value="",  # Will be populated from cookies via JS
+                    info="Required if using Grok 4.1 model",
+                    elem_id="xai_key_input"
+                )
+                with gr.Row():
+                    save_keys_btn = gr.Button("💾 Save Keys", variant="secondary", size="sm")
+                    clear_keys_btn = gr.Button("🗑️ Clear Keys", variant="stop", size="sm")
+                keys_status = gr.Markdown("")
+            
+            gr.Markdown("---")
+            
+            gr.Markdown("### 📊 Quick Reference")
+            
+            gr.Markdown("""
+**Risk Categories:**
+- 🔴 **Unacceptable** - Banned
+- 🟠 **High Risk** - Strict requirements
+- 🟡 **Limited Risk** - Transparency
+- 🟢 **Minimal Risk** - No obligations
+
+**Key Deadlines:**
+- 📅 Feb 2, 2025: Banned AI
+- 📅 Aug 2, 2026: High-risk rules
+- 📅 Aug 2, 2027: Full enforcement
+            """)
+            
+            gr.Markdown("---")
+            
+            tools_info = gr.Markdown(
+                value=get_available_tools(),
+                label="🔧 MCP Tools - Generate Reports & Documentation"
+            )
+            
+            gr.Markdown("---")
+            
+            # Sidebar ChatGPT App section
+            if is_production:
+                sidebar_chatgpt = f"""
+                <a href="{MCP_SPACE_URL}" target="_blank" style="text-decoration: none;">
+                    <div style="background: linear-gradient(135deg, #4CAF50 0%, #45a049 100%); padding: 12px; border-radius: 8px; margin: 5px 0;">
+                        <strong style="color: #fff;">💬 MCP Server</strong>
+                        <p style="color: rgba(255,255,255,0.9); font-size: 0.7em; margin: 6px 0 0 0;">
+                            Click to get MCP URL →
+                        </p>
+                    </div>
+                </a>
+                """
+            else:
+                sidebar_chatgpt = """
+                <a href="http://localhost:7861" target="_blank" style="color: #2196F3; text-decoration: none; padding: 8px 16px; border: 1px solid #2196F3; border-radius: 6px; display: inline-block; margin: 5px 0;">
+                    💬 ChatGPT App (MCP Server)
+                </a>
+                <p style="font-size: 0.85em; opacity: 0.7; margin-top: 8px;">
+                    Use the ChatGPT App to connect with ChatGPT Desktop and access MCP tools via OpenAI Apps SDK.
+                </p>
+                """
+            
+            gr.HTML(f"""
+            <div>
+                <h3 style="margin-bottom: 10px;">🔗 Other Interfaces</h3>
+                <div>
+                    {sidebar_chatgpt}
+                </div>
+            </div>
+            """)
+            
+            gr.Markdown("---")
+            
+            status = gr.Textbox(
+                label="🔌 API Status",
+                value=check_api_status(),
+                interactive=False,
+                max_lines=2,
+            )
+            
+            with gr.Row():
+                refresh_btn = gr.Button("🔄 Refresh", size="sm")
+                clear_btn = gr.Button("🗑️ Clear", size="sm")
+    
+    # Footer
+    gr.Markdown("""
+---
+<div style="text-align: center; opacity: 0.7; font-size: 0.85em;">
+    <p>Built for the MCP 1st Birthday Hackathon 🎂</p>
+    <p>Powered by Vercel AI SDK v5 + Model Context Protocol + Gradio</p>
+</div>
+    """)
+    
+    # Disclaimer box - separate for better visibility
+    gr.HTML("""
+<style>
+.disclaimer-box {
+    text-align: center;
+    margin: 20px auto;
+    padding: 15px 20px;
+    max-width: 800px;
+    background: #fff3cd !important;
+    border: 2px solid #ffc107 !important;
+    border-radius: 8px;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+.disclaimer-box p {
+    color: #000000 !important;
+    margin: 0;
+}
+.disclaimer-box strong {
+    color: #000000 !important;
+}
+</style>
+<div class="disclaimer-box">
+    <p style="font-size: 0.9em; font-weight: 500; margin-bottom: 8px;">
+        <strong>⚠️ Disclaimer:</strong> This is a <strong style="background: rgba(255, 193, 7, 0.3); padding: 2px 4px; border-radius: 3px;">demo application (Work in Progress)</strong> and does not constitute legal advice.
+    </p>
+    <p style="font-size: 0.85em; line-height: 1.4;">
+        Always consult with qualified legal professionals before making compliance decisions based on AI outputs.
+    </p>
+</div>
+    """)
+    
+    # Model and API key handlers
+    def update_model(model_value):
+        """Update the selected model"""
+        current_model_settings["model"] = model_value
+        model_info = AVAILABLE_MODELS.get(model_value, {})
+        print(f"[Gradio] Model updated to: {model_value} ({model_info.get('name', model_value)})")
+        return f"✅ Model set to: **{model_info.get('name', model_value)}**"
+    
+    def save_api_keys(tavily_val, anthropic_val, google_val, openai_val, xai_val):
+        """Save user-provided API keys to session AND secure cookie storage
+        
+        SECURITY: Keys are stored in memory for this session AND in encoded cookies
+        that expire after 1 day. Cookies use XOR obfuscation + base64 encoding.
+        GPT-OSS is FREE and uses pre-configured Modal endpoint from environment.
+        Paid models require API keys. Note: Tavily is OPTIONAL - AI model is used as fallback for research.
+        """
+        saved = []
+        
+        # Only update if a real key is provided
+        if tavily_val and len(tavily_val) > 10:
+            current_model_settings["tavily_api_key"] = tavily_val
+            saved.append("Tavily")
+        
+        if anthropic_val and len(anthropic_val) > 10:
+            current_model_settings["anthropic_api_key"] = anthropic_val
+            saved.append("Anthropic")
+        
+        if google_val and len(google_val) > 10:
+            current_model_settings["google_api_key"] = google_val
+            saved.append("Google")
+        
+        if openai_val and len(openai_val) > 10:
+            current_model_settings["openai_api_key"] = openai_val
+            saved.append("OpenAI")
+        
+        if xai_val and len(xai_val) > 10:
+            current_model_settings["xai_api_key"] = xai_val
+            saved.append("xAI")
+        
+        # Build status message
+        status_parts = []
+        
+        # Always show current model
+        model = current_model_settings["model"]
+        model_info = AVAILABLE_MODELS.get(model, {})
+        status_parts.append(f"🤖 **Model:** {model_info.get('name', model)}")
+        
+        if saved:
+            status_parts.append(f"✅ **Keys Saved:** {', '.join(saved)}")
+        
+        status_parts.append("🔐 *Settings stored in secure cookies (expires in 24h)*")
+        
+        # Check for missing required keys based on selected model
+        if model == "gpt-oss":
+            # GPT-OSS uses hardcoded Modal endpoint - always available
+            status_parts.append("🆓 *GPT-OSS model is FREE - no API key required!*")
+        elif model in ["claude-4.5", "claude-opus"] and not current_model_settings["anthropic_api_key"]:
+            status_parts.append(f"⚠️ **Anthropic API key required** for {model}")
+        elif model == "gemini-3" and not current_model_settings["google_api_key"]:
+            status_parts.append("⚠️ **Google API key required** for Gemini 3")
+        elif model == "gpt-5" and not current_model_settings["openai_api_key"]:
+            status_parts.append("⚠️ **OpenAI API key required** for GPT-5")
+        elif model == "grok-4-1" and not current_model_settings["xai_api_key"]:
+            status_parts.append("⚠️ **xAI API key required** for Grok 4.1")
+        
+        # Tavily is optional - just inform user about enhanced features if they have it
+        if not current_model_settings["tavily_api_key"]:
+            status_parts.append("ℹ️ *Tavily not set - will use server env var fallback or AI model*")
+        
+        return "\n\n".join(status_parts)
+    
+    def get_current_model_status():
+        """Get current model and key status"""
+        model = current_model_settings["model"]
+        model_info = AVAILABLE_MODELS.get(model, {})
+        required_key = model_info.get("api_key_env", "")
+        
+        key_status = "❌ Missing"
+        if required_key == "OPENAI_API_KEY" and current_model_settings["openai_api_key"]:
+            key_status = "✅ Set"
+        elif required_key == "XAI_API_KEY" and current_model_settings["xai_api_key"]:
+            key_status = "✅ Set"
+        elif required_key == "ANTHROPIC_API_KEY" and current_model_settings["anthropic_api_key"]:
+            key_status = "✅ Set"
+        
+        return f"**Model:** {model_info.get('name', model)}\n**Key Status:** {key_status}"
+    
+    def check_required_keys():
+        """Check if required API keys are configured
+        
+        Returns a tuple of (is_valid, error_message)
+        - is_valid: True if all required keys are present
+        - error_message: Description of missing keys if not valid
+        
+        Note: GPT-OSS is FREE and no API key is required.
+        Tavily API key is optional - the system will fallback to AI model for research.
+        """
+        missing_keys = []
+        
+        # Check model API key based on selected model
+        model = current_model_settings["model"]
+        if model == "gpt-oss":
+            # GPT-OSS uses hardcoded endpoint - no check needed
+            pass
+        elif model in ["claude-4.5", "claude-opus"] and not current_model_settings["anthropic_api_key"]:
+            missing_keys.append(f"**Anthropic API Key** (required for {model})")
+        elif model == "gemini-3" and not current_model_settings["google_api_key"]:
+            missing_keys.append("**Google API Key** (required for Gemini 3)")
+        elif model == "gpt-5" and not current_model_settings["openai_api_key"]:
+            missing_keys.append("**OpenAI API Key** (required for GPT-5)")
+        elif model == "grok-4-1" and not current_model_settings["xai_api_key"]:
+            missing_keys.append("**xAI API Key** (required for Grok 4.1)")
+        
+        # Note: Tavily is OPTIONAL - system will fallback to AI model for research
+        # We no longer require Tavily API key
+        
+        if missing_keys:
+            error_msg = """## ⚠️ API Keys Required
+
+To use this service, you need to provide your own API keys. The following keys are missing:
+
+"""
+            for key in missing_keys:
+                error_msg += f"- {key}\n"
+            
+            error_msg += """
+### How to add your API keys:
+
+1. Expand the **🔑 API Keys & Settings** section in the sidebar
+2. Enter your API keys in the corresponding fields
+3. Click **💾 Save Keys**
+
+### Where to get API keys:
+
+- **Anthropic**: [console.anthropic.com](https://console.anthropic.com) - Get Claude API key
+- **Google**: [aistudio.google.com](https://aistudio.google.com/apikey) - Get Gemini API key
+- **OpenAI**: [platform.openai.com](https://platform.openai.com) - Get GPT API key
+- **xAI**: [console.x.ai](https://console.x.ai) - Get Grok API key
+
+**🆓 FREE Alternative:**
+- Select **GPT-OSS 20B** from the model dropdown - it's FREE via Modal.com!
+
+**Optional:**
+- **Tavily**: [tavily.com](https://tavily.com) - For enhanced web research (falls back to server env var, then AI model)
+"""
+            return False, error_msg
+        
+        return True, ""
+    
+    # Event handlers - clear input immediately and stream response together
+    def respond_and_clear(message: str, history: list):
+        """Wrapper that yields (cleared_input, chat_history, stop_visible) tuples"""
+        global cancel_token
+        
+        if not message.strip():
+            yield "", history, gr.update(visible=False)
+            return
+        
+        # Check for required API keys before proceeding
+        keys_valid, error_message = check_required_keys()
+        if not keys_valid:
+            # Show user message and error about missing keys
+            error_history = list(history) + [
+                ChatMessage(role="user", content=message),
+                ChatMessage(role="assistant", content=error_message)
+            ]
+            yield "", error_history, gr.update(visible=False)
+            return
+        
+        # Reset cancellation token for new request
+        cancel_token.reset()
+            
+        # First yield: clear input, show loading, and show stop button
+        # Get the actual selected model from current_model_settings (not from env)
+        selected_model = current_model_settings.get("model", "gpt-oss")
+        model_info = AVAILABLE_MODELS.get(selected_model, {})
+        model_name = model_info.get("name", selected_model)
+        print(f"[Gradio] Using model: {selected_model} ({model_name})")
+        initial_history = list(history) + [
+            ChatMessage(role="user", content=message),
+            ChatMessage(role="assistant", content=f"⏳ *Thinking with {model_name}...*")
+        ]
+        yield "", initial_history, gr.update(visible=True)
+        
+        # Stream the actual response (pass initialized_history to avoid duplication)
+        updated_history = initial_history  # Initialize in case generator doesn't yield
+        for updated_history in chat_with_agent_streaming(message, history, initial_history):
+            # Check if cancelled during streaming
+            if cancel_token.is_cancelled():
+                break
+            yield "", updated_history, gr.update(visible=True)
+        
+        # Final yield: hide stop button when done
+        yield "", updated_history, gr.update(visible=False)
+    
+    def stop_response(history: list):
+        """Stop the current response by triggering cancellation"""
+        global cancel_token
+        
+        # Trigger cancellation - this will close the HTTP connection
+        cancel_token.cancel()
+        
+        # Update history to show stopped state (the generator will also update when it detects cancellation)
+        if history and len(history) > 0:
+            last_msg = history[-1]
+            if isinstance(last_msg, ChatMessage):
+                content = last_msg.content
+                # Remove thinking indicator and add stopped message
+                if "⏳" in content:
+                    content = content.replace("⏳ *Thinking", "⏹️ *Stopped")
+                    content = content.replace("⏳ *Processing", "⏹️ *Stopped")
+                if "*— Execution stopped by user*" not in content:
+                    content += "\n\n*— Execution stopped by user*"
+                history[-1] = ChatMessage(role="assistant", content=content)
+        
+        # Return history and hide stop button
+        return history, gr.update(visible=False)
+    
+    # On submit/click: clear input immediately while streaming response
+    # These events are cancellable by the stop button
+    submit_event = msg.submit(respond_and_clear, [msg, chatbot], [msg, chatbot, stop_btn])
+    click_event = submit.click(respond_and_clear, [msg, chatbot], [msg, chatbot, stop_btn])
+    
+    # Stop button cancels the streaming events and updates the chat
+    stop_btn.click(
+        fn=stop_response,
+        inputs=[chatbot],
+        outputs=[chatbot, stop_btn],
+        cancels=[submit_event, click_event]
+    )
+    
+    refresh_btn.click(
+        lambda: (check_api_status(), get_available_tools()), 
+        None, 
+        [status, tools_info]
+    )
+    clear_btn.click(lambda: [], None, chatbot)
+    
+    # Function to update model in browser state
+    def save_model_to_browser_state(model_val, stored_data):
+        """Save model selection to browser state"""
+        if stored_data is None:
+            stored_data = DEFAULT_BROWSER_STATE.copy()
+        new_data = stored_data.copy()
+        new_data["model"] = model_val or "gpt-oss"
+        print(f"[BrowserState] Model changed to: {model_val}")
+        return new_data
+    
+    # Model selection handler - also saves to browser state
+    model_dropdown.change(
+        update_model, 
+        [model_dropdown], 
+        [keys_status]
+    ).then(
+        save_model_to_browser_state,
+        [model_dropdown, browser_state],
+        [browser_state]
+    )
+    
+    # Function to save settings to browser state
+    def save_to_browser_state(tavily_val, anthropic_val, google_val, openai_val, xai_val, model_val, stored_data):
+        """Save API keys and model to browser state (persists across refreshes)"""
+        new_data = {
+            "api_keys": {
+                "tavily": tavily_val or "",
+                "anthropic": anthropic_val or "",
+                "google": google_val or "",
+                "openai": openai_val or "",
+                "xai": xai_val or ""
+            },
+            "model": model_val or "gpt-oss"
+        }
+        print(f"[BrowserState] Saving to browser: model={model_val}, keys={[k for k,v in new_data['api_keys'].items() if v]}")
+        return new_data
+    
+    # Combined save handler - saves to session AND browser state
+    save_keys_btn.click(
+        save_api_keys, 
+        [tavily_key, anthropic_key, google_key, openai_key, xai_key], 
+        [keys_status]
+    ).then(
+        save_to_browser_state,
+        [tavily_key, anthropic_key, google_key, openai_key, xai_key, model_dropdown, browser_state],
+        [browser_state]
+    )
+    
+    # Clear keys function - clears both session and cookies, resets model to default
+    def clear_api_keys():
+        """Clear all stored API keys from session and cookies, reset model to default"""
+        # Note: modal_endpoint_url is hardcoded, so we don't clear it
+        current_model_settings["tavily_api_key"] = ""
+        current_model_settings["anthropic_api_key"] = ""
+        current_model_settings["google_api_key"] = ""
+        current_model_settings["openai_api_key"] = ""
+        current_model_settings["xai_api_key"] = ""
+        current_model_settings["model"] = "gpt-oss"  # Reset to default FREE model
+        # Return: tavily, anthropic, google, openai, xai, model_value, status
+        return "", "", "", "", "", "gpt-oss", "🗑️ All settings cleared (model reset to GPT-OSS)"
+    
+    # Function to clear browser state
+    def clear_browser_state():
+        """Clear all stored data from browser state"""
+        print("[BrowserState] Clearing all stored data")
+        return DEFAULT_BROWSER_STATE
+    
+    # Combined clear handler - clears session AND browser state
+    clear_keys_btn.click(
+        clear_api_keys,
+        [],
+        [tavily_key, anthropic_key, google_key, openai_key, xai_key, model_dropdown, keys_status]
+    ).then(
+        clear_browser_state,
+        [],
+        [browser_state]
+    )
+    
+    # === Load handler: Restore API keys and model from browser storage on page load ===
+    def load_from_browser_state(stored_data):
+        """Load API keys and model from browser storage (runs on page load)
+        
+        Returns: (tavily, anthropic, google, openai, xai, model, status_message)
+        """
+        if not stored_data:
+            print("[BrowserState] No stored data found")
+            return "", "", "", "", "", "gpt-oss", "🔧 Ready - configure API keys to get started"
+        
+        api_keys = stored_data.get("api_keys", {})
+        model = stored_data.get("model", "gpt-oss")
+        
+        # Extract individual keys
+        tavily = api_keys.get("tavily", "")
+        anthropic = api_keys.get("anthropic", "")
+        google = api_keys.get("google", "")
+        openai = api_keys.get("openai", "")
+        xai = api_keys.get("xai", "")
+        
+        # Check which keys were loaded
+        loaded_keys = [k for k, v in api_keys.items() if v]
+        
+        if loaded_keys or model != "gpt-oss":
+            print(f"[BrowserState] Restoring: model={model}, keys={loaded_keys}")
+            
+            # Also update the session state
+            current_model_settings["model"] = model
+            if tavily:
+                current_model_settings["tavily_api_key"] = tavily
+            if anthropic:
+                current_model_settings["anthropic_api_key"] = anthropic
+            if google:
+                current_model_settings["google_api_key"] = google
+            if openai:
+                current_model_settings["openai_api_key"] = openai
+            if xai:
+                current_model_settings["xai_api_key"] = xai
+            
+            # Build status message
+            model_info = AVAILABLE_MODELS.get(model, {})
+            status_parts = []
+            status_parts.append(f"🤖 **Model:** {model_info.get('name', model)}")
+            
+            if loaded_keys:
+                status_parts.append(f"🔐 **Restored from browser:** {', '.join(loaded_keys)}")
+            
+            if model == "gpt-oss":
+                status_parts.append("🆓 *GPT-OSS model is FREE - no API key required!*")
+            
+            status = "\n\n".join(status_parts)
+        else:
+            print("[BrowserState] No saved settings to restore")
+            status = "🔧 Ready - configure API keys to get started"
+        
+        return tavily, anthropic, google, openai, xai, model, status
+    
+    # Trigger on page load - restore saved settings from browser storage
+    demo.load(
+        load_from_browser_state,
+        inputs=[browser_state],
+        outputs=[tavily_key, anthropic_key, google_key, openai_key, xai_key, model_dropdown, keys_status]
+    )
+
+# Launch the app
+if __name__ == "__main__":
+    print("\n" + "="*60)
+    print("🇪🇺 EU AI Act Compliance Agent - Gradio UI")
+    print("="*60)
+    print(f"\n📡 API Server: {API_URL}")
+    print(f"✓ Status: {check_api_status()}")
+    print(f"\n🚀 Starting Gradio interface...")
+    print("="*60 + "\n")
+    
+    demo.launch(
+        server_name=os.getenv("GRADIO_SERVER_NAME", "0.0.0.0"),
+        server_port=int(os.getenv("GRADIO_SERVER_PORT", "7860")),
+        share=os.getenv("GRADIO_SHARE", "false").lower() == "true",
+        show_error=True,
+    )

apps/eu-ai-act-agent/src/server.ts

@@ -0,0 +1,1235 @@
+#!/usr/bin/env node
+
+/**
+ * EU AI Act Compliance Agent Server
+ * Express API with Vercel AI SDK v5 agent
+ *
+ * Supports streaming text and tool calls
+ */
+
+import express from "express";
+import cors from "cors";
+import { config } from "dotenv";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { createAgent } from "./agent/index.js";
+import {
+	discoverOrganization,
+	discoverAIServices,
+	assessCompliance,
+	type ApiKeys,
+} from "@eu-ai-act/mcp-server";
+
+// Load environment variables from project root
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+config({ path: resolve(__dirname, "../../../.env") }); // Go up from src -> eu-ai-act-agent -> apps -> root
+
+const app = express();
+const PORT = process.env.PORT || 3001;
+
+// Middleware
+app.use(
+	cors({
+		origin: [
+			"http://localhost:7860",
+			"http://127.0.0.1:7860",
+			"http://localhost:3000",
+		],
+		credentials: true,
+	}),
+);
+app.use(express.json());
+
+import { readFileSync, existsSync } from "fs";
+
+// Health check
+app.get("/health", (_req, res) => {
+	res.json({
+		status: "ok",
+		service: "EU AI Act Compliance Agent",
+		version: "0.1.0",
+	});
+});
+
+// MCP URL endpoint - returns the gradio.live URL for ChatGPT integration
+app.get("/api/mcp-url", (_req, res) => {
+	try {
+		const mcpUrlFile = resolve(__dirname, ".mcp_url");
+		if (existsSync(mcpUrlFile)) {
+			const url = readFileSync(mcpUrlFile, "utf-8").trim();
+			res.json({ url, status: "ready" });
+		} else {
+			res.json({ url: null, status: "starting" });
+		}
+	} catch (error) {
+		res.json({ url: null, status: "error", error: String(error) });
+	}
+});
+
+/**
+ * Process stream events and write to response
+ * Returns set of tool names that were called
+ *
+ * Tracks "thinking" phases - text that appears before tool calls
+ * vs "response" text that appears after all tools complete
+ */
+async function processStreamEvents(
+	stream: AsyncIterable<any>,
+	res: express.Response,
+): Promise<{
+	toolsCalled: Set<string>;
+	toolResults: Map<string, any>;
+	hasText: boolean;
+}> {
+	const toolsCalled = new Set<string>();
+	const toolResults = new Map<string, any>();
+	let hasText = false;
+
+	// Track phase for thinking vs response text
+	let pendingToolCall = false; // True when we've seen a tool_call but not its result yet
+	let hasHadToolCalls = false; // True once we've seen at least one tool call
+
+	for await (const event of stream) {
+		// Log all non-text events for debugging
+		if (event.type !== "text-delta") {
+			console.log(
+				"Stream event:",
+				event.type,
+				JSON.stringify(event).substring(0, 200),
+			);
+		} else {
+			hasText = true;
+		}
+
+		switch (event.type) {
+			// Handle reasoning/thinking tokens from Claude and GPT
+			// Claude uses "reasoning" with textDelta, OpenAI may use different formats
+			case "reasoning":
+				const reasoningText = (event as any).textDelta ?? "";
+				if (reasoningText) {
+					console.log("[THINKING]", reasoningText.substring(0, 100));
+					res.write(
+						`data: ${JSON.stringify({
+							type: "thinking",
+							content: reasoningText,
+						})}\n\n`,
+					);
+				}
+				break;
+
+			// Handle reasoning signature (Claude's thinking summary)
+			case "reasoning-signature":
+				const signatureText = (event as any).signature ?? "";
+				if (signatureText) {
+					console.log("[THINKING SIGNATURE]", signatureText.substring(0, 100));
+					res.write(
+						`data: ${JSON.stringify({
+							type: "thinking",
+							content: `[Reasoning Summary] ${signatureText}`,
+						})}\n\n`,
+					);
+				}
+				break;
+
+			// Handle redacted reasoning (when thinking is hidden)
+			case "redacted-reasoning":
+				console.log("[REDACTED REASONING]");
+				res.write(
+					`data: ${JSON.stringify({
+						type: "thinking",
+						content: "[Model is reasoning internally...]",
+					})}\n\n`,
+				);
+				break;
+
+			case "text-delta":
+				const textContent =
+					(event as any).textDelta ??
+					(event as any).delta ??
+					(event as any).text ??
+					"";
+
+				// Determine if this is thinking or response text
+				// Text before any tool call = thinking
+				// Text between tool result and next tool call = thinking
+				// Text after last tool result with no more tool calls = response (we can't know this yet, so we mark it as potential_response)
+				const textPhase =
+					hasHadToolCalls && !pendingToolCall
+						? "potential_response"
+						: "thinking";
+
+				res.write(
+					`data: ${JSON.stringify({
+						type: "text",
+						content: textContent,
+						phase: textPhase,
+						hasHadToolCalls,
+					})}\n\n`,
+				);
+				break;
+
+			case "tool-call":
+				console.log("TOOL CALL:", event.toolName);
+				hasHadToolCalls = true;
+				pendingToolCall = true;
+
+				toolsCalled.add(event.toolName);
+				const toolArgs = (event as any).args ?? (event as any).input ?? {};
+				res.write(
+					`data: ${JSON.stringify({
+						type: "tool_call",
+						toolName: event.toolName,
+						toolCallId: event.toolCallId,
+						args: toolArgs,
+					})}\n\n`,
+				);
+				break;
+
+			case "tool-result":
+				console.log("TOOL RESULT:", event.toolName);
+				pendingToolCall = false;
+
+				const toolOutput = (event as any).output;
+				const directResult = (event as any).result;
+				let parsedResult = null;
+
+				if (directResult) {
+					parsedResult = directResult;
+				} else if (toolOutput?.content?.[0]?.text) {
+					try {
+						parsedResult = JSON.parse(toolOutput.content[0].text);
+					} catch {
+						parsedResult = toolOutput.content[0].text;
+					}
+				}
+
+				toolResults.set(event.toolName, parsedResult);
+
+				res.write(
+					`data: ${JSON.stringify({
+						type: "tool_result",
+						toolName: event.toolName,
+						toolCallId: event.toolCallId,
+						result: parsedResult,
+					})}\n\n`,
+				);
+				break;
+
+			case "step-finish":
+				// When a step finishes, if we had tool calls and there's no pending tool,
+				// the next text will be response (or thinking for next tool)
+				res.write(
+					`data: ${JSON.stringify({
+						type: "step_finish",
+						finishReason: event.finishReason,
+						hasHadToolCalls,
+					})}\n\n`,
+				);
+				break;
+
+			case "error":
+				res.write(
+					`data: ${JSON.stringify({
+						type: "error",
+						error: String(event.error),
+					})}\n\n`,
+				);
+				break;
+		}
+	}
+
+	return { toolsCalled, toolResults, hasText };
+}
+
+// Main chat endpoint with full streaming support
+app.post("/api/chat", async (req, res) => {
+	try {
+		const { message, history = [] } = req.body;
+
+		if (!message || typeof message !== "string") {
+			return res.status(400).json({ error: "Message is required" });
+		}
+
+		// Read model selection and API keys from headers (set by Gradio UI)
+		// IMPORTANT: API keys are ONLY from user input via Gradio UI - NEVER from env vars!
+		const modelName = (req.headers["x-ai-model"] as string) || "gpt-oss";
+
+		// API keys from Gradio UI (stored in user's cookies)
+		const apiKeys = {
+			modalEndpointUrl:
+				(req.headers["x-modal-endpoint-url"] as string) || undefined,
+			openaiApiKey: (req.headers["x-openai-api-key"] as string) || undefined,
+			xaiApiKey: (req.headers["x-xai-api-key"] as string) || undefined,
+			anthropicApiKey:
+				(req.headers["x-anthropic-api-key"] as string) || undefined,
+			googleApiKey: (req.headers["x-google-api-key"] as string) || undefined,
+		};
+
+		// Tavily API key (optional - for web research)
+		const tavilyApiKey =
+			(req.headers["x-tavily-api-key"] as string) || undefined;
+
+		console.log(
+			`[API] Model: ${modelName}, API keys provided: ${
+				Object.entries(apiKeys)
+					.filter(([_, v]) => v)
+					.map(([k]) => k)
+					.join(", ") || "none (GPT-OSS is FREE)"
+			}`,
+		);
+		if (tavilyApiKey) {
+			console.log(
+				`[API] Tavily API key provided: ${tavilyApiKey.substring(0, 10)}...`,
+			);
+		}
+
+		// For GPT-OSS, use default Modal endpoint if not provided
+		if (modelName === "gpt-oss" && !apiKeys.modalEndpointUrl) {
+			apiKeys.modalEndpointUrl =
+				"https://vasilis--gpt-oss-vllm-inference-serve.modal.run";
+		}
+
+		// Set headers for streaming
+		res.setHeader("Content-Type", "text/event-stream");
+		res.setHeader("Cache-Control", "no-cache");
+		res.setHeader("Connection", "keep-alive");
+		res.setHeader("X-Accel-Buffering", "no");
+
+		// Send user message confirmation immediately
+		res.write(
+			`data: ${JSON.stringify({ type: "user_message", content: message })}\n\n`,
+		);
+
+		// Create agent instance with model, API keys, and Tavily key from Gradio UI
+		const agent = createAgent({ modelName, apiKeys, tavilyApiKey });
+
+		// Convert history to messages format
+		let messages = history.map((msg: any) => ({
+			role: msg.role,
+			content: msg.content,
+		}));
+
+		// For GPT-OSS (smaller model), implement token-based trimming to avoid context overflow
+		// GPT-OSS 20B has 16K context window
+		const isGptOss = modelName === "gpt-oss";
+		if (isGptOss && messages.length > 0) {
+			// Token budget calculation for GPT-OSS:
+			// - Context window: 16,384 tokens
+			// - System prompt: ~5,000 tokens (expanded with Article 6 guidelines)
+			// - Tool definitions: ~1,500 tokens
+			// - Output buffer (maxOutputTokens): 8,000 tokens (for comprehensive reports)
+			// - Safety margin: 300 tokens
+			// Available for history: ~1,584 tokens (~6 short messages)
+			const GPT_OSS_CONTEXT_WINDOW = 16384;
+			const SYSTEM_PROMPT_TOKENS = 5000;
+			const TOOL_DEFINITIONS_TOKENS = 1500;
+			const OUTPUT_BUFFER_TOKENS = 8000;
+			const SAFETY_MARGIN_TOKENS = 300;
+			const MAX_HISTORY_TOKENS =
+				GPT_OSS_CONTEXT_WINDOW -
+				SYSTEM_PROMPT_TOKENS -
+				TOOL_DEFINITIONS_TOKENS -
+				OUTPUT_BUFFER_TOKENS -
+				SAFETY_MARGIN_TOKENS;
+
+			// Estimate tokens: ~4 characters per token (conservative estimate for English text)
+			const estimateTokens = (text: string): number =>
+				Math.ceil((text || "").length / 4);
+
+			// First, truncate very long individual messages (e.g., tool results)
+			const MAX_MESSAGE_CHARS = 1000; // ~250 tokens per message max (tight budget)
+			messages = messages.map((msg: any) => {
+				if (msg.content && msg.content.length > MAX_MESSAGE_CHARS) {
+					console.log(
+						`[API] GPT-OSS: Truncating long ${msg.role} message (${msg.content.length} chars → ${MAX_MESSAGE_CHARS} chars)`,
+					);
+					return {
+						...msg,
+						content:
+							msg.content.substring(0, MAX_MESSAGE_CHARS) +
+							"\n\n[...truncated for context limits...]",
+					};
+				}
+				return msg;
+			});
+
+			// Calculate total history tokens
+			let totalHistoryTokens = messages.reduce(
+				(sum: number, msg: any) => sum + estimateTokens(msg.content),
+				0,
+			);
+
+			// Also count tokens for the current message we're about to add
+			const currentMessageTokens = estimateTokens(message);
+			totalHistoryTokens += currentMessageTokens;
+
+			console.log(
+				`[API] GPT-OSS: History tokens estimate: ${totalHistoryTokens} / ${MAX_HISTORY_TOKENS} max (${messages.length} messages)`,
+			);
+
+			// If over budget, trim oldest messages first
+			while (totalHistoryTokens > MAX_HISTORY_TOKENS && messages.length > 0) {
+				const removedMsg = messages.shift();
+				const removedTokens = estimateTokens(removedMsg?.content || "");
+				totalHistoryTokens -= removedTokens;
+				console.log(
+					`[API] GPT-OSS: Trimmed oldest ${removedMsg?.role} message (${removedTokens} tokens). New total: ${totalHistoryTokens}`,
+				);
+			}
+
+			// Hard limit: max 4 messages (2 turns) due to limited history budget
+			// With 8000 output tokens, we need to prioritize output over history
+			const MAX_HISTORY_MESSAGES = 4;
+			if (messages.length > MAX_HISTORY_MESSAGES) {
+				const trimCount = messages.length - MAX_HISTORY_MESSAGES;
+				console.log(
+					`[API] GPT-OSS: Trimming ${trimCount} messages to stay under ${MAX_HISTORY_MESSAGES} message limit`,
+				);
+				messages = messages.slice(-MAX_HISTORY_MESSAGES);
+			}
+
+			console.log(
+				`[API] GPT-OSS: Final history: ${messages.length} messages, ~${totalHistoryTokens} tokens`,
+			);
+		}
+
+		// Add current message
+		messages.push({
+			role: "user",
+			content: message,
+		});
+
+		console.log(
+			`Starting stream for message: ${message} (history: ${messages.length - 1} messages)`,
+		);
+
+		// First pass - stream the response
+		const result = await agent.streamText({ messages });
+		let { toolsCalled, toolResults, hasText } = await processStreamEvents(
+			result.fullStream,
+			res,
+		);
+
+		console.log("First pass complete. Tools called:", [...toolsCalled]);
+
+		// Check if this looks like an organization analysis that needs more tool calls
+		const hasOrgDiscovery = toolsCalled.has("discover_organization");
+		const hasAIServicesDiscovery = toolsCalled.has("discover_ai_services");
+
+		// Need AI services discovery if we have org but not AI services
+		const needsAIServicesDiscovery = hasOrgDiscovery && !hasAIServicesDiscovery;
+
+		// If discover_ai_services wasn't called but discover_organization was, make a follow-up request for AI services
+		if (needsAIServicesDiscovery && !hasText) {
+			console.log(
+				"⚠️ discover_organization called but discover_ai_services missing. Making follow-up request...",
+			);
+
+			const orgContext = toolResults.get("discover_organization");
+
+			// List which tools were already called to prevent duplicates
+			const alreadyCalled = [...toolsCalled].join(", ");
+
+			const aiServicesFollowUp = `
+You called discover_organization but SKIPPED discover_ai_services.
+
+## TOOLS ALREADY CALLED (DO NOT CALL AGAIN): ${alreadyCalled}
+
+## CRITICAL: Call discover_ai_services NOW (ONLY ONCE)
+
+Organization context is ready:
+- Name: ${orgContext?.organization?.name || "Unknown"}
+- Sector: ${orgContext?.organization?.sector || "Unknown"}
+
+Call discover_ai_services ONCE with:
+- organizationContext: Use the organization profile from discover_organization
+- systemNames: Extract any AI systems mentioned in the user's original query
+
+After discover_ai_services completes, call assess_compliance ONCE with BOTH contexts.
+
+⚠️ EACH TOOL MUST BE CALLED EXACTLY ONCE - NO DUPLICATES!`;
+
+			const aiServicesMessages = [
+				...messages,
+				{
+					role: "assistant",
+					content: `I have gathered the organization profile for ${orgContext?.organization?.name || "the organization"}. Now I will discover their AI systems.`,
+				},
+				{
+					role: "user",
+					content: aiServicesFollowUp,
+				},
+			];
+
+			console.log("Making follow-up request to call discover_ai_services...");
+
+			const aiServicesResult = await agent.streamText({
+				messages: aiServicesMessages,
+			});
+			const aiServicesData = await processStreamEvents(
+				aiServicesResult.fullStream,
+				res,
+			);
+
+			// Update tracking with follow-up results (only add new tools)
+			for (const [tool, result] of aiServicesData.toolResults) {
+				if (!toolResults.has(tool)) {
+					toolResults.set(tool, result);
+				}
+			}
+			for (const tool of aiServicesData.toolsCalled) {
+				toolsCalled.add(tool);
+			}
+			hasText = hasText || aiServicesData.hasText;
+
+			// Update needsAssessment check
+			const nowHasAssessment = toolsCalled.has("assess_compliance");
+			if (!nowHasAssessment) {
+				console.log(
+					"discover_ai_services called but assess_compliance still missing...",
+				);
+			}
+		}
+
+		// Recalculate if we still need assessment after AI services discovery
+		const stillNeedsAssessment =
+			(toolsCalled.has("discover_organization") ||
+				toolsCalled.has("discover_ai_services")) &&
+			!toolsCalled.has("assess_compliance");
+
+		// If organization/AI services tools were called but assess_compliance wasn't, make a follow-up request
+		if (stillNeedsAssessment && !hasText) {
+			console.log(
+				"⚠️ Organization/AI tools called but assess_compliance missing. Making follow-up request...",
+			);
+
+			// Build context from tool results - these are the FULL results from the previous tools
+			const orgContext = toolResults.get("discover_organization");
+			const aiServicesContext = toolResults.get("discover_ai_services");
+
+			// Create a follow-up message that includes the COMPLETE tool results as JSON
+			// This ensures the model has all the data needed to call assess_compliance correctly
+			const alreadyCalledTools = [...toolsCalled].join(", ");
+
+			const fullContextMessage = `
+I have received the complete results from the previous tools. Now I need you to call assess_compliance with the FULL context.
+
+## ⚠️ TOOLS ALREADY CALLED (DO NOT CALL AGAIN): ${alreadyCalledTools}
+
+## COMPLETE ORGANIZATION CONTEXT (from discover_organization):
+\`\`\`json
+${JSON.stringify(orgContext, null, 2)}
+\`\`\`
+
+## COMPLETE AI SERVICES CONTEXT (from discover_ai_services):
+\`\`\`json
+${JSON.stringify(aiServicesContext, null, 2)}
+\`\`\`
+
+## INSTRUCTION:
+Call assess_compliance ONCE with these EXACT parameters:
+- organizationContext: Pass the COMPLETE organization context JSON shown above (not a summary)
+- aiServicesContext: Pass the COMPLETE AI services context JSON shown above (not a summary)
+- generateDocumentation: true
+
+⚠️ CALL assess_compliance EXACTLY ONCE - DO NOT call any tool that was already called!
+After assess_compliance returns, provide a human-readable summary of the compliance assessment.`;
+
+			const followUpMessages = [
+				...messages,
+				{
+					role: "assistant",
+					content: `I have gathered the organization profile for ${orgContext?.organization?.name || "the organization"} and discovered ${aiServicesContext?.systems?.length || 0} AI systems. Now I will call assess_compliance with the complete context to generate the full compliance report.`,
+				},
+				{
+					role: "user",
+					content: fullContextMessage,
+				},
+			];
+
+			console.log(
+				"Making follow-up request to call assess_compliance with FULL context...",
+			);
+			console.log(
+				`Organization context size: ${JSON.stringify(orgContext || {}).length} chars`,
+			);
+			console.log(
+				`AI services context size: ${JSON.stringify(aiServicesContext || {}).length} chars`,
+			);
+
+			const followUpResult = await agent.streamText({
+				messages: followUpMessages,
+			});
+			const followUpData = await processStreamEvents(
+				followUpResult.fullStream,
+				res,
+			);
+
+			// Update tracking with follow-up results
+			for (const [tool, result] of followUpData.toolResults) {
+				toolResults.set(tool, result);
+			}
+			for (const tool of followUpData.toolsCalled) {
+				toolsCalled.add(tool);
+			}
+			// Update hasText from follow-up
+			hasText = hasText || followUpData.hasText;
+		}
+
+		// Final check for text
+		const hasTextNow = hasText;
+
+		// If still no text response, generate a comprehensive summary based on available tool results
+		if (!hasTextNow && toolResults.size > 0) {
+			console.log(
+				"Generating comprehensive compliance report from tool results...",
+			);
+
+			// Create a summary from available data
+			const orgData = toolResults.get("discover_organization");
+			const aiData = toolResults.get("discover_ai_services");
+			const assessData = toolResults.get("assess_compliance");
+
+			let summary = "\n\n---\n\n";
+
+			// ================== HEADER ==================
+			const orgName = orgData?.organization?.name || "Organization";
+			summary += `# 🇪🇺 EU AI Act Compliance Report\n`;
+			summary += `## ${orgName}\n\n`;
+			summary += `*Assessment Date: ${new Date().toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric" })}*\n\n`;
+			summary += `---\n\n`;
+
+			// ================== ORGANIZATION PROFILE ==================
+			if (orgData?.organization) {
+				const org = orgData.organization;
+				summary += `## 🏢 Organization Profile\n\n`;
+				summary += `| Attribute | Value |\n`;
+				summary += `|-----------|-------|\n`;
+				summary += `| **Name** | ${org.name} |\n`;
+				summary += `| **Sector** | ${org.sector} |\n`;
+				summary += `| **Size** | ${org.size} |\n`;
+				summary += `| **Headquarters** | ${org.headquarters?.city || "Unknown"}, ${org.headquarters?.country || "Unknown"} |\n`;
+				summary += `| **EU Presence** | ${org.euPresence ? "✅ Yes" : "❌ No"} |\n`;
+				summary += `| **AI Maturity Level** | ${org.aiMaturityLevel} |\n`;
+				summary += `| **Primary Role** | ${org.primaryRole} (per Article 3) |\n`;
+				summary += `| **Jurisdictions** | ${org.jurisdiction?.join(", ") || "Unknown"} |\n`;
+				if (org.contact?.website) {
+					summary += `| **Website** | ${org.contact.website} |\n`;
+				}
+				summary += `\n`;
+
+				// Regulatory Context
+				if (orgData.regulatoryContext) {
+					const reg = orgData.regulatoryContext;
+					summary += `### 📋 Regulatory Context\n\n`;
+					summary += `- **Quality Management System (Article 17):** ${reg.hasQualityManagementSystem ? "✅ Implemented" : "⚠️ Not Implemented"}\n`;
+					summary += `- **Risk Management System (Article 9):** ${reg.hasRiskManagementSystem ? "✅ Implemented" : "⚠️ Not Implemented"}\n`;
+					if (reg.existingCertifications?.length > 0) {
+						summary += `- **Certifications:** ${reg.existingCertifications.join(", ")}\n`;
+					}
+					if (!org.euPresence) {
+						summary += `- **Authorized Representative (Article 22):** ${reg.hasAuthorizedRepresentative ? "✅ Appointed" : "⚠️ Required for non-EU entities"}\n`;
+					}
+					summary += `\n`;
+				}
+			}
+
+			// ================== AI SYSTEMS ANALYSIS ==================
+			if (aiData?.systems && aiData.systems.length > 0) {
+				summary += `## 🤖 AI Systems Analysis\n\n`;
+
+				// Risk Summary Table
+				const riskSummary = aiData.riskSummary;
+				summary += `### Risk Distribution\n\n`;
+				summary += `| Risk Category | Count | Status |\n`;
+				summary += `|---------------|-------|--------|\n`;
+				if (riskSummary.unacceptableRiskCount > 0) {
+					summary += `| 🔴 **Unacceptable Risk** | ${riskSummary.unacceptableRiskCount} | ⛔ PROHIBITED |\n`;
+				}
+				summary += `| 🟠 **High Risk** | ${riskSummary.highRiskCount} | Requires Conformity Assessment |\n`;
+				summary += `| 🟡 **Limited Risk** | ${riskSummary.limitedRiskCount} | Transparency Obligations |\n`;
+				summary += `| 🟢 **Minimal Risk** | ${riskSummary.minimalRiskCount} | No Specific Obligations |\n`;
+				summary += `| **Total** | ${riskSummary.totalCount} | |\n\n`;
+
+				// Detailed System Analysis
+				summary += `### Detailed System Analysis\n\n`;
+
+				for (const sys of aiData.systems) {
+					const riskEmoji =
+						sys.riskClassification.category === "High"
+							? "🟠"
+							: sys.riskClassification.category === "Limited"
+								? "🟡"
+								: sys.riskClassification.category === "Unacceptable"
+									? "🔴"
+									: "🟢";
+
+					summary += `#### ${riskEmoji} ${sys.system.name}\n\n`;
+					summary += `**Risk Classification:** ${sys.riskClassification.category} Risk (Score: ${sys.riskClassification.riskScore}/100)\n\n`;
+
+					// Purpose and Description
+					summary += `**Intended Purpose:** ${sys.system.intendedPurpose}\n\n`;
+
+					// Classification Reasoning
+					if (sys.riskClassification.justification) {
+						summary += `**Classification Reasoning:**\n> ${sys.riskClassification.justification}\n\n`;
+					}
+
+					// Annex III Category for High-Risk
+					if (
+						sys.riskClassification.category === "High" &&
+						sys.riskClassification.annexIIICategory
+					) {
+						summary += `**Annex III Category:** ${sys.riskClassification.annexIIICategory}\n\n`;
+					}
+
+					// Technical Details
+					summary += `**Technical Details:**\n`;
+					summary += `- AI Technology: ${sys.technicalDetails.aiTechnology?.join(", ") || "Not specified"}\n`;
+					summary += `- Data Processed: ${sys.technicalDetails.dataProcessed?.join(", ") || "Not specified"}\n`;
+					summary += `- Deployment: ${sys.technicalDetails.deploymentModel || "Not specified"}\n`;
+					summary += `- Human Oversight: ${sys.technicalDetails.humanOversight?.enabled ? "✅ Enabled" : "⚠️ Not enabled"}\n`;
+					if (sys.technicalDetails.humanOversight?.description) {
+						summary += `  - *${sys.technicalDetails.humanOversight.description}*\n`;
+					}
+					summary += `\n`;
+
+					// Compliance Status
+					summary += `**Compliance Status:**\n`;
+					summary += `- Conformity Assessment: ${sys.complianceStatus.conformityAssessmentStatus}\n`;
+					summary += `- Technical Documentation: ${sys.complianceStatus.hasTechnicalDocumentation ? "✅" : "❌"}\n`;
+					summary += `- EU Database Registration: ${sys.complianceStatus.registeredInEUDatabase ? "✅" : "❌"}\n`;
+					summary += `- Post-Market Monitoring: ${sys.complianceStatus.hasPostMarketMonitoring ? "✅" : "❌"}\n`;
+					if (sys.complianceStatus.complianceDeadline) {
+						summary += `- **Deadline:** ${sys.complianceStatus.complianceDeadline}\n`;
+					}
+					if (sys.complianceStatus.estimatedComplianceEffort) {
+						summary += `- **Estimated Effort:** ${sys.complianceStatus.estimatedComplianceEffort}\n`;
+					}
+					summary += `\n`;
+
+					// Regulatory References
+					if (sys.riskClassification.regulatoryReferences?.length > 0) {
+						summary += `**Applicable Articles:** ${sys.riskClassification.regulatoryReferences.join(", ")}\n\n`;
+					}
+
+					summary += `---\n\n`;
+				}
+			}
+
+			// ================== COMPLIANCE ASSESSMENT ==================
+			if (assessData?.assessment) {
+				const assess = assessData.assessment;
+
+				summary += `## 📊 Compliance Assessment Results\n\n`;
+
+				// Score Card
+				const scoreEmoji =
+					assess.overallScore >= 80
+						? "🟢"
+						: assess.overallScore >= 60
+							? "🟡"
+							: assess.overallScore >= 40
+								? "🟠"
+								: "🔴";
+				summary += `### Overall Score: ${scoreEmoji} ${assess.overallScore}/100\n`;
+				summary += `**Risk Level:** ${assess.riskLevel}\n\n`;
+
+				// Compliance by Article
+				if (
+					assess.complianceByArticle &&
+					Object.keys(assess.complianceByArticle).length > 0
+				) {
+					summary += `### Compliance by EU AI Act Article\n\n`;
+					summary += `| Article | Status | Issues |\n`;
+					summary += `|---------|--------|--------|\n`;
+					for (const [article, statusData] of Object.entries(
+						assess.complianceByArticle,
+					)) {
+						const articleStatus = statusData as {
+							compliant: boolean;
+							gaps?: string[];
+						};
+						const icon = articleStatus.compliant ? "✅" : "❌";
+						const issues = articleStatus.gaps?.length
+							? articleStatus.gaps.length + " gap(s)"
+							: "None";
+						summary += `| ${article} | ${icon} | ${issues} |\n`;
+					}
+					summary += `\n`;
+				}
+
+				// Gap Analysis
+				if (assess.gaps && assess.gaps.length > 0) {
+					summary += `### 🔍 Gap Analysis\n\n`;
+
+					// Group by severity
+					const critical = assess.gaps.filter(
+						(g: any) => g.severity === "CRITICAL",
+					);
+					const high = assess.gaps.filter((g: any) => g.severity === "HIGH");
+					const medium = assess.gaps.filter(
+						(g: any) => g.severity === "MEDIUM",
+					);
+					const low = assess.gaps.filter((g: any) => g.severity === "LOW");
+
+					if (critical.length > 0) {
+						summary += `#### 🔴 Critical Gaps (${critical.length})\n\n`;
+						for (const gap of critical) {
+							summary += `**${gap.category}** - ${gap.articleReference || "General"}\n`;
+							summary += `> ${gap.description}\n`;
+							if (gap.currentState)
+								summary += `> *Current:* ${gap.currentState}\n`;
+							if (gap.requiredState)
+								summary += `> *Required:* ${gap.requiredState}\n`;
+							if (gap.deadline) summary += `> ⏰ Deadline: ${gap.deadline}\n`;
+							summary += `\n`;
+						}
+					}
+
+					if (high.length > 0) {
+						summary += `#### 🟠 High Priority Gaps (${high.length})\n\n`;
+						for (const gap of high) {
+							summary += `**${gap.category}** - ${gap.articleReference || "General"}\n`;
+							summary += `> ${gap.description}\n`;
+							if (gap.deadline) summary += `> ⏰ Deadline: ${gap.deadline}\n`;
+							summary += `\n`;
+						}
+					}
+
+					if (medium.length > 0) {
+						summary += `#### 🟡 Medium Priority Gaps (${medium.length})\n\n`;
+						for (const gap of medium.slice(0, 5)) {
+							summary += `- **${gap.category}:** ${gap.description}\n`;
+						}
+						if (medium.length > 5) {
+							summary += `- *...and ${medium.length - 5} more medium-priority gaps*\n`;
+						}
+						summary += `\n`;
+					}
+
+					if (low.length > 0) {
+						summary += `#### 🟢 Low Priority Gaps (${low.length})\n\n`;
+						summary += `*${low.length} low-priority gaps identified - see detailed report*\n\n`;
+					}
+				}
+
+				// Recommendations
+				if (assess.recommendations && assess.recommendations.length > 0) {
+					summary += `### 💡 Priority Recommendations\n\n`;
+
+					// Sort by priority
+					const sortedRecs = [...assess.recommendations].sort(
+						(a: any, b: any) => a.priority - b.priority,
+					);
+
+					for (const rec of sortedRecs.slice(0, 5)) {
+						summary += `#### ${rec.priority}. ${rec.title}\n`;
+						summary += `*${rec.articleReference || "General Compliance"}*\n\n`;
+						summary += `${rec.description}\n\n`;
+
+						if (rec.implementationSteps && rec.implementationSteps.length > 0) {
+							summary += `**Implementation Steps:**\n`;
+							for (
+								let i = 0;
+								i < Math.min(rec.implementationSteps.length, 5);
+								i++
+							) {
+								summary += `${i + 1}. ${rec.implementationSteps[i]}\n`;
+							}
+							summary += `\n`;
+						}
+
+						if (rec.estimatedEffort) {
+							summary += `**Estimated Effort:** ${rec.estimatedEffort}\n`;
+						}
+						if (rec.expectedOutcome) {
+							summary += `**Expected Outcome:** ${rec.expectedOutcome}\n`;
+						}
+						summary += `\n`;
+					}
+
+					if (sortedRecs.length > 5) {
+						summary += `*...and ${sortedRecs.length - 5} additional recommendations*\n\n`;
+					}
+				}
+			}
+
+			// ================== KEY COMPLIANCE DEADLINES ==================
+			if (aiData?.complianceDeadlines) {
+				summary += `## 📅 Key Compliance Deadlines\n\n`;
+				summary += `| Deadline | Requirement |\n`;
+				summary += `|----------|-------------|\n`;
+				summary += `| **February 2, 2025** | Prohibited AI practices ban (Article 5) |\n`;
+				summary += `| **August 2, 2025** | GPAI model obligations (Article 53) |\n`;
+				summary += `| **${aiData.complianceDeadlines.limitedRisk}** | Limited-risk transparency (Article 50) |\n`;
+				summary += `| **${aiData.complianceDeadlines.highRisk}** | High-risk AI full compliance |\n`;
+				summary += `\n`;
+			}
+
+			// ================== DOCUMENTATION TEMPLATES ==================
+			if (assessData?.documentation) {
+				const docs = assessData.documentation;
+				summary += `## 📝 Generated Documentation Templates\n\n`;
+				summary += `The following EU AI Act compliance documentation templates have been generated:\n\n`;
+
+				const docList = [
+					{
+						name: "Risk Management System",
+						field: "riskManagementTemplate",
+						article: "Article 9",
+					},
+					{
+						name: "Technical Documentation",
+						field: "technicalDocumentation",
+						article: "Article 11, Annex IV",
+					},
+					{
+						name: "Conformity Assessment",
+						field: "conformityAssessment",
+						article: "Article 43",
+					},
+					{
+						name: "Transparency Notice",
+						field: "transparencyNotice",
+						article: "Article 50",
+					},
+					{
+						name: "Quality Management System",
+						field: "qualityManagementSystem",
+						article: "Article 17",
+					},
+					{
+						name: "Human Oversight Procedure",
+						field: "humanOversightProcedure",
+						article: "Article 14",
+					},
+					{
+						name: "Data Governance Policy",
+						field: "dataGovernancePolicy",
+						article: "Article 10",
+					},
+					{
+						name: "Incident Reporting Procedure",
+						field: "incidentReportingProcedure",
+						article: "General",
+					},
+				];
+
+				summary += `| Document | Article Reference | Status |\n`;
+				summary += `|----------|-------------------|--------|\n`;
+				for (const doc of docList) {
+					const hasDoc = (docs as any)[doc.field];
+					summary += `| ${doc.name} | ${doc.article} | ${hasDoc ? "✅ Generated" : "⚪ Not generated"} |\n`;
+				}
+				summary += `\n`;
+
+				// Show first template as example
+				const firstTemplate =
+					docs.riskManagementTemplate ||
+					docs.technicalDocumentation ||
+					docs.transparencyNotice;
+				if (firstTemplate) {
+					summary += `### 📄 Sample Template: Risk Management System (Article 9)\n\n`;
+					summary += `<details>\n<summary>Click to expand template</summary>\n\n`;
+					summary += `${firstTemplate.substring(0, 2000)}${firstTemplate.length > 2000 ? "\n\n*...template truncated for display...*" : ""}\n`;
+					summary += `\n</details>\n\n`;
+				}
+			}
+
+			// ================== AI REASONING ==================
+			if (assessData?.reasoning) {
+				summary += `## 🧠 Assessment Reasoning\n\n`;
+				summary += `<details>\n<summary>Click to expand AI analysis reasoning</summary>\n\n`;
+				summary += `${assessData.reasoning}\n`;
+				summary += `\n</details>\n\n`;
+			}
+
+			summary += `---\n\n`;
+			summary += `*Report generated on ${new Date().toISOString()}*\n\n`;
+			summary += `**Disclaimer:** This report is for informational purposes only and does not constitute legal advice. Consult with qualified legal professionals for official compliance guidance.\n`;
+
+			// Stream the comprehensive summary
+			for (const char of summary) {
+				res.write(
+					`data: ${JSON.stringify({ type: "text", content: char })}\n\n`,
+				);
+			}
+		}
+
+		// Send final done message
+		res.write(`data: ${JSON.stringify({ type: "done" })}\n\n`);
+		res.end();
+	} catch (error) {
+		console.error("Chat error:", error);
+
+		// Try to send error via stream if headers already sent
+		if (res.headersSent) {
+			res.write(
+				`data: ${JSON.stringify({
+					type: "error",
+					error: error instanceof Error ? error.message : "Unknown error",
+				})}\n\n`,
+			);
+			res.write(`data: ${JSON.stringify({ type: "done" })}\n\n`);
+			res.end();
+		} else {
+			res.status(500).json({
+				error: "Internal server error",
+				message: error instanceof Error ? error.message : "Unknown error",
+			});
+		}
+	}
+});
+
+// Tool status endpoint
+app.get("/api/tools", async (_req, res) => {
+	try {
+		// Use default GPT-OSS (free, no API key needed) just to list tools
+		const agent = createAgent({
+			modelName: "gpt-oss",
+			apiKeys: {
+				modalEndpointUrl:
+					"https://vasilis--gpt-oss-vllm-inference-serve.modal.run",
+			},
+		});
+		const tools = await agent.getTools();
+
+		res.json({
+			tools: tools.map((tool: any) => ({
+				name: tool.name,
+				description: tool.description,
+			})),
+		});
+	} catch (error) {
+		console.error("Tools error:", error);
+		res.status(500).json({ error: "Failed to fetch tools" });
+	}
+});
+
+// ============================================================================
+// DIRECT TOOL ENDPOINTS - For ChatGPT Apps and direct API calls
+// ============================================================================
+
+/**
+ * Direct endpoint for discover_organization tool
+ * Used by ChatGPT Apps via Gradio MCP server
+ */
+app.post("/api/tools/discover_organization", async (req, res) => {
+	try {
+		const { organizationName, domain, context } = req.body;
+
+		if (!organizationName) {
+			return res.status(400).json({ error: "organizationName is required" });
+		}
+
+		console.log(`[API] discover_organization called for: ${organizationName}`);
+
+		// Read API keys from headers (from Gradio UI), fallback to server env (HF Spaces secret)
+		const tavilyApiKey =
+			(req.headers["x-tavily-api-key"] as string) ||
+			process.env.TAVILY_API_KEY ||
+			undefined;
+		if (tavilyApiKey) {
+			console.log(
+				`[API] Using Tavily API key from: ${req.headers["x-tavily-api-key"] ? "request header" : "server env (HF Spaces secret)"}`,
+			);
+		} else {
+			console.log(`[API] No Tavily API key - will use AI model fallback`);
+		}
+		const modelName = (req.headers["x-ai-model"] as string) || "gpt-oss";
+		const apiKeys = {
+			modalEndpointUrl:
+				(req.headers["x-modal-endpoint-url"] as string) || undefined,
+			openaiApiKey: (req.headers["x-openai-api-key"] as string) || undefined,
+			xaiApiKey: (req.headers["x-xai-api-key"] as string) || undefined,
+			anthropicApiKey:
+				(req.headers["x-anthropic-api-key"] as string) || undefined,
+			googleApiKey: (req.headers["x-google-api-key"] as string) || undefined,
+		};
+
+		const result = await discoverOrganization({
+			organizationName,
+			domain: domain || undefined,
+			context: context || undefined,
+			model: modelName,
+			apiKeys,
+			tavilyApiKey,
+		});
+
+		console.log(
+			`[API] discover_organization completed for: ${organizationName}`,
+		);
+		res.json(result);
+	} catch (error) {
+		console.error("discover_organization error:", error);
+		res.status(500).json({
+			error: true,
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+});
+
+/**
+ * Direct endpoint for discover_ai_services tool
+ * Used by ChatGPT Apps via Gradio MCP server
+ */
+app.post("/api/tools/discover_ai_services", async (req, res) => {
+	try {
+		const { organizationContext, systemNames, scope, context } = req.body;
+
+		console.log(
+			`[API] discover_ai_services called, systemNames: ${JSON.stringify(systemNames)}`,
+		);
+
+		// Read API keys from headers (from Gradio UI), fallback to server env (HF Spaces secret)
+		const tavilyApiKey =
+			(req.headers["x-tavily-api-key"] as string) ||
+			process.env.TAVILY_API_KEY ||
+			undefined;
+		if (tavilyApiKey) {
+			console.log(
+				`[API] Using Tavily API key from: ${req.headers["x-tavily-api-key"] ? "request header" : "server env (HF Spaces secret)"}`,
+			);
+		} else {
+			console.log(`[API] No Tavily API key - will use AI model fallback`);
+		}
+		const modelName = (req.headers["x-ai-model"] as string) || "gpt-oss";
+		const apiKeys = {
+			modalEndpointUrl:
+				(req.headers["x-modal-endpoint-url"] as string) || undefined,
+			openaiApiKey: (req.headers["x-openai-api-key"] as string) || undefined,
+			xaiApiKey: (req.headers["x-xai-api-key"] as string) || undefined,
+			anthropicApiKey:
+				(req.headers["x-anthropic-api-key"] as string) || undefined,
+			googleApiKey: (req.headers["x-google-api-key"] as string) || undefined,
+		};
+
+		const result = await discoverAIServices({
+			organizationContext: organizationContext || undefined,
+			systemNames: systemNames || undefined,
+			scope: scope || undefined,
+			context: context || undefined,
+			model: modelName,
+			apiKeys,
+			tavilyApiKey,
+		});
+
+		console.log(
+			`[API] discover_ai_services completed, found ${result.systems?.length || 0} systems`,
+		);
+		res.json(result);
+	} catch (error) {
+		console.error("discover_ai_services error:", error);
+		res.status(500).json({
+			error: true,
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+});
+
+/**
+ * Direct endpoint for assess_compliance tool
+ * Used by ChatGPT Apps via Gradio MCP server
+ *
+ * Note: This endpoint sets env vars for the MCP tool to read.
+ * The main /api/chat endpoint uses direct API key passing instead.
+ */
+app.post("/api/tools/assess_compliance", async (req, res) => {
+	try {
+		const {
+			organizationContext,
+			aiServicesContext,
+			focusAreas,
+			generateDocumentation,
+		} = req.body;
+
+		console.log(
+			`[API] assess_compliance called, generateDocumentation: ${generateDocumentation}`,
+		);
+
+		// Read model selection and API keys from headers (from Gradio UI), fallback to server env (HF Spaces secret)
+		const modelName = (req.headers["x-ai-model"] as string) || "gpt-oss";
+		const tavilyApiKey =
+			(req.headers["x-tavily-api-key"] as string) ||
+			process.env.TAVILY_API_KEY ||
+			undefined;
+		if (tavilyApiKey) {
+			console.log(
+				`[API] Using Tavily API key from: ${req.headers["x-tavily-api-key"] ? "request header" : "server env (HF Spaces secret)"}`,
+			);
+		} else {
+			console.log(`[API] No Tavily API key - will use AI model fallback`);
+		}
+		const apiKeys = {
+			modalEndpointUrl:
+				(req.headers["x-modal-endpoint-url"] as string) || undefined,
+			openaiApiKey: (req.headers["x-openai-api-key"] as string) || undefined,
+			xaiApiKey: (req.headers["x-xai-api-key"] as string) || undefined,
+			anthropicApiKey:
+				(req.headers["x-anthropic-api-key"] as string) || undefined,
+			googleApiKey: (req.headers["x-google-api-key"] as string) || undefined,
+		};
+
+		// For GPT-OSS, use default Modal endpoint if not provided
+		if (modelName === "gpt-oss" && !apiKeys.modalEndpointUrl) {
+			apiKeys.modalEndpointUrl =
+				"https://vasilis--gpt-oss-vllm-inference-serve.modal.run";
+		}
+
+		const result = await assessCompliance({
+			organizationContext: organizationContext || undefined,
+			aiServicesContext: aiServicesContext || undefined,
+			focusAreas: focusAreas || undefined,
+			generateDocumentation: generateDocumentation !== false, // Default true
+			model: modelName,
+			apiKeys,
+			tavilyApiKey,
+		});
+
+		console.log(
+			`[API] assess_compliance completed, score: ${result.assessment?.overallScore}`,
+		);
+		res.json(result);
+	} catch (error) {
+		console.error("assess_compliance error:", error);
+		res.status(500).json({
+			error: true,
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+});
+
+// Start server
+app.listen(PORT, () => {
+	const PUBLIC_URL = process.env.PUBLIC_URL;
+	const isProduction = process.env.NODE_ENV === "production";
+
+	console.log(`\n🇪🇺 EU AI Act Compliance Agent Server`);
+	console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+
+	if (isProduction) {
+		console.log(`🌐 Environment: PRODUCTION (HF Spaces)`);
+		console.log(`✓ Gradio UI: ${PUBLIC_URL || "https://*.hf.space"}`);
+		console.log(`✓ API Server: http://localhost:${PORT} (internal only)`);
+		console.log(`\n📡 Internal API Endpoints (used by Gradio):`);
+	} else {
+		console.log(`🛠️  Environment: LOCAL DEVELOPMENT`);
+		console.log(`✓ Server running on http://localhost:${PORT}`);
+		console.log(`\n📡 API Endpoints:`);
+	}
+
+	console.log(`  • GET  /health`);
+	console.log(`  • POST /api/chat`);
+	console.log(`  • GET  /api/tools`);
+	console.log(`  • POST /api/tools/discover_organization`);
+	console.log(`  • POST /api/tools/discover_ai_services`);
+	console.log(`  • POST /api/tools/assess_compliance`);
+
+	if (!isProduction) {
+		console.log(`\n💡 Start Gradio UI: pnpm gradio`);
+		console.log(`💡 Start ChatGPT App: pnpm chatgpt-app`);
+	}
+	console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+});

apps/eu-ai-act-agent/src/types/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Type definitions for EU AI Act Compliance Agent
+ */
+
+export interface ChatMessage {
+  role: "user" | "assistant" | "system";
+  content: string;
+}
+
+export interface ChatRequest {
+  message: string;
+  history: ChatMessage[];
+}
+
+export interface ChatResponse {
+  type: "text" | "tool_call" | "result" | "done" | "error";
+  content?: string;
+  tool?: string;
+  data?: any;
+  error?: string;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, any>;
+}
+
+export interface AgentConfig {
+  model: string;
+  temperature?: number;
+  maxTokens?: number;
+  maxSteps?: number;
+}
+
+// Re-export types from MCP package
+// @ts-ignore - These will be available at runtime after building
+export type {
+  OrganizationProfile,
+  AIServiceDiscovery,
+  ComplianceAssessment,
+} from "../../../eu-ai-act-mcp/dist/types/index.js";
+

apps/eu-ai-act-agent/start.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+
+# EU AI Act Compliance Agent Startup Script
+# Starts both the API server and Gradio UI
+
+set -e
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🇪🇺 EU AI Act Compliance Agent"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if .env exists
+if [ ! -f "../../.env" ]; then
+    echo "⚠️  Warning: .env file not found"
+    echo "   Create one from .env.example and add your OPENAI_API_KEY"
+    echo ""
+fi
+
+# Check Node.js
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js not found. Please install Node.js 18+"
+    exit 1
+fi
+
+# Check Python
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 not found. Please install Python 3.9+"
+    exit 1
+fi
+
+echo "✓ Node.js: $(node --version)"
+echo "✓ Python: $(python3 --version)"
+echo ""
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "📦 Installing uv (fast Python package manager)..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    echo ""
+    echo "⚠️  Please restart your terminal and run this script again"
+    exit 0
+fi
+
+# Create virtual environment if it doesn't exist
+if [ ! -d ".venv" ]; then
+    echo "📦 Creating virtual environment with Python 3.13..."
+    uv venv --python python3.13
+    echo ""
+fi
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# Install Python dependencies if needed
+if ! python -c "import gradio" 2>/dev/null; then
+    echo "📦 Installing Python dependencies with uv..."
+    uv pip install -r requirements.txt
+    echo ""
+fi
+
+# Build MCP server if needed
+if [ ! -d "../../packages/eu-ai-act-mcp/dist" ]; then
+    echo "🔨 Building MCP server..."
+    cd ../../
+    pnpm --filter @eu-ai-act/mcp-server build
+    cd apps/eu-ai-act-agent
+    echo ""
+fi
+
+echo "🚀 Starting EU AI Act Compliance Agent..."
+echo ""
+echo "📡 API Server will start on: http://localhost:3001"
+echo "🎨 Gradio UI will start on: http://localhost:7860"
+echo ""
+echo "Press Ctrl+C to stop both servers"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Function to cleanup on exit
+cleanup() {
+    echo ""
+    echo "🛑 Shutting down servers..."
+    kill $API_PID $GRADIO_PID $CHATGPT_PID 2>/dev/null
+    exit 0
+}
+
+trap cleanup INT TERM
+
+# Start API server in background
+echo "Starting API server..."
+pnpm dev > /tmp/eu-ai-act-api.log 2>&1 &
+API_PID=$!
+
+# Wait for API to be ready
+echo "Waiting for API server to start..."
+sleep 3
+
+# Start Gradio UI in background (using virtual environment Python)
+echo "Starting Gradio UI..."
+python src/gradio_app.py > /tmp/eu-ai-act-gradio.log 2>&1 &
+GRADIO_PID=$!
+
+# Start ChatGPT App in background (using virtual environment Python)
+echo "Starting ChatGPT App..."
+python src/chatgpt_app.py > /tmp/eu-ai-act-chatgpt.log 2>&1 &
+CHATGPT_PID=$!
+
+# Wait for apps to be ready
+sleep 3
+
+echo ""
+echo "✅ All servers are running!"
+echo ""
+echo "🌐 Open your browser to:"
+echo "   Gradio UI:    http://localhost:7860"
+echo "   ChatGPT App:  http://localhost:7861"
+echo ""
+echo "📋 Logs:"
+echo "   API:         tail -f /tmp/eu-ai-act-api.log"
+echo "   Gradio:      tail -f /tmp/eu-ai-act-gradio.log"
+echo "   ChatGPT App: tail -f /tmp/eu-ai-act-chatgpt.log"
+echo ""
+
+# Wait for all processes
+wait $API_PID $GRADIO_PID $CHATGPT_PID
+

apps/eu-ai-act-agent/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tooling/typescript/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2022"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+

apps/eu-ai-act-agent/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/server.ts"],
+  format: ["esm"],
+  dts: false, // Disable dts generation to avoid module resolution issues
+  sourcemap: true,
+  clean: true,
+  minify: false,
+  external: ["express", "dotenv"],
+  noExternal: [], // Bundle everything except external
+  bundle: true,
+});
+

biome.json

@@ -0,0 +1,43 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.0.6/schema.json",
+	"assist": { "actions": { "source": { "organizeImports": "on" } } },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"complexity": {
+				"noForEach": "off",
+				"noUselessFragments": "off"
+			},
+			"correctness": {
+				"useExhaustiveDependencies": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "off"
+			},
+			"style": {
+				"noParameterAssign": "error",
+				"useAsConstAssertion": "error",
+				"useDefaultParameterLast": "error",
+				"useEnumInitializers": "error",
+				"useSelfClosingElements": "error",
+				"useSingleVarDeclarator": "error",
+				"noUnusedTemplateLiteral": "error",
+				"useNumberNamespace": "error",
+				"noInferrableTypes": "error",
+				"noUselessElse": "error"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"includes": [
+			"**",
+			"!**/node_modules/**/*",
+			"!**/*.config.*",
+			"!**/*.json",
+			"!**/tsconfig.json",
+			"!**/.turbo"
+		]
+	}
+}

modal/README.md

@@ -0,0 +1,237 @@
+# Modal Deployment for GPT-OSS vLLM
+
+Deploy OpenAI's GPT-OSS models (20B or 120B) on [Modal.com](https://modal.com) with vLLM for efficient inference.
+
+## 🚀 Quick Start
+
+### 1. Install Modal CLI
+
+```bash
+# Install the Modal Python package
+pip install modal
+
+# Authenticate with Modal (opens browser)
+modal setup
+```
+
+If `modal setup` doesn't work, try:
+```bash
+python -m modal setup
+```
+
+### 2. Create a Modal Account
+
+1. Go to [modal.com](https://modal.com)
+2. Create a free account
+3. Run `modal setup` to authenticate
+
+### 3. Deploy the GPT-OSS Model
+
+```bash
+# Navigate to the modal directory
+cd modal
+
+# Test the server (spins up a temporary instance)
+modal run gpt_oss_inference.py
+
+# Deploy to production (creates a persistent endpoint)
+modal deploy gpt_oss_inference.py
+```
+
+## 📋 Configuration
+
+### GPU Selection (Cost Optimization)
+
+Edit `gpt_oss_inference.py` to choose your GPU tier:
+
+```python
+# Choose your GPU - uncomment the one you want:
+GPU_CONFIG = "A10G"  # ~$0.76/hr - RECOMMENDED for budget ✅
+# GPU_CONFIG = "L4"     # ~$0.59/hr - Cheapest option
+# GPU_CONFIG = "A100"   # ~$1.79/hr - More headroom
+# GPU_CONFIG = "H100"   # ~$3.95/hr - Maximum performance
+```
+
+### GPU Pricing Comparison
+
+| GPU       | VRAM | Price/hr   | Best For                         |
+| --------- | ---- | ---------- | -------------------------------- |
+| L4        | 24GB | ~$0.59     | Tightest budget (may be tight)   |
+| **A10G**  | 24GB | **~$0.76** | **Best value for GPT-OSS 20B** ✅ |
+| A100 40GB | 40GB | ~$1.79     | More headroom                    |
+| A100 80GB | 80GB | ~$2.78     | Both 20B and 120B                |
+| H100      | 80GB | ~$3.95     | Maximum performance              |
+
+### Model Selection
+
+```python
+# 20B model - faster, fits on A10G/L4
+MODEL_NAME = "openai/gpt-oss-20b"
+
+# 120B model - needs A100 80GB or H100
+MODEL_NAME = "openai/gpt-oss-120b"
+```
+
+### Performance Tuning
+
+```python
+# FAST_BOOT = True  - Faster startup, less memory (use for smaller GPUs)
+# FAST_BOOT = False - Slower startup, faster inference
+FAST_BOOT = True
+
+# Data type - GPT-OSS MXFP4 quantization REQUIRES bfloat16 (float16 not supported)
+# The Marlin kernel warning on A10G/L4 is expected and can be ignored
+USE_FLOAT16 = False  # Must be False for GPT-OSS (MXFP4 only supports bfloat16)
+
+# Maximum model length (context window) - reduce to speed up startup
+MAX_MODEL_LEN = 32768  # 32k tokens (can increase to 131072 if needed)
+
+# Keep container warm longer to avoid cold starts
+SCALEDOWN_WINDOW = 5 * MINUTES  # Reduced from 10 minutes for faster warm starts
+
+# Maximum concurrent requests (reduce for smaller GPUs)
+MAX_INPUTS = 50
+```
+
+#### Startup Time Optimization
+
+The following optimizations are enabled by default to reduce the ~1 minute startup time:
+
+- **`--max-model-len 65536`**: Limits context window to 64k tokens (faster startup, can increase to 131072 if needed)
+- **`--disable-custom-all-reduce`**: Disabled for single GPU (reduces startup overhead)
+- **`--enable-prefix-caching`**: Enables prefix caching for faster subsequent requests
+- **`--load-format auto`**: Auto-detects best loading format for faster model loading
+- **Reduced scaledown window**: Keeps container warm for 5 minutes instead of 10 (faster warm starts)
+
+Note: `--dtype bfloat16` is required for GPT-OSS (MXFP4 quantization only supports bf16)
+
+## 🔧 Commands
+
+| Command                                 | Description                  |
+| --------------------------------------- | ---------------------------- |
+| `modal run gpt_oss_inference.py`        | Test with a temporary server |
+| `modal deploy gpt_oss_inference.py`     | Deploy to production         |
+| `modal app stop gpt-oss-vllm-inference` | Stop the deployed app        |
+| `modal app logs gpt-oss-vllm-inference` | View deployment logs         |
+| `modal volume ls`                       | List cached volumes          |
+
+## 🌐 API Usage
+
+Once deployed, the server exposes an OpenAI-compatible API:
+
+### Endpoint URL
+
+After deployment, Modal will provide a URL like:
+```
+https://your-workspace--gpt-oss-vllm-inference-serve.modal.run
+```
+
+### Making Requests
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="https://your-workspace--gpt-oss-vllm-inference-serve.modal.run/v1",
+    api_key="not-needed"  # Modal handles auth via the URL
+)
+
+response = client.chat.completions.create(
+    model="llm",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hello!"}
+    ]
+)
+print(response.choices[0].message.content)
+```
+
+### cURL Example
+
+```bash
+curl -X POST "https://your-workspace--gpt-oss-vllm-inference-serve.modal.run/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "llm",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ]
+  }'
+```
+
+## 💰 Pricing
+
+Modal charges per second of usage:
+- **A10G GPU**: ~$0.76/hour (recommended) ✅
+- **L4 GPU**: ~$0.59/hour (cheapest)
+- **A100 40GB**: ~$1.79/hour
+- **H100 GPU**: ~$3.95/hour (fastest)
+- No charges when idle (scale to zero)
+- First $30/month is free
+
+## 📦 Model Details
+
+### GPT-OSS 20B
+- MoE architecture with efficient inference
+- MXFP4 quantization for MoE layers (~10-15GB VRAM)
+- Attention sink support for longer contexts
+- **Fits on A10G, L4, A100, or H100** ✅
+
+### GPT-OSS 120B
+- Larger model with more capabilities
+- Same quantization and architecture (~40-50GB VRAM)
+- **Requires A100 80GB or H100**
+
+## 🔍 Troubleshooting
+
+### Authentication Issues
+```bash
+# Re-authenticate
+modal token new
+```
+
+### GPU Availability
+If your selected GPU is not available, Modal will queue your request. Tips:
+- **A10G and L4** typically have better availability than H100
+- Try different regions
+- Use off-peak hours
+- Change `GPU_CONFIG` to a different tier
+
+### Marlin Kernel Warning
+If you see: `You are running Marlin kernel with bf16 on GPUs before SM90`:
+- **This warning can be safely ignored** - GPT-OSS uses MXFP4 quantization which **requires bfloat16**
+- float16 is NOT supported for MXFP4 quantization (will cause a validation error)
+- The warning is just a performance suggestion, but we cannot use fp16 for this model
+- For optimal performance, use H100 (SM90+) which is optimized for bf16
+
+### Startup Time Optimization
+If startup takes ~1 minute:
+- ✅ **Already optimized** - The code includes several optimizations:
+  - Uses `float16` instead of `bfloat16` for faster loading
+  - Limits context window to 32k tokens (faster memory allocation)
+  - Disables custom all-reduce for single GPU
+  - Enables prefix caching
+  - Uses auto load format detection
+- To reduce startup further, you can:
+  - Increase `SCALEDOWN_WINDOW` to keep container warm longer (costs more)
+  - Use a larger GPU (A100/H100) for faster model loading
+  - Reduce `MAX_MODEL_LEN` if you don't need full context window
+
+### Cache Issues
+```bash
+# Clear vLLM cache
+modal volume rm vllm-cache
+modal volume create vllm-cache
+
+# Clear HuggingFace cache
+modal volume rm huggingface-cache
+modal volume create huggingface-cache
+```
+
+## 📚 Resources
+
+- [Modal Documentation](https://modal.com/docs/guide)
+- [vLLM Documentation](https://docs.vllm.ai/)
+- [GPT-OSS on HuggingFace](https://huggingface.co/openai/gpt-oss-20b)
+- [Modal Examples](https://modal.com/docs/examples)
+

modal/deploy.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+# =============================================================================
+# Modal GPT-OSS Deployment Script
+# =============================================================================
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "🚀 Modal GPT-OSS vLLM Deployment"
+echo "================================"
+echo ""
+
+# Check if modal is installed
+if ! command -v modal &> /dev/null; then
+    echo "❌ Modal CLI not found. Installing..."
+    pip install modal
+    echo ""
+fi
+
+# Check if authenticated
+echo "📋 Checking Modal authentication..."
+if ! modal token info &> /dev/null 2>&1; then
+    echo "❌ Not authenticated with Modal."
+    echo ""
+    echo "Please run: modal setup"
+    echo "Or set your token with: modal token set --token-id <ID> --token-secret <SECRET>"
+    echo ""
+    exit 1
+fi
+
+echo "✅ Authenticated with Modal"
+echo ""
+
+# Show options
+echo "What would you like to do?"
+echo ""
+echo "  1) Test the server (temporary deployment)"
+echo "  2) Deploy to production"
+echo "  3) Stop the deployed app"
+echo "  4) View logs"
+echo "  5) Exit"
+echo ""
+read -p "Enter choice [1-5]: " choice
+
+case $choice in
+    1)
+        echo ""
+        echo "🧪 Running test deployment..."
+        cd "$SCRIPT_DIR"
+        modal run gpt_oss_inference.py
+        ;;
+    2)
+        echo ""
+        echo "🚀 Deploying to production..."
+        cd "$SCRIPT_DIR"
+        modal deploy gpt_oss_inference.py
+        echo ""
+        echo "✅ Deployment complete!"
+        echo ""
+        echo "Your endpoint URL will be displayed above."
+        ;;
+    3)
+        echo ""
+        echo "🛑 Stopping app..."
+        modal app stop gpt-oss-vllm-inference
+        echo "✅ App stopped"
+        ;;
+    4)
+        echo ""
+        echo "📜 Fetching logs..."
+        modal app logs gpt-oss-vllm-inference
+        ;;
+    5)
+        echo "👋 Goodbye!"
+        exit 0
+        ;;
+    *)
+        echo "❌ Invalid choice"
+        exit 1
+        ;;
+esac
+

modal/gpt_oss_inference.py

@@ -0,0 +1,362 @@
+"""
+GPT-OSS Model Deployment on Modal with vLLM
+
+This script deploys OpenAI's GPT-OSS models (20B or 120B) on Modal.com
+with vLLM for efficient inference.
+
+Usage:
+    # First time setup - pre-download model weights (run once, takes ~5-10 min)
+    modal run gpt_oss_inference.py::download_model
+    
+    # Test the server locally
+    modal run gpt_oss_inference.py
+    
+    # Deploy to production
+    modal deploy gpt_oss_inference.py
+
+Performance Tips:
+    1. Run download_model first to cache weights in the volume
+    2. Reduce MAX_MODEL_LEN for faster startup (8k is sufficient for most use cases)
+    3. Keep FAST_BOOT=True for cheaper GPUs (A10G, L4)
+    4. Increase SCALEDOWN_WINDOW to reduce cold starts during demos
+
+Based on: https://modal.com/docs/examples/gpt_oss_inference
+"""
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+import aiohttp
+import modal
+
+# =============================================================================
+# Container Image Configuration
+# =============================================================================
+
+# Enable HF Transfer for faster model downloads (5-10x faster)
+vllm_image = (
+    modal.Image.from_registry(
+        "nvidia/cuda:12.8.1-devel-ubuntu22.04",
+        add_python="3.12",
+    )
+    .entrypoint([])
+    .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})  # Enable fast downloads
+    .uv_pip_install(
+        "vllm==0.11.0",
+        "huggingface_hub[hf_transfer]==0.35.0",
+        "flashinfer-python==0.3.1",
+    )
+)
+
+# =============================================================================
+# Model Configuration
+# =============================================================================
+
+# Choose the model size - 20B is faster, 120B has more capabilities
+MODEL_NAME = "openai/gpt-oss-20b"  # or "openai/gpt-oss-120b"
+MODEL_REVISION = "d666cf3b67006cf8227666739edf25164aaffdeb"
+
+# =============================================================================
+# GPU Configuration - CHOOSE YOUR GPU TIER
+# =============================================================================
+# 
+# Modal GPU Pricing (approximate, per hour):
+# ┌─────────────┬──────────┬────────────────────────────────────────────┐
+# │ GPU         │ Price/hr │ Notes                                      │
+# ├─────────────┼──────────┼────────────────────────────────────────────┤
+# │ T4 (16GB)   │ ~$0.25   │ ❌ Too small for GPT-OSS                   │
+# │ L4 (24GB)   │ ~$0.59   │ ⚠️  Tight fit, may work with 20B           │
+# │ A10G (24GB) │ ~$0.76   │ ✅ Good balance for 20B model              │
+# │ A100 40GB   │ ~$1.79   │ ✅ Comfortable for 20B                     │
+# │ A100 80GB   │ ~$2.78   │ ✅ Works for both 20B and 120B             │
+# │ H100 (80GB) │ ~$3.95   │ ✅ Best performance, both models           │
+# └─────────────┴──────────┴────────────────────────────────────────────┘
+#
+# GPT-OSS 20B with MXFP4 quantization needs ~10-15GB VRAM
+# GPT-OSS 120B needs ~40-50GB VRAM
+
+# Choose your GPU - uncomment the one you want to use:
+GPU_CONFIG = "A100-40GB"  # ~$0.76/hr - RECOMMENDED for budget (works with 20B)
+# GPU_CONFIG = "L4"     # ~$0.59/hr - Cheapest option (may be tight)
+# GPU_CONFIG = "A100"   # ~$1.79/hr - More headroom (40GB version)
+# GPU_CONFIG = "H100"   # ~$3.95/hr - Maximum performance
+
+# =============================================================================
+# Volume Configuration for Caching
+# =============================================================================
+
+# Cache for HuggingFace model weights
+hf_cache_vol = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
+
+# Cache for vLLM compilation artifacts
+vllm_cache_vol = modal.Volume.from_name("vllm-cache", create_if_missing=True)
+
+# =============================================================================
+# Performance Configuration
+# =============================================================================
+
+MINUTES = 60  # Helper constant
+
+# FAST_BOOT = True: Faster startup but slower inference
+# FAST_BOOT = False: Slower startup but faster inference (recommended for production)
+FAST_BOOT = True  # Use True for cheaper GPUs to reduce startup memory
+
+# CUDA graph capture sizes for optimized inference
+CUDA_GRAPH_CAPTURE_SIZES = [1, 2, 4, 8, 16, 24, 32]
+
+# Data type configuration
+# NOTE: GPT-OSS uses MXFP4 quantization which REQUIRES bfloat16 - float16 is NOT supported
+# The Marlin kernel warning on A10G/L4 is expected and can be ignored
+USE_FLOAT16 = False  # Must be False for GPT-OSS (MXFP4 only supports bfloat16)
+
+# Maximum model length (context window) - SIGNIFICANTLY REDUCED for faster startup
+# The KV cache allocation is proportional to context length, so smaller = much faster startup
+# For EU AI Act assessments, 8k-16k tokens is more than enough
+# GPT-OSS 20B supports up to 128k tokens, but we only need ~8k for our use case
+MAX_MODEL_LEN = 16384  # 16k tokens - sufficient for compliance assessments, 4x faster startup
+
+# Server configuration
+VLLM_PORT = 8000
+N_GPU = 1  # Number of GPUs for tensor parallelism
+MAX_INPUTS = 50  # Reduced for smaller GPUs
+
+# Keep container warm longer to avoid cold starts (costs more but faster response)
+# For hackathon demo: 10 minutes to reduce cold starts during presentation
+SCALEDOWN_WINDOW = 10 * MINUTES  # Increased for demo stability
+
+# =============================================================================
+# Modal App Definition
+# =============================================================================
+
+app = modal.App("gpt-oss-vllm-inference")
+
+
+# Select GPU based on GPU_CONFIG
+_GPU_MAP = {
+    "T4": "T4",
+    "L4": "L4",
+    "A10G": "A10G",
+    "A100": "A100:40GB",
+    "A100-80GB": "A100:80GB",
+    "H100": "H100",
+}
+SELECTED_GPU = _GPU_MAP.get(GPU_CONFIG, "A10G")
+
+
+# =============================================================================
+# Pre-download Model Weights (reduces warm start time significantly)
+# =============================================================================
+
+@app.function(
+    image=vllm_image,
+    volumes={"/root/.cache/huggingface": hf_cache_vol},
+    timeout=30 * MINUTES,
+)
+def download_model():
+    """
+    Pre-download the model weights to the volume cache.
+    Run this once with: modal run gpt_oss_inference.py::download_model
+    This will cache the weights and make subsequent starts much faster.
+    """
+    from huggingface_hub import snapshot_download
+    
+    print(f"📥 Downloading model weights for {MODEL_NAME}...")
+    print(f"   Revision: {MODEL_REVISION}")
+    
+    snapshot_download(
+        MODEL_NAME,
+        revision=MODEL_REVISION,
+        local_dir=f"/root/.cache/huggingface/hub/models--{MODEL_NAME.replace('/', '--')}",
+    )
+    
+    print("✅ Model weights downloaded and cached!")
+    print("   Future container starts will use the cached weights.")
+
+
+@app.function(
+    image=vllm_image,
+    gpu=SELECTED_GPU,
+    scaledown_window=SCALEDOWN_WINDOW,
+    timeout=30 * MINUTES,
+    volumes={
+        "/root/.cache/huggingface": hf_cache_vol,
+        "/root/.cache/vllm": vllm_cache_vol,
+    },
+)
+@modal.concurrent(max_inputs=MAX_INPUTS)
+@modal.web_server(port=VLLM_PORT, startup_timeout=30 * MINUTES)
+def serve():
+    """Start the vLLM server with GPT-OSS model."""
+    import subprocess
+
+    cmd = [
+        "vllm",
+        "serve",
+        "--uvicorn-log-level=info",
+        MODEL_NAME,
+        "--revision",
+        MODEL_REVISION,
+        "--served-model-name",
+        "llm",  # Serve model as "llm" - this is what clients expect
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(VLLM_PORT),
+    ]
+
+    # enforce-eager disables both Torch compilation and CUDA graph capture
+    # default is no-enforce-eager. see the --compilation-config flag for tighter control
+    cmd += ["--enforce-eager" if FAST_BOOT else "--no-enforce-eager"]
+
+    if not FAST_BOOT:  # CUDA graph capture is only used with `--no-enforce-eager`
+        cmd += [
+            "-O.cudagraph_capture_sizes="
+            + str(CUDA_GRAPH_CAPTURE_SIZES).replace(" ", "")
+        ]
+
+    # Data type optimization: use float16 for A10G/L4 (SM86) to avoid Marlin kernel warning
+    # bf16 is optimized for SM90+ (H100), fp16 is better for Ampere architecture
+    if USE_FLOAT16:
+        cmd += ["--dtype", "float16"]
+    else:
+        cmd += ["--dtype", "bfloat16"]
+
+    # Limit context length to speed up startup and reduce memory allocation
+    cmd += ["--max-model-len", str(MAX_MODEL_LEN)]
+
+    # Disable custom all-reduce for single GPU (reduces startup overhead)
+    if N_GPU == 1:
+        cmd += ["--disable-custom-all-reduce"]
+
+    # Enable prefix caching for faster subsequent requests
+    cmd += ["--enable-prefix-caching"]
+
+    # Trust remote code for GPT-OSS models
+    cmd += ["--trust-remote-code"]
+
+    # Optimize loading format for faster startup
+    cmd += ["--load-format", "auto"]  # Auto-detect best format
+
+    # assume multiple GPUs are for splitting up large matrix multiplications
+    cmd += ["--tensor-parallel-size", str(N_GPU)]
+
+    # Additional optimizations for faster startup and inference
+    # Disable usage stats collection to speed up startup
+    cmd += ["--disable-log-stats"]
+    
+    # Use swap space if needed (helps with memory pressure on smaller GPUs)
+    cmd += ["--swap-space", "4"]  # 4GB swap space
+
+    print(f"Starting vLLM server with command: {' '.join(cmd)}")
+
+    subprocess.Popen(" ".join(cmd), shell=True)
+
+
+# =============================================================================
+# Local Test Entrypoint
+# =============================================================================
+
+
+@app.local_entrypoint()
+async def test(test_timeout=30 * MINUTES, user_content=None, twice=True):
+    """
+    Test the deployed server with a sample prompt.
+    
+    Args:
+        test_timeout: Maximum time to wait for server health
+        user_content: Custom prompt to send (default: SVD explanation)
+        twice: Whether to send a second request
+    """
+    url = serve.get_web_url()
+    
+    system_prompt = {
+        "role": "system",
+        "content": f"""You are ChatModal, a large language model trained by Modal.
+Knowledge cutoff: 2024-06
+Current date: {datetime.now(timezone.utc).date()}
+Reasoning: low
+# Valid channels: analysis, commentary, final. Channel must be included for every message.
+Calls to these tools must go to the commentary channel: 'functions'.""",
+    }
+
+    if user_content is None:
+        user_content = "Explain what the Singular Value Decomposition is."
+
+    messages = [  # OpenAI chat format
+        system_prompt,
+        {"role": "user", "content": user_content},
+    ]
+
+    async with aiohttp.ClientSession(base_url=url) as session:
+        print(f"Running health check for server at {url}")
+        async with session.get("/health", timeout=test_timeout - 1 * MINUTES) as resp:
+            up = resp.status == 200
+        assert up, f"Failed health check for server at {url}"
+        print(f"Successful health check for server at {url}")
+
+        print(f"Sending messages to {url}:", *messages, sep="\n\t")
+        await _send_request(session, "llm", messages)
+
+        if twice:
+            messages[0]["content"] += "\nTalk like a pirate, matey."
+            print(f"Re-sending messages to {url}:", *messages, sep="\n\t")
+            await _send_request(session, "llm", messages)
+
+
+async def _send_request(
+    session: aiohttp.ClientSession, model: str, messages: list
+) -> None:
+    """Send a streaming request to the vLLM server."""
+    # `stream=True` tells an OpenAI-compatible backend to stream chunks
+    payload: dict[str, Any] = {"messages": messages, "model": model, "stream": True}
+
+    headers = {"Content-Type": "application/json", "Accept": "text/event-stream"}
+
+    t = time.perf_counter()
+    async with session.post(
+        "/v1/chat/completions", json=payload, headers=headers, timeout=10 * MINUTES
+    ) as resp:
+        async for raw in resp.content:
+            resp.raise_for_status()
+            # extract new content and stream it
+            line = raw.decode().strip()
+            if not line or line == "data: [DONE]":
+                continue
+            if line.startswith("data: "):  # SSE prefix
+                line = line[len("data: ") :]
+
+            chunk = json.loads(line)
+            assert (
+                chunk["object"] == "chat.completion.chunk"
+            )  # or something went horribly wrong
+            delta = chunk["choices"][0]["delta"]
+
+            if "content" in delta:
+                print(delta["content"], end="")  # print the content as it comes in
+            elif "reasoning_content" in delta:
+                print(delta["reasoning_content"], end="")
+            elif not delta:
+                print()
+            else:
+                raise ValueError(f"Unsupported response delta: {delta}")
+    print("")
+    print(f"Time to Last Token: {time.perf_counter() - t:.2f} seconds")
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+
+def get_endpoint_url() -> str:
+    """Get the deployed endpoint URL."""
+    return serve.get_web_url()
+
+
+if __name__ == "__main__":
+    print("Run this script with Modal:")
+    print("  modal run gpt_oss_inference.py       # Test the server")
+    print("  modal deploy gpt_oss_inference.py    # Deploy to production")
+

modal/requirements.txt

@@ -0,0 +1,4 @@
+# Modal CLI and dependencies
+modal>=0.64.0
+aiohttp>=3.9.0
+