Document Python import style guidelines in AGENTS.md

AGENTS.md

@@ -120,6 +120,16 @@ please follow these guidelines:
   - **Exception**: Explicit re-export patterns like `from ... import X as X` or marked with "# For export"
   - This prevents circular imports and makes dependencies clear
 
+## Python Import Style Guidelines
+
+* **Default to Module-Qualified Imports:** Prefer importing whole modules and using qualified calls (e.g., `import math; math.sqrt(16)` or `import pandas as pd; pd.DataFrame()`) to prevent namespace pollution, avoid name clashes, and provide immediate context for where functions or objects originate.
+* **Use Direct Symbol Imports Cautiously:** Restrict direct imports (`from module import symbol`) to specific scenarios where they genuinely improve readability or adhere to standard conventions:
+  * Importing classes, exceptions, or constants (e.g., `from my_project.models import User`).
+  * Avoiding severe, repetitive visual clutter in heavy mathematical or algorithmic code.
+  * Standard library patterns (e.g., `from collections import defaultdict, Counter`).
+  * **Exception**: In `tests/`, importing functions directly to call them in assertions is idiomatic pytest style and is not held to this restriction (see #298).
+* **Prohibit Wildcard Imports:** Never use wildcard imports (`from module import *`) in normal code. **Exception**: the same explicit re-export aggregator pattern allowed by the Import Architecture Rules above (e.g. `interfaces.py` re-exporting `interfaces_core`, `interfaces_indexes`, etc. with `__all__`) — enforced by `make ruff` (see Makefile), with that file listed in `[tool.ruff.lint.per-file-ignores]`.
+
 * Order imports alphabetically after lowercasing; group them as follows
   (with a blank line between groups):
   1. standard library imports

Makefile

@@ -11,13 +11,19 @@ format: venv
 	uv run isort src tests tools examples $(FLAGS)
 	uv run black -tpy312 src tests tools examples $(FLAGS)
 
-# intentionally running pyright only for the lowest and the highest version 
+# intentionally running pyright only for the lowest and the highest version
 # running it for all versions takes too much time and doesn't add enough diagnostic power
 .PHONY: check
 check: venv
 	uv run pyright --pythonversion 3.12 src tests tools examples
 	uv run pyright --pythonversion 3.15 src tests tools examples
 
+# Not wired into 'all'/CI yet -- see #116. Narrowly scoped for now to
+# deterministically banning wildcard imports (AGENTS.md's import guidelines).
+.PHONY: ruff
+ruff: venv
+	uv run ruff check src tests tools examples
+
 .PHONY: test
 test: venv
 	uv run pytest $(FLAGS)
@@ -105,6 +111,7 @@ help:
 	@echo "make all         # venv, format, check, test, build"
 	@echo "make format      # Run isort and black"
 	@echo "make check       # Run pyright"
+	@echo "make ruff        # Run ruff (wildcard-import checks only, not part of 'all' yet)"
 	@echo "make test        # Run pytest (tests are in tests/)"
 	@echo "make coverage    # Run tests with coverage"
 	@echo "make build       # Build the wheel (under dist/)"

make.bat

@@ -28,6 +28,7 @@ if defined ARGS set "ARGS=%ARGS:~1%"
 :dispatch
 if /I "%CMD%"=="format" goto format
 if /I "%CMD%"=="check" goto check
+if /I "%CMD%"=="ruff" goto ruff
 if /I "%CMD%"=="test" goto test
 if /I "%CMD%"=="coverage" goto coverage
 if /I "%CMD%"=="demo" goto demo
@@ -59,6 +60,14 @@ uv run pyright --pythonversion 3.12 src tests tools examples || exit /b 1
 uv run pyright --pythonversion 3.15 src tests tools examples || exit /b 1
 goto end
 
+:: Not wired into CI yet -- see #116. Narrowly scoped for now to
+:: deterministically banning wildcard imports (AGENTS.md's import guidelines).
+:ruff
+if not exist ".venv\" call make.bat venv
+echo Running ruff...
+uv run ruff check src tests tools examples || exit /b 1
+goto end
+
 :test
 if not exist ".venv\" call make.bat venv
 echo Running unit tests...
@@ -123,7 +132,7 @@ if exist .pytest_cache rmdir /s /q .pytest_cache
 goto end
 
 :help
-echo Usage: .\make [format^|check^|test^|coverage^|demo^|build^|venv^|sync^|install-uv^|clean^|help]
+echo Usage: .\make [format^|check^|ruff^|test^|coverage^|demo^|build^|venv^|sync^|install-uv^|clean^|help]
 goto end
 
 :end

pyproject.toml

@@ -97,6 +97,19 @@ known_ai = ["mcp", "openai", "pydantic", "pydantic_ai", "tiktoken", "typechat"]
 known_first_party = ["typeagent", "tests", "tools", "gmail", "demo"]
 known_local_folder = ["conftest"]
 
+# isort/black/pyright already cover ordering, formatting and unused/duplicate
+# imports (see above). Ruff is scoped narrowly to the one gap those don't
+# fill: deterministically banning wildcard imports, per AGENTS.md's "Python
+# Import Style Guidelines". Broader adoption of ruff as an isort/black
+# replacement was considered and deferred in #116.
+[tool.ruff.lint]
+select = ["F403", "F405"]
+
+[tool.ruff.lint.per-file-ignores]
+# Explicit re-export aggregator (see AGENTS.md's "Import Architecture Rules"
+# and "Prohibit Wildcard Imports" exceptions).
+"src/typeagent/knowpro/interfaces.py" = ["F403", "F405"]
+
 [dependency-groups]
 
 # Dev tooling never reaches the wheel metadata -- these bounds only pick which
@@ -118,4 +131,5 @@ dev = [
   "pytest>=9.1.1",
   "pytest-asyncio>=1.4.0",
   "pytest-mock>=3.15.1",
+  "ruff>=0.16.4",
 ]