PaperlayerView exact revision on arXiv

Source-linked AI summary

BuildOcc: A Large Language Model Occupant Agent Platform for Building Energy Research

Wooyoung Jung

arXiv:2609.02729v1cs.HC

TL;DR

Existing occupant behavior models have limited capacity to represent adaptive, contextual responses involving personal history and energy signals. BuildOcc grounds LLM occupant agents in ATUS data and evaluates schedule fidelity and demographic differentiation, finding calibrated activity distributions and internally consistent persona-driven behavior, while model-call cost and absent occupant interaction bound its use.

  • Problem

    Existing occupant behavior models often rely on fixed schedules or stochastic processes that incompletely capture personal history, current context, and delivered energy signals.

  • Method

    BuildOcc combines ATUS-grounded activity scheduling, demographic personas, memory-based LLM reasoning, and Python, REST, and MCP integration interfaces.

  • Results

    Tier 1 keeps every ATUS-grounded condition below 0.03 nats, versus 9.92–11.48 for the fixed baseline, while Tier 2 finds demographic priors produce qualitatively distinct reasoning patterns.

  • Takeaways & Limitations

    BuildOcc offers a reusable, extensible occupant behavioral layer that treats occupant behavior as a reproducible, demographically parameterizable experimental variable.

  • Takeaways & Limitations

    LLM calls scale linearly with agent-days and household size, and interactions between occupants are not modeled in this version.

Abstract

from arXiv · show

Occupants are a primary source of uncertainty in building energy consumption and management, yet existing occupant behavior models cannot capture adaptive and reasoning responses considering the occupant's personal history, current context, and the type of energy signal being delivered. This study presents BuildOcc, an open-source Python platform that grounds large language model agents in the American Time Use Survey (ATUS), a nationally representative diary dataset covering 16,684 respondents. Through BuildOcc, each simulated occupant agent can be instantiated with a demographic persona drawn from ATUS population statistics, a memory stream that accumulates and reflects on timestep-level observations, and an activity scheduler that samples empirically from ATUS time-at-activity distributions. The platform exposes a three-layer interface - Python library, REST API, and Model Context Protocol server - so that any building energy tool (EnergyPlus, Home Assistant) can integrate behavioral intelligence without bespoke coupling code. A plugin registry lets the community add new occupant strata, custom schedulers, and alternative memory backends as separate installable packages. Two validation tiers show that ATUS-grounded sampling reproduces empirically calibrated activity distributions and that demographic priors propagate into persona-consistent agent reasoning across timesteps, establishing internal consistency across strata. BuildOcc provides the building energy community with a reusable, openly available implementation of the occupant behavioral layer. BuildOcc is openly released at https://doi.org/10.5281/zenodo.21192895 under the Apache License 2.0 and installable via pip install buildocc.

Current code version

Table 1 identifies the paper’s code metadata as mandatory.

  • Table 1 lists the code metadata required for the BuildOcc software artifact.

1. Motivation and Significance

Building occupants introduce substantial uncertainty because their adaptive responses depend on personal history, current context, and delivered energy signals. BuildOcc addresses this gap with an openly released, extensible occupant behavioral layer for building energy research.

  • Occupant responses are difficult to predict, creating substantial uncertainty in building energy use and management.
  • Many existing models use fixed schedules or stochastic processes that do not comprehensively represent personal history, current context, or energy signals.
  • LLM agents offer contextual reasoning, memory retention, and adaptive behavior for simulating complex occupant decision-making.
  • BuildOcc provides a reusable and extensible implementation of the occupant behavioral layer through abstract base classes and a plugin registry.

2. Software Description

