# Template für das Agentensystem

## Einstieg
0. Rechner vorbereiten
 	1. Docker Desktop installieren <https://docs.docker.com/desktop/>
	2. Editor (IDE) installieren (freie Auswahl, Beispiele für <https://code.visualstudio.com/>)
1. Repository einrichten 
	1. Template laden `git clone -o UHH https://git.chai.uni-hamburg.de/UMS-Agenten/Agent-Template.git`
	2. *Eigenes* Repository hinzufügen `git remote add UMS https://git.uni-muenster.de/example/my-group.git`
	3. In *eigenes* Repository pushen `git push UMS master`
	4. Später dann auch immer `git push UMS ...`, `git pull UMS ...`
	5. Updates vom Template `git pull UHH master` (Achtung: Merge-Konflikt)
2. Lokale Umgebung (kann übersprungen werden, mach aber das Entwickeln netter; nur für VS Code)
	- Python-Paket `src`: Eigene Implementierung
	- Python-Paket `ums`: Agenten-Plattform ([Quelle](https://git.chai.uni-hamburg.de/UMS-Agenten/Agenten-Plattform/src/branch/master/ums))
	- VS Code kann leider kein Autocomplete/ IntelliSense im Docker Container anbieten, daher müssen die Quellen auch auf dem Host verfügbar sein.
	- VS Code erkennt das Verzeichnis `./src/` als Paket `src`
	- Wir brauchen zusätzlich ein paar Abhängigkeiten und `ums`
	1. Virtuelles Env. erstellen `python3 -m venv .`
	2. Virtuelles Env. aktivieren `source ./bin/activate`
	3. Pakete installieren `pip install requests fastapi pdoc` (evtl. später weitere, damit diese auch IntelliSense unterstützen)
	4. In VS Code (in einer Python-Datei unten rechts) das Virtuelle Env. auswählen (`./bin/...`)
	5. Verzeichnis `ums` aus dem Docker Container extrahieren:
		```bash
			docker create --name "management" "git.chai.uni-hamburg.de/ums-agenten/management:arm64" # oder :amd64
			docker cp "management:/ums-agenten/plattform/ums/" ./ums/
			docker rm "management"
		```
	- Virtuelles Env. und das Verzeichnis `./ums` werden von git ignoriert (siehe `./.gitignore`) 
3. Agenten und Management starten
	- Die Konfiguration des Managements und er verschiedenen Agenten erfolgt über die Datei `docker-compose.yml`
	- Es ist sehr sinnvoll die Datei einmal durchzugehen und die Kommentare dort anzusehen.
	1. Für jeden Container/ Service die Images prüfen und anpassen (`:arm64` or `:amd64`, siehe [&darr;](#docker-images))
	2. `docker compose up` startet alle Container wie in der `docker-compose.yml` angegeben
		- Anschließend hängt das Terminal an der Ausgabe der verschiedenen Container
		- Fehler erscheinen dort im Terminal oder/ und in `./data/persist-*/ums.log`
	3. Das Management kann über <http://localhost:8080> erreicht werden, es bietet:
		- Dokumentation: <http://localhost:8080/docs/ums.html>
		- Übersicht der Nachrichten zwischen Agenten und Management: <http://localhost:8080/app/table>
		- Senden von Nachrichten/ Erstellen von Rätseln: <http://localhost:8080/app/new>
		- Web API: <http://localhost:8080/api> (siehe auch <http://localhost:8080/docs/ums/utils/request.html>)
4. Im Ordner `src` ist ein sehr einfaches Agentensystem implementiert [&rarr; Beispiel: Rätsel & Agent](./Example.md)
5. Die Implementierung kann auf dem Beispiel aufbauen [&rarr; Implementierung](./Implement.md)

> **Generell gilt:**
> Die Images sind größtenteils neu. 
> Auch das Management und Agenten-Framework wurde neu entworfen, d.h., es können (und werden) noch ein paar Käfer irgendwo lauern.
> Bugs also bitte melden und bei Problemen mit dem System nachfragen (magnus.bender@uni-hamburg.de).

## Update Images
- Image für Management 
	- `docker compose pull` (aktualisiert neu)
- Images für Agenten
	- `docker pull git.chai.uni-hamburg.de/ums-agenten/base-agent:cpu-arm64` (oder `:cpu-amd64`)
	- `docker compose build`

## Docker Images
Es gibt unter <https://git.chai.uni-hamburg.de/UMS-Agenten/-/packages> viele verschiedene Docker Images.
Die Images stellen die vorbereitete Umgebung da.

Folgende Images sind verfügbar:
- `base-image`
	- Basis für alle Agenten, beinhaltet eine Menge von relevanten Tools (Python und Pakete mit z.B. PyTorch, ...)
	- Tags `:cpu-arm64 :cpu-amd64 :gpu-amd64`
		(Die `cpu-*` Variante sind für das lokale Entwickeln und beinhalten keine NVIDIA CUDA Treiber, sind aber sonst identisch.
		Die `gpu-*` Variate kann später auf dem Evaluationsserver ausgeführt werden, oder wenn man lokal einen geeignete GPU hat, das Image ist durch die Treiber sehr groß.
		Die `*-arm64` Variante ist insb. für aktuelle Apple-Prozessoren gedacht.)
	- Das Image wird als Basis für `base-agent` benutzt, muss also i.A. nicht direkt genutzt werden.
- `management`
	- Das Image für den Management Container.
	- Tags `:arm64, :amd64` 
		(Alles CPU Varianten, `arm64` ist wieder insb. für aktuelle Apple-Prozessoren und `amd64` für alle anderen.)
	- Hier muss nichts angepasst werden. Der Container muss nur lokal und später auf dem Server laufen und stellt dann das Management für die einzelnen Agenten (auch wieder einzelne Container) bereit.
- `base-agent`
	- In diesem Image sind die Agenten zu implementieren bzw. darauf aufzubauen.
	- Tags `:cpu-arm64 :cpu-amd64 :gpu-amd64`
		(Analog zu `base-image`)
	- Dieses Repository bildet einen einfachen und beispielhaften Agenten ab und soll als Basis dienen.


Es wird im Laufe der Zeit sicherlich Updates der verschiedenen Images geben. 
Aus diesem Grund gibt bei den Tags Suffixe wie z.B. `2024-10-04` mit dem Datum des Build eines Images.
Somit bleiben auch alte Versionen erreichbar, auch wenn am Ende die aktuelle Version ohne Suffix genutzt werden soll.