Decision Models

Python SDK reference for decision models: methods create, decide, delete, get, list, update.

Methods on this page are called as client.decision_models.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Create a decision model

decision_models.create(*, display_name: str, endpoint_url: str, model_identifier: str, provider_type: DecisionModelProviderType, api_path: str = None, configuration: dict[str, Any] = None, credentials: EndpointAuthentication = None, decision_model_id: str = None, description: str = None, labels: dict[str, str] = None, monitoring_endpoint: str = None, owner_id: str = None, version: str = None) → DecisionModelResponse

Saves the connection settings for a decision model. Requires CREATE_DECISION_MODEL for the new model and its owner. You can register the same provider connection more than once, but each registration must have a unique UUID. Credentials are omitted from the response.

Parameters:

display_name (str) — Name shown in the console and CLI.
endpoint_url (str) — Base URL of the provider, starting with http:// or https://. Do not include a query string, fragment, or username and password.
model_identifier (str) — Model identifier accepted by the provider.
provider_type (DecisionModelProviderType) — Provider used by this model. This cannot be changed after creation.
api_path (str, optional) — Path appended to endpoint_url when sending a request. Jev and Laya use /v1/systemone if omitted. Clef requires the path for your account and model.
configuration (dict[str, Any], optional) — Provider settings. Supported keys are image_preview (Jev only), timeout_millis, and max_response_bytes. These settings cannot change which features the model supports.
credentials (EndpointAuthentication, optional) — API key for the provider, supplied in credentials.api_key.inline_secret with kind set to CREDENTIAL_KIND_API_KEY. May be omitted for Laya when the endpoint allows anonymous access.
decision_model_id (str, format: uuid, optional) — Optional UUID for the new model. GoodMem generates one if omitted. A UUID that is already in use returns 409; reusing connection settings is allowed.
description (str, optional) — Optional description.
labels (dict[str, str], optional) — Labels for filtering and organization.
monitoring_endpoint (str, optional) — Optional URL for the provider health or metrics endpoint. Must start with http:// or https://.
owner_id (str, format: uuid, optional) — UUID of the principal that will own the model. If omitted, the authenticated principal becomes the owner.
version (str, optional) — Optional version label.

Returns:

DecisionModelResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

model = client.decision_models.create(
    display_name="Doc decision model", provider_type="LAYA",
    endpoint_url="http://localhost:8000", model_identifier="laya",
    monitoring_endpoint="http://localhost:8000/health",
)

Get a decision model

decision_models.get(*, id: str, include_credentials: bool = None) → DecisionModelResponse

Returns the connection settings and supported features of a decision model. Requires READ_DECISION_MODEL. Set include_credentials=true to include stored credentials; this also requires READ_DECISION_MODEL_CREDENTIALS. Returns 404 if the model does not exist, or 403 if it exists but you lack permission.

Parameters:

id (str) — UUID of the decision model
include_credentials (bool, optional, server default=False) — Include stored credentials. Requires READ_DECISION_MODEL_CREDENTIALS in addition to READ_DECISION_MODEL.

Returns:

DecisionModelResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

model = client.decision_models.get(id=model.decision_model_id)

List decision models

decision_models.list(*, label: dict[str, str] = None, owner_id: str = None, page_size: int = None, page_token: str = None, provider_type: DecisionModelProviderType = None) → ListDecisionModelsResponse

Lists decision models that you have permission to read. Requires LIST_DECISION_MODEL for the instance and READ_DECISION_MODEL for each returned model. Results are ordered by creation time, newest first, with UUID descending to break ties. Credentials are omitted.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

Parameters:

label (dict[str, str], optional) — Filter by label key-value pairs. Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).
owner_id (str, optional) — Return only decision models owned by this principal UUID.
page_size (int, format: int32, optional, server default=50) — Maximum number of models to return, from 1 to 1000. Omit this parameter or use 0 for 50.
page_token (str, optional) — Use next_page_token from the previous response to request the next page. Keep the filters and page_size unchanged.
provider_type (DecisionModelProviderType, optional) — Return only decision models that use this provider.

Returns:

ListDecisionModelsResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

page = client.decision_models.list(provider_type="LAYA", page_size=20)
print(page.total_count, page.next_page_token)

Update a decision model

decision_models.update(*, id: str, request: UpdateDecisionModelRequest | dict) → DecisionModelResponse

Changes only the fields supplied in the request. Requires UPDATE_DECISION_MODEL. Send an empty string to clear description, version, or monitoring_endpoint. A supplied configuration replaces all existing settings; use {} to reset them to defaults. The provider and owner cannot be changed. Credentials are omitted from the response.

