Spaxiom-DSL

                ███████╗██████╗  █████╗ ██╗  ██╗██╗ ██████╗ ███╗   ███╗
                ██╔════╝██╔══██╗██╔══██╗╚██╗██╔╝██║██╔═══██╗████╗ ████║
                ███████╗██████╔╝███████║ ╚███╔╝ ██║██║   ██║██╔████╔██║
                ╚════██║██╔═══╝ ██╔══██║ ██╔██╗ ██║██║   ██║██║╚██╔╝██║
                ███████║██║     ██║  ██║██╔╝ ██╗██║╚██████╔╝██║ ╚═╝ ██║
                ╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝ ╚═════╝ ╚═╝     ╚═╝
    

An embedded domain-specific language for spatial sensor fusion, temporal reasoning, and real-time event detection.

     ╔═══════════╗                   ╔═══════════╗
     ║ SENSORS   ║                   ║ DETECTION ║
     ║ ●━━━━━━━━━║═══════════════════║━━━━━━━━━● ║
     ║ ●━━━━━━━━━║═══════════════════║━━━━━━━━━● ║
     ╚═══════════╝                   ╚═══════════╝
           │                               ▲
           ▼                               │
     ╔═══════════╗     ╔═══════════╗     ╔═══════════╗
     ║           ║     ║           ║     ║           ║
     ║  SPATIAL  ║════>║ TEMPORAL  ║════>║   EVENTS  ║
     ║           ║     ║           ║     ║           ║
     ╚═══════════╝     ╚═══════════╝     ╚═══════════╝
    

What is Spaxiom?

Spaxiom is a powerful Domain-Specific Language (DSL) designed for building intelligent systems that work with:

• Spatial Data: Zones, sensors, and physical spaces
• Temporal Logic: Time-based conditions and historical analysis
• Event Processing: Triggering actions based on complex conditions
• Entity Management: Tracking and querying objects in your system
• Physical Units: Working with measurements in a type-safe manner

With Spaxiom, you can easily define complex conditions that span across space and time, and connect them to real-world events.

Key Features

• 🏠 Spatial Zones: Define and work with 2D spatial regions
• ⚡ Sensors: Interface with various sensor types and data streams
• ⏱️ Temporal Logic: Create conditions that must be true for specific durations
• 🔄 Event Callbacks: Register event handlers triggered by complex conditions
• 👥 Entity Tracking: Maintain collections of entities with flexible attributes
• 📏 Physical Units: Work with measurements and conversions seamlessly
• 🧩 Logical Operators: Combine conditions using intuitive &, |, and ~ operators
• 📄 YAML Configuration: Define sensors and system setup through YAML files

Installation

pip install spaxiom

Quick Examples

Spatial & Temporal Logic

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

# Define a zone and sensor
office_zone = Zone(0, 0, 10, 10)
motion_sensor = Sensor("motion1", "motion", (5, 5, 0))

# Create condition based on sensor data
motion_detected = Condition(lambda: motion_sensor.read() > 0.5)

# Make it temporal - must be true for 5 seconds
sustained_motion = within(5.0, motion_detected)

# Register an event handler
@on(sustained_motion)
def alert_sustained_motion():
    print("Motion has been detected for 5 seconds!")

Entity Management

from spaxiom import EntitySet, Entity, exists, on, Condition

# Create a collection of entities
persons = EntitySet("Persons")

# Add entities with attributes
persons.add(Entity(attrs={"type": "person", "confidence": 0.9}))

# Create condition based on entity existence
person_detected = exists(persons, lambda p: p.attrs.get("confidence", 0) > 0.8)

# Register an event handler
@on(person_detected)
def alert_person():
    print("Person detected with high confidence!")

Physical Units

from spaxiom import Quantity

# Create measurements with units
distance = Quantity(10, "m")
time = Quantity(2, "s")

# Automatic unit conversion
speed = distance / time  # 5 m/s

# Convert to different units
speed_kph = speed.to("km/hour")  # 18 km/h

YAML Configuration

from spaxiom import load_sensors_from_yaml, on, Condition, within

# Load sensors from YAML configuration file
sensors = load_sensors_from_yaml("sensors_config.yaml")

# Access sensors by name from the registry
from spaxiom import SensorRegistry
registry = SensorRegistry()
motion_sensor = registry.get("motion_sensor1")

# Create condition based on sensor from config
motion_detected = Condition(lambda: motion_sensor.read() > 0.5)

# Register event handler
@on(motion_detected)
def alert_motion():
    print("Motion detected!")

Example YAML configuration:

sensors:
  - name: motion_sensor1
    type: gpio_digital
    pin: 17
    location: [0, 0, 0]
    pull_up: true
    
  - name: temperature_sensor1
    type: random
    location: [1, 2, 0]
    hz: 5.0

Documentation

Online Documentation

The full documentation is available online at: https://joescanlin.github.io/spaxiom-dsl/

Local Documentation

For local development, you can build and view the documentation using MkDocs:

# Install MkDocs and required extensions
pip install mkdocs-material pymdown-extensions

# Serve the documentation locally
mkdocs serve

# Build the documentation
mkdocs build

The documentation source files are located in the docs/ directory. Some key sections:

• Temporal and Entity Operations
• Quick Start Guide
• CLI Usage

Documentation Updates

The documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. Changes to files in the docs/ directory or to mkdocs.yml will trigger a new build and deployment.

License

MIT