91 lines
2.9 KiB
Markdown
91 lines
2.9 KiB
Markdown
# 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:<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.
|