AISE1_Project_Irina_Livio/README.md

AISE AI Agent — Code Editor & Coding Assistant

Ein browserbasierter Code-Editor mit integriertem AI-Chat und autonomem Coding-Agent, gebaut mit Streamlit und dem Model Context Protocol (MCP).

---

Installation & Setup

Voraussetzungen: Python 3.13+, pip

# 1. Repository klonen und ins Verzeichnis wechseln
cd AISE_AIAgent

# 2. Virtuelle Umgebung erstellen und aktivieren
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux

# 3. Abhängigkeiten installieren
pip install -r requirements.txt

# 4. Umgebungsvariablen konfigurieren
copy .env.example .env
# .env öffnen und HOST, PORT, API_KEY, MODEL eintragen

.env Konfiguration:

HOST=silicon.fhgr.ch
PORT=7080
API_KEY=EMPTY
MODEL=qwen3.5-35b-a3b

---

Starten

# Streamlit App (Hauptinterface)
streamlit run frontend/app.py

# Coding Agent direkt im Terminal testen
python run_agent.py

---

Projektstruktur

AISE_AIAgent/
├── frontend/               # Streamlit UI
├── backend/
│   ├── agent/              # Coding Agent + MCP-Adapter
│   │   └── servers/        # MCP-Server (Tools für den Agent)
│   └── managers/           # Business-Logik (Chat, Dateien, Ausführung)
├── workspace/              # Arbeitsverzeichnis des Agents & Editors
└── run_agent.py            # CLI-Test für den Coding Agent

---

Frontend

frontend/app.py — Einstiegspunkt

Initialisiert die Streamlit-App, setzt das Layout und routet zwischen Code-Editor und Chat-Ansicht basierend auf der Sidebar-Navigation.

frontend/state.py — Session State

Initialisiert alle Streamlit session_state-Variablen beim App-Start (offene Dateien, Chat-Verlauf, Agent-Status etc.). Verhindert KeyError beim ersten Laden.

frontend/sidebar.py — Sidebar & File Explorer

• Navigation: Radio-Button zum Wechseln zwischen "Code Editor" und "Chat with AI Assistant"
• File Tree: Interaktiver Dateibaum (via streamlit-arborist) zeigt den workspace/-Ordner
• Datei-Aktionen: Datei öffnen, umbenennen, löschen
• Ordner-Aktionen: Ordner erstellen, Dateien in Ordner hinzufügen, Ordner löschen

frontend/editor.py — Code-Editor

• Ace Editor: Syntax-Highlighting für Python, JS, HTML, CSS, JSON, YAML, LaTeX u.a.
• Tabs: Mehrere Dateien gleichzeitig offen, Tab-Wechsel per Klick
• Datei-Operationen: Speichern, Schliessen, Umbenennen, Löschen direkt im Tab
• Code ausführen: Button "▶ Run Code" führt die aktive Datei aus, Output wird darunter angezeigt
• Debug with AI: Bei Fehlern erscheint ein Button der den Fehler + Code automatisch an den AI-Chat weiterleitet

frontend/chat.py — Chat & Agent Mode

Normaler Chat (render_normal_chat):

• Multi-Turn Konversation mit dem konfigurierten LLM
• Injiziert die aktuell offene Datei automatisch als Kontext in den System-Prompt
• Einstellungen: Modell wählen, Max Tokens, eigener System-Prompt
• "Clear Chat" mit Bestätigungsdialog

Agent Mode (render_agent_mode):

• Autonomer Coding-Agent im Step-by-Step Modus
• Benutzer gibt eine Aufgabe ein, der Agent schlägt Aktionen vor
• Jede Aktion muss einzeln genehmigt (Approve) oder abgelehnt (Reject) werden
• Agent Log: Zeigt alle ausgeführten Schritte mit Tool, Gedanken und Resultat
• Follow-up: Nach Abschluss einer Aufgabe können Korrekturen eingegeben werden

---

Backend — Managers

backend/managers/chat_manager.py — ChatManager

Verwaltet den Konversationsverlauf und kommuniziert mit dem LLM über eine OpenAI-kompatible REST-API. Sendet bei jedem Request den gesamten Verlauf als Kontext mit.

Methode	Beschreibung
send_message(user_message)	Nachricht senden, Antwort zurückgeben, History updaten
add_message(role, content)	Nachricht manuell zur History hinzufügen
clear_history()	Gesamten Chat-Verlauf löschen
get_history()	Kopie des aktuellen Verlaufs zurückgeben

backend/managers/file_manager.py — FileManager

Alle Datei- und Ordneroperationen innerhalb des workspace/-Verzeichnisses. Jede Operation validiert den Pfad gegen Path-Traversal-Angriffe.

Methode	Beschreibung
create_file(relative_path, name)	Neue Datei im Workspace erstellen
create_folder(relative_path, name)	Neuen Ordner erstellen
read_file(path)	Dateiinhalt lesen
save_file(path, content)	Datei speichern/überschreiben
rename_file(old_path, new_name)	Datei umbenennen (Extension bleibt erhalten)
delete_file(relative_path)	Datei löschen
delete_folder(relative_path)	Ordner inkl. Inhalt löschen
get_file_tree()	Verschachteltes Dict des gesamten Workspace-Baums

