Projektregeln und Betriebsanleitung für Coding-Agenten dokumentieren
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.
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
> **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.
|
||||
@@ -35,3 +39,159 @@ Fuer die naechste Uebung erwartet das Backend JSON-Antworten mit:
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user