PHI-Model-8B/docs/api-reference.md

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.