Data Models¶

The classes below validate the experiment configuration. Their attributes are the keys of the configuration, see the Configuration Reference for how to use them.

Questionnaire¶

rupsycho.models.questionnaire ¶

Questionnaire ¶

Represents a questionnaire used in a psychological test.

ATTRIBUTE	DESCRIPTION
`name`	The name of the questionnaire. TYPE: `str`
`general_instruction`	General instructions provided to the participants. TYPE: `str`
`demographic_profiles`	A list of demographic profiles for the participants. This field is optional. TYPE: `Optional[List[DemographicProfile]]`
`default_answer_options`	A dictionary of default answer options for the questionnaire. The keys represent unique identifiers for each option. This field is optional. TYPE: `Optional[Dict[str, AnswerOption]]`
`instruction_items`	A list of instruction items (questions) included in the questionnaire. This field is optional. TYPE: `Optional[List[InstructionItem]]`

METHOD	DESCRIPTION
`get_number_of_questions`	Returns the number of questions in the questionnaire.

name ¶

name: str

general_instruction ¶

general_instruction: str

demographic_profiles ¶

demographic_profiles: list[DemographicProfile] | None = None

attributes ¶

attributes: dict = Field(default_factory=dict, description='Additional attributes related to the question, such as its dimension in a multi-dimensional test structure.')

default_answer_options ¶

default_answer_options: AnswerOptions | None = None

instruction_items ¶

instruction_items: list[InstructionItem] | None = None

ensure_default_answer_options_is_proper_model ¶

ensure_default_answer_options_is_proper_model(v: Any) -> Any

Convert a dictionary to an AnswerOptions model if necessary.

get_number_of_questions ¶

get_number_of_questions() -> int

Returns the number of questions in the questionnaire.

print_questionnaire ¶

print_questionnaire()

Prints the questionnaire in a human-readable format.

InstructionItem ¶

Represents a single question item in a psychological test, along with its answer options and specific attributes.

question ¶

question: str = 'Enter question text here'

reversed ¶

reversed: bool = False

answer_options ¶

answer_options: AnswerOptions | None = None

attributes ¶

attributes: dict = Field(default_factory=dict, description='Additional attributes related to the question, such as its dimension in a multi-dimensional test structure.')

answers ¶

answers: dict[Any, dict[Any, dict[Any, Any]]] | None = Field(default_factory=dict, description='A nested dictionary storing answers indexed by model, profile, and run.')

ensure_answer_options_is_proper_model ¶

ensure_answer_options_is_proper_model(v: Any) -> Any

Convert a dictionary to an AnswerOptions model if necessary.

update_answer ¶

update_answer(model_key: str, profile_key: str, run_idx: int, answer: Any) -> None

Store the answer in the appropriate location.

get_answer ¶

get_answer(model_key: str, profile_key: str, run_idx: int) -> Any

Return the stored answer.

RAISES	DESCRIPTION
`KeyError`	If there is no answer for this model, persona and seed. Reading never modifies the stored answers.

get_all_answers ¶

get_all_answers() -> dict[str, dict[str, dict[int, Any]]]

Retrieve all answers.

get_answer_options_as_list ¶

get_answer_options_as_list() -> list[str]

Return the list of answer options' text.

AnswerOptions ¶

Represents a collection of answer options in a psychological test along with a delimiter for joining them.

options ¶

options: dict[str, AnswerOption] = Field(default_factory=dict, description='A dictionary of answer options.')

delimiter ¶

delimiter: str = Field(default=', ', description="The delimiter used to join the answer options when displayed as a string. Default is ', '. Insert a line break '\\n' for a new line.")

prepend_delimiter ¶

prepend_delimiter: bool = Field(default=False, description='If True, the delimiter will be added before the first answer option as well.')

join_options ¶

join_options() -> str

Join the answer options' text using the specified delimiter.

get_options_as_list ¶

get_options_as_list() -> list[str]

Return the list of answer options' text.

AnswerOption ¶

Represents an answer option in a psychological test.

text ¶

text: str = 'Choose an option'

ignored_for_scale ¶

ignored_for_scale: bool = False

weight ¶

weight: int = 0

