2.9 KiB
Generator API reference
Hosting
Run the ASP.NET Core .NET 10 project
PHI.Data.Generator/RLHF.Generator.Api. Production requires:
- the
RLHFGeneratorSQL Server connection string; - migrated database schema;
- copied generator
Datafiles; - 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
$base = "http://localhost:<port>"
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.