[DX] Add Python code formatting & linting infrastructure (ruff, pre-commit, CI)

[Edison-A-N]

Problem

The project declares black, flake8, mypy，和 pre-commit in [project.optional-dependencies] dev, but none of them are actually configured or enforced:

Tool	In dev deps?	Config present?	CI check?
black	✅ >=23.7.0	❌ No [tool.black]	❌
flake8	✅ >=6.0.0	❌ No .flake8	❌
isort	❌ Not listed	❌	❌
mypy	✅ >=1.5.0	❌ No [tool.mypy]	❌
pre-commit	✅ >=3.3.0	❌ No .pre-commit-config.yaml	❌

As a result, the 279 Python source files under src/ have no automated formatting or linting — style is entirely dependent on individual contributor habits. Common issues observed:

• Inconsistent import ordering (e.g., from pathlib import Path appearing in the middle of third-party imports in sdk/network.py)
• No format-on-save in .vscode/settings.json (only python.pythonPath is set)
• GitHub Actions (pytest.yml) only runs tests — no lint or format check gate on PRs

Proposal

Replace the current unused black + flake8 + isort stack with Ruff — a single tool that handles formatting, linting, and import sorting, ~100x faster than the individual tools.

Concrete changes

1. pyproject.toml — Add [tool.ruff] configuration:

   [tool.ruff]
   target-version = "py310"
   line-length = 120
   src = ["src"]
   
   [tool.ruff.lint]
   select = ["E", "F", "W", "I", "UP", "B", "SIM"]
   ignore = ["E501"]  # line length handled by formatter
   
   [tool.ruff.lint.isort]
   known-first-party = ["openagents"]
   
   [tool.ruff.format]
   quote-style = "double"

2. pyproject.toml — Update dev dependencies:

   - "black>=23.7.0",
   - "flake8>=6.0.0",
   + "ruff>=0.4.0",

3. .pre-commit-config.yaml — Create with ruff hooks:

   repos:
     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.4.0
       hooks:
         - id: ruff
           args: [--fix]
         - id: ruff-format

4. CI — Add a lint job to .github/workflows/pytest.yml (or a new lint.yml):

   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/ruff-action@v3

5. .vscode/settings.json — Add format-on-save:

   {
     "[python]": {
       "editor.defaultFormatter": "charliermarsh.ruff",
       "editor.formatOnSave": true,
       "editor.codeActionsOnSave": {
         "source.fixAll.ruff": "explicit",
         "source.organizeImports.ruff": "explicit"
       }
     }
   }

6. (Optional) [tool.mypy] — Add basic strict config for gradual adoption.

7. (Optional) One-time ruff format . && ruff check --fix . to normalize existing code. This will touch most files — could be done as a single dedicated PR to keep blame clean (with a .git-blame-ignore-revs entry).

Migration strategy

Two reasonable approaches:

• Gradual: Only add config + pre-commit + CI. New/modified files get fixed on each PR. No big-bang reformatting.
• Big-bang: One PR that runs ruff format . + ruff check --fix . on all 279 files, then adds a .git-blame-ignore-revs entry. Followed by config + CI PR.

Additional context

• Ruff is already the de facto standard for new Python projects (used by FastAPI, Pydantic, pandas, etc.)
• It natively replaces black, flake8, isort, pyupgrade, and dozens of flake8 plugins
• Pre-commit + CI gate ensures no unformatted code merges going forward

[linear]

OADEV-43

[JiwaniZakir]

The core issue is that the dev dependencies in pyproject.toml were listed without any accompanying configuration, making them effectively decorative — black, flake8, and mypy all require explicit config sections ([tool.black], .flake8, [tool.mypy]) or they either run with defaults or not at all. The absence of a .pre-commit-config.yaml means pre-commit was never actually wired up, so even contributors who ran pre-commit install would have gotten no hooks. Worth noting that the pytest.yml CI pipeline only invoking tests (and not a lint/format step) means this gap has been silently accumulating across all 279 source files with no enforcement point at any stage of the contribution flow.

[QuanCheng-QC]

Thanks — this is a valid tooling gap. The repo currently declares several dev tools, but we aren’t enforcing formatting/linting in pre-commit or CI yet.

I’m planning to address this in phases:

add Ruff config, pre-commit hooks, and a CI lint/format gate;
keep the initial ruleset conservative to avoid noisy repo-wide churn;
discuss broader auto-fixes and mypy enforcement separately.