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

AI summary

Overview

Research area: Building energy research, occupant behavior modeling, and LLM-based AI agents (submitted to the journal SoftwareX; arXiv category cs.HC).

Technical level: Intermediate. The paper is written as a software description, so it assumes some familiarity with building simulation (EnergyPlus, thermostat setpoints, time-of-use tariffs) and with large language model concepts (prompts, temperature, memory retrieval), but it explains each component of the platform in plain terms.

Scope: This paper describes BuildOcc, an open-source Python platform that grounds large language model occupant agents in American Time Use Survey (ATUS) data so that building energy tools can integrate demographically differentiated occupant behavior without writing custom integration code.

What This Paper Is About

Occupants are a primary source of uncertainty in building energy consumption, but most existing occupant behavior models rely on fixed schedules (such as ASHRAE 90.1 reference schedules) or stochastic processes that cannot reason about an occupant's personal history, current context, or the type of energy signal being delivered. Recent LLM-based agents address this, but they are typically instantiated from hand-crafted profiles or small convenience samples, rarely validated quantitatively against empirical activity benchmarks, and rarely released as open platforms. BuildOcc fills this gap by packaging survey-grounded, demographically parameterized occupant agents as a reusable component that any building energy tool can drive through a Python library, a REST API, or a Model Context Protocol (MCP) server.

Key Contributions

1. A survey-grounded occupant agent platform. BuildOcc grounds agent personas and activity schedules in the American Time Use Survey (ATUS), a nationally representative diary dataset covering 16,684 respondents from ATUS 2022–2023 microdata, with appliance ownership and income priors drawn from EIA RECS probability distributions.

2. A six-component agent architecture. Each agent combines a Persona (one of four demographic strata, O1–O4), an ActivityScheduler (samples activity at each 15-minute timestep from stratum- and hour-specific distributions), a MemoryStream (recency- and importance-ranked log with periodic reflection), an LLM Reasoning Engine (queried at temperature T=0 for reproducibility), a SimulationEnvironment, and an AgentStore persisting cognitive state to SQLite via SQLAlchemy.

3. A three-layer integration interface. The platform is distributed as the package buildocc and imported as occupant_agent, exposing a Python library, a stateless FastAPI REST API (POST /step, POST /signal, GET /state), and an MCP server that lets MCP-compatible hosts such as Claude Desktop, LangChain, and Home Assistant drive a simulation without integration code.

4. A plugin registry for community extension. Abstract base classes (BasePersona, BaseScheduler, BaseMemoryStream) plus Python package entry-point discovery let third parties add new occupant strata, alternative activity grounding sources, and alternative memory architectures as separate installable packages without forking the repository.

Main Findings

• Tier 1 — ATUS grounding reproduces empirical activity distributions. Over 180 simulated days of 96 timesteps each (17,280 observations per stratum), mean per-hour KL divergence between simulated and ATUS reference distributions was 0.0181 (O1), 0.0253 (O2), 0.0184 (O3), and 0.0092 (O4) nats. Every ATUS-grounded condition stayed below 0.03 nats.

• Tier 1 — the fixed rule-based baseline fails categorically. The deterministic baseline (e.g., sleeping 23:00–06:59, work 09:00–16:59, without demographic conditioning) produced KL divergences of 10.11 (O1), 11.48 (O2), 9.92 (O3), and 11.27 (O4) nats, ranging from 9.92 to 11.48 overall. The paper states this gap is one of kind rather than degree: the baseline places zero probability on categories the reference records as occurring, so its divergence is governed by the smoothing constant ε = 10⁻⁹ and registers impossible predictions rather than the size of a behavioral error.

