AI feature and containerization

[leijerry888]

AI Workflow Composer + API-first Docker Stack

This branch integrates two feature lines:

1. AI Workflow Composer – lets users generate ConStrain workflow and verification-case JSON from natural language, via a REST API and a browser UI.
2. API-first Docker stack – replaces the previous four-service Docker setup with a two-container deployment (api-server + api-ui).

---

New modules

constrain/ai/

• llm_client.py – Provider-agnostic LLM client; speaks to any OpenAI-compatible /chat/completions endpoint. Configured via CONSTRAIN_LLM_API_BASE, CONSTRAIN_LLM_MODEL, CONSTRAIN_LLM_API_KEY.
• workflow_composer.py – suggest_workflow() and suggest_verification_cases(): prompt the LLM using a live introspection catalog, parse and validate the result.
• schema_utils.py – Validates workflow and case-suite dicts against JSON schema and Python validators; returns annotated ValidationResult.
• introspection.py – Inspects the ConStrain API and verification library at runtime to build a grounded callable catalog for prompting.
• workflow_runner.py – Runs a workflow dict from a server process with correct cwd, with full traceback logging on failure.

REST API (constrain/app/ai_workflow_server.py)

Method	Path	Purpose
POST	/ai/workflow/suggest	Generate workflow JSON from a goal
POST	/ai/cases/suggest	Generate verification-case JSON from a goal
POST	/ai/workflow/validate	Validate a workflow dict
POST	/ai/cases/validate	Validate a case suite dict
GET	/ai/catalog	Return callable and verification-class catalog
POST	/ai/workflow/execute	Validate then run a workflow synchronously
POST	/ai/workflow/jobs	Enqueue a workflow execution job
POST	/ai/verification/execute	Execute a verification case file synchronously
POST	/ai/verification/jobs	Enqueue a verification execution job
GET	/ai/jobs/{job_id}	Poll a queued job status/result
GET	/ai/artifacts/list	List output artifacts from a results directory
GET	/ai/artifacts/download	Download a single artifact
GET	/ai/artifacts/download-zip	Download all artifacts as a zip

constrain/app/ai_workflow_ui.py + templates/ai_workflow_index.html – FastAPI UI (port 8080)

Browser form for goal input, AI proposal display with inline validation, workflow execution, and synchronous verification execution with artifact listing and download. Verification is intentionally synchronous — one request runs to completion before the next is accepted.

docker/

Two-container Compose stack (Dockerfile.api-server, Dockerfile.api-ui, docker-compose.yml). Supports APP_UID and APP_GID for bind-mount permission alignment on Linux. These optional variables let the containers run with the same Linux user and group IDs as the host user, which helps prevent mounted files from being created with the wrong ownership and avoids common permission problems during local development.

---

Notable design decisions

• Synchronous verification: the UI /verify endpoint blocks until execution finishes. Concurrent verification requests are not supported by design.
• Grounded prompting: the LLM is only given callables and verification classes that exist in the current codebase (via introspection.py), reducing hallucinated symbols.
• import handling: workflow_runner normalises the imports array to handle both bare module names and full import/from statements emitted by the LLM.

---

Tests

226+ unit tests pass including new integration tests for the AI server, UI endpoints, artifact endpoints, and job lifecycle. All CI workflows (Deployment Test, Docker Tests, Unit Tests) are green on this branch.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

This PR merges the “AI Workflow Composer” feature line with an API-first Docker deployment, adding a FastAPI backend/UI for AI-assisted workflow + verification-case composition/execution and simplifying the container stack to api-server + api-ui.

Changes:

• Added AI composer modules (constrain/ai/) plus FastAPI REST server/UI apps for suggesting/validating/executing workflows and verification runs (including artifacts + job polling).
• Introduced an API-first Docker Compose stack (two containers) and Docker entrypoints/images for workflow/verification/reporting (legacy Streamlit retained as deprecated reference).
• Expanded/updated tests and docs to cover the new API/UI flows and container workflows.

Reviewed changes

