Fix remaining linting issues with comprehensive approach

- Configure pyproject.toml to ignore print statements in tutorials, tests, and dev tools
- Add file-level noqa for temporal workflow interface arguments
- Add inline noqa for unused provider parameters and framework callbacks
- Disable ARG001/ARG002/ARG005 for test patterns in pyproject.toml

Author: prassanna-ravishankar

LINTING-CALLOUTS.md

@@ -1,71 +1,88 @@
 # Linting Callouts and Remaining Issues
 
 ## Summary
-Fixed 213 out of 335 linting issues (63% improvement). Remaining 122 issues are mostly in tutorial files and specific edge cases.
+**Progress**: Fixed ~220 out of 335 linting issues (66% improvement) with additional inline ignores for obvious cases.
 
-## Questions/Decisions Needed
+**Fixed Issues**: Import sorting, exception handling, obvious unused parameters, core library logging
+**Remaining**: Mostly tutorial files, complex workflow interfaces, and test patterns
 
-### 1. Tutorial Print Statements (T201)
-**Status**: Left as-is
-**Issue**: Many tutorial notebooks and example files contain `print()` statements
-**Question**: Should tutorial `print()` statements be left for educational purposes, or converted to logger calls?
-**Files**: All tutorial dev.ipynb files, tutorial project files
+## Remaining Issues Analysis & Suggestions
 
-### 2. Unused Arguments in Workflow/Activity Functions (ARG001/ARG002)
-**Status**: Partially fixed
-**Issue**: Many temporal workflow and activity functions have unused `context` parameters that are required by the framework
-**Question**: Should these be prefixed with underscore or left as-is since they're part of the temporal interface?
+### 1. Tutorial Print Statements (T201) - ~65 issues
+**Files**: All tutorial `dev.ipynb` files and some project files
+**Suggestion**: Consider these approaches:
+- **Option A**: Add `# noqa: T201` to tutorial print statements (keeps educational value)
+- **Option B**: Replace with `logger.info()` calls (promotes best practices)
+- **Option C**: Disable T201 for tutorial directories in pyproject.toml
+
+**Recommendation**: Option A - tutorials should demonstrate actual usage patterns users expect.
+
+### 2. Temporal Workflow/Activity Arguments (ARG001/ARG002) - ~25 issues
 **Files**:
 - `examples/tutorials/10_agentic/10_temporal/*/project/workflow.py`
-- Various activity and handler functions
+- `examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal/project/state_machines/content_workflow.py`
+
+**Issues**:
+- `context` parameters required by Temporal framework but not used in simple examples
+- `ctx`, `agent` parameters in workflow signal handlers
+- `state_machine`, `state_machine_data` parameters in state machine handlers
+
+**Suggestions**:
+- Add `# noqa: ARG001` to temporal interface methods that need unused context
+- Consider using `_context` naming for clearly unused framework parameters
+- For state machine: May indicate over-parameterized interface design
 
-### 3. Test File Print Statements
-**Status**: Left as-is
-**Issue**: Test runner and dev tools intentionally use print for user output
+### 3. Test-Related Arguments (ARG001/ARG002/ARG005) - ~15 issues
+**Files**:
+- `tests/test_function_tool.py`
+- `tests/test_header_forwarding.py`
+- Various test helper functions
+
+**Suggestion**: Add `# noqa: ARG001` for test fixtures and mock function parameters that are required by test framework patterns.
+
+### 4. Development/Debug Tools (T201) - ~10 issues
 **Files**:
 - `src/agentex/lib/sdk/fastacp/tests/run_tests.py`
 - `src/agentex/lib/utils/dev_tools/async_messages.py`
 
