From 2a58c2208ffbdbefa785f8117441fb86792b5fcd Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sat, 13 Jun 2026 20:29:24 +0000
Subject: [PATCH] ci: add test/lint/smoke workflow, declare python-dotenv,
 recommend Python 3.12

GitHub Actions: pytest across Python 3.10-3.13, a clean-install import smoke
that catches undeclared runtime deps, and a strict Ruff gate (standard rule set)
scoped to the files each PR changes. Declares python-dotenv (imported by the CLI
but previously undeclared) and adds a [dev] extra. Recommends Python 3.12 for
setup, verified from a clean isolated install.
---
 .github/workflows/ci.yml | 75 ++++++++++++++++++++++++++++++++++++++++
 README.md                |  2 +-
 pyproject.toml           | 24 +++++++++++++
 3 files changed, 100 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..e0370afc5
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run test suite
+        run: pytest -q
+
+  smoke-install:
+    name: clean-install smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Fresh install (no dev extras) and import
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          # Catches undeclared runtime deps (e.g. #994 python-dotenv): a bare
+          # install must import the package and the CLI module.
+          python -c "import tradingagents, cli.main; print('clean-install import OK')"
+
+  lint:
+    name: ruff (changed files, strict)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff>=0.15"
+      - name: Lint only the Python files this PR changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          # Strict going-forward gate: the full-repo cleanup is deferred (see
+          # worklog 03/01), so we lint only files this PR adds or modifies.
+          files=$(git diff --name-only --diff-filter=ACM "$BASE_SHA"...HEAD -- '*.py' \
+                  | grep -vE '^(results|worklog)/' || true)
+          if [ -z "$files" ]; then
+            echo "No Python changes to lint."
+            exit 0
+          fi
+          echo "Linting changed files:"
+          echo "$files"
+          ruff check $files
diff --git a/README.md b/README.md
index 451d4a2e7..1b2858148 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ cd TradingAgents
 
 Create a virtual environment in any of your favorite environment managers:
 ```bash
-conda create -n tradingagents python=3.13
+conda create -n tradingagents python=3.12
 conda activate tradingagents
 ```
 
diff --git a/pyproject.toml b/pyproject.toml
index 9604c3381..40399819f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -19,6 +19,7 @@ dependencies = [
     "langgraph-checkpoint-sqlite>=2.0.0",
     "pandas>=2.3.0",
     "parsel>=1.10.0",
+    "python-dotenv>=1.0.0",
     "pytz>=2025.2",
     "questionary>=2.1.0",
     "redis>=6.2.0",
@@ -32,6 +33,13 @@ dependencies = [
     "yfinance>=1.4.1",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.15",
+    "pytest>=8.0",
+    "pytest-subtests>=0.13",
+]
+
 [project.scripts]
 tradingagents = "cli.main:app"
 
@@ -52,3 +60,19 @@ markers = [
 filterwarnings = [
     "ignore::DeprecationWarning",
 ]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["results", "worklog"]
+
+[tool.ruff.lint]
+# Standard "good defaults" rule set (pyflakes + pycodestyle + isort + bugbear +
+# pyupgrade + comprehensions/simplify). Line length (E501) and layout are owned
+# by the formatter; whole-repo `ruff format` adoption is deferred until the
+# open-PR backlog clears, to avoid mass merge conflicts.
+select = ["E", "W", "F", "I", "B", "UP", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]   # intentional re-exports