Parameters:

id (str) — The unique identifier of the resource to update.
request (UpdateDecisionModelRequest | dict) — The update payload. Accepts a UpdateDecisionModelRequest instance or a plain dict with the same fields. Only specified fields will be modified.

Returns:

DecisionModelResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

model = client.decision_models.update(
    id=model.decision_model_id, request={"displayName": "Updated decision model"},
)

Delete a decision model

decision_models.delete(*, id: str) → None

Removes the decision model from GoodMem. Requires DELETE_DECISION_MODEL. This does not contact or delete the model at the provider. Returns 404 if the registration has already been deleted.

Parameters:

id (str) — UUID of the decision model

Returns:

None

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

client.decision_models.delete(id=model.decision_model_id)

Request decisions from a model

decision_models.decide(*, id: str, request: DecisionRequest | dict) → DecisionResponse

Sends the supplied questions and content to the registered provider. Requires READ_DECISION_MODEL and EXECUTE_DECISION_MODEL. Each request calls the provider once and may incur charges, so do not retry automatically. GoodMem does not store the input or answers. Unsupported questions or media return 400. Problems with the stored provider credentials or settings return 412.

Parameters:

id (str) — UUID of the decision model
request (DecisionRequest | dict) — Request payload. Pass a DecisionRequest instance or a plain dict (validated automatically).

Returns:

DecisionResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.decision_models.decide(id=model.decision_model_id, request={
    "state": {"text": "The account has been verified."},
    "questions": {"verified": {
        "instructions": {"text": "Is the account verified?"},
        "noul": {},
    }},
})
print(result.answers["verified"].noul.probability_true)

Async usage: client.decision_models exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

DecisionModelProviderType

String enum: "JEV" · "LAYA" · "CLEF"

DecisionModelResponse

Connection settings and supported features of a registered decision model.

decision_model_id (str) — UUID of the decision model.
display_name (str) — Name shown in the console and CLI.
description (str, optional) — Optional description.
provider_type (DecisionModelProviderType | None) — Provider used by this model.
endpoint_url (str) — Provider base URL.
api_path (str) — Inference path appended to the base URL.
model_identifier (str) — Configured model identifier.
credentials (EndpointAuthentication, optional) — Stored credentials. Returned only by get when include_credentials=true and you have READ_DECISION_MODEL_CREDENTIALS permission.
configuration (dict[str, Any]) — Settings used when calling the provider. These do not change which features the model supports.
labels (dict[str, str]) — Labels for filtering and organization.
version (str, optional) — Optional version label.
monitoring_endpoint (str, optional) — Optional HTTP(S) health or metrics URL.
owner_id (str) — UUID of the principal that owns this model.
capabilities (DecisionModelCapabilities) — Supported questions and media, known limits, and the meaning of each answer type.
created_at (int) — Creation time in milliseconds since epoch.
updated_at (int) — Last update time in milliseconds since epoch.
created_by_id (str) — UUID of the principal or API key that created this model.
updated_by_id (str) — UUID of the principal or API key that last updated this model.

DecisionModelCapabilities

Supported features and known limits for this provider and model. An omitted limit is unknown; it does not mean unlimited.

question_types (list[str]) — Types of questions this model can answer.
media (list[DecisionMediaSupport]) — Supported media formats, placements and known limits.
limits (list[DecisionLimit]) — Known numeric limits.
context_bound_limits (list[str]) — Limits that depend on the provider context window instead of a fixed count.
semantics (list[DecisionQuestionSemantics]) — Meaning of the answer and confidence value for each question type.
input_overflow (Optional[Literal['REJECTS', 'TRUNCATES_STATE', 'TRUNCATES_STATE_AND_OPTIONS']]) — What the provider does when the input exceeds its context window.

DecisionMediaSupport

Media formats, placements and provider constraints.

kind (Optional[Literal['IMAGE', 'AUDIO', 'VIDEO']]) — Media category.
mime_types (list[str]) — Accepted MIME types.
placements (list[str]) — Allowed content positions.
limits (list[DecisionMediaLimit]) — Known limits for media. The provider checks dimensions and duration.

DecisionLimit

A known numeric limit.

type (Optional[Literal['MAX_QUESTIONS', 'MIN_CHOICES', 'MAX_CHOICES', 'MIN_SCORE_LEVELS', 'MAX_SCORE_LEVELS', 'MAX_TOTAL_OPTIONS', 'MAX_STATE_CHARACTERS', 'MAX_BODY_BYTES', 'MAX_CONTENT_DEPTH', 'MAX_INPUT_TOKENS', 'MAX_QUESTION_ID_CHARACTERS', 'MAX_AUDIO_VIDEO_BYTES']]) — Limit identifier.
value (int) — Known limit value.

