blindpath 0.1.0__py3-none-any.whl

blindpath/Constants/__init__.py

@@ -0,0 +1,37 @@
+from blindpath.Constants.tiles import (
+    AGENT,
+    EMPTY,
+    OBSTACLE,
+    GOAL,
+    BOUNDARY,
+    TILE_WORDS,
+)
+from blindpath.Constants.env import (
+    DEFAULT_SEED,
+    DEFAULT_ENV_SIZE,
+    DEFAULT_NUM_GOALS,
+    DEFAULT_OBSTACLE_COUNT,
+    DEFAULT_VISION_SIZE,
+    MIN_ENV_DIMENSION,
+    MIN_VISION_SIZE,
+    MIN_NUM_GOALS,
+    MIN_OBSTACLE_COUNT,
+)
+
+__all__ = [
+    "DEFAULT_SEED",
+    "DEFAULT_ENV_SIZE",
+    "DEFAULT_NUM_GOALS",
+    "DEFAULT_OBSTACLE_COUNT",
+    "DEFAULT_VISION_SIZE",
+    "MIN_ENV_DIMENSION",
+    "MIN_VISION_SIZE",
+    "MIN_NUM_GOALS",
+    "MIN_OBSTACLE_COUNT",
+    "AGENT",
+    "EMPTY",
+    "OBSTACLE",
+    "GOAL",
+    "BOUNDARY",
+    "TILE_WORDS",
+]

blindpath/Constants/env.py

@@ -0,0 +1,24 @@
+"""
+Constants for BlindPath environment configuration.
+"""
+
+from typing import Tuple
+
+# ---------------------------------------------------------------------------
+# Default values
+# ---------------------------------------------------------------------------
+
+DEFAULT_SEED: None = None
+DEFAULT_ENV_SIZE: Tuple[int, int] = (40, 40)
+DEFAULT_NUM_GOALS: int = 1
+DEFAULT_OBSTACLE_COUNT: int = 0
+DEFAULT_VISION_SIZE: int = 11
+
+# ---------------------------------------------------------------------------
+# Minimum allowed values
+# ---------------------------------------------------------------------------
+
+MIN_ENV_DIMENSION: int = 5
+MIN_VISION_SIZE: int = 3
+MIN_NUM_GOALS: int = 1
+MIN_OBSTACLE_COUNT: int = 0

blindpath/Constants/tiles.py

@@ -0,0 +1,19 @@
+"""
+blindpath/Constants/tiles.py
+
+Single-character tile labels used throughout the grid system.
+"""
+
+AGENT = "A"
+EMPTY = "E"
+OBSTACLE = "O"
+GOAL = "G"
+BOUNDARY = "B"
+
+TILE_WORDS: dict[str, str] = {
+    AGENT: "Agent",
+    EMPTY: "Empty",
+    OBSTACLE: "Obstacle",
+    GOAL: "Goal",
+    BOUNDARY: "Boundary",
+}

blindpath/DataClasses/__init__.py

@@ -0,0 +1,7 @@
+from blindpath.DataClasses.vector2 import Vector2
+from blindpath.core.grid import Grid
+from blindpath.DataClasses.step_result import StepResult
+from blindpath.DataClasses.env_config import EnvConfig
+from blindpath.DataClasses.generated_map import GeneratedMap
+
+__all__ = ["Vector2", "Grid", "StepResult", "EnvConfig", "GeneratedMap"]

blindpath/DataClasses/env_config.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from blindpath.Constants.env import (
+    DEFAULT_SEED,
+    DEFAULT_ENV_SIZE,
+    DEFAULT_NUM_GOALS,
+    DEFAULT_OBSTACLE_COUNT,
+    DEFAULT_VISION_SIZE,
+    MIN_ENV_DIMENSION,
+    MIN_VISION_SIZE,
+    MIN_NUM_GOALS,
+    MIN_OBSTACLE_COUNT,
+)
+
+
+@dataclass
+class EnvConfig:
+    """All hyperparameters for one BlindPath environment instance."""
+
+    seed: Optional[int] = DEFAULT_SEED
+    env_size: Tuple[int, int] = DEFAULT_ENV_SIZE
+    num_goals: int = DEFAULT_NUM_GOALS
+    obstacle_count: int = DEFAULT_OBSTACLE_COUNT
+    vision_size: int = DEFAULT_VISION_SIZE
+
+    def __post_init__(self) -> None:
+        rows, cols = self.env_size
+        if rows < MIN_ENV_DIMENSION or cols < MIN_ENV_DIMENSION:
+            raise ValueError(f"env_size must be at least {MIN_ENV_DIMENSION}x{MIN_ENV_DIMENSION}")
+        if self.vision_size < MIN_VISION_SIZE:
+            raise ValueError(f"vision_size must be at least {MIN_VISION_SIZE}")
+        if self.vision_size % 2 == 0:
+            raise ValueError("vision_size must be odd")
+        if self.vision_size > min(rows, cols):
+            raise ValueError("vision_size cannot exceed the environment size")
+        if self.num_goals < MIN_NUM_GOALS:
+            raise ValueError(f"num_goals must be >= {MIN_NUM_GOALS}")
+        if self.obstacle_count < MIN_OBSTACLE_COUNT:
+            raise ValueError(f"obstacle_count must be >= {MIN_OBSTACLE_COUNT}")

