COSC343

Wordle playing agent

Task 1 (10 marks)
Write a Python program that plays the game of Wordle.
In the game of Wordle the player attempts to guess a target word in as few attempts as
possible given information about which letters from the guesses are present (or not present)
in the intended solution. The objective for your agent will be to score the lowest average
number of guesses across a number of games.
The environment
The environment for this game uses a dictionary of words of certain length, and runs the
game a number of times, each time picking a random word from the dictionary for the
solution. For a given run the player/agent has up to some maximum number of guesses to
guess the solution word. In the ‘easy’ mode of the game the environment is episodic – each
guess of the agent is treated independently of the previous guesses providing information
about whether letters in the guess are present in the solution, and whether they are in
correct position. In the ‘hard’ mode, the environment still provides the same feedback
about a given guess, but over the set of guesses to a given solution word the environment
is sequential – it remembers previous guesses and does not allow a new guesses that do
not contain letters already revealed to be part of the solution and it does not allowed
misplacement of letters already revealed to be in the correct position.
The agent is scored over a series of plays with the average number of guesses it takes to
find the solution word. There is an extra penalty that doubles the score for the particular
run if the agent does not guess the word within the allowed maximum number of guesses.
Thus, for example, in a game of maximum of 6 guesses, an agent can obtain a score of
1,2,3,4,5,6 or 12.
Game parameters
For the purpose of development and testing, the game environment in this assignment will
have the following configurable parameters:
• dictionary,
• length of words used in the game,
• maximum number of guesses allowed,
• number of games that are played,
• game mode (easy or hard),
• whether repeats of target solution are allowed or not,
• seed of the pseudorandom number generator picking the solution words.
The agent
The agent whose behaviour you have to implement for this assignment is a Wordle player.
On initialisation the agent is provided with the dictionary that the environment is using,
valid alphabet of letters, the length of the solution word, number of guesses per game and
the mode that the game is played in.
The agent function
The agent function is invoked to get agent’s next guess. Its single argument is a tuple of
percepts, which relate the information about the last guess provided by the environment.
The agent function returns a string, which is a word from the dictionary that constitutes
the next guess.

Percepts
The percepts of the Wordle-playing agent is a tuple that contains three pieces of informa-
tion:
• guess counter – an integer value indicating which guess the agent is on, starting
with guess counter=0 indicating the first guess;
• letter indexes – a list of integers indexing the valid alphabet (passed in at initiali-
sation time) according to the letters of the last valid guess; informs what the last valid
guess was; the length of this list is the length of the guess word; at guess counter=0
this list contains all -1’s and it should be ignored by the agent.
• letter states – a list of integers that can be either -1, 0 or 1, relating whether and
which letters from the corresponding letter indexes are in the solution word, and
whether they are in correct place; informs how the last valid guess relates to the secret
solution; the length of this list is the length of the guess word; at guess counter=0
this list contains all 0’s and it should be ignored by the agent.
The meaning of the three valid letter states is as follows:
• -1 – the corresponding letter indexed by letter indexes is present in the solution,
but not in that position (equivalent to yellow state in the official implementation of
Wordle);
• 0 – the corresponding letter indexed by letter indexes is not present in the solution
(equivalent to the grey state in the official implementation of Wordle);
• 1 – the corresponding letter indexed by letter indexes is in the solution and in the
same location (equivalent to the green state in the official implementation of Wordle).
For an illustrative example of how the percepts work, see Figure 1.
Actions
The action of the agent is a string from the dictionary, which constitutes the next guess.
In ‘easy’ mode a valid guess is any word from the dictionary. In ‘hard’ mode a valid guess
is a word from dictionary that contains all previously revealed letters to be in the solution
in their correct place if their location was revealed. If the agent guesses correctly within
the maximum number of guesses, its function is invoked once more with the correct guess
revealed via letter indexes and all 1’s of the letter state in the percepts. The action
returned by the agent after being shown the correct guess is ignored. If the agent does not
guess correctly within the maximum number of guesses allowed, it is not given the solution

Figure 1: Percepts corresponding to a sequence of guesses in a 5-letter game with the alpha-
bet of letters as shown on top of the figure; a) first guess, the values of letter indexes
and letter states should be ignored by the agent; b) second guess indicating the previ-
ous guess was ‘WORDS’ and none of its letters are in the solution; c) third guess indicting
the previous guess was ‘INPUT’, with ‘N’ being present in the solution, but not as a sec-
ond letter, and ‘T’ also being present and being the last letter of the solution; d) fourth
guess indicating the previous guess was ‘GAMES’, with ’G’, ’A’, and ’E’ being found in the
solution, but not in the same places; e) fourth guess, indicating the last guess was not a
valid guess as the guess counter has not incremented and the last valid guess, ‘GAMES’,
is still given in the percepts; f) fifth guess indicating the last valid guess was ’AGENT’
and that it was the intended solution – whatever action the agent returns in this case is
ignored, since this run of the game is finished.
(though in verbose mode the environment prints the solution to the console). The next
time agent is invoked, the guess counter will be 0, which indicates a new run of the game
is played.
The engine
A framework project implementing the environment for this assignment is provided for
you. For files and instructions on how to use it see the “How to use the Wordle Engine for
Assignment 1” in the “Assignments” section on Blackboard.

Task 2 (10 marks)
You must also write a report explaining the strategy of your agent and providing some
results of its evaluation. The report should include:
• a brief introduction – you don’t have to repeat the entire description of the game
and environment given, but a short intro to what your report is about is required;
• explanation of how your agent works – the strategy, high level algorithm, not expla-
nation of you code line by line;
• analysis of your agent’s performance with some results – ideally conveyed via graphs
and/or tables;
• brief conclusion – summary/discussion of the results/conclusions;
• citations – if needed;
• information on how to run your code – if extra libraries are required.
Screenshots of the text in your terminal and/or photos of hand-drawn diagrams are not
the best way to add figures to your report. Figures and diagrams are great to have, but
draw them properly (in Inkscape or PowerPoint for instance).
To give you a bit of guidance for the report structure, a L
A T E Xtemplate is provided (you can
find it on Blackboard in the ”Assignments” section under ”Report template in L
A T E X”).
You don’t have to use L
A T E X to write your report – but it might be a good idea to follow
the general structure provided in the template.
Finally, to pre-empt inevitable questions about the length of the report, let’s say: ”around
1500 words (which is roughly 3 pages)”. But this is not an absolute number – a bit more
is fine; more pages if you have lots of figures is not a problem; a shorter (but really good)
report won’t be marked down for length.