Add lint CI and apply style cleanups

Add a GitHub Actions workflow to run ruff and mypy on changed Python files and add ruff/mypy to the dev dependency group with minimal configs in pyproject.toml. Apply widespread non-functional style and formatting changes across the codebase (whitespace, line-wrapping, minor import reorderings, single-line logging calls, and test formatting tweaks) to satisfy linting/formatting. No behavioral logic changes intended.

Author: edwinjosechittilappilly

.github/workflows/lint-backend.yml

@@ -0,0 +1,85 @@
+name: Lint Backend
+
+on:
+  pull_request:
+    paths:
+      - 'src/**.py'
+      - 'tests/**.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/lint-backend.yml'
+
+# Cancel in-flight runs on the same PR when a new push lands.
+concurrency:
+  group: lint-backend-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Ruff and mypy on changed files
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need the full base ref locally so we can compute the diff
+          # against the PR's merge base.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dev dependencies
+        run: uv sync --group dev
+
+      - name: Compute changed Python files
+        id: changed
+        run: |
+          base="${{ github.event.pull_request.base.sha }}"
+          head="${{ github.event.pull_request.head.sha }}"
+          # Diff against the merge base so we only see files touched in the PR.
+          merge_base=$(git merge-base "$base" "$head")
+          mapfile -t files < <(git diff --name-only --diff-filter=ACMR "$merge_base" "$head" -- '*.py')
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No Python files changed."
+            echo "files=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          printf '%s\n' "${files[@]}"
+          # Pass as a single space-separated string to subsequent steps.
+          echo "files=${files[*]}" >> "$GITHUB_OUTPUT"
+
+      - name: Ruff (auto-fix dry run + format check)
+        if: steps.changed.outputs.files != ''
+        run: |
+          # `--no-fix` reports the same set of issues that `--fix` would
+          # apply, so the developer sees what to run locally to clean up.
+          uv run ruff check --no-fix --output-format=github ${{ steps.changed.outputs.files }}
+          uv run ruff format --check ${{ steps.changed.outputs.files }}
+
+      - name: Mypy
+        if: steps.changed.outputs.files != ''
+        run: |
+          # Run mypy from src/ so module paths resolve, dropping the
+          # leading "src/" from each path. Tests files are checked from
+          # the repo root.
+          src_files=()
+          test_files=()
+          for f in ${{ steps.changed.outputs.files }}; do
+            case "$f" in
+              src/*) src_files+=("${f#src/}") ;;
+              tests/*) test_files+=("$f") ;;
+            esac
+          done
+          if [ "${#src_files[@]}" -gt 0 ]; then
+            (cd src && uv run mypy "${src_files[@]}")
+          fi
+          if [ "${#test_files[@]}" -gt 0 ]; then
+            uv run mypy "${test_files[@]}"
+          fi

pyproject.toml

@@ -63,7 +63,14 @@ dependencies = [
 ]
 
 [dependency-groups]
-dev = ["pytest>=9.0.3", "pytest-asyncio>=0.21.0", "pytest-mock>=3.12.0", "pytest-cov>=4.0.0"]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.21.0",
+    "pytest-mock>=3.12.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.15.12",
+    "mypy>=2.0.0",
+]
 
 [project.scripts]
 openrag = "tui.main:run_tui"
@@ -77,4 +84,22 @@ filterwarnings = [
 package = true
 override-dependencies = ["python-dotenv>=1.1.0"]
 
+# Ruff and mypy run only against files changed in a PR (see
+# .github/workflows/lint-backend.yml). The configs below stay
+# intentionally minimal — broad enforcement is out of scope for the
+# refactor that introduced them.
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]  # line-length handled by formatter
+
+[tool.mypy]
+python_version = "3.13"
+ignore_missing_imports = true
+no_strict_optional = true
+warn_unused_ignores = true
+
 

src/api/health.py

@@ -1,4 +1,5 @@
 """Liveness and readiness probes."""
+
 import asyncio
 
 import httpx
@@ -21,9 +22,7 @@ async def opensearch_health_ready(request):
     from config.settings import IBM_AUTH_ENABLED, OPENSEARCH_URL
 
     if IBM_AUTH_ENABLED:
-        logger.debug(
-            "[OPENSEARCH] OpenSearch auth mode enabled, health check per-request"
-        )
+        logger.debug("[OPENSEARCH] OpenSearch auth mode enabled, health check per-request")
         # In IBM auth mode we cannot rely on the global OpenSearch client
         # (auth is established per-request), so perform a lightweight,
         # unauthenticated connectivity check against the OpenSearch endpoint.
@@ -53,9 +52,7 @@ async def opensearch_health_ready(request):
                     status_code=503,
                 )
         except Exception as e:
-            logger.error(
-                "[OPENSEARCH] OpenSearch health check failed", error=str(e)
-            )
+            logger.error("[OPENSEARCH] OpenSearch health check failed", error=str(e))
             return JSONResponse(
                 {
                     "status": "not_ready",
@@ -72,9 +69,7 @@ async def opensearch_health_ready(request):
             status_code=200,
         )
     except Exception as e:
-        logger.error(
-            "[OPENSEARCH] OpenSearch health check failed", error=str(e)
-        )
+        logger.error("[OPENSEARCH] OpenSearch health check failed", error=str(e))
         return JSONResponse(
             {
                 "status": "not_ready",

src/app/container.py

@@ -2,6 +2,7 @@
 
 Returns a dict consumed by routes (via FastAPI Depends) and the lifespan hook.
 """
+
 import os
 
 from api.connector_router import ConnectorRouter
@@ -31,16 +32,14 @@
 from session_manager import SessionManager
 from utils.jwt_keygen import generate_jwt_keys
 from utils.logging_config import get_logger
-from utils.telemetry import TelemetryClient, Category, MessageId
+from utils.telemetry import Category, MessageId, TelemetryClient
 
 logger = get_logger(__name__)
 
 
 async def initialize_services():
     """Initialize all services and their dependencies"""
-    await TelemetryClient.send_event(
-        Category.SERVICE_INITIALIZATION, MessageId.ORB_SVC_INIT_START
-    )
+    await TelemetryClient.send_event(Category.SERVICE_INITIALIZATION, MessageId.ORB_SVC_INIT_START)
     from config.settings import IBM_AUTH_ENABLED
 
     if IBM_AUTH_ENABLED:
@@ -128,9 +127,7 @@ async def initialize_services():
                 loaded_count=loaded_count,
             )
         except Exception as e:
-            logger.error(
-                "Failed to load persisted connections on startup", error=str(e)
-            )
+            logger.error("Failed to load persisted connections on startup", error=str(e))
             await TelemetryClient.send_event(
                 Category.CONNECTOR_OPERATIONS, MessageId.ORB_CONN_LOAD_FAILED
             )
@@ -179,8 +176,9 @@ def _lazy_session_factory():
     # (session_ownership + conversation_persistence). They lazy-resolve
     # `db.engine.SessionLocal` as a fallback, but setting it here makes
     # the wiring explicit and avoids the import path on the hot loop.
-    from services.session_ownership_service import session_ownership_service
     from services.conversation_persistence_service import conversation_persistence
+    from services.session_ownership_service import session_ownership_service
+
     session_ownership_service._session_factory = _lazy_session_factory
     conversation_persistence._session_factory = _lazy_session_factory
 

src/app/factory.py

@@ -3,6 +3,7 @@
 Wires the service container, middleware, routes, and lifespan together
 into a ready-to-serve FastAPI app.
 """
+
 from fastapi import FastAPI
 from prometheus_fastapi_instrumentator import Instrumentator
 

src/app/lifespan.py

@@ -8,6 +8,7 @@
 Order matches the original behavior exactly — see plan
 main-py-is-too-long-wiggly-knuth.md.
 """
+
 import asyncio
 import os
 
@@ -16,7 +17,7 @@
 from config.settings import clients, get_openrag_config
 from services.startup_orchestrator import startup_tasks
 from utils.logging_config import get_logger
-from utils.telemetry import TelemetryClient, Category, MessageId
+from utils.telemetry import Category, MessageId, TelemetryClient
 
 logger = get_logger(__name__)
 
@@ -31,9 +32,7 @@ async def cleanup_subscriptions_proper(services):
 
         all_connections = await connector_service.connection_manager.list_connections()
         active_connections = [
-            c
-            for c in all_connections
-            if c.is_active and c.config.get("webhook_channel_id")
+            c for c in all_connections if c.is_active and c.config.get("webhook_channel_id")
         ]
 
         for connection in active_connections:
@@ -42,15 +41,11 @@ async def cleanup_subscriptions_proper(services):
                     "Cancelling subscription for connection",
                     connection_id=connection.connection_id,
                 )
-                connector = await connector_service.get_connector(
-                    connection.connection_id
-                )
+                connector = await connector_service.get_connector(connection.connection_id)
                 if connector:
                     subscription_id = connection.config.get("webhook_channel_id")
                     await connector.cleanup_subscription(subscription_id)
-                    logger.info(
-                        "Cancelled subscription", subscription_id=subscription_id
-                    )
+                    logger.info("Cancelled subscription", subscription_id=subscription_id)
             except Exception as e:
                 logger.error(
                     "Failed to cancel subscription",
@@ -75,17 +70,13 @@ async def _periodic_backup(services):
 
             config = get_openrag_config()
             if not config.edited:
-                logger.debug(
-                    "Onboarding not completed yet, skipping periodic backup"
-                )
+                logger.debug("Onboarding not completed yet, skipping periodic backup")
                 continue
 
             flows_service = services.get("flows_service")
             if flows_service:
                 logger.info("Running periodic flow backup")
-                backup_results = await flows_service.backup_all_flows(
-                    only_if_changed=True
-                )
+                backup_results = await flows_service.backup_all_flows(only_if_changed=True)
                 if backup_results["backed_up"]:
                     logger.info(
                         "Periodic backup completed",
@@ -147,6 +138,7 @@ async def run_startup(app: FastAPI):
     # the operator owns the trade-off.
     from services.rbac_service import is_rbac_enforced
     from utils.run_mode_utils import get_run_mode
+
     if is_rbac_enforced():
         logger.info("RBAC enforcement is ON", run_mode=get_run_mode())
     else:
@@ -163,6 +155,7 @@ async def run_startup(app: FastAPI):
     # at call time, so it will pick up the binding we set here.
     try:
         from db.engine import init_engine
+
         init_engine()
     except Exception as e:
         logger.error("DB engine init failed at startup", error=str(e))
@@ -173,6 +166,7 @@ async def run_startup(app: FastAPI):
     try:
         from db.engine import SessionLocal as _SL
         from db.migrations_runtime import run as run_runtime_migration
+
         if _SL is not None:
             async with _SL() as _session:
                 await run_runtime_migration(_session)
@@ -181,9 +175,7 @@ async def run_startup(app: FastAPI):
         logger.error("Runtime DB migration failed", error=str(e))
         raise
 
-    await TelemetryClient.send_event(
-        Category.APPLICATION_STARTUP, MessageId.ORB_APP_STARTED
-    )
+    await TelemetryClient.send_event(Category.APPLICATION_STARTUP, MessageId.ORB_APP_STARTED)
 
     # FastMCP requires its own lifespan to be entered before requests
     # arrive so the StreamableHTTPSessionManager task group exists.
@@ -212,9 +204,7 @@ async def run_shutdown(app: FastAPI):
 
     logger.info("Application shutdown initiated")
 
-    await TelemetryClient.send_event(
-        Category.APPLICATION_SHUTDOWN, MessageId.ORB_APP_SHUTDOWN
-    )
+    await TelemetryClient.send_event(Category.APPLICATION_SHUTDOWN, MessageId.ORB_APP_SHUTDOWN)
 
     # Drain any pending workspace_config DB-mirror tasks before we
     # tear down the engine. Without this, a save_config triggered
@@ -238,6 +228,7 @@ async def run_shutdown(app: FastAPI):
     # Gracefully shutdown OpenSearch connection
     try:
         from utils.opensearch_utils import graceful_opensearch_shutdown
+
         await graceful_opensearch_shutdown(clients.opensearch)
     except Exception as e:
         logger.error("Error during graceful OpenSearch shutdown", error=str(e))
@@ -252,11 +243,13 @@ async def run_shutdown(app: FastAPI):
     # path did this; the live shutdown_event leaked the engine.
     try:
         from db.engine import dispose_engine
+
         await dispose_engine()
     except Exception as e:
         logger.error("Error disposing DB engine", error=str(e))
 
     # Cleanup telemetry client
     from utils.telemetry.client import cleanup_telemetry_client
+
     await cleanup_telemetry_client()
     logger.info("Application shutdown completed")

src/app/middleware.py

@@ -1,4 +1,5 @@
 """ASGI middleware for request correlation IDs and structured access logs."""
+
 import time
 import uuid
 
@@ -31,9 +32,7 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         _structlog.contextvars.clear_contextvars()
 
         headers_dict = dict(scope.get("headers", []))
-        request_id = (
-            headers_dict.get(b"x-request-id", b"").decode() or str(uuid.uuid4())
-        )
+        request_id = headers_dict.get(b"x-request-id", b"").decode() or str(uuid.uuid4())
         path = scope.get("path", "")
         method = scope.get("method", "")
 

src/app/routes/__init__.py

@@ -3,6 +3,7 @@
 The factory calls `register_all_routes(app, services)`. Each sub-module
 owns one cohesive group of endpoints.
 """
+
 from fastapi import FastAPI
 
 from app.routes.internal import register_internal_routes