# Generator API reference ## Hosting Run the ASP.NET Core .NET 10 project `PHI.Data.Generator/RLHF.Generator.Api`. Production requires: - the `RLHFGenerator` SQL Server connection string; - migrated database schema; - copied generator `Data` files; - LM Studio listening at the configured OpenAI-compatible endpoint. Swagger and Scalar are enabled only in the Development environment. ## Endpoints ### `GET /` Returns a small service status/identity response. Use it as a basic process health check; it does not prove database or LM Studio readiness. ### `POST /api/lm-studio/complete` Normalizes one supplied sentence or fragment without persistence. The request contract supports: - text/sentence; - required fragment flag; - optional protected subject; - optional protected medical term; - optional allowed medical forms; - optional requested tense. Validation rejects empty input, missing fragment status, invalid tense, inconsistent protected-term/forms metadata, and duplicate allowed forms. Successful output is the normalized plain-text line. ### `POST /api/keywords/load` Loads the category catalogs into `Keyword`/`KeywordVariant`. - additive; - case-insensitive; - idempotent; - does not backfill existing training items. ### `POST /api/training-items/backfill-keywords` Matches existing generated text to keywords. Query behavior includes a `dryRun` option and bounded batch processing. Only a unique match is assigned. Ambiguous and unmatched records remain null. ### `POST /api/generation/run` Starts a new compatible generation run or resumes an incomplete one. The HTTP request waits for generation and all persistence commits to complete; it does not merely enqueue background work. The response reports run identity/status and generation counts. Failures and cancellation update durable run state before surfacing the error. ### `POST /api/training-items/reset` Clears generated training items and generation checkpoints while preserving the seeded category rows. Treat this as destructive and restrict it operationally. ## Suggested invocation sequence ```powershell $base = "http://localhost:" Invoke-RestMethod -Method Post -Uri "$base/api/keywords/load" Invoke-RestMethod -Method Post -Uri "$base/api/generation/run" Invoke-RestMethod -Method Post -Uri "$base/api/training-items/backfill-keywords?dryRun=true" Invoke-RestMethod -Method Post -Uri "$base/api/training-items/backfill-keywords?dryRun=false" ``` Use the actual port shown by `dotnet run`/launch settings. ## Operational controls - Put authentication/authorization and network controls in front of the API; the tracked host does not define an application authorization policy. - Restrict reset and generation endpoints to operators. - Do not expose the configured SQL Server connection details or LM endpoint. - Monitor generation progress, LM failures, request duration, committed counts, and generation-run status. - Back up the database before reset or migration.