backend/managers/execution_engine.py — ExecutionEngine

Führt Dateien aus dem Editor in einem Subprocess aus. Unterstützt Python (.py) und LaTeX (.tex). Timeout: 30 Sekunden.

Methode	Beschreibung
run_code(active_file)	Datei ausführen, gibt {stdout, stderr, rc} zurück

backend/managers/system_prompter.py — SystemPrompter

Generiert den System-Prompt für den AI-Chat. Wenn eine Datei im Editor offen ist, wird ihr Inhalt (max. 4000 Zeichen) automatisch eingebettet.

Methode	Beschreibung
generate_prompt(file_context)	System-Prompt mit optionalem Datei-Kontext bauen

backend/managers/debug_logger.py — DebugLogger

Einfacher In-Memory-Logger für den Code-Editor (Ausführungsstatus, Fehler).

---

Backend — Coding Agent

backend/agent/coding_agent.py — CodingAgent

Autonomer Agent nach dem Plan → Act → Observe → Fix → Done Loop. Kommuniziert mit dem LLM und ruft MCP-Tools über den Adapter auf.

Methode	Beschreibung
start_task(task)	Neue Aufgabe initialisieren, State zurücksetzen
propose_next_action()	LLM fragen was als nächstes zu tun ist (führt nichts aus)
approve()	Vorgeschlagene Aktion ausführen, nächsten Schritt vorschlagen
reject(feedback)	Aktion ablehnen, Feedback injizieren, Agent plant neu
follow_up(question)	Folgefrage nach abgeschlossener Aufgabe stellen

Hilfsfunktionen:

• dispatch_tool(tool_name, arguments) — Leitet Tool-Aufrufe an den MCP-Adapter weiter
• build_all_tool_description() — Generiert die Tool-Beschreibung für den System-Prompt
• extract_json(text) / _repair_json_strings(text) — Parst und repariert LLM-JSON-Antworten
• trim_messages(messages) — Kürzt alte History wenn Kontextfenster voll wird

backend/agent/mcp_server_adapter.py — MCPToolAdapter

Verbindet den Coding Agent mit den MCP-Servern. Liest die Konfiguration aus mcp_server_config.json, registriert alle verfügbaren Tools und startet bei jedem Tool-Aufruf eine frische stdio-Verbindung zum zuständigen Server.

Methode	Beschreibung
initialize_all_servers()	Alle Server verbinden und Tools registrieren
call_tool(tool_name, arguments)	Tool auf dem zuständigen Server aufrufen
get_all_tools()	Liste aller registrierten Tools zurückgeben

---

MCP-Server (Tools für den Agent)

Alle Server laufen als eigenständige Prozesse und kommunizieren über stdio.

backend/agent/servers/mcp_server_code_execution.py — CodeExecutionServer

Tool	Beschreibung
run_python_sandboxed(code)	Python-Code sicher ausführen (statische Analyse + Subprocess mit isoliertem stdin)
python_code_validation(code)	Syntax und Sicherheit prüfen ohne auszuführen
lint_code(code)	Statische Analyse mit pyflakes (ungenutzte Imports, undefinierte Variablen)
analyse_structure(code)	Struktur-Zusammenfassung (Klassen, Funktionen, Imports)

Sicherheitsmechanismen: Blockierte Imports (os, sys, subprocess etc.), blockierte Builtins (exec, eval, open etc.), verbotene Pfadsequenzen, Timeout nach 45 Sekunden.

backend/agent/servers/mcp_server_file_search.py — FileSearchServer

Tool	Beschreibung
list_files()	Alle Dateien im Workspace auflisten
get_file_tree(dir_path)	Verzeichnisbaum anzeigen
search_files(query)	Dateien nach Name oder Inhalt durchsuchen
read_file(path)	Dateiinhalt lesen
write_new_file(path, content)	Neue Datei erstellen (keine Überschreibung bestehender Dateien)
create_new_directory(path)	Neues Verzeichnis erstellen

Alle Zugriffe sind auf den workspace/-Ordner beschränkt (Path-Traversal-Schutz).

backend/agent/servers/mcp_server_web_search.py — WebSearchServer

Tool	Beschreibung
web_search(query, max_results)	DuckDuckGo-Suche, gibt formatierte Ergebnisse zurück
fetch_page(url)	Webseite abrufen und Text extrahieren (max. 4000 Zeichen)

SSRF-Schutz: Blockiert localhost, private IP-Ranges und nicht-HTTP/HTTPS-Schemata.

---

CLI-Test

run_agent.py ermöglicht den Coding Agent direkt im Terminal zu testen ohne die Streamlit-App zu starten:

python run_agent.py
# Aufgabe eingeben → Enter zum Genehmigen, Text zum Ablehnen, "stop" zum Abbrechen