Azure / Azure/GPT-RAG

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

Open
#681 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.2k
Forks
321
Avg merge
6h 22m
Merged PRs (30d)
26

Description

## 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:

```text
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):**
- [x] gpt-rag-orchestrator
- [x] gpt-rag-ingestion
- [x] gpt-rag-ui
- [ ] gpt-rag-mcp

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing CI workflows, AGENTS.md, typed modules, audit contracts, and ADRs across the three named repositories. Then inspect gpt-rag-ui's root runtime modules plus main.py and app.py to map the proposed src/gpt_rag_ui structure. Done means CI reports lint, typing, import-boundary, exception, and test results while UI imports, APIs, configuration, and deployment remain compatible.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, ci-cd, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.