How kabitacodeforge/industrial-ai-vision works
1. What this repository is
- This is an industrial PPE compliance system centered on real-time video inference. The core job is to detect people and safety gear such as helmets, vests, and boots from webcam or video input, then turn those detections into operational safety signals.
2. Primary runtime path
- The main data path starts in the vision layer: frames are captured from a camera or stream, passed through YOLO-based detection, and then annotated with overlays such as bounding boxes, FPS, timestamps, and status markers.
- The README emphasizes a standalone detection experience, while the file tree shows a broader system around that pipeline.
3. Vision subsystem
- vision/camera.py handles frame acquisition from physical cameras or video sources.
- vision/stream.py likely manages continuous streaming and frame delivery.
- vision/detector.py and vision/yolo_engine.py form the inference boundary, wrapping the Ultralytics YOLO model in models/yolov8n.pt.
- This layer is the main compute-heavy component and is where OpenCV and YOLO are directly used.
4. Model asset boundary
- models/yolov8n.pt is the packaged detector weight file.
- That makes the model an embedded local dependency rather than a remote service, so inference is likely done in-process on CPU or GPU depending on availability.
5. Core orchestration
- core/factory_loop.py appears to be the central runtime loop that ties vision output to business logic.
- core/state.py likely holds shared runtime state for the current frame, detection status, and system status.
- core/decision_engine.py converts raw detections into compliance decisions or safety events.
- core/alerts.py likely handles alarm/notification logic when violations are detected.
- core/analytics.py aggregates metrics over time, such as detection counts, compliance rates, or throughput.
- core/predictor.py suggests some forecasting or trend estimation on top of the live data.
6. Agent layer
- The agents/ directory indicates a higher-level abstraction above raw vision and core logic.
- agents/vision_agent.py likely wraps visual analysis tasks.
- agents/safety_agent.py likely focuses on PPE compliance interpretation and safety rule enforcement.
- agents/prediction_agent.py likely consumes historical or current signals to forecast outcomes.
- agents/energy_agent.py suggests a separate operational concern, possibly monitoring or optimizing resource usage.
- These agents imply a modular, decision-oriented design rather than a single monolithic detector.
7. Persistence and operational state
- core/database.py and factory.db show a local persistence layer, likely for events, detections, analytics summaries, or system state snapshots.
- This means the system is not purely transient; it retains operational history for dashboards or audits.
- The database is a local SQLite-style artifact rather than an external managed datastore, based on the presence of a single .db file.
8. API and application entrypoints
- api/main.py is likely the service-facing entrypoint for programmatic access to detections, metrics, or alert data.
- app/main.py appears to be a separate application entrypoint, possibly for the main runtime or UI service.
- The presence of multiple entrypoints suggests the system can be run as a detector, as an API service, and as a user-facing app.
9. Dashboard/UI layer
- dashboard/app.py is a distinct presentation boundary for visualizing system status, compliance, and analytics.
- This layer likely reads from the core/database/API rather than directly from the camera pipeline, which keeps visualization decoupled from inference.
10. End-to-end data flow
- Camera/video input enters the vision subsystem.
- YOLO detection produces structured objects like person/PPE detections.
- Core logic evaluates compliance, updates state, triggers alerts, and writes records.
- Analytics and predictor components summarize or forecast behavior.
- API/dashboard layers expose the resulting information to users or other systems.
11. Key architectural separation
- The repository cleanly separates perception (vision/), decision-making (core/), specialized agents (agents/), and presentation/integration (api/, dashboard/, app/).
- That separation matters for an architecture diagram because the frame stream, business logic, persistence, and UI are distinct concerns.
12. Deployment/runtime hints
- requirements.txt and the README point to a Python runtime using OpenCV and Ultralytics YOLO.
- The README notes GPU acceleration with CUDA as optional, with CPU fallback, so inference is designed to run locally across different hardware profiles.
- render.yaml indicates the project has at least one cloud deployment target or hosting configuration.
13. What to emphasize in a diagram
- Show the camera/video stream as the input source.
- Show the YOLO model as the inference engine inside the vision boundary.
- Show core decisioning/alerts/database as the processing and persistence layer.
- Show API/dashboard/app as consumers of stored or live system state.
- Show agents as orchestration or specialization layers above the core logic.
14. Overall shape
- This is best represented as a real-time edge AI pipeline with operational control layers, not just a computer vision demo.
- The main technical boundary is between the high-frequency frame processing path and the slower state, analytics, and presentation path.
Main entry points: factory_loop.py Factory loop · database.py Database · detector.py Detector · decision_engine.py Decision engine
Components 20
Vision
Frame capture, streaming, and YOLO inference
- Camera · Captures frames from camera or video input
vision/camera.py - Stream · Maintains continuous frame delivery
vision/stream.py - Detector · Coordinates object detection on incoming frames
vision/detector.py - YOLO engine · Wraps Ultralytics YOLO for in-process inference
vision/yolo_engine.py - YOLO weights · Packaged detector weights used by the inference engine
models/yolov8n.pt
Core
Decisioning, alerts, analytics, and persistence
- Factory loop · Main runtime loop connecting vision output to business logic
core/factory_loop.py - State · Holds current frame, status, and operational state
core/state.py - Decision engine · Turns detections into compliance decisions and events
core/decision_engine.py - Alerts · Emits alarms or violation notifications
core/alerts.py - Analytics · Aggregates detection and compliance metrics over time
core/analytics.py - Predictor · Produces trend or outcome predictions from system signals
core/predictor.py - Database · Stores events, summaries, and operational history
core/database.py - factory.db · Local database artifact for persisted records
factory.db
Agents
Specialized orchestration layers
- Vision agent · Higher-level wrapper for visual analysis tasks
agents/vision_agent.py - Safety agent · Interprets PPE compliance and safety rules
agents/safety_agent.py - Prediction agent · Consumes signals for forecasting and trend estimation
agents/prediction_agent.py - Energy agent · Handles operational or resource-efficiency concerns
agents/energy_agent.py
Connections 24
- Camera → Stream: frames · Raw frames flow into the stream pipeline
- Stream → Detector: frames · Continuous frames are handed to detection
- Detector → YOLO engine: infer · Detector delegates inference to the YOLO engine
- YOLO engine → YOLO weights: loads · Inference engine uses packaged model weights
- Detector → Factory loop: detections · Structured detections feed the main runtime loop
- Factory loop → State: updates · Loop maintains shared operational state
- Factory loop → Decision engine: evaluates · Runtime loop passes detections into policy logic
- Decision engine → Alerts: triggers · Policy outcomes can emit alerts
- Decision engine → Database: records · Decisions and events are persisted
- Alerts → Database: logs · Alerts are stored for audit and history
- Factory loop → Analytics: metrics · Operational signals feed analytics
- Analytics → Predictor: features · Historical metrics support forecasting
- Database → factory.db: writes · Persistence targets the local database file
- Vision agent → Detector: uses · Vision agent consumes detection capabilities
- Safety agent → Decision engine: uses · Safety agent relies on compliance logic
- Safety agent → Alerts: uses · Safety agent can surface violations
- Prediction agent → Predictor: uses · Prediction agent wraps forecasting behavior
- Energy agent → State: reads · Energy agent uses runtime state signals
- API → Database: reads · API exposes persisted operational data
- API → Analytics: serves · API can expose metrics and summaries
- Dashboard → Database: reads · Dashboard visualizes stored history and status
- Dashboard → Analytics: shows · Dashboard renders analytics views
- App → Factory loop: starts · Application entrypoint launches the runtime loop
- App → API: may host · App can coexist with or launch the API surface