Copilot reviewed 58 out of 62 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
uv.lock	Adds uv lockfile header (currently minimal).
tests/test_examples.py	Removes timing-based threading assertion for stability.
tests/test_docker_workflow.py	Adds Docker build/run integration test for workflow image.
tests/test_docker_verification.py	Adds Docker build/run integration tests for verification image.
tests/test_docker_reporting.py	Adds Docker build/run integration tests for reporting image.
tests/test_ai_workflow_ui_integration.py	Adds UI integration tests for compose/run/verify and artifact redirects.
tests/test_ai_workflow_server_jobs.py	Adds tests for async job lifecycle (workflow + verification).
tests/test_ai_workflow_server_artifacts.py	Adds tests for artifact listing/download and path traversal blocking.
tests/conftest.py	Adds session autouse fixture to force tests to run from repo root.
tests/api/test_verification_library.py	Makes library.json path resolution robust via absolute path.
tests/api/test_verification_case.py	Uses OS-agnostic absolute paths for fixture JSON.
tests/api/test_verification.py	Updates expectations for new output-dir creation warning behavior.
pyproject.toml	Adds FastAPI/UI deps and dev deps used by the new UI/tests.
docs/Branch_review_feature_merge_experiment_vs_develop.md	Adds narrative branch review and scope summary.
docs/AI_Workflow_Composer_Overview.md	Adds user-facing overview of the AI workflow composer.
docs/AI_Workflow_Composer_Design.md	Adds design/architecture documentation for composer + API/UI.
docker/streamlit_app.py	Adds deprecated legacy Streamlit UI retained for reference.
docker/run_workflow.py	Adds Docker entrypoint script for running workflows.
docker/run_verification.py	Adds Docker entrypoint script for running a verification case.
docker/run_reporting.py	Adds Docker entrypoint script for generating reports.
docker/examples_results/.gitkeep	Keeps example results directory in git.
docker/examples/workflows/G36_demo_workflow.json	Adds docker-mounted demo workflow JSON.
docker/examples/verification_cases/G36_library_verification_cases.json	Adds docker-mounted demo verification case suite.
docker/examples/README.md	Notes equivalence to existing demo with different paths.
docker/docker-compose.yml	Introduces two-service (api-server, api-ui) compose stack with hardening.
docker/container_docs/archive/STREAMLIT_DOCKER.md	Archives legacy Streamlit Docker deployment doc.
docker/container_docs/STREAMLIT_DOCKER.md	Marks Streamlit doc as archived and points to archived copy.
docker/container_docs/DOCKER_WORKFLOW.md	Adds workflow container usage documentation.
docker/container_docs/DOCKER_VERIFICATION.md	Adds verification container usage documentation.
docker/container_docs/DOCKER_REPORTING.md	Adds reporting container usage documentation.
docker/TROUBLESHOOTING.md	Adds operator troubleshooting guide for Phase 4 stack.
docker/TESTING_PHASE4.md	Adds Phase 4 test plan and validation notes.
docker/README.md	Adds quickstart and env override guidance for the API-first stack.
docker/Dockerfile.workflow	Adds workflow image Dockerfile (multi-stage, headless).
docker/Dockerfile.verification	Adds verification image Dockerfile (multi-stage, headless).
docker/Dockerfile.streamlit	Adds deprecated Streamlit Dockerfile (legacy).
docker/Dockerfile.reporting	Adds reporting image Dockerfile (multi-stage, headless).
docker/Dockerfile.api-ui	Adds API UI container Dockerfile with hardening/toolchain remediation.
docker/Dockerfile.api-server	Adds API server container Dockerfile with hardening/toolchain remediation.
docker/.streamlit/config.toml	Retains legacy Streamlit config marked deprecated.
docker/.dockerignore	Adds docker build ignore rules for smaller images.
design/phase4_containerization_audit.md	Adds Phase 4 containerization audit and plan.
design/merge_feature_merge_experiment_docker_conf.md	Adds merge design document for combining feature lines.
design/frontend_feature_mapping_streamlit_to_unified.md	Adds feature mapping from Streamlit to unified API-driven UI.
constrain/libcases.py	Fixes csv_path handling when no IDF instrumentation occurs.
constrain/app/templates/ai_workflow_index.html	Adds UI HTML template for composer + verification panel.
constrain/app/ai_workflow_ui.py	Adds FastAPI UI app that calls backend APIs + job polling + artifact redirects.
constrain/app/ai_workflow_server.py	Adds FastAPI REST API for AI suggest/validate/execute, jobs, artifacts.
constrain/api/workflow.py	Extends workflow import handling to tolerate LLM-emitted import formats.
constrain/api/verification.py	Changes configure() to create missing output directory with warning.
constrain/api/reporting.py	Initializes caseids_sorted field.
constrain/ai/workflow_runner.py	Adds workflow execution helper with cwd normalization + traceback logging.
constrain/ai/workflow_composer.py	Adds LLM-backed workflow/case suggestion + validation glue.
constrain/ai/schema_utils.py	Adds JSON-schema + API validation helpers with structured issues.
constrain/ai/llm_client.py	Adds provider-agnostic OpenAI-compatible chat client using stdlib urllib.
constrain/ai/introspection.py	Adds runtime introspection catalog for callables + verification classes.
constrain/ai/init.py	Exposes AI helper public API.
.gitignore	Updates ignore patterns and ensures UI template remains tracked.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new FastAPI stack dependencies are unconstrained (fastapi = "*", uvicorn = "*", jinja2 = "*", python-multipart = "*"), while the Docker images explicitly pin uvicorn[standard]==0.24.0. This makes local installs vs container installs diverge and can introduce breaking changes unexpectedly. Consider pinning these to compatible version ranges in pyproject.toml (and/or aligning the Dockerfile pins with the dependency spec) so the runtime is reproducible.

[Copilot]

output_dir is accepted as an arbitrary filesystem path and _resolve_output_dir() resolves and allows any existing directory. Combined with /ai/artifacts/list and /ai/artifacts/download, an unauthenticated caller can enumerate and download files from any directory the server process can read (e.g. /etc, /proc, secrets mounted into the container). Restrict output_dir to a configured base directory (e.g. OUTPUT_DIR) and reject paths outside it (and consider similar restrictions for case_file_path / library_json_path).