Models-Phi-8B/docs/api-reference.md

2.9 KiB

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

$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.