What it does
The engine ingests building structures in the form of a standardized ontology, occupancy data and booking data to generate recommendations that are ranked using scores and confidence metrics. Examples include:
- "This room is underused, reallocate or consolidate."
- "This zone is over capacity at certain hours, reduce HVAC/maintenance costs by rescheduling."
- "This room type is systematically underbooked, investigate why."
Each recommendation carries a subject_key, a target-scoped identity that attaches feedback and later runs back to the same underlying finding across re-runs, rather than treating every run as a clean slate.
Personas were integrated into the engine such that the program creates recommendations based on the type of site/building and the type of person inspecting the recommendations. A healthcare persona would be recommended ways to optimize clinic usage by observing booked clinic space that goes unused, whereas office building managers would receive recommendations on underused office spaces and underperforming meeting rooms based on available amenities.
Design philosophy
To optimize the project for extensibility and a business-logic-first approach, the application was prototyped using three different models: LLMs, traditional TensorFlow-based ML, and a basic statistical model. A statistical model was arrived at, with the ability to extend functionality using TensorFlow and LLMs built in.
Each recommendation type links to a candidate builder, which in its current form runs a statistical model to generate relevant features and metrics for the recommendation. TensorFlow is used for trend prediction and pattern recognition as needed, while still falling back on the statistical model to parse business logic and policies.
Simplified pipeline, including the parallel metric layer — see the Architecture tab below for the full breakdown.
Ontology
Organization → Site → Floor → Zone → Room → Sensor, with per-room metadata (features, tags, activities, bookings) and time-series occupancy data.
Pipeline
Feature layer → candidate generation → policy & ranking. A metric layer computes historical trends on its own schedule and feeds candidate generation.
- Plugins: features, candidate builders, and policies auto-register — just drop in a new class.
- Candidate builders: one opportunity check each, with a score and confidence rating.
- Policies: a veto chain — every policy must agree to keep a recommendation.
- Ranking: dedupes and caps recommendations per zone with one shared scoring formula.
Run model
An API layer admits runs; a worker process claims and executes them. Atomic DB admission keeps this correct under concurrency, and crashed runs recover automatically.
REST surface
A versioned API to trigger runs, fetch recommendations, submit feedback, and manage settings — every setting resolves through one clear precedence chain.
Dev tooling
Four internal consoles: an API tester, a read-only DB viewer, a config admin panel, and a client-facing settings preview.
Test suite
~900 pytest unit and integration tests, plus an opt-in real-data pass. One script drives both the pre-push hook and CI, and a Docker Compose smoke test catches what unit tests miss.
Current direction
Two AWS Lambda functions sharing one container image, orchestrated by Step Functions and EventBridge — no persistent server.
Storage & ingestion
SQLite today behind a swappable storage interface, with a PostgreSQL/RDS backend in progress. Ingests CSV and JSON sources, with Athena support planned.
What's next
More recommendation types, richer features, and an LLM/chatbot front end that calls the engine as a tool rather than replacing it.