# rule_engine

**Repository Path**: J12_Kyrie/rule_engine

## Basic Information

- **Project Name**: rule_engine
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-11
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

MQTT -> Rule Engine -> Proto -> gRPC Orchestrator
===============================================

Purpose
- Lightweight pipeline for testing: publish detection JSON to an MQTT broker, run rule logic to detect door-open collisions, convert alerts to a protobuf Alert message and deliver them to a simple gRPC orchestrator.

Repository files created
- alert.proto — protobuf definitions (Alert, Detection, BBox, Ack, Orchestrator service)
- requirements.txt — recommended Python packages
- orchestrator_server.py — minimal gRPC server that prints received Alert messages and returns Ack
- mqtt_to_grpc_bridge.py — subscribes to MQTT topic, runs rule_door_collision.check_door_collision, maps alerts to proto and sends via gRPC
- publish_to_mqtt.py — (already present) test publisher that publishes detection_results.json
- rule_door_collision.py — rule logic used by the bridge (already present)

Quick start (developer)
1. Ensure MQTT broker is running locally (mosquitto on localhost:1883). If you don't have mosquitto installed, you can install and start it as follows:
   - Install (Debian/Ubuntu):
     sudo apt update && sudo apt install -y mosquitto mosquitto-clients
   - Start as a system service:
     sudo systemctl start mosquitto
     sudo systemctl enable mosquitto
     sudo systemctl status mosquitto
   - Run in the foreground for quick debugging:
     mosquitto -v
   - Or run via Docker (no installation required on host):
     docker run -it --rm -p 1883:1883 eclipse-mosquitto

2. Install dependencies (you said you'll manage this):
   pip install -r requirements.txt

3. Generate Python protobuf/grpc stubs from the proto:
   python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. alert.proto
   This creates alert_pb2.py and alert_pb2_grpc.py which are required by the server and bridge.

4. Start orchestrator server (terminal 1):
   python orchestrator_server.py
   - Binds to 127.0.0.1:50051. It prints a summary of each Alert it receives.

5. Start the bridge (terminal 2):
   python mqtt_to_grpc_bridge.py
   - Subscribes to topic "yolo/detections" on localhost:1883.
   - On incoming messages it runs the rule logic and calls the orchestrator over gRPC.

6. Send test message (terminal 3):
   python publish_to_mqtt.py
   - Publishes JSON from detection_results.json to topic "yolo/detections".

Expected behavior
- publish_to_mqtt.py publishes to MQTT.
- mqtt_to_grpc_bridge.py receives the message, extracts detections, runs check_door_collision(detections).
- For each alert produced, the bridge maps it into the Alert proto and calls Orchestrator.PublishAlert.
- orchestrator_server.py logs the alert and returns Ack(ok=True, message="received"). Bridge logs the ack.

Proto mapping summary (JSON -> Alert proto)
- Alert.event_id <- event_id (payload or top-level) or "001" default
- Alert.event_type <- alert_dict['event'] (e.g., "door_open_collision_alert")
- Alert.source, priority, timestamp, image_path <- from incoming message
- Alert.detections <- list of Detection where Detection.class_name = detection['class'], confidence and bbox copied
- Alert.car_bbox, Alert.person_bbox, Alert.iou <- copied from individual alert returned by the rule logic

Notes & troubleshooting
- If you see ImportError complaining about alert_pb2 or alert_pb2_grpc, run the protoc command in step 3.
- If python -m grpc_tools.protoc fails with "No module named grpc_tools", install grpcio-tools.
- If MQTT messages are not received, confirm mosquitto is running and reachable on localhost:1883.
- The gRPC channel is insecure (plain TCP) for local testing. For TLS, the proto/service is the same; you must add credentials and adjust client/server channels.

Possible extensions
- Batch alerts: change proto to carry repeated Alert in one RPC (one call per MQTT message).
- Add persistence, logging to file, or forwarding the alert to other services.
- Add TLS and/or authentication on gRPC.

Current status (what I created)
- [x] alert.proto
- [x] requirements.txt
- [x] orchestrator_server.py
- [x] mqtt_to_grpc_bridge.py
- [x] README.md (this file)

Remaining steps for you
- [ ] Install dependencies: pip install -r requirements.txt
- [ ] Generate stubs: python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. alert.proto
- [ ] Run end-to-end test (start orchestrator, start bridge, run publish_to_mqtt.py)

If you want any of the remaining steps automated here (install deps, run protoc, run tests), toggle to Act mode and allow me to run the requested commands. Otherwise run the three remaining commands locally and paste back any logs/errors you want me to help troubleshoot.