BuildOcc combines survey-grounded occupant scheduling, demographic personas, memory-based LLM reasoning, and external integration interfaces. Its extensibility supports new data sources and components, while model calls create computational and multi-occupant scaling constraints.

  • 2.1. Agent Architecture: BuildOcc separates internal agent components from a platform interface for external building energy tools.
  • 2.1. Agent Architecture: The agent combines demographic persona, ATUS activity scheduling, memory retrieval, LLM reasoning, simulation state, and persistent cognitive storage.
  • 2.6. Platform Extensibility: BuildOcc exposes Python, REST, and MCP interfaces, while a plugin registry supports adaptation without modifying the core library.
  • 2.2. ATUS Behavioral Grounding: ATUS schedules use 16,684 respondents’ 2022–2023 diary data, with 15-minute activity probabilities stratified by demographic group and weekday or weekend.
  • 2.2. ATUS Behavioral Grounding: The in-progress activity framing estimates what activity is occurring at each time rather than sampling activity start times.
  • 2.4. LLM Reasoning Pipeline: The per-timestep pipeline resolves activities, retrieves up to five memories, constructs a prompt, obtains an action, and updates the memory stream.
  • 2.6. Platform Extensibility: Cross-country scheduler transfer requires substituting national time-use probabilities, whereas US-derived persona priors require a national equivalent.
  • 2.7. Computational Cost and Scalability: LLM-query cost and runtime scale linearly with simulated agent-days, and household call volume scales linearly with occupant count.

3. Illustrative Examples

BuildOcc is demonstrated through a demand-response walkthrough and two validation tiers: ATUS-grounded scheduling matches empirical activity patterns, while demographic priors produce differentiated agent behavior under shared conditions.

  • 3.1. Demand response walkthrough: In the walkthrough, an O1 agent raises the thermostat setpoint from 22°C to 24°C during a 39°C summer peak period while remaining within its comfort tolerance.The agent reasons that the change reduces cooling costs during the $0.22/kWh peak-rate period.
  • 3.1. Demand response walkthrough: After receiving an educational price signal, the agent recalls its earlier thermostat action, accepts the signal, and maintains the raised setpoint without further intervention.The remembered action makes the effort of repeating the change effectively zero, while routine observations receive low importance ratings of 2–3 out of 10.
  • Tier 1: Activity Schedule Fidelity: Tier 1 simulates 180 days with 96 timesteps per day for each stratum and compares hourly activity distributions against ATUS references using KL divergence.The mean per-hour divergence is averaged across all 24 hours and both weekday and weekend day types.
  • Tier 1: Activity Schedule Fidelity: Every ATUS-grounded condition stays below 0.03 nats, whereas the fixed rule-based baseline ranges from 9.92 to 11.48.The baseline uses deterministic hour-of-day rules without demographic conditioning, producing especially large divergence for retired and unemployed strata.
  • Tier 1: Activity Schedule Fidelity: Figure 3 shows ATUS-grounded O1 weekday activity probabilities closely tracking the reference, while the rule-based baseline creates step functions and misplaces the late-evening peak.The category-level comparison illustrates the distributional divergence reported by Tier 1.
  • Tier 2: Persona-Driven Behavioral Differentiation: Tier 2 finds qualitatively distinct LLM-driven patterns across strata: employment status shapes thermostat adjustments, household composition affects signal compliance, and full-day occupancy drives device toggling.O2 is the most active stratum, with 67.4% inactivity, 8.0% device toggling, 21.5% room movement, and a 24.3°C mean peak setpoint; O4’s pattern is provisional because it uses 107 respondents.

4. Impact

BuildOcc makes survey-grounded occupant agents reusable for building energy research and supports controlled studies of demographic and adaptive behavior.

  • Survey-grounded behavioral agents: BuildOcc packages population-calibrated occupant agents as a reusable component, avoiding a separate grounding pipeline for each study.Its ATUS-derived activity distributions and RECS-conditioned personas provide a documented baseline researchers can adopt or extend.
  • Survey-grounded behavioral agents: Researchers can introduce demographically differentiated occupant behavior into building energy studies without constructing grounding infrastructure from scratch.
  • Demographic behavioral experiments: BuildOcc enables controlled factorial experiments by combining demographic strata, persona income brackets, and configurable intervention signals.
  • Demographic behavioral experiments: Agents reason from demographic personas and accumulated memory at each timestep, producing adaptive responses based on personal history and current context rather than fixed schedules.