DecisionQuestionSemantics

Meaning of the answer and confidence value for one question type.

question_type (Optional[Literal['CHOICE', 'SCORE', 'NOUL', 'BOX']]) — Question type.
confidence (Optional[Literal['ADJUSTED_TOP_PROBABILITY', 'NORMALIZED_ENTROPY_COMPLEMENT', 'TOP_PROBABILITY', 'ORDERED_MEAN_ABSOLUTE_DEVIATION', 'PROVIDER_DEFINED', 'NOT_REPORTED']]) — How to interpret the confidence value reported by the provider.
output (Optional[Literal['CANDIDATE_IDENTIFIER', 'EXPECTED_ZERO_BASED_LEVEL', 'PROBABILITY_TRUE', 'NORMALIZED_EDGES_NO_ABSENCE_SENTINEL']]) — Meaning of the primary answer value.

DecisionMediaLimit

A known media limit.

type (Optional[Literal['MAX_ITEMS', 'MAX_ITEM_BYTES', 'MAX_TOTAL_BYTES', 'MAX_PIXELS', 'MIN_WIDTH', 'MAX_WIDTH', 'MIN_HEIGHT', 'MAX_HEIGHT', 'MIN_PIXELS', 'MAX_DURATION_MILLIS']]) — Media limit identifier.
value (int) — Known limit value.

ListDecisionModelsResponse

One page of decision models that you have permission to read.

decision_models (list[DecisionModelResponse]) — Decision models ordered by creation time, newest first, with UUID descending to break ties.
next_page_token (str, optional) — Token to pass as page_token in the next request. Omitted when there are no more results.
total_count (int) — Total number of models that match the filters and that you have permission to read, across all pages.

UpdateDecisionModelRequest

Changes only the supplied fields. Omitted fields keep their current values. A supplied configuration replaces all existing provider settings.

display_name (str, optional) — Name shown in the console and CLI.
description (str, optional) — Description of the model. Send an empty string to clear it, or omit it to keep the current value.
endpoint_url (str, optional) — Base URL of the provider, starting with http:// or https://. Do not include a query string, fragment, or username and password.
api_path (str, optional) — Path appended to endpoint_url when sending a request. Omit it to keep the current path. An empty string resets Jev and Laya to /v1/systemone; Clef requires the path for your account and model.
model_identifier (str, optional) — Model identifier accepted by the provider.
credentials (EndpointAuthentication, optional) — Replacement API key for the provider, supplied in credentials.api_key.inline_secret with kind set to CREDENTIAL_KIND_API_KEY. Omit credentials to keep the current key.
configuration (dict[str, Any], optional) — Replacement provider settings. Supported keys are image_preview (Jev only), timeout_millis, and max_response_bytes. Send {} to reset all settings to defaults, or omit configuration to keep the current settings.
version (str, optional) — Version label. Send an empty string to clear it, or omit it to keep the current value.
monitoring_endpoint (str, optional) — URL for the provider health or metrics endpoint. Must start with http:// or https://. Send an empty string to clear it, or omit it to keep the current value.
replace_labels (dict[str, str], optional) — Replace all labels with this map. Send {} to remove all labels. Do not combine with merge_labels.
merge_labels (dict[str, str], optional) — Add labels and replace the values of matching keys. Other labels are unchanged. Do not combine with replace_labels.

DecisionRequest

Sends named questions and content to a registered decision model. The provider may charge for this request.

state (DecisionContent) — Content evaluated by all questions.
attachments (list[DecisionMedia], optional) — Media files included with the request. Their order is preserved within each media type.
questions (dict[str, DecisionQuestion]) — Questions keyed by names that you choose. The model must support each question type and its media.

DecisionContent

Set exactly one of text, json_value, object_value, array_value, or media. Use text for ordinary text. Use json_value to preserve a complete JSON value, including the exact precision of its numbers.

json_value (str, optional) — A complete JSON value encoded as a string. For example, {"json_value":"null"} represents JSON null. For ordinary text, use the text field.
text (str, optional) — Ordinary text without JSON quoting.
object_value (DecisionObject, optional) — Object whose fields can contain nested media.
array_value (DecisionArray, optional) — Ordered array whose elements can contain nested media.
media (DecisionMedia, optional) — Media file included in the request. GoodMem does not download media from URLs.

DecisionMedia

