cleveragents/cleveragents-core

Fork 3

UAT: 16 functions missing return type annotations or parameter annotations — violates full static typing requirement #1687

New issue

Open

opened 2026-04-02 23:29:39 +00:00 by freemo · 2 comments

freemo commented

2026-04-02 23:29:39 +00:00

Owner

Metadata

Branch: fix/add-missing-type-annotations
Commit Message: fix(typing): add missing return type and parameter annotations to 16 functions
Milestone: v3.5.0
Parent Epic: #397

Background and Context

Static analysis of the source code reveals 16 functions that are missing return type annotations or parameter type annotations. The project specification and CONTRIBUTING.md require that "Every function signature, variable declaration, and return type must have explicit type annotations."

This was discovered during UAT testing via AST-based analysis of all Python source files in src/cleveragents/.

Expected Behavior

Per the project specification and CONTRIBUTING.md:

"All code must be statically typed. Every function signature, variable declaration, and return type must have explicit type annotations."

All functions must have explicit return type annotations and all parameters (except self/cls) must have type annotations.

Actual Behavior

16 annotation violations found across 6 files:

src/cleveragents/agents/__init__.py:56: function "__getattr__" missing return annotation
src/cleveragents/application/container.py:121: function "_build_stream_router" missing return annotation
src/cleveragents/application/container.py:128: function "_build_langgraph_bridge" missing return annotation
src/cleveragents/application/container.py:128: function "_build_langgraph_bridge" arg "stream_router" missing annotation
src/cleveragents/application/container.py:135: function "_build_route_bridge" missing return annotation
src/cleveragents/application/container.py:135: function "_build_route_bridge" arg "stream_router" missing annotation
src/cleveragents/application/container.py:135: function "_build_route_bridge" arg "agents" missing annotation
src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" missing return annotation
src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "stream_router" missing annotation
src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "route_bridge" missing annotation
src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "actor_registry" missing annotation
src/cleveragents/application/services/__init__.py:565: function "__getattr__" missing return annotation
src/cleveragents/cli/commands/actor.py:203: function "_get_services" missing return annotation
src/cleveragents/cli/commands/plan.py:1056: function "_get_lifecycle_service" missing return annotation
src/cleveragents/cli/commands/plan.py:2575: function "_get_apply_service" missing return annotation
src/cleveragents/langgraph/__init__.py:13: function "__getattr__" missing return annotation

Breakdown by file:

src/cleveragents/application/container.py: 8 violations (4 functions missing return types, 4 parameters missing annotations)
src/cleveragents/agents/__init__.py: 1 violation (__getattr__ missing return type)
src/cleveragents/application/services/__init__.py: 1 violation (__getattr__ missing return type)
src/cleveragents/cli/commands/actor.py: 1 violation (_get_services missing return type)
src/cleveragents/cli/commands/plan.py: 2 violations (_get_lifecycle_service and _get_apply_service missing return types)
src/cleveragents/langgraph/__init__.py: 1 violation (__getattr__ missing return type)

Steps to Reproduce

python3 -c "
import ast, os
issues = []
for root, dirs, files in os.walk('src/cleveragents'):
    for fname in files:
        if fname.endswith('.py'):
            path = os.path.join(root, fname)
            with open(path) as f:
                tree = ast.parse(f.read())
            for node in ast.walk(tree):
                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                    if node.returns is None and node.name != '__init__':
                        issues.append(f'{path}:{node.lineno}: function \"{node.name}\" missing return annotation')
                    for arg in node.args.args + node.args.posonlyargs + node.args.kwonlyargs:
                        if arg.annotation is None and arg.arg not in ('self', 'cls'):
                            issues.append(f'{path}:{node.lineno}: function \"{node.name}\" arg \"{arg.arg}\" missing annotation')
print(f'Total: {len(issues)}')
for i in issues: print(i)
"

Acceptance Criteria