5. Conclusions

BuildOcc provides a reusable, extensible occupant behavioral layer grounded in survey data, while its validation establishes calibration and demographic consistency without proving behavioral realism.

  • BuildOcc delivers a survey-grounded, three-layer platform that building energy researchers can use and extend without reconstructing the behavioral layer for each study.
  • Tier 1 confirms that ATUS grounding produces empirically calibrated activity distributions.
  • Tier 2 shows that demographic priors propagate into differentiated agent reasoning across strata.This validation does not by itself establish that the resulting behavior is realistic.
  • The platform treats occupant behavior as a structured, demographically parameterizable experimental variable that is reproducible and extendable across research groups.The ATUS-derived strata, frozen schema, and plugin registry support this intended use.
  • Current limitations include one action per timestep, US-only demographic strata, primary-activity grounding, and self-assigned memory-importance scores without external calibration or corrective feedback.

CRediT Author Statement

Wooyoung Jung contributed across conception, methodology, software, validation, analysis, and manuscript preparation.

  • Wooyoung Jung handled conceptualization, methodology, software, validation, formal analysis, and both original drafting and revision.

A. ATUS Activity Probability Computation

The appendix computes ATUS-grounded activity probabilities by identifying activities in progress at representative time points and aggregating them across demographic strata and day types.

  • Episode-overlap framing: The scheduler identifies the activity episode in progress at the midpoint of each 15-minute simulation slot.This midpoint query avoids start-time bias that would overrepresent short activities.
  • Category probability: Eight broad activity categories are defined for probability computation by demographic stratum, hour, and weekday or weekend day type.
  • Category probability: ATUS person-level survey weights aggregate respondent activity indicators into normalized category probabilities.The resulting probabilities are evaluated across 24 hours and eight categories for each stratum and day type.
  • Code-level sampling: After category sampling, specific activity codes are drawn in proportion to total diary minutes within the selected category.This preserves realistic relative frequencies among activities mapped to the same broad category.
  • Work-from-home probability: Work-from-home probability is estimated from the ATUS TEWHERE field for employed respondents who worked on their diary day.A survey-weighted per-day Bernoulli draw determines each simulated agent’s work-from-home status.

B. Memory Retrieval and Reflection Mechanics

BuildOcc retrieves memories by equally combining exponentially decayed recency with LLM-assigned importance, then periodically reflects on accumulated observations to produce higher-order insights.

  • Each memory receives a retrieval score balancing normalized recency and normalized importance, with both components weighted equally.The top-ranked memories are selected for the next timestep prompt.
  • Recency starts at 1.0 and decays exponentially with a 24-hour half-life, leaving week-old entries with near-zero recency contribution.
  • The importance score is an integer from 1 to 10 assigned by the agent’s LLM when the memory is written.Scores range from routine events to rare or extreme situations.
  • By default, the five memories with the highest combined retrieval scores are injected into the next prompt.
  • When cumulative importance reaches the default threshold of 100, a dedicated reflection call synthesizes the 30 most recent entries into exactly three behavioral insights.Each synthesized insight is written back into the memory stream.

C. Demographic Strata Selection Rationale

The four ATUS strata were chosen to vary peak-hour occupancy schedules and household composition, capturing differences relevant to residential demand response research.

  • The four strata maximize variation in peak-hour occupancy schedules and household composition, the two behavioral dimensions identified as most consequential for residential demand response.
  • O1 and O3 are absent from home during most peak grid hours, whereas O2 and O4 remain home throughout the day.
  • Household composition spans single-person households, a two-adult couple, and a family with children to represent differences in thermostat authority and social dynamics.
  • O4 has the smallest sample, n = 107, making its 15-minute probability tables the noisiest among the four strata.
Loading 2609.02729v1…