Media file included in the request. The provider and model determine which formats and sizes are supported.

kind (Optional[Literal['IMAGE', 'AUDIO', 'VIDEO']]) — Media category.
mime_type (str) — Declared MIME type.
data (bytes) — Base64-encoded file bytes.

DecisionQuestion

Set exactly one of choice, score, noul, or box. Clef requires instructions for every question.

instructions (DecisionContent, optional) — Instructions for this question. Clef requires nonblank text, an object, or an array. Other providers allow omission; to supply JSON null, use {"json_value":"null"}.
choice (DecisionChoiceQuestion, optional) — Choose one labeled option.
score (DecisionScoreQuestion, optional) — Score the content against a list of levels ordered from lowest to highest.
noul (DecisionNoulQuestion, optional) — Estimate the probability that a statement is true.
box (DecisionBoxQuestion, optional) — Locate an object in an image. A returned box does not guarantee that the object is present.

DecisionObject

Named decision content fields.

fields (dict[str, DecisionContent]) — Content keyed by field name.

DecisionArray

Ordered decision content elements.

values (list[DecisionContent]) — Ordered content elements.

DecisionChoiceQuestion

Choice options.

options (dict[str, DecisionContent]) — Option identifiers and descriptions.

DecisionScoreQuestion

Ordered rubric levels.

levels (list[DecisionContent]) — Descriptions of the score levels, ordered from lowest to highest. The first level has index 0.

DecisionNoulQuestion

Optional true and false descriptions.

true_criterion (DecisionContent, optional) — Description of the true outcome.
false_criterion (DecisionContent, optional) — Description of the false outcome.

DecisionBoxQuestion

Locate an object in an image. Use instructions to describe the object.

No parameters.

DecisionResponse

Structured provider answers with reported usage.

model (str) — Provider-reported model identifier.
answers (dict[str, DecisionAnswer]) — Answers keyed by the original question identifiers.
usage (DecisionUsage) — Token counts reported by the provider. An omitted count is unknown; a count of 0 means the provider reported zero.

DecisionAnswer

Answer to one question. Exactly one of choice, score, noul, or box is present.

choice (DecisionChoiceAnswer, optional) — Selected option and the probability assigned to each option.
score (DecisionScoreAnswer, optional) — Score and the probability assigned to each score level.
noul (DecisionNoulAnswer, optional) — Probability that the statement is true.
box (DecisionBoxAnswer, optional) — Normalized image coordinates.

DecisionUsage

Token usage reported by the provider. Counts are omitted when unknown.

input_tokens (int, optional) — Reported input tokens.
output_tokens (int, optional) — Reported output tokens.

DecisionChoiceAnswer

Selected option and probability distribution.

choice (str) — Selected option identifier.
probabilities (dict[str, float]) — Probability for every option.
confidence (float, optional) — Confidence reported by the provider. This is not a calibrated probability that the answer is correct.
confidence_meaning (Optional[Literal['ADJUSTED_TOP_PROBABILITY', 'NORMALIZED_ENTROPY_COMPLEMENT', 'TOP_PROBABILITY', 'ORDERED_MEAN_ABSOLUTE_DEVIATION', 'PROVIDER_DEFINED', 'NOT_REPORTED']]) — Interpretation of confidence.

DecisionScoreAnswer

Expected zero-based rubric level; not a percentage.

score (float) — Score on the scale defined by levels. The first level has value 0, and fractional values fall between levels.
probabilities (dict[str, float]) — Probability assigned to each level, using its index starting at 0.
levels (list[DecisionContent]) — Original caller rubric, including structured content and media.
confidence (float, optional) — Confidence reported by the provider. This is not a calibrated probability that the answer is correct.
confidence_meaning (Optional[Literal['ADJUSTED_TOP_PROBABILITY', 'NORMALIZED_ENTROPY_COMPLEMENT', 'TOP_PROBABILITY', 'ORDERED_MEAN_ABSOLUTE_DEVIATION', 'PROVIDER_DEFINED', 'NOT_REPORTED']]) — Interpretation of confidence.

DecisionNoulAnswer

Probability that the proposition is true.

probability_true (float) — Probability that the statement is true. Your application decides what threshold to use.

DecisionBoxAnswer

Rectangle with coordinates expressed as fractions of the image width or height. A returned box does not guarantee that the object is present.

left (float) — Left edge as a fraction of image width.
top (float) — Top edge as a fraction of image height.
right (float) — Right edge as a fraction of image width.
bottom (float) — Bottom edge as a fraction of image height.
confidence (float, optional) — Optional provider confidence.

On this page