DemographicProfile ¶

Represents the demographic profile of a participant in a psychological test. This includes attributes like age, title, name, and a template for formatting purposes.

attributes ¶

attributes: DemographicAttributes = Field(..., description='Attributes containing demographic information such as age, title, and name.')

template ¶

template: str = Field(default='{title} {name} is {age} years old.', description="A template string to format the demographic information. Use placeholders for attributes (e.g., '{title}', '{name}', '{age}').")

get_profile_desc ¶

get_profile_desc()

Returns a string representation of the profile.

DemographicAttributes ¶

Represents the demographic attributes of a participant in a psychological test. This model includes default fields such as 'age', 'title', and 'name', but it is extendable to include additional demographic details as needed.

ATTRIBUTE	DESCRIPTION
`age`	The age of the participant. Default is None. TYPE: `Optional[int]`
`title`	The title of the participant (e.g., Mr, Ms, Dr). Default is None. TYPE: `Optional[str]`
`name`	The name of the participant. Default is None. TYPE: `Optional[str]`

The model is flexible to accept additional fields beyond the ones specified.

age ¶

age: Any | None = None

title ¶

title: Any | None = None

name ¶

name: Any | None = None

Parameters¶

rupsycho.models.parameters.ExperimentParameters ¶

Parameters of an experiment.

ATTRIBUTE	DESCRIPTION
`seeds`	Seeds of the repetitions. Every model is asked every question once per seed. Integers (`[1, 2, 3]`) and numeric strings (`["1", "2"]`) are accepted. If omitted, one random seed is drawn per experiment - set seeds explicitly for reproducible experiments. TYPE: `Seeds`
`lazy_load_models`	Load each model only when the run reaches it (default). With `False` all models are loaded when the experiment is created. TYPE: `bool`

Additional keys are kept as they are.

Example

ExperimentParameters(seeds=[1, 2, 3]).seeds  # ['1', '2', '3']

seeds ¶

seeds: Seeds = Field(default_factory=lambda: [str(randint(0, 999999))], description='A list of seeds for random number generation in the experiment.')

lazy_load_models ¶

lazy_load_models: bool = Field(default=True, description='If True, models will be loaded only when they are needed during the experiment.')

Prompt templates¶

rupsycho.models.prompt ¶

NormalPromptTemplateConfig ¶

Configuration for a normal LangChain PromptTemplate. This model defines the template string with placeholders.

type ¶

type: str = Field('normal', description='The type of the prompt configuration.')

template ¶

template: str = Field(..., description="The template string with placeholders (e.g., 'Tell me a {adjective} joke about {content}').")

load_prompt_template ¶

load_prompt_template()

Method to create the actual PromptTemplate object.

ChatMessageConfig ¶

Configuration for a single message in a ChatPromptTemplate.

role ¶

role: str = Field(..., description="The role of the message (e.g., 'system', 'human', 'ai').")

content ¶

content: str = Field(..., description='The content of the message, with placeholders if necessary.')

ChatPromptTemplateConfig ¶

Configuration for a LangChain ChatPromptTemplate. This model defines the sequence of messages, each associated with a role.

type ¶

type: str = Field('chat', description='The type of the prompt configuration.')

messages ¶

messages: list[ChatMessageConfig] = Field(..., description='A list of messages, each with a role and content.')

load_prompt_template ¶

load_prompt_template()

Method to create the actual ChatPromptTemplate object.

LangchainPromptTemplateConfig ¶

Configuration for a LangChain ChatPromptTemplate. This model defines the sequence of messages, each associated with a role.

type ¶

type: str = Field('langchain', description='The type of the prompt configuration.')

definition ¶

definition: dict[str, Any] = Field(..., description='A dictionary containing the serialized LangChain prompt or other runnable configuration.')

load_prompt_template ¶

load_prompt_template()

Method to deserialize and create the actual LangChain PromptTemplate object.

Model configurations¶

rupsycho.models.model ¶

Data model: language model configurations.

Each configuration describes how to build one LangChain model and exposes load_model(). Provider SDKs are imported lazily inside load_model so that configurations can be created, validated and serialised without the corresponding extra installed. Loading a model whose extra is missing raises an ImportError naming the extra to install.

