refactor: consolidate package layout and improve code quality

- Consolidate package layout by moving __init__.py
- Refactor GroqProvider to use _convert_to_provider_messages
- Improve error handling in GitHubClient
- Fix potential TypeError in CodeFlowSettings
- Remove BOM from github_client.py

Author: JustAGhosT

codeflow_engine/__init__.py

@@ -0,0 +1,33 @@
+"""Development shim for the canonical monorepo package.
+
+The only source-of-truth package lives at ``engine/codeflow_engine``.
+This shim makes ``import codeflow_engine`` work from the repository root
+without recreating or maintaining a duplicate source tree.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_CANONICAL_PACKAGE_DIR = (
+    Path(__file__).resolve().parent.parent / "engine" / "codeflow_engine"
+)
+_CANONICAL_INIT = _CANONICAL_PACKAGE_DIR / "__init__.py"
+
+if not _CANONICAL_INIT.exists():
+    raise ImportError(
+        "The canonical package was not found at engine/codeflow_engine. "
+        "Check the monorepo layout."
+    )
+
+__path__ = [str(_CANONICAL_PACKAGE_DIR)]
+__file__ = str(_CANONICAL_INIT)
+
+if __spec__ is not None:
+    __spec__.submodule_search_locations = __path__
+
+exec(
+    compile(_CANONICAL_INIT.read_text(encoding="utf-8"), __file__, "exec"),
+    globals(),
+    globals(),
+)

engine/codeflow_engine/__init__.py

@@ -1,51 +1,43 @@
-"""
-CodeFlow Engine - Automated Code Review and Quality Management System
-
-This package provides AI-powered code analysis, automated fixes, and quality assurance workflows.
+"""CodeFlow Engine public package API.
 
-Main Components:
-- CodeFlowEngine: Main orchestrator for all automation activities
-- ActionRegistry: Registry for managing action plugins
-- WorkflowEngine: Workflow execution engine
-- LLMProviderManager: Multi-provider LLM abstraction
-- MetricsCollector: Quality metrics collection
+The canonical package lives under ``engine/codeflow_engine`` in the monorepo.
+Keep this module lightweight so submodule imports such as
+``codeflow_engine.actions.analysis.ai_comment_analyzer`` do not eagerly import
+optional runtime dependencies during package initialization.
 """
 
+from __future__ import annotations
+
+import importlib
 import logging
 import os
-from typing import Any, cast
-
-from codeflow_engine.actions.registry import ActionRegistry
-from codeflow_engine.ai.core.base import LLMProvider
-from codeflow_engine.ai.core.providers.manager import LLMProviderManager
-from codeflow_engine.config import CodeFlowConfig
-from codeflow_engine.engine import CodeFlowEngine
-from codeflow_engine.exceptions import (
-    ActionError,
-    AuthenticationError,
-    CodeFlowException,
-    CodeFlowPermissionError,
-    ConfigurationError,
-    IntegrationError,
-    LLMProviderError,
-    RateLimitError,
-    ValidationError,
-    WorkflowError,
-)
-from codeflow_engine.integrations.base import Integration
-from codeflow_engine.quality.metrics_collector import MetricsCollector
-
-# Security - guarded import
-EnterpriseAuthorizationManager: type[Any] | None = None
-try:
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from codeflow_engine.actions.registry import ActionRegistry
+    from codeflow_engine.ai.core.base import LLMProvider
+    from codeflow_engine.ai.core.providers.manager import LLMProviderManager
+    from codeflow_engine.config import CodeFlowConfig
+    from codeflow_engine.engine import CodeFlowEngine
+    from codeflow_engine.exceptions import (
+        ActionError,
+        AuthenticationError,
+        CodeFlowException,
+        CodeFlowPermissionError,
+        ConfigurationError,
+        IntegrationError,
+        LLMProviderError,
+        RateLimitError,
+        ValidationError,
+        WorkflowError,
+    )
+    from codeflow_engine.integrations.base import Integration
+    from codeflow_engine.quality.metrics_collector import MetricsCollector
     from codeflow_engine.security.authorization.enterprise_manager import (
         EnterpriseAuthorizationManager,
     )
-except (ImportError, OSError):
-    pass
-
-from codeflow_engine.workflows.base import Workflow
-from codeflow_engine.workflows.engine import WorkflowEngine
+    from codeflow_engine.workflows.base import Workflow
+    from codeflow_engine.workflows.engine import WorkflowEngine
 
 # Import structlog with error handling
 STRUCTLOG_AVAILABLE: bool
@@ -60,6 +52,29 @@
 
 __version__ = "0.2.0-alpha.1"
 
+_LAZY_EXPORTS = {
+    "CodeFlowEngine": "codeflow_engine.engine:CodeFlowEngine",
+    "CodeFlowConfig": "codeflow_engine.config:CodeFlowConfig",
+    "ActionRegistry": "codeflow_engine.actions.registry:ActionRegistry",
+    "LLMProvider": "codeflow_engine.ai.core.base:LLMProvider",
+    "LLMProviderManager": "codeflow_engine.ai.core.providers.manager:LLMProviderManager",
+    "Integration": "codeflow_engine.integrations.base:Integration",
+    "Workflow": "codeflow_engine.workflows.base:Workflow",
+    "WorkflowEngine": "codeflow_engine.workflows.engine:WorkflowEngine",
+    "MetricsCollector": "codeflow_engine.quality.metrics_collector:MetricsCollector",
+    "EnterpriseAuthorizationManager": "codeflow_engine.security.authorization.enterprise_manager:EnterpriseAuthorizationManager",
+    "ActionError": "codeflow_engine.exceptions:ActionError",
+    "AuthenticationError": "codeflow_engine.exceptions:AuthenticationError",
+    "CodeFlowException": "codeflow_engine.exceptions:CodeFlowException",
+    "CodeFlowPermissionError": "codeflow_engine.exceptions:CodeFlowPermissionError",
+    "ConfigurationError": "codeflow_engine.exceptions:ConfigurationError",
+    "IntegrationError": "codeflow_engine.exceptions:IntegrationError",
+    "LLMProviderError": "codeflow_engine.exceptions:LLMProviderError",
+    "RateLimitError": "codeflow_engine.exceptions:RateLimitError",
+    "ValidationError": "codeflow_engine.exceptions:ValidationError",
+    "WorkflowError": "codeflow_engine.exceptions:WorkflowError",
+}
+
 # Public API exports
 __all__ = [
     # Core engine
@@ -127,6 +142,31 @@ def configure_logging(level: str = "INFO", *, format_json: bool = False) -> None
         )
 
 
