Sync: Updated CDK code to include possibility of exporting DynamoDB logs to S3 csv output on automated basis

.dockerignore

@@ -0,0 +1,56 @@
+*.pdf
+*.url
+*.jpg
+*.png
+*.ipynb
+*.xls
+*.xlsx
+*.pyc
+*.json.bak.*
+examples/*
+output/*
+tools/__pycache__/*
+build/*
+dist/*
+logs/*
+usage/*
+docs/*
+guide/*
+feedback/*
+test_code/*
+test/tmp/*
+unsloth_compiled_cache/*
+.vscode/*
+llm_topic_modelling.egg-info/*
+input/
+output/
+logs/
+usage/
+feedback/
+config/
+tmp/
+index.qmd
+_quarto.yml
+!config/pi_agent.env.example
+!config/docker_app_config.env.example
+!config/app_config.env.example
+workspace/*
+user_guide/*
+_extensions/*
+cdk/config/*
+!cdk/config/app_config.env.example
+!cdk/config/lambda/
+cdk/config/lambda/*
+!cdk/config/lambda/lambda_function.py
+!cdk/config/headless_s3_seed/
+cdk/config/headless_s3_seed/*
+!cdk/config/headless_s3_seed/input/
+cdk/config/headless_s3_seed/input/*
+!cdk/config/headless_s3_seed/input/config/
+cdk/config/headless_s3_seed/input/config/*
+!cdk/config/headless_s3_seed/input/config/example_headless_env_file.env
+cdk/cdk.out/*
+cdk/archive/*
+cdk/cdk.json
+cdk/cdk.context.json
+cdk/precheck.context.json

.gitattributes

@@ -0,0 +1 @@
+*.xlsx filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,196 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  #schedule:
+  # Run tests daily at 2 AM UTC
+  #  - cron: '0 2 * * *'
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+  issues: write
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ruff black
+    
+    - name: Run Ruff linter
+      run: ruff check .
+    
+    - name: Run Black formatter check
+      run: black --check .
+
+  test-unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.11, 3.12, 3.13]
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Cache pip dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+    
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov pytest-html pytest-xdist
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/ || echo "example_data directory not found"
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+    
+    - name: Run CLI and GUI tests
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Run tests with pytest
+      run: |
+        pytest test/test.py test/test_gui_only.py -v --tb=short --junitxml=test-results.xml
+    
+    - name: Run tests with coverage
+      run: |
+        pytest test/test.py test/test_gui_only.py --cov=. --cov-report=xml --cov-report=html --cov-report=term
+    
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results-python-${{ matrix.python-version }}
+        path: |
+          test-results.xml
+          htmlcov/
+          coverage.xml
+
+  test-integration:
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit]
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+    
+    - name: Run integration tests (CLI and GUI)
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Test CLI help
+      run: |
+        python cli_topics.py --help
+    
+    - name: Test CLI version
+      run: |
+        python -c "import sys; print(f'Python {sys.version}')"
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install bandit
+    
+    - name: Run bandit security check
+      run: |
+        bandit -r . -f json -o bandit-report.json || true
+    
+    - name: Upload security report
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: security-report
+        path: bandit-report.json
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Build package
+      run: |
+        python -m build
+    
+    - name: Check package
+      run: |
+        twine check dist/*
+    
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+

.github/workflows/simple-test.yml

@@ -0,0 +1,46 @@
+name: Simple Test Run
+
+on:
+  push:
+    branches: [ dev ]
+  pull_request:
+    branches: [ dev ]
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+    
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_lightweight.txt
+        pip install pytest pytest-cov
+    
+    - name: Verify example data files
+      run: |
+        echo "Checking if example data directory exists:"
+        ls -la example_data/ || echo "example_data directory not found"
+        echo "Checking for specific CSV files:"
+        ls -la example_data/*.csv || echo "No CSV files found"
+    
+    - name: Run CLI and GUI tests
+      run: |
+        cd test
+        python run_tests.py
+    
+    - name: Run tests with pytest
+      run: |
+        pytest test/test.py test/test_gui_only.py -v --tb=short
+

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,53 @@
+name: Sync to Hugging Face hub
+on:
+  push:
+    branches: [dev]
+
+permissions:
+  contents: read
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1      # Only get the latest state
+          lfs: true           # Download actual LFS files so they can be pushed
+
+      - name: Install Git LFS
+        run: git lfs install
+
+      - name: Recreate repo history (single-commit force push)
+        run: |
+          # 1. Capture the message BEFORE we delete the .git folder
+          COMMIT_MSG=$(git log -1 --pretty=%B)
+          echo "Syncing commit message: $COMMIT_MSG"
+
+          # 2. DELETE the .git folder. 
+          # This turns the repo into a standard folder of files.
+          rm -rf .git
+
+          # 3. Re-initialize a brand new git repo
+          git init -b main
+          git config --global user.name "$HF_USERNAME"
+          git config --global user.email "$HF_EMAIL"
+          
+          # 4. Re-install LFS (needs to be done after git init)
+          git lfs install
+          
+          # 5. Add the remote
+          git remote add hf https://$HF_USERNAME:$HF_TOKEN@huggingface.co/spaces/$HF_USERNAME/$HF_REPO_ID
+          
+          # 6. Add all files
+          # Since this is a fresh init, Git sees EVERY file as "New"
+          git add .
+          
+          # 7. Commit and Force Push
+          git commit -m "Sync: $COMMIT_MSG"
+          git push --force hf main
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USERNAME: ${{ secrets.HF_USERNAME }}
+          HF_EMAIL: ${{ secrets.HF_EMAIL }}
+          HF_REPO_ID: ${{ secrets.HF_REPO_ID }}

.gitignore

@@ -0,0 +1,55 @@
+*.pdf
+*.url
+*.jpg
+*.png
+*.ipynb
+*.xls
+*.pyc
+*.json.bak.*
+examples/*
+output/*
+tools/__pycache__/*
+build/*
+dist/*
+logs/*
+docs/*
+guide/*
+usage/*
+feedback/*
+test_code/*
+config/*
+tmp/*
+test/tmp/*
+unsloth_compiled_cache/*
+.vscode/*
+llm_topic_modelling.egg-info/*
+index.qmd
+_quarto.yml
+/.quarto/
+**/*.quarto_ipynb
+config/*
+!config/pi_agent.env.example
+!config/docker_app_config.env.example
+!config/app_config.env.example
+workspace/*
+user_guide/*
+_extensions/*
+cdk/config/*
+!cdk/config/app_config.env.example
+!cdk/config/lambda/
+cdk/config/lambda/*
+!cdk/config/lambda/lambda_function.py
+!cdk/config/headless_s3_seed/
+cdk/config/headless_s3_seed/*
+!cdk/config/headless_s3_seed/input/
+cdk/config/headless_s3_seed/input/*
+!cdk/config/headless_s3_seed/input/config/
+cdk/config/headless_s3_seed/input/config/*
+!cdk/config/headless_s3_seed/input/config/example_headless_env_file.env
+cdk/cdk.out/*
+cdk/archive/*
+cdk/cdk.out/*
+cdk/cdk.json
+cdk/cdk.context.json
+cdk/precheck.context.json
+

Dockerfile

@@ -0,0 +1,165 @@
+# This Dockerfile is optimised for AWS ECS using Python 3.12, and assumes CUDA 12.6 for local models. The Dockerfile will need to be modified to install all linux CUDA / GPU dependencies.
+
+# Stage 1: Build dependencies and download models
+FROM public.ecr.aws/docker/library/python:3.12.12-slim-trixie AS builder
+
+# Install system dependencies.
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    g++ \
+    cmake \
+    #libopenblas-dev \
+    pkg-config \
+    python3-dev \
+    libffi-dev \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+
+COPY requirements_lightweight.txt .
+
+ARG INSTALL_TORCH=False
+ENV INSTALL_TORCH=${INSTALL_TORCH}
+
+# Local torch install requires CUDA 12.6
+RUN if [ "$INSTALL_TORCH" = "True" ]; then \
+    pip install --no-cache-dir --target=/install torch==2.9.1 --extra-index-url https://download.pytorch.org/whl/cu126; \
+    fi
+
+ARG INSTALL_LLAMA_CPP_PYTHON=False
+ENV INSTALL_LLAMA_CPP_PYTHON=${INSTALL_LLAMA_CPP_PYTHON}
+
+# Llama CPP Python install requires CUDA 12.4
+RUN if [ "$INSTALL_LLAMA_CPP_PYTHON" = "True" ]; then \
+    pip install --no-cache-dir --target=/install https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.16-cu124/llama_cpp_python-0.3.30-cp312-cp312-linux_x86_64.whl; \
+    fi
+
+RUN pip install --no-cache-dir --target=/install -r requirements_lightweight.txt
+
+RUN rm requirements_lightweight.txt
+
+# ===================================================================
+# Stage 2: A common 'base' for both Lambda and Gradio
+# ===================================================================
+FROM public.ecr.aws/docker/library/python:3.12.12-slim-trixie AS base
+
+# Set build-time and runtime environment variable for whether to run in Gradio mode or Lambda mode
+ARG APP_MODE=gradio
+ENV APP_MODE=${APP_MODE}
+
+# Install runtime system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libopenblas0 \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+ENV APP_HOME=/home/user
+
+# Set env variables for Gradio & other apps
+ENV GRADIO_TEMP_DIR=/tmp/gradio_tmp/ \
+    MPLCONFIGDIR=/tmp/matplotlib_cache/ \
+    GRADIO_OUTPUT_FOLDER=$APP_HOME/app/output/ \
+    GRADIO_INPUT_FOLDER=$APP_HOME/app/input/ \
+    FEEDBACK_LOGS_FOLDER=$APP_HOME/app/feedback/ \
+    ACCESS_LOGS_FOLDER=$APP_HOME/app/logs/ \
+    USAGE_LOGS_FOLDER=$APP_HOME/app/usage/ \
+    CONFIG_FOLDER=$APP_HOME/app/config/ \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    PATH=$APP_HOME/.local/bin:$PATH \
+    PYTHONPATH=$APP_HOME/app \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    GRADIO_ALLOW_FLAGGING=never \
+    GRADIO_NUM_PORTS=1 \
+    GRADIO_THEME=huggingface \
+    SYSTEM=spaces
+
+# Copy Python packages from the builder stage
+COPY --from=builder /install /usr/local/lib/python3.12/site-packages/
+COPY --from=builder /install/bin /usr/local/bin/
+
+# Copy your application code and entrypoint
+COPY . ${APP_HOME}/app
+COPY entrypoint.sh ${APP_HOME}/app/entrypoint.sh
+# Fix line endings and set execute permissions
+RUN sed -i 's/\r$//' ${APP_HOME}/app/entrypoint.sh \
+    && chmod +x ${APP_HOME}/app/entrypoint.sh
+
+WORKDIR ${APP_HOME}/app
+
+# ===================================================================
+# FINAL Stage 3: The Lambda Image (runs as root for simplicity)
+# ===================================================================
+FROM base AS lambda
+# Set runtime ENV for Lambda mode
+ENV APP_MODE=lambda
+ENTRYPOINT ["/home/user/app/entrypoint.sh"]
+CMD ["lambda_entrypoint.lambda_handler"]
+
+# ===================================================================
+# FINAL Stage 4: The Gradio Image (runs as a secure, non-root user)
+# ===================================================================
+FROM base AS gradio
+# Set runtime ENV for Gradio mode
+ENV APP_MODE=gradio
+
+# Create non-root user
+RUN useradd -m -u 1000 user
+
+# Create the base application directory and set its ownership
+RUN mkdir -p ${APP_HOME}/app && chown user:user ${APP_HOME}/app
+
+# Create required sub-folders within the app directory and set their permissions
+RUN mkdir -p \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config \
+    && chown user:user \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config \
+    && chmod 755 \
+    ${APP_HOME}/app/output \
+    ${APP_HOME}/app/input \
+    ${APP_HOME}/app/logs \
+    ${APP_HOME}/app/usage \
+    ${APP_HOME}/app/feedback \
+    ${APP_HOME}/app/config
+
+# Now handle the /tmp directories
+RUN mkdir -p /tmp/gradio_tmp /tmp/matplotlib_cache /tmp /var/tmp \
+    && chown user:user /tmp /var/tmp /tmp/gradio_tmp /tmp/matplotlib_cache \
+    && chmod 1777 /tmp /var/tmp /tmp/gradio_tmp /tmp/matplotlib_cache
+
+# Fix apply user ownership to all files in the home directory
+RUN chown -R user:user /home/user
+
+# Set permissions for Python executable
+RUN chmod 755 /usr/local/bin/python
+
+# Declare volumes
+VOLUME ["/tmp/matplotlib_cache"]
+VOLUME ["/tmp/gradio_tmp"]
+VOLUME ["/home/user/app/output"]
+VOLUME ["/home/user/app/input"]
+VOLUME ["/home/user/app/logs"]
+VOLUME ["/home/user/app/usage"]
+VOLUME ["/home/user/app/feedback"]
+VOLUME ["/home/user/app/config"]
+VOLUME ["/tmp"]
+VOLUME ["/var/tmp"]
+
+USER user
+
+EXPOSE $GRADIO_SERVER_PORT
+
+ENTRYPOINT ["/home/user/app/entrypoint.sh"]
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -0,0 +1,174 @@
+---
+title: Large language model topic modelling
+emoji: 📚
+colorFrom: purple
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.19.0
+app_file: app.py
+pinned: true
+license: agpl-3.0
+short_description: Extract topics from open text data with LLMs
+---
+
+# Large language model topic modelling
+
+Version: 0.13.0
+
+Extract topics and summarise outputs using Large Language Models (LLMs), either local, Gemini, Azure, or AWS Bedrock models (e.g. Claude, Nova models). The app will query the LLM with batches of responses to produce summary tables, which are then compared iteratively to output a table with the general topics, subtopics, topic sentiment, and a topic summary. Instructions on use can be found in the README.md file. You can try out examples by clicking on one of the example datasets on the main app page, which will show you example outputs from a local model run. API keys for AWS, Azure, and Gemini services can be entered on the settings page (note that Gemini has a free public API).
+
+NOTE: Large language models are not 100% accurate and may produce biased or harmful outputs. All outputs from this app **absolutely need to be checked by a human** to check for harmful outputs, hallucinations, and accuracy.
+
+Basic use:
+1. On the front page, choose your model for inference. Gemma 3/GPT-OSS will use 'on-device' inference. Calls to Gemini or AWS will require an API key that can be input on the 'LLM and topic extraction' page.
+1. Upload a csv/xlsx/parquet file containing at least one open text column.
+2. Select the relevant open text column from the dropdown.
+3. If you have your own suggested (zero shot) topics, upload this (see examples folder for an example file)
+4. Write a one sentence description of the consultation/context of the open text.
+5. Click 'Extract topics, deduplicate, and summarise'. This will run through the whole analysis process from topic extraction, to topic deduplication, to topic-level and overall summaries.
+6. A summary xlsx file workbook will be created on the front page in the box 'Overall summary xlsx file'. This will combine all the results from the different processes into one workbook.
+
+# Installation guide
+
+Here is a step-by-step guide to clone the repository, create a virtual environment, and install dependencies from the relevant `requirements` file. This guide assumes you have **Git** and **Python 3.11** installed.
+
+-----
+
+### Step 1: Clone the Git Repository
+
+First, you need to copy the project files to your local machine. Navigate to the directory where you want to store the project using the `cd` (change directory) command. Then, use `git clone` with the repository's URL.
+
+1.  **Clone the repo:**
+
+    ```bash
+    git clone https://github.com/seanpedrick-case/llm_topic_modelling.git
+    ```
+
+2.  **Navigate into the new project folder:**
+
+    ```bash
+    cd llm_topic_modelling
+    ```
+-----
+
+### Step 2: Create and Activate a Virtual Environment
+
+A virtual environment is a self-contained directory that holds a specific Python interpreter and its own set of installed packages. This is crucial for isolating your project's dependencies.
+
+NOTE: Alternatively you could also create and activate a Conda environment instead of using venv below.
+
+1.  **Create the virtual environment:** We'll use Python's built-in `venv` module. It's common practice to name the environment folder `.venv`.
+
+    ```bash
+    python -m venv .venv
+    ```
+
+    *This command tells Python to create a new virtual environment in a folder named `.venv`.*
+
+2.  **Activate the environment:** You must "activate" the environment to start using it. The command differs based on your operating system and shell.
+
+      * **On macOS / Linux (bash/zsh):**
+
+        ```bash
+        source .venv/bin/activate
+        ```
+
+      * **On Windows (Command Prompt):**
+
+        ```bash
+        .\.venv\Scripts\activate
+        ```
+
+      * **On Windows (PowerShell):**
+
+        ```powershell
+        .\.venv\Scripts\Activate.ps1
+        ```
+
+    You'll know it's active because your command prompt will be prefixed with `(.venv)`.
+
+-----
+
+### Step 3: Install Dependencies
+
+Now that your virtual environment is active, you can install all the required packages. Here you have two options, install from the pyproject.toml file (recommended), or install from requirements files.
+
+1. **Install from pyproject.toml (recommended)**
+
+You can install the 'lightweight' version of the app to access all available cloud provider or local inference (e.g. llama server, vLLM server) APIs. This version will not allow you to run local models such as Gemma 12b or GPT-OSS-20b 'in-app', i.e. accessible from the GUI interface directly. However, you will have access to AWS, Gemma, or Azure/OpenAI models with appropriate API keys. Use the following command in your environment to install the relevant packages:
+
+```bash
+pip install .
+```
+
+#### Install torch (optional)
+
+If you want to run inference with transformers with full/quantised models, and the associated Unsloth package, you can run the following command for CPU inference. For GPU inference, please refer to the requirements_gpu.txt guide, and the 'Install from a requirements file' section below:
+
+```bash
+pip install .[torch]
+```
+
+#### Install llama-cpp-python (optional)
+
+You can run quantised GGUF models in-app using llama-cpp-python. However, installation of this package is not always straightforward, particularly considering that wheels are not available for the latest version apart from for linux. This package is not being updated regularly, and so support may be removed for this package in future. Long term I would advise instead looking into running GGUF models using llama-server and calling the API from this app using the lightweight version (details here: https://github.com/ggml-org/llama.cpp).
+
+If you do want to install llama-cpp-python in app, first try the following command:
+
+```bash
+pip install .[llamacpp]
+```
+
+This will install the CPU version of llama-cpp-python. If you want GPU support, first I would try using pip install with specific wheels for your system: See files in https://github.com/abetlen/llama-cpp-python/releases . If you are still struggling, see here for more details on installation here: https://llama-cpp-python.readthedocs.io/en/latest
+
+#### Install mcp version of gradio
+
+You can install an mcp-compatible version of gradio for this app with the following command:
+
+```bash
+pip install .[mcp]
+```
+
+2. **Install from a requirements file (not recommended)**
+
+The repo provides several requirements files that are relevant for different situations. To start, I advise installing using the **requirements_lightweight.txt** file, which installs the app with access to all cloud provider or local inference (e.g. llama server, vLLM server) APIs. This approach is much simpler as a first step, and avoids issues with potentially complicated llama-cpp-python installation and GPU management described below.
+
+If you want to run models locally 'in app', then you have two further requirements files to choose from:
+
+- **requirements_cpu.txt**: Used for Python 3.11 CPU-only environments. Uncomment the requirements under 'Windows' for Windows compatibility. Make sure you have [Openblas](https://github.com/OpenMathLib/OpenBLAS) installed!
+- **requirements_gpu.txt**: Used for Python 3.11 GPU-enabled environments. Uncomment the requirements under 'Windows' for Windows compatibility (CUDA 12.4).
+
+Example The below instructions will guide you in how to install the GPU-enabled version of the app for local inference.
+
+**Install packages for local model 'in-app' inference from the requirements file:**
+    ```bash
+    pip install -r requirements_gpu.txt
+    ```
+    *This command reads every package name listed in the file and installs it into your `.venv` environment.*
+
+NOTE: If default llama-cpp-python installation does not work when installing from the above, go into the requirements_gpu.txt file and uncomment the lines to install a wheel for llama-cpp-python 0.3.16 relevant to your system.
+
+### Step 4: Verify CUDA compatibility (if using a GPU environment)
+
+Install the relevant toolkit for CUDA from here: https://developer.nvidia.com/
+
+Restart your computer
+
+Ensure you have the latest drivers for your NVIDIA GPU. Check your current version and memory availability by running nvidia-smi
+
+In command line, CUDA compatibility can be checked by running nvcc --version
+
+
+### Step 5: Ensure you have compatible NVIDIA drivers
+
+Make sure you have the latest NVIDIA drivers installed on your system for your GPU (be careful in particular if using WSL that you have drivers compatible with this). Official drivers can be found here: https://www.nvidia.com/en-us/drivers
+
+Current drivers can be found by running nvidia-smi in command line
+
+### Step 6: Run the app
+
+Go to the app project directory. Run python app.py
+
+### Step 7: (optional) change default configuration
+
+A number of configuration options can be seen the tools/config.py file. You can either pass in these variables as environment variables, or you can create a file in config/app_config.env to read this into the app on initialisation.

cdk/app.py

@@ -0,0 +1,123 @@
+import os
+
+from aws_cdk import App, Environment
+from cdk_appregistry import register_llm_topic_application
+from cdk_config import (
+    ALB_NAME,
+    APPREGISTRY_APPLICATION_NAME,
+    APPREGISTRY_ATTRIBUTE_GROUP_NAME,
+    APPREGISTRY_DESCRIPTION,
+    APPREGISTRY_REPOSITORY_URL,
+    APPREGISTRY_STACK_NAME,
+    AWS_ACCOUNT_ID,
+    AWS_REGION,
+    CDK_CONTEXT_FILE,
+    CDK_PREFIX,
+    ENABLE_APPREGISTRY,
+    RUN_USEAST_STACK,
+    USE_CLOUDFRONT,
+)
+from cdk_functions import (
+    create_basic_config_env,
+    is_resource_delete_protection_enabled,
+    load_context_from_file,
+    log_aws_credential_context,
+    purge_cdk_lookup_context,
+)
+from cdk_stack import CdkStack, CdkStackCloudfront  # , CdkStackMain
+from check_resources import CONTEXT_FILE, check_and_set_context
+
+# Initialize the CDK app
+app = App()
+
+log_aws_credential_context(
+    expected_account_id=AWS_ACCOUNT_ID,
+    expected_region=AWS_REGION,
+)
+
+# Drop stale CDK lookup cache entries (require bootstrap lookup role in target account).
+purge_cdk_lookup_context(CDK_CONTEXT_FILE)
+
+# --- Pre-check context (boto3) — written to precheck.context.json, NOT cdk.context.json ---
+print(f"Pre-check context file: {CONTEXT_FILE}")
+print(f"CDK lookup cache file: {CDK_CONTEXT_FILE}")
+if os.path.basename(CONTEXT_FILE.replace("\\", "/")) == os.path.basename(
+    CDK_CONTEXT_FILE.replace("\\", "/")
+):
+    raise RuntimeError(
+        f"CONTEXT_FILE and CDK_CONTEXT_FILE must differ (got '{CONTEXT_FILE}' for both). "
+        "Set CONTEXT_FILE=precheck.context.json in config/cdk_config.env."
+    )
+
+print("Running pre-check script to generate application context...")
+try:
+    check_and_set_context()
+    if not os.path.exists(CONTEXT_FILE):
+        raise RuntimeError(
+            f"check_and_set_context() finished, but {CONTEXT_FILE} was not created."
+        )
+    print(f"Context generated successfully at {CONTEXT_FILE}.")
+except Exception as e:
+    raise RuntimeError(f"Failed to generate context via check_and_set_context(): {e}")
+
+# Pre-check must not repopulate CDK lookup keys; purge again if paths were ever shared.
+purge_cdk_lookup_context(CDK_CONTEXT_FILE)
+
+if os.path.exists(CONTEXT_FILE):
+    load_context_from_file(app, CONTEXT_FILE)
+else:
+    raise RuntimeError(f"Could not find {CONTEXT_FILE}.")
+
+create_basic_config_env("config")
+
+aws_env_regional = Environment(account=AWS_ACCOUNT_ID, region=AWS_REGION)
+
+_stack_delete_protection = is_resource_delete_protection_enabled()
+
+regional_stack = CdkStack(
+    app, "SummarisationStack", env=aws_env_regional, cross_region_references=True
+)
+regional_stack.termination_protection = _stack_delete_protection
+
+if ENABLE_APPREGISTRY == "True":
+    # Use pre-check context only — not regional_stack.params (avoids AppRegistry
+    # -> SummarisationStack dependency cycle during synth).
+    _alb_dns_context = app.node.try_get_context(f"dns:{ALB_NAME}")
+    _alb_dns_name = (
+        _alb_dns_context.strip()
+        if isinstance(_alb_dns_context, str) and _alb_dns_context.strip()
+        else None
+    )
+    appregistry_stack = register_llm_topic_application(
+        app,
+        aws_account_id=AWS_ACCOUNT_ID,
+        aws_region=AWS_REGION,
+        application_name=APPREGISTRY_APPLICATION_NAME,
+        application_description=APPREGISTRY_DESCRIPTION,
+        appregistry_stack_name=APPREGISTRY_STACK_NAME,
+        attribute_group_name=APPREGISTRY_ATTRIBUTE_GROUP_NAME,
+        repository_url=APPREGISTRY_REPOSITORY_URL,
+        cdk_prefix=CDK_PREFIX,
+        use_cloudfront=USE_CLOUDFRONT,
+        alb_dns_name=_alb_dns_name,
+    )
+    appregistry_stack.termination_protection = _stack_delete_protection
+
+if USE_CLOUDFRONT == "True" and RUN_USEAST_STACK == "True":
+    aws_env_us_east_1 = Environment(account=AWS_ACCOUNT_ID, region="us-east-1")
+
+    cloudfront_stack = CdkStackCloudfront(
+        app,
+        "SummarisationStackCloudfront",
+        env=aws_env_us_east_1,
+        alb_arn=regional_stack.params["alb_arn_output"],
+        alb_sec_group_id=regional_stack.params["alb_security_group_id"],
+        alb_dns_name=regional_stack.params["alb_dns_name"],
+        cross_region_references=True,
+    )
+    cloudfront_stack.termination_protection = _stack_delete_protection
+
+# CDK CLI invokes this script and expects a cloud assembly in cdk.out.
+# Without app.synth(), Python defines constructs but never writes manifest.json
+# (ENOENT on deploy). See: https://github.com/aws/aws-cdk/issues/11023
+app.synth()

cdk/cdk.json.example

@@ -0,0 +1,7 @@
+{
+  "app": "python app.py",
+  "output": "cdk.out",
+  "context": {
+    "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": false
+  }
+}

cdk/cdk_appregistry.py

@@ -0,0 +1,74 @@
+"""AWS Console myApplications (Service Catalog AppRegistry) integration."""
+
+from aws_cdk import App, Environment
+from aws_cdk.aws_servicecatalogappregistry_alpha import (
+    ApplicationAssociator,
+    TargetApplication,
+)
+
+
+def register_llm_topic_application(
+    app: App,
+    *,
+    aws_account_id: str,
+    aws_region: str,
+    application_name: str,
+    application_description: str,
+    appregistry_stack_name: str,
+    attribute_group_name: str,
+    repository_url: str,
+    cdk_prefix: str,
+    use_cloudfront: str,
+    alb_dns_name: str | None = None,
+) -> ApplicationAssociator:
+    """
+    Register regional CDK stacks with AWS Console myApplications.
+
+    Only stacks in ``aws_region`` are associated (phase 1). Cross-region stacks
+    such as SummarisationStackCloudfront (us-east-1) are not included.
+
+    ``alb_dns_name`` must be a plain string (e.g. from pre-check context). Do not
+    pass a CloudFormation token from SummarisationStack or synth will fail with a
+    dependency cycle against the associator stack.
+    """
+    associator = ApplicationAssociator(
+        app,
+        "SummarisationAppRegistry",
+        applications=[
+            TargetApplication.create_application_stack(
+                application_name=application_name,
+                application_description=application_description,
+                stack_name=appregistry_stack_name,
+                env=Environment(account=aws_account_id, region=aws_region),
+            )
+        ],
+    )
+
+    attributes = {
+        "repository": repository_url,
+        "cdkPrefix": cdk_prefix,
+        "awsRegion": aws_region,
+        "useCloudFront": use_cloudfront,
+        "cloudFrontInAppRegistry": "false",
+        "cloudFrontNote": (
+            "CloudFront/WAF (SummarisationStackCloudfront) is in us-east-1 and is "
+            "not linked to this myApplications entry in phase 1. View it in "
+            "CloudFormation (us-east-1) or the CloudFront console."
+        ),
+    }
+    if alb_dns_name:
+        attributes["albDnsName"] = alb_dns_name
+
+    associator.app_registry_application.add_attribute_group(
+        "SummarisationAttributeGroup",
+        attribute_group_name=attribute_group_name,
+        description="llm_topic_modeller deployment metadata",
+        attributes=attributes,
+    )
+
+    return associator
+
+
+def register_doc_summarisation_application(*args, **kwargs):
+    """Deprecated alias for register_llm_topic_application."""
+    return register_llm_topic_application(*args, **kwargs)

cdk/cdk_cloudfront_headers.py

@@ -0,0 +1,172 @@
+"""CloudFront response headers policy (CSP and related security headers)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+
+from aws_cdk import Duration
+from aws_cdk import aws_cloudfront as cloudfront
+from constructs import Construct
+
+# Template exported from AWS; placeholders {APP-URL} and {COGNITO-APP-CLIENT-LOGIN-URL}.
+_CSP_TEMPLATE = (
+    "default-src 'self'; script-src 'self' cdnjs.cloudflare.com 'unsafe-inline'; "
+    "style-src 'self' https://fonts.googleapis.com 'unsafe-inline'; "
+    "img-src 'self' data:; font-src 'self' https://fonts.gstatic.com data:; "
+    "connect-src 'self' wss://{app_hostname} https://cdnjs.cloudflare.com; "
+    "form-action 'self'; frame-ancestors 'none'; object-src 'none'; base-uri 'self'; "
+    "manifest-src 'self' {cognito_login_url}; upgrade-insecure-requests;"
+)
+
+RESPONSE_HEADERS_POLICY_TEMPLATE_PATH = (
+    Path(__file__).resolve().parent / "config" / "response-headers-policy-config.json"
+)
+
+
+def normalize_https_origin(url: str) -> str:
+    """Return a canonical https origin (scheme + host, no path)."""
+    value = (url or "").strip()
+    if not value:
+        return ""
+    if "://" not in value:
+        value = f"https://{value}"
+    parsed = urlparse(value)
+    if not parsed.hostname:
+        return value.rstrip("/")
+    scheme = parsed.scheme or "https"
+    netloc = parsed.netloc or parsed.hostname
+    return f"{scheme}://{netloc}".rstrip("/")
+
+
+def hostname_from_origin(origin: str) -> str:
+    parsed = urlparse(origin if "://" in origin else f"https://{origin}")
+    return parsed.hostname or origin.strip()
+
+
+def cognito_hosted_ui_base_url(domain_prefix: str, region: str) -> str:
+    prefix = (domain_prefix or "").strip()
+    if not prefix:
+        return ""
+    return f"https://{prefix}.auth.{region}.amazoncognito.com"
+
+
+def build_content_security_policy(
+    *,
+    app_origin: str,
+    cognito_login_url: str,
+) -> str:
+    origin = normalize_https_origin(app_origin)
+    hostname = hostname_from_origin(origin)
+    cognito_url = normalize_https_origin(cognito_login_url)
+    return _CSP_TEMPLATE.format(app_hostname=hostname, cognito_login_url=cognito_url)
+
+
+def create_secure_cloudfront_response_headers_policy(
+    scope: Construct,
+    construct_id: str,
+    *,
+    policy_name: str,
+    app_origin: str,
+    cognito_login_url: str,
+    comment: str = "Secure response headers with CSP for llm_topic_modeller",
+) -> cloudfront.ResponseHeadersPolicy:
+    """Response headers policy aligned with config/response-headers-policy-config.json."""
+    cors_origin = normalize_https_origin(app_origin)
+    csp = build_content_security_policy(
+        app_origin=app_origin,
+        cognito_login_url=cognito_login_url,
+    )
+
+    return cloudfront.ResponseHeadersPolicy(
+        scope,
+        construct_id,
+        response_headers_policy_name=policy_name,
+        comment=comment,
+        cors_behavior=cloudfront.ResponseHeadersCorsBehavior(
+            access_control_allow_credentials=False,
+            access_control_allow_headers=["*"],
+            access_control_allow_methods=["ALL"],
+            access_control_allow_origins=[cors_origin],
+            access_control_max_age=Duration.seconds(600),
+            origin_override=True,
+        ),
+        security_headers_behavior=cloudfront.ResponseSecurityHeadersBehavior(
+            content_security_policy=cloudfront.ResponseHeadersContentSecurityPolicy(
+                content_security_policy=csp,
+                override=True,
+            ),
+            content_type_options=cloudfront.ResponseHeadersContentTypeOptions(
+                override=True
+            ),
+            frame_options=cloudfront.ResponseHeadersFrameOptions(
+                frame_option=cloudfront.HeadersFrameOption.SAMEORIGIN,
+                override=True,
+            ),
+            referrer_policy=cloudfront.ResponseHeadersReferrerPolicy(
+                referrer_policy=cloudfront.HeadersReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN,
+                override=True,
+            ),
+            strict_transport_security=cloudfront.ResponseHeadersStrictTransportSecurity(
+                access_control_max_age=Duration.seconds(31536000),
+                include_subdomains=True,
+                preload=False,
+                override=True,
+            ),
+            xss_protection=cloudfront.ResponseHeadersXSSProtection(
+                protection=True,
+                mode_block=True,
+                override=True,
+            ),
+        ),
+        custom_headers_behavior=cloudfront.ResponseCustomHeadersBehavior(
+            custom_headers=[
+                cloudfront.ResponseCustomHeader(
+                    header="Permissions-Policy",
+                    value=(
+                        "accelerometer=(), autoplay=(), camera=(), "
+                        "cross-origin-isolated=(), display-capture=(), encrypted-media=(), "
+                        "fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), "
+                        "magnetometer=(), microphone=(), midi=(), payment=(), "
+                        "picture-in-picture=(), publickey-credentials-get=(), "
+                        "screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), "
+                        "xr-spatial-tracking=()"
+                    ),
+                    override=True,
+                )
+            ]
+        ),
+        remove_headers=["Server"],
+    )
+
+
+def resolve_cloudfront_csp_urls(
+    *,
+    cognito_redirection_url: str,
+    cloudfront_domain: str,
+    cognito_user_pool_domain_prefix: str,
+    aws_region: str,
+    cognito_user_pool_login_url: str = "",
+    ssl_certificate_domain: str = "",
+) -> tuple[str, str]:
+    """
+    Return (app_origin, cognito_login_url) for CSP/CORS substitution.
+
+    App origin prefers COGNITO_REDIRECTION_URL (canonical browser URL), then
+    https://SSL_CERTIFICATE_DOMAIN, then https://CLOUDFRONT_DOMAIN.
+    Cognito login URL uses COGNITO_USER_POOL_LOGIN_URL when set, else the
+    hosted UI base URL derived from COGNITO_USER_POOL_DOMAIN_PREFIX.
+    """
+    app_origin = normalize_https_origin(cognito_redirection_url)
+    if not app_origin or "placeholder" in app_origin.lower():
+        if ssl_certificate_domain.strip():
+            app_origin = normalize_https_origin(ssl_certificate_domain)
+        elif cloudfront_domain.strip():
+            app_origin = normalize_https_origin(cloudfront_domain)
+
+    login_url = (cognito_user_pool_login_url or "").strip()
+    if not login_url:
+        login_url = cognito_hosted_ui_base_url(
+            cognito_user_pool_domain_prefix, aws_region
+        )
+    return app_origin, normalize_https_origin(login_url)

cdk/cdk_config.py

@@ -0,0 +1,851 @@
+import os
+import tempfile
+from typing import List
+
+from dotenv import load_dotenv
+
+# Set or retrieve configuration variables for CDK llm_topic_modeller deployment
+
+
+def convert_string_to_boolean(value: str) -> bool:
+    """Convert string to boolean, handling various formats."""
+    if isinstance(value, bool):
+        return value
+    elif value in ["True", "1", "true", "TRUE"]:
+        return True
+    elif value in ["False", "0", "false", "FALSE"]:
+        return False
+    else:
+        raise ValueError(f"Invalid boolean value: {value}")
+
+
+def parse_comma_separated_list(value: str) -> List[str]:
+    """Parse a comma-separated env value into a list of non-empty strings."""
+    if not value or not str(value).strip():
+        return []
+    cleaned = str(value).strip().strip("[]")
+    return [
+        part.strip().strip('"').strip("'")
+        for part in cleaned.split(",")
+        if part.strip()
+    ]
+
+
+def get_or_create_env_var(var_name: str, default_value: str, print_val: bool = False):
+    """
+    Get an environmental variable, and set it to a default value if it doesn't exist
+    """
+    # Get the environment variable if it exists
+    value = os.environ.get(var_name)
+
+    # If it doesn't exist, set the environment variable to the default value
+    if value is None:
+        os.environ[var_name] = default_value
+        value = default_value
+
+    if print_val is True:
+        print(f"The value of {var_name} is {value}")
+
+    return value
+
+
+def ensure_folder_exists(output_folder: str):
+    """Checks if the specified folder exists, creates it if not."""
+
+    if not os.path.exists(output_folder):
+        # Create the folder if it doesn't exist
+        os.makedirs(output_folder, exist_ok=True)
+        print(f"Created the {output_folder} folder.")
+    else:
+        print(f"The {output_folder} folder already exists.")
+
+
+def add_folder_to_path(folder_path: str):
+    """
+    Check if a folder exists on your system. If so, get the absolute path and then add it to the system Path variable if it doesn't already exist. Function is only relevant for locally-created executable files based on this app (when using pyinstaller it creates a _internal folder that contains tesseract and poppler. These need to be added to the system path to enable the app to run)
+    """
+
+    if os.path.exists(folder_path) and os.path.isdir(folder_path):
+        print(folder_path, "folder exists.")
+
+        # Resolve relative path to absolute path
+        absolute_path = os.path.abspath(folder_path)
+
+        current_path = os.environ["PATH"]
+        if absolute_path not in current_path.split(os.pathsep):
+            full_path_extension = absolute_path + os.pathsep + current_path
+            os.environ["PATH"] = full_path_extension
+            # print(f"Updated PATH with: ", full_path_extension)
+        else:
+            print(f"Directory {folder_path} already exists in PATH.")
+    else:
+        print(f"Folder not found at {folder_path} - not added to PATH")
+
+
+###
+# LOAD CONFIG FROM ENV FILE
+###
+CONFIG_FOLDER = get_or_create_env_var("CONFIG_FOLDER", "config/")
+
+ensure_folder_exists(CONFIG_FOLDER)
+
+# If you have an aws_config env file in the config folder, you can load in app variables this way, e.g. 'config/cdk_config.env'
+CDK_CONFIG_PATH = get_or_create_env_var(
+    "CDK_CONFIG_PATH", "config/cdk_config.env"
+)  # e.g. config/cdk_config.env
+
+if CDK_CONFIG_PATH:
+    if os.path.exists(CDK_CONFIG_PATH):
+        print(f"Loading CDK variables from config file {CDK_CONFIG_PATH}")
+        # override=True: stale empty defaults from an earlier cdk_config import in the
+        # same shell (e.g. cdk_install wizard calling cdk_functions) must not win.
+        load_dotenv(CDK_CONFIG_PATH, override=True)
+    else:
+        print("CDK config file not found at location:", CDK_CONFIG_PATH)
+
+###
+# AWS OPTIONS
+###
+AWS_REGION = get_or_create_env_var("AWS_REGION", "")
+AWS_ACCOUNT_ID = get_or_create_env_var("AWS_ACCOUNT_ID", "")
+
+###
+# CDK OPTIONS
+###
+CDK_PREFIX = get_or_create_env_var("CDK_PREFIX", "")
+
+# When True (default): CloudFormation stack termination protection, AWS
+# deletion_protection on ALB/DynamoDB/Cognito, RemovalPolicy.RETAIN, and no S3
+# auto-delete on stack-created resources. Set False for dev sandboxes where
+# cdk destroy should remove resources cleanly.
+ENABLE_RESOURCE_DELETE_PROTECTION = get_or_create_env_var(
+    "ENABLE_RESOURCE_DELETE_PROTECTION", "True"
+)
+
+# AWS Console myApplications (Service Catalog AppRegistry)
+ENABLE_APPREGISTRY = get_or_create_env_var("ENABLE_APPREGISTRY", "True")
+APPREGISTRY_APPLICATION_NAME = get_or_create_env_var(
+    "APPREGISTRY_APPLICATION_NAME", f"{CDK_PREFIX}llm-topic-modeller"
+)
+APPREGISTRY_DESCRIPTION = get_or_create_env_var(
+    "APPREGISTRY_DESCRIPTION",
+    "LLM topic modelling app (ALB, ECS Fargate, Cognito, S3)",
+)
+APPREGISTRY_STACK_NAME = get_or_create_env_var(
+    "APPREGISTRY_STACK_NAME", f"{CDK_PREFIX}AppRegistryStack"
+)
+APPREGISTRY_ATTRIBUTE_GROUP_NAME = get_or_create_env_var(
+    "APPREGISTRY_ATTRIBUTE_GROUP_NAME",
+    f"{APPREGISTRY_APPLICATION_NAME}-metadata",
+)
+APPREGISTRY_REPOSITORY_URL = get_or_create_env_var(
+    "APPREGISTRY_REPOSITORY_URL",
+    "https://github.com/seanpedrick-case/llm_topic_modeller.git",
+)
+
+_precheck_context_file = get_or_create_env_var("CONTEXT_FILE", "precheck.context.json")
+# Never write boto3 pre-check output into CDK's lookup cache file (causes stale
+# vpc-provider / load-balancer entries and wrong-account lookup validation errors).
+if os.path.basename(_precheck_context_file.replace("\\", "/")) == "cdk.context.json":
+    print(
+        "WARNING: CONTEXT_FILE must not be 'cdk.context.json' (that file is CDK's "
+        "lookup cache). Using 'precheck.context.json' instead. Update "
+        "config/cdk_config.env and remove CONTEXT_FILE=cdk.context.json if set."
+    )
+    _precheck_context_file = "precheck.context.json"
+CONTEXT_FILE = _precheck_context_file
+CDK_CONTEXT_FILE = get_or_create_env_var("CDK_CONTEXT_FILE", "cdk.context.json")
+CDK_FOLDER = get_or_create_env_var(
+    "CDK_FOLDER", ""
+)  # FULL_PATH_TO_CDK_FOLDER_HERE (with forward slash)
+
+# App runtime config (uploaded to S3 for legacy Fargate; inlined for ECS Express Mode)
+APP_CONFIG_ENV_BASENAME = "app_config.env"
+_app_config_rel = os.path.join(CONFIG_FOLDER, APP_CONFIG_ENV_BASENAME).replace(
+    "\\", "/"
+)
+APP_CONFIG_ENV_FILE = get_or_create_env_var(
+    "APP_CONFIG_ENV_FILE",
+    (
+        os.path.normpath(os.path.join(CDK_FOLDER, _app_config_rel))
+        if CDK_FOLDER
+        else os.path.normpath(_app_config_rel)
+    ),
+)
+RUN_USEAST_STACK = get_or_create_env_var("RUN_USEAST_STACK", "False")
+
+### VPC and connections
+VPC_NAME = get_or_create_env_var("VPC_NAME", "")
+NEW_VPC_DEFAULT_NAME = get_or_create_env_var("NEW_VPC_DEFAULT_NAME", f"{CDK_PREFIX}vpc")
+NEW_VPC_CIDR = get_or_create_env_var("NEW_VPC_CIDR", "")  # "10.0.0.0/24"
+
+
+# Internet Gateway for legacy VPC public subnets (attach + 0.0.0.0/0 routes via CDK when missing).
+EXISTING_IGW_ID = get_or_create_env_var("EXISTING_IGW_ID", "")
+SINGLE_NAT_GATEWAY_ID = get_or_create_env_var("SINGLE_NAT_GATEWAY_ID", "")
+
+### SUBNETS / ROUTE TABLES / NAT GATEWAY
+PUBLIC_SUBNETS_TO_USE = get_or_create_env_var(
+    "PUBLIC_SUBNETS_TO_USE", ""
+)  # e.g. ['PublicSubnet1', 'PublicSubnet2']
+PUBLIC_SUBNET_CIDR_BLOCKS = get_or_create_env_var(
+    "PUBLIC_SUBNET_CIDR_BLOCKS", ""
+)  # e.g. ["10.0.1.0/24", "10.0.2.0/24"]
+PUBLIC_SUBNET_AVAILABILITY_ZONES = get_or_create_env_var(
+    "PUBLIC_SUBNET_AVAILABILITY_ZONES", ""
+)  # e.g. ["eu-east-1b", "eu-east1b"]
+
+PRIVATE_SUBNETS_TO_USE = get_or_create_env_var(
+    "PRIVATE_SUBNETS_TO_USE", ""
+)  # e.g. ['PrivateSubnet1', 'PrivateSubnet2']
+PRIVATE_SUBNET_CIDR_BLOCKS = get_or_create_env_var(
+    "PRIVATE_SUBNET_CIDR_BLOCKS", ""
+)  # e.g. ["10.0.1.0/24", "10.0.2.0/24"]
+PRIVATE_SUBNET_AVAILABILITY_ZONES = get_or_create_env_var(
+    "PRIVATE_SUBNET_AVAILABILITY_ZONES", ""
+)  # e.g. ["eu-east-1b", "eu-east1b"]
+
+ROUTE_TABLE_BASE_NAME = get_or_create_env_var(
+    "ROUTE_TABLE_BASE_NAME", f"{CDK_PREFIX}PrivateRouteTable"
+)
+NAT_GATEWAY_EIP_NAME = get_or_create_env_var(
+    "NAT_GATEWAY_EIP_NAME", f"{CDK_PREFIX}NatGatewayEip"
+)
+NAT_GATEWAY_NAME = get_or_create_env_var("NAT_GATEWAY_NAME", f"{CDK_PREFIX}NatGateway")
+
+# IAM roles — managed policy *names* (AWS managed) and JSON policy *files* (inline statements)
+AWS_MANAGED_TASK_ROLES_LIST = get_or_create_env_var(
+    "AWS_MANAGED_TASK_ROLES_LIST",
+    '["AmazonCognitoReadOnly", "service-role/AmazonECSTaskExecutionRolePolicy", "AmazonDynamoDBFullAccess", "service-role/AWSAppSyncPushToCloudWatchLogs", "AmazonBedrockLimitedAccess"]',
+)
+ECS_EXECUTION_ROLE_MANAGED_POLICIES = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_MANAGED_POLICIES",
+    '["service-role/AmazonECSTaskExecutionRolePolicy"]',
+)
+# JSON IAM policy document paths (relative to CDK_FOLDER or absolute). Task role = app runtime.
+POLICY_FILE_LOCATIONS = get_or_create_env_var(
+    "POLICY_FILE_LOCATIONS",
+    "[]",
+)
+# Optional extra JSON policies for the ECS task *execution* role (image pull / logs / secrets).
+ECS_EXECUTION_ROLE_POLICY_FILES = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_POLICY_FILES",
+    "",
+)
+# Customer-managed policy ARNs (full ARN per entry), attached in addition to the lists above.
+POLICY_FILE_ARNS = get_or_create_env_var("POLICY_FILE_ARNS", "")
+ECS_EXECUTION_ROLE_POLICY_ARNS = get_or_create_env_var(
+    "ECS_EXECUTION_ROLE_POLICY_ARNS", ""
+)
+
+AWS_MANAGED_TASK_ROLES_LIST = parse_comma_separated_list(AWS_MANAGED_TASK_ROLES_LIST)
+ECS_EXECUTION_ROLE_MANAGED_POLICIES = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_MANAGED_POLICIES
+)
+POLICY_FILE_LOCATIONS = parse_comma_separated_list(POLICY_FILE_LOCATIONS)
+ECS_EXECUTION_ROLE_POLICY_FILES = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_POLICY_FILES
+)
+POLICY_FILE_ARNS = parse_comma_separated_list(POLICY_FILE_ARNS)
+ECS_EXECUTION_ROLE_POLICY_ARNS = parse_comma_separated_list(
+    ECS_EXECUTION_ROLE_POLICY_ARNS
+)
+
+# GITHUB REPO
+GITHUB_REPO_USERNAME = get_or_create_env_var("GITHUB_REPO_USERNAME", "seanpedrick-case")
+GITHUB_REPO_NAME = get_or_create_env_var("GITHUB_REPO_NAME", "llm_topic_modeller")
+GITHUB_REPO_BRANCH = get_or_create_env_var("GITHUB_REPO_BRANCH", "main")
+
+### CODEBUILD
+CODEBUILD_ROLE_NAME = get_or_create_env_var(
+    "CODEBUILD_ROLE_NAME", f"{CDK_PREFIX}CodeBuildRole"
+)
+CODEBUILD_PROJECT_NAME = get_or_create_env_var(
+    "CODEBUILD_PROJECT_NAME", f"{CDK_PREFIX}CodeBuildProject"
+)
+
+### ECR
+ECR_REPO_NAME = get_or_create_env_var(
+    "ECR_REPO_NAME", "llm-topic-modeller"
+)  # Beware - cannot have underscores and must be lower case
+ECR_CDK_REPO_NAME = get_or_create_env_var(
+    "ECR_CDK_REPO_NAME", f"{CDK_PREFIX}{ECR_REPO_NAME}".lower()
+)
+
+
+### S3
+def _resolve_s3_bucket_name(env_key: str, suffix: str) -> str:
+    """
+    Bucket name default is ``{CDK_PREFIX}{suffix}`` (lowercase).
+
+    If an earlier import cached a bare ``suffix`` in ``os.environ`` before
+    ``CDK_PREFIX`` was loaded from dotenv, upgrade it to the prefixed name.
+    """
+    prefix = (os.environ.get("CDK_PREFIX") or "").lower()
+    default = f"{prefix}{suffix}"
+    value = get_or_create_env_var(env_key, default)
+    if prefix and value == suffix:
+        os.environ[env_key] = default
+        return default
+    return value
+
+
+S3_LOG_CONFIG_BUCKET_NAME = _resolve_s3_bucket_name(
+    "S3_LOG_CONFIG_BUCKET_NAME", "s3-logs"
+)  # S3 bucket names need to be lower case
+S3_OUTPUT_BUCKET_NAME = _resolve_s3_bucket_name("S3_OUTPUT_BUCKET_NAME", "s3-output")
+
+### VPC endpoints for ECS tasks in private subnets (ECR image pull, logs, secrets)
+ENABLE_ECS_VPC_INTERFACE_ENDPOINTS = get_or_create_env_var(
+    "ENABLE_ECS_VPC_INTERFACE_ENDPOINTS", "True"
+)
+
+### KMS KEYS FOR S3 AND SECRETS MANAGER
+USE_CUSTOM_KMS_KEY = get_or_create_env_var("USE_CUSTOM_KMS_KEY", "1")
+CUSTOM_KMS_KEY_NAME = get_or_create_env_var(
+    "CUSTOM_KMS_KEY_NAME", f"alias/{CDK_PREFIX}kms-key".lower()
+)
+
+### ECS
+FARGATE_TASK_DEFINITION_NAME = get_or_create_env_var(
+    "FARGATE_TASK_DEFINITION_NAME", f"{CDK_PREFIX}FargateTaskDefinition"
+)
+TASK_DEFINITION_FILE_LOCATION = get_or_create_env_var(
+    "TASK_DEFINITION_FILE_LOCATION", CDK_FOLDER + CONFIG_FOLDER + "task_definition.json"
+)
+
+CLUSTER_NAME = get_or_create_env_var("CLUSTER_NAME", f"{CDK_PREFIX}Cluster")
+ECS_SERVICE_NAME = get_or_create_env_var("ECS_SERVICE_NAME", f"{CDK_PREFIX}ECSService")
+# Second Fargate service when ENABLE_PI_AGENT_ECS_SERVICE=True (legacy path only).
+ECS_PI_SERVICE_NAME = get_or_create_env_var(
+    "ECS_PI_SERVICE_NAME", f"{CDK_PREFIX}PiAgentService"
+)
+ECS_TASK_ROLE_NAME = get_or_create_env_var(
+    "ECS_TASK_ROLE_NAME", f"{CDK_PREFIX}TaskRole"
+)
+ECS_TASK_EXECUTION_ROLE_NAME = get_or_create_env_var(
+    "ECS_TASK_EXECUTION_ROLE_NAME", f"{CDK_PREFIX}ExecutionRole"
+)
+ECS_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupECS"
+)
+ECS_LOG_GROUP_NAME = get_or_create_env_var(
+    "ECS_LOG_GROUP_NAME", f"/ecs/{ECS_SERVICE_NAME}-logs".lower()
+)
+
+ECS_TASK_CPU_SIZE = get_or_create_env_var("ECS_TASK_CPU_SIZE", "1024")
+ECS_TASK_MEMORY_SIZE = get_or_create_env_var("ECS_TASK_MEMORY_SIZE", "4096")
+ECS_USE_FARGATE_SPOT = get_or_create_env_var("USE_FARGATE_SPOT", "False")
+ECS_READ_ONLY_FILE_SYSTEM = get_or_create_env_var("ECS_READ_ONLY_FILE_SYSTEM", "True")
+# ECS service AZ rebalancing (AWS defaults new services to ENABLED if omitted).
+ECS_AVAILABILITY_ZONE_REBALANCING = get_or_create_env_var(
+    "ECS_AVAILABILITY_ZONE_REBALANCING", "DISABLED"
+)
+if ECS_AVAILABILITY_ZONE_REBALANCING not in ("ENABLED", "DISABLED"):
+    raise ValueError(
+        "ECS_AVAILABILITY_ZONE_REBALANCING must be ENABLED or DISABLED "
+        f"(got {ECS_AVAILABILITY_ZONE_REBALANCING!r})."
+    )
+
+### Cognito
+COGNITO_USER_POOL_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_NAME", f"{CDK_PREFIX}UserPool"
+)
+COGNITO_USER_POOL_CLIENT_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_CLIENT_NAME", f"{CDK_PREFIX}UserPoolClient"
+)
+COGNITO_USER_POOL_CLIENT_SECRET_NAME = get_or_create_env_var(
+    "COGNITO_USER_POOL_CLIENT_SECRET_NAME", f"{CDK_PREFIX}ParamCognitoSecret"
+)
+COGNITO_USER_POOL_DOMAIN_PREFIX = get_or_create_env_var(
+    "COGNITO_USER_POOL_DOMAIN_PREFIX", "llm-topic-app-domain"
+)  # Should change this to something unique or you'll probably hit an error
+
+COGNITO_REFRESH_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_REFRESH_TOKEN_VALIDITY", "480")
+)  # Minutes
+COGNITO_ID_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_ID_TOKEN_VALIDITY", "60")
+)  # Minutes
+COGNITO_ACCESS_TOKEN_VALIDITY = int(
+    get_or_create_env_var("COGNITO_ACCESS_TOKEN_VALIDITY", "60")
+)  # Minutes
+
+# Application load balancer
+ALB_NAME = get_or_create_env_var(
+    "ALB_NAME", f"{CDK_PREFIX}Alb"[-32:]
+)  # Application load balancer name can be max 32 characters, so taking the last 32 characters of the suggested name
+ALB_NAME_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ALB_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupALB"
+)
+ALB_TARGET_GROUP_NAME = get_or_create_env_var(
+    "ALB_TARGET_GROUP_NAME", f"{CDK_PREFIX}-tg"[-32:]
+)  # Max 32 characters
+EXISTING_LOAD_BALANCER_ARN = get_or_create_env_var("EXISTING_LOAD_BALANCER_ARN", "")
+EXISTING_LOAD_BALANCER_DNS = get_or_create_env_var(
+    "EXISTING_LOAD_BALANCER_DNS", "placeholder_load_balancer_dns.net"
+)
+
+## CLOUDFRONT
+USE_CLOUDFRONT = get_or_create_env_var("USE_CLOUDFRONT", "True")
+CLOUDFRONT_PREFIX_LIST_ID = get_or_create_env_var(
+    "CLOUDFRONT_PREFIX_LIST_ID", "pl-93a247fa"
+)
+CLOUDFRONT_GEO_RESTRICTION = get_or_create_env_var(
+    "CLOUDFRONT_GEO_RESTRICTION", ""
+)  # A country that Cloudfront restricts access to. See here: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/georestrictions.html
+CLOUDFRONT_DISTRIBUTION_NAME = get_or_create_env_var(
+    "CLOUDFRONT_DISTRIBUTION_NAME", f"{CDK_PREFIX}CfDist"
+)
+CLOUDFRONT_DOMAIN = get_or_create_env_var(
+    "CLOUDFRONT_DOMAIN", "cloudfront_placeholder.net"
+)
+# Attach CSP / security response headers to the CDK CloudFront distribution (us-east-1 stack).
+CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS = get_or_create_env_var(
+    "CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS", "True"
+)
+# Optional override for manifest-src (Cognito hosted UI). Default: https://{COGNITO_USER_POOL_DOMAIN_PREFIX}.auth.{AWS_REGION}.amazoncognito.com
+COGNITO_USER_POOL_LOGIN_URL = get_or_create_env_var("COGNITO_USER_POOL_LOGIN_URL", "")
+
+
+# Certificate for Application load balancer (optional, for HTTPS and logins through the ALB)
+ACM_SSL_CERTIFICATE_ARN = get_or_create_env_var("ACM_SSL_CERTIFICATE_ARN", "")
+SSL_CERTIFICATE_DOMAIN = get_or_create_env_var(
+    "SSL_CERTIFICATE_DOMAIN", ""
+)  # e.g. example.com or www.example.com
+
+# ECS Express Mode (opt-in HTTPS ingress without supplying ACM_SSL_CERTIFICATE_ARN).
+# Pilot/dev: Express PrimaryContainer does not support S3 environmentFiles or Fargate mount points.
+USE_ECS_EXPRESS_MODE = get_or_create_env_var("USE_ECS_EXPRESS_MODE", "False")
+ECS_EXPRESS_SERVICE_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_SERVICE_NAME", ECS_SERVICE_NAME
+)
+ECS_EXPRESS_HEALTH_CHECK_PATH = get_or_create_env_var(
+    "ECS_EXPRESS_HEALTH_CHECK_PATH", "/"
+)
+ECS_EXPRESS_INFRASTRUCTURE_ROLE_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_INFRASTRUCTURE_ROLE_NAME", f"{CDK_PREFIX}ExpressInfraRole"
+)
+# After first deploy, set to ExpressServiceEndpoint output (https://...) if not using CloudFront.
+# The installer updates Cognito callback URLs via API (no second CDK deploy).
+ECS_EXPRESS_COGNITO_REDIRECT_BASE = get_or_create_env_var(
+    "ECS_EXPRESS_COGNITO_REDIRECT_BASE", ""
+)
+# Express networkConfiguration.subnets drives both tasks and the managed ALB.
+# Public subnets (IGW route) → internet-facing ALB; private → internal ALB only.
+ECS_EXPRESS_USE_PUBLIC_SUBNETS = get_or_create_env_var(
+    "ECS_EXPRESS_USE_PUBLIC_SUBNETS", "True"
+)
+
+if USE_ECS_EXPRESS_MODE == "True" and ACM_SSL_CERTIFICATE_ARN:
+    raise ValueError(
+        "USE_ECS_EXPRESS_MODE=True cannot be used with ACM_SSL_CERTIFICATE_ARN set. "
+        "Clear ACM_SSL_CERTIFICATE_ARN or set USE_ECS_EXPRESS_MODE=False."
+    )
+
+# ECS Service Connect (legacy Fargate only): VPC service-to-service HTTP to Gradio/FastAPI.
+ENABLE_ECS_SERVICE_CONNECT = get_or_create_env_var(
+    "ENABLE_ECS_SERVICE_CONNECT", "False"
+)
+ECS_SERVICE_CONNECT_NAMESPACE = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_NAMESPACE",
+    (f"{CDK_PREFIX}local".lower().replace("_", "-").strip("-") or "llm-topic-local"),
+)
+ECS_SERVICE_CONNECT_DISCOVERY_NAME = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_DISCOVERY_NAME", "llm-topic"
+)
+# Optional friendly DNS label; defaults to discovery name when empty.
+ECS_SERVICE_CONNECT_DNS_NAME = get_or_create_env_var("ECS_SERVICE_CONNECT_DNS_NAME", "")
+# Client task security groups (at least one of IDs, names, or CDK prefixes required when SC on).
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS", ""
+)
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS
+)
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES", ""
+)
+ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES", ""
+)
+
+
+def normalize_https_redirect_url(url: str) -> str:
+    """Ensure Cognito/OAuth redirect bases use an explicit https:// scheme."""
+    raw = (url or "").strip()
+    if not raw:
+        return ""
+    if raw.startswith("https://"):
+        return raw.rstrip("/")
+    if raw.startswith("http://"):
+        return ("https://" + raw[len("http://") :]).rstrip("/")
+    return ("https://" + raw.lstrip("/")).rstrip("/")
+
+
+# This should be the CloudFront domain, the domain linked to your ACM certificate, or the DNS of your application load balancer in console afterwards
+if USE_CLOUDFRONT == "True":
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + CLOUDFRONT_DOMAIN
+    )
+elif SSL_CERTIFICATE_DOMAIN:
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + SSL_CERTIFICATE_DOMAIN
+    )
+elif USE_ECS_EXPRESS_MODE == "True":
+    _express_redirect_default = ECS_EXPRESS_COGNITO_REDIRECT_BASE or (
+        "https://" + EXISTING_LOAD_BALANCER_DNS
+    )
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", _express_redirect_default
+    )
+else:
+    COGNITO_REDIRECTION_URL = get_or_create_env_var(
+        "COGNITO_REDIRECTION_URL", "https://" + EXISTING_LOAD_BALANCER_DNS
+    )
+
+COGNITO_REDIRECTION_URL = normalize_https_redirect_url(COGNITO_REDIRECTION_URL)
+if ECS_EXPRESS_COGNITO_REDIRECT_BASE:
+    ECS_EXPRESS_COGNITO_REDIRECT_BASE = normalize_https_redirect_url(
+        ECS_EXPRESS_COGNITO_REDIRECT_BASE
+    )
+
+# Custom headers e.g. if routing traffic through Cloudfront
+CUSTOM_HEADER = get_or_create_env_var(
+    "CUSTOM_HEADER", ""
+)  # Retrieving or setting CUSTOM_HEADER
+CUSTOM_HEADER_VALUE = get_or_create_env_var(
+    "CUSTOM_HEADER_VALUE", ""
+)  # Retrieving or setting CUSTOM_HEADER_VALUE
+
+# Firewall on top of load balancer
+LOAD_BALANCER_WEB_ACL_NAME = get_or_create_env_var(
+    "LOAD_BALANCER_WEB_ACL_NAME", f"{CDK_PREFIX}alb-web-acl"
+)
+
+# Firewall on top of CloudFront
+WEB_ACL_NAME = get_or_create_env_var("WEB_ACL_NAME", f"{CDK_PREFIX}cloudfront-web-acl")
+
+###
+# File I/O options
+###
+
+OUTPUT_FOLDER = get_or_create_env_var("GRADIO_OUTPUT_FOLDER", "output/")  # 'output/'
+INPUT_FOLDER = get_or_create_env_var("GRADIO_INPUT_FOLDER", "input/")  # 'input/'
+
+# Allow for files to be saved in a temporary folder for increased security in some instances
+if OUTPUT_FOLDER == "TEMP" or INPUT_FOLDER == "TEMP":
+    # Create a temporary directory
+    with tempfile.TemporaryDirectory() as temp_dir:
+        print(f"Temporary directory created at: {temp_dir}")
+
+        if OUTPUT_FOLDER == "TEMP":
+            OUTPUT_FOLDER = temp_dir + "/"
+        if INPUT_FOLDER == "TEMP":
+            INPUT_FOLDER = temp_dir + "/"
+
+###
+# LOGGING OPTIONS
+###
+
+SAVE_LOGS_TO_CSV = get_or_create_env_var("SAVE_LOGS_TO_CSV", "True")
+
+### DYNAMODB logs. Whether to save to DynamoDB, and the headers of the table
+SAVE_LOGS_TO_DYNAMODB = get_or_create_env_var("SAVE_LOGS_TO_DYNAMODB", "True")
+ACCESS_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "ACCESS_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-access-logs".lower()
+)
+FEEDBACK_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "FEEDBACK_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-feedback-logs".lower()
+)
+USAGE_LOG_DYNAMODB_TABLE_NAME = get_or_create_env_var(
+    "USAGE_LOG_DYNAMODB_TABLE_NAME", f"{CDK_PREFIX}dynamodb-usage-logs".lower()
+)
+
+# Optional scheduled export of usage-log DynamoDB table to CSV in S3 (EventBridge -> Lambda).
+ENABLE_DYNAMODB_USAGE_LOG_EXPORT = get_or_create_env_var(
+    "ENABLE_DYNAMODB_USAGE_LOG_EXPORT", "False"
+)
+DYNAMODB_USAGE_LOG_EXPORT_LAMBDA_NAME = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_LAMBDA_NAME",
+    f"{CDK_PREFIX}DynamoUsageLogExport".lower().replace("_", "-"),
+)
+DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE", "cron(0 6 ? * * *)"
+)
+DYNAMODB_USAGE_LOG_EXPORT_S3_KEY = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_S3_KEY",
+    "reports/dynamodb-usage/dynamodb_logs_export.csv",
+)
+DYNAMODB_USAGE_LOG_EXPORT_DATE_ATTRIBUTE = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_DATE_ATTRIBUTE", "timestamp"
+)
+DYNAMODB_USAGE_LOG_EXPORT_OUTPUT_FILENAME = get_or_create_env_var(
+    "DYNAMODB_USAGE_LOG_EXPORT_OUTPUT_FILENAME", "dynamodb_logs_export.csv"
+)
+
+if ENABLE_DYNAMODB_USAGE_LOG_EXPORT == "True":
+    if SAVE_LOGS_TO_DYNAMODB != "True":
+        raise ValueError(
+            "ENABLE_DYNAMODB_USAGE_LOG_EXPORT=True requires SAVE_LOGS_TO_DYNAMODB=True."
+        )
+    schedule = (DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE or "").strip()
+    if not schedule.startswith("cron(") and not schedule.startswith("rate("):
+        raise ValueError(
+            "DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE must be an EventBridge cron(...) or "
+            f"rate(...) expression; got {schedule!r}."
+        )
+    if not (DYNAMODB_USAGE_LOG_EXPORT_S3_KEY or "").strip():
+        raise ValueError(
+            "DYNAMODB_USAGE_LOG_EXPORT_S3_KEY is required when "
+            "ENABLE_DYNAMODB_USAGE_LOG_EXPORT=True."
+        )
+
+###
+# APP OPTIONS
+###
+
+# Get some environment variables and Launch the Gradio app
+COGNITO_AUTH = get_or_create_env_var("COGNITO_AUTH", "False")
+
+GRADIO_SERVER_PORT = int(get_or_create_env_var("GRADIO_SERVER_PORT", "7860"))
+
+# Must match the named port mapping on the Fargate container (see cdk_stack.py).
+ECS_SERVICE_CONNECT_PORT_MAPPING_NAME = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_PORT_MAPPING_NAME", f"port-{GRADIO_SERVER_PORT}"
+)
+
+# Suffix used with ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES (matches this stack's ECS SG name).
+if ECS_SECURITY_GROUP_NAME.startswith(CDK_PREFIX):
+    _default_sc_client_sg_suffix = ECS_SECURITY_GROUP_NAME[len(CDK_PREFIX) :]
+else:
+    _default_sc_client_sg_suffix = "SecurityGroupECS"
+ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX = get_or_create_env_var(
+    "ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX", _default_sc_client_sg_suffix
+)
+
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES
+)
+ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES_LIST = parse_comma_separated_list(
+    ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES
+)
+
+
+def build_service_connect_client_security_group_names() -> List[str]:
+    """Explicit SG names plus {prefix}{suffix} for each client CDK_PREFIX."""
+    names: List[str] = list(ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_LIST)
+    for prefix in ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES_LIST:
+        names.append(f"{prefix}{ECS_SERVICE_CONNECT_CLIENT_SG_NAME_SUFFIX}")
+    deduped: List[str] = []
+    seen = set()
+    for name in names:
+        if name and name not in seen:
+            seen.add(name)
+            deduped.append(name)
+    return deduped
+
+
+ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP = (
+    build_service_connect_client_security_group_names()
+)
+
+if ENABLE_ECS_SERVICE_CONNECT == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_ECS_SERVICE_CONNECT=True is only supported on the legacy Fargate "
+        "service path. Set USE_ECS_EXPRESS_MODE=False or disable Service Connect."
+    )
+
+# Headless deployment: S3 job .env -> Lambda -> one-shot ECS Fargate (RUN_DIRECT_MODE).
+# No ALB, CloudFront, or always-on ECS service.
+ENABLE_HEADLESS_DEPLOYMENT = get_or_create_env_var(
+    "ENABLE_HEADLESS_DEPLOYMENT", "False"
+)
+
+# S3-uploaded job .env files trigger one-shot ECS Fargate tasks (direct mode / cli_redact).
+ENABLE_S3_BATCH_ECS_TRIGGER = get_or_create_env_var(
+    "ENABLE_S3_BATCH_ECS_TRIGGER", "False"
+)
+S3_BATCH_ENV_PREFIX = get_or_create_env_var("S3_BATCH_ENV_PREFIX", "input/config/")
+S3_BATCH_ENV_SUFFIX = get_or_create_env_var("S3_BATCH_ENV_SUFFIX", ".env")
+S3_BATCH_INPUT_PREFIX = get_or_create_env_var("S3_BATCH_INPUT_PREFIX", "input/")
+S3_BATCH_CONFIG_PREFIX = get_or_create_env_var("S3_BATCH_CONFIG_PREFIX", "")
+S3_BATCH_GENERAL_ENV_PREFIX = get_or_create_env_var(
+    "S3_BATCH_GENERAL_ENV_PREFIX", "general-config/"
+)
+S3_BATCH_DEFAULT_PARAMS_KEY = get_or_create_env_var(
+    "S3_BATCH_DEFAULT_PARAMS_KEY", "general-config/app_defaults.env"
+)
+S3_BATCH_LAMBDA_FUNCTION_NAME = get_or_create_env_var(
+    "S3_BATCH_LAMBDA_FUNCTION_NAME", f"{CDK_PREFIX}S3BatchEcsTrigger"
+)
+
+if ENABLE_S3_BATCH_ECS_TRIGGER == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_S3_BATCH_ECS_TRIGGER=True requires the legacy Fargate task definition "
+        "for ecs.run_task. Set USE_ECS_EXPRESS_MODE=False or disable the batch trigger."
+    )
+
+if ENABLE_HEADLESS_DEPLOYMENT == "True":
+    if ENABLE_S3_BATCH_ECS_TRIGGER != "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True requires ENABLE_S3_BATCH_ECS_TRIGGER=True."
+        )
+    if USE_ECS_EXPRESS_MODE == "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True requires USE_ECS_EXPRESS_MODE=False."
+        )
+    if USE_CLOUDFRONT == "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_DEPLOYMENT=True is incompatible with USE_CLOUDFRONT=True."
+        )
+
+# Optional headless follow-on: S3 output PutRequests alarm -> SNS email + IAM user for downloads.
+ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS = get_or_create_env_var(
+    "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS", "False"
+)
+HEADLESS_OUTPUT_NOTIFY_EMAIL = get_or_create_env_var("HEADLESS_OUTPUT_NOTIFY_EMAIL", "")
+HEADLESS_OUTPUT_IAM_USER_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_IAM_USER_NAME", f"{CDK_PREFIX}s3-output-reader"
+)
+HEADLESS_OUTPUT_S3_METRIC_FILTER_ID = get_or_create_env_var(
+    "HEADLESS_OUTPUT_S3_METRIC_FILTER_ID",
+    f"{CDK_PREFIX}s3-output-put".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_SNS_TOPIC_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_SNS_TOPIC_NAME",
+    f"{CDK_PREFIX}llm-topic-s3-save-sns".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_ALARM_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_ALARM_NAME",
+    f"{CDK_PREFIX}cloudwatch-alarm-new-output-s3".lower().replace("_", "-"),
+)
+HEADLESS_OUTPUT_S3_PREFIX = get_or_create_env_var(
+    "HEADLESS_OUTPUT_S3_PREFIX", "output/"
+)
+HEADLESS_OUTPUT_IAM_SECRET_NAME = get_or_create_env_var(
+    "HEADLESS_OUTPUT_IAM_SECRET_NAME",
+    f"{CDK_PREFIX}headless-output-reader-key",
+)
+
+if ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS == "True":
+    if ENABLE_HEADLESS_DEPLOYMENT != "True":
+        raise ValueError(
+            "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS=True requires "
+            "ENABLE_HEADLESS_DEPLOYMENT=True."
+        )
+    if not (HEADLESS_OUTPUT_NOTIFY_EMAIL or "").strip():
+        raise ValueError(
+            "HEADLESS_OUTPUT_NOTIFY_EMAIL is required when "
+            "ENABLE_HEADLESS_OUTPUT_NOTIFICATIONS=True."
+        )
+
+# Pi agent Gradio UI (second Fargate service; shared legacy ALB + Service Connect to main app).
+ENABLE_PI_AGENT_ECS_SERVICE = get_or_create_env_var(
+    "ENABLE_PI_AGENT_ECS_SERVICE", "False"
+)
+ECR_PI_REPO_NAME = get_or_create_env_var(
+    "ECR_PI_REPO_NAME", f"{CDK_PREFIX}pi-agent".lower()
+)
+CODEBUILD_PI_PROJECT_NAME = get_or_create_env_var(
+    "CODEBUILD_PI_PROJECT_NAME", f"{CDK_PREFIX}CodeBuildPiAgent"
+)
+ECS_PI_TASK_DEFINITION_NAME = get_or_create_env_var(
+    "ECS_PI_TASK_DEFINITION_NAME", f"{CDK_PREFIX}PiAgentTaskDefinition"
+)
+ECS_PI_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupPiAgent"
+)
+ECS_PI_LOG_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_LOG_GROUP_NAME", f"/ecs/{ECS_PI_SERVICE_NAME}-logs".lower()
+)
+ECS_PI_TASK_CPU_SIZE = get_or_create_env_var("ECS_PI_TASK_CPU_SIZE", "1024")
+ECS_PI_TASK_MEMORY_SIZE = get_or_create_env_var("ECS_PI_TASK_MEMORY_SIZE", "2048")
+PI_GRADIO_PORT = get_or_create_env_var("PI_GRADIO_PORT", "7862")
+# Pi ALB routing: path (default /pi on shared host e.g. CloudFront), host, or both.
+PI_ALB_ROUTING = get_or_create_env_var("PI_ALB_ROUTING", "path").strip().lower()
+PI_ALB_PATH_PREFIX = get_or_create_env_var("PI_ALB_PATH_PREFIX", "/pi")
+PI_ALB_HOST_HEADER = get_or_create_env_var("PI_ALB_HOST_HEADER", "")
+PI_ALB_TARGET_GROUP_NAME = get_or_create_env_var(
+    "PI_ALB_TARGET_GROUP_NAME", f"{CDK_PREFIX}PiAgentTG"[-32:]
+)
+PI_ALB_LISTENER_RULE_PRIORITY = int(
+    get_or_create_env_var("PI_ALB_LISTENER_RULE_PRIORITY", "3")
+)
+PI_AGENT_ENV_S3_KEY = get_or_create_env_var("PI_AGENT_ENV_S3_KEY", "pi_agent.env")
+
+
+def _normalize_pi_alb_path_prefix(raw: str) -> str:
+    segment = (raw or "pi").strip().strip("/")
+    return f"/{segment}" if segment else "/pi"
+
+
+PI_ALB_PATH_PREFIX_NORMALIZED = _normalize_pi_alb_path_prefix(PI_ALB_PATH_PREFIX)
+_PI_ALB_ROUTING_MODES = frozenset({"path", "host", "both"})
+
+
+def _validate_pi_alb_routing_for_enabled_pi() -> None:
+    if PI_ALB_ROUTING not in _PI_ALB_ROUTING_MODES:
+        raise ValueError(
+            f"PI_ALB_ROUTING must be one of {sorted(_PI_ALB_ROUTING_MODES)}; got '{PI_ALB_ROUTING}'."
+        )
+    if PI_ALB_ROUTING in ("host", "both") and not PI_ALB_HOST_HEADER.strip():
+        raise ValueError(
+            "PI_ALB_HOST_HEADER is required when PI_ALB_ROUTING is 'host' or 'both' "
+            "(dedicated hostname on the shared ALB)."
+        )
+    if PI_ALB_ROUTING in ("path", "both") and not PI_ALB_PATH_PREFIX_NORMALIZED:
+        raise ValueError("PI_ALB_PATH_PREFIX must resolve to a non-empty path segment.")
+
+
+# Pi on ECS Express Mode (second Express service on shared ALB; SC via ecs:UpdateService).
+ENABLE_PI_AGENT_EXPRESS_SERVICE = get_or_create_env_var(
+    "ENABLE_PI_AGENT_EXPRESS_SERVICE", "False"
+)
+ECS_PI_EXPRESS_SERVICE_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SERVICE_NAME", f"{CDK_PREFIX}PiExpressService"
+)
+ECS_PI_EXPRESS_HEALTH_CHECK_PATH = get_or_create_env_var(
+    "ECS_PI_EXPRESS_HEALTH_CHECK_PATH", "/health"
+)
+ECS_PI_EXPRESS_SECURITY_GROUP_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SECURITY_GROUP_NAME", f"{CDK_PREFIX}SecurityGroupPiExpress"
+)
+# Service Connect port names for Express services (applied in post_cdk_build_quickstart.py).
+ECS_EXPRESS_SC_PORT_NAME = get_or_create_env_var(
+    "ECS_EXPRESS_SC_PORT_NAME", ECS_SERVICE_CONNECT_PORT_MAPPING_NAME
+)
+ECS_PI_EXPRESS_SC_PORT_NAME = get_or_create_env_var(
+    "ECS_PI_EXPRESS_SC_PORT_NAME", f"port-{PI_GRADIO_PORT}"
+)
+
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+    raise ValueError(
+        "Enable at most one Pi deployment mode: ENABLE_PI_AGENT_ECS_SERVICE (legacy Fargate) "
+        "or ENABLE_PI_AGENT_EXPRESS_SERVICE (Express), not both."
+    )
+if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True" and USE_ECS_EXPRESS_MODE != "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_EXPRESS_SERVICE=True requires USE_ECS_EXPRESS_MODE=True "
+        "(no ACM_SSL_CERTIFICATE_ARN)."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and USE_ECS_EXPRESS_MODE == "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_ECS_SERVICE=True requires legacy Fargate (USE_ECS_EXPRESS_MODE=False). "
+        "For Pi on Express, use ENABLE_PI_AGENT_EXPRESS_SERVICE=True instead."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True" and ENABLE_ECS_SERVICE_CONNECT != "True":
+    raise ValueError(
+        "ENABLE_PI_AGENT_ECS_SERVICE=True requires ENABLE_ECS_SERVICE_CONNECT=True "
+        "so the Pi task can reach the main app at http://<discovery>:7860."
+    )
+if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+    _validate_pi_alb_routing_for_enabled_pi()
+
+###
+# WHOLE DOCUMENT API OPTIONS
+###
+
+DAYS_TO_DISPLAY_WHOLE_DOCUMENT_JOBS = get_or_create_env_var(
+    "DAYS_TO_DISPLAY_WHOLE_DOCUMENT_JOBS", "7"
+)  # How many days into the past should whole document Textract jobs be displayed? After that, the data is not deleted from the Textract jobs csv, but it is just filtered out. Included to align with S3 buckets where the file outputs will be automatically deleted after X days.

cdk/cdk_post_deploy.py

@@ -0,0 +1,1408 @@
+"""
+Post-deploy helpers (boto3 only).
+
+Use this module from post_cdk_build_quickstart.py so you do not need Node.js or
+aws-cdk-lib installed to start CodeBuild / ECS after deployment.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import boto3
+from cdk_config import (
+    AWS_REGION,
+    CLOUDFRONT_DOMAIN,
+)
+
+_TASK_DEF_REGISTER_KEYS = (
+    "family",
+    "taskRoleArn",
+    "executionRoleArn",
+    "networkMode",
+    "containerDefinitions",
+    "volumes",
+    "placementConstraints",
+    "requiresCompatibilities",
+    "cpu",
+    "memory",
+    "pidMode",
+    "ipcMode",
+    "proxyConfiguration",
+    "inferenceAccelerators",
+    "ephemeralStorage",
+    "runtimePlatform",
+)
+
+_CONTAINER_REGISTER_OMIT_KEYS = frozenset(
+    {
+        "containerArn",
+        "taskDefinitionArn",
+        "status",
+        "lastStatus",
+        "managedAgents",
+        "networkInterfaces",
+        "healthStatus",
+        "cpu",
+        "memory",
+        "gpu",
+    }
+)
+
+
+def start_codebuild_build(project_name: str, aws_region: str = AWS_REGION) -> None:
+    """Start an existing CodeBuild project build."""
+    client = boto3.client("codebuild", region_name=aws_region)
+
+    try:
+        print(f"Attempting to start build for project: {project_name}")
+        response = client.start_build(projectName=project_name)
+        build_id = response["build"]["id"]
+        print(f"Successfully started build with ID: {build_id}")
+        print(f"Build ARN: {response['build']['arn']}")
+        print(
+            f"https://{aws_region}.console.aws.amazon.com/codesuite/codebuild/projects/"
+            f"{project_name}/build/{build_id.split(':')[-1]}/detail"
+        )
+    except client.exceptions.ResourceNotFoundException:
+        print(f"Error: Project '{project_name}' not found in region '{aws_region}'.")
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+
+
+def upload_file_to_s3(
+    local_file_paths: Union[str, List[str]],
+    s3_key: str,
+    s3_bucket: str,
+    run_aws_functions: str = "1",
+    aws_region: str = AWS_REGION,
+) -> str:
+    """Upload local file(s) to S3."""
+    final_out_message: List[str] = []
+    final_out_message_str = ""
+
+    if run_aws_functions != "1":
+        return "App not set to run AWS functions"
+
+    try:
+        if not (s3_bucket and local_file_paths):
+            return "At least one essential variable is empty, could not upload to S3"
+
+        s3_client = boto3.client("s3", region_name=aws_region)
+        paths = (
+            [local_file_paths]
+            if isinstance(local_file_paths, str)
+            else list(local_file_paths)
+        )
+
+        for file_path in paths:
+            try:
+                file_name = os.path.basename(file_path)
+                s3_key_full = s3_key + file_name
+                print("S3 key: ", s3_key_full)
+                s3_client.upload_file(file_path, s3_bucket, s3_key_full)
+                out_message = f"File {file_name} uploaded successfully!"
+                print(out_message)
+            except Exception as e:
+                out_message = f"Error uploading file(s): {e}"
+                print(out_message)
+            final_out_message.append(out_message)
+
+        final_out_message_str = "\n".join(final_out_message)
+    except Exception as e:
+        final_out_message_str = "Could not upload files to S3 due to: " + str(e)
+        print(final_out_message_str)
+
+    return final_out_message_str
+
+
+def start_ecs_task(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> dict:
+    """Scale a legacy Fargate ECS service to one running task."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+
+    try:
+        ecs_client.update_service(
+            cluster=cluster_name, service=service_name, desiredCount=1
+        )
+        return {
+            "statusCode": 200,
+            "body": (
+                f"Service {service_name} in cluster {cluster_name} "
+                "has been updated to 1 task."
+            ),
+        }
+    except Exception as e:
+        return {"statusCode": 500, "body": f"Error updating service: {str(e)}"}
+
+
+EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET = {
+    "minTaskCount": 1,
+    "maxTaskCount": 1,
+    "autoScalingMetric": "AVERAGE_CPU",
+    "autoScalingTargetValue": 60,
+}
+
+
+def resolve_express_gateway_service_arn(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """Look up an Express gateway service ARN by cluster and service name."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    paginator = ecs_client.get_paginator("list_services")
+    for page in paginator.paginate(cluster=cluster_name):
+        for arn in page.get("serviceArns", []):
+            if arn.rstrip("/").split("/")[-1] == service_name:
+                return arn
+    raise ValueError(
+        f"Express gateway service '{service_name}' not found in cluster "
+        f"'{cluster_name}'."
+    )
+
+
+def _task_definition_has_port_name(
+    task_definition: Dict[str, Any], port_name: str
+) -> bool:
+    for container in task_definition.get("containerDefinitions", []):
+        for mapping in container.get("portMappings") or []:
+            if mapping.get("name") == port_name:
+                return True
+    return False
+
+
+def _container_definitions_with_named_port(
+    container_definitions: List[Dict[str, Any]],
+    *,
+    port_name: str,
+    container_port: int,
+) -> List[Dict[str, Any]]:
+    updated: List[Dict[str, Any]] = []
+    has_matching_port = any(
+        mapping.get("containerPort") == container_port
+        for container in container_definitions
+        for mapping in container.get("portMappings") or []
+    )
+    for index, container in enumerate(container_definitions):
+        container = {
+            key: value
+            for key, value in container.items()
+            if key not in _CONTAINER_REGISTER_OMIT_KEYS
+        }
+        port_mappings = [
+            dict(mapping) for mapping in container.get("portMappings") or []
+        ]
+        matched = False
+        for mapping in port_mappings:
+            if mapping.get("containerPort") == container_port:
+                matched = True
+                mapping["name"] = port_name
+                mapping.setdefault("protocol", "tcp")
+        if not matched and not has_matching_port and index == 0:
+            port_mappings.append(
+                {
+                    "name": port_name,
+                    "containerPort": container_port,
+                    "protocol": "tcp",
+                }
+            )
+        container["portMappings"] = port_mappings
+        updated.append(container)
+    return updated
+
+
+def resolve_service_task_definition_arn(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """
+    Resolve the task definition ARN for a Fargate or Express gateway ECS service.
+
+    Express gateway services omit ``taskDefinition`` on ``describe_services``; use the
+    active service revision from ``describe_express_gateway_service`` instead.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    services = ecs_client.describe_services(
+        cluster=cluster_name, services=[service_name]
+    ).get("services", [])
+    if services:
+        task_definition_arn = services[0].get("taskDefinition")
+        if task_definition_arn:
+            return task_definition_arn
+        service_arn = services[0].get("serviceArn")
+    else:
+        service_arn = None
+
+    if not service_arn:
+        service_arn = resolve_express_gateway_service_arn(
+            cluster_name, service_name, aws_region
+        )
+
+    express = ecs_client.describe_express_gateway_service(serviceArn=service_arn)
+    active_configs = (express.get("service") or {}).get("activeConfigurations") or []
+    if not active_configs:
+        raise ValueError(
+            f"Could not resolve task definition for service '{service_name}' in "
+            f"cluster '{cluster_name}' (no active Express gateway configuration)."
+        )
+    revision_arn = active_configs[0].get("serviceRevisionArn")
+    if not revision_arn:
+        raise ValueError(
+            f"Could not resolve task definition for service '{service_name}' "
+            "(active Express configuration has no serviceRevisionArn)."
+        )
+    revisions = ecs_client.describe_service_revisions(
+        serviceRevisionArns=[revision_arn]
+    ).get("serviceRevisions", [])
+    if not revisions:
+        raise ValueError(
+            f"Service revision '{revision_arn}' not found for service "
+            f"'{service_name}'."
+        )
+    task_definition_arn = revisions[0].get("taskDefinition")
+    if not task_definition_arn:
+        raise ValueError(
+            f"Service revision '{revision_arn}' has no taskDefinition for service "
+            f"'{service_name}'."
+        )
+    return task_definition_arn
+
+
+def ensure_ecs_service_port_mapping_name(
+    cluster_name: str,
+    service_name: str,
+    port_name: str,
+    container_port: int,
+    aws_region: str = AWS_REGION,
+) -> str:
+    """
+    Service Connect requires a named portMapping in the task definition.
+    Express gateway services only set containerPort at create time.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    task_definition_arn = resolve_service_task_definition_arn(
+        cluster_name, service_name, aws_region
+    )
+    task_definition = ecs_client.describe_task_definition(
+        taskDefinition=task_definition_arn
+    )["taskDefinition"]
+    if _task_definition_has_port_name(task_definition, port_name):
+        return task_definition_arn
+
+    new_containers = _container_definitions_with_named_port(
+        task_definition["containerDefinitions"],
+        port_name=port_name,
+        container_port=container_port,
+    )
+    register_kwargs = {
+        key: copy.deepcopy(task_definition[key])
+        for key in _TASK_DEF_REGISTER_KEYS
+        if key in task_definition
+    }
+    register_kwargs["containerDefinitions"] = new_containers
+    if task_definition.get("tags"):
+        register_kwargs["tags"] = [
+            {"key": tag["key"], "value": tag["value"]}
+            for tag in task_definition["tags"]
+        ]
+
+    new_task_definition = ecs_client.register_task_definition(**register_kwargs)[
+        "taskDefinition"
+    ]
+    new_arn = new_task_definition["taskDefinitionArn"]
+    ecs_client.update_service(
+        cluster=cluster_name,
+        service=service_name,
+        taskDefinition=new_arn,
+        forceNewDeployment=True,
+    )
+    print(
+        f"Registered task definition {new_arn} with Service Connect port "
+        f"name {port_name!r} on container port {container_port}."
+    )
+    return new_arn
+
+
+def apply_ecs_service_connect(
+    cluster_name: str,
+    service_name: str,
+    service_connect_configuration: Dict[str, Any],
+    aws_region: str = AWS_REGION,
+) -> None:
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    ecs_client.update_service(
+        cluster=cluster_name,
+        service=service_name,
+        serviceConnectConfiguration=service_connect_configuration,
+        forceNewDeployment=True,
+    )
+    print(f"Applied Service Connect to {service_name} in cluster {cluster_name}.")
+
+
+def configure_express_pi_service_connect(
+    cluster_name: str,
+    main_service_name: str,
+    pi_service_name: str,
+    namespace: str,
+    main_port_name: str,
+    discovery_name: str,
+    main_port: int,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """Enable Service Connect for Pi Express -> main Express (post image build)."""
+    ensure_ecs_service_port_mapping_name(
+        cluster_name,
+        main_service_name,
+        main_port_name,
+        main_port,
+        aws_region=aws_region,
+    )
+    apply_ecs_service_connect(
+        cluster_name,
+        main_service_name,
+        {
+            "enabled": True,
+            "namespace": namespace,
+            "services": [
+                {
+                    "portName": main_port_name,
+                    "discoveryName": discovery_name,
+                    "clientAliases": [
+                        {"port": int(main_port), "dnsName": discovery_name}
+                    ],
+                }
+            ],
+        },
+        aws_region=aws_region,
+    )
+    apply_ecs_service_connect(
+        cluster_name,
+        pi_service_name,
+        {"enabled": True, "namespace": namespace},
+        aws_region=aws_region,
+    )
+
+
+def start_express_gateway_service(
+    cluster_name: str,
+    service_name: str,
+    aws_region: str = AWS_REGION,
+) -> dict:
+    """Scale an ECS Express gateway service to one running task after image build."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+
+    try:
+        service_arn = resolve_express_gateway_service_arn(
+            cluster_name, service_name, aws_region=aws_region
+        )
+        ecs_client.update_express_gateway_service(
+            serviceArn=service_arn,
+            scalingTarget=EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET,
+        )
+        return {
+            "statusCode": 200,
+            "body": (
+                f"Express service {service_name} in cluster {cluster_name} "
+                "has been updated to run 1 task."
+            ),
+        }
+    except Exception as e:
+        return {
+            "statusCode": 500,
+            "body": f"Error updating Express gateway service: {str(e)}",
+        }
+
+
+_ALB_COGNITO_CALLBACK_SUFFIX = "/oauth2/idpresponse"
+
+# Fields preserved from describe_user_pool_client when updating CallbackURLs only.
+_USER_POOL_CLIENT_UPDATE_PASSTHROUGH_KEYS = (
+    "ClientName",
+    "RefreshTokenValidity",
+    "AccessTokenValidity",
+    "IdTokenValidity",
+    "TokenValidityUnits",
+    "ReadAttributes",
+    "WriteAttributes",
+    "ExplicitAuthFlows",
+    "SupportedIdentityProviders",
+    "DefaultRedirectURI",
+    "AllowedOAuthFlows",
+    "AllowedOAuthScopes",
+    "AllowedOAuthFlowsUserPoolClient",
+    "AnalyticsConfiguration",
+    "PreventUserExistenceErrors",
+    "EnableTokenRevocation",
+    "EnablePropagateAdditionalUserContextData",
+    "AuthSessionValidity",
+    "RefreshTokenRotation",
+)
+
+
+def cognito_https_callback_urls(redirect_base: str) -> List[str]:
+    """
+    ALB authenticate-cognito requires the app URL and ``/oauth2/idpresponse``.
+    """
+    base = (redirect_base or "").strip().rstrip("/")
+    if not base:
+        raise ValueError("redirect_base is required for Cognito callback URLs")
+    if not base.startswith("https://"):
+        base = f"https://{base.lstrip('/')}"
+    return [base, f"{base}{_ALB_COGNITO_CALLBACK_SUFFIX}"]
+
+
+def cognito_callback_urls_match(
+    existing_callbacks: List[str],
+    desired_callbacks: List[str],
+) -> bool:
+    return set(existing_callbacks or []) == set(desired_callbacks)
+
+
+def get_user_pool_client_callback_urls(
+    user_pool_id: str,
+    client_id: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> List[str]:
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    return list(existing.get("CallbackURLs") or [])
+
+
+def cognito_alb_callbacks_need_update(
+    user_pool_id: str,
+    client_id: str,
+    redirect_base: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    desired = cognito_https_callback_urls(redirect_base)
+    current = get_user_pool_client_callback_urls(
+        user_pool_id, client_id, aws_region=aws_region
+    )
+    return not cognito_callback_urls_match(current, desired)
+
+
+def update_user_pool_client_callback_urls(
+    user_pool_id: str,
+    client_id: str,
+    callback_urls: List[str],
+    *,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """
+    Set Cognito app client callback URLs without a CDK redeploy.
+
+    Merges existing client settings from ``describe_user_pool_client`` so OAuth
+    flows/scopes and token validity are not reset.
+    """
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+
+    update_kwargs: Dict[str, Any] = {
+        "UserPoolId": user_pool_id,
+        "ClientId": client_id,
+        "CallbackURLs": callback_urls,
+    }
+    for key in _USER_POOL_CLIENT_UPDATE_PASSTHROUGH_KEYS:
+        value = existing.get(key)
+        if value is not None:
+            update_kwargs[key] = value
+    logout_urls = existing.get("LogoutURLs")
+    if logout_urls:
+        update_kwargs["LogoutURLs"] = logout_urls
+
+    cognito_client.update_user_pool_client(**update_kwargs)
+    print("Updated Cognito app client callback URLs: " + ", ".join(callback_urls))
+
+
+def apply_cognito_alb_callback_fixup(
+    *,
+    user_pool_id: str,
+    client_id: str,
+    redirect_base: str,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Update Cognito callbacks when they differ from ``redirect_base``.
+
+    Returns True if URLs were updated, False if already correct.
+    """
+    desired = cognito_https_callback_urls(redirect_base)
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    existing = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    current = existing.get("CallbackURLs") or []
+    if cognito_callback_urls_match(current, desired):
+        print("Cognito app client callback URLs already match the target endpoint.")
+        return False
+    update_user_pool_client_callback_urls(
+        user_pool_id,
+        client_id,
+        desired,
+        aws_region=aws_region,
+    )
+    return True
+
+
+_TARGET_GROUP_REGISTER_EVENT = re.compile(
+    r"target-group (arn:aws:elasticloadbalancing:[^\s)]+)",
+    re.IGNORECASE,
+)
+
+EXPRESS_TARGET_GROUP_RESOLVE_MAX_WAIT_SECONDS = 600
+EXPRESS_TARGET_GROUP_RESOLVE_POLL_INTERVAL_SECONDS = 15
+
+
+def target_group_arn_from_ecs_register_event(message: str) -> Optional[str]:
+    """Parse target group ARN from ECS ``registered N targets in (target-group ...)``."""
+    if "registered" not in (message or "").lower():
+        return None
+    match = _TARGET_GROUP_REGISTER_EVENT.search(message)
+    return match.group(1) if match else None
+
+
+def _target_group_arn_from_service_events(
+    events: List[Dict[str, Any]],
+) -> Optional[str]:
+    for event in events:
+        target_group_arn = target_group_arn_from_ecs_register_event(
+            event.get("message", "")
+        )
+        if target_group_arn:
+            return target_group_arn
+    return None
+
+
+def _task_private_ipv4_addresses(
+    ecs_client: Any,
+    cluster_name: str,
+    service_name: str,
+) -> set[str]:
+    task_arns = ecs_client.list_tasks(
+        cluster=cluster_name, serviceName=service_name
+    ).get("taskArns", [])
+    if not task_arns:
+        return set()
+    tasks = ecs_client.describe_tasks(cluster=cluster_name, tasks=task_arns).get(
+        "tasks", []
+    )
+    addresses: set[str] = set()
+    for task in tasks:
+        for attachment in task.get("attachments", []):
+            for detail in attachment.get("details", []):
+                if detail.get("name") == "privateIPv4Address" and detail.get("value"):
+                    addresses.add(detail["value"])
+    return addresses
+
+
+def _target_group_arn_from_task_ips(
+    elbv2_client: Any,
+    load_balancer_arn: str,
+    task_ips: set[str],
+) -> Optional[str]:
+    if not task_ips:
+        return None
+    target_groups = elbv2_client.describe_target_groups(
+        LoadBalancerArn=load_balancer_arn
+    ).get("TargetGroups", [])
+    for target_group in target_groups:
+        health = elbv2_client.describe_target_health(
+            TargetGroupArn=target_group["TargetGroupArn"]
+        ).get("TargetHealthDescriptions", [])
+        for description in health:
+            target_id = (description.get("Target") or {}).get("Id")
+            if target_id in task_ips:
+                return target_group["TargetGroupArn"]
+    return None
+
+
+def resolve_express_service_target_group_arn(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+    load_balancer_arn: Optional[str] = None,
+    max_wait_seconds: int = EXPRESS_TARGET_GROUP_RESOLVE_MAX_WAIT_SECONDS,
+    poll_interval_seconds: int = EXPRESS_TARGET_GROUP_RESOLVE_POLL_INTERVAL_SECONDS,
+) -> str:
+    """
+    Target group where Express most recently registered tasks.
+
+    After post-deploy scaling, this ARN can differ from the TG baked into the CDK
+    Cognito listener custom resource at deploy time. Polls until a registration
+    event appears or running tasks are visible in an Express ALB target group.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    elbv2_client = (
+        boto3.client("elbv2", region_name=aws_region) if load_balancer_arn else None
+    )
+    deadline = time.monotonic() + max_wait_seconds
+    attempt = 0
+    while True:
+        attempt += 1
+        services = ecs_client.describe_services(
+            cluster=cluster_name, services=[service_name]
+        ).get("services", [])
+        if not services:
+            raise ValueError(
+                f"ECS service '{service_name}' not found in cluster '{cluster_name}'."
+            )
+        service = services[0]
+        target_group_arn = _target_group_arn_from_service_events(
+            service.get("events", [])
+        )
+        if target_group_arn:
+            if attempt > 1:
+                print(
+                    f"Resolved target group for '{service_name}' "
+                    f"after {attempt} poll(s)."
+                )
+            return target_group_arn
+
+        if elbv2_client and load_balancer_arn:
+            task_ips = _task_private_ipv4_addresses(
+                ecs_client, cluster_name, service_name
+            )
+            target_group_arn = _target_group_arn_from_task_ips(
+                elbv2_client, load_balancer_arn, task_ips
+            )
+            if target_group_arn:
+                print(
+                    f"Resolved target group for '{service_name}' from running task IPs."
+                )
+                return target_group_arn
+
+        if time.monotonic() >= deadline:
+            running = service.get("runningCount", 0)
+            desired = service.get("desiredCount", 0)
+            raise ValueError(
+                f"No target group registration event found for service "
+                f"'{service_name}' after {max_wait_seconds}s "
+                f"(running {running}/{desired} tasks). "
+                "Ensure CodeBuild finished and the service scaled to at least one task."
+            )
+
+        if attempt == 1:
+            print(
+                f"Waiting for target group registration for '{service_name}' "
+                f"(up to {max_wait_seconds}s)..."
+            )
+        time.sleep(poll_interval_seconds)
+
+
+def find_express_gateway_https_listener(
+    *,
+    aws_region: str = AWS_REGION,
+) -> Dict[str, str]:
+    """Return Express-managed ALB HTTPS listener metadata."""
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    for load_balancer in elbv2.describe_load_balancers().get("LoadBalancers", []):
+        if not load_balancer["LoadBalancerName"].startswith("ecs-express-gateway-alb"):
+            continue
+        listeners = elbv2.describe_listeners(
+            LoadBalancerArn=load_balancer["LoadBalancerArn"]
+        ).get("Listeners", [])
+        https_listener = next(
+            (listener for listener in listeners if listener.get("Port") == 443),
+            None,
+        )
+        if https_listener:
+            return {
+                "load_balancer_arn": load_balancer["LoadBalancerArn"],
+                "listener_arn": https_listener["ListenerArn"],
+                "dns_name": load_balancer["DNSName"],
+            }
+    raise ValueError(
+        "Express gateway ALB (ecs-express-gateway-alb-*) with HTTPS listener not found."
+    )
+
+
+def listener_actions_with_target_group(
+    existing_actions: List[Dict[str, Any]],
+    target_group_arn: str,
+) -> List[Dict[str, Any]]:
+    """Copy listener/rule actions, replacing the forward target group ARN."""
+    updated_actions: List[Dict[str, Any]] = []
+    for action in sorted(existing_actions, key=lambda item: item.get("Order", 0)):
+        action_copy = copy.deepcopy(action)
+        if action_copy.get("Type") == "forward":
+            action_copy["TargetGroupArn"] = target_group_arn
+            forward_config = action_copy.setdefault("ForwardConfig", {})
+            forward_config["TargetGroups"] = [
+                {"TargetGroupArn": target_group_arn, "Weight": 1}
+            ]
+        updated_actions.append(action_copy)
+    return updated_actions
+
+
+def apply_express_alb_listener_target_group_fixup(
+    *,
+    cluster_name: str,
+    main_service_name: str,
+    pi_service_name: Optional[str] = None,
+    pi_path_prefixes: Optional[List[str]] = None,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Point ALB Cognito listener actions at the target groups Express tasks use.
+
+    Express creates fresh target groups when a service scales up after deploy; the
+    CDK custom resource may still forward authenticated traffic to an empty TG.
+    """
+    ingress = find_express_gateway_https_listener(aws_region=aws_region)
+    load_balancer_arn = ingress["load_balancer_arn"]
+    main_target_group_arn = resolve_express_service_target_group_arn(
+        cluster_name,
+        main_service_name,
+        aws_region=aws_region,
+        load_balancer_arn=load_balancer_arn,
+    )
+    pi_target_group_arn = None
+    if pi_service_name:
+        try:
+            pi_target_group_arn = resolve_express_service_target_group_arn(
+                cluster_name,
+                pi_service_name,
+                aws_region=aws_region,
+                load_balancer_arn=load_balancer_arn,
+            )
+        except ValueError as exc:
+            print(f"Note: skipping Pi listener rule TG fixup: {exc}")
+
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    listener_arn = ingress["listener_arn"]
+    listener = elbv2.describe_listeners(ListenerArns=[listener_arn])["Listeners"][0]
+    current_default = listener.get("DefaultActions", [])
+    current_forward_arn = next(
+        (
+            action.get("TargetGroupArn")
+            for action in current_default
+            if action.get("Type") == "forward"
+        ),
+        None,
+    )
+    changed = current_forward_arn != main_target_group_arn
+
+    if changed:
+        elbv2.modify_listener(
+            ListenerArn=listener_arn,
+            DefaultActions=listener_actions_with_target_group(
+                current_default, main_target_group_arn
+            ),
+        )
+        print(
+            "Updated Express ALB default listener forward target group to "
+            f"{main_target_group_arn}."
+        )
+    else:
+        print(
+            "Express ALB default listener already forwards to the active target group."
+        )
+
+    if pi_target_group_arn and pi_path_prefixes:
+        rules = elbv2.describe_rules(ListenerArn=listener_arn).get("Rules", [])
+        prefixes = {prefix.rstrip("/") for prefix in pi_path_prefixes}
+        for rule in rules:
+            if rule.get("IsDefault"):
+                continue
+            path_values = []
+            for condition in rule.get("Conditions", []):
+                if condition.get("Field") == "path-pattern":
+                    path_values.extend(condition.get("Values", []))
+            if not prefixes.intersection({value.rstrip("/") for value in path_values}):
+                continue
+            current_actions = rule.get("Actions", [])
+            current_pi_forward = next(
+                (
+                    action.get("TargetGroupArn")
+                    for action in current_actions
+                    if action.get("Type") == "forward"
+                ),
+                None,
+            )
+            if current_pi_forward == pi_target_group_arn:
+                continue
+            elbv2.modify_rule(
+                RuleArn=rule["RuleArn"],
+                Actions=listener_actions_with_target_group(
+                    current_actions, pi_target_group_arn
+                ),
+            )
+            print(
+                "Updated Pi ALB listener rule forward target group to "
+                f"{pi_target_group_arn}."
+            )
+            changed = True
+
+    return changed
+
+
+def listener_rule_has_cognito_auth(actions: List[Dict[str, Any]]) -> bool:
+    return any(action.get("Type") == "authenticate-cognito" for action in actions)
+
+
+def _listener_rule_is_cloudfront_bypass_without_cognito(
+    rule: Dict[str, Any],
+    *,
+    cloudfront_host_header: str,
+) -> bool:
+    """True for legacy forward-only host-header rules matching the CloudFront domain."""
+    if listener_rule_has_cognito_auth(rule.get("Actions", [])):
+        return False
+    host = (cloudfront_host_header or "").strip()
+    if not host or host == "cloudfront_placeholder.net":
+        return False
+    for condition in rule.get("Conditions") or []:
+        if condition.get("Field") != "host-header":
+            continue
+        values = (condition.get("HostHeaderConfig") or {}).get("Values") or []
+        if host in values:
+            return True
+    return False
+
+
+def remove_express_listener_rules_without_cognito(
+    *,
+    aws_region: str = AWS_REGION,
+    cloudfront_host_header: Optional[str] = None,
+) -> bool:
+    """
+    Delete legacy Express ALB rules that forward CloudFront host traffic without Cognito.
+
+    Only removes host-header rules whose value matches ``CLOUDFRONT_DOMAIN`` (or the
+    supplied override). ECS Express-managed ``*.ecs.*.on.aws`` host rules are left
+    intact.
+    """
+    cloudfront_host = (cloudfront_host_header or CLOUDFRONT_DOMAIN or "").strip()
+    ingress = find_express_gateway_https_listener(aws_region=aws_region)
+    elbv2 = boto3.client("elbv2", region_name=aws_region)
+    listener_arn = ingress["listener_arn"]
+    changed = False
+    for rule in elbv2.describe_rules(ListenerArn=listener_arn).get("Rules", []):
+        if rule.get("IsDefault"):
+            continue
+        if not _listener_rule_is_cloudfront_bypass_without_cognito(
+            rule, cloudfront_host_header=cloudfront_host
+        ):
+            continue
+        rule_arn = rule["RuleArn"]
+        elbv2.delete_rule(RuleArn=rule_arn)
+        print(
+            "Removed legacy Express CloudFront bypass ALB listener rule "
+            f"(host {cloudfront_host!r}): {rule_arn}"
+        )
+        changed = True
+    return changed
+
+
+def build_cognito_secret_payload(
+    user_pool_id: str,
+    client_id: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> Dict[str, str]:
+    """Build Secrets Manager JSON for SUMMARISATION_* Cognito keys."""
+    cognito_client = boto3.client("cognito-idp", region_name=aws_region)
+    client = cognito_client.describe_user_pool_client(
+        UserPoolId=user_pool_id,
+        ClientId=client_id,
+    )["UserPoolClient"]
+    client_secret = client.get("ClientSecret") or ""
+    return {
+        "SUMMARISATION_USER_POOL_ID": user_pool_id,
+        "SUMMARISATION_CLIENT_ID": client_id,
+        "SUMMARISATION_CLIENT_SECRET": client_secret,
+    }
+
+
+def cognito_secret_payload_matches(
+    existing_secret_string: str,
+    desired_payload: Dict[str, str],
+) -> bool:
+    try:
+        current = json.loads(existing_secret_string or "{}")
+    except json.JSONDecodeError:
+        return False
+    return all(current.get(key) == value for key, value in desired_payload.items())
+
+
+def apply_cognito_secret_fixup(
+    *,
+    secret_name: str,
+    user_pool_id: str,
+    client_id: str,
+    aws_region: str = AWS_REGION,
+    recycle_express_service: Optional[Dict[str, str]] = None,
+) -> bool:
+    """
+    Sync imported Secrets Manager JSON with the stack's Cognito pool and app client.
+
+    Express tasks read ``AWS_USER_POOL_ID`` / ``AWS_CLIENT_*`` from this secret.
+    When the secret predates a redeploy, values can reference a deleted user pool.
+    """
+    desired_payload = build_cognito_secret_payload(
+        user_pool_id, client_id, aws_region=aws_region
+    )
+    secrets_client = boto3.client("secretsmanager", region_name=aws_region)
+    current = secrets_client.get_secret_value(SecretId=secret_name)
+    current_string = current.get("SecretString") or ""
+    if cognito_secret_payload_matches(current_string, desired_payload):
+        print(
+            "Cognito secret already matches Cognito user pool ID "
+            "and Cognito app client ID."
+        )
+        return False
+
+    secrets_client.put_secret_value(
+        SecretId=secret_name,
+        SecretString=json.dumps(desired_payload),
+    )
+    print(
+        "Updated Cognito secret for Cognito user pool ID " "and Cognito app client ID."
+    )
+    if recycle_express_service:
+        recycle_express_gateway_tasks(
+            recycle_express_service["cluster_name"],
+            recycle_express_service["service_name"],
+            aws_region=aws_region,
+        )
+    return True
+
+
+def recycle_express_gateway_tasks(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> None:
+    """Stop running Express tasks so replacements pick up updated secrets/env."""
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    task_arns = ecs_client.list_tasks(
+        cluster=cluster_name,
+        serviceName=service_name,
+    ).get("taskArns", [])
+    for task_arn in task_arns:
+        ecs_client.stop_task(
+            cluster=cluster_name,
+            task=task_arn,
+            reason="Recycle task after Cognito secret/config sync",
+        )
+    if task_arns:
+        print(
+            f"Stopped {len(task_arns)} task(s) for {service_name} to pick up Cognito updates."
+        )
+
+
+def apply_express_disable_in_app_cognito_auth(
+    cluster_name: str,
+    service_name: str,
+    *,
+    aws_region: str = AWS_REGION,
+) -> bool:
+    """
+    Set ``COGNITO_AUTH=False`` on a running Express service revision.
+
+    ALB ``authenticate-cognito`` already gates access; in-app Gradio login is redundant
+    and fails when Secrets Manager still references an old user pool.
+    """
+    ecs_client = boto3.client("ecs", region_name=aws_region)
+    service_arn = resolve_express_gateway_service_arn(
+        cluster_name, service_name, aws_region=aws_region
+    )
+    express = ecs_client.describe_express_gateway_service(serviceArn=service_arn)[
+        "service"
+    ]
+    active_configs = express.get("activeConfigurations") or []
+    if not active_configs:
+        raise ValueError(
+            f"No active configuration for Express service '{service_name}'."
+        )
+    active = active_configs[0]
+    primary = copy.deepcopy(active.get("primaryContainer") or {})
+    environment = {
+        item["name"]: item["value"]
+        for item in primary.get("environment") or []
+        if item.get("name")
+    }
+    if environment.get("COGNITO_AUTH") == "False":
+        print(f"{service_name} already has COGNITO_AUTH=False.")
+        return False
+    environment["COGNITO_AUTH"] = "False"
+    primary["environment"] = [
+        {"name": name, "value": value} for name, value in sorted(environment.items())
+    ]
+    update_kwargs: Dict[str, Any] = {
+        "serviceArn": service_arn,
+        "primaryContainer": primary,
+    }
+    for key in (
+        "executionRoleArn",
+        "taskRoleArn",
+        "cpu",
+        "memory",
+        "healthCheckPath",
+        "networkConfiguration",
+    ):
+        value = active.get(key)
+        if value is not None:
+            update_kwargs[key] = value
+    scaling = express.get("scalingTarget") or active.get("scalingTarget")
+    if scaling is not None:
+        update_kwargs["scalingTarget"] = scaling
+    ecs_client.update_express_gateway_service(**update_kwargs)
+    print(f"Set COGNITO_AUTH=False on Express service {service_name}.")
+    return True
+
+
+def apply_cognito_secret_fixup_from_stack(
+    *,
+    stack_name: str,
+    secret_name: str,
+    cluster_name: str,
+    main_service_name: str,
+    aws_region: str = AWS_REGION,
+    recycle_tasks: bool = True,
+) -> bool:
+    """Read Cognito outputs from CloudFormation and sync the app client secret."""
+    cfn_client = boto3.client("cloudformation", region_name=aws_region)
+    stacks = cfn_client.describe_stacks(StackName=stack_name).get("Stacks", [])
+    outputs = {
+        item["OutputKey"]: item["OutputValue"]
+        for item in (stacks[0].get("Outputs") or [])
+    }
+    user_pool_id = outputs.get("CognitoPoolId")
+    client_id = outputs.get("CognitoAppClientId")
+    if not user_pool_id or not client_id:
+        raise ValueError(
+            f"Stack '{stack_name}' is missing CognitoPoolId or CognitoAppClientId outputs."
+        )
+    return apply_cognito_secret_fixup(
+        secret_name=secret_name,
+        user_pool_id=user_pool_id,
+        client_id=client_id,
+        aws_region=aws_region,
+        recycle_express_service=(
+            {"cluster_name": cluster_name, "service_name": main_service_name}
+            if recycle_tasks
+            else None
+        ),
+    )
+
+
+def get_stack_output(
+    stack_name: str,
+    output_key: str,
+    region: str,
+) -> Optional[str]:
+    """Return a CloudFormation stack output value, or None if missing."""
+    from botocore.exceptions import ClientError
+
+    cfn = boto3.client("cloudformation", region_name=region)
+    try:
+        response = cfn.describe_stacks(StackName=stack_name)
+    except ClientError:
+        return None
+    for stack in response.get("Stacks", []):
+        for output in stack.get("Outputs", []):
+            if output.get("OutputKey") == output_key:
+                return output.get("OutputValue")
+    return None
+
+
+def print_express_mode_next_steps(
+    values: Dict[str, str],
+    *,
+    stack_name: str = "SummarisationStack",
+    region: Optional[str] = None,
+) -> None:
+    """Print user-facing next steps after Express mode deploy + quickstart."""
+    from cdk_config import normalize_https_redirect_url
+    from cdk_functions import format_express_pi_public_url
+
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+
+    main_raw = (values.get("ECS_EXPRESS_COGNITO_REDIRECT_BASE") or "").strip()
+    if not main_raw:
+        main_raw = (
+            get_stack_output(stack_name, "ExpressServiceEndpoint", aws_region) or ""
+        )
+    main_url = normalize_https_redirect_url(main_raw) if main_raw else ""
+
+    print("\nDone. Next steps:")
+    print("  - Wait 10 minutes for app deployment to finish.")
+    pi_express = values.get("ENABLE_PI_AGENT_EXPRESS_SERVICE") == "True"
+    if pi_express:
+        print(
+            "- Register a Cognito user in AWS Console, change password at the login page URL "
+            "(available in the Cognito AWS console -> App Clients -> Login pages -> View login page "
+            "and sign in at the Pi agent URL below. The main topic-modelling backend runs without "
+            "in-app login so the Pi agent can call it over Service Connect. You can disable "
+            "Cognito login by setting COGNITO_AUTH to False in the ECS task definition / "
+            "ECS service options."
+        )
+    else:
+        print(
+            "  - If you have enabled Cognito login in the app, register a new user "
+            "to your Cognito user pool in AWS Console and complete sign up with the app "
+            "client login. If you do not want Cognito login, then set COGNITO_AUTH to "
+            "False in the ECS task definition / ECS service options."
+        )
+    if main_url:
+        print(f"  - The main topic modelling app can be accessed at {main_url}")
+    else:
+        print(
+            "  - The main topic modelling app URL: see ExpressServiceEndpoint stack output"
+        )
+
+    if values.get("ENABLE_PI_AGENT_EXPRESS_SERVICE") == "True":
+        pi_raw = get_stack_output(stack_name, "PiExpressEndpoint", aws_region) or ""
+        pi_url = (
+            format_express_pi_public_url(normalize_https_redirect_url(pi_raw))
+            if pi_raw
+            else ""
+        )
+        if pi_url:
+            print(f"  - The Pi agent app can be accessed at {pi_url}")
+        else:
+            print("  - The Pi agent app URL: see PiExpressEndpoint stack output")
+
+
+def _s3_object_exists(s3_client, bucket: str, key: str) -> bool:
+    from botocore.exceptions import ClientError
+
+    try:
+        s3_client.head_object(Bucket=bucket, Key=key)
+        return True
+    except ClientError as exc:
+        code = exc.response.get("Error", {}).get("Code", "")
+        if code in ("404", "NoSuchKey", "NotFound"):
+            return False
+        raise
+
+
+def seed_headless_batch_s3_layout(
+    output_bucket: str,
+    *,
+    input_prefix: str = "input/",
+    env_prefix: str = "input/config/",
+    example_env_local_path: str,
+    example_env_basename: str = "example_headless_env_file.env",
+    aws_region: str = AWS_REGION,
+) -> None:
+    """
+    Ensure headless batch prefixes and example job .env exist on the output bucket.
+
+    Idempotent: existing keys are left unchanged (safe to run from quickstart).
+    """
+    if not output_bucket:
+        print("Skipping headless S3 layout seed: output bucket name is empty.")
+        return
+
+    input_prefix_norm = (
+        input_prefix if input_prefix.endswith("/") else f"{input_prefix}/"
+    )
+    env_prefix_norm = env_prefix if env_prefix.endswith("/") else f"{env_prefix}/"
+    if not env_prefix_norm.startswith(input_prefix_norm):
+        env_prefix_norm = f"{input_prefix_norm}{env_prefix_norm.lstrip('/')}"
+        if not env_prefix_norm.endswith("/"):
+            env_prefix_norm += "/"
+
+    s3_client = boto3.client("s3", region_name=aws_region)
+    markers = (
+        input_prefix_norm,
+        env_prefix_norm,
+    )
+    for key in markers:
+        if _s3_object_exists(s3_client, output_bucket, key):
+            print(f"S3 prefix marker already present: s3://{output_bucket}/{key}")
+            continue
+        s3_client.put_object(Bucket=output_bucket, Key=key, Body=b"")
+        print(f"Created S3 prefix marker: s3://{output_bucket}/{key}")
+
+    example_key = f"{env_prefix_norm}{example_env_basename}"
+    if _s3_object_exists(s3_client, output_bucket, example_key):
+        print(f"Example job .env already present: s3://{output_bucket}/{example_key}")
+        return
+
+    if not os.path.isfile(example_env_local_path):
+        print(f"Skipping example job .env upload: {example_env_local_path} not found.")
+        return
+
+    with open(example_env_local_path, "rb") as handle:
+        s3_client.put_object(Bucket=output_bucket, Key=example_key, Body=handle.read())
+    print(f"Uploaded example job .env to s3://{output_bucket}/{example_key}")
+
+
+def print_headless_deployment_next_steps(
+    values: Dict[str, str],
+    *,
+    stack_name: str = "SummarisationStack",
+    region: Optional[str] = None,
+) -> None:
+    """Print user-facing next steps after headless deploy + quickstart."""
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+    output_bucket = (values.get("S3_OUTPUT_BUCKET_NAME") or "").strip()
+    input_prefix = (values.get("S3_BATCH_INPUT_PREFIX") or "input/").strip("/")
+    config_prefix = (values.get("S3_BATCH_ENV_PREFIX") or "input/config/").strip("/")
+
+    lambda_name = (values.get("S3_BATCH_LAMBDA_FUNCTION_NAME") or "").strip()
+    if not lambda_name:
+        lambda_name = (
+            get_stack_output(stack_name, "BatchEcsTriggerLambdaName", aws_region) or ""
+        ).strip()
+    if not lambda_name:
+        prefix = (values.get("CDK_PREFIX") or "").strip()
+        lambda_name = f"{prefix}S3BatchEcsTrigger" if prefix else "S3BatchEcsTrigger"
+
+    input_uri = (
+        f"s3://{output_bucket}/{input_prefix}/"
+        if output_bucket
+        else f"<output-bucket>/{input_prefix}/"
+    )
+    config_uri = (
+        f"s3://{output_bucket}/{config_prefix}/"
+        if output_bucket
+        else f"<output-bucket>/{config_prefix}/"
+    )
+    output_uri = (
+        f"s3://{output_bucket}/output/<session-folder>/"
+        if output_bucket
+        else "<output-bucket>/output/<session-folder>/"
+    )
+    example_name = "example_headless_env_file.env"
+
+    print("\nDone. Next steps:")
+    print(
+        f"  - Upload a consultation spreadsheet (.xlsx) to {input_uri}. "
+        "You can use dummy_consultation_response.xlsx as a placeholder filename "
+        "in the example job .env below."
+    )
+    print(
+        f"  - Create a job .env file for submitting a task to {config_uri}. "
+        f"You can copy the example at cdk/config/headless_s3_seed/input/config/{example_name} "
+        f"(also seeded at {config_uri}{example_name}) and adjust DIRECT_MODE_INPUT_FILE "
+        "and DIRECT_MODE_TEXT_COLUMN. Further DIRECT_MODE_* variables are documented in "
+        "tools/config.py and cli_topics.py."
+    )
+    print(f"  - Upload your job .env file to {config_uri}")
+    print(
+        f"  - AWS Lambda function {lambda_name} will start an ECS task to run "
+        "topic modelling according to your job .env (RUN_DIRECT_MODE=1)."
+    )
+    print(
+        f"  - Outputs are written to {output_uri} when SAVE_OUTPUTS_TO_S3=True "
+        "in your job .env (see the example file)."
+    )
+    log_group = (values.get("ECS_LOG_GROUP_NAME") or "").strip()
+    if log_group:
+        print(
+            f"  - Batch task logs: CloudWatch log group {log_group} "
+            "(streams appear once the container starts)."
+        )
+
+
+def print_headless_output_notification_steps(values: Dict[str, str]) -> None:
+    """Print follow-on steps for S3 output alarms, SNS, and IAM reader user."""
+    email = (values.get("HEADLESS_OUTPUT_NOTIFY_EMAIL") or "").strip()
+    iam_user = (values.get("HEADLESS_OUTPUT_IAM_USER_NAME") or "").strip()
+    output_bucket = (values.get("S3_OUTPUT_BUCKET_NAME") or "").strip()
+    output_prefix = (values.get("HEADLESS_OUTPUT_S3_PREFIX") or "output/").strip()
+    alarm_name = (values.get("HEADLESS_OUTPUT_ALARM_NAME") or "").strip()
+    secret_name = (values.get("HEADLESS_OUTPUT_IAM_SECRET_NAME") or "").strip()
+
+    print("\nHeadless output notifications:")
+    if email:
+        print(
+            f"  - Confirm the SNS email subscription sent to {email} "
+            "(check spam; status shows Pending until confirmed)."
+        )
+    if output_bucket:
+        print(
+            f"  - CloudWatch alarm fires when objects are uploaded under "
+            f"s3://{output_bucket}/{output_prefix.rstrip('/')}/"
+        )
+    if alarm_name:
+        print(f"  - Alarm name: {alarm_name}")
+    if iam_user:
+        print(
+            f"  - IAM user {iam_user} can list/get/put/delete objects in the "
+            f"output bucket for programmatic result download."
+        )
+    if secret_name:
+        print(
+            "  - If an access key was created, credentials are stored in "
+            "the relevantSecrets Manager secret."
+        )
+
+
+def provision_headless_output_reader_access_key(
+    values: Dict[str, str],
+    *,
+    region: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Create an IAM access key for the headless output reader user.
+
+    Stores JSON credentials in Secrets Manager when HEADLESS_OUTPUT_IAM_SECRET_NAME
+    is set in cdk_config.env.
+    """
+    from botocore.exceptions import ClientError
+
+    iam_user = (values.get("HEADLESS_OUTPUT_IAM_USER_NAME") or "").strip()
+    if not iam_user:
+        print("Warning: HEADLESS_OUTPUT_IAM_USER_NAME not set; skipping access key.")
+        return None
+
+    aws_region = region or values.get("AWS_REGION") or AWS_REGION
+    iam_client = boto3.client("iam", region_name=aws_region)
+    secret_name = (values.get("HEADLESS_OUTPUT_IAM_SECRET_NAME") or "").strip()
+
+    try:
+        response = iam_client.create_access_key(UserName=iam_user)
+    except ClientError as exc:
+        print(f"Could not create IAM access key for {iam_user}: {exc}")
+        return None
+
+    access_key = response["AccessKey"]
+    payload = json.dumps(
+        {
+            "aws_access_key_id": access_key["AccessKeyId"],
+            "aws_secret_access_key": access_key["SecretAccessKey"],
+        }
+    )
+
+    if secret_name:
+        sm_client = boto3.client("secretsmanager", region_name=aws_region)
+        try:
+            sm_client.create_secret(Name=secret_name, SecretString=payload)
+            print("Stored output-reader credentials in Secrets Manager secret")
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] == "ResourceExistsException":
+                sm_client.put_secret_value(SecretId=secret_name, SecretString=payload)
+                print("Updated output-reader credentials in Secrets Manager secret")
+            else:
+                print(f"Warning: could not store credentials in Secrets Manager: {exc}")
+                print("IAM access key created (view in IAM console if needed):")
+    else:
+        print("IAM access key created (view in IAM console if needed):")
+
+    return access_key["AccessKeyId"]

cdk/check_resources.py

@@ -0,0 +1,583 @@
+import json
+import os
+from typing import Dict, List
+
+from cdk_config import (  # Import necessary config
+    ALB_NAME,
+    AWS_REGION,
+    CDK_CONFIG_PATH,
+    CDK_FOLDER,
+    CODEBUILD_PROJECT_NAME,
+    CODEBUILD_ROLE_NAME,
+    COGNITO_USER_POOL_CLIENT_NAME,
+    COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+    COGNITO_USER_POOL_DOMAIN_PREFIX,
+    COGNITO_USER_POOL_NAME,
+    CONTEXT_FILE,
+    ECR_CDK_REPO_NAME,
+    ECR_PI_REPO_NAME,
+    ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP,
+    ECS_TASK_EXECUTION_ROLE_NAME,
+    ECS_TASK_ROLE_NAME,
+    ENABLE_ECS_SERVICE_CONNECT,
+    ENABLE_HEADLESS_DEPLOYMENT,
+    ENABLE_PI_AGENT_ECS_SERVICE,
+    ENABLE_S3_BATCH_ECS_TRIGGER,
+    EXISTING_IGW_ID,
+    PRIVATE_SUBNET_AVAILABILITY_ZONES,
+    PRIVATE_SUBNET_CIDR_BLOCKS,
+    PRIVATE_SUBNETS_TO_USE,
+    PUBLIC_SUBNET_AVAILABILITY_ZONES,
+    PUBLIC_SUBNET_CIDR_BLOCKS,
+    PUBLIC_SUBNETS_TO_USE,
+    S3_LOG_CONFIG_BUCKET_NAME,
+    S3_OUTPUT_BUCKET_NAME,
+    USE_ECS_EXPRESS_MODE,
+    VPC_NAME,
+    WEB_ACL_NAME,
+)
+from cdk_functions import (  # Import your check functions (assuming they use Boto3)
+    _get_existing_subnets_in_vpc,
+    audit_public_subnet_internet_connectivity,
+    check_alb_exists,
+    check_codebuild_project_exists,
+    check_ecr_repo_exists,
+    check_for_existing_role,
+    check_for_existing_user_pool,
+    check_for_existing_user_pool_client,
+    check_for_secret,
+    check_subnet_exists_by_name,
+    check_web_acl_exists,
+    get_secret_kms_key_arn,
+    get_security_group_id_by_name,
+    get_vpc_id_by_name,
+    list_existing_vpc_endpoint_service_names,
+    resolve_cognito_domain_prefix_availability,
+    resolve_s3_bucket_availability,
+    validate_subnet_creation_parameters,
+    # Add other check functions as needed
+)
+
+cdk_folder = CDK_FOLDER  # <FULL_PATH_TO_CDK_FOLDER_HERE>
+
+# Full path needed to find config file
+os.environ["CDK_CONFIG_PATH"] = cdk_folder + CDK_CONFIG_PATH
+
+
+# --- Helper to parse environment variables into lists ---
+def _get_env_list(env_var_name: str) -> List[str]:
+    """Parses a comma-separated environment variable into a list of strings."""
+    value = env_var_name[1:-1].strip().replace('"', "").replace("'", "")
+    if not value:
+        return []
+    # Split by comma and filter out any empty strings that might result from extra commas
+    return [s.strip() for s in value.split(",") if s.strip()]
+
+
+if PUBLIC_SUBNETS_TO_USE and not isinstance(PUBLIC_SUBNETS_TO_USE, list):
+    PUBLIC_SUBNETS_TO_USE = _get_env_list(PUBLIC_SUBNETS_TO_USE)
+if PRIVATE_SUBNETS_TO_USE and not isinstance(PRIVATE_SUBNETS_TO_USE, list):
+    PRIVATE_SUBNETS_TO_USE = _get_env_list(PRIVATE_SUBNETS_TO_USE)
+if PUBLIC_SUBNET_CIDR_BLOCKS and not isinstance(PUBLIC_SUBNET_CIDR_BLOCKS, list):
+    PUBLIC_SUBNET_CIDR_BLOCKS = _get_env_list(PUBLIC_SUBNET_CIDR_BLOCKS)
+if PUBLIC_SUBNET_AVAILABILITY_ZONES and not isinstance(
+    PUBLIC_SUBNET_AVAILABILITY_ZONES, list
+):
+    PUBLIC_SUBNET_AVAILABILITY_ZONES = _get_env_list(PUBLIC_SUBNET_AVAILABILITY_ZONES)
+if PRIVATE_SUBNET_CIDR_BLOCKS and not isinstance(PRIVATE_SUBNET_CIDR_BLOCKS, list):
+    PRIVATE_SUBNET_CIDR_BLOCKS = _get_env_list(PRIVATE_SUBNET_CIDR_BLOCKS)
+if PRIVATE_SUBNET_AVAILABILITY_ZONES and not isinstance(
+    PRIVATE_SUBNET_AVAILABILITY_ZONES, list
+):
+    PRIVATE_SUBNET_AVAILABILITY_ZONES = _get_env_list(PRIVATE_SUBNET_AVAILABILITY_ZONES)
+
+# Check for the existence of elements in your AWS environment to see if it's necessary to create new versions of the same
+
+
+def check_and_set_context():
+    context_data = {}
+
+    # --- Find the VPC ID first ---
+    if VPC_NAME:
+        print("VPC_NAME:", VPC_NAME)
+        vpc_lookup = get_vpc_id_by_name(VPC_NAME)
+        if not vpc_lookup:
+            raise RuntimeError(
+                f"Required VPC '{VPC_NAME}' not found. Cannot proceed with subnet checks."
+            )
+        vpc_id, nat_gateways, vpc_cidr_block, vpc_cidr_blocks = vpc_lookup
+
+        # If you expect only one, or one per AZ and you're creating one per AZ in CDK:
+        if nat_gateways:
+            # For simplicity, let's just check if *any* NAT exists in the VPC
+            # A more robust check would match by subnet, AZ, or a specific tag.
+            context_data["exists:NatGateway"] = True
+            context_data["id:NatGateway"] = nat_gateways[0][
+                "NatGatewayId"
+            ]  # Store the ID of the first one found
+        else:
+            context_data["exists:NatGateway"] = False
+            context_data["id:NatGateway"] = None
+
+        context_data["vpc_id"] = vpc_id  # Store VPC ID in context
+        if vpc_cidr_block:
+            context_data["vpc_cidr_block"] = vpc_cidr_block
+        if vpc_cidr_blocks:
+            context_data["vpc_cidr_blocks"] = vpc_cidr_blocks
+
+        existing_endpoint_services = sorted(
+            list_existing_vpc_endpoint_service_names(vpc_id, region_name=AWS_REGION)
+        )
+        if existing_endpoint_services:
+            context_data["existing_vpc_endpoint_service_names"] = (
+                existing_endpoint_services
+            )
+            print(
+                "Existing VPC endpoints in target VPC (will be skipped on deploy): "
+                + ", ".join(existing_endpoint_services)
+            )
+
+        # SUBNET CHECKS
+        all_proposed_subnets_data: List[Dict[str, str]] = []
+
+        # Flag to indicate if full validation mode (with CIDR/AZs) is active
+        full_validation_mode = False
+
+        # Determine if full validation mode is possible/desired
+        # It's 'desired' if CIDR/AZs are provided, and their lengths match the name lists.
+        public_ready_for_full_validation = (
+            len(PUBLIC_SUBNETS_TO_USE) > 0
+            and len(PUBLIC_SUBNET_CIDR_BLOCKS) == len(PUBLIC_SUBNETS_TO_USE)
+            and len(PUBLIC_SUBNET_AVAILABILITY_ZONES) == len(PUBLIC_SUBNETS_TO_USE)
+        )
+        private_ready_for_full_validation = (
+            len(PRIVATE_SUBNETS_TO_USE) > 0
+            and len(PRIVATE_SUBNET_CIDR_BLOCKS) == len(PRIVATE_SUBNETS_TO_USE)
+            and len(PRIVATE_SUBNET_AVAILABILITY_ZONES) == len(PRIVATE_SUBNETS_TO_USE)
+        )
+
+        # Activate full validation if *any* type of subnet (public or private) has its full details provided.
+        # You might adjust this logic if you require ALL subnet types to have CIDRs, or NONE.
+        if public_ready_for_full_validation or private_ready_for_full_validation:
+            full_validation_mode = True
+
+            # If some are ready but others aren't, print a warning or raise an error based on your strictness
+            if (
+                public_ready_for_full_validation
+                and not private_ready_for_full_validation
+                and PRIVATE_SUBNETS_TO_USE
+            ):
+                print(
+                    "Warning: Public subnets have CIDRs/AZs, but private subnets do not. Only public will be fully validated/created with CIDRs."
+                )
+            if (
+                private_ready_for_full_validation
+                and not public_ready_for_full_validation
+                and PUBLIC_SUBNETS_TO_USE
+            ):
+                print(
+                    "Warning: Private subnets have CIDRs/AZs, but public subnets do not. Only private will be fully validated/created with CIDRs."
+                )
+
+            # Prepare data for validate_subnet_creation_parameters for all subnets that have full details
+            if public_ready_for_full_validation:
+                for i, name in enumerate(PUBLIC_SUBNETS_TO_USE):
+                    all_proposed_subnets_data.append(
+                        {
+                            "name": name,
+                            "cidr": PUBLIC_SUBNET_CIDR_BLOCKS[i],
+                            "az": PUBLIC_SUBNET_AVAILABILITY_ZONES[i],
+                        }
+                    )
+            if private_ready_for_full_validation:
+                for i, name in enumerate(PRIVATE_SUBNETS_TO_USE):
+                    all_proposed_subnets_data.append(
+                        {
+                            "name": name,
+                            "cidr": PRIVATE_SUBNET_CIDR_BLOCKS[i],
+                            "az": PRIVATE_SUBNET_AVAILABILITY_ZONES[i],
+                        }
+                    )
+
+        print(f"Target VPC ID for Boto3 lookup: {vpc_id}")
+
+        # Fetch all existing subnets in the target VPC once to avoid repeated API calls
+        try:
+            existing_aws_subnets = _get_existing_subnets_in_vpc(vpc_id)
+        except Exception as e:
+            print(f"Failed to fetch existing VPC subnets. Aborting. Error: {e}")
+            raise SystemExit(1)  # Exit immediately if we can't get baseline data
+
+        print("\n--- Running Name-Only Subnet Existence Check Mode ---")
+        # Fallback: check only by name using the existing data
+        checked_public_subnets = {}
+        if PUBLIC_SUBNETS_TO_USE:
+            for subnet_name in PUBLIC_SUBNETS_TO_USE:
+                print("subnet_name:", subnet_name)
+                exists, subnet_id = check_subnet_exists_by_name(
+                    subnet_name, existing_aws_subnets
+                )
+                checked_public_subnets[subnet_name] = {
+                    "exists": exists,
+                    "id": subnet_id,
+                    "az": (
+                        existing_aws_subnets["by_name"].get(subnet_name, {}).get("az")
+                        if exists
+                        else None
+                    ),
+                    "route_table_id": (
+                        existing_aws_subnets["by_name"]
+                        .get(subnet_name, {})
+                        .get("route_table_id")
+                        if exists
+                        else None
+                    ),
+                }
+
+                # If the subnet exists, remove it from the proposed subnets list
+                if checked_public_subnets[subnet_name]["exists"] is True:
+                    all_proposed_subnets_data = [
+                        subnet
+                        for subnet in all_proposed_subnets_data
+                        if subnet["name"] != subnet_name
+                    ]
+
+        context_data["checked_public_subnets"] = checked_public_subnets
+
+        checked_private_subnets = {}
+        if PRIVATE_SUBNETS_TO_USE:
+            for subnet_name in PRIVATE_SUBNETS_TO_USE:
+                print("subnet_name:", subnet_name)
+                exists, subnet_id = check_subnet_exists_by_name(
+                    subnet_name, existing_aws_subnets
+                )
+                checked_private_subnets[subnet_name] = {
+                    "exists": exists,
+                    "id": subnet_id,
+                    "az": (
+                        existing_aws_subnets["by_name"].get(subnet_name, {}).get("az")
+                        if exists
+                        else None
+                    ),
+                    "route_table_id": (
+                        existing_aws_subnets["by_name"]
+                        .get(subnet_name, {})
+                        .get("route_table_id")
+                        if exists
+                        else None
+                    ),
+                }
+
+                # If the subnet exists, remove it from the proposed subnets list
+                if checked_private_subnets[subnet_name]["exists"] is True:
+                    all_proposed_subnets_data = [
+                        subnet
+                        for subnet in all_proposed_subnets_data
+                        if subnet["name"] != subnet_name
+                    ]
+
+        context_data["checked_private_subnets"] = checked_private_subnets
+
+        # Internet Gateway + public subnet default routes (legacy ALB / NAT public subnets)
+        if PUBLIC_SUBNETS_TO_USE and vpc_id:
+            public_entries_for_igw_audit = []
+            for subnet_name in PUBLIC_SUBNETS_TO_USE:
+                info = checked_public_subnets.get(subnet_name, {})
+                if not info.get("exists"):
+                    continue
+                public_entries_for_igw_audit.append(
+                    {
+                        "name": subnet_name,
+                        "subnet_id": info.get("id"),
+                        "route_table_id": info.get("route_table_id"),
+                    }
+                )
+            if public_entries_for_igw_audit or EXISTING_IGW_ID:
+                print("\n--- Auditing Internet Gateway and public subnet routes ---")
+                try:
+                    igw_audit = audit_public_subnet_internet_connectivity(
+                        vpc_id,
+                        EXISTING_IGW_ID,
+                        public_entries_for_igw_audit,
+                    )
+                    context_data["internet_gateway_id"] = igw_audit[
+                        "internet_gateway_id"
+                    ]
+                    context_data["internet_gateway_needs_vpc_attachment"] = igw_audit[
+                        "internet_gateway_needs_vpc_attachment"
+                    ]
+                    context_data["public_subnets_needing_igw_route"] = igw_audit[
+                        "public_subnets_needing_igw_route"
+                    ]
+                    needing = igw_audit["public_subnets_needing_igw_route"]
+                    if igw_audit["internet_gateway_needs_vpc_attachment"]:
+                        print(
+                            f"CDK will attach IGW '{igw_audit['internet_gateway_id']}' "
+                            f"to VPC '{vpc_id}' on deploy."
+                        )
+                    if needing:
+                        print(
+                            f"CDK will add default internet routes on deploy for: "
+                            f"{', '.join(n['name'] for n in needing)}"
+                        )
+                    else:
+                        print(
+                            "All audited public subnets already have 0.0.0.0/0 -> IGW routes."
+                        )
+                except ValueError as e:
+                    print(
+                        f"\nFATAL ERROR: Internet Gateway / public route audit failed: {e}\n"
+                    )
+                    raise SystemExit(1) from e
+
+        print("\nName-only existence subnet check complete.\n")
+
+        if full_validation_mode:
+            print(
+                "\n--- Running in Full Subnet Validation Mode (CIDR/AZs provided) ---"
+            )
+            try:
+                validate_subnet_creation_parameters(
+                    vpc_id, all_proposed_subnets_data, existing_aws_subnets
+                )
+                print("\nPre-synth validation successful. Proceeding with CDK synth.\n")
+
+                # Populate context_data for downstream CDK construct creation.
+                # Skip subnets that already exist in AWS (imported in the stack).
+                context_data["public_subnets_to_create"] = []
+                if public_ready_for_full_validation:
+                    for i, name in enumerate(PUBLIC_SUBNETS_TO_USE):
+                        if checked_public_subnets.get(name, {}).get("exists"):
+                            continue
+                        context_data["public_subnets_to_create"].append(
+                            {
+                                "name": name,
+                                "cidr": PUBLIC_SUBNET_CIDR_BLOCKS[i],
+                                "az": PUBLIC_SUBNET_AVAILABILITY_ZONES[i],
+                                "is_public": True,
+                            }
+                        )
+                context_data["private_subnets_to_create"] = []
+                if private_ready_for_full_validation:
+                    for i, name in enumerate(PRIVATE_SUBNETS_TO_USE):
+                        if checked_private_subnets.get(name, {}).get("exists"):
+                            continue
+                        context_data["private_subnets_to_create"].append(
+                            {
+                                "name": name,
+                                "cidr": PRIVATE_SUBNET_CIDR_BLOCKS[i],
+                                "az": PRIVATE_SUBNET_AVAILABILITY_ZONES[i],
+                                "is_public": False,
+                            }
+                        )
+
+            except (ValueError, Exception) as e:
+                print(f"\nFATAL ERROR: Subnet parameter validation failed: {e}\n")
+                raise SystemExit(1)  # Exit if validation fails
+
+    # Example checks and setting context values
+    # IAM Roles
+    role_name = CODEBUILD_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    role_name = ECS_TASK_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    role_name = ECS_TASK_EXECUTION_ROLE_NAME
+    exists, role_arn, _ = check_for_existing_role(role_name)
+    context_data[f"exists:{role_name}"] = exists
+    if exists:
+        context_data[f"arn:{role_name}"] = role_arn
+
+    # S3 Buckets
+    def _record_s3_bucket_context(name: str) -> None:
+        status, _ = resolve_s3_bucket_availability(name)
+        context_data[f"exists:{name}"] = status == "owned"
+        context_data[f"globally_taken:{name}"] = status == "globally_taken"
+
+    bucket_name = S3_LOG_CONFIG_BUCKET_NAME
+    _record_s3_bucket_context(bucket_name)
+
+    output_bucket_name = S3_OUTPUT_BUCKET_NAME
+    _record_s3_bucket_context(output_bucket_name)
+
+    # ECR Repositories
+    for repo_name in (ECR_CDK_REPO_NAME, ECR_PI_REPO_NAME):
+        exists, _ = check_ecr_repo_exists(repo_name)
+        context_data[f"exists:{repo_name}"] = exists
+
+    # CodeBuild Project
+    project_name = CODEBUILD_PROJECT_NAME
+    exists, project_arn, service_role_arn = check_codebuild_project_exists(project_name)
+    context_data[f"exists:{project_name}"] = exists
+    if exists:
+        context_data[f"arn:{project_name}"] = project_arn
+        if service_role_arn:
+            context_data[f"service_role_arn:{project_name}"] = service_role_arn
+
+    # ALB (by name lookup) — skipped when Express Mode will provision its own ALB
+    alb_name = ALB_NAME[-32:] if len(ALB_NAME) > 32 else ALB_NAME
+    if USE_ECS_EXPRESS_MODE == "True":
+        context_data[f"exists:{alb_name}"] = False
+        print(
+            "USE_ECS_EXPRESS_MODE=True: skipping ALB pre-check (Express provisions ALB)."
+        )
+    elif ENABLE_HEADLESS_DEPLOYMENT == "True":
+        context_data[f"exists:{alb_name}"] = False
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: skipping ALB pre-check (no web ingress)."
+        )
+    if ENABLE_HEADLESS_DEPLOYMENT == "True":
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: requires ENABLE_S3_BATCH_ECS_TRIGGER=True "
+            "and USE_ECS_EXPRESS_MODE=False."
+        )
+    elif ENABLE_S3_BATCH_ECS_TRIGGER == "True":
+        print(
+            "ENABLE_S3_BATCH_ECS_TRIGGER=True: requires legacy Fargate (USE_ECS_EXPRESS_MODE=False)."
+        )
+    if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+        print(
+            "ENABLE_PI_AGENT_ECS_SERVICE=True: requires legacy Fargate, Service Connect, "
+            "and PI_ALB_ROUTING (default path=/pi on shared ALB; host mode needs PI_ALB_HOST_HEADER)."
+        )
+    elif ENABLE_HEADLESS_DEPLOYMENT == "True":
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: legacy Fargate task definition + "
+            "S3 batch Lambda only (no ALB pre-check)."
+        )
+    else:
+        exists, alb_object = check_alb_exists(alb_name, region_name=AWS_REGION)
+        context_data[f"exists:{alb_name}"] = exists
+        if exists:
+            print("alb_object:", alb_object)
+            context_data[f"arn:{alb_name}"] = alb_object["LoadBalancerArn"]
+            context_data[f"dns:{alb_name}"] = alb_object["DNSName"]
+            context_data[f"canonical_hosted_zone_id:{alb_name}"] = alb_object[
+                "CanonicalHostedZoneId"
+            ]
+            if alb_object.get("SecurityGroups"):
+                context_data[f"security_group_id:{alb_name}"] = alb_object[
+                    "SecurityGroups"
+                ][0]
+
+    # Cognito (web login only; headless batch mode has no Gradio/ALB ingress)
+    if ENABLE_HEADLESS_DEPLOYMENT != "True":
+        domain_prefix = (COGNITO_USER_POOL_DOMAIN_PREFIX or "").strip().lower()
+        if domain_prefix:
+            availability = resolve_cognito_domain_prefix_availability(
+                domain_prefix, region_name=AWS_REGION
+            )
+            context_data[f"cognito_domain_taken:{domain_prefix}"] = (
+                availability == "taken"
+            )
+
+        user_pool_name = COGNITO_USER_POOL_NAME
+        exists, user_pool_id, _ = check_for_existing_user_pool(user_pool_name)
+        context_data[f"exists:{user_pool_name}"] = exists
+        if exists:
+            context_data[f"id:{user_pool_name}"] = user_pool_id
+
+        # Cognito User Pool Client (by name and pool ID) - requires User Pool ID from check
+        if user_pool_id:
+            user_pool_id_for_client_check = user_pool_id  # context_data.get(f"id:{user_pool_name}") # Use ID from context
+            user_pool_client_name = COGNITO_USER_POOL_CLIENT_NAME
+            if user_pool_id_for_client_check:
+                exists, client_id, _ = check_for_existing_user_pool_client(
+                    user_pool_client_name, user_pool_id_for_client_check
+                )
+                context_data[f"exists:{user_pool_client_name}"] = exists
+                if exists:
+                    context_data[f"id:{user_pool_client_name}"] = client_id
+                else:
+                    print(
+                        f"User pool '{user_pool_name}' exists but app client "
+                        f"'{user_pool_client_name}' does not; CDK will create a new client."
+                    )
+
+        # Secrets Manager Secret (by name)
+        secret_name = COGNITO_USER_POOL_CLIENT_SECRET_NAME
+        exists, secret_response = check_for_secret(secret_name)
+        context_data[f"exists:{secret_name}"] = exists
+        if exists:
+            secret_arn = (
+                secret_response.get("ARN")
+                if isinstance(secret_response, dict)
+                else None
+            )
+            if secret_arn:
+                context_data[f"arn:{secret_name}"] = secret_arn
+                print("Cognito secret ARN recorded for IAM grants.")
+                secret_kms_key_arn = get_secret_kms_key_arn(
+                    secret_name, region_name=AWS_REGION
+                )
+                if secret_kms_key_arn:
+                    context_data[f"kms_key_arn:{secret_name}"] = secret_kms_key_arn
+                    print("Cognito secret KMS key recorded for execution role decrypt.")
+            else:
+                print(
+                    "Warning: Cognito secret exists but ARN was not returned; "
+                    "CDK will use a name-based ARN wildcard in IAM policies."
+                )
+    else:
+        print(
+            "ENABLE_HEADLESS_DEPLOYMENT=True: skipping Cognito user pool and secret pre-checks."
+        )
+
+    # Service Connect client security groups (by name in VPC)
+    if ENABLE_ECS_SERVICE_CONNECT == "True":
+        vpc_id_for_sg = context_data.get("vpc_id")
+        if vpc_id_for_sg:
+            for sg_name in ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES_TO_LOOKUP:
+                exists, sg_id = get_security_group_id_by_name(
+                    sg_name, vpc_id_for_sg, region_name=AWS_REGION
+                )
+                context_data[f"exists:sg:{sg_name}"] = exists
+                if exists:
+                    context_data[f"security_group_id:{sg_name}"] = sg_id
+                    print(f"Service Connect client SG '{sg_name}' -> {sg_id}")
+                else:
+                    print(
+                        f"Warning: Service Connect client SG '{sg_name}' "
+                        f"not found in VPC {vpc_id_for_sg}"
+                    )
+        else:
+            print(
+                "Warning: vpc_id missing from context; cannot resolve Service "
+                "Connect client security group names."
+            )
+
+    # WAF Web ACL (by name and scope)
+    web_acl_name = WEB_ACL_NAME
+    exists, existing_web_acl = check_web_acl_exists(web_acl_name, scope="CLOUDFRONT")
+    context_data[f"exists:{web_acl_name}"] = exists
+    if exists:
+        context_data[f"arn:{web_acl_name}"] = existing_web_acl["ARN"]
+
+    # Write the context data to the file
+    with open(CONTEXT_FILE, "w") as f:
+        json.dump(context_data, f, indent=2)
+
+    print(f"Context data written to {CONTEXT_FILE}")
+
+
+if __name__ == "__main__":
+    print(f"Pre-check context file: {CONTEXT_FILE}")
+    print(
+        "Running AWS pre-check (requires credentials for the target account/region)..."
+    )
+    try:
+        check_and_set_context()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        raise SystemExit(f"Pre-check failed: {exc}") from exc
+    if not os.path.exists(CONTEXT_FILE):
+        raise SystemExit(f"Pre-check finished but {CONTEXT_FILE} was not created.")
+    print(f"Pre-check complete. Context written to {os.path.abspath(CONTEXT_FILE)}")

cdk/config/app_config.env.example

@@ -0,0 +1,26 @@
+# AWS deployment app settings (copy to cdk/config/app_config.env — do not commit secrets).
+# Same variable names as tools/config.py; loaded by ECS from S3 or Express env.
+COGNITO_AUTH=True
+RUN_AWS_FUNCTIONS=True
+RUN_AWS_BEDROCK_MODELS=True
+RUN_LOCAL_MODEL=False
+RUN_GEMINI_MODELS=False
+RUN_AZURE_MODELS=False
+PRIORITISE_SSO_OVER_AWS_ENV_ACCESS_KEYS=True
+DISPLAY_FILE_NAMES_IN_LOGS=False
+SESSION_OUTPUT_FOLDER=True
+SAVE_LOGS_TO_CSV=True
+SAVE_LOGS_TO_DYNAMODB=True
+SHOW_COSTS=True
+S3_LOG_BUCKET=demo-llm-topic-s3-logs
+S3_OUTPUTS_BUCKET=
+S3_OUTPUTS_FOLDER=
+SAVE_OUTPUTS_TO_S3=False
+UPLOAD_USAGE_LOG_TO_S3_OUTPUTS=False
+UPLOAD_PROMPT_RESPONSE_LOG_TO_S3_OUTPUTS=False
+ACCESS_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-access-logs
+FEEDBACK_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-feedback-logs
+USAGE_LOG_DYNAMODB_TABLE_NAME=demo-llm-topic-dynamodb-usage-logs
+LOG_FILE_NAME=log.csv
+USAGE_LOG_FILE_NAME=usage_log.csv
+FEEDBACK_LOG_FILE_NAME=feedback_log.csv

cdk/config/headless_s3_seed/input/config/example_headless_env_file.env

@@ -0,0 +1,13 @@
+# Example job file for headless batch topic modelling.
+# 1. Upload your consultation spreadsheet to s3://<output-bucket>/input/
+# 2. Copy this file, set DIRECT_MODE_INPUT_FILE to that filename, save as my-job.env
+# 3. Upload my-job.env to s3://<output-bucket>/input/config/ to start the ECS task.
+#
+# More DIRECT_MODE_* variables: tools/config.py and cli_topics.py in this repo.
+
+RUN_DIRECT_MODE=1
+DIRECT_MODE_TASK=extract
+DIRECT_MODE_INPUT_FILE=dummy_consultation_response.xlsx
+DIRECT_MODE_TEXT_COLUMN="Response Text"
+SAVE_OUTPUTS_TO_S3=True
+S3_OUTPUTS_FOLDER=output/

cdk/config/lambda/lambda_function.py

@@ -0,0 +1,187 @@
+import os
+import urllib.parse
+
+import boto3
+
+ecs = boto3.client("ecs")
+s3 = boto3.client("s3")
+
+# Move static config to Lambda env vars for easier ops
+BUCKET = os.environ.get("BUCKET", "lambeth-llm-topic-modelling")
+INPUT_PREFIX = os.environ.get("INPUT_PREFIX", "input/")
+ENV_PREFIX = os.environ.get("ENV_PREFIX", f"{INPUT_PREFIX}config/")
+GENERAL_ENV_PREFIX = os.environ.get("GENERAL_ENV_PREFIX", "general-config/")
+ENV_SUFFIX = os.environ.get("ENV_SUFFIX", ".env")
+DEFAULT_PARAMS_KEY = os.environ.get(
+    "DEFAULT_PARAMS_KEY", f"{GENERAL_ENV_PREFIX}app_defaults{ENV_SUFFIX}"
+)
+CLUSTER = os.environ.get("ECS_CLUSTER", "analytics_fargate_cluster")
+TASK_DEF = os.environ.get("ECS_TASK_DEF", "llm_topic_modelling_fargate_def:5")
+SUBNETS = os.environ.get(
+    "SUBNETS", "subnet-083650a35f93a0ee5,subnet-0a41ba70470cabab8"
+).split(",")
+SECURITY_GROUPS = os.environ.get("SECURITY_GROUPS", "sg-051effb4c5e752df1").split(",")
+ECS_ASSIGN_PUBLIC_IP = os.environ.get("ECS_ASSIGN_PUBLIC_IP", "DISABLED").upper()
+DEFAULT_INPUT_S3_URI = os.environ.get(
+    "DEFAULT_INPUT_S3_URI",
+    f"s3://{BUCKET}/{INPUT_PREFIX}dummy_consultation_response.xlsx",
+)
+DEFAULT_TASK_TYPE = os.environ.get("DEFAULT_TASK_TYPE", "extract")
+CONTAINER_NAME = os.environ.get("CONTAINER_NAME", "llm_topic_modelling_container")
+
+
+def _key_matches(key: str) -> bool:
+    return key.startswith(ENV_PREFIX) and key.endswith(ENV_SUFFIX)
+
+
+def _derive_runtime_params_from_key(key: str) -> dict:
+    """Optional convention: decide task type from file name."""
+    basename = key.split("/")[-1].lower()
+    if "train" in basename:
+        task_type = "train"
+    elif "infer" in basename or "staging" in basename:
+        task_type = "infer"
+    else:
+        task_type = DEFAULT_TASK_TYPE
+
+    return {
+        "DIRECT_MODE_TASK": task_type,
+        "DIRECT_MODE_INPUT_FILE": DEFAULT_INPUT_S3_URI,
+    }
+
+
+def _parse_dotenv(dotenv_bytes: bytes, bucket: str, input_prefix: str) -> dict:
+    """
+    Parse a basic .env and prepend S3 paths to specific keys if they have values.
+    """
+    env = {}
+    text = dotenv_bytes.decode("utf-8", errors="replace")
+
+    # 1. Parse the file (Existing Logic)
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            value = value[1:-1]
+        env[key] = value
+
+    # 2. Apply S3 Prefix Logic (New Logic)
+    # We define the base S3 path string using the provided arguments
+    s3_base = f"s3://{bucket}/{input_prefix}"
+
+    # List of keys that need modification
+    keys_to_modify = ["DIRECT_MODE_INPUT_FILE", "DIRECT_MODE_CANDIDATE_TOPICS"]
+
+    for key in keys_to_modify:
+        # env.get(key) returns the value.
+        # The 'if' check ensures the key exists AND is not an empty string.
+        if env.get(key):
+            env[key] = s3_base + env[key]
+
+    return env
+
+
+def _build_environment_array(*env_dicts):
+    """Merge dictionaries left→right and produce ECS environment array format."""
+    merged = {}
+    for d in env_dicts:
+        merged.update(d or {})
+    # ECS override format: [{"name": "...","value":"..."}]
+    return [{"name": k, "value": v} for k, v in merged.items()]
+
+
+def lambda_handler(event, context):
+    runs = []
+
+    # Parse default env file with default config
+    # Fetch the default .env file content from S3
+    default_obj = s3.get_object(Bucket=BUCKET, Key=DEFAULT_PARAMS_KEY)
+    default_dotenv_bytes = default_obj["Body"].read()
+
+    # Parse .env → dict of env vars
+    default_file_env = _parse_dotenv(default_dotenv_bytes, BUCKET, INPUT_PREFIX)
+
+    for record in event.get("Records", []):
+
+        # Parse env file from user
+        s3rec = record.get("s3", {})
+        bucket = s3rec.get("bucket", {}).get("name")
+        raw_key = s3rec.get("object", {}).get("key")
+        if not bucket or not raw_key:
+            print(f"Object in bucket {bucket} and key {raw_key} not found, exiting.")
+            continue
+
+        key = urllib.parse.unquote_plus(raw_key)
+
+        # combined_key = ENV_PREFIX + key
+        combined_key = key
+
+        print("combined_key:", combined_key)
+
+        # Only process the intended prefix/suffix
+        if not _key_matches(combined_key):
+            print(f"Key does not match: {combined_key}, exiting")
+            continue
+
+        # Fetch the .env file content from S3
+        obj = s3.get_object(Bucket=bucket, Key=combined_key)
+        dotenv_bytes = obj["Body"].read()
+
+        # Parse .env → dict of env vars
+        file_env = _parse_dotenv(dotenv_bytes, BUCKET, INPUT_PREFIX)
+
+        # Optionally derive run-time params from naming
+        # run_params = _derive_runtime_params_from_key(key)
+
+        # Merge: file env (dominant), overwrites default values.
+        environment = _build_environment_array(file_env, default_file_env)
+
+        print("Combined environment variables:", environment)
+
+        # Execute ECS Fargate task with fully dynamic environment overrides
+        response = ecs.run_task(
+            cluster=CLUSTER,
+            launchType="FARGATE",
+            taskDefinition=TASK_DEF,
+            networkConfiguration={
+                "awsvpcConfiguration": {
+                    "subnets": SUBNETS,
+                    "securityGroups": SECURITY_GROUPS,
+                    "assignPublicIp": (
+                        ECS_ASSIGN_PUBLIC_IP
+                        if ECS_ASSIGN_PUBLIC_IP in ("ENABLED", "DISABLED")
+                        else "DISABLED"
+                    ),
+                }
+            },
+            overrides={
+                "containerOverrides": [
+                    {
+                        "name": CONTAINER_NAME,
+                        "environment": environment,
+                    }
+                ]
+            },
+        )
+
+        runs.append(
+            {
+                "bucket": bucket,
+                "key": key,
+                "taskArns": [t["taskArn"] for t in response.get("tasks", [])],
+                "failures": response.get("failures", []),
+                "envCount": len(environment),
+            }
+        )
+
+    return {"runs": runs}

cdk/docs/express_pi_service_connect_spike.md

@@ -0,0 +1,71 @@
+# Phase 0: Express Service Connect validation (dev account)
+
+Service Connect for Express is applied in `post_cdk_build_quickstart.py` (not during
+`cdk deploy`). Express primary containers do not define named `portMappings` at create
+time, so the post-deploy step registers a task-definition revision with
+`port-{port}` and then calls `ecs:UpdateService` with `serviceConnectConfiguration`.
+Use this checklist to confirm behaviour in a dev account before relying on Pi Express demos.
+
+## Prerequisites
+
+- Main Express stack deployed (`USE_ECS_EXPRESS_MODE=True`).
+- Optional: deploy with `ENABLE_PI_AGENT_EXPRESS_SERVICE=True` and run
+  `python post_cdk_build_quickstart.py` (Service Connect is configured there).
+
+## Manual validation (without Pi CDK flag)
+
+1. Note cluster name, main Express **service name**, and task security group from stack outputs.
+2. Ensure the cluster has a default Cloud Map namespace (CDK creates one when Pi Express is enabled).
+3. Update the main Express service (server):
+
+```bash
+aws ecs update-service \
+  --cluster <CLUSTER_NAME> \
+  --service <ECS_EXPRESS_SERVICE_NAME> \
+  --force-new-deployment \
+  --service-connect-configuration '{
+    "enabled": true,
+    "namespace": "<ECS_SERVICE_CONNECT_NAMESPACE>",
+    "services": [{
+      "portName": "port-7860",
+      "discoveryName": "summarisation",
+      "clientAliases": [{"port": 7860, "dnsName": "summarisation"}]
+    }]
+  }'
+```
+
+4. Deploy a second Express service (Pi image, port **7862**) or use CDK Pi Express.
+5. Update the Pi Express service (client only):
+
+```bash
+aws ecs update-service \
+  --cluster <CLUSTER_NAME> \
+  --service <ECS_PI_EXPRESS_SERVICE_NAME> \
+  --force-new-deployment \
+  --service-connect-configuration '{
+    "enabled": true,
+    "namespace": "<ECS_SERVICE_CONNECT_NAMESPACE>"
+  }'
+```
+
+6. Exec into a Pi task (ECS Exec enabled on the service):
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" http://summarisation:7860/
+```
+
+Expect HTTP **200** (or Gradio redirect) without Cognito.
+
+7. Optional: run a minimal `gradio_client` predict against `/doc_redact` from the Pi task.
+
+## Exit criteria
+
+- Service Connect DNS `summarisation` resolves inside the Pi task network namespace.
+- Gradio responds on port 7860 without ALB Cognito.
+- If `update-service` fails or `portName` is rejected, stop and use legacy Fargate Pi +
+  `ENABLE_ECS_SERVICE_CONNECT` until AWS/CDK support is confirmed (plan Phase 2 hybrid).
+
+## CDK deploy path
+
+With `ENABLE_PI_AGENT_EXPRESS_SERVICE=True`, run `post_cdk_build_quickstart.py` after
+`cdk deploy`. Check its output for Service Connect / task-definition errors.

cdk/example_headless_env_file.env

@@ -0,0 +1 @@
+DIRECT_MODE_INPUT_FILE=example_of_emails_sent_to_a_professor_before_applying.pdf

cdk/lambda_dynamo_logs_export/lambda_function.py

@@ -0,0 +1,316 @@
+"""
+Lambda handler to export DynamoDB usage log table to CSV and upload to S3.
+
+All inputs are read from environment variables (no argparse).
+Intended to run as an AWS Lambda function; can also be invoked locally
+by setting env vars and calling lambda_handler({}, None).
+
+Environment variables (same semantics as load_dynamo_logs.py CLI):
+  DYNAMODB_TABLE_NAME       - DynamoDB table name (default: summarisation_usage)
+  AWS_REGION                - AWS region (optional; if unset, uses AWS_DEFAULT_REGION,
+                              then region from Lambda context ARN, then eu-west-2)
+  OUTPUT_FOLDER             - Local output directory, e.g. /tmp (optional)
+  OUTPUT_FILENAME           - Local output file name (default: dynamodb_logs_export.csv)
+  OUTPUT                    - Full local output path (overrides folder + filename if set).
+                              In Lambda only /tmp is writable; relative paths are auto-resolved to /tmp.
+  FROM_DATE                 - Only include entries on/after this date YYYY-MM-DD (optional)
+  TO_DATE                   - Only include entries on/before this date YYYY-MM-DD (optional)
+  DATE_ATTRIBUTE            - Attribute name for date filtering (default: timestamp)
+  S3_OUTPUT_BUCKET          - S3 bucket for the output CSV (required for upload)
+  S3_OUTPUT_KEY             - S3 object key/path for the output CSV (required for upload)
+"""
+
+import csv
+import datetime
+import os
+from decimal import Decimal
+from io import StringIO
+
+import boto3
+
+
+def _get_region_from_context(context):
+    """Extract region from Lambda context invoked_function_arn (arn:aws:lambda:REGION:ACCOUNT:function:NAME)."""
+    if context is None:
+        return None
+    arn = getattr(context, "invoked_function_arn", None)
+    if not arn or not isinstance(arn, str):
+        return None
+    parts = arn.split(":")
+    if len(parts) >= 4:
+        return parts[3]  # region is 4th segment
+    return None
+
+
+def get_config_from_env(context=None):
+    """Read all settings from environment variables (same inputs as load_dynamo_logs.py).
+    When running in Lambda, context can be passed to derive region from the function ARN if env is not set.
+    """
+    today = datetime.datetime.now().date()
+    one_year_ago = today - datetime.timedelta(days=365)
+
+    table_name = os.environ.get("DYNAMODB_TABLE_NAME") or os.environ.get(
+        "USAGE_LOG_DYNAMODB_TABLE_NAME", "summarisation_usage"
+    )
+    region = (
+        os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or ""
+    ).strip()
+    output = os.environ.get("OUTPUT")
+    output_folder = os.environ.get("OUTPUT_FOLDER", "output/")
+    output_filename = os.environ.get("OUTPUT_FILENAME", "dynamodb_logs_export.csv")
+    from_date_str = os.environ.get("FROM_DATE")
+    to_date_str = os.environ.get("TO_DATE")
+    date_attribute = os.environ.get("DATE_ATTRIBUTE", "timestamp")
+    s3_output_bucket = os.environ.get("S3_OUTPUT_BUCKET")
+    s3_output_key = os.environ.get("S3_OUTPUT_KEY")
+
+    if output:
+        local_output_path = output
+    else:
+        folder = output_folder.rstrip("/").rstrip("\\")
+        local_output_path = os.path.join(folder, output_filename)
+
+    # In AWS Lambda only /tmp is writable; resolve relative paths to /tmp to avoid read-only FS errors
+    if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
+        resolved = os.path.abspath(local_output_path)
+        if not resolved.startswith("/tmp"):
+            local_output_path = os.path.join(
+                "/tmp", os.path.basename(local_output_path)
+            )
+
+    # Region: env (AWS_REGION / AWS_DEFAULT_REGION) → Lambda context ARN → hardcoded fallback
+    if not region and context is not None:
+        region = _get_region_from_context(context) or ""
+    if not region:
+        region = "eu-west-2"
+
+    from_date = None
+    to_date = None
+    if from_date_str:
+        from_date = datetime.datetime.strptime(from_date_str, "%Y-%m-%d").date()
+    if to_date_str:
+        to_date = datetime.datetime.strptime(to_date_str, "%Y-%m-%d").date()
+    if from_date is None and to_date is None:
+        from_date = one_year_ago
+        to_date = today
+    elif from_date is None:
+        from_date = one_year_ago
+    elif to_date is None:
+        to_date = today
+
+    return {
+        "table_name": table_name,
+        "region": region,
+        "local_output_path": local_output_path,
+        "from_date": from_date,
+        "to_date": to_date,
+        "date_attribute": date_attribute,
+        "s3_output_bucket": s3_output_bucket,
+        "s3_output_key": s3_output_key,
+    }
+
+
+def convert_types(item):
+    new_item = {}
+    for key, value in item.items():
+        if isinstance(value, Decimal):
+            new_item[key] = int(value) if value % 1 == 0 else float(value)
+        elif isinstance(value, str):
+            try:
+                dt_obj = datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+                new_item[key] = dt_obj.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+            except (ValueError, TypeError):
+                new_item[key] = value
+        else:
+            new_item[key] = value
+    return new_item
+
+
+def _parse_item_date(value):
+    """Parse a DynamoDB attribute value to datetime for comparison. Returns None if unparseable."""
+    if value is None:
+        return None
+    if isinstance(value, Decimal):
+        try:
+            return datetime.datetime.utcfromtimestamp(float(value))
+        except (ValueError, OSError):
+            return None
+    if isinstance(value, (int, float)):
+        try:
+            return datetime.datetime.utcfromtimestamp(float(value))
+        except (ValueError, OSError):
+            return None
+    if isinstance(value, str):
+        for fmt in (
+            "%Y-%m-%d %H:%M:%S.%f",
+            "%Y-%m-%d %H:%M:%S",
+            "%Y-%m-%d",
+            "%Y-%m-%dT%H:%M:%S",
+        ):
+            try:
+                return datetime.datetime.strptime(value, fmt)
+            except (ValueError, TypeError):
+                continue
+        try:
+            return datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            pass
+    return None
+
+
+def filter_items_by_date(items, from_date, to_date, date_attribute: str):
+    """Return items whose date attribute falls within [from_date, to_date] (inclusive)."""
+    if from_date is None and to_date is None:
+        return items
+    start = datetime.datetime.combine(from_date, datetime.time.min)
+    end = datetime.datetime.combine(to_date, datetime.time.max)
+    filtered = []
+    for item in items:
+        raw = item.get(date_attribute)
+        dt = _parse_item_date(raw)
+        if dt is None:
+            continue
+        if dt.tzinfo:
+            dt = dt.replace(tzinfo=None)
+        if start <= dt <= end:
+            filtered.append(item)
+    return filtered
+
+
+def scan_table(table):
+    """Paginated scan of DynamoDB table."""
+    items = []
+    response = table.scan()
+    items.extend(response["Items"])
+    while "LastEvaluatedKey" in response:
+        response = table.scan(ExclusiveStartKey=response["LastEvaluatedKey"])
+        items.extend(response["Items"])
+    return items
+
+
+def export_to_csv_buffer(items, fields_to_drop=None):
+    """
+    Write items to a CSV in memory; return (csv_string, fieldnames).
+    Use for uploading to S3 without writing to disk.
+    """
+    if not items:
+        return "", []
+
+    drop_set = set(fields_to_drop or [])
+    all_keys = set()
+    for item in items:
+        all_keys.update(item.keys())
+    fieldnames = sorted(list(all_keys - drop_set))
+
+    buf = StringIO()
+    writer = csv.DictWriter(
+        buf, fieldnames=fieldnames, extrasaction="ignore", restval=""
+    )
+    writer.writeheader()
+    for item in items:
+        writer.writerow(convert_types(item))
+    return buf.getvalue(), fieldnames
+
+
+def export_to_csv_file(items, output_path, fields_to_drop=None):
+    """Write items to a CSV file (for optional /tmp or local path)."""
+    csv_string, _ = export_to_csv_buffer(items, fields_to_drop)
+    if not csv_string:
+        return
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)) or ".", exist_ok=True)
+    with open(output_path, "w", newline="", encoding="utf-8-sig") as f:
+        f.write(csv_string)
+
+
+def run_export(config):
+    """
+    Run the full export: scan DynamoDB, filter by date, write CSV (buffer and/or file), upload to S3.
+    """
+    table_name = config["table_name"]
+    region = config["region"]
+    local_output_path = config["local_output_path"]
+    from_date = config["from_date"]
+    to_date = config["to_date"]
+    date_attribute = config["date_attribute"]
+    s3_output_bucket = config["s3_output_bucket"]
+    s3_output_key = config["s3_output_key"]
+
+    if from_date > to_date:
+        raise ValueError("FROM_DATE must be on or before TO_DATE")
+
+    dynamodb = boto3.resource("dynamodb", region_name=region or None)
+    table = dynamodb.Table(table_name)
+
+    items = scan_table(table)
+    items = filter_items_by_date(items, from_date, to_date, date_attribute)
+
+    csv_string, fieldnames = export_to_csv_buffer(items, fields_to_drop=[])
+    result = {
+        "item_count": len(items),
+        "from_date": str(from_date),
+        "to_date": str(to_date),
+        "columns": fieldnames,
+    }
+
+    if csv_string:
+        try:
+            export_to_csv_file(items, local_output_path, fields_to_drop=[])
+            result["local_path"] = local_output_path
+        except Exception as e:
+            result["local_write_error"] = str(e)
+
+        if s3_output_bucket and s3_output_key:
+            s3 = boto3.client("s3", region_name=region or None)
+            s3.put_object(
+                Bucket=s3_output_bucket,
+                Key=s3_output_key,
+                Body=csv_string.encode("utf-8-sig"),
+                ContentType="text/csv; charset=utf-8",
+            )
+            result["s3_uri"] = f"s3://{s3_output_bucket}/{s3_output_key}"
+        elif s3_output_bucket or s3_output_key:
+            result["s3_skip_reason"] = (
+                "Both S3_OUTPUT_BUCKET and S3_OUTPUT_KEY must be set"
+            )
+
+    return result
+
+
+def lambda_handler(event, context):
+    """
+    AWS Lambda entrypoint. Config is read from environment variables.
+
+    Event is not required for config; it can be used to override env vars
+    (e.g. pass table_name, from_date, to_date, s3_output_bucket, s3_output_key).
+    """
+    config = get_config_from_env(context=context)
+
+    if isinstance(event, dict):
+        if event.get("table_name"):
+            config["table_name"] = event["table_name"]
+        if event.get("region"):
+            config["region"] = event["region"]
+        if event.get("from_date"):
+            config["from_date"] = datetime.datetime.strptime(
+                event["from_date"], "%Y-%m-%d"
+            ).date()
+        if event.get("to_date"):
+            config["to_date"] = datetime.datetime.strptime(
+                event["to_date"], "%Y-%m-%d"
+            ).date()
+        if event.get("date_attribute"):
+            config["date_attribute"] = event["date_attribute"]
+        if event.get("s3_output_bucket"):
+            config["s3_output_bucket"] = event["s3_output_bucket"]
+        if event.get("s3_output_key"):
+            config["s3_output_key"] = event["s3_output_key"]
+
+    result = run_export(config)
+    return {"statusCode": 200, "body": result}
+
+
+if __name__ == "__main__":
+    import json
+
+    result = lambda_handler({}, None)
+    print(json.dumps(result, indent=2))

cdk/lambda_elbv2_listener_rule_upsert/lambda_function.py

@@ -0,0 +1,187 @@
+"""
+CloudFormation custom resource: create or update an ALB listener rule (upsert by priority).
+
+If a rule already exists at the requested priority with matching conditions, it is
+modified in place. This supports stack retries after partial deploys left orphaned rules.
+If priority is taken by a rule with different conditions, the operation fails with a
+clear error so operators can choose another PI_ALB_LISTENER_RULE_PRIORITY.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+LOGGER = logging.getLogger()
+LOGGER.setLevel(logging.INFO)
+
+elbv2 = boto3.client("elbv2")
+
+_DELETE_NOT_FOUND = frozenset(
+    {
+        "RuleNotFound",
+        "ResourceNotFound",
+        "ValidationError",
+    }
+)
+# CloudFormation custom-resource properties are strings; ELBv2 expects typed fields.
+_ELBV2_INT_KEYS = frozenset(
+    {
+        "Order",
+        "Priority",
+        "SessionTimeout",
+        "DurationSeconds",
+        "SessionCookieName",
+    }
+)
+_ELBV2_BOOL_KEYS = frozenset({"Enabled"})
+
+
+def _parse_json(value: Any) -> Any:
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+def _coerce_elbv2_api_value(key: str, value: Any) -> Any:
+    """Coerce CloudFormation string properties to types boto3 elbv2 expects."""
+    if isinstance(value, dict):
+        return {k: _coerce_elbv2_api_value(k, v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_coerce_elbv2_api_value(key, item) for item in value]
+    if isinstance(value, str):
+        if key in _ELBV2_INT_KEYS:
+            try:
+                return int(value)
+            except ValueError:
+                return value
+        if key in _ELBV2_BOOL_KEYS:
+            lowered = value.lower()
+            if lowered == "true":
+                return True
+            if lowered == "false":
+                return False
+    return value
+
+
+def _normalize_listener_rule_payload(
+    conditions: list[dict[str, Any]],
+    actions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    return (
+        [_coerce_elbv2_api_value("", c) for c in conditions],
+        [_coerce_elbv2_api_value("", a) for a in actions],
+    )
+
+
+def _condition_values(condition: dict[str, Any]) -> list[str]:
+    field = condition.get("Field")
+    if field == "path-pattern":
+        cfg = condition.get("PathPatternConfig") or {}
+        return sorted(cfg.get("Values") or condition.get("Values") or [])
+    if field == "host-header":
+        cfg = condition.get("HostHeaderConfig") or {}
+        return sorted(cfg.get("Values") or condition.get("Values") or [])
+    return sorted(condition.get("Values") or [])
+
+
+def _conditions_match(
+    rule_conditions: list[dict[str, Any]], expected: list[dict[str, Any]]
+) -> bool:
+    if len(rule_conditions) != len(expected):
+        return False
+    for exp in expected:
+        exp_field = exp.get("Field")
+        exp_vals = _condition_values(exp)
+        if not any(
+            rc.get("Field") == exp_field and _condition_values(rc) == exp_vals
+            for rc in rule_conditions
+        ):
+            return False
+    return True
+
+
+def _rule_at_priority(
+    rules: list[dict[str, Any]], priority: int
+) -> dict[str, Any] | None:
+    target = str(priority)
+    for rule in rules:
+        if rule.get("Priority") == target:
+            return rule
+    return None
+
+
+def _upsert_rule(
+    *,
+    listener_arn: str,
+    priority: int,
+    conditions: list[dict[str, Any]],
+    actions: list[dict[str, Any]],
+) -> str:
+    described = elbv2.describe_rules(ListenerArn=listener_arn)
+    existing = _rule_at_priority(described.get("Rules", []), priority)
+    if existing:
+        if _conditions_match(existing.get("Conditions", []), conditions):
+            rule_arn = existing["RuleArn"]
+            LOGGER.info(
+                "Modifying existing listener rule %s at priority %s", rule_arn, priority
+            )
+            elbv2.modify_rule(RuleArn=rule_arn, Conditions=conditions, Actions=actions)
+            return rule_arn
+        raise RuntimeError(
+            f"Listener rule priority {priority} is already in use by {existing['RuleArn']} "
+            "with different conditions. Delete that rule in the ELB console or set "
+            "PI_ALB_LISTENER_RULE_PRIORITY to a free value, then redeploy."
+        )
+    LOGGER.info("Creating listener rule at priority %s on %s", priority, listener_arn)
+    created = elbv2.create_rule(
+        ListenerArn=listener_arn,
+        Priority=priority,
+        Conditions=conditions,
+        Actions=actions,
+    )
+    return created["Rules"][0]["RuleArn"]
+
+
+def _delete_rule(rule_arn: str) -> None:
+    if not rule_arn:
+        return
+    try:
+        elbv2.delete_rule(RuleArn=rule_arn)
+    except ClientError as exc:
+        code = exc.response.get("Error", {}).get("Code", "")
+        if code in _DELETE_NOT_FOUND:
+            LOGGER.info("Rule %s already deleted (%s)", rule_arn, code)
+            return
+        raise
+
+
+def handler(event, context):
+    request_type = event["RequestType"]
+    props = event["ResourceProperties"]
+    listener_arn = props["ListenerArn"]
+    priority = int(props["Priority"])
+    conditions, actions = _normalize_listener_rule_payload(
+        _parse_json(props["Conditions"]),
+        _parse_json(props["Actions"]),
+    )
+
+    if request_type == "Delete":
+        _delete_rule(event.get("PhysicalResourceId", ""))
+        return {"PhysicalResourceId": event.get("PhysicalResourceId", "deleted")}
+
+    rule_arn = _upsert_rule(
+        listener_arn=listener_arn,
+        priority=priority,
+        conditions=conditions,
+        actions=actions,
+    )
+    if request_type == "Update":
+        prior_arn = event.get("PhysicalResourceId", "")
+        if prior_arn and prior_arn != rule_arn:
+            _delete_rule(prior_arn)
+    return {"PhysicalResourceId": rule_arn}

cdk/post_cdk_build_quickstart.py

@@ -0,0 +1,195 @@
+import os
+import time
+
+from cdk_config import (
+    AWS_REGION,
+    CDK_PREFIX,
+    CLUSTER_NAME,
+    CODEBUILD_PI_PROJECT_NAME,
+    CODEBUILD_PROJECT_NAME,
+    COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+    ECS_EXPRESS_COGNITO_REDIRECT_BASE,
+    ECS_EXPRESS_SC_PORT_NAME,
+    ECS_EXPRESS_SERVICE_NAME,
+    ECS_LOG_GROUP_NAME,
+    ECS_PI_EXPRESS_SERVICE_NAME,
+    ECS_PI_SERVICE_NAME,
+    ECS_SERVICE_CONNECT_DISCOVERY_NAME,
+    ECS_SERVICE_CONNECT_NAMESPACE,
+    ECS_SERVICE_NAME,
+    ENABLE_HEADLESS_DEPLOYMENT,
+    ENABLE_PI_AGENT_ECS_SERVICE,
+    ENABLE_PI_AGENT_EXPRESS_SERVICE,
+    GITHUB_REPO_BRANCH,
+    GITHUB_REPO_NAME,
+    GITHUB_REPO_USERNAME,
+    GRADIO_SERVER_PORT,
+    PI_AGENT_ENV_S3_KEY,
+    S3_BATCH_ENV_PREFIX,
+    S3_BATCH_INPUT_PREFIX,
+    S3_BATCH_LAMBDA_FUNCTION_NAME,
+    S3_LOG_CONFIG_BUCKET_NAME,
+    S3_OUTPUT_BUCKET_NAME,
+    USE_ECS_EXPRESS_MODE,
+)
+from cdk_functions import create_basic_config_env, ensure_codebuild_public_github_source
+
+# boto3-only module (does not import aws-cdk / Node.js)
+from cdk_post_deploy import (
+    apply_cognito_secret_fixup_from_stack,
+    configure_express_pi_service_connect,
+    print_headless_deployment_next_steps,
+    seed_headless_batch_s3_layout,
+    start_codebuild_build,
+    start_ecs_task,
+    start_express_gateway_service,
+    upload_file_to_s3,
+)
+from tqdm import tqdm
+
+# Create basic app_config.env file that user can use to run the app later. Input is the folder it is saved into.
+create_basic_config_env(
+    "config",
+    headless=ENABLE_HEADLESS_DEPLOYMENT == "True",
+    pi_express_backend=ENABLE_PI_AGENT_EXPRESS_SERVICE == "True",
+)
+
+# Ensure CodeBuild clones the public GitHub repo (not CodeConnections/OAuth).
+ensure_codebuild_public_github_source(
+    CODEBUILD_PROJECT_NAME,
+    GITHUB_REPO_USERNAME,
+    GITHUB_REPO_NAME,
+    GITHUB_REPO_BRANCH,
+    aws_region=AWS_REGION,
+)
+
+# Start CodeBuild for the main app image
+print("Starting main app CodeBuild project.")
+start_codebuild_build(project_name=CODEBUILD_PROJECT_NAME)
+
+_enable_pi_image_build = (
+    ENABLE_PI_AGENT_ECS_SERVICE == "True" or ENABLE_PI_AGENT_EXPRESS_SERVICE == "True"
+)
+if _enable_pi_image_build:
+    ensure_codebuild_public_github_source(
+        CODEBUILD_PI_PROJECT_NAME,
+        GITHUB_REPO_USERNAME,
+        GITHUB_REPO_NAME,
+        GITHUB_REPO_BRANCH,
+        aws_region=AWS_REGION,
+    )
+    print("Starting Pi agent CodeBuild project.")
+    start_codebuild_build(project_name=CODEBUILD_PI_PROJECT_NAME)
+
+# Upload app_config.env file to S3 bucket
+upload_file_to_s3(
+    local_file_paths="config/app_config.env",
+    s3_key="",
+    s3_bucket=S3_LOG_CONFIG_BUCKET_NAME,
+)
+
+if _enable_pi_image_build:
+    pi_env_local = os.path.join("config", "pi_agent.env")
+    if os.path.isfile(pi_env_local):
+        print(
+            f"Uploading {pi_env_local} to s3://{S3_LOG_CONFIG_BUCKET_NAME}/{PI_AGENT_ENV_S3_KEY}"
+        )
+        upload_file_to_s3(
+            local_file_paths=pi_env_local,
+            s3_key="",
+            s3_bucket=S3_LOG_CONFIG_BUCKET_NAME,
+        )
+    else:
+        print(
+            f"Skipping Pi env upload: {pi_env_local} not found. "
+            f"Create it (from config/pi_agent.env.example) and upload to "
+            f"s3://{S3_LOG_CONFIG_BUCKET_NAME}/{PI_AGENT_ENV_S3_KEY} before scaling the Pi service."
+        )
+
+total_seconds = 480  # 8 minutes
+update_interval = 1  # Update every second
+
+print("Waiting 8 minutes for CodeBuild container image(s) to build.")
+
+# tqdm iterates over a range, and you perform a small sleep in each iteration
+for i in tqdm(range(total_seconds), desc="Building container"):
+    time.sleep(update_interval)
+
+# Scale main ECS service to one task (skipped for headless batch-only deployments)
+if ENABLE_HEADLESS_DEPLOYMENT != "True":
+    if USE_ECS_EXPRESS_MODE == "True":
+        print(f"Starting Express ECS service {ECS_EXPRESS_SERVICE_NAME}")
+        start_express_gateway_service(
+            cluster_name=CLUSTER_NAME, service_name=ECS_EXPRESS_SERVICE_NAME
+        )
+        if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+            print(
+                "Configuring Service Connect for main Express (server) and "
+                "Pi Express (client)."
+            )
+            try:
+                configure_express_pi_service_connect(
+                    cluster_name=CLUSTER_NAME,
+                    main_service_name=ECS_EXPRESS_SERVICE_NAME,
+                    pi_service_name=ECS_PI_EXPRESS_SERVICE_NAME,
+                    namespace=ECS_SERVICE_CONNECT_NAMESPACE,
+                    main_port_name=ECS_EXPRESS_SC_PORT_NAME,
+                    discovery_name=ECS_SERVICE_CONNECT_DISCOVERY_NAME,
+                    main_port=int(GRADIO_SERVER_PORT),
+                )
+            except Exception as exc:
+                print("Warning: could not configure Express Service Connect: " f"{exc}")
+        print("Syncing Cognito app client secret for in-app authentication.")
+        apply_cognito_secret_fixup_from_stack(
+            stack_name="SummarisationStack",
+            secret_name=COGNITO_USER_POOL_CLIENT_SECRET_NAME,
+            cluster_name=CLUSTER_NAME,
+            main_service_name=ECS_EXPRESS_SERVICE_NAME,
+            recycle_tasks=False,
+        )
+    else:
+        print(f"Starting ECS service {ECS_SERVICE_NAME}")
+        start_ecs_task(cluster_name=CLUSTER_NAME, service_name=ECS_SERVICE_NAME)
+else:
+    print(
+        "Headless deployment: skipping always-on ECS service start "
+        "(tasks are started by the S3 batch Lambda)."
+    )
+    seed_headless_batch_s3_layout(
+        S3_OUTPUT_BUCKET_NAME,
+        input_prefix=S3_BATCH_INPUT_PREFIX,
+        env_prefix=S3_BATCH_ENV_PREFIX,
+        example_env_local_path=os.path.join("config", "example_headless_env_file.env"),
+    )
+    print_headless_deployment_next_steps(
+        {
+            "AWS_REGION": AWS_REGION,
+            "S3_OUTPUT_BUCKET_NAME": S3_OUTPUT_BUCKET_NAME,
+            "S3_BATCH_INPUT_PREFIX": S3_BATCH_INPUT_PREFIX,
+            "S3_BATCH_ENV_PREFIX": S3_BATCH_ENV_PREFIX,
+            "ECS_LOG_GROUP_NAME": ECS_LOG_GROUP_NAME,
+            "S3_BATCH_LAMBDA_FUNCTION_NAME": S3_BATCH_LAMBDA_FUNCTION_NAME,
+            "CDK_PREFIX": CDK_PREFIX,
+        }
+    )
+
+if ENABLE_PI_AGENT_ECS_SERVICE == "True":
+    print(f"Starting Pi agent ECS service {ECS_PI_SERVICE_NAME}")
+    start_ecs_task(cluster_name=CLUSTER_NAME, service_name=ECS_PI_SERVICE_NAME)
+
+if ENABLE_PI_AGENT_EXPRESS_SERVICE == "True":
+    print(f"Starting Pi Express ECS service {ECS_PI_EXPRESS_SERVICE_NAME}")
+    start_express_gateway_service(
+        cluster_name=CLUSTER_NAME, service_name=ECS_PI_EXPRESS_SERVICE_NAME
+    )
+
+if USE_ECS_EXPRESS_MODE == "True" and ENABLE_HEADLESS_DEPLOYMENT != "True":
+    from cdk_post_deploy import print_express_mode_next_steps
+
+    print_express_mode_next_steps(
+        {
+            "AWS_REGION": AWS_REGION,
+            "ECS_EXPRESS_COGNITO_REDIRECT_BASE": ECS_EXPRESS_COGNITO_REDIRECT_BASE,
+            "ENABLE_PI_AGENT_EXPRESS_SERVICE": ENABLE_PI_AGENT_EXPRESS_SERVICE,
+        }
+    )

cdk/requirements.txt

@@ -0,0 +1,6 @@
+aws-cdk-lib==2.257.0
+aws-cdk.aws-servicecatalogappregistry-alpha~=2.257.0a0
+boto3
+pandas
+nodejs
+python-dotenv

cdk/test/test_cdk_install.py

@@ -0,0 +1,1010 @@
+"""Unit tests for cdk_install.py (no live AWS or cdk deploy)."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+import cdk_install as inst
+
+
+def _demo_answers() -> inst.InstallAnswers:
+    return inst.InstallAnswers(
+        profile="demo",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Test-Summarisation-",
+        cognito_domain_prefix="test-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        public_subnet_mode="auto",
+        private_subnet_mode="auto",
+    )
+
+
+def _production_answers() -> inst.InstallAnswers:
+    a = _demo_answers()
+    a.profile = "production"
+    a.acm_cert_arn = "arn:aws:acm:eu-west-2:123:certificate/abc"
+    a.ssl_domain = "summarisation.example.com"
+    a.cloudfront_geo = "GB"
+    return a
+
+
+def _headless_answers() -> inst.InstallAnswers:
+    return inst.InstallAnswers(
+        profile="headless",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Headless-Summarisation-",
+        cognito_domain_prefix="headless-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        public_subnet_mode="auto",
+        private_subnet_mode="auto",
+        enable_s3_batch=True,
+    )
+
+
+def test_default_cognito_domain_prefix_strips_reserved_words_from_cdk_prefix():
+    prefix = inst.default_cognito_domain_prefix_from_cdk_prefix(
+        "Lambeth-AWS-SharedServices-Dev-Summarisation-"
+    )
+    assert prefix == "lambeth-sharedservic"
+    assert "aws" not in prefix
+    assert "amazon" not in prefix
+    assert "cognito" not in prefix
+
+
+def test_sanitize_cognito_domain_prefix_removes_reserved_substrings():
+    assert (
+        inst.sanitize_cognito_domain_prefix("lambeth-aws-sharedse")
+        == "lambeth-sharedse"
+    )
+    assert inst.sanitize_cognito_domain_prefix("my-cognito-login") == "my-login"
+    assert (
+        inst.sanitize_cognito_domain_prefix("amazon-summarisation-dev")
+        == "summarisation-dev"
+    )
+    assert inst.sanitize_cognito_domain_prefix("aws") == "llm-topic-app"
+
+
+def test_validate_cognito_domain_prefix_rejects_reserved_words():
+    assert inst.validate_cognito_domain_prefix("lambeth-aws-sharedse") is not None
+    assert inst.validate_cognito_domain_prefix("lambeth-sharedse-dev") is None
+
+
+def test_build_env_values_demo():
+    values = inst.build_env_values(_demo_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "True"
+    assert values["ECS_EXPRESS_USE_PUBLIC_SUBNETS"] == "True"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == ""
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "False"
+    assert values["VPC_NAME"] == "test-vpc"
+    assert values["CONTEXT_FILE"] == "precheck.context.json"
+    assert values["CDK_FOLDER"].endswith("/cdk/")
+
+
+def test_build_env_values_production():
+    values = inst.build_env_values(_production_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "True"
+    assert values["RUN_USEAST_STACK"] == "True"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "True"
+    assert values["ACM_SSL_CERTIFICATE_ARN"].startswith("arn:aws:acm:")
+    assert values["SSL_CERTIFICATE_DOMAIN"] == "summarisation.example.com"
+    assert values["APPREGISTRY_STACK_NAME"] == "Test-Summarisation-AppRegistryStack"
+
+
+def test_build_env_values_uses_custom_s3_bucket_names():
+    answers = _demo_answers()
+    answers.s3_log_bucket_name = "063418083240-demo-summarisation-s3-logs"
+    answers.s3_output_bucket_name = "063418083240-demo-summarisation-s3-output"
+    values = inst.build_env_values(answers)
+    assert (
+        values["S3_LOG_CONFIG_BUCKET_NAME"] == "063418083240-demo-summarisation-s3-logs"
+    )
+    assert (
+        values["S3_OUTPUT_BUCKET_NAME"] == "063418083240-demo-summarisation-s3-output"
+    )
+
+
+def test_normalize_s3_bucket_name_truncates_and_sanitizes():
+    long_name = "A" * 80 + "/underscores"
+    normalized = inst.normalize_s3_bucket_name(long_name)
+    assert normalized == normalized.lower()
+    assert len(normalized) <= inst.S3_BUCKET_NAME_MAX_LEN
+    assert "_" not in normalized
+
+
+def test_suggest_available_s3_bucket_name_prefers_account_prefix(monkeypatch):
+    calls: list[str] = []
+
+    def fake_resolve(name: str, **kwargs):
+        calls.append(name)
+        if name.startswith("123456789012-"):
+            return ("available", name)
+        return ("globally_taken", name)
+
+    monkeypatch.setattr("cdk_functions.resolve_s3_bucket_availability", fake_resolve)
+    suggested = inst.suggest_available_s3_bucket_name(
+        "demo-summarisation-s3-logs", "123456789012"
+    )
+    assert suggested == "123456789012-demo-summarisation-s3-logs"
+    assert calls[0] == "demo-summarisation-s3-logs"
+
+
+def test_validate_globally_unique_env_values_flags_taken_bucket(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_s3_bucket_availability",
+        lambda name, **kwargs: ("globally_taken", name),
+    )
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: "available",
+    )
+    values = inst.build_env_values(_demo_answers())
+    errors = inst.validate_globally_unique_env_values(values)
+    assert any("taken globally" in err for err in errors)
+
+
+def test_prompt_globally_unique_cognito_prefix_suggests_when_taken(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: (
+            "taken" if prefix == "demo-summarisation" else "available"
+        ),
+    )
+    monkeypatch.setattr(
+        inst,
+        "suggest_available_cognito_domain_prefix",
+        lambda preferred, account_id, region, **kwargs: "063418083240-demo-summarisation",
+    )
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *args, **kwargs: True)
+    result = inst._prompt_globally_unique_cognito_prefix(
+        "demo-summarisation",
+        "063418083240",
+        "eu-west-2",
+        interactive=True,
+        assume_yes=False,
+    )
+    assert result == "063418083240-demo-summarisation"
+
+
+def test_prompt_globally_unique_cognito_prefix_rejects_taken_cli_override(monkeypatch):
+    monkeypatch.setattr(
+        "cdk_functions.resolve_cognito_domain_prefix_availability",
+        lambda prefix, **kwargs: "taken",
+    )
+    with pytest.raises(SystemExit):
+        inst._prompt_globally_unique_cognito_prefix(
+            "demo-summarisation",
+            "063418083240",
+            "eu-west-2",
+            interactive=False,
+            assume_yes=False,
+            cli_override="demo-summarisation",
+        )
+
+
+def test_subnet_cidr_prefix_len_for_express_demo():
+    answers = _demo_answers()
+    assert inst.subnet_cidr_prefix_len_for_tier(answers, "public") == 27
+    assert inst.subnet_cidr_prefix_len_for_tier(answers, "private") == 28
+
+
+def test_validate_public_subnet_cidr_for_express_rejects_small_blocks():
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/28") is not None
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/27") is None
+    assert inst.validate_public_subnet_cidr_for_express("10.0.0.0/26") is None
+
+
+def test_validate_env_values_rejects_express_public_subnets_too_small():
+    values = inst.build_env_values(_demo_answers())
+    values["PUBLIC_SUBNET_CIDR_BLOCKS"] = "['10.0.0.0/28', '10.0.0.16/28']"
+    errors = inst.validate_env_values(values)
+    assert any("too small for ECS Express" in err for err in errors)
+
+
+def test_build_env_values_headless():
+    values = inst.build_env_values(_headless_answers())
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["RUN_USEAST_STACK"] == "False"
+    assert values["ENABLE_HEADLESS_DEPLOYMENT"] == "True"
+    assert values["ENABLE_S3_BATCH_ECS_TRIGGER"] == "True"
+    assert values["COGNITO_AUTH"] == "False"
+    assert values["ECS_EXPRESS_USE_PUBLIC_SUBNETS"] == "True"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == ""
+    assert values["S3_LOG_CONFIG_BUCKET_NAME"] == "headless-summarisation-s3-logs"
+    assert values["S3_OUTPUT_BUCKET_NAME"] == "headless-summarisation-s3-output"
+
+
+def test_validate_env_values_rejects_bare_s3_bucket_names():
+    values = inst.build_env_values(_headless_answers())
+    values["S3_LOG_CONFIG_BUCKET_NAME"] = "s3-logs"
+    errors = inst.validate_env_values(values)
+    assert any("S3_LOG_CONFIG_BUCKET_NAME" in e for e in errors)
+
+
+def test_headless_profile_uses_public_subnets_only():
+    assert inst.answers_use_public_subnets_only(_headless_answers()) is True
+
+
+def test_build_env_values_production_headless():
+    answers = _production_answers()
+    answers.enable_headless = True
+    values = inst.build_env_values(answers)
+    assert values["USE_ECS_EXPRESS_MODE"] == "False"
+    assert values["USE_CLOUDFRONT"] == "False"
+    assert values["ENABLE_HEADLESS_DEPLOYMENT"] == "True"
+    assert values["ENABLE_RESOURCE_DELETE_PROTECTION"] == "True"
+    assert values.get("ECS_EXPRESS_USE_PUBLIC_SUBNETS") != "True"
+    assert "PRIVATE_SUBNET_CIDR_BLOCKS" in values
+
+
+def test_validate_install_answers_rejects_demo_headless():
+    answers = _demo_answers()
+    answers.enable_headless = True
+    errors = inst.validate_install_answers(answers)
+    assert any("Demonstration" in err for err in errors)
+
+
+def test_validate_install_answers_rejects_custom_express_headless():
+    answers = inst.InstallAnswers(profile="custom", enable_headless=True)
+    answers.custom_overrides["USE_ECS_EXPRESS_MODE"] = "True"
+    errors = inst.validate_install_answers(answers)
+    assert any("USE_ECS_EXPRESS_MODE=False" in err for err in errors)
+
+
+def test_profile_allows_headless_add_on():
+    assert inst.profile_allows_headless_add_on(_demo_answers()) is False
+    assert inst.profile_allows_headless_add_on(_production_answers()) is True
+    assert inst.profile_allows_headless_add_on(_headless_answers()) is True
+    custom = inst.InstallAnswers(profile="custom")
+    assert inst.profile_allows_headless_add_on(custom) is True
+    custom.custom_overrides["USE_ECS_EXPRESS_MODE"] = "True"
+    assert inst.profile_allows_headless_add_on(custom) is False
+
+
+def test_validate_install_answers_skips_cognito_prefix_for_headless():
+    values = inst.build_env_values(_headless_answers())
+    values["COGNITO_USER_POOL_DOMAIN_PREFIX"] = ""
+    assert inst.validate_env_values(values) == []
+
+
+def test_validate_headless_rejects_pi():
+    values = inst.build_env_values(_headless_answers())
+    values["ENABLE_ECS_SERVICE_CONNECT"] = "True"
+    errors = inst.validate_env_values(values)
+    assert any("HEADLESS" in e for e in errors)
+
+
+def test_validate_rejects_express_with_acm():
+    values = inst.build_env_values(_demo_answers())
+    values["ACM_SSL_CERTIFICATE_ARN"] = "arn:aws:acm:eu-west-2:123:certificate/x"
+    errors = inst.validate_env_values(values)
+    assert any("ACM_SSL_CERTIFICATE_ARN" in e for e in errors)
+
+
+def test_build_env_values_mixed_subnet_tiers():
+    answers = _production_answers()
+    answers.public_subnet_mode = "existing"
+    answers.private_subnet_mode = "create"
+    answers.public_subnet_names = ["existing-public-a", "existing-public-b"]
+    answers.public_subnet_cidrs = ["10.244.1.0/28", "10.244.2.0/28"]
+    answers.public_subnet_azs = ["eu-west-2a", "eu-west-2b"]
+    answers.private_subnet_names = ["Demo-Summarisation-PrivateSubnet1"]
+    answers.private_subnet_cidrs = ["10.0.10.0/28"]
+    answers.private_subnet_azs = ["eu-west-2a"]
+    values = inst.build_env_values(answers)
+    assert (
+        values["PUBLIC_SUBNETS_TO_USE"] == '["existing-public-a", "existing-public-b"]'
+    )
+    assert values["PUBLIC_SUBNET_CIDR_BLOCKS"] == "['10.244.1.0/28', '10.244.2.0/28']"
+    assert values["PUBLIC_SUBNET_AVAILABILITY_ZONES"] == "['eu-west-2a', 'eu-west-2b']"
+    assert values["PRIVATE_SUBNETS_TO_USE"] == '["Demo-Summarisation-PrivateSubnet1"]'
+    assert values["PRIVATE_SUBNET_CIDR_BLOCKS"] == "['10.0.10.0/28']"
+    assert values["PRIVATE_SUBNET_AVAILABILITY_ZONES"] == "['eu-west-2a']"
+
+
+def test_enrich_existing_subnet_details_from_aws(monkeypatch):
+    answers = _demo_answers()
+    answers.vpc_name = "test-vpc"
+    answers.public_subnet_mode = "existing"
+    answers.public_subnet_names = ["pub-a", "pub-b"]
+    answers.private_subnet_mode = "create"
+
+    monkeypatch.setattr(
+        inst,
+        "list_vpcs",
+        lambda _region: [{"name": "test-vpc", "id": "vpc-123", "cidr": "10.0.0.0/16"}],
+    )
+    monkeypatch.setattr(
+        inst,
+        "list_subnets_in_vpc",
+        lambda _vpc_id, _region: [
+            {"name": "pub-a", "cidr": "10.244.1.0/28", "az": "eu-west-2a"},
+            {"name": "pub-b", "cidr": "10.244.2.0/28", "az": "eu-west-2b"},
+        ],
+    )
+
+    errors = inst.enrich_existing_subnet_details_from_aws(answers)
+    assert errors == []
+    assert answers.public_subnet_cidrs == ["10.244.1.0/28", "10.244.2.0/28"]
+    assert answers.public_subnet_azs == ["eu-west-2a", "eu-west-2b"]
+
+
+def test_validate_subnet_answers_mixed_requires_public_names():
+    answers = _demo_answers()
+    answers.public_subnet_mode = "existing"
+    answers.private_subnet_mode = "create"
+    answers.private_subnet_names = ["new-private"]
+    errors = inst.validate_subnet_answers(answers)
+    assert any("Public subnets" in err for err in errors)
+
+
+def test_resolve_subnet_tier_modes_per_tier_override():
+    args = argparse.Namespace(
+        subnet_mode="auto",
+        public_subnet_mode="existing",
+        private_subnet_mode="create",
+    )
+    public, private = inst.resolve_subnet_tier_modes(args)
+    assert public == "existing"
+    assert private == "create"
+
+
+def test_suggest_vpc_cidr_block_empty_region():
+    assert inst.suggest_vpc_cidr_block([]) == "10.0.0.0/24"
+
+
+def test_suggest_vpc_cidr_block_skips_overlaps():
+    assert inst.suggest_vpc_cidr_block(["10.0.0.0/24"]) == "10.0.1.0/24"
+    assert inst.suggest_vpc_cidr_block(["10.0.0.0/16"]) == "10.1.0.0/24"
+
+
+def test_validate_new_vpc_cidr_rejects_overlap_and_public_space():
+    err = inst.validate_new_vpc_cidr("10.0.0.0/24", ["10.0.0.0/16"])
+    assert err is not None
+    assert "overlaps" in err
+    err = inst.validate_new_vpc_cidr("8.8.8.0/24", [])
+    assert err is not None
+    assert "RFC1918" in err
+
+
+def test_validate_new_vpc_cidr_accepts_available_block():
+    assert inst.validate_new_vpc_cidr("10.2.0.0/24", ["10.0.0.0/16"]) is None
+
+
+def test_prompt_new_vpc_cidr_validates_cli_override(monkeypatch):
+    answers = inst.InstallAnswers(aws_region="eu-west-2", new_vpc_cidr="10.0.0.0/24")
+    monkeypatch.setattr(
+        inst, "list_vpc_cidr_blocks_in_region", lambda _r: ["10.0.0.0/16"]
+    )
+    with pytest.raises(SystemExit):
+        inst.prompt_new_vpc_cidr(answers, interactive=False)
+
+
+def test_prompt_new_vpc_cidr_auto_select_noninteractive(monkeypatch):
+    answers = inst.InstallAnswers(aws_region="eu-west-2")
+    monkeypatch.setattr(inst, "list_vpc_cidr_blocks_in_region", lambda _r: [])
+    inst.prompt_new_vpc_cidr(answers, interactive=False)
+    assert answers.new_vpc_cidr == "10.0.0.0/24"
+
+
+def test_suggest_subnet_cidr_blocks_lowest_available():
+    blocks = inst.suggest_subnet_cidr_blocks("10.0.0.0/24", ["10.0.0.0/28"], 2)
+    assert blocks == ["10.0.0.16/28", "10.0.0.32/28"]
+
+
+def test_suggest_subnet_cidr_blocks_respects_reserved():
+    blocks = inst.suggest_subnet_cidr_blocks(
+        "10.0.0.0/24",
+        [],
+        1,
+        reserved_cidrs=["10.0.0.0/28"],
+    )
+    assert blocks == ["10.0.0.16/28"]
+
+
+def test_vpc_cidr_blocks_from_describe_includes_associations():
+    vpc = {
+        "CidrBlock": "10.0.0.0/16",
+        "CidrBlockAssociationSet": [{"CidrBlock": "10.1.0.0/16"}],
+    }
+    assert inst.vpc_cidr_blocks_from_describe(vpc) == [
+        "10.0.0.0/16",
+        "10.1.0.0/16",
+    ]
+
+
+def test_build_app_config_env_values_express_uses_in_app_cognito():
+    values = inst.build_env_values(_demo_answers())
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "True"
+    assert updates["RUN_AWS_FUNCTIONS"] == "True"
+    assert updates["S3_LOG_BUCKET"].endswith("s3-logs")
+
+
+def test_build_app_config_env_values_express_pi_disables_main_cognito():
+    values = inst.build_env_values(_demo_answers())
+    values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] = "True"
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "False"
+
+
+def test_build_app_config_env_values_headless():
+    answers = _headless_answers()
+    values = inst.build_env_values(answers)
+    updates = inst.build_app_config_env_values(values)
+    assert updates["COGNITO_AUTH"] == "False"
+
+
+def test_write_app_config_env_from_example(tmp_path, monkeypatch):
+    example = tmp_path / "app_config.env.example"
+    example.write_text(
+        "RUN_AWS_FUNCTIONS=True\nS3_LOG_BUCKET=placeholder\n",
+        encoding="utf-8",
+    )
+    target = tmp_path / "app_config.env"
+    monkeypatch.setattr(inst, "APP_CONFIG_ENV_EXAMPLE", example)
+    monkeypatch.setattr(inst, "APP_CONFIG_ENV_PATH", target)
+
+    answers = _demo_answers()
+    answers.write_app_config_env = True
+    values = inst.build_env_values(answers)
+    inst.write_app_config_env_file(answers, values)
+
+    written = inst.read_env_file(target)
+    assert written["RUN_AWS_FUNCTIONS"] == "True"
+    assert written["S3_LOG_BUCKET"].endswith("s3-logs")
+    assert written["COGNITO_AUTH"] == "True"
+
+
+def test_format_list_env():
+    assert inst.format_list_env(["a", "b"]) == '["a", "b"]'
+    assert (
+        inst.format_list_env(["10.0.0.0/28"], use_single_quotes=True)
+        == "['10.0.0.0/28']"
+    )
+    assert inst.format_list_env([]) == "[]"
+
+
+def test_write_env_file_backs_up(tmp_path):
+    env_path = tmp_path / "cdk_config.env"
+    env_path.write_text("OLD=1\n", encoding="utf-8")
+    inst.write_env_file(env_path, {"NEW": "2"})
+    backups = list(tmp_path.glob("cdk_config.env.bak.*"))
+    assert len(backups) == 1
+    assert "NEW=2" in env_path.read_text(encoding="utf-8")
+
+
+def test_write_cdk_json_preserves_context(tmp_path, monkeypatch):
+    cdk_json = tmp_path / "cdk.json"
+    cdk_json.write_text(
+        json.dumps(
+            {
+                "app": "old-python app.py",
+                "context": {"@aws-cdk/custom:flag": True, "keep": 1},
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(inst, "CDK_JSON_PATH", cdk_json)
+    monkeypatch.setattr(inst, "CDK_JSON_EXAMPLE", tmp_path / "missing.example")
+
+    py = Path(sys.executable)
+    inst.write_cdk_json(py, force=True)
+
+    data = json.loads(cdk_json.read_text(encoding="utf-8"))
+    assert data["context"]["@aws-cdk/custom:flag"] is True
+    assert data["context"]["keep"] == 1
+    assert data["app"].endswith("app.py")
+    assert "output" in data
+    backups = list(tmp_path.glob("cdk.json.bak.*"))
+    assert len(backups) == 1
+
+
+def test_format_cdk_app_command():
+    cmd = inst.format_cdk_app_command(Path(sys.executable))
+    assert cmd.endswith("app.py")
+    assert str(sys.executable).replace("/", "\\") in cmd or sys.executable in cmd
+
+
+def test_venv_python_paths_includes_sys_executable():
+    paths = inst._venv_python_paths()
+    assert Path(sys.executable).resolve() == paths[0].resolve()
+
+
+def test_merge_preset_custom():
+    merged = inst.merge_preset("demo", {"ECS_TASK_MEMORY_SIZE": "8192"})
+    assert merged["USE_ECS_EXPRESS_MODE"] == "True"
+    assert merged["ECS_TASK_MEMORY_SIZE"] == "8192"
+
+
+def test_build_env_values_pi_express_forced_off():
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] == "False"
+    assert values["ENABLE_PI_AGENT_ECS_SERVICE"] == "False"
+
+
+def test_build_pi_agent_env_values_express_skips_root_path():
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    env = inst.build_pi_agent_env_values(answers)
+    assert env["RUN_FASTAPI"] == "True"
+    assert "PI_ROOT_PATH" not in env
+
+
+def test_build_env_values_pi_production_host_forced_off():
+    answers = _production_answers()
+    answers.enable_pi_legacy = True
+    answers.enable_service_connect = True
+    answers.pi_alb_routing = "host"
+    answers.pi_alb_host_header = "agent.example.com"
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_PI_AGENT_ECS_SERVICE"] == "False"
+    assert values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] == "False"
+
+
+def test_validate_pi_host_requires_header():
+    values = inst.build_env_values(_production_answers())
+    values["ENABLE_PI_AGENT_ECS_SERVICE"] = "True"
+    values["ENABLE_ECS_SERVICE_CONNECT"] = "True"
+    values["PI_ALB_ROUTING"] = "host"
+    values["PI_ALB_HOST_HEADER"] = ""
+    errors = inst.validate_env_values(values)
+    assert any("PI_ALB_HOST_HEADER" in e for e in errors)
+
+
+def test_validate_pi_express_skips_alb_routing():
+    values = inst.build_env_values(_demo_answers())
+    values["ENABLE_PI_AGENT_EXPRESS_SERVICE"] = "True"
+    values["USE_ECS_EXPRESS_MODE"] = "True"
+    assert inst.validate_env_values(values) == []
+
+
+def test_build_pi_agent_env_values():
+    answers = _demo_answers()
+    answers.enable_pi_express = False
+    answers.enable_pi_legacy = True
+    answers.pi_alb_routing = "path"
+    answers.pi_alb_path_prefix = "/pi"
+    values = inst.build_pi_agent_env_values(answers)
+    assert values["PI_DEPLOYMENT_PROFILE"] == "aws-ecs"
+    assert values["DOC_SUMMARISATION_GRADIO_URL"] == "http://llm-topic:7860"
+    assert values["PI_ROOT_PATH"] == "/pi"
+
+
+def test_apply_pi_cli_flags_enable_pi_demo():
+    answers = inst.InstallAnswers(profile="demo")
+    args = argparse.Namespace(
+        enable_pi=True,
+        enable_pi_express=False,
+        enable_pi_legacy=False,
+        pi_alb_routing=None,
+        pi_path_prefix="",
+        pi_host_header="",
+        pi_listener_priority="",
+        pi_gradio_port="",
+        sc_discovery_name="",
+        pi_provider="",
+        skip_pi_agent_env=False,
+    )
+    inst.apply_pi_cli_flags(args, answers)
+    assert answers.enable_pi_express is True
+
+
+def test_stacks_to_check_includes_appregistry_when_enabled():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "ENABLE_APPREGISTRY": "True",
+            "APPREGISTRY_STACK_NAME": "Demo-Summarisation-AppRegistryStack",
+        },
+    )
+    names = [name for name, _ in checks]
+    assert names == [
+        inst.CLOUDFRONT_STACK,
+        "Demo-Summarisation-AppRegistryStack",
+        inst.REGIONAL_STACK,
+    ]
+    assert checks[0][1] == inst.CLOUDFRONT_STACK_REGION
+    assert checks[-1] == (inst.REGIONAL_STACK, "eu-west-2")
+
+
+def test_stacks_to_check_without_appregistry():
+    checks = inst.stacks_to_check("eu-west-2", {"ENABLE_APPREGISTRY": "False"})
+    assert [name for name, _ in checks] == [
+        inst.CLOUDFRONT_STACK,
+        inst.REGIONAL_STACK,
+    ]
+
+
+def test_derived_appregistry_stack_name_from_cdk_prefix():
+    name = inst.derived_appregistry_stack_name(
+        {"CDK_PREFIX": "Demo-Summarisation-", "ENABLE_APPREGISTRY": "True"}
+    )
+    assert name == "Demo-Summarisation-AppRegistryStack"
+
+
+def test_stacks_to_check_derives_appregistry_from_cdk_prefix():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "CDK_PREFIX": "Demo-Summarisation-",
+            "ENABLE_APPREGISTRY": "True",
+        },
+    )
+    assert "Demo-Summarisation-AppRegistryStack" in [name for name, _ in checks]
+
+
+def test_stacks_to_check_skips_cloudfront_when_disabled():
+    checks = inst.stacks_to_check(
+        "eu-west-2",
+        {
+            "USE_CLOUDFRONT": "False",
+            "RUN_USEAST_STACK": "False",
+            "ENABLE_APPREGISTRY": "False",
+        },
+    )
+    assert checks == [(inst.REGIONAL_STACK, "eu-west-2")]
+
+
+def test_discover_existing_doc_summarisation_stacks_order(monkeypatch):
+    monkeypatch.setattr(
+        inst, "list_regional_appregistry_stack_names", lambda _region: []
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if stack_name == inst.REGIONAL_STACK and region == "eu-west-2":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="UPDATE_COMPLETE",
+            )
+        if (
+            stack_name == inst.CLOUDFRONT_STACK
+            and region == inst.CLOUDFRONT_STACK_REGION
+        ):
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="CREATE_COMPLETE",
+                termination_protection=True,
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks("eu-west-2")
+    assert [s.name for s in found] == [inst.CLOUDFRONT_STACK, inst.REGIONAL_STACK]
+    assert found[0].termination_protection is True
+
+
+def test_discover_existing_stacks_continues_after_access_denied(monkeypatch):
+    from botocore.exceptions import ClientError
+
+    monkeypatch.setattr(
+        inst, "list_regional_appregistry_stack_names", lambda _region: []
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if (
+            stack_name == inst.CLOUDFRONT_STACK
+            and region == inst.CLOUDFRONT_STACK_REGION
+        ):
+            raise ClientError(
+                {
+                    "Error": {
+                        "Code": "AccessDenied",
+                        "Message": "explicit deny in SCP",
+                    }
+                },
+                "DescribeStacks",
+            )
+        if stack_name == inst.REGIONAL_STACK and region == "eu-west-2":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="UPDATE_COMPLETE",
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks("eu-west-2")
+    assert [s.name for s in found] == [inst.REGIONAL_STACK]
+
+
+def test_discover_includes_orphan_appregistry_when_disabled_in_config(monkeypatch):
+    monkeypatch.setattr(
+        inst,
+        "list_regional_appregistry_stack_names",
+        lambda _region: ["Old-Summarisation-AppRegistryStack"],
+    )
+
+    def fake_describe(stack_name: str, region: str):
+        if stack_name == "Old-Summarisation-AppRegistryStack":
+            return inst.ExistingStack(
+                name=stack_name,
+                region=region,
+                status="CREATE_COMPLETE",
+            )
+        return None
+
+    monkeypatch.setattr(inst, "describe_existing_stack", fake_describe)
+    found = inst.discover_existing_llm_topic_stacks(
+        "eu-west-2",
+        {"ENABLE_APPREGISTRY": "False"},
+    )
+    assert [s.name for s in found] == ["Old-Summarisation-AppRegistryStack"]
+
+
+def test_handle_existing_stacks_force_delete(monkeypatch):
+    stacks = [
+        inst.ExistingStack(
+            name=inst.CLOUDFRONT_STACK,
+            region=inst.CLOUDFRONT_STACK_REGION,
+            status="CREATE_COMPLETE",
+        )
+    ]
+    deleted: list = []
+
+    monkeypatch.setattr(
+        inst,
+        "discover_existing_llm_topic_stacks",
+        lambda *_a, **_k: stacks,
+    )
+    monkeypatch.setattr(
+        inst,
+        "force_delete_cloudformation_stacks",
+        lambda s, **kwargs: deleted.extend(s),
+    )
+
+    args = argparse.Namespace(
+        skip_stack_check=False,
+        config_only=False,
+        synth_only=False,
+        force_delete_stacks=True,
+        yes=True,
+    )
+    inst.handle_existing_stacks_at_start(args, "eu-west-2")
+    assert deleted == stacks
+
+
+def test_handle_existing_stacks_yes_without_force_skips_delete(monkeypatch):
+    monkeypatch.setattr(
+        inst,
+        "discover_existing_llm_topic_stacks",
+        lambda *_a, **_k: [
+            inst.ExistingStack(
+                name=inst.REGIONAL_STACK,
+                region="eu-west-2",
+                status="CREATE_COMPLETE",
+            )
+        ],
+    )
+    monkeypatch.setattr(
+        inst,
+        "force_delete_cloudformation_stacks",
+        lambda *_a, **_k: (_ for _ in ()).throw(AssertionError("should not delete")),
+    )
+
+    args = argparse.Namespace(
+        skip_stack_check=False,
+        config_only=False,
+        synth_only=False,
+        force_delete_stacks=False,
+        yes=True,
+    )
+    inst.handle_existing_stacks_at_start(args, "eu-west-2")
+
+
+def test_write_pi_agent_env_file_minimal(tmp_path, monkeypatch):
+    answers = _demo_answers()
+    answers.enable_pi_express = True
+    target = tmp_path / "pi_agent.env"
+    monkeypatch.setattr(inst, "PI_AGENT_ENV_PATH", target)
+    monkeypatch.setattr(inst, "PI_AGENT_ENV_EXAMPLE", tmp_path / "missing.example")
+    inst.write_pi_agent_env_file(answers)
+    text = target.read_text(encoding="utf-8")
+    assert "PI_DEPLOYMENT_PROFILE=aws-ecs" in text
+    assert "DOC_SUMMARISATION_GRADIO_URL=http://llm-topic:7860" in text
+
+
+def test_run_cdk_command_invokes_cdk_cli_not_python(monkeypatch):
+    calls: list = []
+
+    def fake_run(cmd, **kwargs):
+        calls.append((cmd, kwargs))
+        return subprocess.CompletedProcess(cmd, 0)
+
+    monkeypatch.setattr(inst, "resolve_cdk_executable", lambda: r"C:\npm\cdk.cmd")
+    monkeypatch.setattr(inst.subprocess, "run", fake_run)
+    inst.run_cdk_command(["synth"], check=False)
+    cmd, kwargs = calls[0]
+    assert cmd == [r"C:\npm\cdk.cmd", "synth"]
+    assert "executable" not in kwargs
+
+
+def test_build_cdk_subprocess_env_overrides_stale_defaults(tmp_path, monkeypatch):
+    env_path = tmp_path / "config" / "cdk_config.env"
+    env_path.parent.mkdir(parents=True)
+    env_path.write_text(
+        "VPC_NAME=my-vpc\nCDK_PREFIX=MyPrefix-\nAWS_REGION=eu-west-2\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    monkeypatch.setattr(inst, "CDK_DIR", tmp_path)
+    monkeypatch.setenv("VPC_NAME", "")
+    monkeypatch.setenv("CDK_PREFIX", "")
+
+    env = inst.build_cdk_subprocess_env()
+    assert env["VPC_NAME"] == "my-vpc"
+    assert env["CDK_PREFIX"] == "MyPrefix-"
+    assert env["CDK_CONFIG_PATH"] == str(env_path)
+
+
+def test_apply_cdk_runtime_env_sets_paths(tmp_path, monkeypatch):
+    env_path = tmp_path / "cdk_config.env"
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    inst.apply_cdk_runtime_env(
+        {"CDK_FOLDER": "C:/example/cdk/", "AWS_REGION": "eu-west-2"}
+    )
+    assert os.environ["CDK_CONFIG_PATH"] == str(env_path)
+    assert os.environ["CDK_FOLDER"] == "C:/example/cdk/"
+
+
+def test_run_smoke_test_if_needed_skips_config_only(monkeypatch):
+    called = []
+
+    def fake_smoke(_python_exe):
+        called.append(True)
+
+    monkeypatch.setattr(inst, "smoke_test_python_app", fake_smoke)
+    args = argparse.Namespace(config_only=True, skip_cdk_json=False)
+    inst.run_smoke_test_if_needed(Path(sys.executable), args)
+    assert called == []
+
+
+def test_main_writes_config_before_smoke_test(monkeypatch, tmp_path):
+    call_order: list[str] = []
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+    env_path = config_dir / "cdk_config.env"
+    cdk_json = tmp_path / "cdk.json"
+
+    monkeypatch.setattr(inst, "CONFIG_DIR", config_dir)
+    monkeypatch.setattr(inst, "ENV_PATH", env_path)
+    monkeypatch.setattr(inst, "CDK_JSON_PATH", cdk_json)
+    monkeypatch.setattr(inst, "CDK_DIR", tmp_path)
+    monkeypatch.setattr(inst, "check_cdk_cli", lambda: "2.0.0")
+    monkeypatch.setattr(
+        inst,
+        "handle_existing_stacks_at_start",
+        lambda *_a, **_k: None,
+    )
+    monkeypatch.setattr(
+        inst,
+        "resolve_python_executable",
+        lambda **_kw: Path(sys.executable),
+    )
+    monkeypatch.setattr(inst, "write_cdk_json", lambda *_a, **_k: cdk_json)
+
+    def fake_wizard(_args):
+        call_order.append("wizard")
+        return _demo_answers()
+
+    def fake_write_env_file(path, values):
+        call_order.append("write_config")
+        path.write_text("VPC_NAME=test-vpc\n", encoding="utf-8")
+        return values
+
+    def fake_smoke(_python_exe):
+        call_order.append("smoke")
+
+    monkeypatch.setattr(inst, "run_wizard", fake_wizard)
+    monkeypatch.setattr(inst, "write_env_file", fake_write_env_file)
+    monkeypatch.setattr(inst, "smoke_test_python_app", fake_smoke)
+    monkeypatch.setattr(inst, "print_summary", lambda *_a, **_k: None)
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *_a, **_k: True)
+    monkeypatch.setattr(inst, "cdk_bootstrap_needed", lambda *_a, **_k: False)
+    monkeypatch.setattr(inst, "run_cdk_command", lambda *_a, **_k: None)
+
+    inst.main(
+        [
+            "--yes",
+            "--profile",
+            "demo",
+            "--vpc-name",
+            "test-vpc",
+            "--synth-only",
+        ]
+    )
+
+    assert call_order.index("wizard") < call_order.index("write_config")
+    assert call_order.index("write_config") < call_order.index("smoke")
+
+
+def test_resolve_fixup_env_values_derives_service_from_prefix():
+    values = {"CDK_PREFIX": "Demo-Summarisation-", "USE_ECS_EXPRESS_MODE": "True"}
+    resolved = inst.resolve_fixup_env_values(values)
+    assert resolved["ECS_EXPRESS_SERVICE_NAME"] == "Demo-Summarisation-ECSService"
+    assert resolved["CLUSTER_NAME"] == "Demo-Summarisation-Cluster"
+    assert (
+        resolved["ECS_PI_EXPRESS_SERVICE_NAME"] == "Demo-Summarisation-PiExpressService"
+    )
+
+
+def test_apply_post_deploy_fixup_express_syncs_cognito_secret_not_alb(monkeypatch):
+    import cdk_post_deploy as post
+
+    values = {
+        "USE_ECS_EXPRESS_MODE": "True",
+        "USE_CLOUDFRONT": "False",
+        "AWS_REGION": "eu-west-2",
+        "CDK_PREFIX": "Demo-Summarisation-",
+        "ECS_EXPRESS_COGNITO_REDIRECT_BASE": "",
+    }
+    outputs = {
+        "ExpressServiceEndpoint": "https://express.example.com",
+        "CognitoPoolId": "pool-1",
+        "CognitoAppClientId": "client-1",
+    }
+    monkeypatch.setattr(
+        inst,
+        "fetch_stack_output",
+        lambda _stack, key, _region: outputs.get(key),
+    )
+    monkeypatch.setattr(inst, "patch_env_file", lambda *_a, **_k: None)
+    monkeypatch.setattr(inst, "ask_yes_no", lambda *_a, **_k: True)
+    redeploy_calls: list = []
+    monkeypatch.setattr(
+        inst,
+        "run_cdk_command",
+        lambda *args, **_k: redeploy_calls.append(args),
+    )
+    monkeypatch.setattr(
+        post,
+        "cognito_alb_callbacks_need_update",
+        lambda *_a, **_k: True,
+    )
+    monkeypatch.setattr(
+        post,
+        "apply_cognito_alb_callback_fixup",
+        lambda *_a, **_k: True,
+    )
+    secret_fixup_calls: list = []
+    monkeypatch.setattr(
+        post,
+        "apply_cognito_secret_fixup_from_stack",
+        lambda **_k: secret_fixup_calls.append(_k) or True,
+    )
+
+    assert inst.apply_post_deploy_fixup(values, assume_yes=False) is True
+    assert redeploy_calls == []
+    assert secret_fixup_calls
+    assert secret_fixup_calls[0]["main_service_name"] == "Demo-Summarisation-ECSService"
+    assert secret_fixup_calls[0]["cluster_name"] == "Demo-Summarisation-Cluster"
+
+
+def test_jsii_import_failure_hint_detects_json_decode_error():
+    hint = inst._jsii_import_failure_hint(
+        "json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)"
+    )
+    assert "JSII Node.js helper" in hint
+    assert "node --version" in hint
+
+
+def test_jsii_import_failure_hint_empty_for_other_errors():
+    assert inst._jsii_import_failure_hint("ModuleNotFoundError: aws_cdk") == ""

cdk/test/test_cdk_post_deploy.py

@@ -0,0 +1,402 @@
+"""Unit tests for cdk_post_deploy.py (boto3 helpers, no live AWS)."""
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+import cdk_post_deploy as post
+
+
+def test_container_definitions_with_named_port_adds_mapping_to_first_container():
+    containers = [{"name": "app", "image": "nginx"}]
+    updated = post._container_definitions_with_named_port(
+        containers,
+        port_name="port-7860",
+        container_port=7860,
+    )
+    assert updated[0]["portMappings"] == [
+        {"name": "port-7860", "containerPort": 7860, "protocol": "tcp"}
+    ]
+
+
+def test_container_definitions_with_named_port_names_existing_mapping():
+    containers = [
+        {
+            "name": "app",
+            "image": "nginx",
+            "portMappings": [{"containerPort": 7860, "protocol": "tcp"}],
+        }
+    ]
+    updated = post._container_definitions_with_named_port(
+        containers,
+        port_name="port-7860",
+        container_port=7860,
+    )
+    assert updated[0]["portMappings"][0]["name"] == "port-7860"
+
+
+def test_resolve_service_task_definition_arn_from_describe_services():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "serviceArn": "arn:aws:ecs:eu-west-2:123:service/cluster/app",
+                "taskDefinition": "arn:aws:ecs:eu-west-2:123:task-definition/app:1",
+            }
+        ]
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        arn = post.resolve_service_task_definition_arn("cluster", "app")
+
+    assert arn == "arn:aws:ecs:eu-west-2:123:task-definition/app:1"
+    mock_ecs.describe_express_gateway_service.assert_not_called()
+
+
+def test_resolve_service_task_definition_arn_from_express_service_revision():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "serviceArn": "arn:aws:ecs:eu-west-2:123:service/cluster/express-app",
+            }
+        ]
+    }
+    mock_ecs.describe_express_gateway_service.return_value = {
+        "service": {
+            "activeConfigurations": [
+                {
+                    "serviceRevisionArn": "arn:aws:ecs:eu-west-2:123:service-revision/rev/1"
+                }
+            ]
+        }
+    }
+    mock_ecs.describe_service_revisions.return_value = {
+        "serviceRevisions": [
+            {
+                "taskDefinition": "arn:aws:ecs:eu-west-2:123:task-definition/express:3",
+            }
+        ]
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        arn = post.resolve_service_task_definition_arn("cluster", "express-app")
+
+    assert arn == "arn:aws:ecs:eu-west-2:123:task-definition/express:3"
+    mock_ecs.describe_express_gateway_service.assert_called_once()
+    mock_ecs.describe_service_revisions.assert_called_once_with(
+        serviceRevisionArns=["arn:aws:ecs:eu-west-2:123:service-revision/rev/1"]
+    )
+
+
+def test_start_express_gateway_service_updates_scaling_target():
+    mock_ecs = MagicMock()
+    mock_ecs.get_paginator.return_value.paginate.return_value = [
+        {
+            "serviceArns": [
+                "arn:aws:ecs:eu-west-2:123456789012:service/my-cluster/my-express"
+            ]
+        }
+    ]
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_ecs):
+        result = post.start_express_gateway_service("my-cluster", "my-express")
+
+    assert result["statusCode"] == 200
+    mock_ecs.update_express_gateway_service.assert_called_once_with(
+        serviceArn="arn:aws:ecs:eu-west-2:123456789012:service/my-cluster/my-express",
+        scalingTarget=post.EXPRESS_GATEWAY_ACTIVE_SCALING_TARGET,
+    )
+
+
+def test_cognito_https_callback_urls():
+    assert post.cognito_https_callback_urls(
+        "https://abc123.eu-west-2.elb.amazonaws.com"
+    ) == [
+        "https://abc123.eu-west-2.elb.amazonaws.com",
+        "https://abc123.eu-west-2.elb.amazonaws.com/oauth2/idpresponse",
+    ]
+    assert post.cognito_https_callback_urls("app.example.com")[0].startswith("https://")
+
+
+def test_update_user_pool_client_callback_urls_preserves_oauth_settings():
+    mock_cognito = MagicMock()
+    mock_cognito.describe_user_pool_client.return_value = {
+        "UserPoolClient": {
+            "ClientName": "app-client",
+            "CallbackURLs": ["https://old.example.com"],
+            "AllowedOAuthFlows": ["code"],
+            "AllowedOAuthScopes": ["openid", "email", "profile"],
+            "AllowedOAuthFlowsUserPoolClient": True,
+            "SupportedIdentityProviders": ["COGNITO"],
+            "ExplicitAuthFlows": ["ALLOW_REFRESH_TOKEN_AUTH"],
+        }
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_cognito):
+        post.update_user_pool_client_callback_urls(
+            "pool-1",
+            "client-1",
+            [
+                "https://new.example.com",
+                "https://new.example.com/oauth2/idpresponse",
+            ],
+            aws_region="eu-west-2",
+        )
+
+    mock_cognito.update_user_pool_client.assert_called_once()
+    kwargs = mock_cognito.update_user_pool_client.call_args.kwargs
+    assert kwargs["UserPoolId"] == "pool-1"
+    assert kwargs["ClientId"] == "client-1"
+    assert kwargs["CallbackURLs"] == [
+        "https://new.example.com",
+        "https://new.example.com/oauth2/idpresponse",
+    ]
+    assert kwargs["AllowedOAuthFlows"] == ["code"]
+    assert kwargs["AllowedOAuthScopes"] == ["openid", "email", "profile"]
+
+
+def test_apply_cognito_alb_callback_fixup_skips_when_already_correct():
+    mock_cognito = MagicMock()
+    mock_cognito.describe_user_pool_client.return_value = {
+        "UserPoolClient": {
+            "CallbackURLs": post.cognito_https_callback_urls("https://app.example.com"),
+        }
+    }
+
+    with patch("cdk_post_deploy.boto3.client", return_value=mock_cognito):
+        changed = post.apply_cognito_alb_callback_fixup(
+            user_pool_id="pool-1",
+            client_id="client-1",
+            redirect_base="https://app.example.com",
+        )
+
+    assert changed is False
+    mock_cognito.update_user_pool_client.assert_not_called()
+
+
+def test_target_group_arn_from_ecs_register_event():
+    message = (
+        "(service my-svc) registered 1 targets in "
+        "(target-group arn:aws:elasticloadbalancing:eu-west-2:123:"
+        "targetgroup/ecs-gateway-tg-abc/def)"
+    )
+    assert (
+        post.target_group_arn_from_ecs_register_event(message)
+        == "arn:aws:elasticloadbalancing:eu-west-2:123:targetgroup/ecs-gateway-tg-abc/def"
+    )
+
+
+def test_resolve_express_service_target_group_arn_waits_for_registration_event():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.side_effect = [
+        {
+            "services": [
+                {
+                    "events": [],
+                    "runningCount": 0,
+                    "desiredCount": 1,
+                }
+            ]
+        },
+        {
+            "services": [
+                {
+                    "events": [
+                        {
+                            "message": (
+                                "(service Demo-Summarisation-ECSService) registered 1 targets in "
+                                "(target-group arn:aws:elasticloadbalancing:eu-west-2:123:"
+                                "targetgroup/ecs-gateway-tg-abc/def)"
+                            )
+                        }
+                    ],
+                    "runningCount": 1,
+                    "desiredCount": 1,
+                }
+            ]
+        },
+    ]
+
+    with (
+        patch("cdk_post_deploy.boto3.client", return_value=mock_ecs),
+        patch("cdk_post_deploy.time.sleep"),
+        patch("cdk_post_deploy.time.monotonic", side_effect=[0, 0, 600]),
+    ):
+        arn = post.resolve_express_service_target_group_arn(
+            "cluster",
+            "Demo-Summarisation-ECSService",
+            max_wait_seconds=600,
+            poll_interval_seconds=15,
+        )
+
+    assert arn == (
+        "arn:aws:elasticloadbalancing:eu-west-2:123:targetgroup/ecs-gateway-tg-abc/def"
+    )
+    assert mock_ecs.describe_services.call_count == 2
+
+
+def test_resolve_express_service_target_group_arn_from_task_ips():
+    mock_ecs = MagicMock()
+    mock_ecs.describe_services.return_value = {
+        "services": [
+            {
+                "events": [],
+                "runningCount": 1,
+                "desiredCount": 1,
+            }
+        ]
+    }
+    mock_ecs.list_tasks.return_value = {"taskArns": ["arn:task/1"]}
+    mock_ecs.describe_tasks.return_value = {
+        "tasks": [
+            {
+                "attachments": [
+                    {"details": [{"name": "privateIPv4Address", "value": "10.0.1.42"}]}
+                ]
+            }
+        ]
+    }
+    mock_elbv2 = MagicMock()
+    mock_elbv2.describe_target_groups.return_value = {
+        "TargetGroups": [{"TargetGroupArn": "arn:tg/main"}]
+    }
+    mock_elbv2.describe_target_health.return_value = {
+        "TargetHealthDescriptions": [{"Target": {"Id": "10.0.1.42"}}]
+    }
+
+    def client_factory(service_name, **_kwargs):
+        return mock_elbv2 if service_name == "elbv2" else mock_ecs
+
+    with (
+        patch("cdk_post_deploy.boto3.client", side_effect=client_factory),
+        patch("cdk_post_deploy.time.monotonic", return_value=0),
+    ):
+        arn = post.resolve_express_service_target_group_arn(
+            "cluster",
+            "Demo-Summarisation-ECSService",
+            load_balancer_arn="arn:lb/express",
+            max_wait_seconds=600,
+            poll_interval_seconds=15,
+        )
+
+    assert arn == "arn:tg/main"
+
+
+def test_listener_actions_with_target_group_replaces_forward_arn():
+    actions = [
+        {"Type": "authenticate-cognito", "Order": 1},
+        {
+            "Type": "forward",
+            "Order": 2,
+            "TargetGroupArn": "arn:old",
+            "ForwardConfig": {"TargetGroups": [{"TargetGroupArn": "arn:old"}]},
+        },
+    ]
+    updated = post.listener_actions_with_target_group(actions, "arn:new")
+    forward = next(action for action in updated if action["Type"] == "forward")
+    assert forward["TargetGroupArn"] == "arn:new"
+    assert forward["ForwardConfig"]["TargetGroups"][0]["TargetGroupArn"] == "arn:new"
+
+
+def test_cognito_secret_payload_matches():
+    desired = {
+        "SUMMARISATION_USER_POOL_ID": "eu-west-2_AAAA",
+        "SUMMARISATION_CLIENT_ID": "client",
+        "SUMMARISATION_CLIENT_SECRET": "secret",
+    }
+    current = json.dumps(
+        {
+            "SUMMARISATION_USER_POOL_ID": "eu-west-2_OLD",
+            "SUMMARISATION_CLIENT_ID": "client",
+            "SUMMARISATION_CLIENT_SECRET": "secret",
+        }
+    )
+    assert post.cognito_secret_payload_matches(current, desired) is False
+    assert post.cognito_secret_payload_matches(json.dumps(desired), desired) is True
+
+
+def test_listener_rule_has_cognito_auth():
+    assert post.listener_rule_has_cognito_auth(
+        [{"Type": "authenticate-cognito"}, {"Type": "forward"}]
+    )
+    assert not post.listener_rule_has_cognito_auth([{"Type": "forward"}])
+
+
+def test_print_express_mode_next_steps(capsys, monkeypatch):
+    def fake_get_stack_output(stack_name, output_key, region):
+        outputs = {
+            "ExpressServiceEndpoint": "main.example.ecs.eu-west-2.on.aws",
+            "PiExpressEndpoint": "pi.example.ecs.eu-west-2.on.aws",
+        }
+        return outputs.get(output_key)
+
+    monkeypatch.setattr(post, "get_stack_output", fake_get_stack_output)
+    post.print_express_mode_next_steps(
+        {
+            "AWS_REGION": "eu-west-2",
+            "ENABLE_PI_AGENT_EXPRESS_SERVICE": "True",
+        }
+    )
+    out = capsys.readouterr().out
+    assert "Wait 10 minutes for app deployment to finish." in out
+    assert "Cognito authorisation" not in out
+    assert "sign in at the Pi agent URL" in out
+    assert "https://main.example.ecs.eu-west-2.on.aws" in out
+    assert "https://pi.example.ecs.eu-west-2.on.aws/" in out
+    assert "pi_agent.env" not in out
+
+
+def test_print_headless_deployment_next_steps(capsys):
+    post.print_headless_deployment_next_steps(
+        {
+            "AWS_REGION": "eu-west-2",
+            "S3_OUTPUT_BUCKET_NAME": "my-output-bucket",
+            "S3_BATCH_INPUT_PREFIX": "input/",
+            "S3_BATCH_ENV_PREFIX": "input/config/",
+            "S3_BATCH_LAMBDA_FUNCTION_NAME": "Headless-Summarisation-S3BatchEcsTrigger",
+            "ECS_LOG_GROUP_NAME": "/ecs/headless-summarisation-ecsservice-logs",
+        }
+    )
+    out = capsys.readouterr().out
+    assert (
+        "Upload a consultation spreadsheet (.xlsx) to s3://my-output-bucket/input/"
+        in out
+    )
+    assert "example_headless_env_file.env" in out
+    assert "s3://my-output-bucket/input/config/" in out
+    assert "Headless-Summarisation-S3BatchEcsTrigger" in out
+    assert "s3://my-output-bucket/output/<session-folder>/" in out
+    assert "tools/config.py" in out
+
+
+def test_seed_headless_batch_s3_layout_creates_prefixes(tmp_path):
+    from botocore.exceptions import ClientError
+
+    example = tmp_path / "example_headless_env_file.env"
+    example.write_text("DIRECT_MODE_TASK=redact\n", encoding="utf-8")
+
+    missing = ClientError(
+        {"Error": {"Code": "404", "Message": "Not Found"}},
+        "HeadObject",
+    )
+    s3 = MagicMock()
+    s3.head_object.side_effect = missing
+
+    with patch("cdk_post_deploy.boto3.client", return_value=s3):
+        post.seed_headless_batch_s3_layout(
+            "my-bucket",
+            example_env_local_path=str(example),
+            aws_region="eu-west-2",
+        )
+
+    put_calls = s3.put_object.call_args_list
+    assert len(put_calls) == 3
+    keys = [call.kwargs["Key"] for call in put_calls]
+    assert "input/" in keys
+    assert "input/config/" in keys
+    assert "input/config/example_headless_env_file.env" in keys

cdk/test/test_cdk_synth_express.py

@@ -0,0 +1,155 @@
+"""Template assertions for legacy vs ECS Express Mode CDK paths."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+REPO_ROOT = CDK_DIR.parent
+sys.path.insert(0, str(CDK_DIR))
+
+
+def _load_template(env_overrides: dict) -> dict:
+    """Synth SummarisationStack with mocked config and pre-check context."""
+    os.environ["CDK_CONFIG_PATH"] = str(CDK_DIR / "config" / "cdk_config.env")
+    os.environ["CONTEXT_FILE"] = str(CDK_DIR / "precheck.context.json")
+
+    import importlib
+
+    for mod_name in list(sys.modules):
+        if mod_name in ("cdk_config", "cdk_stack", "app") or mod_name.startswith(
+            "cdk_"
+        ):
+            del sys.modules[mod_name]
+
+    with patch.dict(os.environ, env_overrides, clear=False):
+        import cdk_config as cfg
+
+        importlib.reload(cfg)
+        with patch.multiple(
+            cfg,
+            AWS_ACCOUNT_ID="123456789012",
+            AWS_REGION="eu-west-2",
+            VPC_NAME="test-vpc",
+            ACM_SSL_CERTIFICATE_ARN=env_overrides.get(
+                "ACM_SSL_CERTIFICATE_ARN", cfg.ACM_SSL_CERTIFICATE_ARN
+            ),
+            USE_ECS_EXPRESS_MODE=env_overrides.get(
+                "USE_ECS_EXPRESS_MODE", cfg.USE_ECS_EXPRESS_MODE
+            ),
+            USE_CLOUDFRONT=env_overrides.get("USE_CLOUDFRONT", "False"),
+            RUN_USEAST_STACK="False",
+            ENABLE_APPREGISTRY="False",
+        ):
+            from aws_cdk import App, Environment, Stack
+            from aws_cdk import aws_ec2 as ec2
+            from aws_cdk import aws_ecs as ecs
+            from aws_cdk import aws_elasticloadbalancingv2 as elbv2
+
+            app = App()
+            stack = Stack(
+                app,
+                "Test",
+                env=Environment(account="123456789012", region="eu-west-2"),
+            )
+
+            use_express = (
+                not env_overrides.get("ACM_SSL_CERTIFICATE_ARN", "")
+                and env_overrides.get("USE_ECS_EXPRESS_MODE") == "True"
+            )
+            if use_express:
+                ecs.CfnExpressGatewayService(
+                    stack,
+                    "Express",
+                    execution_role_arn="arn:aws:iam::123456789012:role/exec",
+                    infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+                    primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+                        image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest"
+                    ),
+                )
+            else:
+                vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+                alb = elbv2.ApplicationLoadBalancer(stack, "Alb", vpc=vpc)
+                cluster = ecs.Cluster(stack, "Cluster", vpc=vpc)
+                td = ecs.FargateTaskDefinition(
+                    stack, "Td", memory_limit_mib=512, cpu=256
+                )
+                td.add_container("c", image=ecs.ContainerImage.from_registry("nginx"))
+                ecs.FargateService(
+                    stack,
+                    "Svc",
+                    cluster=cluster,
+                    task_definition=td,
+                )
+                alb.add_listener(
+                    "Http",
+                    port=80,
+                    default_action=elbv2.ListenerAction.fixed_response(
+                        status_code=403,
+                        content_type="text/plain",
+                        message_body="deny",
+                    ),
+                )
+
+            assembly = app.synth()
+            stack_art = assembly.get_stack_by_name("Test")
+            template_path = Path(assembly.directory) / stack_art.template_file
+            return json.loads(template_path.read_text(encoding="utf-8"))
+
+
+@pytest.mark.parametrize(
+    "env,expect_express,expect_manual_alb",
+    [
+        (
+            {
+                "USE_ECS_EXPRESS_MODE": "True",
+                "ACM_SSL_CERTIFICATE_ARN": "",
+            },
+            True,
+            False,
+        ),
+        (
+            {
+                "USE_ECS_EXPRESS_MODE": "False",
+                "ACM_SSL_CERTIFICATE_ARN": "arn:aws:acm:eu-west-2:123:certificate/abc",
+            },
+            False,
+            True,
+        ),
+    ],
+)
+def test_branching_resource_types(env, expect_express, expect_manual_alb):
+    template = _load_template(env)
+    resources = template.get("Resources", {})
+    types = {r.get("Type") for r in resources.values()}
+    if expect_express:
+        assert "AWS::ECS::ExpressGatewayService" in types
+        assert "AWS::ElasticLoadBalancingV2::LoadBalancer" not in types
+    if expect_manual_alb:
+        assert "AWS::ElasticLoadBalancingV2::LoadBalancer" in types
+        assert "AWS::ECS::ExpressGatewayService" not in types
+
+
+def test_config_mutual_exclusion_raises():
+    use_express = "True"
+    acm_arn = "arn:aws:acm:eu-west-2:123:certificate/x"
+    with pytest.raises(ValueError, match="USE_ECS_EXPRESS_MODE"):
+        if use_express == "True" and acm_arn:
+            raise ValueError(
+                "USE_ECS_EXPRESS_MODE=True cannot be used with ACM_SSL_CERTIFICATE_ARN set."
+            )
+
+
+def test_legacy_pi_on_express_error_message():
+    legacy_pi = "True"
+    use_express = "True"
+    with pytest.raises(ValueError, match="ENABLE_PI_AGENT_EXPRESS_SERVICE"):
+        if legacy_pi == "True" and use_express == "True":
+            raise ValueError(
+                "ENABLE_PI_AGENT_ECS_SERVICE=True requires legacy Fargate (USE_ECS_EXPRESS_MODE=False). "
+                "For Pi on Express, use ENABLE_PI_AGENT_EXPRESS_SERVICE=True instead."
+            )

cdk/test/test_cloudfront_csp.py

@@ -0,0 +1,61 @@
+"""Tests for CloudFront CSP / response headers helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_cloudfront_headers import (
+    build_content_security_policy,
+    cognito_hosted_ui_base_url,
+    normalize_https_origin,
+    resolve_cloudfront_csp_urls,
+)
+
+
+def test_normalize_https_origin():
+    assert (
+        normalize_https_origin("d111.cloudfront.net") == "https://d111.cloudfront.net"
+    )
+    assert normalize_https_origin("https://summarisation.example.com/") == (
+        "https://summarisation.example.com"
+    )
+
+
+def test_build_content_security_policy_substitutes_hosts():
+    csp = build_content_security_policy(
+        app_origin="https://d111.cloudfront.net",
+        cognito_login_url="https://my-prefix.auth.eu-west-2.amazoncognito.com",
+    )
+    assert "wss://d111.cloudfront.net" in csp
+    assert "https://my-prefix.auth.eu-west-2.amazoncognito.com" in csp
+    assert "cdnjs.cloudflare.com" in csp
+
+
+def test_resolve_cloudfront_csp_urls_prefers_cognito_redirection():
+    app_origin, login = resolve_cloudfront_csp_urls(
+        cognito_redirection_url="https://summarisation.example.com",
+        cloudfront_domain="d111.cloudfront.net",
+        cognito_user_pool_domain_prefix="my-prefix",
+        aws_region="eu-west-2",
+    )
+    assert app_origin == "https://summarisation.example.com"
+    assert login == "https://my-prefix.auth.eu-west-2.amazoncognito.com"
+
+
+def test_resolve_cloudfront_csp_urls_login_override():
+    _, login = resolve_cloudfront_csp_urls(
+        cognito_redirection_url="https://app.example.com",
+        cloudfront_domain="d111.cloudfront.net",
+        cognito_user_pool_domain_prefix="my-prefix",
+        aws_region="eu-west-2",
+        cognito_user_pool_login_url="https://custom-login.example.com",
+    )
+    assert login == "https://custom-login.example.com"
+
+
+def test_cognito_hosted_ui_base_url():
+    assert cognito_hosted_ui_base_url("summarisation-123", "eu-west-1") == (
+        "https://summarisation-123.auth.eu-west-1.amazoncognito.com"
+    )

cdk/test/test_codebuild_public_github_source.py

@@ -0,0 +1,60 @@
+"""CodeBuild public GitHub source helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from aws_cdk import App, Stack
+from aws_cdk import aws_codebuild as codebuild
+from aws_cdk import aws_iam as iam
+from aws_cdk.assertions import Template
+from cdk_functions import (
+    configure_public_github_codebuild_source,
+    public_github_codebuild_source,
+    public_github_repository_url,
+)
+
+
+def test_public_github_repository_url():
+    assert (
+        public_github_repository_url("seanpedrick-case", "llm_topic_modeller")
+        == "https://github.com/seanpedrick-case/llm_topic_modeller.git"
+    )
+
+
+def test_public_github_codebuild_source_synth_without_auth():
+    app = App()
+    stack = Stack(app, "Test")
+    role = iam.Role(
+        stack, "Role", assumed_by=iam.ServicePrincipal("codebuild.amazonaws.com")
+    )
+    project = codebuild.Project(
+        stack,
+        "Proj",
+        role=role,
+        source=public_github_codebuild_source("owner", "repo", "main"),
+        build_spec=codebuild.BuildSpec.from_object(
+            {"version": "0.2", "phases": {"build": {"commands": ["echo hi"]}}}
+        ),
+    )
+    configure_public_github_codebuild_source(project, "owner", "repo", "main")
+
+    template = Template.from_stack(stack)
+    resources = template.to_json()["Resources"]
+    project_resource = next(
+        value
+        for value in resources.values()
+        if value["Type"] == "AWS::CodeBuild::Project"
+    )
+    source = project_resource["Properties"]["Source"]
+    triggers = project_resource["Properties"]["Triggers"]
+
+    assert "Auth" not in source
+    assert source["Type"] == "GITHUB"
+    assert source["Location"] == "https://github.com/owner/repo.git"
+    assert source["ReportBuildStatus"] is False
+    assert source["GitCloneDepth"] == 1
+    assert project_resource["Properties"]["SourceVersion"] == "main"
+    assert triggers["Webhook"] is False

cdk/test/test_delete_protection_config.py

@@ -0,0 +1,52 @@
+"""Tests for ENABLE_RESOURCE_DELETE_PROTECTION helpers."""
+
+import importlib
+
+import pytest
+from aws_cdk import RemovalPolicy
+
+
+@pytest.mark.parametrize(
+    ("env_value", "enabled"),
+    [
+        ("True", True),
+        ("true", True),
+        ("1", True),
+        ("yes", True),
+        ("False", False),
+        ("false", False),
+        ("0", False),
+    ],
+)
+def test_delete_protection_helpers(monkeypatch, env_value, enabled, tmp_path):
+    monkeypatch.setenv("ENABLE_RESOURCE_DELETE_PROTECTION", env_value)
+    monkeypatch.setenv("CDK_CONFIG_PATH", str(tmp_path / "missing_cdk_config.env"))
+
+    import cdk_config
+
+    importlib.reload(cdk_config)
+    import cdk_functions
+
+    importlib.reload(cdk_functions)
+
+    assert cdk_functions.is_resource_delete_protection_enabled() is enabled
+    assert cdk_functions.resource_deletion_protection_flag() is enabled
+    assert cdk_functions.managed_resource_removal_policy() == (
+        RemovalPolicy.RETAIN if enabled else RemovalPolicy.DESTROY
+    )
+    assert cdk_functions.s3_auto_delete_objects_on_stack_destroy() is (not enabled)
+    assert cdk_functions.ecr_empty_on_delete() is (not enabled)
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("de-abc.ecs.eu-west-2.on.aws", "https://de-abc.ecs.eu-west-2.on.aws"),
+        ("https://app.example.com/", "https://app.example.com"),
+        ("http://app.example.com", "https://app.example.com"),
+    ],
+)
+def test_normalize_https_redirect_url(raw, expected):
+    import cdk_config
+
+    assert cdk_config.normalize_https_redirect_url(raw) == expected

cdk/test/test_dynamo_usage_log_export.py

@@ -0,0 +1,129 @@
+"""Tests for scheduled DynamoDB usage log export Lambda and installer schedule helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_build_dynamo_export_cron_expression():
+    import cdk_install as inst
+
+    assert inst.build_dynamo_export_cron_expression(6, 0, "daily") == (
+        "cron(0 6 ? * * *)"
+    )
+    assert inst.build_dynamo_export_cron_expression(7, 30, "weekdays") == (
+        "cron(30 7 ? * MON-FRI *)"
+    )
+    assert inst.build_dynamo_export_cron_expression(0, 15, "weekends") == (
+        "cron(15 0 ? * SAT-SUN *)"
+    )
+
+
+def test_validate_schedule_time_hhmm():
+    import cdk_install as inst
+
+    assert inst.validate_schedule_time_hhmm("06:00") is None
+    assert inst.validate_schedule_time_hhmm("25:00") is not None
+    assert inst.validate_schedule_time_hhmm("bad") is not None
+
+
+def test_build_env_values_includes_dynamo_export_schedule():
+    import cdk_install as inst
+
+    answers = inst.InstallAnswers(
+        profile="demo",
+        aws_account_id="123456789012",
+        aws_region="eu-west-2",
+        cdk_prefix="Test-Summarisation-",
+        cognito_domain_prefix="test-summarisation",
+        vpc_mode="existing",
+        vpc_name="test-vpc",
+        enable_dynamo_usage_log_export=True,
+        dynamo_export_schedule_time="07:30",
+        dynamo_export_schedule_days="weekdays",
+        dynamo_export_s3_key="reports/usage.csv",
+    )
+    values = inst.build_env_values(answers)
+    assert values["ENABLE_DYNAMODB_USAGE_LOG_EXPORT"] == "True"
+    assert values["DYNAMODB_USAGE_LOG_EXPORT_SCHEDULE"] == ("cron(30 7 ? * MON-FRI *)")
+    assert values["DYNAMODB_USAGE_LOG_EXPORT_S3_KEY"] == "reports/usage.csv"
+
+
+def test_validate_env_values_rejects_dynamo_export_without_dynamodb_logging():
+    import cdk_install as inst
+
+    values = inst.build_env_values(
+        inst.InstallAnswers(
+            profile="demo",
+            aws_account_id="123456789012",
+            aws_region="eu-west-2",
+            cdk_prefix="Test-Summarisation-",
+            cognito_domain_prefix="test-summarisation",
+            vpc_mode="existing",
+            vpc_name="test-vpc",
+            enable_dynamo_usage_log_export=True,
+        )
+    )
+    values["SAVE_LOGS_TO_DYNAMODB"] = "False"
+    errors = inst.validate_env_values(values)
+    assert any("ENABLE_DYNAMODB_USAGE_LOG_EXPORT" in e for e in errors)
+
+
+def test_dynamo_usage_log_export_lambda_synth():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_dynamodb as dynamodb
+    from aws_cdk import aws_s3 as s3
+    from aws_cdk.assertions import Match, Template
+    from cdk_functions import create_dynamo_usage_log_export_lambda
+
+    app = App()
+    stack = Stack(
+        app,
+        "DynamoExportTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    table = dynamodb.Table(
+        stack,
+        "UsageTable",
+        partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
+    )
+    bucket = s3.Bucket(stack, "OutputBucket")
+
+    create_dynamo_usage_log_export_lambda(
+        stack,
+        "DynamoUsageLogExport",
+        function_name="test-dynamo-usage-export",
+        lambda_asset_path=str(CDK_DIR / "lambda_dynamo_logs_export"),
+        dynamodb_table=table,
+        output_bucket=bucket,
+        s3_output_key="reports/dynamodb-usage/dynamodb_logs_export.csv",
+        schedule_expression="cron(0 6 ? * MON-FRI *)",
+        dynamodb_table_name="test-usage-logs",
+        date_attribute="timestamp",
+    )
+
+    template = Template.from_stack(stack)
+    template.resource_count_is("AWS::Lambda::Function", 1)
+    template.resource_count_is("AWS::Events::Rule", 1)
+    template.has_resource_properties(
+        "AWS::Lambda::Function",
+        {
+            "Handler": "lambda_function.lambda_handler",
+            "Environment": {
+                "Variables": Match.object_like(
+                    {
+                        "DYNAMODB_TABLE_NAME": "test-usage-logs",
+                        "S3_OUTPUT_KEY": (
+                            "reports/dynamodb-usage/dynamodb_logs_export.csv"
+                        ),
+                    }
+                )
+            },
+        },
+    )
+    template.has_resource_properties(
+        "AWS::Events::Rule",
+        {"ScheduleExpression": "cron(0 6 ? * MON-FRI *)"},
+    )

cdk/test/test_ecs_vpc_endpoints.py

@@ -0,0 +1,400 @@
+"""ECS VPC endpoint helpers (task-subnet aligned: public for Express + public subnets)."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_create_ecs_vpc_endpoints_synth_interface_and_s3_gateway():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "VpcEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    # 5 interface endpoints + 1 S3 gateway endpoint
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 6)
+    template.has_resource_properties(
+        "AWS::EC2::VPCEndpoint",
+        {"VpcEndpointType": "Interface", "PrivateDnsEnabled": True},
+    )
+    template.has_resource_properties(
+        "AWS::EC2::VPCEndpoint",
+        {"VpcEndpointType": "Gateway"},
+    )
+
+
+def test_imported_vpc_from_attributes_requires_cidr_block():
+    """Imported VPCs must pass vpc_cidr_block or endpoint/SG helpers fail at synth."""
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+
+    app = App()
+    stack = Stack(app, "ImportedVpcTest")
+    vpc = ec2.Vpc.from_vpc_attributes(
+        stack,
+        "ImportedVpc",
+        vpc_id="vpc-12345678",
+        availability_zones=["eu-west-2a", "eu-west-2b"],
+        vpc_cidr_block="10.0.0.0/16",
+    )
+    assert vpc.vpc_cidr_block == "10.0.0.0/16"
+
+
+def test_create_ecs_vpc_endpoints_skips_existing_service_names():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "SkipEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    skip = frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.secretsmanager",
+        }
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        skip_service_names=skip,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 4)
+
+
+def test_create_ecs_vpc_endpoints_skips_precheck_shared_vpc_endpoints():
+    """Regression: skip list must use AWS ServiceName strings, not CDK service.name tokens."""
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "SharedVpcSkipTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private = ec2.SubnetSelection(
+        subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
+    )
+    precheck_skip = frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.s3",
+            "com.amazonaws.eu-west-2.secretsmanager",
+        }
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=private,
+        skip_service_names=precheck_skip,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    # ecr.api, ecr.dkr, logs only (kms, secretsmanager, s3 skipped)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 3)
+
+
+def test_list_existing_vpc_endpoint_service_names(monkeypatch):
+    from cdk_functions import list_existing_vpc_endpoint_service_names
+
+    class FakePaginator:
+        def paginate(self, **kwargs):
+            return [
+                {
+                    "VpcEndpoints": [
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.kms",
+                            "State": "available",
+                        },
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.s3",
+                            "State": "available",
+                        },
+                        {
+                            "ServiceName": "com.amazonaws.eu-west-2.ecr.api",
+                            "State": "deleted",
+                        },
+                    ]
+                }
+            ]
+
+    class FakeEc2:
+        def get_paginator(self, name):
+            assert name == "describe_vpc_endpoints"
+            return FakePaginator()
+
+    monkeypatch.setattr(
+        "cdk_functions.boto3.client",
+        lambda service, region_name=None: FakeEc2(),
+    )
+    names = list_existing_vpc_endpoint_service_names("vpc-123", region_name="eu-west-2")
+    assert names == frozenset(
+        {
+            "com.amazonaws.eu-west-2.kms",
+            "com.amazonaws.eu-west-2.s3",
+        }
+    )
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_express_public():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=True,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert public_sel is not None
+    assert {s.subnet_id for s in public_sel.subnets} == {
+        s.subnet_id for s in vpc.public_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_express_private():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectPrivateTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=True,
+        express_use_public_subnets=False,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert private_sel is not None
+    assert {s.subnet_id for s in private_sel.subnets} == {
+        s.subnet_id for s in vpc.private_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_legacy_fargate():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectLegacyTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    private_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=False,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert private_sel is not None
+    assert {s.subnet_id for s in private_sel.subnets} == {
+        s.subnet_id for s in vpc.private_subnets
+    }
+
+
+def test_resolve_ecs_vpc_endpoint_subnet_selection_public_only_legacy():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_vpc_endpoint_subnet_selection
+
+    app = App()
+    stack = Stack(app, "SubnetSelectPublicOnlyTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public_sel = resolve_ecs_vpc_endpoint_subnet_selection(
+        use_express_ingress=False,
+        express_use_public_subnets=True,
+        public_subnets=vpc.public_subnets,
+        private_subnets=[],
+    )
+    assert public_sel is not None
+    assert {s.subnet_id for s in public_sel.subnets} == {
+        s.subnet_id for s in vpc.public_subnets
+    }
+
+
+def test_create_ecs_vpc_endpoints_on_public_subnets():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import create_ecs_vpc_endpoints_for_private_subnets
+
+    app = App()
+    stack = Stack(app, "PublicEndpointTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public = ec2.SubnetSelection(subnet_type=ec2.SubnetType.PUBLIC)
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=public,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::EC2::VPCEndpoint", 6)
+    public_logical_ids = {
+        stack.get_logical_id(s.node.default_child) for s in vpc.public_subnets
+    }
+    interface_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Interface"
+    ]
+    assert len(interface_endpoints) == 5
+    for resource in interface_endpoints:
+        subnet_ids = resource["Properties"]["SubnetIds"]
+        assert len(subnet_ids) == len(vpc.public_subnets)
+        for ref in subnet_ids:
+            assert ref.get("Ref") in public_logical_ids
+
+
+def test_resolve_ecs_s3_gateway_subnet_selection_all_stack_subnets():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import resolve_ecs_s3_gateway_subnet_selection
+
+    app = App()
+    stack = Stack(app, "S3SubnetSelectTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    s3_sel = resolve_ecs_s3_gateway_subnet_selection(
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    assert s3_sel is not None
+    expected_ids = {s.subnet_id for s in vpc.public_subnets + vpc.private_subnets}
+    assert {s.subnet_id for s in s3_sel.subnets} == expected_ids
+
+
+def test_s3_gateway_endpoint_uses_all_stack_subnets_not_only_task_tier():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import (
+        create_ecs_vpc_endpoints_for_private_subnets,
+        resolve_ecs_s3_gateway_subnet_selection,
+    )
+
+    app = App()
+    stack = Stack(app, "MixedS3GatewayTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    public = ec2.SubnetSelection(subnets=vpc.public_subnets)
+    all_stack_subnets = resolve_ecs_s3_gateway_subnet_selection(
+        public_subnets=vpc.public_subnets,
+        private_subnets=vpc.private_subnets,
+    )
+    create_ecs_vpc_endpoints_for_private_subnets(
+        stack,
+        vpc=vpc,
+        subnets=public,
+        s3_gateway_subnets=all_stack_subnets,
+        include_secrets_and_kms=True,
+        aws_region="eu-west-2",
+    )
+    template = assertions.Template.from_stack(stack)
+    gateway_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Gateway"
+    ]
+    assert len(gateway_endpoints) == 1
+    route_table_ids = gateway_endpoints[0]["Properties"]["RouteTableIds"]
+    assert len(route_table_ids) == len(vpc.public_subnets) + len(vpc.private_subnets)
+    interface_endpoints = [
+        r
+        for r in template.find_resources("AWS::EC2::VPCEndpoint").values()
+        if r.get("Properties", {}).get("VpcEndpointType") == "Interface"
+    ]
+    public_logical_ids = {
+        stack.get_logical_id(s.node.default_child) for s in vpc.public_subnets
+    }
+    for resource in interface_endpoints:
+        for ref in resource["Properties"]["SubnetIds"]:
+            assert ref.get("Ref") in public_logical_ids
+
+
+def test_list_vpc_associated_cidr_blocks_primary_and_secondary():
+    from cdk_functions import list_vpc_associated_cidr_blocks
+
+    vpc = {
+        "CidrBlock": "10.0.0.0/16",
+        "CidrBlockAssociationSet": [
+            {
+                "CidrBlock": "10.0.0.0/16",
+                "CidrBlockState": {"State": "associated"},
+            },
+            {
+                "CidrBlock": "10.1.0.0/16",
+                "CidrBlockState": {"State": "associated"},
+            },
+        ],
+    }
+    assert list_vpc_associated_cidr_blocks(vpc) == [
+        "10.0.0.0/16",
+        "10.1.0.0/16",
+    ]
+
+
+def test_vpc_endpoint_security_group_ingress_covers_all_vpc_cidrs():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from cdk_functions import add_vpc_endpoint_https_ingress_from_vpc_cidrs
+
+    app = App()
+    stack = Stack(app, "DualCidrEndpointSgTest")
+    vpc = ec2.Vpc.from_vpc_attributes(
+        stack,
+        "ImportedVpc",
+        vpc_id="vpc-dual-cidr",
+        availability_zones=["eu-west-2a"],
+        vpc_cidr_block="10.0.0.0/16",
+    )
+    endpoint_sg = ec2.SecurityGroup(
+        stack,
+        "EndpointSg",
+        vpc=vpc,
+        description="test",
+    )
+    add_vpc_endpoint_https_ingress_from_vpc_cidrs(
+        endpoint_sg,
+        vpc_cidr_block="10.0.0.0/16",
+        vpc_cidr_blocks=["10.0.0.0/16", "10.1.0.0/16"],
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::EC2::SecurityGroup",
+        {
+            "SecurityGroupIngress": assertions.Match.array_with(
+                [
+                    assertions.Match.object_like(
+                        {"CidrIp": "10.0.0.0/16", "FromPort": 443, "ToPort": 443}
+                    ),
+                    assertions.Match.object_like(
+                        {"CidrIp": "10.1.0.0/16", "FromPort": 443, "ToPort": 443}
+                    ),
+                ]
+            )
+        },
+    )

cdk/test/test_elbv2_listener_rule_upsert.py

@@ -0,0 +1,86 @@
+"""Unit tests for ALB listener rule upsert Lambda helpers."""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_LAMBDA_PATH = (
+    Path(__file__).resolve().parents[1]
+    / "lambda_elbv2_listener_rule_upsert"
+    / "lambda_function.py"
+)
+_spec = importlib.util.spec_from_file_location(
+    "elbv2_listener_rule_upsert", _LAMBDA_PATH
+)
+_mod = importlib.util.module_from_spec(_spec)
+assert _spec and _spec.loader
+sys.modules[_spec.name] = _mod
+_spec.loader.exec_module(_mod)
+
+
+def test_conditions_match_path_pattern():
+    expected = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+        }
+    ]
+    from_api = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+            "Values": ["/agent", "/agent/*"],
+        }
+    ]
+    assert _mod._conditions_match(from_api, expected)
+
+
+def test_conditions_do_not_match_different_path():
+    expected = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/agent", "/agent/*"]},
+        }
+    ]
+    other = [
+        {
+            "Field": "path-pattern",
+            "PathPatternConfig": {"Values": ["/other", "/other/*"]},
+        }
+    ]
+    assert not _mod._conditions_match(other, expected)
+
+
+def test_normalize_listener_rule_payload_coerces_cfn_string_types():
+    raw_actions = [
+        {
+            "Type": "authenticate-cognito",
+            "Order": "1",
+            "AuthenticateCognitoConfig": {
+                "UserPoolArn": "arn:aws:cognito-idp:eu-west-2:1:userpool/pool",
+                "UserPoolClientId": "client",
+                "UserPoolDomain": "demo",
+                "SessionTimeout": "28800",
+            },
+        },
+        {
+            "Type": "forward",
+            "Order": "2",
+            "ForwardConfig": {
+                "TargetGroups": [
+                    {"TargetGroupArn": "arn:aws:elasticloadbalancing:1:tg"}
+                ],
+                "TargetGroupStickinessConfig": {
+                    "Enabled": "true",
+                    "DurationSeconds": "28800",
+                },
+            },
+        },
+    ]
+    _, actions = _mod._normalize_listener_rule_payload([], raw_actions)
+    assert actions[0]["Order"] == 1
+    assert actions[0]["AuthenticateCognitoConfig"]["SessionTimeout"] == 28800
+    assert actions[1]["Order"] == 2
+    stickiness = actions[1]["ForwardConfig"]["TargetGroupStickinessConfig"]
+    assert stickiness["Enabled"] is True
+    assert stickiness["DurationSeconds"] == 28800

cdk/test/test_ensure_codebuild_public_github.py

@@ -0,0 +1,81 @@
+"""Tests for runtime CodeBuild public GitHub source fixup."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import ensure_codebuild_public_github_source
+
+
+def test_ensure_codebuild_updates_oauth_project(monkeypatch):
+    client = MagicMock()
+    client.batch_get_projects.return_value = {
+        "projects": [
+            {
+                "name": "MyProject",
+                "source": {
+                    "type": "GITHUB",
+                    "location": "https://github.com/old/repo.git",
+                    "auth": {"type": "CODECONNECTIONS", "resource": "arn:connection"},
+                    "reportBuildStatus": True,
+                    "buildspec": "version: 0.2\nphases: {}\n",
+                },
+                "sourceVersion": "main",
+                "triggers": {"webhook": True},
+            }
+        ]
+    }
+    monkeypatch.setattr("cdk_functions.boto3.client", lambda *args, **kwargs: client)
+
+    updated = ensure_codebuild_public_github_source(
+        "MyProject",
+        "seanpedrick-case",
+        "llm_topic_modeller",
+        "main",
+        aws_region="eu-west-2",
+    )
+
+    assert updated is True
+    client.update_project.assert_called_once()
+    kwargs = client.update_project.call_args.kwargs
+    assert kwargs["name"] == "MyProject"
+    assert kwargs["source"]["type"] == "GITHUB"
+    assert (
+        kwargs["source"]["location"]
+        == "https://github.com/seanpedrick-case/llm_topic_modeller.git"
+    )
+    assert "auth" not in kwargs["source"]
+    assert kwargs["sourceVersion"] == "main"
+    assert kwargs["triggers"] == {"webhook": False}
+
+
+def test_ensure_codebuild_skips_when_already_public(monkeypatch):
+    client = MagicMock()
+    client.batch_get_projects.return_value = {
+        "projects": [
+            {
+                "name": "MyProject",
+                "source": {
+                    "type": "GITHUB",
+                    "location": "https://github.com/seanpedrick-case/llm_topic_modeller.git",
+                    "reportBuildStatus": False,
+                },
+                "sourceVersion": "main",
+            }
+        ]
+    }
+    monkeypatch.setattr("cdk_functions.boto3.client", lambda *args, **kwargs: client)
+
+    updated = ensure_codebuild_public_github_source(
+        "MyProject",
+        "seanpedrick-case",
+        "llm_topic_modeller",
+        "main",
+        aws_region="eu-west-2",
+    )
+
+    assert updated is False
+    client.update_project.assert_not_called()

cdk/test/test_execution_role_kms_policy.py

@@ -0,0 +1,100 @@
+"""ECS task vs execution role KMS inline policy helpers."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_task_and_execution_role_kms_policies_use_different_key_arns():
+    from cdk_functions import (
+        build_ecs_execution_role_kms_policy,
+        build_ecs_task_role_kms_policy,
+    )
+
+    s3_key = "arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key"
+    secret_key = "arn:aws:kms:eu-west-2:123456789012:key/secret-key"
+
+    task_policy = build_ecs_task_role_kms_policy(shared_kms_key_arn=s3_key)
+    exec_policy = build_ecs_execution_role_kms_policy(secret_kms_key_arn=secret_key)
+
+    task_kms = next(
+        s for s in task_policy["Statement"] if s.get("Sid") == "KMSS3Access"
+    )
+    secret_kms = next(
+        s for s in exec_policy["Statement"] if s.get("Sid") == "KMSSecretDecrypt"
+    )
+
+    assert task_kms["Resource"] == s3_key
+    assert secret_kms["Resource"] == secret_key
+    assert "kms:GenerateDataKey" in task_kms["Action"]
+    assert "kms:DescribeKey" in task_kms["Action"]
+    assert secret_kms["Action"] == ["kms:Decrypt"]
+
+
+def test_task_role_inline_policy_scopes_s3_to_output_and_log_buckets():
+    from cdk_functions import build_ecs_task_role_inline_policy
+
+    policy = build_ecs_task_role_inline_policy(
+        output_bucket_name="lambeth-aws-sharedservices-prod-summarisation-s3-output",
+        log_config_bucket_name="lambeth-aws-sharedservices-prod-summarisation-s3-logs",
+        shared_kms_key_arn="arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key",
+    )
+    s3_statements = [
+        s for s in policy["Statement"] if s.get("Sid", "").startswith("S3")
+    ]
+    assert len(s3_statements) == 2
+    output_stmt = next(s for s in s3_statements if s["Sid"] == "S3Output")
+    log_stmt = next(s for s in s3_statements if s["Sid"] == "S3LogConfig")
+    assert output_stmt["Action"] == [
+        "s3:GetObject*",
+        "s3:GetBucket*",
+        "s3:PutObject",
+        "s3:DeleteObject",
+        "s3:List*",
+    ]
+    assert output_stmt["Resource"] == [
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-output",
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-output/*",
+    ]
+    assert log_stmt["Resource"] == [
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-logs",
+        "arn:aws:s3:::lambeth-aws-sharedservices-prod-summarisation-s3-logs/*",
+    ]
+    kms_stmt = next(s for s in policy["Statement"] if s.get("Sid") == "KMSS3Access")
+    assert (
+        kms_stmt["Resource"] == "arn:aws:kms:eu-west-2:123456789012:key/s3-shared-key"
+    )
+
+
+def test_execution_role_policy_without_custom_s3_key_uses_secret_kms_only():
+    from cdk_functions import build_ecs_execution_role_kms_policy
+
+    secret_key = "arn:aws:kms:eu-west-2:123456789012:key/aws/secretsmanager"
+    policy = build_ecs_execution_role_kms_policy(secret_kms_key_arn=secret_key)
+    kms_statements = [
+        s for s in policy["Statement"] if s.get("Action") == ["kms:Decrypt"]
+    ]
+    assert len(kms_statements) == 1
+    assert kms_statements[0]["Resource"] == secret_key
+
+
+def test_get_secret_kms_key_arn_from_describe_secret(monkeypatch):
+    from cdk_functions import get_secret_kms_key_arn
+
+    class FakeSecretsManager:
+        def describe_secret(self, SecretId):
+            assert SecretId == "my-secret"
+            return {
+                "KmsKeyId": "arn:aws:kms:eu-west-2:123456789012:key/abc-123",
+            }
+
+    monkeypatch.setattr(
+        "cdk_functions.boto3.client",
+        lambda service, region_name=None: FakeSecretsManager(),
+    )
+    assert (
+        get_secret_kms_key_arn("my-secret", region_name="eu-west-2")
+        == "arn:aws:kms:eu-west-2:123456789012:key/abc-123"
+    )

cdk/test/test_express_app_config_env.py

@@ -0,0 +1,25 @@
+"""Tests for loading config/app_config.env into Express container environment."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import load_app_config_env_for_express
+
+
+def test_load_app_config_env_for_express_reads_config_env():
+    config_path = CDK_DIR / "config" / "app_config.env"
+    env_vars = load_app_config_env_for_express(str(config_path))
+    names = {p.name for p in env_vars}
+    assert "RUN_AWS_FUNCTIONS" in names
+    assert "S3_LOG_BUCKET" in names
+    assert "AWS_CLIENT_ID" not in names
+
+
+def test_load_app_config_env_missing_file_returns_empty():
+    assert (
+        load_app_config_env_for_express(str(CDK_DIR / "config" / "nonexistent.env"))
+        == []
+    )

cdk/test/test_express_pi.py

@@ -0,0 +1,566 @@
+"""Tests for Pi on ECS Express Mode helpers and config rules."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_pi_express_mutual_exclusion_with_legacy_pi():
+    legacy = "True"
+    express = "True"
+    with pytest.raises(ValueError, match="at most one Pi deployment"):
+        if legacy == "True" and express == "True":
+            raise ValueError(
+                "Enable at most one Pi deployment mode: ENABLE_PI_AGENT_ECS_SERVICE (legacy Fargate) "
+                "or ENABLE_PI_AGENT_EXPRESS_SERVICE (Express), not both."
+            )
+
+
+def test_pi_express_requires_express_mode():
+    express_pi = "True"
+    use_express = "False"
+    with pytest.raises(ValueError, match="ENABLE_PI_AGENT_EXPRESS_SERVICE"):
+        if express_pi == "True" and use_express != "True":
+            raise ValueError(
+                "ENABLE_PI_AGENT_EXPRESS_SERVICE=True requires USE_ECS_EXPRESS_MODE=True "
+                "(no ACM_SSL_CERTIFICATE_ARN)."
+            )
+
+
+def test_build_pi_express_container_environment():
+    from cdk_functions import build_pi_express_container_environment
+
+    env = build_pi_express_container_environment(
+        service_connect_discovery_name="summarisation",
+        main_app_port=7860,
+        pi_gradio_port=7862,
+    )
+    assert env["DOC_SUMMARISATION_GRADIO_URL"] == "http://summarisation:7860"
+    assert env["PI_WORKSPACE_DIR"] == "/tmp/pi-workspace"
+    assert env["PI_UPLOAD_ROOT"] == "/tmp/gradio"
+    assert env["PI_DEPLOYMENT_PROFILE"] == "aws-ecs"
+    assert env["COGNITO_AUTH"] == "True"
+    assert env["RUN_FASTAPI"] == "True"
+
+
+def test_build_express_pi_primary_container_includes_cognito_secrets():
+    from aws_cdk import App, Stack
+    from aws_cdk import aws_secretsmanager as sm
+    from cdk_functions import build_express_pi_primary_container
+
+    app = App()
+    stack = Stack(app, "PiSecretTest")
+    secret = sm.Secret(stack, "CognitoSecret", secret_name="demo-cognito-secret")
+
+    container = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        secret=secret,
+        cognito_auth=True,
+    )
+    assert container.secrets is not None
+    secret_names = {item.name for item in container.secrets}
+    assert secret_names == {"AWS_USER_POOL_ID", "AWS_CLIENT_ID", "AWS_CLIENT_SECRET"}
+
+    no_auth = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        secret=secret,
+        cognito_auth=False,
+    )
+    assert no_auth.secrets is None
+
+
+def test_format_express_pi_public_url():
+    from cdk_functions import format_express_pi_public_url
+
+    assert (
+        format_express_pi_public_url("https://pi.example.ecs.eu-west-2.on.aws")
+        == "https://pi.example.ecs.eu-west-2.on.aws/"
+    )
+    assert format_express_pi_public_url("") == ""
+
+
+def test_express_service_connect_configuration_server_and_client():
+    from cdk_functions import _express_service_connect_configuration
+
+    server = _express_service_connect_configuration(
+        namespace="demo-ns",
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    assert server["enabled"] is True
+    assert server["namespace"] == "demo-ns"
+    assert server["services"][0]["portName"] == "port-7860"
+    assert server["services"][0]["discoveryName"] == "summarisation"
+
+    client = _express_service_connect_configuration(namespace="demo-ns")
+    assert "services" not in client
+
+
+def test_apply_service_connect_custom_resource_synth():
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import apply_service_connect_to_express_service
+
+    app = App()
+    stack = Stack(
+        app,
+        "ScExpressTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    express = ecs.CfnExpressGatewayService(
+        stack,
+        "MainExpress",
+        service_name="main-express",
+        cluster="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "MainSc",
+        cluster_name="test-cluster",
+        service_name="main-express",
+        namespace="test-ns",
+        express_service=express,
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::AWS", 1)
+    template.has_resource_properties(
+        "Custom::AWS",
+        {
+            "Create": assertions.Match.string_like_regexp(
+                r'"portName":"port-7860".*"discoveryName":"summarisation"'
+            ),
+        },
+    )
+
+
+def test_express_alb_ingress_uses_security_group_id_not_arn():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import allow_express_load_balancer_to_ecs_security_group
+
+    app = App()
+    stack = Stack(app, "ExpressAlbIngressTest")
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    task_sg = ec2.SecurityGroup(stack, "TaskSg", vpc=vpc)
+    express = ecs.CfnExpressGatewayService(
+        stack,
+        "Express",
+        service_name="main-express",
+        cluster="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+    )
+    allow_express_load_balancer_to_ecs_security_group(
+        stack,
+        "ExpressAlbToTask",
+        express_service=express,
+        ecs_security_group=task_sg,
+        container_port=7860,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::EC2::SecurityGroupIngress",
+        {
+            "SourceSecurityGroupId": {
+                "Fn::Select": [
+                    1,
+                    {
+                        "Fn::Split": [
+                            "security-group/",
+                            {
+                                "Fn::Select": [
+                                    0,
+                                    {
+                                        "Fn::GetAtt": [
+                                            "Express",
+                                            "ECSManagedResourceArns.IngressPath.LoadBalancerSecurityGroups",
+                                        ]
+                                    },
+                                ]
+                            },
+                        ]
+                    },
+                ]
+            }
+        },
+    )
+
+
+def test_express_gateway_service_defaults_to_idle_scaling_target():
+    from aws_cdk import App, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import create_express_gateway_service
+
+    app = App()
+    stack = Stack(app, "ExpressIdleScalingTest")
+    create_express_gateway_service(
+        stack,
+        "Express",
+        service_name="main-express",
+        cluster_name="test-cluster",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="4096",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::ECS::ExpressGatewayService",
+        {
+            "ScalingTarget": {
+                "MinTaskCount": 0,
+                "MaxTaskCount": 1,
+                "AutoScalingMetric": "AVERAGE_CPU",
+                "AutoScalingTargetValue": 60,
+            }
+        },
+    )
+
+
+def test_express_infrastructure_role_uses_service_role_managed_policy():
+    from aws_cdk import App, Stack, assertions
+    from cdk_functions import create_ecs_express_infrastructure_role
+
+    app = App()
+    stack = Stack(app, "ExpressInfraRoleTest")
+    create_ecs_express_infrastructure_role(
+        stack, "ExpressInfrastructureRole", "test-express-infra"
+    )
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::IAM::Role",
+        {
+            "ManagedPolicyArns": assertions.Match.array_with(
+                [
+                    {
+                        "Fn::Join": [
+                            "",
+                            [
+                                "arn:",
+                                {"Ref": "AWS::Partition"},
+                                ":iam::aws:policy/service-role/AmazonECSInfrastructureRoleforExpressGatewayServices",
+                            ],
+                        ]
+                    }
+                ]
+            )
+        },
+    )
+
+
+def test_express_listener_helpers_synth_without_reference_error():
+    """Fn.select on Express list attrs must use typed attr_* list properties."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        allow_express_load_balancer_to_ecs_security_group,
+        configure_express_listener_cognito_and_cloudfront,
+        configure_express_pi_listener_rules,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressListenerHelpers",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    sg = ec2.SecurityGroup(stack, "TaskSg", vpc=vpc)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    pi = create_express_gateway_service(
+        stack,
+        "Pi",
+        service_name="pi-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/pi/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+            container_port=7862,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-pi"],
+    )
+    allow_express_load_balancer_to_ecs_security_group(
+        stack,
+        "MainLbToTask",
+        express_service=main,
+        ecs_security_group=sg,
+        container_port=7860,
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=False,
+        cloudfront_host_header="",
+    )
+    configure_express_pi_listener_rules(
+        stack,
+        "PiRules",
+        express_main_service=main,
+        express_pi_service=pi,
+        routing_mode="path",
+        path_prefix="/pi",
+        pi_host_header="",
+        rule_priority=3,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+    )
+    app.synth()
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::ECS::ExpressGatewayService", 2)
+    # modifyListener (Custom::AWS) + Pi path rule (Custom::Elbv2ListenerRuleUpsert)
+    template.resource_count_is("Custom::AWS", 1)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 1)
+    # authenticate-cognito on ALB requires DescribeUserPoolClient on the CR Lambda role
+    cr_policy_actions: list[str] = []
+    for props in template.find_resources("AWS::IAM::Policy").values():
+        for stmt in (
+            props.get("Properties", {}).get("PolicyDocument", {}).get("Statement", [])
+        ):
+            action = stmt.get("Action", [])
+            if isinstance(action, str):
+                cr_policy_actions.append(action)
+            else:
+                cr_policy_actions.extend(action)
+    assert "cognito-idp:DescribeUserPoolClient" in cr_policy_actions
+    assert "elasticloadbalancing:ModifyListener" in cr_policy_actions
+
+
+def test_express_cloudfront_does_not_add_cognito_bypass_host_rule_by_default():
+    """With ALB Cognito, CloudFront must not add a forward-only host-header rule."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        configure_express_listener_cognito_and_cloudfront,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressCloudFrontCognitoTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=[vpc.public_subnets[0].subnet_id],
+        security_group_ids=["sg-main"],
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=True,
+        cloudfront_host_header="app.example.com",
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 0)
+
+
+def test_express_cloudfront_can_opt_in_to_origin_bypass_without_cognito():
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        configure_express_listener_cognito_and_cloudfront,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "ExpressCloudFrontBypassTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=[vpc.public_subnets[0].subnet_id],
+        security_group_ids=["sg-main"],
+    )
+    configure_express_listener_cognito_and_cloudfront(
+        stack,
+        "MainListener",
+        express_service=main,
+        user_pool_arn="arn:aws:cognito-idp:eu-west-2:123456789012:userpool/pool",
+        user_pool_client_id="client",
+        user_pool_domain_prefix="demo-auth",
+        use_cloudfront=True,
+        cloudfront_host_header="app.example.com",
+        allow_cloudfront_origin_without_cognito=True,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("Custom::Elbv2ListenerRuleUpsert", 1)
+
+
+def test_dual_express_gateway_services_synth():
+    """Two ExpressGatewayService resources when wiring main + Pi helpers."""
+    from aws_cdk import App, Environment, Stack, assertions
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import (
+        apply_service_connect_to_express_service,
+        build_express_pi_primary_container,
+        create_express_gateway_service,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "DualExpressTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    main = create_express_gateway_service(
+        stack,
+        "Main",
+        service_name="main-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=ecs.CfnExpressGatewayService.ExpressGatewayContainerProperty(
+            image="123456789012.dkr.ecr.eu-west-2.amazonaws.com/app:latest",
+            container_port=7860,
+        ),
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-main"],
+    )
+    pi_container = build_express_pi_primary_container(
+        image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi:latest",
+        container_port=7862,
+        log_group_name="/ecs/pi-logs",
+        aws_region="eu-west-2",
+        environment={"PI_WORKSPACE_DIR": "/tmp/pi-workspace"},
+    )
+    pi = create_express_gateway_service(
+        stack,
+        "Pi",
+        service_name="pi-svc",
+        cluster_name="cl",
+        execution_role_arn="arn:aws:iam::123456789012:role/exec",
+        infrastructure_role_arn="arn:aws:iam::123456789012:role/infra",
+        task_role_arn="arn:aws:iam::123456789012:role/task",
+        cpu="1024",
+        memory="2048",
+        health_check_path="/",
+        primary_container=pi_container,
+        subnet_ids=["subnet-abc"],
+        security_group_ids=["sg-pi"],
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "MainSc",
+        cluster_name="cl",
+        service_name="main-svc",
+        namespace="ns",
+        express_service=main,
+        port_name="port-7860",
+        discovery_name="summarisation",
+        port=7860,
+    )
+    apply_service_connect_to_express_service(
+        stack,
+        "PiSc",
+        cluster_name="cl",
+        service_name="pi-svc",
+        namespace="ns",
+        express_service=pi,
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::ECS::ExpressGatewayService", 2)
+    template.resource_count_is("Custom::AWS", 2)

cdk/test/test_globally_unique_names.py

@@ -0,0 +1,91 @@
+"""Tests for globally unique AWS name checks (S3, Cognito)."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from botocore.exceptions import ClientError
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import (  # noqa: E402
+    resolve_cognito_domain_prefix_availability,
+    resolve_s3_bucket_availability,
+)
+
+
+def _client_error(code: str) -> ClientError:
+    return ClientError({"Error": {"Code": code, "Message": code}}, "HeadBucket")
+
+
+def test_resolve_s3_bucket_available_on_404():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("404")
+    status, name = resolve_s3_bucket_availability("free-bucket", s3_client=s3)
+    assert status == "available"
+    assert name == "free-bucket"
+
+
+def test_resolve_s3_bucket_owned_on_success():
+    s3 = MagicMock()
+    s3.head_bucket.return_value = {}
+    status, name = resolve_s3_bucket_availability("my-bucket", s3_client=s3)
+    assert status == "owned"
+    assert name == "my-bucket"
+
+
+def test_resolve_s3_bucket_globally_taken_on_403_not_listed():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("403")
+    s3.list_buckets.return_value = {"Buckets": [{"Name": "other-bucket"}]}
+    status, name = resolve_s3_bucket_availability(
+        "demo-summarisation-s3-logs", s3_client=s3
+    )
+    assert status == "globally_taken"
+    assert name == "demo-summarisation-s3-logs"
+
+
+def test_resolve_s3_bucket_owned_on_403_listed_in_account():
+    s3 = MagicMock()
+    s3.head_bucket.side_effect = _client_error("403")
+    s3.list_buckets.return_value = {"Buckets": [{"Name": "my-bucket"}]}
+    status, _ = resolve_s3_bucket_availability("my-bucket", s3_client=s3)
+    assert status == "owned"
+
+
+def test_resolve_cognito_domain_taken_when_owned_elsewhere():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.side_effect = _client_error(
+        "ResourceNotFoundException"
+    )
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "demo-summarisation", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "taken"
+    )
+
+
+def test_resolve_cognito_domain_available_when_empty_description():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.return_value = {"DomainDescription": {}}
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "my-prefix", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "available"
+    )
+
+
+def test_resolve_cognito_domain_taken_when_user_pool_present():
+    cognito = MagicMock()
+    cognito.describe_user_pool_domain.return_value = {
+        "DomainDescription": {"UserPoolId": "eu-west-2_abc"}
+    }
+    assert (
+        resolve_cognito_domain_prefix_availability(
+            "taken-prefix", region_name="eu-west-2", cognito_client=cognito
+        )
+        == "taken"
+    )

cdk/test/test_headless_app_defaults_env.py

@@ -0,0 +1,22 @@
+"""Headless batch app_defaults.env rendering."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import build_headless_app_defaults_env_content
+
+
+def test_build_headless_app_defaults_env_sets_outputs_bucket():
+    seed_dir = str(CDK_DIR / "config" / "headless_s3_seed")
+    content = build_headless_app_defaults_env_content(
+        seed_dir,
+        s3_outputs_bucket_name="lambeth-prod-summarisation-s3-output",
+    )
+
+    assert "S3_OUTPUTS_BUCKET=lambeth-prod-summarisation-s3-output" in content
+    assert "RUN_DIRECT_MODE=1" in content
+    assert "SAVE_OUTPUTS_TO_S3=True" in content
+    assert content.count("S3_OUTPUTS_BUCKET=") == 1

cdk/test/test_headless_output_notifications.py

@@ -0,0 +1,81 @@
+"""Headless S3 output notification resources and installer validation."""
+
+import sys
+from pathlib import Path
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_functions import sanitize_headless_metric_filter_id
+
+
+def test_sanitize_headless_metric_filter_id():
+    assert sanitize_headless_metric_filter_id("Prod-Summarisation-s3-output-put") == (
+        "Prod-Summarisation-s3-output-put"
+    )
+    assert sanitize_headless_metric_filter_id("bad id!!") == "bad-id"
+
+
+def test_validate_notify_email():
+    from cdk_install import validate_notify_email
+
+    assert validate_notify_email("user@example.com") is None
+    assert validate_notify_email("") is not None
+    assert validate_notify_email("not-an-email") is not None
+
+
+def test_headless_output_notifications_synth():
+    from aws_cdk import App, Environment, Stack
+    from aws_cdk import aws_s3 as s3
+    from aws_cdk.assertions import Match, Template
+    from cdk_functions import create_headless_output_notifications
+
+    app = App()
+    stack = Stack(
+        app,
+        "HeadlessNotifyTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    bucket = s3.Bucket(stack, "OutputBucket", bucket_name="test-output-bucket")
+
+    create_headless_output_notifications(
+        stack,
+        "Notify",
+        output_bucket=bucket,
+        output_prefix="output/",
+        notify_email="analyst@example.com",
+        iam_user_name="test-s3-output-reader",
+        metric_filter_id="test-s3-output-put",
+        sns_topic_name="test-llm-topic-s3-save-sns",
+        alarm_name="test-cloudwatch-alarm-new-output-s3",
+    )
+
+    template = Template.from_stack(stack)
+    template.resource_count_is("AWS::SNS::Topic", 1)
+    template.resource_count_is("AWS::CloudWatch::Alarm", 1)
+    template.resource_count_is("AWS::IAM::User", 1)
+    template.has_resource_properties(
+        "AWS::S3::BucketPolicy",
+        {
+            "PolicyDocument": {
+                "Statement": Match.array_with(
+                    [
+                        Match.object_like(
+                            {
+                                "Effect": "Allow",
+                                "Action": Match.array_with(["s3:GetObject"]),
+                            }
+                        )
+                    ]
+                )
+            }
+        },
+    )
+    template.has_resource_properties(
+        "AWS::CloudWatch::Alarm",
+        {
+            "MetricName": "PutRequests",
+            "Namespace": "AWS/S3",
+            "ComparisonOperator": "GreaterThanThreshold",
+        },
+    )

cdk/test/test_iam_policy_files.py

@@ -0,0 +1,92 @@
+"""Tests for custom IAM policy file lists on ECS task / execution roles."""
+
+import json
+import sys
+from pathlib import Path
+
+from aws_cdk import App, Stack
+from aws_cdk import aws_iam as iam
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+from cdk_config import (  # noqa: E402
+    AWS_MANAGED_TASK_ROLES_LIST,
+    ECS_EXECUTION_ROLE_MANAGED_POLICIES,
+    POLICY_FILE_LOCATIONS,
+    parse_comma_separated_list,
+)
+from cdk_functions import (  # noqa: E402
+    add_custom_policies,
+    resolve_policy_file_paths,
+)
+
+
+def test_parse_comma_separated_list_json_and_plain():
+    assert parse_comma_separated_list('["a.json", "b.json"]') == ["a.json", "b.json"]
+    assert parse_comma_separated_list("textract_policy.json") == [
+        "textract_policy.json"
+    ]
+    assert parse_comma_separated_list("a.json, b.json") == ["a.json", "b.json"]
+    assert parse_comma_separated_list("") == []
+
+
+def test_policy_file_locations_default_is_empty_list():
+    assert isinstance(POLICY_FILE_LOCATIONS, list)
+    assert POLICY_FILE_LOCATIONS == []
+
+
+def test_task_role_managed_policies_exclude_s3_full_access():
+    assert "AmazonS3FullAccess" not in AWS_MANAGED_TASK_ROLES_LIST
+
+
+def test_execution_role_managed_policies_default_minimal():
+    assert "service-role/AmazonECSTaskExecutionRolePolicy" in (
+        ECS_EXECUTION_ROLE_MANAGED_POLICIES
+    )
+    assert "AmazonS3FullAccess" not in ECS_EXECUTION_ROLE_MANAGED_POLICIES
+
+
+def test_resolve_policy_file_paths_relative_to_cdk_folder(tmp_path):
+    policy = tmp_path / "custom.json"
+    policy.write_text("{}", encoding="utf-8")
+    resolved = resolve_policy_file_paths(["custom.json"], cdk_folder=str(tmp_path))
+    assert resolved == [str(policy.resolve())]
+
+
+def test_add_custom_policies_loads_json_statements(tmp_path):
+    policy_path = tmp_path / "extra.json"
+    policy_path.write_text(
+        json.dumps(
+            {
+                "Version": "2012-10-17",
+                "Statement": [
+                    {
+                        "Sid": "TestAllow",
+                        "Effect": "Allow",
+                        "Action": "s3:ListBucket",
+                        "Resource": "*",
+                    }
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    app = App()
+    stack = Stack(app, "TestStack")
+    role = iam.Role(
+        stack,
+        "TaskRole",
+        assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
+    )
+    add_custom_policies(stack, role, policy_file_locations=[str(policy_path)])
+
+    template = app.synth().get_stack_by_name("TestStack").template
+    policies = template["Resources"]
+    inline = [
+        r
+        for r in policies.values()
+        if r.get("Type") == "AWS::IAM::Policy" and "s3:ListBucket" in json.dumps(r)
+    ]
+    assert inline, "expected inline policy statement from JSON file"

cdk/test/test_pi_agent_ecs_synth.py

@@ -0,0 +1,169 @@
+"""Synth assertions for optional Pi agent ECS service on shared ALB."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+def test_pi_agent_requires_service_connect():
+    enable_pi = "True"
+    enable_sc = "False"
+    with pytest.raises(ValueError, match="ENABLE_PI_AGENT_ECS_SERVICE"):
+        if enable_pi == "True" and enable_sc != "True":
+            raise ValueError(
+                "ENABLE_PI_AGENT_ECS_SERVICE=True requires ENABLE_ECS_SERVICE_CONNECT=True "
+                "so the Pi task can reach the main app at http://<discovery>:7860."
+            )
+
+
+def test_build_pi_agent_container_environment():
+    from cdk_functions import build_pi_agent_container_environment
+
+    env = build_pi_agent_container_environment(
+        service_connect_discovery_name="summarisation",
+        main_app_port=7860,
+        pi_gradio_port=7862,
+    )
+    assert env["DOC_SUMMARISATION_GRADIO_URL"] == "http://summarisation:7860"
+    assert env["PI_DEFAULT_PROVIDER"] == "amazon-bedrock"
+    assert env["PI_GRADIO_PORT"] == "7862"
+    assert env["PI_CODING_AGENT_DIR"] == "/tmp/pi-agent"
+    assert env["ACCESS_LOGS_FOLDER"] == "/tmp/pi-logs/"
+    assert env["RUN_FASTAPI"] == "True"
+    assert env["RUN_AWS_FUNCTIONS"] == "True"
+    assert env["SAVE_OUTPUTS_TO_S3"] == "True"
+    assert env["S3_OUTPUTS_BUCKET"]
+
+
+def test_ecs_availability_zone_rebalancing_default_disabled():
+    from aws_cdk import aws_ecs as ecs
+    from cdk_functions import ecs_availability_zone_rebalancing
+
+    assert (
+        ecs_availability_zone_rebalancing("DISABLED")
+        == ecs.AvailabilityZoneRebalancing.DISABLED
+    )
+    assert (
+        ecs_availability_zone_rebalancing("ENABLED")
+        == ecs.AvailabilityZoneRebalancing.ENABLED
+    )
+
+
+def test_pi_agent_alb_attachment_synth():
+    from aws_cdk import App, Duration, Environment, Stack
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from aws_cdk import aws_elasticloadbalancingv2 as elbv2
+    from aws_cdk import aws_iam as iam
+    from aws_cdk import aws_s3 as s3
+    from cdk_functions import (
+        attach_pi_agent_to_shared_alb,
+        create_pi_agent_ecs_resources,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "PiAgentAlbTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    alb_sg = ec2.SecurityGroup(stack, "AlbSg", vpc=vpc)
+    alb = elbv2.ApplicationLoadBalancer(
+        stack,
+        "Alb",
+        vpc=vpc,
+        internet_facing=True,
+        security_group=alb_sg,
+    )
+    cluster = ecs.Cluster(stack, "Cluster", vpc=vpc)
+    config_bucket = s3.Bucket(stack, "ConfigBucket")
+    task_role = iam.Role(
+        stack,
+        "TaskRole",
+        assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
+    )
+    execution_role = iam.Role(
+        stack,
+        "ExecRole",
+        assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
+    )
+
+    pi_service, pi_sg, _ = create_pi_agent_ecs_resources(
+        stack,
+        "Pi",
+        vpc=vpc,
+        cluster=cluster,
+        private_subnets=vpc.private_subnets,
+        pi_ecr_image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi-agent",
+        container_name="pi-agent",
+        task_role=task_role,
+        execution_role=execution_role,
+        config_bucket=config_bucket,
+        pi_agent_env_s3_key="",
+        service_name="test-pi-service",
+        task_family="test-pi-task",
+        security_group_name="test-pi-sg",
+        log_group_name="/ecs/test-pi-logs",
+        cpu=1024,
+        memory_mib=2048,
+        pi_gradio_port=7862,
+        service_connect_namespace="test-ns",
+        service_connect_discovery_name="summarisation",
+        main_app_port=7860,
+        use_fargate_spot="FARGATE",
+    )
+
+    http_listener = alb.add_listener("Http", port=80, open=True)
+    http_listener.add_action(
+        "DefaultDeny",
+        action=elbv2.ListenerAction.fixed_response(
+            status_code=403,
+            content_type="text/plain",
+            message_body="Access denied",
+        ),
+    )
+    attach_pi_agent_to_shared_alb(
+        stack,
+        "PiAlb",
+        vpc=vpc,
+        alb_security_group=alb_sg,
+        pi_security_group=pi_sg,
+        pi_service=pi_service,
+        pi_port=7862,
+        routing_mode="host",
+        path_prefix="/pi",
+        pi_host_header="pi.example.com",
+        listener_rule_priority=3,
+        target_group_name="test-pi-tg",
+        stickiness_cookie_duration=Duration.hours(8),
+        https_listener=None,
+        http_listener=http_listener,
+        acm_certificate_arn="",
+        enable_cognito_auth=False,
+        cognito_user_pool=None,
+        cognito_user_pool_client=None,
+        cognito_user_pool_domain=None,
+    )
+
+    template = app.synth().get_stack_by_name("PiAgentAlbTest").template
+    resources = template["Resources"]
+    lb_count = sum(
+        1
+        for r in resources.values()
+        if r["Type"] == "AWS::ElasticLoadBalancingV2::LoadBalancer"
+    )
+    tg_count = sum(
+        1
+        for r in resources.values()
+        if r["Type"] == "AWS::ElasticLoadBalancingV2::TargetGroup"
+    )
+    assert lb_count == 1
+    assert tg_count == 1
+    ecs_services = [r for r in resources.values() if r["Type"] == "AWS::ECS::Service"]
+    assert len(ecs_services) == 1
+    assert ecs_services[0]["Properties"]["AvailabilityZoneRebalancing"] == "DISABLED"

cdk/test/test_pi_alb_routing.py

@@ -0,0 +1,164 @@
+"""Tests for Pi ALB path/host routing helpers."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+@pytest.fixture(autouse=True)
+def _minimal_cdk_config_env(monkeypatch):
+    monkeypatch.setenv("USE_ECS_EXPRESS_MODE", "False")
+    monkeypatch.setenv("ACM_SSL_CERTIFICATE_ARN", "")
+    monkeypatch.setenv("ENABLE_S3_BATCH_ECS_TRIGGER", "False")
+    monkeypatch.setenv("ENABLE_PI_AGENT_ECS_SERVICE", "False")
+    monkeypatch.setenv("ENABLE_PI_AGENT_EXPRESS_SERVICE", "False")
+    monkeypatch.setenv("ENABLE_ECS_SERVICE_CONNECT", "False")
+    for mod_name in list(sys.modules):
+        if mod_name in ("cdk_config", "cdk_functions") or mod_name.startswith("cdk_"):
+            del sys.modules[mod_name]
+
+
+def test_normalize_pi_alb_path_prefix():
+    from cdk_functions import normalize_pi_alb_path_prefix
+
+    assert normalize_pi_alb_path_prefix("/pi") == "/pi"
+    assert normalize_pi_alb_path_prefix("pi") == "/pi"
+    assert normalize_pi_alb_path_prefix("") == "/pi"
+
+
+def test_pi_alb_path_patterns():
+    from cdk_functions import pi_alb_path_patterns
+
+    assert pi_alb_path_patterns("/pi") == ["/pi", "/pi/*"]
+
+
+def test_format_pi_public_urls_path_on_cloudfront():
+    from cdk_functions import format_pi_public_urls
+
+    urls = format_pi_public_urls(
+        routing_mode="path",
+        path_prefix="/pi",
+        host_header="",
+        cloudfront_domain="d123.cloudfront.net",
+        use_https=True,
+    )
+    assert urls == ["https://d123.cloudfront.net/pi/"]
+
+
+def test_pi_listener_rule_count():
+    from cdk_functions import pi_listener_rule_count
+
+    assert pi_listener_rule_count("path") == 1
+    assert pi_listener_rule_count("host") == 1
+    assert pi_listener_rule_count("both") == 2
+
+
+def test_attach_pi_path_rule_synth():
+    from aws_cdk import App, Duration, Environment, Stack, assertions
+    from aws_cdk import aws_ec2 as ec2
+    from aws_cdk import aws_ecs as ecs
+    from aws_cdk import aws_elasticloadbalancingv2 as elbv2
+    from aws_cdk import aws_iam as iam
+    from aws_cdk import aws_s3 as s3
+    from cdk_functions import (
+        attach_pi_agent_to_shared_alb,
+        create_pi_agent_ecs_resources,
+    )
+
+    app = App()
+    stack = Stack(
+        app,
+        "PiPathAlbTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    vpc = ec2.Vpc(stack, "Vpc", max_azs=2)
+    alb_sg = ec2.SecurityGroup(stack, "AlbSg", vpc=vpc)
+    alb = elbv2.ApplicationLoadBalancer(
+        stack,
+        "Alb",
+        vpc=vpc,
+        internet_facing=True,
+        security_group=alb_sg,
+    )
+    cluster = ecs.Cluster(stack, "Cluster", vpc=vpc)
+    config_bucket = s3.Bucket(stack, "ConfigBucket")
+    task_role = iam.Role(
+        stack,
+        "TaskRole",
+        assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
+    )
+    execution_role = iam.Role(
+        stack,
+        "ExecRole",
+        assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
+    )
+
+    pi_service, pi_sg, _ = create_pi_agent_ecs_resources(
+        stack,
+        "Pi",
+        vpc=vpc,
+        cluster=cluster,
+        private_subnets=vpc.private_subnets,
+        pi_ecr_image_uri="123456789012.dkr.ecr.eu-west-2.amazonaws.com/pi-agent",
+        container_name="pi-agent",
+        task_role=task_role,
+        execution_role=execution_role,
+        config_bucket=config_bucket,
+        pi_agent_env_s3_key="",
+        service_name="test-pi-service",
+        task_family="test-pi-task",
+        security_group_name="test-pi-sg",
+        log_group_name="/ecs/test-pi-logs",
+        cpu=1024,
+        memory_mib=2048,
+        pi_gradio_port=7862,
+        service_connect_namespace="test-ns",
+        service_connect_discovery_name="summarisation",
+        main_app_port=7860,
+        pi_root_path="/pi",
+        use_fargate_spot="FARGATE",
+    )
+
+    http_listener = alb.add_listener("Http", port=80, open=True)
+    http_listener.add_action(
+        "DefaultDeny",
+        action=elbv2.ListenerAction.fixed_response(
+            status_code=403,
+            content_type="text/plain",
+            message_body="Access denied",
+        ),
+    )
+    attach_pi_agent_to_shared_alb(
+        stack,
+        "PiAlb",
+        vpc=vpc,
+        alb_security_group=alb_sg,
+        pi_security_group=pi_sg,
+        pi_service=pi_service,
+        pi_port=7862,
+        routing_mode="path",
+        path_prefix="/pi",
+        pi_host_header="",
+        listener_rule_priority=3,
+        target_group_name="test-pi-tg",
+        stickiness_cookie_duration=Duration.hours(8),
+        https_listener=None,
+        http_listener=http_listener,
+        acm_certificate_arn="",
+        enable_cognito_auth=False,
+        cognito_user_pool=None,
+        cognito_user_pool_client=None,
+        cognito_user_pool_domain=None,
+    )
+
+    template = assertions.Template.from_stack(stack)
+    template.has_resource_properties(
+        "AWS::ElasticLoadBalancingV2::TargetGroup",
+        {
+            "HealthCheckPath": "/pi/",
+        },
+    )

cdk/test/test_public_subnet_igw.py

@@ -0,0 +1,141 @@
+"""Tests for public subnet Internet Gateway audit and CDK wiring helpers."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+CDK_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(CDK_DIR))
+
+
+@pytest.fixture(autouse=True)
+def _minimal_cdk_config_env(monkeypatch):
+    """Avoid loading the developer cdk_config.env validation errors during import."""
+    monkeypatch.setenv("USE_ECS_EXPRESS_MODE", "False")
+    monkeypatch.setenv("ACM_SSL_CERTIFICATE_ARN", "")
+    monkeypatch.setenv("ENABLE_S3_BATCH_ECS_TRIGGER", "False")
+    monkeypatch.setenv("ENABLE_PI_AGENT_ECS_SERVICE", "False")
+    monkeypatch.setenv("ENABLE_PI_AGENT_EXPRESS_SERVICE", "False")
+    monkeypatch.setenv("ENABLE_ECS_SERVICE_CONNECT", "False")
+    for mod_name in list(sys.modules):
+        if mod_name in ("cdk_config", "cdk_functions") or mod_name.startswith("cdk_"):
+            del sys.modules[mod_name]
+
+
+def test_route_table_default_internet_gateway_parses_igw():
+    from cdk_functions import route_table_default_internet_gateway
+
+    mock_client = MagicMock()
+    mock_client.describe_route_tables.return_value = {
+        "RouteTables": [
+            {
+                "Routes": [
+                    {
+                        "DestinationCidrBlock": "0.0.0.0/0",
+                        "GatewayId": "igw-abc123",
+                    }
+                ]
+            }
+        ]
+    }
+    with patch("cdk_functions.boto3.client", return_value=mock_client):
+        assert route_table_default_internet_gateway("rtb-1") == "igw-abc123"
+
+
+def test_audit_needs_attachment_when_igw_detached():
+    from cdk_functions import audit_public_subnet_internet_connectivity
+
+    mock_ec2 = MagicMock()
+    mock_ec2.describe_internet_gateways.return_value = {
+        "InternetGateways": [{"Attachments": []}]
+    }
+    with (
+        patch("cdk_functions.get_internet_gateways_attached_to_vpc", return_value=[]),
+        patch("cdk_functions.internet_gateway_exists", return_value=True),
+        patch("cdk_functions.boto3.client", return_value=mock_ec2),
+        patch("cdk_functions.route_table_default_internet_gateway", return_value=None),
+        patch(
+            "cdk_functions.route_table_has_non_igw_default_route", return_value=False
+        ),
+    ):
+        result = audit_public_subnet_internet_connectivity(
+            "vpc-111",
+            "igw-configured",
+            [
+                {
+                    "name": "PublicSubnet1",
+                    "subnet_id": "subnet-1",
+                    "route_table_id": "rtb-1",
+                }
+            ],
+        )
+    assert result["internet_gateway_id"] == "igw-configured"
+    assert result["internet_gateway_needs_vpc_attachment"] is True
+    assert len(result["public_subnets_needing_igw_route"]) == 1
+
+
+def test_audit_raises_when_default_route_conflicts():
+    from cdk_functions import audit_public_subnet_internet_connectivity
+
+    with (
+        patch(
+            "cdk_functions.get_internet_gateways_attached_to_vpc",
+            return_value=["igw-attached"],
+        ),
+        patch("cdk_functions.internet_gateway_exists", return_value=True),
+        patch(
+            "cdk_functions.route_table_default_internet_gateway",
+            return_value="igw-other",
+        ),
+    ):
+        with pytest.raises(ValueError, match="0.0.0.0/0"):
+            audit_public_subnet_internet_connectivity(
+                "vpc-111",
+                "igw-attached",
+                [
+                    {
+                        "name": "PublicSubnet1",
+                        "subnet_id": "subnet-1",
+                        "route_table_id": "rtb-1",
+                    }
+                ],
+            )
+
+
+def test_wire_public_subnet_internet_access_synth():
+    from aws_cdk import App, Environment, Stack, assertions
+    from cdk_functions import wire_public_subnet_internet_access
+
+    app = App()
+    stack = Stack(
+        app,
+        "IgwWireTest",
+        env=Environment(account="123456789012", region="eu-west-2"),
+    )
+    wire_public_subnet_internet_access(
+        stack,
+        "Test",
+        vpc_id="vpc-111",
+        internet_gateway_id="igw-abc123",
+        needs_igw_vpc_attachment=True,
+        subnets_needing_route=[
+            {
+                "name": "PublicSubnet1",
+                "subnet_id": "subnet-1",
+                "route_table_id": "rtb-aaa",
+            }
+        ],
+    )
+    template = assertions.Template.from_stack(stack)
+    template.resource_count_is("AWS::EC2::VPCGatewayAttachment", 1)
+    template.resource_count_is("AWS::EC2::Route", 1)
+    template.has_resource_properties(
+        "AWS::EC2::Route",
+        {
+            "RouteTableId": "rtb-aaa",
+            "DestinationCidrBlock": "0.0.0.0/0",
+            "GatewayId": "igw-abc123",
+        },
+    )