blindpath/DataClasses/generated_map.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from typing import List
+
+from blindpath.DataClasses.vector2 import Vector2
+from blindpath.core.grid import Grid
+
+
+@dataclass
+class GeneratedMap:
+    grid: Grid
+    agent_start: Vector2
+    goals: List[Vector2]
+    optimal_path_len: int
+    accessible_tiles: int
+    accessible_vision_tiles: int

blindpath/DataClasses/step_result.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from blindpath.DataClasses.vector2 import Vector2
+from blindpath.core.grid import Grid
+
+
+@dataclass
+class StepResult:
+    """Returned by BlindPathEnv.step()."""
+    vision_grid: Grid          # NxN vision window (LLM input)
+    full_grid: Grid            # Full grid (debug only)
+    agent_position: Vector2
+    goals_remaining: int
+    done: bool                 # episode finished (success OR timeout)
+    success: bool              # all goals reached
+    timed_out: bool
+    legal: bool                # was the attempted action legal?
+    iteration: int

blindpath/DataClasses/vector2.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Vector2:
+    x: int   # column
+    y: int   # row (0 = top)
+
+    def __add__(self, other: Vector2) -> Vector2:
+        return Vector2(self.x + other.x, self.y + other.y)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Vector2):
+            return NotImplemented
+        return self.x == other.x and self.y == other.y
+
+    def __hash__(self) -> int:
+        return hash((self.x, self.y))
+
+    def __repr__(self) -> str:
+        return f"Vector2({self.x}, {self.y})"
+
+    def manhattan(self, other: Vector2) -> int:
+        return abs(self.x - other.x) + abs(self.y - other.y)

blindpath/Util/__init__.py

@@ -0,0 +1,9 @@
+"""
+blindpath/Util/__init__.py
+"""
+
+from blindpath.Util.astar import astar
+from blindpath.Util.grid_formatting import grid_to_ascii, grid_to_json, grid_to_chess, grid_to_word, grid_to_row_narrative, grid_to_col_narrative
+from blindpath.Util.action_parsing import parse_action
+
+__all__ = ["astar", "grid_to_ascii", "grid_to_json", "grid_to_chess", "grid_to_word", "grid_to_row_narrative", "grid_to_col_narrative", "parse_action"]

blindpath/Util/action_parsing.py

