Summary	Students design and implement agents for the board game of RISK, using knowledge and techniques gained in the class. These agents then compete in a class tournament for extra credit. Two preliminary assignments are also included, where students implement uniform cost search and decision trees within the context of RISK. These assignments can be used to help students get started with ideas for their agents.
Topics	Game-tree search, probabilistic reasoning, uniform cost search, decision-trees, reinforcement-learning
Audience	Introduction to AI. Could be used for more advanced general AI or machine learning classes as well.
Difficulty	To get full credit students have to create an agent that beats a provided baseline agent. This task can usually be achieved with a low to medium amount of effort. Extra credit is on the line as the students compete against each other and against the instructor/TA (if they choose to participate). Success in the class competitions is very challenging. Some students welcome this challenge and spend a lot of time and effort on the assignment, but also get a lot out of it. Of course, instructors can change the difficulty of the baseline agent or how much credit comes due to the tournament to impact the difficulty.
Strengths	Very engaging for students to work on, and very fun to watch the results together. Open ended, so students get to decide which ideas from the class they will use in their agent, and even come up with their own new ideas, which can get them interested in research. Students usually work in teams so this promotes collaboration. The preliminary assignments provide a way to give the students more exposure to the RISK simulator and cover important AI topics.
Weaknesses	A reasonably successful agent can be designed without using a lot of AI ideas. Some students come in already not liking the game of RISK and aren't excited about the assignment.
Dependencies	Provided code (simulator, gui, assignment starter code, tournament scripts) is in Python 2.7. UPDATE: A Python 3 port is now available as a link at the bottom of this page. Requires Python Imaging Library (PIL).
Variants	Instructors can change the way that credit is assigned, i.e. put more weight on the tournament to encourage students to spend more time on it. Instructors can also vary the baseline agents that students use to train against, making it more challenging to beat them. Instructors could require specific AI techniques to be used in the final agent, or at least one topic from the class. The amount of planning time the AIs have during a game is also easily modified. The instructor can also vary the way the tournament is run, several different styles are provided.

Files included:

README - Help to get anyone started with RISK and this project.
instructor_notes.html - Instructor notes, including instructions for running tournaments
Assignment Handouts:
- RISK_AI_Handout.pdf - Main assignment handout.
- RISK_AI_Handout.tex - Main assignment handout source.
- RISK_Search_Handout.pdf - Preliminary search assignment handout.
- RISK_Search_Handout.tex - Preliminary search assignment handout source.
- RISK_Decision_Tree_Handout.pdf - Preliminary decision tree assignment handout.
- RISK_Decision_Tree_Handout.tex - Preliminary decision tree assignment handout source.
RISK Simulator Files:
- risktools.py - Main RISK simulator code.
- risktools.m.html - Simulator html documentation
- play_risk_ai.py - Script that will play matches between agents.
- risk_game_viewer.py - Script that will allow you to watch a game log.
- world.zip - a .zip file containing the information about the board/map and images for the RISK game board.
RISK AI Files:
- ai\attacker_ai.py - Provided baseline AI. Always attacks if it can.
- ai\random_ai.py - Provided baseline AI. Selects random valid action.
- ai\donothing_ai.py - Provided baseline AI. Random agent, except never attacks.
- ai\heuristic_ai.py - Provided starter AI. Agent that simulates all valid actions, evaluates possible resulting state with heuristic function, then chooses action with highest expected heuristic value. The heuristic function is not implemented. Provided as possible starter code for student AIs.
Preliminary Assignment Files:
- RISK Search Assignment
  - risk_search.py - Search assignment starter code
  - risk_search_solution.py - Search assignment solution code
- RISK Decision-Tree Assignment
  - generate_dt_data.py - Script to generate data for decision tree learning. This has already been run to provide data for the assignment, but is provided so students or instructors can generate their own datasets from their own agents.
  - learn_d_tree.py - Decision tree assignment starter code
  - learn_d_tree_solution.py - Decision tree assignment solution code
  - evaluate_d_tree.py - Decision tree evaluation code. Used by students to evaluate their learned decision trees.
  - example_tree.txt - This is the example output for decision tree code run on the smallest dataset. For students to be able to ensure their code is working properly.
  - Decision Tree Data
    - dt_data\dt_10.dat - Data generated from 10 matches. Useful for ensuring that assignment code is functioning properly.
    - dt_data\dt_1000.dat - Data generated from 1000 matches.
    - dt_data\dt_10000.dat - Data generated from 10000 matches.
    - dt_data\dt_100000.dat - Data generated from 100000 matches.
    - dt_data\dt_test.dat - Dataset for evaluating learned decision trees.
Helpful Tournament Scripts (for Instructors):
- run_rr_tournament.py - This script will run a full round robin tournament, where every AI plays against every other combination of AIs in a match. Due to the number of matches this creates, it is recommended to only be used for two-player and three-player variants of RISK, except in the case of very low number of competing AIs. Tournament results are saved to the tournaments folder.
- run_sampled_tournament.py - This script runs a sampled tournament. This means that before each match, the participating agents are randomly selected from the all of the AIs. The mean points obtained across all matches is stored for every AI and can be used to rank their performance. This is very useful for variants of RISK with between four and eight players.
- save_csv_results_2p.py - This script will process the results from a two-player RISK tournament file (generated by the run_rr_tournament script) and save it out into a csv table for display.
- save_csv_results_3p.py - This script will process the results from a three-player RISK tournament file (generated by the run_rr_tournament script) and save it out into a csv table for display.
- iterative_knockout_results.py - This script will process the results from a round robin tournament (generated by the run_rr_tournament script) as an iterative knockout tournament. This means that repeatedly, all of the results from still included players will be processed, and the lowest scoring player will be eliminated. Thus, points gained from beating eliminated players will not count moving forward, and instead the importance is performance against remaining players. This is done until only enough players for a single game are left, at which point they are ranked based on their performance with that set of agents. This script works with any number of players in a game, but is usually used with two or three player games, since that is the about the limit of the run_rr_tournament script
Interactive GUI files. This GUI allows students to play interactively against the agents. This GUI code was written by John Bauman and is used basically unchanged under the GNU General Public License (see additional information in files):
- risk.pyw - The main script for running the GUI.
- gui\__init__.py - Init file for gui folder
- gui\aihelper.py - Support code for interactive RISK GUI
- gui\riskengine.py - Support code for interactive RISK GUI. Implements the rules of RISK.
- gui\riskgui.py - Support code for interactive RISK GUI
- gui\risknetwork.py - Support code for interactive RISK GUI
- gui\turbohelper.py - Support code for interactive RISK GUI
RISK_AI.zip - a .zip file containing all of the above.
RISK-AI-master.zip - a 2022 April 18 clone of the Python 3 version GitHub repository