Spaxiom Logo
Spaxiom Technical Series - Part 1

Architectural Overview

Understanding Spaxiom's Core Abstractions and INTENT Layer

Joe Scanlin

November 2025

About This Section

This section provides an architectural overview of Spaxiom's core abstractions and the INTENT layer. You'll learn what Spaxiom is, how it translates heterogeneous sensor streams into structured semantic events, and how INTENT patterns provide agent-ready abstractions.

The section covers the minimal DSL example showing spatial primitives, sensors, and temporal logic, followed by an introduction to INTENT patterns like OccupancyField, QueueFlow, ADLTracker, and FmSteward. You'll also see how these patterns compress raw sensor data into compact, meaningful events that reduce token usage by 100-1000× when feeding context to LLMs.

2. Spaxiom Today: Architectural Overview

Spaxiom is currently implemented as an embedded DSL in Python, backed by a runtime and a growing documentation set. Concretely, Spaxiom provides:

2.1 Minimal example

from spaxiom import Sensor, Zone, Condition, on, within

office_zone   = Zone(0, 0, 10, 10)
motion_sensor = Sensor("motion1", "motion", (5, 5, 0))

motion_detected   = Condition(lambda: motion_sensor.read() > 0.5)
sustained_motion  = within(5.0, motion_detected)

@on(sustained_motion)
def alert_sustained_motion():
    print("Motion has been detected for 5 seconds!")

Instead of pushing raw time series into downstream systems, the user expresses what they care about (e.g., "sustained motion in this region for >5 seconds"), and Spaxiom takes responsibility for timing, buffering, and triggering.

2.2 INTENT: Agent-ready patterns

On top of the core DSL, we define INTENT (Intelligent Network for Temporal & Embodied Neuro-symbolic Tasks), a pattern library that captures common behaviors over sensors.

INTENT sits between the low-level DSL primitives (sensors, conditions, zones from Section 2.1) and high-level agent reasoning. While the DSL provides the building blocks for expressing spatiotemporal logic, INTENT patterns encapsulate recurring behaviors as reusable abstractions. For example, detecting "a queue is forming" involves sensor fusion (camera + pressure mat), temporal filtering (queue must persist >30 seconds), and queueing theory (estimating wait times from arrival/service rates). Rather than re-implementing this logic at each deployment, an INTENT.QueueFlow pattern captures it once and exposes an agent-ready event stream.

INTENT patterns serve three critical purposes:

  1. Semantic compression: Reducing hundreds of sensor readings per second to a single OccupancyChanged or QueueFormed event saves 100-1000× tokens when feeding context to LLMs (Section 3).
  2. Domain expertise: Patterns embed specialized knowledge (queueing theory for QueueFlow, ADL recognition heuristics for elder care, facilities management logic for FmSteward) that would otherwise need to be re-discovered at each site.
  3. Agent-readiness: Patterns emit events with agent-friendly schemas (JSON-serializable, self-describing, typed) optimized for inclusion in LLM context windows or as observations in RL environments.

Core INTENT patterns

The INTENT library includes a growing collection of domain-specific patterns. Four foundational patterns demonstrate the breadth of applicability:

Additional domain-specific patterns (detailed in appendix use cases and Section 2.4) include:

This diversity demonstrates that INTENT is not a fixed set of patterns, but an extensible framework for capturing domain expertise across industries: from healthcare to manufacturing, retail to agriculture, smart buildings to autonomous systems.

Example: OccupancyField → LLM integration

The following code demonstrates how an OccupancyField pattern compresses floor sensor data into crowding metrics and feeds them to an LLM agent for decision-making:

from spaxiom.config  import load_yaml
from spaxiom.runtime import start_runtime
from spaxiom.temporal import within
from spaxiom.logic    import on
from spaxiom.intent   import OccupancyField

import asyncio, json, os, openai

sensors = load_yaml("examples/lobby.yaml")
floor   = sensors["lobby_floor"]

field   = OccupancyField(floor, name="lobby")
crowded = within(180.0, field.percent_above(10.0))   # >= 10% tiles active, 3 minutes

@on(crowded)
async def lobby_agent():
    facts = {
        "zone": field.name,
        "occupancy_pct": field.percent(),
        "hotspots": field.hotspots(top_k=3),
    }
    prompt = (
        "You are a smart-building lobby agent. "
        "Given this JSON describing current crowding, "
        "suggest 1--3 actions to improve flow and experience. "
        "Respond as JSON.\n"
        + json.dumps(facts)
    )
    openai.api_key = os.getenv("OPENAI_API_KEY", "")
    if not openai.api_key:
        return

    rsp = await openai.ChatCompletion.acreate(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    print("INTENT actions:", rsp.choices[0].message.content)

if __name__ == "__main__":
    asyncio.run(start_runtime())

In this example, the OccupancyField pattern continuously monitors a floor sensor grid. When crowding persists for 3 minutes (within(180.0, ...)), the pattern's percent() and hotspots() methods provide agent-ready summaries: no raw sensor arrays, no manual aggregation. The LLM receives a compact JSON payload (~200 bytes) instead of 100s of kilobytes of raw sensor timeseries.

Extensibility: Users can define custom patterns by subclassing the Pattern base class (detailed in Section 2.4). This allows organizations to capture domain-specific knowledge (manufacturing process signatures, hospital workflow patterns, retail merchandising behaviors) as reusable INTENT abstractions that can be versioned, tested, and shared across deployments.

This pattern (sensor → DSL → INTENT → agent) is central to the rest of the paper. Section 2.4 provides the full pattern interface architecture, lifecycle methods, performance benchmarks, and guidelines for creating custom patterns.