LLM Services

LLM Clients

class econsimulacra.llm_services.clients.base.LLMRecordConfig(save_path=None, save_num_tokens=False, save_prompt_response_pair=False)[source]

Bases: object

Configuration for recording LLM prompts and responses.

Parameters:

save_path (str | None)
save_num_tokens (bool)
save_prompt_response_pair (bool)

save_path: str | None = None

save_num_tokens: bool = False

save_prompt_response_pair: bool = False

class econsimulacra.llm_services.clients.base.LLMClient(config, prng=None, registered_classes=[])[source]

Bases: ABC

LLM Client class (abstract class).

You can implement your own LLM client by inheriting this class and implementing the generate_response method. Currently, OpenAIClient and TransformersClient are implemented as built-in options.

See also

econsimulacra.llm_services.clients.OpenAIClient: LLM client implementation for OpenAI’s API.
econsimulacra.llm_services.clients.TransformersClient: LLM client implementation using the Transformers library and Outlines for structured generation.

Parameters:

config (dict[str, Any])
prng (Random | None)
registered_classes (list[Type])

abstractmethod async generate_response(prompt)[source]

Parameters:: prompt (str)
Return type:: dict[str, Any]

async generate_response_with_schema(prompt, json_schema)[source]

Generate a response using a request-specific action schema when supported.

Parameters:

prompt (str) – Input prompt sent to the model.
json_schema (dict[str, Any]) – Schema for this individual request.

Returns:

Parsed model response.

Return type:

dict[str, Any]

Note

The compatibility implementation delegates to generate_response. Built-in structured clients override this method.

get_action_schema(mobility_names)[source]

Build an action schema for one agent’s available mobility modes.

Parameters:: mobility_names (list[str]) – Mobility names available to the agent.
Returns:: Isolated, request-specific action schema.
Return type:: dict[str, Any]

Note

The stored or configured base schema is not mutated.

class econsimulacra.llm_services.clients.openai_client.OpenAIClient(config, prng=None, registered_classes=[])[source]

Bases: LLMClient

OpenAI client for interacting with OpenAI’s language models.

Parameters:

config (dict[str, Any])
prng (Optional[random.Random])
registered_classes (list[Type])

async generate_response(prompt)[source]

Generate a response from the OpenAI API based on the given prompt.

Parameters:: prompt (str) – The input prompt to send to the OpenAI API.
Returns:: The parsed JSON response from the OpenAI API.
Return type:: dict[str, Any]

Note

Existing callers use the client-level schema through the dynamic path.

async generate_response_with_schema(prompt, json_schema)[source]

Generate a response using a request-specific JSON schema.

Parameters:

prompt (str) – Input prompt sent to the OpenAI API.
json_schema (dict[str, Any]) – Schema for this individual request.

Returns:

Parsed JSON response.

Return type:

dict[str, Any]

Note

The schema is copied to keep concurrent agent requests isolated.

class econsimulacra.llm_services.clients.transformers_client.TransformersClient(config, prng=None, registered_classes=[])[source]

Bases: LLMClient

Transformers client using Outlines for structured generation.

Parameters:

config (dict[str, Any])
prng (Random | None)
registered_classes (list[Type])

async generate_response(prompt)[source]

Generate a response from the model based on the given prompt.

Parameters:: prompt (str) – The input prompt to send to the model.
Returns:: The parsed JSON response from the model.
Return type:: dict[str, Any]

Note

Existing callers continue to use generators built from the base schema.

async generate_response_with_schema(prompt, json_schema)[source]

Generate a response using a request-specific action schema.

Parameters:

prompt (str) – Input prompt sent to the model.
json_schema (dict[str, Any]) – Schema for this individual request.

Returns:

Parsed model response.

Return type:

dict[str, Any]

Note

Generators are cached by serialized schema while loaded models are reused.

class econsimulacra.llm_services.clients.text_base.TextGenerationClient[source]

Bases: ABC

Abstract service for asynchronous plain-text generation.

This interface is intentionally separate from LLMClient, whose response contract is a structured action dictionary. Text-only consumers, such as the household tweet renderer, should not generate or parse the complete simulation action schema.

abstractmethod async generate_text(prompt)[source]

Generate plain text for one prompt.

Parameters:: prompt (str) – Text-generation prompt.
Returns:: Generated text without a structured action wrapper.
Return type:: str

class econsimulacra.llm_services.clients.transformers_text_client.TransformersTextClient(config, prng=None, registered_classes=[])[source]

Bases: TextGenerationClient

Generate short plain text with a local Transformers causal LM.

Parameters:

