Model Object

This page describes the Model object returned by the SDK and shows how to retrieve a model by ID or name in Go and Python.

Fields

The Model object contains the following data:

Data	Description	Data Type
ID	Model identifier	Integer
Name	Model name	String
Type	Type of model	String
Script	Model source code and language syntax	Structure
Parameters	Model parameters (one of Constant or Map)	Structure
Structured	Structured model definition (if any)	Structure
From	Where to start in transition matrix	String
To	Where to end in transition matrix	String
Filter	Filter definition (if any)	String
FilterSQL	Filter SQL expression (if any)	String
Series	Supporting series (e.g., docs/equations)	Structure
Comment	Comment text	Structure
Version	Version number	Integer
Desc	Description	String
LOB	Line of business	String
InternalID	Internal identifier	String
Processed	Last processed timestamp	DateTime
Created	Created timestamp	DateTime
UserName	Name of the user	String
UserID	ID of the user	String
UserEmail	Email of the user	String
CreatedUserName	Name of the creating user	String
UserPlaypen	Playpen ID	Integer
MetaTags	Tags attached to the model	Map
ExcelFile	Attached Excel binary (if any)	Bytes
Structured	Structured model definition (if any)	Structure

Parameters

Parameters are represented as a one-of structure:

• Constant: single numeric value with a name.
• Map: map of parameter names to numeric values.

Reading a Model by ID

A single model can be retrieved by passing its unique numeric identifier to ReadModelByID in Go or model.get in Python.

Example: Go

u.ReadModelByID is a convenience wrapper that calls sdkClient.BuildModelByID. It fetches the model and compiles it into a runnable plugin under SrcRoot.

mod, err := u.ReadModelByID(4)
if err != nil {
    log.Fatal(err)
}

input := map[string]interface{}{"Segment": 1.0}
output, err := mod.Model(input)
if err != nil {
    log.Fatal(err)
}
log.Println(output["pd"]) // Example of accessing a model output field

Note

u.ReadModelByID internally calls BuildModelByID, which compiles the model into a Go plugin under <SrcRoot>/src in a temporary directory.

If lower-level SDK access is desired, retrieve the model definition (source only):

resp, err := sdkClient.ReadModelByID(4) // returns *sdk.ReadModelByIDOutput
if err != nil {
    log.Fatal(err)
}
modelDef := resp.GetModel() // definition, parameters, and script

Example: Python

from sdk import model

result = model.get(4)

>>> result.name
Simple Go Model

>>> result.type
PD_SEGMENT

>>> result.script[0].syntax
go

Reading a Model by Name

A model can also be retrieved by its name and playpen ID using ReadModelByName in Go or model.get_by_name in Python.

Example: Go

resp, err := sdkClient.ReadModelByName(1, "Simple Go Model") // playpenID, name
if err != nil {
    log.Fatal(err)
}
modelDef := resp.GetModel()

Example: Python

from sdk import model

result = model.get_by_name("Simple Go Model", playpen_id=1)

>>> result.name
Simple Go Model

>>> result.id
4

Excel File

When a model has an attached Excel file, the ExcelFile field contains the raw binary content of the .xlsx workbook. This can be saved to disk or parsed in-memory.

Saving to Disk

Go

resp, err := sdkClient.ReadModelByID(4)
if err != nil {
    log.Fatal(err)
}
excelBytes := resp.GetModel().GetExcelFile()
if len(excelBytes) > 0 {
    err = os.WriteFile("model_excel.xlsx", excelBytes, 0644)
    if err != nil {
        log.Fatal(err)
    }
}

Python

from sdk import model

result = model.get(4)
if result.excel_file:
    with open("model_excel.xlsx", "wb") as f:
        f.write(result.excel_file)

Parsing In-Memory

The bytes can also be parsed directly without writing to disk.

Go

import (
    "bytes"

    log "github.com/sirupsen/logrus"
    "github.com/xuri/excelize/v2"
)

