update documentation and add tags

main.py

@@ -19,21 +19,77 @@ from dotenv import load_dotenv
 load_dotenv(override=True)
 
 
+# --- DOCUMENTATION METADATA ---
+tags_metadata = [
+    {
+        "name": "Live Stream Monitoring",
+        "description": "Real-time AI surveillance for RTSP cameras.",
+    },
+    {
+        "name": "Recorded Video Analysis",
+        "description": "Upload and process video files for theft detection.",
+    },
+]
+
 description = """
-### 🚀 Quick Start Guide for Non-Tech Users
+<details>
+<summary><b> USER GUIDE & ENDPOINT MANUAL (Click to Expand)</b></summary>
+
+<br>
+
+### 📽️ Section 1: Live Stream Monitoring
+*Use these endpoints to manage and watch live AI security feeds.*
+
+1. **`POST /stream/create` (Register Camera)**
+   - **What it does:** Saves your camera's RTSP address and location into the system.
+   - **How to use:** Enter a name (e.g., "Cashier-1"), the RTSP link from your camera, and the location.
+
+2. **`POST /stream/start/{id}` (Activate AI)**
+   - **What it does:** Powers up the AI "Brain" for a specific camera.
+   - **How to use:** Enter the ID (like `cam-1`). It returns a **view_url**. Paste this URL into a new browser tab to see the live AI.
+
+3. **`GET /stream/frame/{id}` (Main Video Feed)**
+   - **What it does:** The actual live video stream with AI boxes and the security card.
+   - **How to use:** This is the URL used by your browser or dashboard to display the video.
+
+4. **`GET /stream/list_cameras` (Camera Directory)**
+   - **What it does:** Displays a list of all added cameras.
+   - **How to use:** Use this to see which cameras are currently "Online" or to find a Camera ID.
+
+5. **`POST /stream/stop/{id}` (Deactivate AI)**
+   - **What it does:** Shuts down the AI processing for a camera to save computer resources.
+   - **How to use:** Enter the ID and click Execute. The camera will move to "Offline" status.
+
+<br>
+
+### 📁 Section 2: Recorded Video Analysis
+*Use these endpoints to scan uploaded files for theft incidents.*
+
+1. **`POST /video/detect` (Upload for Analysis)**
+   - **What it does:** Uploads a video file (MP4/MOV) to the server for a full AI scan.
+   - **How to use:** Select your video file and click Execute. You will receive a **job_id**.
+
+2. **`GET /video/status/{job_id}` (Check Progress)**
+   - **What it does:** Provides the scan percentage (0% to 100%) and current state.
+   - **How to use:** Enter your **job_id**. Once it reaches 100%, your file is ready.
+
+3. **`GET /video/jobs` (Task History)**
+   - **What it does:** Lists every video ever uploaded and whether the scan is finished or failed.
+   - **How to use:** Helpful for finding old `job_id`s or checking multiple scans at once.
 
-Welcome to the AI Theft Detection Hub. Follow these simple steps to use the system:
+4. **`GET /video/download/{job_id}` (Get Result)**
+   - **What it does:** Allows you to download the final processed video.
+   - **How to use:** Once status is 100%, enter the `job_id` here to save the analyzed video to your PC.
 
-#### 📽️ 1. How to Monitor a Live Stream
-1. **Add your Camera**: Go to the **POST** `/stream/create` section below. Click *Try it out*, enter a Name and your RTSP link, then click *Execute*.
-2. **Start the AI**: Go to the **POST** `/stream/start/{id}` section. Enter your Camera ID (e.g., `cam-1`) and click *Execute*. 
-3. **View the Stream**: Copy one of the URLs returned in the response (Hugging Face or Local) and paste it into a new browser tab to see the live AI analysis.
-4. **Discord Alerts**: If the system detects theft, a notification with a photo will be sent to your Discord channel automatically.
+<br>
 
-#### 📁 2. How to Analyze a Recorded Video
-1. **Upload Video**: Go to the **POST** `/video/detect` section. Click *Try it out*, choose your video file, and click *Execute*.
-2. **Check Progress**: Copy the `job_id` from the response. Go to **GET** `/video/status/{job_id}` to see the percentage completed.
-3. **Download Result**: Once the progress reaches `100%`, go to **GET** `/video/download/{job_id}` and click *Execute* to save your analyzed video.
+### 🔔 Section 3: Discord Notifications
+*Automatic alerts for security teams.*
+
+- **How it works:** Whenever the AI detects a theft (Live or Recorded), it takes a snapshot of the person and sends a high-priority alert card to your Discord channel.
+- **Requirement:** Ensure your `DISCORD_WEBHOOK_URL` is set in the system settings.
+
+</details>
 
 ---
 """
