Catalog

Modules concerning the catalog to manage and load prompt builders used in Gen AI applications.

`LMInvokerCatalog`

Bases: BaseCatalog[BaseLMInvoker]

Loads multiple LM invokers from certain sources.

Attributes:

Name	Type	Description
`components`	`dict[str, BaseLMInvoker]`	Dictionary of the loaded LM invokers.
`prompt_builder_names`	`dict[str, str]`	Maps invoker names to their explicitly assigned prompt builder names.

Initialization

Example 1: Load from Google Sheets using client email and private key

catalog = LMInvokerCatalog.from_gsheets(
    sheet_id="...",
    worksheet_id="...",
    client_email="...",
    private_key="...",
)

lm_invoker = catalog.name

Example 2: Load from CSV

catalog = LMInvokerCatalog.from_csv(csv_path="...")
lm_invoker = catalog.name

Example 3: Load from record/JSON file

import json

records = [
    {
        "name": "answer_question",
        "model_id": "openai/gpt-5-nano",
        "credentials": "OPENAI_API_KEY",
        "config": "{}",
        "system_template": "You are a helpful assistant.",
        "user_template": "{query}",
        "prompt_builder_kwargs": json.dumps({"use_jinja": True}),
    }
]

catalog = LMInvokerCatalog.from_records(records=records)
lm_invoker = catalog.answer_question

Template Example

For template examples compatible with LMInvokerCatalog, refer to: 1. CSV: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/lm_invoker_catalog_template.csv 2. JSON: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/lm_invoker_catalog_template.json

Template Explanation

Required columns: 1. name (str): The name of the LM invoker. 2. model_id (str): The model ID of the LM invoker. 3. credentials (str | json_str | dict): The credentials of the LM invoker. Supported prefixes: - env:ENV_VAR_KEY (load from environment variable) - raw: (use raw value directly) Legacy unprefixed values are still treated as environment variable names for backward compatibility. A dictionary of credentials is also supported, where each value is either env:..., raw:..., or a legacy unprefixed environment variable name (e.g. {"api_key": "env:OPENAI_API_KEY"}). Currently supported for providers requiring dictionary credentials (e.g. Bedrock, LangChain). 4. config (json_str): Additional configuration for the LM invoker. String values using the obj: prefix are resolved from the objects registry passed to from_records, from_csv, or from_gsheets.

Optional prompt-builder columns: 1. system_template (str): The system template used for lm_invoker.prompt.build(...). 2. user_template (str): The user template used for lm_invoker.prompt.build(...). 3. prompt_builder_kwargs (json_str): Additional prompt builder kwargs. 4. prompt_builder_name (str): A named builder resolved later with apply_prompt_selection(...).

Important Notes: 1. If any prompt-builder input has a non-empty value, the invoker will call build_lm_invoker(...).prompt.build(...). 2. If no prompt-builder input has a non-empty value, the invoker is created using only build_lm_invoker(...). 3. The model_id can load environment variables using "${ENV_VAR_KEY}" syntax. 4. prompt_builder_name cannot be combined with inline prompt-builder inputs. 5. credentials and config are optional in value; empty values use default invoker behavior.

`apply_prompt_selection(prompt_builder_catalog, prompt_selection=None)`

Attaches named prompt builders to promptless invokers using fixed selection precedence.

Explicit record references take precedence over exact model-ID mappings, provider mappings, and the default. Invokers that already have a prompt builder are left unchanged.

Parameters:

Name	Type	Description	Default
`prompt_builder_catalog`	`PromptBuilderCatalog`	Catalog that supplies named prompt builders.	required
`prompt_selection`	`PromptSelectionConfig \| dict[str, Any] \| None`	Model-ID, provider, and default selection mappings. A dictionary is validated as `PromptSelectionConfig`. Defaults to None.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	This catalog after attaching selected prompt builders in place.

`LMRequestProcessorCatalog`

Bases: BaseCatalog[LMRequestProcessor]

Loads multiple LM request processors from certain sources.

Attributes:

Name	Type	Description
`components`	`dict[str, LMRequestProcessor]`	Dictionary of the loaded LM request processors.

Initialization

Example 1: Load from Google Sheets using client email and private key

catalog = LMRequestProcessorCatalog.from_gsheets(
    sheet_id="...",
    worksheet_id="...",
    client_email="...",
    private_key="...",
)

lm_request_processor = catalog.name

Example 2: Load from Google Sheets using credential file

catalog = LMRequestProcessorCatalog.from_gsheets(
    sheet_id="...",
    worksheet_id="...",
    credential_file_path="...",
)

lm_request_processor = catalog.name

Example 3: Load from CSV

catalog = LMRequestProcessorCatalog.from_csv(csv_path="...")

lm_request_processor = catalog.name

Example 4: Load from record/JSON file

import json

