Zentrale AGENTS.md mit Architektur, Lern- und Bewertungsregeln, Schutz historischer Daten, Umgang mit Modellkosten und Grenzen produktiver Eingriffe. Verbindliche Prüfabläufe unterscheiden lokale Fixtures und echte Anbieterqualität. README, KI-Betriebsanleitung, Browser-Testhinweise und historische Flowise- Dokumentation beschreiben die direkte Modellanbindung, versionierte Kursbank und statistische Ausspracheplanung. Die Qualitäts-API dokumentiert nun beide Grammatik- und Schreibsuites mit ihren Kosten und begrenzter Aussagekraft. Projektkontext hält die Übergabe und erfolgreiche lokale Verifikation fest. Keine Schlüssel, Produktionsprofile oder personenbezogenen Aufnahmen enthalten.
198 lines
9.7 KiB
Markdown
198 lines
9.7 KiB
Markdown
> **Archiv:** Der aktuelle Arbeitsbaum verwendet direkte DeepSeek-/Mistral-Aufrufe. Neue Einrichtung: [docs/AI_OPERATIONS.md](../docs/AI_OPERATIONS.md). Die folgenden Flowise-Anleitungen gelten für den früheren Stand.
|
|
|
|
> **Aktueller adaptiver A1-Kurs (Vertrag v2):** Einrichtung und vollständige Prompts in [course-v2/README.md](course-v2/README.md). Der Aussprache-Flow bleibt separat. Die untenstehenden Kurs-v1-Prompts sind historisch und werden für die neue Kursansicht nicht verwendet.
|
|
|
|
# Flowise Setup
|
|
|
|
Flowise laeuft in Docker als Service `flowise` und ist vom Backend intern ueber `http://flowise:3000` erreichbar.
|
|
|
|
## MVP-Agent
|
|
|
|
Fuer Agentflow V2 nutze zuerst die konkrete Anleitung in
|
|
[`agentflow-v2-setup.md`](./agentflow-v2-setup.md). Sie passt zur aktuellen
|
|
Go-Backend-Anbindung, die Flowise mit `question` und `overrideConfig.sessionId` aufruft.
|
|
|
|
1. Flowise im Browser oeffnen: http://localhost:3000
|
|
2. Einen Chatflow oder Agentflow fuer `A1 English Teacher` erstellen.
|
|
3. Den System Prompt aus `prompts/a1_teacher_system.md` verwenden.
|
|
4. Den Chatflow speichern und die ID in `.env` setzen:
|
|
|
|
```bash
|
|
FLOWISE_CHATFLOW_ID=...
|
|
```
|
|
|
|
Fuer die naechste Uebung erwartet das Backend JSON-Antworten mit:
|
|
|
|
```json
|
|
{
|
|
"exercise_type": "repeat_sentence",
|
|
"target_language": "en-US",
|
|
"cefr_level": "A1",
|
|
"reference_text": "Hello, my name is Anna.",
|
|
"display_prompt": "Sprich den Satz klar nach.",
|
|
"tts_text": "Hello, my name is Anna.",
|
|
"focus_points": ["name"],
|
|
"success_criteria": ["accuracy above 80"],
|
|
"reason_for_choice": "Kurzer A1-Satz fuer klare Betonung."
|
|
}
|
|
```
|
|
|
|
Feedback und einfache Konversation laufen vorerst lokal im Backend. Wenn keine Chatflow-ID gesetzt
|
|
ist oder Flowise kein valides JSON liefert, nutzt die API Seed-Uebungen als Fallback.
|
|
|
|
## Archiv: zusätzliche Kursaufgaben, Vertrag v1
|
|
|
|
The course uses a **second** flow in the same instance. Keep the working
|
|
`FLOWISE_CHATFLOW_ID` pronunciation flow unchanged. Configure the new ID through
|
|
`FLOWISE_COURSE_CHATFLOW_ID`; optionally use `FLOWISE_COURSE_API_KEY` (otherwise
|
|
`FLOWISE_API_KEY` is used). Compose forwards both course variables to the API.
|
|
An empty course ID enables reviewed seed fallback.
|
|
|
|
Graph: **Start (Chat Input) → LLM → Direct Reply**. Enable Ephemeral Memory at
|
|
Start, disable LLM memory, and pass the incoming question to the LLM as its User
|
|
message. In the editor used for this project the input variable is `{{question}}`.
|
|
Direct Reply returns the LLM output without any surrounding text. Do not connect
|
|
DB, Azure, or other tools. Use JSON Structured Output where available; configure
|
|
field types, not fixed example values for module, skill, or learning goal.
|
|
|
|
System message:
|
|
|
|
```text
|
|
Du erzeugst genau eine zusätzliche A1-Englischaufgabe.
|
|
Modul und Lernziel kommen aus der JSON-Nutzernachricht.
|
|
Die Nutzernachricht enthält task="generate_course_task".
|
|
|
|
Gib ausschließlich ein JSON-Objekt mit diesen Pflichtfeldern zurück:
|
|
schema_version (Zahl), target_language, cefr_level, module_id,
|
|
learning_goal_id, skill, kind, prompt, options (Array aus drei Strings),
|
|
solution und explanation. Alle anderen Felder sind Strings.
|
|
Keine weiteren Felder, kein Markdown und keine Codeblöcke.
|
|
|
|
Übernimm schema_version, target_language, cefr_level, module_id,
|
|
skill und kind exakt aus der Eingabe.
|
|
learning_goal_id entspricht learning_goal.id.
|
|
Vergib keine eigene Aufgaben-ID und entscheide keinen Lernfortschritt.
|
|
|
|
Befolge learning_goal.description und learning_goal.prompt_template.
|
|
Ersetze ausschließlich die Platzhalter <Name> und <Ort> der Vorlage
|
|
mit einfachen Namen beziehungsweise Orten. Gib die Platzhalter nicht aus.
|
|
Verwende ausschließlich die drei Optionen aus learning_goal.allowed_forms,
|
|
in beliebiger Reihenfolge. Genau eine Option muss richtig sein.
|
|
solution muss exakt dieser Option entsprechen.
|
|
Vermeide alle Prompts in avoid_prompts und wähle andere Namen oder Orte.
|
|
|
|
Für vocabulary: Frage nach der Wortbedeutung im englischen Beispielsatz.
|
|
Die deutschen Optionen übersetzen ausschließlich das erfragte Wort.
|
|
Für grammar: Erzeuge den englischen Lückensatz mit deutscher Anweisung.
|
|
Erklärung immer Deutsch, kurz und fachlich passend.
|
|
Keine Bilder, Audioverweise oder externen Inhalte. Kein Markdown in Strings.
|
|
```
|
|
|
|
Example test input (the API constructs this context, not the browser):
|
|
|
|
```json
|
|
{
|
|
"task": "generate_course_task",
|
|
"schema_version": 1,
|
|
"target_language": "en-US",
|
|
"cefr_level": "A1",
|
|
"ui_language": "de-DE",
|
|
"module_id": "a1_introductions_v1",
|
|
"skill": "grammar",
|
|
"kind": "choice",
|
|
"learning_goal": {
|
|
"id": "introductions.be_i",
|
|
"description": "am nach I bei der Vorstellung mit Namen oder Herkunft verwenden",
|
|
"prompt_template": "Ergänze: I ___ from <Ort>.",
|
|
"allowed_forms": ["am", "is", "are"]
|
|
},
|
|
"learning_state": {
|
|
"goal_attempt_count": 0,
|
|
"goal_correct_count": 0,
|
|
"recent_results": []
|
|
},
|
|
"avoid_prompts": []
|
|
}
|
|
```
|
|
|
|
Each API request additionally includes explicit `rules` requiring the exact
|
|
`prompt_template` and the three `allowed_forms` strings. An invalid parsed or
|
|
validated response triggers at most one correction request with
|
|
`retry_instruction`; the same handler deadline of 25 seconds covers both calls.
|
|
HTTP/network errors go directly to fallback. Every correction is fully validated;
|
|
the raw rejected response is not sent back. Logs show
|
|
`course generation requesting correction` before the final selection.
|
|
|
|
The response contains `learning_goal_id`, not the nested `learning_goal` object,
|
|
and adds `prompt`, `options`, `solution`, and `explanation`. Transport uses
|
|
`POST /api/v1/prediction/{FLOWISE_COURSE_CHATFLOW_ID}` with the above JSON encoded
|
|
as a string in `question` and `streaming: false`. No personal identifiers,
|
|
recordings, or full answer histories are sent. Responses may be direct JSON or
|
|
wrapped in `json`, `text`, or `output`. Task JSON rejects unknown fields and trailing
|
|
content. One complete outer Markdown block (plain or `json`) is removed before
|
|
strict JSON parsing; surrounding prose and multiple blocks remain invalid; the HTTP response is limited to 64 KiB. Bold markers
|
|
in prompt/explanation are removed before validation because React renders text.
|
|
|
|
Version 1 deliberately accepts only four reviewed objectives in introductions:
|
|
`introductions.name`, `introductions.from`, `introductions.be_i`, and
|
|
`introductions.be_name`. Go validates sentence patterns, the three permitted
|
|
options, and the correct solution for each objective. Vocabulary contexts accept
|
|
equivalent greetings (e.g. `Hello, my name is Anna`), capitalization and common
|
|
quotation styles; the queried word and its reviewed meaning remain mandatory.
|
|
Origin contexts accept `I am`, `I'm`, `He is`, and `She is`.
|
|
Rejected tasks log a bounded public `prompt` under `course generation rejected`,
|
|
with reason, objective and generation attempt, without the solution or full
|
|
response. The `I am` objective also
|
|
accepts the reviewed self-introduction `I am a student`; short German choice
|
|
instructions and optional final periods do not change the objective. Arbitrary
|
|
English continuations (e.g. `I ___ like school`) are still rejected. Free-form explanations
|
|
are length/format checked, but their linguistic accuracy is not automatically
|
|
proven. New modules/objectives require reviewed server rules; editing only the
|
|
prompt does not enable them.
|
|
|
|
The API selects a goal last answered incorrectly first, then an unattempted
|
|
one, then an older one. Ties prefer the least recently used goal. Historic seed
|
|
attempts participate through fixed seed-ID mappings. `recent_results` contains
|
|
at most five results in chronological order; `avoid_prompts` includes the last
|
|
five generated prompts. This is practice selection, not a mastery calculation.
|
|
|
|
Authenticated course endpoints:
|
|
|
|
- `POST /course/modules/{id}/practice/next` with `{"request_id":"<UUID>"}`:
|
|
returns `{"task": <public CourseTask>, "source": "flowise" | "seed"}`.
|
|
Only Go selects the objective. Reusing a request ID returns the stored task.
|
|
- `GET /course/modules/{id}/practice`: up to 50 latest personal generated tasks.
|
|
- Existing `POST /course/tasks/{id}/attempts` with `{"answer":"<option>"}`:
|
|
checks the stored solution and returns feedback after submission.
|
|
|
|
Public tasks now include additive `source` metadata (`flowise` or `seed`).
|
|
The web task heading displays its origin, including tasks reopened from history.
|
|
Generated content is saved before delivery and is visible only to its owner.
|
|
Solutions stay out of task/list responses. The twelve core tasks and their
|
|
progress denominator remain unchanged. Generating a task never creates an
|
|
attempt. Missing config, invalid output, timeout (25 seconds), or save failure
|
|
selects the matching existing seed task. Logs show `course practice selected`
|
|
with `source`, task ID, and objective; fallback logs explain rejection without
|
|
logging the raw model response. A database outage is an error, not a success.
|
|
Fallback repeats the real core task: answering it contributes to that core
|
|
task's existing progress, without creating a thirteenth core task.
|
|
|
|
The startup schema upgrade adds provenance, owner, objective, request ID, and
|
|
prompt fingerprint columns without changing existing answers or seed IDs.
|
|
Unique indexes prevent duplicate requests and normalized generated prompts per
|
|
user. Repeated startup preserves both core attempts and generated tasks.
|
|
|
|
Validation:
|
|
|
|
```bash
|
|
cd apps/api
|
|
go test ./...
|
|
# Optional: dedicated disposable PostgreSQL test database (URL format).
|
|
# Creates and drops a random test schema; never reads the application .env.
|
|
COURSE_TEST_DATABASE_URL='postgres://test:test@localhost:5432/speech_test?sslmode=disable' go test ./internal/store -run TestCourseGenerationPostgres -v
|
|
```
|
|
|
|
Setting the environment variable alone does not update an already running API.
|
|
Deploying later requires rebuilding API and web, and recreating the API with
|
|
its updated environment. No deployment or restart is performed by these docs.
|