@@ -351,17 +407,17 @@ manager = StreamManager()
 async def root(): return RedirectResponse(url="/docs")
 
 # --- CAMERA ENDPOINTS ---
-@app.get("/stream/list_cameras")
+@app.get("/stream/list_cameras",  tags=["Live Stream Monitoring"])
 def get_cameras(): return {"cameras": list(MOCK_DB["cameras"].values())}
 
-@app.post("/stream/create")
+@app.post("/stream/create",  tags=["Live Stream Monitoring"])
 def create_camera(cam: CameraCreate):
     new_id = f"cam-{len(MOCK_DB['cameras']) + 1}"
     camera = {**cam.dict(), "id": new_id, "status": "offline", "isStreaming": False}
     MOCK_DB["cameras"][new_id] = camera
     return {"camera": camera}
 
-@app.post("/stream/start/{id}")
+@app.post("/stream/start/{id}",  tags=["Live Stream Monitoring"])
 async def start_camera(id: str, request: Request):
     if id not in MOCK_DB["cameras"]:
         raise HTTPException(404)
@@ -385,7 +441,7 @@ async def start_camera(id: str, request: Request):
         }
     }
 
-@app.post("/stream/stop/{id}")
+@app.post("/stream/stop/{id}",  tags=["Live Stream Monitoring"])
 def stop_camera(id: str):
     if id not in MOCK_DB["cameras"]:
         raise HTTPException(404)
@@ -395,7 +451,7 @@ def stop_camera(id: str):
         MOCK_DB["cameras"][id]["isStreaming"] = False
     return {"success": stopped}
 
-@app.get("/stream/frame/{id}")
+@app.get("/stream/frame/{id}",  tags=["Live Stream Monitoring"])
 def get_frame(id: str):
     if id not in manager.active_pipelines:
         raise HTTPException(404)
@@ -408,21 +464,8 @@ def get_frame(id: str):
             time.sleep(0.05)
     return StreamingResponse(generate(), media_type="multipart/x-mixed-replace; boundary=frame")
 
-@app.get("/cameras/{id}/frame")
-def get_frame_legacy(id: str):
-    if id not in manager.active_pipelines:
-        raise HTTPException(404)
-    def generate():
-        while id in manager.active_pipelines:
-            frame = manager.active_pipelines[id].latest_frame
-            if frame is not None:
-                _, buffer = cv2.imencode('.jpg', frame)
-                yield (b'--frame\r\nContent-Type: image/jpeg\r\n\r\n' + buffer.tobytes() + b'\r\n')
-            time.sleep(0.05)
-    return StreamingResponse(generate(), media_type="multipart/x-mixed-replace; boundary=frame")
-
 # --- VIDEO PROCESSING ENDPOINTS ---
-@app.post("/video/detect")
+@app.post("/video/detect", tags=["Recorded Video Analysis"])
 async def detect(background_tasks: BackgroundTasks, file: UploadFile = File(...)):
     jid = str(uuid.uuid4())
     in_p = os.path.join(UPLOAD_DIR, f"{jid}_{file.filename}")
@@ -435,15 +478,15 @@ async def detect(background_tasks: BackgroundTasks, file: UploadFile = File(...)
     background_tasks.add_task(lambda: asyncio.run(process_video_file(jid, in_p, out_p)))
     return {"job_id": jid}
 
-@app.get("/video/jobs")
+@app.get("/video/jobs", tags=["Recorded Video Analysis"])
 async def list_jobs():
     return [{"job_id": j, "status": d["status"], "progress": f"{d['progress']}%"} for j, d in jobs.items()]
 
-@app.get("/video/status/{job_id}")
+@app.get("/video/status/{job_id}", tags=["Recorded Video Analysis"])
 async def get_status(job_id: str):
     return jobs.get(job_id, {"error": "Not found"})
 
-@app.get("/video/download/{job_id}")
+@app.get("/video/download/{job_id}", tags=["Recorded Video Analysis"])
 async def download(job_id: str):
     if job_id in jobs and jobs[job_id]["status"] == "completed":
         return FileResponse(jobs[job_id]["output_path"])