LLMs

Methods on this page are called as client.llms.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.LlmsAPI (extends internal LlmsAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.llms.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncLlmsAPI (accessed via asyncClient.llms on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.llms.<method>(...)  // returns CompletableFuture<T>
}

Method Detail

`create(LLMCreationRequest)`

CreateLLMResponse create(LLMCreationRequest request)

Creates a new LLM configuration for text generation services. LLMs represent connections to different language model API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them for text generation. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another LLM exists with identical {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, credentialsFingerprint} after URL canonicalization. Uniqueness is enforced per-owner. Credentials are hashed (SHA-256) for uniqueness while remaining encrypted. The apiPath field defaults to '/chat/completions' if omitted. Requires CREATE_LLM_OWN permission (or CREATE_LLM_ANY for admin users).

Convenience override: applies declarative transforms (registry lookup / endpoint inference / default injection / credential check as declared in convenience.json) before forwarding to the raw Tier-2 request. Any field already set on request wins over registry values.

HTTP — POST /v1/llms

Parameters

request (LLMCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — CreateLLMResponse

Example

CreateLLMResponse createLLMResponse = client.llms.create(LLMCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/llms' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc LLM",
    "modelIdentifier": "gpt-4o-mini",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "sk-..."
      }
    },
    "providerType": "OPENAI",
    "supportedModalities": [
      "TEXT",
      "IMAGE",
      "AUDIO"
    ],
    "maxContextLength": 128000,
    "endpointUrl": "https://api.openai.com/v1"
  }'

`create(LLMCreationRequest, String)`

CreateLLMResponse create(LLMCreationRequest request, String apiKey)

Convenience overload: auto-fills provider / endpoint / dimensionality from the bundled model registry keyed by modelIdentifier, and converts a bare apiKey string to the structured EndpointAuthentication. Pass null for apiKey to preserve request.credentials(). Any field already set on request wins over registry values.

HTTP — POST /v1/llms

Parameters

request (LLMCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.
apiKey (String, optional) — bare API key for the upstream provider. Converted to EndpointAuthentication via Transforms.apiKeyToCredentials. Pass null to preserve request.credentials().

Returns — CreateLLMResponse

Example

CreateLLMResponse createLLMResponse = client.llms.create(LLMCreationRequest.builder()
            // …set required fields…
            .build(), "<provider-api-key>");

REST equivalent

curl -X POST 'http://localhost:8080/v1/llms' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc LLM",
    "modelIdentifier": "gpt-4o-mini",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "sk-..."
      }
    },
    "providerType": "OPENAI",
    "supportedModalities": [
      "TEXT",
      "IMAGE",
      "AUDIO"
    ],
    "maxContextLength": 128000,
    "endpointUrl": "https://api.openai.com/v1"
  }'

`delete(String)`

void delete(String id)

Permanently deletes an LLM configuration. This operation cannot be undone and removes the LLM record and securely deletes stored credentials. IMPORTANT: This does NOT invalidate or delete any previously generated content using this LLM - existing generations remain accessible. Requires DELETE_LLM_OWN permission for LLMs you own (or DELETE_LLM_ANY for admin users).

HTTP — DELETE /v1/llms/{id}

Parameters

id (String) — The unique identifier of the LLM to delete

Returns — None (HTTP 204).

Example

client.llms.delete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/llms/{id}' \
  -H "x-api-key: gm_..."

`get(String)`

LLMResponse get(String id)

Retrieves the details of a specific LLM configuration by its unique identifier. Requires READ_LLM_OWN permission for LLMs you own (or READ_LLM_ANY for admin users to view any user's LLMs). This is a read-only operation with no side effects.

HTTP — GET /v1/llms/{id}

Parameters

id (String) — The unique identifier of the LLM to retrieve

Returns — LLMResponse

Example

LLMResponse lLMResponse = client.llms.get("...");

REST equivalent

curl -X GET 'http://localhost:8080/v1/llms/{id}' \
  -H "x-api-key: gm_..."

`list(LLMListOptions)`

List<LLMResponse> list(LLMListOptions options)

Retrieves a list of LLM configurations accessible to the caller, with optional filtering. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production). PERMISSION-BASED FILTERING: With LIST_LLM_OWN permission, you can only see your own LLMs (ownerId filter is ignored if set to another user). With LIST_LLM_ANY permission, you can see all LLMs or filter by any ownerId. This is a read-only operation with no side effects.

HTTP — GET /v1/llms

Parameters

options (LLMListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — List``<LLMResponse>

Example

List<LLMResponse> list = client.llms.list(LLMListOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/llms' \
  -H "x-api-key: gm_..."

`update(String, LLMUpdateRequest)`

LLMResponse update(String id, LLMUpdateRequest request)

Updates an existing LLM configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated. SUPPORTED_MODALITIES UPDATE: If the array contains >=1 elements, it replaces the stored set; if empty or omitted, no change occurs and it does not count as an update by itself. IMPORTANT: providerType is IMMUTABLE after creation and cannot be changed. Requires UPDATE_LLM_OWN permission for LLMs you own (or UPDATE_LLM_ANY for admin users).

HTTP — PUT /v1/llms/{id}

Parameters

id (String) — The unique identifier of the LLM to update
request (LLMUpdateRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — LLMResponse

Example

LLMResponse lLMResponse = client.llms.update("...", LLMUpdateRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/llms/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc LLM (updated)",
    "mergeLabels": {
      "version": "2"
    }
  }'

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

LLMs

On this page