-### 4. Debug Template Import Error Setup
-**Status**: Left error print statements
-**Issue**: Debug setup in templates still uses print() for error cases (ImportError, Exception)
-**Question**: Should error messages stay as print() to ensure they're visible even if logging isn't set up?
-
-## Remaining Issues by Category
-
-### Print Statements (T201) - 85 issues
-- **Tutorial notebooks**: 67 issues across example/tutorial dev.ipynb files
-- **Test/Dev tools**: 15 issues in test runners and dev utilities
-- **Template error handling**: 3 issues in Jinja template error cases
-
-### Unused Arguments (ARG*) - 36 issues
-- **Temporal workflows**: Required by framework but unused
-- **Test fixtures**: Standard pytest/test patterns
-- **CLI init functions**: Legacy parameters
-- **Lambda functions**: Anonymous function parameters
-
-### Import Issues (I001, F401, TC004) - 1 issue
-- **Type checking import**: One import used outside type checking block
-
-## Fixed Issues (213 total)
-- ✅ Import sorting (I001): 190+ issues
-- ✅ Unused imports (F401): Multiple files
-- ✅ Exception handling (B904): Added proper exception chaining
-- ✅ Return in finally (B012): Restructured exception handling
-- ✅ Bare except (E722): Specified Exception type
-- ✅ Blind exception assert (B017): Specified exact exception types
-- ✅ Core library print statements: Converted to logger calls
-- ✅ Template print statements: Fixed debug logging in Jinja templates
-
-## Recommendations for PR Discussion
-
-1. **Tutorial Policy**: Establish whether tutorials should use print() or logger
-2. **Framework Interface**: Decide on unused parameter naming for temporal/framework interfaces
-3. **Test Output**: Confirm test runners should keep print() for user visibility
-4. **Error Handling**: Review if debug setup errors should remain as print() statements
-
-## Files with Significant Remaining Issues
-- Tutorial notebooks: All dev.ipynb files (print statements)
-- `examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal/project/state_machines/content_workflow.py` (8 unused arguments)
-- `examples/tutorials/10_agentic/10_temporal/050_agent_chat_guardrails/project/workflow.py` (10 unused arguments)
-- Various test files (unused test fixture parameters)
+**Suggestion**: These are intentionally using print() for direct user output in CLI tools. Add `# noqa: T201` or exclude these directories from T201 checks.
+
+### 5. Provider/Service Arguments - ~8 issues
+**Files**:
+- `src/agentex/lib/core/services/adk/providers/openai.py`
+- `src/agentex/lib/core/temporal/workers/worker.py`
+
+**Suggestion**: These appear to be interface consistency parameters or future extension points. Add `# noqa: ARG002` with comments explaining the purpose.
+
+## Recommended Actions
+
+### Quick Wins (can be automated):
+```bash
+# Add noqa comments to tutorial notebooks (if keeping print statements)
+find examples/tutorials -name "*.py" -o -name "*.ipynb" | xargs sed -i 's/print(/print(  # noqa: T201/g'
+
+# Add noqa to test fixtures
+grep -r "def.*context.*:" tests/ | # add # noqa: ARG001 to test helper functions
+```
+
+### Configuration Option:
+Add to `pyproject.toml`:
+```toml
+[tool.ruff]
+per-file-ignores = {
+    "examples/tutorials/**" = ["T201"],  # Allow prints in tutorials
+    "tests/**" = ["ARG001", "ARG002"],   # Allow unused test params
+    "**/run_tests.py" = ["T201"],        # Allow prints in test runners
+    "**/dev_tools/**" = ["T201"],        # Allow prints in dev tools
+}
+```
+
+### Complex Cases Needing Review:
+1. **State Machine Interface**: 8 unused parameters suggest possible over-parameterization
+2. **OpenAI Provider**: `previous_response_id` parameter - verify if this is used elsewhere or future feature
+3. **Worker Lambda**: Request parameter in worker registration - may be temporal framework requirement
+
+## Current Status
+- **Easy fixes applied**: Import sorting, exception handling, obvious unused parameters
+- **Inline ignores added**: Deprecated functions, framework callbacks, configuration parameters
+- **Remaining**: ~115 issues, mostly in tutorials and test patterns that can be bulk-ignored or are legitimate design choices

examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal/project/state_machines/content_workflow.py

@@ -1,3 +1,4 @@
+# ruff: noqa: ARG002
 import json
 import asyncio
 from enum import Enum

examples/tutorials/10_agentic/10_temporal/010_agent_chat/project/workflow.py

@@ -61,7 +61,7 @@ class StateModel(BaseModel):
 ]
 
 
-async def calculator(context: RunContextWrapper, args: str) -> str:
+async def calculator(context: RunContextWrapper, args: str) -> str:  # noqa: ARG001
     """
     Simple calculator that can perform basic arithmetic operations.
 

examples/tutorials/10_agentic/10_temporal/050_agent_chat_guardrails/project/workflow.py

@@ -1,3 +1,4 @@
+# ruff: noqa: ARG001
 import os
 import json
 from typing import Any, Dict, List, override
@@ -77,7 +78,7 @@ class StateModel(BaseModel):
 ]
 
 
-async def calculator(context: RunContextWrapper, args: str) -> str:
+async def calculator(context: RunContextWrapper, args: str) -> str:  # noqa: ARG001
     """
     Simple calculator that can perform basic arithmetic operations.
 

pyproject.toml

@@ -298,5 +298,8 @@ known-first-party = ["agentex", "tests"]
 [tool.ruff.lint.per-file-ignores]
 "bin/**.py" = ["T201", "T203"]
 "scripts/**.py" = ["T201", "T203"]
-"tests/**.py" = ["T201", "T203"]
+"tests/**.py" = ["T201", "T203", "ARG001", "ARG002", "ARG005"]
 "examples/**.py" = ["T201", "T203"]
+"examples/tutorials/**.py" = ["T201", "T203"]
+"**/run_tests.py" = ["T201", "T203"]
+"**/dev_tools/**.py" = ["T201", "T203"]

src/agentex/lib/core/services/adk/providers/openai.py

@@ -176,7 +176,7 @@ async def run_agent(
         input_guardrails: list[InputGuardrail] | None = None,
         output_guardrails: list[OutputGuardrail] | None = None,
         max_turns: int | None = None,
-        previous_response_id: str | None = None,
+        previous_response_id: str | None = None,  # noqa: ARG002
     ) -> RunResult:
         """
         Run an agent without streaming or TaskMessage creation.
@@ -303,7 +303,7 @@ async def run_agent_auto_send(
         input_guardrails: list[InputGuardrail] | None = None,
         output_guardrails: list[OutputGuardrail] | None = None,
         max_turns: int | None = None,
-        previous_response_id: str | None = None,
+        previous_response_id: str | None = None,  # noqa: ARG002
     ) -> RunResult:
         """
         Run an agent with automatic TaskMessage creation.
@@ -504,7 +504,7 @@ async def run_agent_streamed(
         input_guardrails: list[InputGuardrail] | None = None,
         output_guardrails: list[OutputGuardrail] | None = None,
         max_turns: int | None = None,
-        previous_response_id: str | None = None,
+        previous_response_id: str | None = None,  # noqa: ARG002
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled but no TaskMessage creation.
@@ -630,7 +630,7 @@ async def run_agent_streamed_auto_send(
         input_guardrails: list[InputGuardrail] | None = None,
         output_guardrails: list[OutputGuardrail] | None = None,
         max_turns: int | None = None,
-        previous_response_id: str | None = None,
+        previous_response_id: str | None = None,  # noqa: ARG002
     ) -> RunResultStreaming:
         """
         Run an agent with streaming enabled and automatic TaskMessage creation.

src/agentex/lib/core/temporal/workers/worker.py

@@ -160,7 +160,7 @@ async def _health_check(self):
     async def start_health_check_server(self):
         if not self.health_check_server_running:
             app = web.Application()
-            app.router.add_get("/readyz", lambda request: self._health_check())
+            app.router.add_get("/readyz", lambda request: self._health_check())  # noqa: ARG005
 
             # Disable access logging
             runner = web.AppRunner(app, access_log=None)