All 16 annotation violations listed above are resolved with correct, meaningful type annotations.
No new annotation violations are introduced.
The AST-based reproduction script above reports Total: 0 violations.
All existing tests continue to pass.
Static type checker (pyright/mypy) passes with no new errors introduced by these changes.

Subtasks

Add return type annotation to __getattr__ in src/cleveragents/agents/__init__.py
Add return type annotation to _build_stream_router in src/cleveragents/application/container.py
Add return type annotation and stream_router parameter annotation to _build_langgraph_bridge in src/cleveragents/application/container.py
Add return type annotation and stream_router/agents parameter annotations to _build_route_bridge in src/cleveragents/application/container.py
Add return type annotation and stream_router/route_bridge/actor_registry parameter annotations to _lazy_register_registry_agents in src/cleveragents/application/container.py
Add return type annotation to __getattr__ in src/cleveragents/application/services/__init__.py
Add return type annotation to _get_services in src/cleveragents/cli/commands/actor.py
Add return type annotation to _get_lifecycle_service in src/cleveragents/cli/commands/plan.py
Add return type annotation to _get_apply_service in src/cleveragents/cli/commands/plan.py
Add return type annotation to __getattr__ in src/cleveragents/langgraph/__init__.py
Verify the AST reproduction script reports Total: 0 violations
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
All 16 annotation violations are resolved with correct, meaningful type annotations.
The AST-based reproduction script reports Total: 0 violations.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(typing): add missing return type and parameter annotations to 16 functions), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/add-missing-type-annotations).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/add-missing-type-annotations` - **Commit Message**: `fix(typing): add missing return type and parameter annotations to 16 functions` - **Milestone**: v3.5.0 - **Parent Epic**: #397 ## Background and Context Static analysis of the source code reveals 16 functions that are missing return type annotations or parameter type annotations. The project specification and CONTRIBUTING.md require that "Every function signature, variable declaration, and return type must have explicit type annotations." This was discovered during UAT testing via AST-based analysis of all Python source files in `src/cleveragents/`. ## Expected Behavior Per the project specification and CONTRIBUTING.md: > "All code must be statically typed. Every function signature, variable declaration, and return type must have explicit type annotations." All functions must have explicit return type annotations and all parameters (except `self`/`cls`) must have type annotations. ## Actual Behavior 16 annotation violations found across 6 files: ``` src/cleveragents/agents/__init__.py:56: function "__getattr__" missing return annotation src/cleveragents/application/container.py:121: function "_build_stream_router" missing return annotation src/cleveragents/application/container.py:128: function "_build_langgraph_bridge" missing return annotation src/cleveragents/application/container.py:128: function "_build_langgraph_bridge" arg "stream_router" missing annotation src/cleveragents/application/container.py:135: function "_build_route_bridge" missing return annotation src/cleveragents/application/container.py:135: function "_build_route_bridge" arg "stream_router" missing annotation src/cleveragents/application/container.py:135: function "_build_route_bridge" arg "agents" missing annotation src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" missing return annotation src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "stream_router" missing annotation src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "route_bridge" missing annotation src/cleveragents/application/container.py:142: function "_lazy_register_registry_agents" arg "actor_registry" missing annotation src/cleveragents/application/services/__init__.py:565: function "__getattr__" missing return annotation src/cleveragents/cli/commands/actor.py:203: function "_get_services" missing return annotation src/cleveragents/cli/commands/plan.py:1056: function "_get_lifecycle_service" missing return annotation src/cleveragents/cli/commands/plan.py:2575: function "_get_apply_service" missing return annotation src/cleveragents/langgraph/__init__.py:13: function "__getattr__" missing return annotation ``` **Breakdown by file:** - `src/cleveragents/application/container.py`: 8 violations (4 functions missing return types, 4 parameters missing annotations) - `src/cleveragents/agents/__init__.py`: 1 violation (`__getattr__` missing return type) - `src/cleveragents/application/services/__init__.py`: 1 violation (`__getattr__` missing return type) - `src/cleveragents/cli/commands/actor.py`: 1 violation (`_get_services` missing return type) - `src/cleveragents/cli/commands/plan.py`: 2 violations (`_get_lifecycle_service` and `_get_apply_service` missing return types) - `src/cleveragents/langgraph/__init__.py`: 1 violation (`__getattr__` missing return type) ## Steps to Reproduce ```bash python3 -c " import ast, os issues = [] for root, dirs, files in os.walk('src/cleveragents'): for fname in files: if fname.endswith('.py'): path = os.path.join(root, fname) with open(path) as f: tree = ast.parse(f.read()) for node in ast.walk(tree): if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): if node.returns is None and node.name != '__init__': issues.append(f'{path}:{node.lineno}: function \"{node.name}\" missing return annotation') for arg in node.args.args + node.args.posonlyargs + node.args.kwonlyargs: if arg.annotation is None and arg.arg not in ('self', 'cls'): issues.append(f'{path}:{node.lineno}: function \"{node.name}\" arg \"{arg.arg}\" missing annotation') print(f'Total: {len(issues)}') for i in issues: print(i) " ``` ## Acceptance Criteria - All 16 annotation violations listed above are resolved with correct, meaningful type annotations. - No new annotation violations are introduced. - The AST-based reproduction script above reports `Total: 0` violations. - All existing tests continue to pass. - Static type checker (`pyright`/`mypy`) passes with no new errors introduced by these changes. ## Subtasks - [ ] Add return type annotation to `__getattr__` in `src/cleveragents/agents/__init__.py` - [ ] Add return type annotation to `_build_stream_router` in `src/cleveragents/application/container.py` - [ ] Add return type annotation and `stream_router` parameter annotation to `_build_langgraph_bridge` in `src/cleveragents/application/container.py` - [ ] Add return type annotation and `stream_router`/`agents` parameter annotations to `_build_route_bridge` in `src/cleveragents/application/container.py` - [ ] Add return type annotation and `stream_router`/`route_bridge`/`actor_registry` parameter annotations to `_lazy_register_registry_agents` in `src/cleveragents/application/container.py` - [ ] Add return type annotation to `__getattr__` in `src/cleveragents/application/services/__init__.py` - [ ] Add return type annotation to `_get_services` in `src/cleveragents/cli/commands/actor.py` - [ ] Add return type annotation to `_get_lifecycle_service` in `src/cleveragents/cli/commands/plan.py` - [ ] Add return type annotation to `_get_apply_service` in `src/cleveragents/cli/commands/plan.py` - [ ] Add return type annotation to `__getattr__` in `src/cleveragents/langgraph/__init__.py` - [ ] Verify the AST reproduction script reports `Total: 0` violations - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - All 16 annotation violations are resolved with correct, meaningful type annotations. - The AST-based reproduction script reports `Total: 0` violations. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(typing): add missing return type and parameter annotations to 16 functions`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/add-missing-type-annotations`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.5.0 milestone

2026-04-02 23:29:51 +00:00

freemo added the

labels

2026-04-02 23:30:31 +00:00

freemo added a new dependency

2026-04-02 23:34:11 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-02 23:37:56 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 441 — v3.7.0 #1734

freemo referenced this issue

2026-04-02 23:40:27 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463

freemo commented

2026-04-02 23:47:55 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels based on issue content
Reason: Per CONTRIBUTING.md, every issue must have exactly one State/*, Type/*, and Priority/* label.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Added missing labels based on issue content - Reason: Per CONTRIBUTING.md, every issue must have exactly one `State/*`, `Type/*`, and `Priority/*` label. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo commented

2026-04-02 23:51:13 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or spec compliance issue.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo removed the

labels

2026-04-02 23:52:10 +00:00

freemo referenced this issue

2026-04-02 23:55:03 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463