Metadata-Version: 2.1
Name: starcode-labyrinth
Version: 0.1.0
Summary: A module to draw labyrinth maps and navigate through them. This is intended for teaching.
Home-page: https://gitlab.com/bpaassen/starcode_labyrinth
Author: Benjamin Paassen
Author-email: benjamin.paassen@dfki.de
License: UNKNOWN
Keywords: labyrinth finite-state-automata finite-state-machines
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: matplotlib

# Starcode Labyrinth

Copyright (C) 2022 - Benjamin Paassen  
starcode  

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see http://www.gnu.org/licenses/.

## Introduction

This module provides functions to draw labyrinth maps and execute
agents in form of finite state machines on them. This module is
intended for teaching, in particular during the courses of
[starcode](https://www.starcode.info/).

## Overview

The key concept for this module is that of an agent, which is
described by a function of the following form.

```python
from starcode_labyrinth import logic

def agent(free, memory):
    return logic.GO, 'new_memory'
```

The function receives two inputs. The first one is a boolean
indicating whether the field ahead of the agent is free or not.
The second one is the current memory state of the agent.
The first output is the next action of the agent (either `logic.GO`,
`logic.LEFT`, or `logic.RIGHT`). The second output is the
next memory state of the agent.

You can execute your agent on a level via the following function.
In this case, we use the first standard level provided by the logic
package.

```python
trace = logic.execute_agent(agent, level = logic.levels[0], start_memory = 'start_memory')
```

This function calls your agent again and again and executes the
actions (if possible). The output is a list of states, indicating
where the agent is in the level and the memory state.

If you want to inspect the trace, you can use the drawing function.

```python
from starcode_labyrinth import drawing
drawing.draw_trace(trace, level = logic.levels[0])
```

This will look something like this:

![An example trace where an agent walks rights two steps](example_trace.png)

The agent is visualized via the blue triangle. The orientation of
the agent is indicated by its point. The goal of the labyrinth is
the orange star. In this case, the agent does indeed end up at the
goal.

The module also provides a feedback function to execute an agent
on an entire list of levels and check where it fails.

```python
from starcode_labyrinth import feedback
feedback.evaluate_agent(agent, start_memory = 'start_memory')
```