@@ -0,0 +1,36 @@
+"""
+blindpath/Util/action_parsing.py
+
+Extracts a valid BlindPath action from raw LLM output.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from blindpath.core.env import ACTIONS
+
+
+def parse_action(raw: str) -> Optional[str]:
+    """
+    Try to extract a valid action string from raw LLM output.
+
+    Extracts the first JSON object/array from the response,
+    then checks for a valid "action" field.
+    Returns None if no valid action could be extracted.
+    """
+    match = re.search(r'(\{.*?\}|\[.*?\])', raw, re.DOTALL)
+    if not match:
+        return None
+
+    try:
+        data = json.loads(match.group(0))
+        action = data.get("action", "")
+        if action in ACTIONS:
+            return action
+    except (json.JSONDecodeError, AttributeError):
+        pass
+
+    return None

blindpath/Util/astar.py

@@ -0,0 +1,102 @@
+"""
+blindpath/Util/astar.py
+
+A* pathfinding on a BlindPath grid.
+"""
+
+import heapq
+import math
+from typing import List, Optional
+
+import numpy as np
+
+from blindpath.DataClasses.vector2 import Vector2
+from blindpath.Constants.tiles import OBSTACLE
+
+# ---------------------------------------------------------------------------
+# Directional offsets (shared with other grid algorithms via import)
+# ---------------------------------------------------------------------------
+
+NEIGHBOURS: List[Vector2] = [
+    Vector2(0, -1),   # Up
+    Vector2(0,  1),   # Down
+    Vector2(-1, 0),   # Left
+    Vector2( 1, 0),   # Right
+]
+
+
+def astar(
+    grid: List[List[str]],
+    start: Vector2,
+    goal: Vector2,
+    *,
+    cost_grid: Optional[np.ndarray] = None,
+) -> Optional[List[Vector2]]:
+    """
+    A* from *start* to *goal*.
+
+    Parameters
+    ----------
+    grid : Grid
+        The map. 'O' cells are impassable.
+    start, goal : Vector2
+        Source and target positions (column=x, row=y).
+    cost_grid : np.ndarray | None
+        If given, adds per-cell movement cost on top of the base cost-1.
+        Used during generation to produce naturalistically winding paths.
+
+    Returns
+    -------
+    List[Vector2] | None
+        Ordered list of positions (excluding *start*, including *goal*),
+        or None if no path exists.
+    """
+    rows = len(grid)
+    cols = len(grid[0]) if rows else 0
+
+    def h(pos: Vector2) -> float:
+        return pos.manhattan(goal)
+
+    def cell_cost(pos: Vector2) -> float:
+        base = 1.0
+        if cost_grid is not None:
+            base += float(cost_grid[pos.y, pos.x])
+        return base
+
+    counter = 0   # tie-breaker so Vector2 is never compared by heapq
+    open_heap: list = []
+    heapq.heappush(open_heap, (h(start), 0.0, counter, start))
+    came_from: dict[Vector2, Optional[Vector2]] = {start: None}
+    g_score: dict[Vector2, float] = {start: 0.0}
+
+    while open_heap:
+        _, g, _, current = heapq.heappop(open_heap)
+
+        if g > g_score.get(current, math.inf):
+            continue   # stale entry
+
+        if current == goal:
+            # Reconstruct
+            path: List[Vector2] = []
+            node: Optional[Vector2] = current
+            while node is not None and node != start:
+                path.append(node)
+                node = came_from[node]
+            path.reverse()
+            return path
+
+        for delta in NEIGHBOURS:
+            nb = current + delta
+            if not (0 <= nb.x < cols and 0 <= nb.y < rows):
+                continue
+            if grid[nb.y][nb.x] == OBSTACLE and nb != goal:
+                continue
+            tentative_g = g_score[current] + cell_cost(nb)
+            if tentative_g < g_score.get(nb, math.inf):
+                g_score[nb] = tentative_g
+                came_from[nb] = current
+                f = tentative_g + h(nb)
+                counter += 1
+                heapq.heappush(open_heap, (f, tentative_g, counter, nb))
+
+    return None   # no path

blindpath/Util/grid_formatting.py

@@ -0,0 +1,138 @@
+"""
+blindpath/Util/grid_formatting.py
+
+Display utilities for BlindPath grids.
+
+Cartesian formats  — each tile as an individual data point with coordinates.
+Topography formats — full grid rendered as a 2D map.
+"""
+
+from __future__ import annotations
+
+import json
+import string
+from typing import List
+
+from blindpath.Constants.tiles import TILE_WORDS
+from blindpath.core.grid import Grid
+
+
+# ---------------------------------------------------------------------------
+# Cartesian
+# ---------------------------------------------------------------------------
+
+def grid_to_json(grid: Grid) -> str:
+    """
+    Each grid point as a JSON object with x, y coordinates and label,
+    wrapped in a root object with grid dimensions.
+
+    Example: {"rows": 3, "cols": 3, "tiles": [{"x": 0, "y": 0, "label": "E"}, ...]}
+    """
+    tiles: List[dict] = []
+    for y, row in enumerate(grid):
+        for x, label in enumerate(row):
+            tiles.append({"x": x, "y": y, "label": label})
+    return json.dumps({"matrix_y_size": len(grid), "matrix_x_size": len(grid[0]), "tiles": tiles})
+
+
+def grid_to_chess(grid: Grid) -> str:
+    """
+    Each grid point as a JSON object using chess notation for coordinates,
+    wrapped in a root object with grid dimensions.
+
+    Columns map to letters (a-z), rows count from the bottom (1-based).
+    Example: {"rows": 3, "cols": 3, "tiles": [{"pos": "a3", "label": "E"}, ...]}
+    """
+    rows = len(grid)
+    tiles: List[dict] = []
+    for y, row in enumerate(grid):
+        rank = rows - y  # chess ranks count from bottom
+        for x, label in enumerate(row):
+            file = string.ascii_lowercase[x] if x < 26 else f"c{x}"
+            tiles.append({"pos": f"{file}{rank}", "label": label})
+    return json.dumps({"matrix_y_size": rows, "matrix_x_size": len(grid[0]), "tiles": tiles})
+
+
+# ---------------------------------------------------------------------------
+# Topography
+# ---------------------------------------------------------------------------
+
+def grid_to_ascii(grid: Grid) -> str:
+    """Convert a 2D grid to a compact ASCII string, one row per line."""
+    return "\n".join(" ".join(row) for row in grid)
+
+
+def grid_to_word(grid: Grid) -> str:
+    """
+    Like ASCII but each tile is a full word instead of a single letter.
+
+    Uses TILE_WORDS mapping from Constants. Unknown labels pass through as-is.
+    Words are space-separated, one row per line.
+    """
+    lines: List[str] = []
+    for row in grid:
+        words = [TILE_WORDS.get(tile, tile) for tile in row]
+        lines.append(" ".join(words))
+    return "\n".join(lines)
+
+
+_UNIQUE_TILES = {"A", "G"}
+
+
+def _ordinal(n: int) -> str:
+    """Return the ordinal string for a 1-based number: 1st, 2nd, 3rd, 4th..."""
+    if 11 <= n % 100 <= 13:
+        return f"{n}th"
+    return f"{n}{('th','st','nd','rd')[min(n % 10, 4)] if n % 10 < 4 else 'th'}"
+
+
+def _describe_group(label: str, count: int) -> str:
+    """Describe a run of identical tiles in natural language."""
+    word = TILE_WORDS.get(label, label).lower()
+    if label in _UNIQUE_TILES:
+        return f"the {word}"
+    cell = "cell" if count == 1 else "cells"
+    return f"{count} {word} {cell}"
+
+
+def _run_length_groups(tiles: List[str]) -> List[tuple[str, int]]:
+    """Group consecutive identical tiles into (label, count) pairs."""
+    groups: List[tuple[str, int]] = []
+    for tile in tiles:
+        if groups and groups[-1][0] == tile:
+            groups[-1] = (tile, groups[-1][1] + 1)
+        else:
+            groups.append((tile, 1))
+    return groups
+
+
+def grid_to_row_narrative(grid: Grid) -> str:
+    """
+    Natural language description of the grid, row by row.
+
+    Groups consecutive identical tiles and describes each run.
+    Example: "The 1st row has 3 empty cells, then the goal, then 1 empty cell."
+    """
+    sentences: List[str] = []
+    for i, row in enumerate(grid):
+        groups = _run_length_groups(list(row))
+        parts = [_describe_group(label, count) for label, count in groups]
+        sentences.append(f"The {_ordinal(i + 1)} row has {', then '.join(parts)}.")
+    return "\n".join(sentences)
+
+
+def grid_to_col_narrative(grid: Grid) -> str:
+    """
+    Natural language description of the grid, column by column.
+
+    Groups consecutive identical tiles and describes each run.
+    Example: "The 1st column has 3 empty cells, then the agent, then 1 empty cell."
+    """
+    sentences: List[str] = []
+    cols = grid.cols if hasattr(grid, 'cols') else len(grid[0])
+    for x in range(cols):
+        column = [grid[y][x] for y in range(len(grid))]
+        groups = _run_length_groups(column)
+        parts = [_describe_group(label, count) for label, count in groups]
+        sentences.append(f"The {_ordinal(x + 1)} column has {', then '.join(parts)}.")
+    return "\n".join(sentences)

blindpath/__init__.py

@@ -0,0 +1,53 @@
+"""
+blindpath — Public API
+"""
+
+from blindpath.core.env import BlindPathEnv, ACTIONS
+from blindpath.DataClasses.env_config import EnvConfig
+from blindpath.DataClasses.step_result import StepResult
+from blindpath.DataClasses.vector2 import Vector2
+from blindpath.DataClasses.generated_map import GeneratedMap
+from blindpath.core.grid import Grid
+from blindpath.Constants.tiles import AGENT, EMPTY, OBSTACLE, GOAL, BOUNDARY
+from blindpath.Util.grid_formatting import grid_to_ascii, grid_to_json, grid_to_chess, grid_to_word, grid_to_row_narrative, grid_to_col_narrative
+from blindpath.Util.action_parsing import parse_action
+from blindpath.core.map_generation import generate_map
+from blindpath.agents.base import BaseAgent
+from blindpath.agents.random_agent import RandomAgent
+from blindpath.agents.pomcp_agent import POMCPAgent
+from blindpath.agents.llm_agent import LLMAgent
+from blindpath.eval.episode_metrics import EpisodeMetrics
+from blindpath.eval.benchmark_results import BenchmarkResults
+from blindpath.session import Session
+from importlib.metadata import version as _version
+
+__version__ = _version("blindpath")
+
+__all__ = [
+    # Environment
+    "BlindPathEnv",
+    "EnvConfig",
+    "StepResult",
+    "ACTIONS",
+    # Grid
+    "Vector2",
+    "Grid",
+    "generate_map",
+    "grid_to_ascii",
+    "grid_to_json",
+    "grid_to_chess",
+    "grid_to_word",
+    "grid_to_row_narrative",
+    "grid_to_col_narrative",
+    "parse_action",
+    # Agents
+    "BaseAgent",
+    "RandomAgent",
+    "POMCPAgent",
+    "LLMAgent",
+    # Metrics
+    "EpisodeMetrics",
+    "BenchmarkResults",
+    # Session
+    "Session",
+]

blindpath/agents/__init__.py

@@ -0,0 +1,11 @@
+from blindpath.agents.base import BaseAgent
+from blindpath.agents.random_agent import RandomAgent
+from blindpath.agents.pomcp_agent import POMCPAgent
+
+__all__ = ["BaseAgent", "RandomAgent", "POMCPAgent"]
+
+try:
+    from blindpath.agents.llm_agent import LLMAgent
+    __all__.append("LLMAgent")
+except ImportError:
+    pass

blindpath/agents/base.py

@@ -0,0 +1,39 @@
+"""
+blindpath/agents/base.py
+
+Abstract base class for all BlindPath agents.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from blindpath.core.env import BlindPathEnv
+from blindpath.DataClasses.step_result import StepResult
+
+
+class BaseAgent(ABC):
+    """
+    Every agent must implement `step()`.
+
+    Parameters passed to `step()`:
+    - env       : the live environment (agents may read public properties
+                  but must NOT modify internal state directly).
+    - result    : the StepResult from the previous step (or initial reset).
+    """
+
+    @abstractmethod
+    def step(
+        self,
+        env: BlindPathEnv,
+        result: StepResult,
+    ) -> str:
+        """
+        Return one of: "Up", "Down", "Left", "Right".
+        """
+
+    def reset(self) -> None:
+        """Called at the beginning of every new episode. Override if needed."""
+
+    def observe(self, action: str, result: StepResult) -> None:
+        """Called after env.step() with the action taken and result. Override if needed."""

