Feature/initial configuration

[kgray-hu]

Overview

This PR establishes the foundational structure and development environment for the fas_llm_applications Promptflow application suite. The configuration is designed for use within Codespaces and standalone VS Code Dev Containers, enabling our team to develop, test, and manage Harvard FAS LLM workflow apps independently of upstream Promptflow changes.

The primary goal is to provide a consistent, reproducible, and secure development experience for all contributors working on Harvard FAS LLM applications, leveraging Promptflow.

This PR is not intended for upstream contributions.

Changes

Development Environment

• Added .devcontainer/ with devcontainer.json for isolated Codespaces/VS Code container-based development
• Configured postCreateCommand to:
  • Create and activate Python virtual environment (.venv) inside the container
  • Install all project dependencies from requirements.txt
  • Execute automated PromptFlow connection setup via _connections_manager_.setup_all_shared_connections.py
• Set VS Code workspace settings to default Python extension to .venv and activate in terminals

Dependency and Configuration Management

• Consolidated requirements.txt: Single source of truth for all Python dependencies
• Updated .gitignore to:
  • Excluded .env and virtual environment files (.venv/)
  • Filter out Promptflow UI metadata while preserving flow.tools.json (required for Azure ML)
  • Included logs, results, and reports directories for development debugging and testing data store

Security & Credentials

• Implemented keyrings.cryptfile backend for secure, non-interactive credential storage
• Added KEYRING_CRYPTFILE_PASSWORD environment variable** for automated secret management
• Configured credential injection via repository secrets (Codespaces) or local .env files (VS Code)

Script & Tooling

• Added general and project-specific scripts:
  • In digital_latin_project/scripts/:
    • generate_prepared_reports.py: Script for generating Markdown LLM reports and manifests
    • generate_report.py: Core script for generating JSON LLM reports
    • load_env_to_shell.py: Helper for loading environment variables in local shells
• Added prompt_selector_tool.py and prompt_registry_util.py for prompt/flow management and utilities.
• Report generation scripts store outputs to results/ and prepared_reports/ for integrated reporting and data generation. Generated reports to date include many docs and will be updated in a seperate PR.

Documentation & Onboarding

• Updated main README fas_llm_applications/README.md with Dev Container setup instructions and keyring troubleshooting.
• Sections include: "Features", "Getting Started", "Project Structure", "Environment Variables & Secrets", "PromptFlow Connections", and "Generated Data & Reports"
• Setup instructions for Dev Containers locally and on Codespaces and keyring troubleshooting.
• Added fas_llm_applications/digital_latin_project/README.md explaining components, usage, and integration context

Notes

Key Architectural Decisions

• Container-First Development: Prioritizes reproducible, isolated environments over local machine dependencies, reducing onboarding friction and environment drift.
• Credential Security: Secrets injected via repository secrets (Codespaces) or local .env files, never committed to version control. Encrypted storage with non-interactive access.
• PromptFlow Independence: Leverages PromptFlow capabilities while establishing clear boundaries for independent development without upstream framework dependencies.

Documentation Alignment

• Please confirm that the updated instructions in the main README under "Getting Started", "Environment Variables & Secrets", and "PromptFlow Connections" are clear and complete with respect to your setup experience.

Testing & Verification

• Dev Container launch - verified dependency installation and virtual environment activation
• Promptflow connections - confirmed scripts execute without prompts when KEYRING_CRYPTFILE_PASSWORD is set
• Repository configuration - validated .gitignore preserves necessary files while excluding environment-specific ones
• Codespaces workflow - To be implemented and tested in a future branch/PR. Codespaces has a different workspace when running changes from the fas_llm_applications/.devcontainer and so the devcontainer needs to be adjusted, secrets and credentials need to be added to codespaces environment to populate variables. This is in development.