records=[
    {
        "name": "answer_question",
        "model_id": "openai/gpt-5-nano",
        "credentials": "OPENAI_API_KEY",
        "config": '{"thinking": {"enabled": true, "kwargs": {"effort": "high"}}}',
        "system_template": (
            "You are helpful assistant.\n"
            "Answer the following question based on the provided context.\n"
            "```{context}```"
        ),
        "user_template": "{query}",
        "prompt_builder_kwargs": json.dumps({
            "key_defaults": {"context": "<default context>"},
            "use_jinja": True,
            "jinja_env": "restricted",
            "history_formatter": {
                "prefix_user_message": "Q: ",
                "suffix_user_message": "\n",
                "prefix_assistant_message": "A: ",
                "suffix_assistant_message": "\n",
            }
        }),
    },
]

# or load the records from a JSON file
records = json.load(open("path/to/records.json"))

catalog = LMRequestProcessorCatalog.from_records(records=records)
lm_request_processor = catalog.answer_question

Template Example

For template examples compatible with LMRequestProcessorCatalog, refer to: 1. CSV: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/lm_request_processor_catalog_template.csv 2. JSON: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/lm_request_processor_catalog_template.json

Template Explanation

The required columns are: 1. name (str): The name of the LM request processor. 2. model_id (str): The model ID of the LM invoker. 3. credentials (str | json_str): The credentials of the LM invoker. 4. config (json_str): The additional configuration of the LM invoker. 5. system_template (str): The system template of the prompt builder. 6. user_template (str): The user template of the prompt builder. 7. prompt_builder_kwargs (json_str): Additional configuration for the prompt builder.

Important Notes: 1. At least one of system_template or user_template must be filled. 2. The model_id: 2.1. Must be filled with the model ID of the LM invoker, e.g. "openai/gpt-5-nano". 2.2. Can be partially loaded from the environment variable using the "${ENV_VAR_KEY}" syntax, e.g. "azure-openai/${AZURE_ENDPOINT}/${AZURE_DEPLOYMENT}". 2.3. For the available model ID formats, see: https://gdplabs.gitbook.io/sdk/resources/supported-models 3. credentials is optional. If it is filled, it can either be: 3.1. A prefixed env var reference (e.g. env:OPENAI_API_KEY). 3.2. A prefixed raw credential value (e.g. raw:sk-...). 3.3. A dictionary of credentials where each value is either env:..., raw:..., or a legacy unprefixed environment variable name (e.g. {"api_key": "env:OPENAI_API_KEY"}). Currently supported for providers requiring dictionary credentials (e.g. Bedrock, LangChain). Legacy unprefixed non-JSON values are still treated as environment variable names. If it is empty, the LM invoker will use the default credentials loaded from the environment variables. 4. config is optional. If filled, must be a dictionary containing the configuration for the LM invoker. If it is empty, the LM invoker will use the default configuration. String values using the obj: prefix are resolved from the objects registry passed via the objects parameter.

`PromptBuilderCatalog`

Bases: BaseCatalog[PromptBuilder]

Loads multiple prompt builders from certain sources.

Attributes:

Name	Type	Description
`components`	`dict[str, PromptBuilder]`	Dictionary of the loaded prompt builders.

Initialization

Example 1: Load from Google Sheets using client email and private key

catalog = PromptBuilderCatalog.from_gsheets(
    sheet_id="...",
    worksheet_id="...",
    client_email="...",
    private_key="...",
)
prompt_builder = catalog.name

Example 2: Load from Google Sheets using credential file

catalog = PromptBuilderCatalog.from_gsheets(
    sheet_id="...",
    worksheet_id="...",
    credential_file_path="...",
)
prompt_builder = catalog.name

Example 3: Load from CSV

catalog = PromptBuilderCatalog.from_csv(csv_path="...")
prompt_builder = catalog.name

Example 4: Load from records/JSON file

records=[
    {
        "name": "answer_question",
        "system": (
            "You are helpful assistant.\n"
            "Answer the following question based on the provided context.\n"
            "```{context}```"
        ),
        "user": "{query}",
        "kwargs": json.dumps({
            "key_defaults": {"context": "<default context>"},
            "use_jinja": True,
            "jinja_env": "restricted"
        }),
    },
]

# or load the records from a JSON file
records = json.load(open("path/to/records.json"))

catalog = PromptBuilderCatalog.from_records(records=records)
prompt_builder = catalog.answer_question

Template Example:

For template examples compatible with PromptBuilderCatalog, refer to:

    1. CSV: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/prompt_builder_catalog_template.csv
    2. JSON: https://github.com/GDP-ADMIN/gl-sdk/tree/main/libs/gllm-inference/gllm_inference/resources/catalog/prompt_builder_catalog_template.json

Template Explanation:

The required columns are:

    1. name (str): The name of the prompt builder.
    2. system (str): The system template of the prompt builder.
    3. user (str): The user template of the prompt builder.
    4. kwargs (json_str): Additional configuration for the prompt builder.

Important Notes:

    1. At least one of the `system` or `user` columns must be filled.