blindpath/agents/llm_agent.py

@@ -0,0 +1,69 @@
+"""
+blindpath/agents/llm_agent.py
+
+Abstract base class for LLM-powered BlindPath agents.
+
+Subclasses implement `_prompt()` to call their LLM of choice.
+The base class handles prompt assembly and action parsing.
+"""
+
+from __future__ import annotations
+
+import random
+from abc import abstractmethod
+from typing import Callable, Optional
+
+from blindpath.agents.base import BaseAgent
+from blindpath.core.env import ACTIONS, BlindPathEnv
+from blindpath.DataClasses.step_result import StepResult
+from blindpath.Util.action_parsing import parse_action
+
+
+PromptBuilder = Callable[[BlindPathEnv, StepResult], Optional[str]]
+
+
+class LLMAgent(BaseAgent):
+    """
+    Abstract base for LLM-powered agents.
+
+    Subclasses must implement `_prompt()` to call their LLM and return
+    the raw response string. The base class assembles the full prompt
+    (custom + static + vision) and parses the action from the response.
+
+    Parameters
+    ----------
+    prompt_builder : PromptBuilder | None
+        Optional callback that receives (env, result) and returns a custom
+        prompt string to prepend before the static prompt.
+    """
+
+    def __init__(self, *, prompt_builder: Optional[PromptBuilder] = None) -> None:
+        self._prompt_builder = prompt_builder
+        self.compliance_failures: int = 0
+
+    @abstractmethod
+    def _prompt(self, prompt: str) -> str:
+        """Send the assembled prompt to the LLM and return the raw response."""
+
+    def reset(self) -> None:
+        self.compliance_failures = 0
+
+    def step(self, env: BlindPathEnv, result: StepResult) -> str:
+        parts: list[str] = []
+
+        if self._prompt_builder is not None:
+            custom = self._prompt_builder(env, result)
+            if custom:
+                parts.append(custom.strip())
+
+        parts.append(env.get_static_prompt())
+        parts.append(f"\nCURRENT VISION GRID:\n{env.get_vision_string()}")
+
+        raw = self._prompt("\n\n".join(parts))
+        action = parse_action(raw)
+
+        if action is None:
+            self.compliance_failures += 1
+            action = random.choice(list(ACTIONS.keys()))
+
+        return action