co2114 2026.1.0__tar.gz → 2026.1.1__tar.gz

{co2114-2026.1.0 → co2114-2026.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2114
-Version: 2026.1.0
+Version: 2026.1.1
 Summary: codebase for co2114
 Author: wil ward
 Requires-Python: >=3.12

{co2114-2026.1.0 → co2114-2026.1.1}/co2114/constraints/csp/__init__.py

@@ -31,6 +31,10 @@ class ConstraintSatisfactionProblem:
 
     @property
     def variables(self):
+        """ List of variables in the CSP. 
+        
+        :return: List of variables.
+        """
         return self.__variables
     
     @property

{co2114-2026.1.0 → co2114-2026.1.1}/co2114/search/graph.py

@@ -207,7 +207,11 @@ class GraphEnvironment(Environment):
 
     @override
     def percept(self, agent:Agent) -> list[tuple[Node, Numeric]]:
-        """ Return the percepts for the agent based on its location in the graph."""
+        """ Return the percepts for the agent based on its location in the graph.
+        
+        :param agent: Agent for which to get percepts.
+        :return: List of tuples (neighbouring node, edge weight). Weight is 1 if unweighted
+        """
         node:Node = agent.location  # type: ignore
         if len(node.weights) == 0:
             return [(n, 1) for n in node.neighbours]
@@ -254,7 +258,7 @@ class GraphEnvironment(Environment):
                 super().add_agent(agent)
 
 
-    def show(self, *args, **kwargs):
+    def show(self, *args, **kwargs) -> Figure:
         """ Show a plot of the graph environment. """
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")

{co2114-2026.1.0 → co2114-2026.1.1}/co2114/search/maze.py

@@ -2,6 +2,8 @@ from collections.abc import Iterable
 import warnings
 from matplotlib import pyplot as plt
 from collections import deque
+from typing import override
+from matplotlib.figure import Figure  # for type hinting
 
 with warnings.catch_warnings():
     warnings.simplefilter("ignore")
@@ -34,6 +36,22 @@ PRESET_MAZES = {
         "x   x xx xx ",
         "xxx x  xxxx ",
         "    xx      "],
+    3: ["xxx                 xxxxxxxxx",
+        "x   xxxxxxxxxxxxxxxxxxx   x x",
+        "x xxxx                x x x x",
+        "x xxxxxxxxxxxxxxxxxxx x x x x",
+        "x                     x x x x",
+        "xxxxxxxxxxxxxxxxxxxxx x x x x",
+        "x   xx                x x x x",
+        "x x xx xxx xx xxxxxxxxx x x x",
+        "x x    x   xxox         x x x",
+        "x x xx xxxxxxxxxxxxxxxx x x x",
+        "xxx xx             xxxx x x x",
+        "xxx xxxxxxxxxxxxxx xx x x x x",
+        "xxx             xx    x x x x",
+        "xxxxxx xxxxxxxx xxxxxxx x x x",
+        "xxxxxx xxxx             x   x",
+        "       xxxxxxxxxxxxxxxxxxxxxx"],
     4: ["xxx                 xxxxxxxxx",
         "x   xxxxxxxxxxxxxxxxxxx   x x",
         "x xxxx                x x x x",
@@ -56,27 +74,39 @@ PRESET_STARTS = {
     0: (3, 0),
     1: (3, 0),
     2: (7, 0),
+    3: (1, 27),
     4: (15, 0)
 }
 
+
 class MazeTile(Node):
-    def __init__(self, passable:bool):
+    def __init__(self, passable:bool) -> None:
+        """ MazeTile - A tile in a maze, either passable or not.
+        
+        :param passable: Whether the tile is passable.
+        """
         super().__init__()
-        self.is_passable = passable
-        self.is_goal = False
-        self.visited = False
+        self.is_passable:bool = passable
+        self.is_goal:bool = False
+        self.visited:bool = False
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        """ Str representation of the MazeTile. """
         repr =  "⬜" if self.is_passable else "⬛"
         if hasattr(self, "location"):
             repr += str(self.location)
         return repr
 
 
+
 class Maze(Graph):
-    def __init__(self, template=None, size=None):
+    def __init__(self, template:list[str]|None=None) -> None:
+        """ Maze class: a grid-based maze structure.
+        
+        :param template: Optional template to generate the maze from.
+        """
         super().__init__()
-        if template is not None:
+        if template is not None:  # generate from template
             if not self._is_valid_template(template):
                 raise ValueError(f"{self}: template provided is not valid")
             self.template = template
@@ -84,11 +114,21 @@ class Maze(Graph):
             self.size = self.width, self.height
             self._generate_from_template()
 
-    def __repr__(self):
+    @override
+    def __repr__(self) -> str:
+        """ String representation of the Maze. """
         return "ꡙ‍"
 
-    def _is_valid_template(self, template):
+    def _is_valid_template(self, template:list[str]) -> bool:
+        """ Checks if the provided template is valid.
+        
+        A valid template is a list of strings, all of the same length, containing only " ", "o", or "x".
+
+        :param template: The template to validate.
+        :return valid: Whether the template is valid.
+        """
         def valid(row, size):
+            """ Internal row validator. """
             return False if len(row) != size else not any(
                 c not in (' ','o','x') for c in row)
 
@@ -98,7 +138,11 @@ class Maze(Graph):
                 return all(valid(row,width) for row in template)
         return False
 
-    def _generate_from_template(self):
+    def _generate_from_template(self) -> None:
+        """ Generates the maze from the provided template. 
+        
+        Uses internal self.template to build the maze grid.
+        """
         self.grid = []
         w,h = self.width, self.height
         print(f"{self}: generating {w}x{h} maze from template")
@@ -117,70 +161,127 @@ class Maze(Graph):
             self.grid.append(grid_row)
         self.add_node(self.grid[0][0])  # cascade adding nodes
 
-
-    def plot_nodes(self, init=None):
+    @override
+    def plot_nodes(self) -> Figure:
+        """ Plots the maze nodes using matplotlib."""
         labels = {self.grid[i][j]: f"({i},{j})" 
                     for i in range(self.width)
                         for j in range(self.height)}
         condition = lambda node: node.is_passable
-        return super().plot_nodes(init=init, labels=labels, condition=condition)
+        return super().plot_nodes(init=None, labels=labels, condition=condition)
+
 
 
 class MazeEnvironment(GraphEnvironment):
-    def __init__(self, maze, *args, **kwargs):
+    """ MazeEnvironment - An environment for maze navigation. 
+    
+    A type of GraphEnvironment specifically for Maze graphs.
+    """
+    def __init__(self, maze:Maze, *args, **kwargs) -> None:
+        """ Initialises the MazeEnvironment.
+        
+        :param maze: The Maze to be used as the environment.
+        :param args: Additional positional arguments for GraphEnvironment.
+        :param kwargs: Additional keyword arguments for GraphEnvironment.
+        """
         if not isinstance(maze, Maze):
             raise TypeError(f"{self}: maze must be valid Maze")
         super().__init__(maze, *args, **kwargs)
         self.size = self.width, self.height = maze.size
         self.success = False  # maze is solved
-    def __repr__(self):
+
+    @override
+    def __repr__(self) -> str:
+        """ String representation of the MazeEnvironment. """
         return self.maze.__repr__()
 
     @property
-    def maze(self):
+    def maze(self) -> Maze:
+        """ Returns the maze graph of the environment. """
         return self.graph
 
     @property
-    def grid(self):
+    def grid(self) -> list[list[MazeTile]]:
+        """ Returns the maze grid as a nested list of MazeTiles. """
         return self.maze.grid
 
     @property
-    def is_done(self):
+    def is_done(self) -> bool:
+        """ Returns whether the maze has been solved. """
         if len(self.agents) == 0: return True
         return self.success
 
     @property
-    def goal(self):
+    def goal(self) -> MazeTile|None:
+        """ Returns the goal tile of the maze, if there is one. 
+        """
         goal = {node for node in self.maze.nodes if node.is_goal}
         if len(goal) == 1:
             goal = next(iter(goal))
+        else:
+            goal = None
         return goal
 
-    def show_graph(self, *args, **kwargs):
+
+    def show_graph(self, *args, **kwargs) -> Figure: 
+        """ Wrapper for GraphEnvironment.show() """
         return self.show(*args, **kwargs)
 
-    def percept(self, agent):
+
+    @override
+    def percept(self, agent:Agent) -> set[MazeTile]:
+        """ Returns the percepts for the agent: neighbouring nodes and their weights.
+        
+        :param agent: The agent to get percepts for.
+        :return percepts: List of tuples of (neighbouring maze tile, weight).
+        """
         node = agent.location
         return node.neighbours
 
-    def execute_action(self, agent, action):
-        """ """
-        command, node = action
+    @override
+    def execute_action(self, agent:Agent, action:tuple[str, MazeTile]) -> None:
+        """ Executes the agent's action in the environment.
+        
+        :param agent: The agent performing the action.
+        :param action: The action to be performed, as a tuple of (command, MazeTile). Command should be "move".
+        """
+        command, node = action  # e.g. ("move", node)
         if command == "move":
             if node in self.maze:
                 self.success = agent.move_to(node)
     
-    def run(self, track_agent=False, *args, **kwargs):
+    @override
+    def run(self, *args, **kwargs) -> None:
+        """ Run the environment for a large number of steps by default. 
+        
+        Non-graphical default.
+        """
         super().run(10000, *args, **kwargs)
 
     @classmethod
-    def from_template(MazeEnvironment, template):
+    def from_template(MazeEnvironment, template:list[str]) -> "MazeEnvironment":
+        """ Creates a MazeEnvironment from a template.
+        
+        Returns instance of MazeEnvironment built from the provided template.
+        :param template: The template to build the maze from.
+        :return environment: The MazeEnvironment instance.
+        """
         maze = Maze(template)
         return MazeEnvironment(maze)
 
 
 class GraphicMaze(MazeEnvironment):
-    def run(self, graphical=True, lps=2, *args, **kwargs):
+    """ Graphical Maze Environment: A MazeEnvironment with graphical rendering capabilities. Uses MazeApp to render.
+    """
+    @override
+    def run(self, graphical=True, lps=2, *args, **kwargs) -> None:
+        """ Run the MazeEnvironment in graphical or non-graphical mode.
+        
+        :param graphical: Whether to run in graphical mode.
+        :param lps: The number of logic updates per second in graphical mode.
+        :param args: Additional positional arguments for Engine.
+        :param kwargs: Additional keyword arguments for Engine.
+        """
         if graphical:
             MazeApp(self, *args, name=f"{self}", lps=lps, **kwargs).run()
         else:
@@ -189,8 +290,18 @@ class GraphicMaze(MazeEnvironment):
   
 class MazeApp(App):
     """ MazeApp
-            Graphical version of Maze """
-    def __init__(self, environment:MazeEnvironment=None, track_agent=False,**kwargs):
+            Graphical version of Maze
+    """
+    def __init__(self,
+                 environment:MazeEnvironment|None = None,
+                 track_agent = False,
+                 **kwargs) -> None:
+        """ Construct MazeApp
+        
+        :param environment: The MazeEnvironment to be rendered. If None, a default maze is created.
+        :param track_agent: Whether to visually track the agent's path, default False
+        :param kwargs: Additional keyword arguments for App.
+        """
         if environment is None:
             print(f"{self}: building new MazeEnvironment from template")
             environment = MazeEnvironment.from_template(PRESET_MAZES[0])
@@ -208,7 +319,8 @@ class MazeApp(App):
         self._flag = True
         self.track = track_agent
 
-    def _fit_to_environment(self):
+    
+    def _fit_to_environment(self) -> None:
         """ Fit width and height ratios to match environment """
         _flag = self.environment.width > self.environment.height
         if _flag:
@@ -225,8 +337,9 @@ class MazeApp(App):
         self.height, self.width = (a,b) if _flag else (b,a)
         self.size = self.width, self.height
 
-
-    def update(self):
+    @override
+    def update(self) -> None:
+        """ Update MazeApp by iterating underlying simulation environment """
         if self.counter < 0:
             self.counter += 1
             return
@@ -237,12 +350,15 @@ class MazeApp(App):
             print(f"{self.environment}: Maze complete after {self.counter} iterations.")
             self._flag = False
 
-    def render(self):
+    @override
+    def render(self) -> None:
+        """ Render frame of MazeApp """
         # self.screen.fill(self.environment.color)
         self.render_grid()
         self.render_things()
 
-    def render_grid(self):
+    def render_grid(self) -> None:
+        """ Render maze grid showing passable and non-passable tiles in light and dark red respectively. If the agent is tracked, visited tiles are shown in light green. """
         nx,ny = self.environment.width, self.environment.height
         self.tile_size = self.width / nx
         tile_origin = (0,0)
@@ -274,7 +390,16 @@ class MazeApp(App):
             tiles.append(row)
         self.tiles = tiles
             
-    def label_tile(self, node, string, color=COLOR_WHITE):
+    def label_tile(self,
+                   node:MazeTile,
+                   string:str,
+                   color:tuple[int,int,int] = COLOR_WHITE) -> None:
+        """ Labels a tile with a string at the center of the tile.
+        
+        :param node: The MazeTile to label.
+        :param string: The string to label the tile with.
+        :param color: The color of the string.
+        """
         i,j = node.location
         renderLoc = self.tiles[i][j].center
         thingRender = self.thing_font.render(string, True, color)
@@ -282,7 +407,11 @@ class MazeApp(App):
         thingRect.center = renderLoc
         self.screen.blit(thingRender, thingRect)
     
-    def render_things(self):
+    def render_things(self) -> None:
+        """ Renders things to the maze environment. 
+        
+        Marks the goal tile with a crown emoji, agents with their string representation, and if tracking is enabled, marks frontier nodes with a question mark.
+        """
         locations = {}
         for node in self.environment.maze:
             if node.is_goal:
@@ -295,5 +424,4 @@ class MazeApp(App):
             if self.track:
                 if hasattr(agent, "frontier"):
                     for node in agent.frontier:
-                        self.label_tile(node, "?", COLOR_WHITE)
-                
+                        self.label_tile(node, "?", COLOR_WHITE)

{co2114-2026.1.0 → co2114-2026.1.1}/co2114/search/things.py

@@ -14,7 +14,7 @@ class MazeRunner(Agent):
 class GoalBasedAgent(ModelBasedAgent):
     """ Base class for goal based agents 
     
-        Requires implemnentation of methods:
+        Requires implementation of methods:
             `program(percepts:Collection[Thing]) -> Action`
             `at_goal() -> bool`
     """
@@ -27,7 +27,7 @@ class GoalBasedAgent(ModelBasedAgent):
 class UtilityBasedAgent(GoalBasedAgent):
     """ Base class for utility based agents 
     
-        Requires implemnentation of methods:
+        Requires implementation of methods:
             `program(percepts:Collection[Thing]) -> Action`
             `at_goal() -> bool`
             `utility(action:Action) -> float`

co2114-2026.1.1/co2114/search/util.py

@@ -0,0 +1,49 @@
+from collections import deque
+from typing import override, Iterator, TypeVar
+
+GenericType = TypeVar('GenericType')
+Numeric = int | float
+
+class queue[GenericType]:
+    """ Wrapper for deque to provide FIFO queue functionality """
+    def __init__(self) -> None:
+        self.data:deque[GenericType] = deque()  # internal deque storage
+
+    @override
+    def __repr__(self) -> str:
+        """ string representation of queue as sequence of elements """
+        return str(list(self.data))
+    
+
+    def __iter__(self) -> Iterator[GenericType]:
+        """ Iterator over queue elements, allows in checks and looping """
+        return iter(self.data)
+
+
+    def push(self, x:GenericType) -> None:
+        """ Appends an item to the end of the queue 
+        
+        :param x: item to append
+        """
+        self.data.append(x)
+
+
+    def pop(self) -> GenericType:
+        """ Pops first element """
+        return self.data.popleft()
+
+
+
+class stack[GenericType](queue):
+    """ Wrapper for deque to provide LIFO stack functionality """
+    @override
+    def pop(self) -> GenericType:
+        """ Pops last element """
+        return self.data.pop()
+    
+
+def manhattan(a: tuple[Numeric, Numeric], b:tuple[Numeric, Numeric]) -> Numeric:
+    """ Basic Manhattan distance calculation between two (x,y) points """
+    ax, ay = a  # (x, y)
+    bx, by = b  # (x, y)
+    return abs(bx-ax) + abs(by-ay)

{co2114-2026.1.0 → co2114-2026.1.1}/co2114.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2114
-Version: 2026.1.0
+Version: 2026.1.1
 Summary: codebase for co2114
 Author: wil ward
 Requires-Python: >=3.12

{co2114-2026.1.0 → co2114-2026.1.1}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup
 
 setup(
     name="co2114",
-    version="2026.1.0",
+    version="2026.1.1",
     description="codebase for co2114",
     author="wil ward",
     python_requires=">=3.12",

co2114-2026.1.0/co2114/search/util.py

@@ -1,27 +0,0 @@
-from collections import deque
-
-class queue:
-    def __init__(self):
-        self.data = deque()
-
-    def __repr__(self):
-        return str(list(self.data))
-    
-    def __iter__(self):
-        return iter(self.data)
-
-    def push(self, x):
-        self.data.append(x)
-
-    def pop(self):
-        return self.data.popleft()
-
-class stack(queue):
-    def pop(self):
-        return self.data.pop()
-    
-
-def manhattan(a, b):
-    ax, ay = a  # (x, y)
-    bx, by = b  # (x, y)
-    return abs(bx-ax) + abs(by-ay)