[Improvement] Enforce Python module boundaries in CI and modularize gpt-rag-ui

[placerda]

Summary

Complete the remaining Python modularization work by:

1. enforcing the existing architecture and error-handling rules through CI; and
2. migrating gpt-rag-ui from flat root modules to a structured src package.

The orchestrator structure, shared audit contracts, existing typed contracts, and ADRs should be reused rather than replaced.

Why will we implement this?

• Problem / opportunity:

  • Current Python CI workflows primarily run tests but do not enforce linting, static typing, import cycles, or documented package boundaries.
  • Architecture and error-handling expectations are documented but depend on manual review.
  • gpt-rag-ui still contains most runtime modules at the repository root, unlike the structured orchestrator layout.

• Business value / outcome:

  • Prevent architecture drift.
  • Detect type and dependency problems during pull requests.
  • Make the UI code easier to navigate and maintain.
  • Enforce consistent error behavior automatically.

• Success metrics (how we know it worked):

  • All three Python repositories run linting and static type checking in CI.
  • CI detects import cycles and prohibited package dependencies.
  • Blind or overly broad exception handling is rejected or explicitly justified.
  • gpt-rag-ui runtime code is packaged under src/.
  • Existing APIs, imports, configuration, and deployment behavior remain compatible.

What does it do? (Functional Overview)

• Core behavior:

  1. Add Ruff configuration and required CI checks to:

     • gpt-rag-orchestrator
     • gpt-rag-ingestion
     • gpt-rag-ui

  2. Add static type checking using an incremental baseline:

     • begin with the currently typed modules;
     • prevent new violations;
     • gradually expand blocking coverage.

  3. Add automated import checks:

     • detect circular imports;
     • encode the boundaries already documented in AGENTS.md;
     • prevent imports from another package's internal modules.

  4. Strengthen error-handling enforcement:

     • enable checks for blind exception handlers;
     • require explicit handling or documented exceptions;
     • add targeted tests for public boundaries that must not return success-shaped fallbacks.

  5. Migrate gpt-rag-ui to a structure such as:

     src/
       gpt_rag_ui/
         api/
         auth/
         clients/
         services/
         telemetry/
         util/
     tests/
     

  6. Keep main.py and app.py as thin compatibility or startup entry points while internal imports move to the package.

  7. Complete the migration through incremental pull requests so each step remains independently deployable.

• Data collection / storage needs: None.

• Data analysis / reporting needs: CI should expose lint, typing, import-boundary, and test results.

• Nice to have (stretch goals):

  • Vendor the existing conversations-panel contract in gpt-rag-ui and generate typed UI models.
  • Apply the same src layout to ingestion after evaluating compatibility impact.
  • Reuse a common CI configuration across the Python repositories.

Out of scope

• Replacing the existing audit and telemetry contracts.
• Reorganizing the orchestrator package structure again.
• Creating a shared cross-repository JWT implementation.
• Creating a new shared Azure client repository.
• Changing the current multi-repository topology.

Components

• Components (check all that apply):
  • gpt-rag-orchestrator
  • gpt-rag-ingestion
  • gpt-rag-ui
  • gpt-rag-mcp