System design flaw study

docs/design_flaw_and_factory_pattern.md

@@ -0,0 +1,82 @@
+# Design Flaw: Inconsistent Object Creation and the Factory Pattern Solution
+
+This document outlines a significant design flaw in our codebase related to object creation and proposes a solution using the **Factory Method** design pattern.
+
+## The Design Flaw: Scattered and Inconsistent Creation Logic
+
+Currently, the instantiation of complex objects, particularly different types of "Environments" (e.g., `SingleAlfredTWEnv`, `ReformatWordleEnvironment`, `ScienceWorldEnv`), is handled by multiple, disparate `create` methods.
+
+This approach has several critical disadvantages:
+
+*   **Violates the Open/Closed Principle:** Whenever a new environment type is introduced, we must modify existing client code or a central creator class. This means our system is not "closed for modification" but requires constant changes for extension.
+*   **Reduced Cohesion and Increased Coupling:** The logic for creating objects is scattered across the codebase. The client code that needs to create an object is tightly coupled to the concrete classes it needs to instantiate, as it must know which specific class or creation function to call. This makes the code harder to read, maintain, and test.
+*   **Inconsistency:** The presence of different `create` methods, including one that uses dynamic `__import__`, leads to an inconsistent and unpredictable API for object creation.
+
+## The Solution: The Factory Method Pattern
+
+To address these issues, we should adopt the **Factory Method** design pattern. This pattern defines a common interface for creating objects but lets subclasses decide which specific class to instantiate.
+
+### How It Works
+
+1.  **Define a `Creator` Base Class:** We will create an abstract base class with a "factory method" for producing objects.
+
+    ```python
+    from abc import ABC, abstractmethod
+
+    class EnvironmentCreator(ABC):
+        """
+        Declares the factory method that returns an object of an Environment class.
+        """
+        @abstractmethod
+        def create_environment(self):
+            pass
+
+    # (Your environment base class would be defined elsewhere)
+    class Environment(ABC):
+        pass
+    ```
+
+2.  **Create Concrete `Creator` Subclasses:** For each type of environment, we will create a concrete subclass that implements the factory method. All the complex setup logic for a specific environment is encapsulated within its creator.
+
+    ```python
+    class ScienceWorldCreator(EnvironmentCreator):
+        """
+        Overrides the factory method to return an instance of a ScienceWorldEnv.
+        """
+        def create_environment(self) -> Environment:
+            return ScienceWorldEnv()
+
+    class WordleCreator(EnvironmentCreator):
+        """
+        Overrides the factory method to return an instance of a WordleEnv.
+        """
+        def create_environment(self) -> Environment:
+            # Encapsulate complex setup logic here
+            vocab = Vocabulary.from_file("...")
+            return ReformatWordleEnvironment(WordleEnvironment(vocab))
+    ```
+
+3.  **Use the Factory in Client Code:** The client code will now work with the `EnvironmentCreator` interface, completely decoupled from the concrete environment classes.
+
+    ```python
+    def client_code(creator: EnvironmentCreator):
+        """
+        The client code works with any creator's subclass through the base interface.
+        """
+        env = creator.create_environment()
+        # ... do something with the environment
+        print(f"Created a {type(env).__name__}")
+
+
+    # Example usage
+    client_code(ScienceWorldCreator())
+    client_code(WordleCreator())
+    ```
+
+### Benefits of This Approach
+
+*   **Adherence to SOLID Principles:** This change aligns our code with the Open/Closed and Dependency Inversion principles.
+*   **Improved Maintainability:** New environments can be added without changing existing code. We simply add a new `Environment` subclass and a corresponding `Creator` subclass.
+*   **Increased Flexibility and Decoupling:** The client code is no longer responsible for knowing how to create objects. This makes our system more modular and easier to refactor or test.
+
+By implementing the Factory Method pattern, we will establish a clean, scalable, and maintainable architecture for object creation in our platform.