• Tier 2 — demographic priors propagate into differentiated behavior. Running each of O1–O4 for three seeds over one weekday each (96 timesteps, 288 timesteps per stratum) under identical environment conditions, O2 (retired couple) was the most active: lowest inactivity (67.4%), highest device-toggling (8.0%) and room-movement (21.5%) rates, and the highest mean peak setpoint (24.3 °C). O4 (unemployed adult) matched O2's toggling rate (8.0%) but recorded the lowest thermostat-adjustment rate (1.4%) and the lowest peak setpoint (23.1 °C). O3 (employed parent) showed the lowest device-toggling rate (3.5%). O1 (employed single) recorded 76.0% inactivity, 2.8% thermostat adjustments, 4.2% toggles, 17.0% moves, and a 23.5 °C peak setpoint. Do-nothing accounted for 67–76% of timesteps across strata.

• Tier 2 — signal compliance varied by stratum and signal type. With five seeds per cell and a 2.5-hour context period (10 simulated timesteps beginning at 16:00), Type A direct commands drew the most acceptance from O2 (2 of 5 seeds), with O1 and O4 accepting in 1 of 5. Type B educational price signals were accepted by O2 and O4 in 2 of 5 seeds each. O3 rejected all signal types across all five seeds — an outcome the paper attributes to signal delivery at 18:30 coinciding with child-care activity codes in the ATUS schedule. Type C social norm signals drew no acceptance in any stratum.

• Interpretation is bounded by the study design. Tier 2 establishes internal consistency (agents from different priors behave differently in directions consistent with those priors), not behavioral realism. Each stratum was run for only one weekday per seed, and the paper notes that with 288 timesteps one percentage point corresponds to roughly three timesteps, so differences of a few tenths should not be read as meaningful. No significance testing is performed on the signal compliance counts.

• A demand response walkthrough shows cross-timestep coherence. An O1 agent (28-year-old employed male, income bracket 9, comfort band ±1.1 °C) at 18:00 on a summer weekday, with zone temperature 23.9 °C, thermostat at 22 °C, outdoor temperatures exceeding 38 °C, and a TOU rate of $0.22/kWh, raised its setpoint to 24 °C to cut peak-rate run time. At 18:30 a Type B educational signal referencing ~$0.35 in savings was accepted, with the agent citing its own earlier action from memory. Importance ratings for routine observations stayed low (2–3 out of 10).

• Computational cost scales linearly with agent-days. A 15-minute timestep gives up to 96 LLM calls per simulated day per agent, plus occasional reflection calls, with responses capped at 512 tokens. A four-occupant household is roughly 384 calls per simulated day; agents can run in parallel across processes. Scheduler-only studies, including Tier 1, require no model calls at all. Cost, rather than platform capability, bounded the simulation lengths reported.

Methodology in Plain English

The researchers built a software platform rather than running a single experiment. They started from the ATUS 2022–2023 microdata (16,684 respondents) and computed, for each hour of the day, the probability that a person in a given demographic group is engaged in each of eight activity categories (sleeping, work, food preparation, laundry, television viewing, eating, exercise, and other). A key design choice is the "in-progress" framing: instead of asking when activities start (which overrepresents short activities such as a 5-minute meal), the method asks which activity was underway at the half-hour mark of each hour, weighting respondents by ATUS person-level weights. Work-from-home status is handled by a separate per-agent probability and a per-day random draw, so the agent does not get assigned "work" activities that place it away from home on remote days.

Four demographic strata were defined — O1 employed single adult, O2 retired couple, O3 employed parent, O4 unemployed adult — spanning variation in occupancy and demand response participation relevant to residential energy research. Appliance ownership and income priors come from EIA RECS, and income brackets are currently sampled uniformly within each stratum's RECS income range.

At each 15-minute timestep, an agent runs a five-step pipeline: resolve the current ATUS activity code into a natural-language description and occupancy flag; retrieve up to five memories ranked by a score combining recency (exponential decay with a half-life of 24 hours) and an LLM-assigned 1–10 importance score; assemble a system prompt encoding the persona and a user prompt encoding environment state, activity, and memories; call a configurable LLM provider (Anthropic, OpenAI, Google, or local Ollama) at temperature T=0 for reproducibility; and update the memory stream, triggering a reflection pass when a cumulative importance accumulator exceeds a default threshold of 100. The model selects among four action types: do_nothing, adjust_thermostat, toggle_device, and move_room. Demand response signals are delivered through a separate interface supporting Type A (direct command), Type B (educational), and Type C (social norm), returning accepted, rejected, or deferred alongside free-text reasoning.

