Metadata-Version: 2.4
Name: fluxstate-edge
Version: 1.2.0
Summary: Zero-Trace Contextual Edge Video Analytics SDK
Author: FluxState Security Architecture
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/markdown
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: mediapipe>=0.10.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: pyaudio>=0.2.14
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: summary

# FluxState: Edge Intelligence SDK

[![PyPI version](https://badge.fury.io/py/fluxstate-edge.svg)](https://badge.fury.io/py/fluxstate-edge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests: Passing](https://img.shields.io/badge/Tests-Passing-brightgreen.svg)]()

**FluxState Edge** is an extensible, camera-agnostic video analytics SDK designed for integration into enterprise security backends. It processes RTSP streams locally on the edge, extracting behavioral metadata using a combination of object detection, 3D skeletal posing, audio processing, and VLM (Vision-Language Model) semantic reasoning.

---

## 🚀 Core Capabilities

- **Temporal Forensic Database:** Events and behavioral anomalies are logged directly into a local SQLite database (`core/forensics.py`). This creates a searchable text-based ledger of physical events.
- **Agentic VLM Reasoner (Preview):** The architecture includes scaffolding (`core/agent.py`) to pass complex spatial events to Vision-Language Models (e.g., Qwen2.5-VL) for deep contextual scene understanding.
- **C-Level Memory Mitigation:** FluxState uses `ctypes.memset` to manually zero out numpy array pixel buffers at the C-level immediately after inference to mitigate image retention in the Python heap.
- **Hardware Agnostic (RTSP):** Connects to existing IP cameras via standard RTSP URLs without requiring proprietary recording hardware.
- **Containerized Edge Deployment:** Includes a highly optimized `Dockerfile` for enterprise edge deployments (e.g., Kubernetes/Docker Swarm), solving native OS dependencies.

---

## 📦 Installation & Deployment

### Option A: Enterprise Docker Deployment (Recommended)
For production environments, use the provided Docker container to guarantee system dependencies (Tesseract, PortAudio) are perfectly locked.
```bash
docker build -t fluxstate-edge .
docker run -d --name fluxstate-edge fluxstate-edge
```

### Option B: Local Python Development
```bash
# macOS
brew install tesseract portaudio
# Linux
sudo apt-get install tesseract-ocr libportaudio2 libportaudiocpp0 portaudio19-dev

pip install fluxstate-edge
```

---

## 🛠️ SDK Integration

FluxState is designed to be embedded into your proprietary backend.

### Minimal 5-Line Integration
Create an entrypoint script (e.g., `main.py`):

```python
import time
from app import FluxStateNode

# Initialize the SDK
sdk = FluxStateNode()

# Define your integration hook
def handle_threat(event_payload):
    print(f"\n[INTEGRATION BUS] Threat Detected! Escalating to VMS...")
    print(f"Target Identity: {event_payload['entities']}")
    print(f"Behavioral Vector: {event_payload['context_log']}")

# Bind the hook to the SDK
sdk.on_threat_detected = handle_threat

# Deploy Headlessly (Runs as a background daemon)
sdk.start_headless_daemon()

try:
    while True: 
        time.sleep(1)
except KeyboardInterrupt:
    print("Shutting down SDK cleanly...")
    sdk.stop()
```

---

## 🧪 Testing
FluxState ships with an automated `pytest` suite covering the Forensic SQLite ledger and JSON intelligence policies.
```bash
pytest tests/
```

---

## 🛡️ Architecture Overview
Please refer to the `architecture.md` file in the source repository for a deeper dive into the threading model, the VLM integration pipeline, and the SQLite database schema.
