Simple Example Agent

Example.md

@@ -1,3 +1,86 @@
 # Beispiel: Rätsel & Agent
 
-TODO
+Der Beispielagent kann Rechenaufgaben lösen, dabei ist das Rätsel eine einfache Aufgabe mit Variablen und in den Daten (Textdateien) werden den Variablen Werte zugewiesen. 
+
+> Der Beispielagent ist nicht sonderlich *schlau*, sondern funktioniert nur Rätseln, die genau einen bestimmten Aufbau haben.
+
+## Beispiel Rätsel (`AgentMessage`)
+- Daten (als Dateien in `./data/share`)
+	- `./example/x.txt`: `x = 10`
+	- `./example/y.txt`: `y = 15`
+	- `./example/z.txt`: `z = 20`
+- Rätsel z.B. 
+	- Kontext: "[Taschenrechner]"
+	- Frage: "x * y ="
+- Eingabe unter <http://localhost:8080/app/new> möglich
+	- Für die Dateien ist eine Liste vorhandener Dateien hinterlegt, sodass Eingaben vervollständigt werden.
+	- Es wird eine JSON-Vorschau angezeigt und das Rätsel kann an das Management geschickt werden
+- Beispiel für JSON Darstellung [&darr;](#json-darstellung)
+- Nachrichten könnten unter <http://localhost:8080/app/table> angesehen werden
+	- Nachricht mit `Solution=True` sollte dann die Lösung beinhalten
+
+## Ablauf der Bestimmung der Lösung
+1. Nachricht mit Rätsel an Management senden
+2. Management wertet Nachricht und sendet Nachricht an alle ihm bekannten Extract-Agenten
+3. Extract-Agenten extrahieren Daten und senden Ergebnis zurück an Management (`status.extract.finished == True`)
+4. Management senden Nachricht (mit Extraktionen) an alle ihm bekannten Solve-Agenten
+5. Solve-Agenten versuchen das Rätsel zu lösen
+	- Können Sub-Rätsel erstellen (<http://localhost:8080/docs/ums/agent/agent.html#BasicAgent.sub_riddle>)
+	- Bekommen ein Rätsel evtl. mehrfach (jeweils wenn ein Extract-Agent) fertig geworden ist. (Evtl. Lösen mit Teilen der Infos schon möglich oder auch nicht.)
+	- Können Antworten an das Management stoppen (<http://localhost:8080/docs/ums/agent/agent.html#BasicAgent.before_response>)
+6. Management bekommt Ergebnis von Solve-Agenten und sendet dies an Gatekeeper-Agenten
+7. Gatekeeper-Agent prüft Lösung und akzeptiert oder lehnt diese ab. Sendet Entscheidung an Management.
+8. Management prüft, ob Lösung angenommen. Falls Lösung nicht akzeptiert, so wird Rätsel erneut gestellt (maximal `SOLUTION_MAX_TRIALS` mal)
+
+## Agenten Quellcode
+1. Extract [`./src/extract/agent.py`](./src/extract/agent.py)
+2. Solve [`./src/solve/agent.py`](./src/solve/agent.py)
+3. Validate [`./src/validate/agent.py`](./src/validate/agent.py)
+
+### JSON-Darstellung
+```json
+{
+	"id": "ex1",
+	"sub_ids": [],
+	"riddle": {
+		"context": "[Taschenrechner]",
+		"question": "x * y =",
+		"solutions_before": []
+	},
+	"solution": null,
+	"data": [
+		{
+			"type": "text",
+			"file_plain": "example/x.txt",
+			"file_extracted": null
+		},
+		{
+			"type": "text",
+			"file_plain": "example/y.txt",
+			"file_extracted": null
+		},
+		{
+			"type": "text",
+			"file_plain": "example/z.txt",
+			"file_extracted": null
+		}
+	],
+	"status": {
+		"extract": {
+			"required": true,
+			"finished": false
+		},
+		"solve": {
+			"required": true,
+			"finished": false
+		},
+		"validate": {
+			"required": true,
+			"finished": false
+		},
+		"trial": 0,
+		"solved": false
+	},
+	"contacts": 0
+}
+```