Validation was done in two tiers. Tier 1 tested the scheduler alone — no LLM calls — by simulating 180 days of 96 timesteps per stratum and computing KL divergence against the ATUS reference, compared with a deterministic rule-based baseline. Tier 2 tested the LLM agent decisions, running each stratum for three seeds over one weekday under identical environment conditions (the same EnergyPlus zone temperature, a device configuration of HVAC, three lighting zones, TV, washer, and dishwasher, and a TOU tariff of $0.22/kWh peak and $0.08/kWh off-peak), then delivering three standardized signals to each stratum with five seeds each.

Why This Matters

Impact on research. BuildOcc treats occupant behavior as a structured, demographically parameterizable experimental variable rather than an uncontrolled source of uncertainty. By packaging population-calibrated agents as a reusable component with a frozen schema and a plugin registry, it removes the need for each research group to construct a grounding pipeline from scratch, and it provides a documented baseline that others can adopt, extend, or cite as a reference condition. It also supplies a shared starting point for reproducible occupant behavior research, which the paper identifies as previously lacking because existing LLM occupant agents relied on hand-crafted profiles or small convenience samples and rarely released open-source platforms.

Real-world applications.

• EnergyPlus co-simulation for testing how different household types respond to thermostat setpoints and tariffs.
• Home Assistant automations that incorporate demographically differentiated occupant reasoning.
• Demand response program design, using the factorial signal interface to test direct commands, price education, and social norms against different strata before field deployment.
• Building management systems and MCP-compatible orchestration frameworks (for example Claude Desktop or LangChain) that need behavioral intelligence without bespoke coupling code.

Industry relevance. The three-layer interface (Python library, REST API, MCP server) means utilities, demand response aggregators, and building technology vendors can integrate occupant behavioral intelligence into existing workflows without rewriting them. Because the signal types correspond to established behavioral intervention typologies, results from BuildOcc experiments are directly comparable to field studies, which the paper positions as a bridge between simulation and program evaluation.

Future Directions

• Multi-agent household simulation. Interaction between occupants, such as negotiation over a shared thermostat, is not modeled in the current version and is identified as future work. The paper notes a four-occupant household is roughly 384 calls per simulated day, so cost is a practical constraint.

• Non-US occupancy data. Transferring the platform to another country is framed as a data-substitution task rather than a redesign: activity probability tables could be regenerated from national time-use surveys following harmonized diary conventions (for example the Multinational Time Use Study or the European HETUS series). The persona layer does not transfer automatically, since appliance-ownership and income priors come from the US RECS survey and would need a national equivalent.

• External behavioral benchmarks. The paper states subsequent phases will match the four ATUS strata against external behavioral benchmarks including ecobee Smart Thermostat field data, which is the comparison needed to move beyond internal consistency toward behavioral realism.

• Addressed limitations. The paper lists a single-action constraint per timestep, ATUS-grounded strata covering US demographic profiles only, activity grounding restricted to primary activities (ATUS records only one activity at a time, so simultaneous secondary activities such as watching television while preparing food are not represented), and a memory-importance score that the agent assigns to itself and then reuses for retrieval without external calibration or a feedback path to correct a mis-scored entry.

Target Audience

Building energy researchers who need demographically differentiated occupant behavior in simulation studies; software developers integrating occupant models with EnergyPlus, Home Assistant, or custom building management systems; researchers in human-computer interaction and AI agent design interested in LLM memory architectures grounded in survey data; and demand response or behavioral energy program analysts who want to test intervention designs against population-calibrated synthetic occupants before running field studies. Readers should be comfortable with Python and basic building simulation concepts, though the paper explains its architecture component by component.

Authors’ abstract

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.