How yan25-06/ai-project works
1. Project shape
- This is a Python search/solver project with two front doors: a CLI entry point in src/main.py and a Streamlit GUI in src/GUI/main.py.
- The core application is organized around a reusable game/state model plus multiple search algorithms.
2. Core domain layer
- src/game/game.py appears to define the problem environment and state transitions.
- src/GUI/state.py likely mirrors or adapts the same state concepts for visualization.
- This layer is the main boundary between “problem definition” and “search algorithms.”
3. Solver subsystem
- src/solver/ contains four algorithm implementations: BFS_solver.py, DFS_solver.py, UCS_solver.py, and Astar_solver.py.
- solver_base.py provides the shared interface/behavior for all solvers.
- The solvers are the main computational subsystem and likely consume game states, expand successors, and produce a path/solution trace.
4. Solver selection / orchestration
- src/helper/solver_factory.py is the central wiring point for choosing which solver to run.
- This factory is the architectural seam between user choice/configuration and the algorithm implementation.
5. GUI subsystem
- src/GUI/main.py is the Streamlit app entry point.
- visualizer.py handles rendering of game state and solver results.
- config.py holds GUI-specific constants, and assets/ contains UI resources.
- The GUI is a consumer of solver outputs rather than the place where algorithms live.
6. Precomputed solution artifacts
- src/GUI/Solution/{Astar,BFS,DFS,UCS}/MAP_*.pkl stores serialized solution data per algorithm and map.
- These pickle files act as a data cache or dataset for the visualizer, letting the GUI display results without recomputing them every time.
- The repeated MAP_1.pkl … MAP_20.pkl pattern suggests multiple scenarios/maps are part of the evaluation set.
7. Input/test generation tooling
- src/bin/ contains utility scripts such as generate_next_states.py, gen_test_ucs.py, and toy.py.
- Makefile, testcase.txt, and test5.txt suggest support tooling for generating or validating search instances.
- This folder is auxiliary infrastructure, not the main runtime path.
8. Testing and benchmark inputs
- src/test/final_testcase.txt and src/test/test.py indicate a test harness or benchmark runner for solver correctness/performance.
- The repository seems to separate generated cases, final test cases, and interactive GUI assets.
9. Execution flow
- CLI flow: src/main.py likely loads a map/problem, asks the factory for a solver, runs the search, and emits a solution.
- GUI flow: Streamlit loads a selected map/solution pair from the pickle artifacts and uses the visualizer to present the state sequence.
- In both flows, the game/state model is the common contract.
10. Dependency boundary
- The architecture is intentionally layered: GUI and utility scripts sit on top, solvers in the middle, and game/state definitions at the core.
- The search algorithms should not depend on GUI code; the GUI consumes solver outputs, not the other way around.
- That separation is important for drawing the architecture diagram: keep “problem model,” “search engines,” and “presentation” as distinct boxes.
11. Runtime and tooling
- The project is pure Python, with Streamlit as the only visible UI runtime.
- requirements.txt defines the Python dependencies; packages.txt suggests additional system packages may be needed for the environment.
- No database or external network service is evident; persistence is file-based via text inputs and pickle outputs.
Main entry points: solver_factory.py Solver factory · Solution Solution cache · game.py Game model · solver_base.py Solver base
Components 19
Core domain
Problem model and shared state contract
- Game model · Problem environment and transitions
src/game/game.py - Solver factory · Selects and wires the requested solver
src/helper/solver_factory.py
Search engines
Reusable search algorithm implementations
- Solver base · Shared solver interface and behavior
src/solver/solver_base.py - BFS · Breadth-first search implementation
src/solver/BFS_solver.py - DFS · Depth-first search implementation
src/solver/DFS_solver.py - UCS · Uniform-cost search implementation
src/solver/UCS_solver.py - A* · Heuristic search implementation
src/solver/Astar_solver.py
Presentation
CLI and Streamlit front doors plus visualization
- CLI entry · Starts command-line solving flow
src/main.py - GUI entry · Starts the Streamlit interface
src/GUI/main.py - Visualizer · Renders states and solution traces
src/GUI/visualizer.py - GUI state · Presentation-side state representation
src/GUI/state.py - UI config · GUI constants and display settings
src/GUI/config.py
Artifacts
Precomputed solution caches used by the GUI
- Solution cache · Precomputed solver traces for GUI playback
src/GUI/Solution - A* cache · Saved A* solutions for multiple maps
src/GUI/Solution/Astar - BFS cache · Saved BFS solutions for multiple maps
src/GUI/Solution/BFS - DFS cache · Saved DFS solutions for multiple maps
src/GUI/Solution/DFS - UCS cache · Saved UCS solutions for multiple maps
src/GUI/Solution/UCS
Tooling
Scripts and test inputs for generation and validation
- Bin tools · State generation and solver test helpers
src/bin - Test inputs · Text fixtures for solver validation
src/test
Connections 23
- CLI entry → Solver factory: selects solver · CLI delegates solver choice and execution
- Solver factory → BFS: creates · Factory can instantiate BFS
- Solver factory → DFS: creates · Factory can instantiate DFS
- Solver factory → UCS: creates · Factory can instantiate UCS
- Solver factory → A*: creates · Factory can instantiate A*
- BFS → Solver base: extends · BFS follows shared solver contract
- DFS → Solver base: extends · DFS follows shared solver contract
- UCS → Solver base: extends · UCS follows shared solver contract
- A* → Solver base: extends · A* follows shared solver contract
- Solver base → Game model: expands · Solvers consume game states and successor generation
- Game model → CLI entry: loads problem · CLI operates on the domain model
- GUI entry → Visualizer: drives · Streamlit entry renders the interface
- GUI entry → UI config: uses · GUI entry reads presentation settings
- Visualizer → GUI state: renders · Visualizer consumes UI state objects
- Visualizer → Solution cache: loads traces · Visualizer reads serialized solution artifacts
- Solution cache → A* cache: contains · Grouped cache for A*
- Solution cache → BFS cache: contains · Grouped cache for BFS
- Solution cache → DFS cache: contains · Grouped cache for DFS
- Solution cache → UCS cache: contains · Grouped cache for UCS
- Bin tools → Game model: generates states · Utility scripts help build or inspect search instances
- Bin tools → Test inputs: validates against · Scripts and harnesses use benchmark inputs
- Test inputs → Game model: defines instances · Test fixtures provide problem setups
- GUI state → Game model: adapts · UI state mirrors the core domain model