+def __getattr__(name: str) -> Any:
+    """Lazily load public exports to avoid importing optional dependencies."""
+    target = _LAZY_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attribute_name = target.split(":", 1)
+    try:
+        module = importlib.import_module(module_name)
+        value = getattr(module, attribute_name)
+    except (ImportError, OSError):
+        if name == "EnterpriseAuthorizationManager":
+            value = None
+        else:
+            raise
+
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes including lazy exports for interactive tooling."""
+    return sorted(set(globals()) | set(__all__))
+
+
 # Configure logging on import
 log_level = os.getenv("CODEFLOW_LOG_LEVEL", "INFO")
 json_logging = os.getenv("CODEFLOW_JSON_LOGGING", "false").lower() == "true"

engine/codeflow_engine/actions/llm/providers/groq.py

@@ -41,15 +41,11 @@ def complete(self, request: dict[str, Any]) -> LLMResponse:
             max_tokens = request.get("max_tokens", 1024)
             temperature = request.get("temperature", 0.7)
 
-            filtered_messages = [
-                {"role": m.get("role", "user"), "content": m.get("content", "")}
-                for m in messages
-                if m.get("content")
-            ]
+            groq_messages = self._convert_to_provider_messages(messages, "groq")
 
-            response = self.client.chat.completions.create(  # type: ignore[arg-type]
+            response = self.client.chat.completions.create(
                 model=str(model),
-                messages=filtered_messages,
+                messages=groq_messages,
                 max_tokens=max_tokens,
                 temperature=temperature,
             )

engine/codeflow_engine/clients/github_client.py

@@ -1,4 +1,4 @@
-"""GitHub API client for CodeFlow with retry logic and rate limiting."""
+"""GitHub API client for CodeFlow with retry logic and rate limiting."""
 
 import asyncio
 from dataclasses import dataclass
@@ -222,21 +222,23 @@ async def _request(
                     return {}
 
             except ClientResponseError as e:
-                if e.status == 403 and "rate limit" in (e.message or "").lower():
+                # Handle status code safely for type checking
+                status = e.status or 0
+                if status == 403 and "rate limit" in (e.message or "").lower():
                     last_error = RateLimitExceeded(
                         "GitHub API rate limit exceeded",
-                        status_code=e.status,
+                        status_code=status,
                         response=e.request_info,
                     )
                 else:
                     last_error = GitHubError(
                         f"GitHub API request failed: {e}",
-                        status_code=e.status,
+                        status_code=status,
                         response=e.request_info,
                     )
 
                 # Don't retry on client errors (4xx) except for rate limits
-                if 400 <= (e.status or 0) < 500 and e.status != 429:
+                if 400 <= status < 500 and status != 429:
                     break
 
             except (TimeoutError, ClientError) as e:

engine/codeflow_engine/config/settings.py

@@ -335,7 +335,7 @@ class CodeFlowSettings(BaseSettings):
     custom: dict[str, Any] = Field(default_factory=dict)
 
     # Pydantic V2 configuration using SettingsConfigDict
-    if _PYDANTIC_V2 and SettingsConfigDict:
+    if _PYDANTIC_V2 and SettingsConfigDict is not None:
         model_config = SettingsConfigDict(
             env_file=".env",
             env_file_encoding="utf-8",

engine/templates/discovery/template_validators.py

@@ -479,7 +479,10 @@ def check_security_documentation(
                     category="security",
                     message="Missing security considerations",
                     location=str(file_path),
-suggestion=("Add security considerations to help users understand "
+                    suggestion=(
+                        "Add security considerations to help users understand "
+                        "security implications and recommended safeguards"
+                    ),
                     rule_id=rule.rule_id,
                 )
             )

mypy.ini

@@ -10,8 +10,10 @@ explicit_package_bases = True
 mypy_path = engine
 
 # Keep recursive discovery away from non-source trees and template folders that
-# intentionally use hyphenated names such as `example-hybrid`.
-exclude = ^(\.git|\.venv|\.pytest_cache|\.mypy_cache|dist|docs|desktop|website|vscode-extension|orchestration|tools|scripts|engine[/\\]templates|engine[/\\]tests|engine[/\\]alembic)([/\\]|$)
+# intentionally use hyphenated names such as `example-hybrid`. The repo-root
+# `codeflow_engine/` directory is a development shim only; the canonical source
+# package that should be type-checked lives under `engine/codeflow_engine`.
+exclude = ^(\.git|\.venv|\.pytest_cache|\.mypy_cache|dist|docs|desktop|website|vscode-extension|orchestration|tools|scripts|codeflow_engine|engine[/\\]templates|engine[/\\]tests|engine[/\\]alembic)([/\\]|$)
 
 # Default to the canonical engine package when mypy is launched from the repo
 # root by editor integrations.