resp, err := sdkClient.ReadModelByID(4)
if err != nil {
    log.Fatal(err)
}
excelBytes := resp.GetModel().GetExcelFile()
if len(excelBytes) > 0 {
    reader := bytes.NewReader(excelBytes)
    f, err := excelize.OpenReader(reader)
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()
    rows, err := f.GetRows("Sheet1")
    if err != nil {
        log.Fatal(err)
    }
    for _, row := range rows {
        log.Println(row)
    }
}

Python

from io import BytesIO
import pandas as pd
from sdk import model

result = model.get(4)
if result.excel_file:
    buf = BytesIO(result.excel_file)
    df = pd.read_excel(buf, sheet_name="Sheet1", engine="openpyxl")
    print(df)

Structured Model

When a model is defined using structured mode (see Structured Models), the Structured field contains the full regression definition. This field is nil/None for freeform models.

The structure is nested as follows:

• StructuredModel — Polymorphic container with a Type discriminator
  • RegressionModel — The regression definition
    • FunctionName — Function type (Regression)
    • NormalizationMethod — None, Logit, or Probit
    • DependentVariable — Target dictionary variable ID
    • DependentVariableName — Target variable name (read-only)
    • RegressionTable — Intercept and predictors
      • Intercept — Baseline constant (β₀)
      • NumericPredictor[] — List of predictors
        • Coefficient — Weight (βᵢ)
        • Exponent — Power (eᵢ)
        • FieldReference — Data source (one of the types below)
    • LocalTransformationFieldReference[] — Computed fields with formulas
    • LookupFieldReference[] — Conditional field selection

FieldReference is a polymorphic type that can be one of:

• FactorReference — Links to a risk factor (ID and name)
• DictionaryReference — Links to a dictionary column (ID and name)
• LocalTransformationFieldReference — Computed field with a formula
• LookupFieldReference — Conditional field selection via a selector

Go

resp, err := sdkClient.ReadModelByID(4)
if err != nil {
    log.Fatal(err)
}
modelDef := resp.GetModel()

// Check if the model has a structured definition
if s := modelDef.GetStructured(); s != nil {
    reg := s.GetRegressionModel()
    table := reg.GetRegressionTable()

    log.Printf("Intercept: %f", table.GetIntercept())
    log.Printf("Normalization: %v", reg.GetNormalizationMethod())

    for _, p := range table.GetPredictors() {
        log.Printf("Predictor: coeff=%f, exp=%d", p.GetCoefficient(), p.GetExponent())

        switch ref := p.GetField().GetFieldType().(type) {
        case *sdk.FieldReference_FactorReference:
            log.Printf("  Factor: %s", ref.FactorReference.GetFactorName())
        case *sdk.FieldReference_DictionaryReference:
            log.Printf("  Dictionary: %s", ref.DictionaryReference.GetDictionaryName())
        case *sdk.FieldReference_LocalTransformation:
            log.Printf("  Local: %s = %s", ref.LocalTransformation.GetName(), ref.LocalTransformation.GetFormula())
        case *sdk.FieldReference_Lookup:
            log.Printf("  Lookup: selector=%s", ref.Lookup.GetSelectorName())
        }
    }
}

Python

from sdk import model as sdk_model

result = sdk_model.get(4)

# Check if the model has a structured definition
if result.structured and result.structured.regression_model:
    reg = result.structured.regression_model
    table = reg.regression_table

    print(f"Intercept: {table.intercept}")
    print(f"Normalization: {reg.normalization_method}")

    for p in table.predictors:
        print(f"Predictor: coeff={p.coefficient}, exp={p.exponent}")

        field = p.field
        if field.HasField("factor_reference"):
            print(f"  Factor: {field.factor_reference.factor_name}")
        elif field.HasField("dictionary_reference"):
            print(f"  Dictionary: {field.dictionary_reference.dictionary_name}")
        elif field.HasField("local_transformation"):
            lt = field.local_transformation
            print(f"  Local: {lt.name} = {lt.formula}")
        elif field.HasField("lookup"):
            print(f"  Lookup: selector={field.lookup.selector_name}")