LangChainModelConfig ¶

Configuration for a serialized LangChain model or any other runnable configuration.

ATTRIBUTE	DESCRIPTION
`definition`	The serialized model as produced by `langchain_core.load.dumpd`. TYPE: `dict[str, Any]`
`parameters`	Generation parameters (informational for serialized models). TYPE: `dict`
`prompt_template`	Optional prompt template of the model. TYPE: `LangchainPromptTemplateConfig \| None`

type ¶

type: str = Field('langchain', description='The type of the model configuration.')

definition ¶

definition: dict[str, Any] = Field(..., description='A dictionary containing the serialized LangChain model or other runnable configuration.')

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation')

prompt_template ¶

prompt_template: LangchainPromptTemplateConfig | None = Field(None, description='The prompt template used by the model')

load_model ¶

load_model() -> Any

Deserialize and return the LangChain model.

RETURNS	DESCRIPTION
`Any`	The deserialized LangChain model.

RAISES	DESCRIPTION
`ValueError`	If the definition cannot be deserialized.

LocalHuggingFaceModelConfig ¶

Configuration for a Hugging Face model that runs in this process.

Requires the huggingface extra. Pin revision to a commit hash to make the exact model version part of your experiment configuration.

Example

config = LocalHuggingFaceModelConfig(
    name_or_path="HuggingFaceTB/SmolLM-1.7b-Instruct",
    revision="main",
    device_map="cpu",
    parameters={"max_new_tokens": 64, "do_sample": True, "return_full_text": False},
)
model = config.load_model()

type ¶

type: str = Field('local_huggingface', description='The type of the model configuration.')

name_or_path ¶

name_or_path: str = Field(..., description='The path to the local directory or the name of the Hugging Face model.')

revision ¶

revision: str | None = Field(None, description='The specific model version to use (e.g., a branch name, tag, or commit hash).')

tokenizer_name_or_path ¶

tokenizer_name_or_path: str | None = Field(None, description='The name or path to the tokenizer to use. Defaults to `name_or_path` if not specified.')

cache_dir ¶

cache_dir: str | None = Field(None, description='Path to the directory where the downloaded model and tokenizer files will be cached.')

huggingfacehub_api_token ¶

huggingfacehub_api_token: Secret = Field(None, description='The API token for accessing gated or private Hugging Face models.')

device_map ¶

device_map: Any | None = Field('auto', description="The device map to load the model onto ('cpu', 'cuda', or custom device map). See https://huggingface.co/docs/accelerate/concept_guides/big_model_inference#designing-a-device-map")

task ¶

task: str | None = Field('text-generation', description="The type of pipeline to create (e.g., 'text-generation').")

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation (e.g., max_new_tokens, temperature).')

prompt_template ¶

prompt_template: str | BaseModel | None = Field(None, description='The prompt template used by the model, if applicable.')

bitsandbytes_config ¶

bitsandbytes_config: dict | None = Field(None, description='Optional dictionary for bitsandbytes quantization configuration.')

load_model ¶

load_model() -> Any

Load the model, wrap it into a Transformers pipeline and return a chat model.

RETURNS	DESCRIPTION
`Any`	A `ChatHuggingFace` around a `HuggingFacePipeline`.

RAISES	DESCRIPTION
`ImportError`	If the `huggingface` extra is not installed.
`ValueError`	If the model cannot be loaded.

RemoteHuggingFaceModelConfig ¶

Configuration for a model served by a Hugging Face Inference Endpoint.

Requires the huggingface extra and a Hugging Face token in the environment (HUGGINGFACEHUB_API_TOKEN).

type ¶

type: str = Field('remote_huggingface', description='The type of the model configuration.')

repo_id ¶

repo_id: str = Field(..., description="The repository ID of the Hugging Face model (e.g., 'HuggingFaceH4/zephyr-7b-beta').")

task ¶

task: str = Field(..., description="The task for the Hugging Face pipeline (e.g., 'text-generation').")

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation (e.g., max_new_tokens, temperature).')

load_model ¶

load_model() -> Any

Create the endpoint client and return it as a chat model.

