agent_urban_planning.DecisionEngine

class DecisionEngine(*args, **kwargs)

Bases: Protocol

Protocol every decision engine implements.

Implementations MUST provide decide(). They MAY override decide_batch() for optimized population-level processing; otherwise the default implementation calls decide() in a loop. They MAY override set_cache() to accept an optional LLMCallCache from the market loop. The four canonical library engines (closed-form, hybrid, LLM, clusterized) all satisfy this protocol.

Examples

>>> import agent_urban_planning as aup
>>> # Any of the public engines can be used wherever
>>> # `DecisionEngine` is required:
>>> # engine: aup.DecisionEngine = aup.UtilityEngine(params)

decide(agent, environment, zone_options, prices)

Choose a location for one agent given the environment and current prices.

Implementations decide on the agent’s residence (and workplace, if joint) given the current state of the market. The choice is returned as a LocationChoice carrying both selected zones, the realized utility, and per-zone diagnostic utilities.

Parameters:

• agent (Agent) – The Agent whose decision is being made.

• environment (Environment) – The Environment in which the agent operates.

• zone_options (list[str]) – Allowed residence (and, where joint, workplace) zones at this market step.

• prices (dict[str, float]) – Mapping zone -> current price seen by the agent.

Return type:

LocationChoice

Returns:

A LocationChoice describing the agent’s chosen (residence, workplace) pair and realized utility.

Examples

>>> import agent_urban_planning as aup
>>> # engine = aup.UtilityEngine(params)
>>> # choice = engine.decide(agent, env, zones, prices)

decide_batch(agents, environment, zone_options, prices)

Choose locations for many agents at once.

Default implementation loops over decide() so legacy engines keep working. Override for optimized batching (e.g. async LLM calls or vectorized per-agent matrix evaluations).

Parameters:

• agents (list[Agent]) – List of Agent instances to decide for.

• environment (Environment) – The Environment they operate in.

• zone_options (list[str]) – Allowed zones at this step.

• prices (dict[str, float]) – Mapping zone -> current price.

Return type:

list[LocationChoice]

Returns:

List of LocationChoice, one per input agent and in the same order.

Examples

>>> import agent_urban_planning as aup
>>> # choices = engine.decide_batch(list(pop), env, zones, prices)

set_cache(cache)

Inject an optional cache from the market loop.

Engines that need not cache anything ignore the call (the default is no-op). LLM-backed engines typically wire the cache into their request layer here.

Parameters:

cache – An agent_urban_planning.llm.LLMCallCache or compatible object.

Return type:

None

Returns:

None.

Examples

>>> import agent_urban_planning as aup
>>> # engine.set_cache(cache)