config (dict[str, Any]) – Service configuration. It must contain modelName and may contain device, dtype, maxModelParameters, maxNewTokens, temperature, topP, repetitionPenalty, maxPromptTokens, maxConcurrentGenerations, numThreads, trustRemoteCode, and ignoreGenerationErrors.
prng (Optional[random.Random]) – Optional simulation pseudo-random generator.
registered_classes (list[Type]) – Registered classes accepted for compatibility with the environment service factory; unused by this implementation.

Unlike TransformersClient, this service does not use an action JSON schema. It is intended for bounded surface realization after another component has already selected the semantic content.

async generate_text(prompt)[source]

Generate plain text without returning the input prompt tokens.

Parameters:: prompt (str) – Prompt to format with the tokenizer chat template.
Returns:: Decoded generated continuation. If ignoreGenerationErrors is enabled, failures produce an empty string.
Return type:: str

class econsimulacra.llm_services.clients.vllm_client.VLLMClient(config, prng=None, registered_classes=[])[source]

Bases: LLMClient

Parameters:

config (dict[str, Any])
prng (Optional[Any])
registered_classes (list[Type])

async generate_response(prompt)[source]

Generate a response with the client’s configured action schema.

Parameters:: prompt (str) – Input prompt sent to the vLLM server.
Returns:: Parsed JSON response.
Return type:: dict[str, Any]

Note

This compatibility method delegates to the request-specific path.

async generate_response_with_schema(prompt, json_schema)[source]

Generate a response using a request-specific JSON schema.

Parameters:

prompt (str) – Input prompt sent to the vLLM server.
json_schema (dict[str, Any]) – Schema for this individual request.

Returns:

Parsed JSON response.

Return type:

dict[str, Any]

Note

The schema is copied to keep concurrent agent requests isolated.

close()[source]

Return type:: None

async aclose()[source]

Return type:: None

Prompt Builders

class econsimulacra.llm_services.prompts.base.PromptBuilder(config, prng=None, registered_classes=[])[source]

Bases: object

Prompt Builder class. Prompt builders are responsible for generating prompts except for the persona description (if applicable) i.e., they translate the observation into a prompt for LLM input. You can implement your own prompt builder by inheriting this class and implementing the build_prompt method.

Parameters:

config (dict[str, Any])
prng (Random | None)
registered_classes (list[Type])

build_prompt(obs)[source]

Translate the observation into a prompt for LLM input.

Parameters:: obs (dict[str, Any]) – the observation to translate into a prompt for LLM input
Returns:: the generated prompt for LLM input
Return type:: str

Note

Called by LLMAgent.act

Persona Builders

class econsimulacra.llm_services.personas.base.PersonaBuilder(config, prng=None, registered_classes=[])[source]

Bases: ABC

Persona Builder class (abstract class).

You can implement your own persona builder by inheriting this class and implementing the build_persona method. Currently, Big5PersonaBuilder is implemented as a built-in option, which builds personas based on the Big5 personality traits.

See also: econsimulacra.llm_services.personas.big5.Big5PersonaBuilder

Parameters:

config (dict[str, Any])
prng (Random | None)
registered_classes (list[Type])

abstractmethod build_persona(agent_id, agent_config)[source]

Register the agent to agent_id2persona_dic.

Parameters:

agent_id (int) – agent_id of the agent to build persona for
agent_config (dict) – config of the agent to build persona for, which is the same as the one in env_config[“agents”][agent_name]

Return type:

None

Note

Called when LLMAgent is initialized. See also: econsimulacra.agents.llm_agent.LLMAgent._setup_env_services()

get_persona(agent_id)[source]

Get the persona for the agent with the given agent_id.

Parameters:: agent_id (int)
Return type:: dict[str, Any] | None

build_persona_prompt(agent_id)[source]

Build persona prompt for the agent with the given agent_id.

Parameters:: agent_id (int) – agent_id of the agent to build persona prompt for
Returns:: persona prompt for the agent
Return type:: str

Note

Called when LLMAgent.act is called. persona prompt contains the description and the persona information of the agent, and is used as part of the prompt for generation.

assign_name(agent_id, default_name, config)[source]

Parameters:

agent_id (int)
default_name (str)
config (dict)

Return type:

str

class econsimulacra.llm_services.personas.scored_persona.ScoredPersonaBuilder(config, prng=None, registered_classes=[])[source]

Bases: PersonaBuilder

Persona builder that builds personas with scores.

The persona is represented as a dictionary of attributes and their corresponding scores.

Parameters:

config (dict[str, Any])
prng (Random | None)
registered_classes (list[Type])

build_persona(agent_id, agent_config)[source]

Register the agent to agent_id2persona_dic with random scores for each attribute.

Parameters:

agent_id (int) – agent_id of the agent to build persona for
agent_config (dict) – config of the agent to build persona for, which is the same as the one in env_config[“agents”][agent_name]

Return type:

None

Note

Called when LLMAgent is initialized. See also: econsimulacra.agents.llm_agent.LLMAgent._setup_env_services()