RETURNS	DESCRIPTION
`Any`	A `ChatHuggingFace` around a `HuggingFaceEndpoint`.

RAISES	DESCRIPTION
`ImportError`	If the `huggingface` extra is not installed.
`ValueError`	If the endpoint cannot be created.

OllamaModelConfig ¶

Configuration for a model served by a local or remote Ollama server.

Requires the ollama extra.

type ¶

type: str = Field('ollama', description='The type of the model configuration.')

model ¶

model: str = Field(..., description="The identifier for the Ollama model (e.g., 'gemma2:2b').")

base_url ¶

base_url: str = 'http://localhost:11434'

Base url the model is hosted under.

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation')

prompt_template ¶

prompt_template: ChatPromptTemplateConfig | None = Field(None, description='The prompt template used by the model')

load_model ¶

load_model() -> Any

Create the Ollama client.

RETURNS	DESCRIPTION
`Any`	An `OllamaLLM`.

RAISES	DESCRIPTION
`ImportError`	If the `ollama` extra is not installed.
`ValueError`	If the client cannot be created.

OpenAIModelConfig ¶

Configuration for an OpenAI (or OpenAI-compatible) chat model.

Requires the openai extra. The API key is read from api_key or, if unset, from the OPENAI_API_KEY environment variable. Prefer the environment variable so that keys never end up in shared configuration files.

type ¶

type: str = Field('openai', description='The type of the model configuration.')

name_or_path ¶

name_or_path: str = Field(..., description="The identifier for the OpenAI model (e.g., 'gpt-4').")

api_key ¶

api_key: Secret = Field(None, description="The API key for accessing OpenAI's models.")

base_url ¶

base_url: str | None = Field(None, description='The base URL for the OpenAI API endpoint.')

organization ¶

organization: str | None = Field(None, description='The organization ID associated with the OpenAI API key.')

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation')

prompt_template ¶

prompt_template: ChatPromptTemplateConfig | None = Field(None, description='The prompt template used by the model')

load_model ¶

load_model() -> Any

Create the OpenAI chat model.

RETURNS	DESCRIPTION
`Any`	A `ChatOpenAI`.

RAISES	DESCRIPTION
`ImportError`	If the `openai` extra is not installed.
`ValueError`	If the client cannot be created.

GoogleModelConfig ¶

Configuration for a Google Gemini chat model.

Requires the google extra. Gemini models cannot be seeded; see rupsycho.seeding.

type ¶

type: str = Field('google', description='The type of the model configuration.')

name_or_path ¶

name_or_path: str = Field(..., description="The identifier for the Google model (e.g., 'gemini-2.0-flash').")

api_key ¶

api_key: Secret = Field(None, description='The API key for accessing Google models.')

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation')

prompt_template ¶

prompt_template: ChatPromptTemplateConfig | None = Field(None, description='The prompt template used by the model')

load_model ¶

load_model() -> Any

Create the Google chat model.

RETURNS	DESCRIPTION
`Any`	A `ChatGoogleGenerativeAI`.

RAISES	DESCRIPTION
`ImportError`	If the `google` extra is not installed.
`ValueError`	If the client cannot be created.

DeepSeekModelConfig ¶

Configuration for a DeepSeek chat model.

Requires the deepseek extra. The API key is read from api_key or, if unset, from the DEEPSEEK_API_KEY environment variable.

type ¶

type: str = Field('deepseek', description='The type of the model configuration.')

name_or_path ¶

name_or_path: str = Field(..., description="The identifier for the DeepSeek model (e.g. 'deepseek-chat').")

api_key ¶

api_key: Secret = Field(None, description='The API key for accessing DeepSeek models.')

parameters ¶

parameters: dict = Field({}, description='The parameters for text generation')

prompt_template ¶

prompt_template: ChatPromptTemplateConfig | None = Field(None, description='The prompt template used by the model')

load_model ¶

load_model() -> Any

Create the DeepSeek chat model.

RETURNS	DESCRIPTION
`Any`	A `ChatDeepSeek`.

RAISES	DESCRIPTION
`ImportError`	If the `deepseek` extra is not installed.
`ValueError`	If the client cannot be created.