Update README.md

README.md

@@ -7,67 +7,78 @@ sdk: docker
 app_port: 7860
 pinned: true
 license: mit
-short_description: A RESTful API for an InterFuser-based self-driving model.
+short_description: Hierarchical API for Interfuser-HDPE self-driving system.
 tags:
   - computer-vision
   - autonomous-driving
   - deep-learning
   - fastapi
   - pytorch
-  - interfuser
-  - graduation-project
   - carla
   - self-driving
+  - graduation-project
+  - control-systems
+  - object-tracking
 ---
 
-# 🚗 Baseer Self-Driving API
+# 🚗 Baseer Self-Driving API: The Hierarchical Brain
+
+**Service** | **Status**
+:--- | :---
+**API Status** | ✅ **Online & Ready**
+**Perception Engine** | 🧠 **[Interfuser-HDPE Model](https://huggingface.co/BaseerAI/Interfuser-Baseer-v1)**
+**Core Logic** | 🚀 **FastAPI, Python**
 
-| Service | Status |
-|---|---|
-| **API Status** | [![Status](https://img.shields.io/website?up_message=online&down_message=offline&url=https%3A%2F%2FBaseerAI-baseer-server.hf.space)](https://BaseerAI-baseer-server.hf.space) |
-| **Model** | [![Model](https://img.shields.io/badge/Model-Interfuser--Baseer--v1-blue)](https://huggingface.co/BaseerAI/Interfuser-Baseer-v1) |
-| **Frameworks** | [![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat&logo=fastapi)](https://fastapi.tiangolo.com/) [![PyTorch](https://img.shields.io/badge/PyTorch-%23EE4C2C.svg?style=flat&logo=PyTorch&logoColor=white)](https://pytorch.org/) |
+---
 
-## 📋 Project Description
+## 📋 Project Overview
 
-**Baseer** is an advanced self-driving system that provides a robust, real-time API for autonomous vehicle control. This Space hosts the FastAPI server that acts as an interface to the fine-tuned **[Interfuser-Baseer-v1](https://huggingface.co/BaseerAI/Interfuser-Baseer-v1)** model.
+Welcome to the **Baseer Self-Driving API**, the real-time, stateful decision-making engine for our advanced autonomous driving system. This Space hosts a high-performance FastAPI server that encapsulates the complete "brain" of our agent, going far beyond simple model inference.
 
-The system is designed to take a live camera feed and vehicle measurements, process them through the deep learning model, and return actionable control commands and a comprehensive scene analysis.
+This API orchestrates the entire driving task: it takes raw sensor data from a simulator like CARLA, processes it through our foundational **Interfuser-HDPE** perception model, and then uses our custom-built **Temporal Tracker** and **Hierarchical Controller** to output intelligent, safe, and interpretable driving commands.
 
 ---
 
-## 🏗️ Architecture
+## 🏗️ System Architecture: Where Perception Meets Control
 
-This project follows a decoupled client-server architecture, where the model and the application are managed separately for better modularity and scalability.
+Our system demonstrates a clean separation between the core perception model and the decision-making logic, which is hosted entirely within this Space.
 
 ```
-+-----------+    +------------------------+    +--------------------------+
-|           |    |                        |    |                          |
-|  Client   | -> |   Baseer API (Space)   | -> |  Interfuser Model (Hub)  |
-|(e.g.CARLA)|    |   (FastAPI Server)     |    | (Private/Gated Weights)  |
-|           |    |                        |    |                          |
-+-----------+    +------------------------+    +--------------------------+
-     HTTP              Loads Model                    Model Repository
-   Request
++-----------+ +------------------------------------+ +-------------------------+
+|           | |                                    | |                         |
+|  Client   | ----> |        Baseer API (This Space)        | ---> | Interfuser-HDPE Model |
+|(e.g.CARLA)| |     +--------------------------------+     | |   (Perception Engine)   |
+|           | HTTP  |        FastAPI Server         |     | |                         |
++-----------+ |     | + Identity-Aware Tracker ✅    |     | +-------------------------+
+              |     | + Hierarchical Controller ✅   |     |
+              |     +--------------------------------+     |
+              |                                            |
+              +--------------------------------------------+
 ```
 
-## ✨ Key Features
+The client sends sensor data, and this API orchestrates everything: it calls the perception model for analysis, then uses its internal stateful modules (Tracker and Controller) to make a final, context-aware decision.
+
+---
+
+## ✨ Key Features & Innovations
+
+This API's intelligence comes from our custom-built downstream modules:
+
+### 🧠 **Intelligent Hierarchical Controller**
+- **What it is:** A sophisticated decision-making module that operates on a clear hierarchy of rules: **`Safety First > Dynamic Obstacle Avoidance > Navigation`**.
+- **Why it matters:** This structured approach ensures predictable, safe behavior and avoids the pitfalls of overly simplistic controllers. It produces actions that are aware of the full driving context.
 
-### 🧠 **Advanced Perception Engine**
-- **Powered by:** The [Interfuser-Baseer-v1](https://huggingface.co/BaseerAI/Interfuser-Baseer-v1) model.
-- **Focus:** High-accuracy traffic object detection and safe waypoint prediction.
-- **Scene Analysis:** Real-time assessment of junctions, traffic lights, and stop signs.
+### 💡 **Cautious Memory for Occlusions**
+- **What it is:** Our controller features a short-term "grace period" memory. If a lead vehicle is temporarily occluded (e.g., behind a truck), the system remains cautious instead of accelerating dangerously into the unknown.
+- **Why it matters:** This elegantly solves the "deadly flutter" problem common in autonomous agents and drastically improves safety in dynamic traffic.
 
-### ⚡ **High-Performance API**
-- **Framework:** Built with **FastAPI** for high throughput and low latency.
-- **Stateful Sessions:** Manages multiple, independent driving sessions, each with its own tracker and controller state.
-- **RESTful Interface:** Intuitive and easy-to-use API design.
+### 👁️ **Identity-Aware Temporal Tracking**
+- **What it is:** A custom-built, object-oriented tracker that maintains a consistent ID for every vehicle in the scene.
+- **Why it matters:** It provides the stable, long-term context needed for our controller to make informed decisions about following, yielding, or reacting to specific agents in the environment.
 
-### 📊 **Comprehensive Outputs**
-- **Control Commands:** `steer`, `throttle`, `brake`.
-- **Scene Analysis:** Probabilities for junctions, traffic lights, and stop signs.
-- **Predicted Waypoints:** The model's intended path for the next 10 steps.
-- **Visual Dashboard:** A generated image that provides a complete, human-readable overview of the current state.
+### 🗣️ **Human-Readable Decisions**
+- **What it is:** The API doesn't just return numbers; it returns a `reason` string (e.g., `"Following vehicle ID 15"`, `"Slowing for red light"`, `"Cautious: Lost track of lead vehicle"`).
+- **Why it matters:** This provides unparalleled interpretability, making it easy to understand and debug the agent's behavior in real-time.
 
 ---
 
@@ -80,7 +91,7 @@ This will initialize a new set of tracker and controller instances on the server
 
 **Request:**
 ```bash
-curl -X POST "https://BaseerAI-baseer-server.hf.space/start_session"
+curl -X POST "https://baseerai-baseer-server.hf.space/start_session"
 ```
 
 **Example Response:**
@@ -96,7 +107,7 @@ Send the current camera view and vehicle measurements to be processed. The API w
 
 **Request:**
 ```bash
-curl -X POST "https://BaseerAI-baseer-server.hf.space/run_step" \
+curl -X POST "https://baseerai-baseer-server.hf.space/run_step" \
   -H "Content-Type: application/json" \
   -d '{
     "session_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
@@ -136,7 +147,7 @@ curl -X POST "https://BaseerAI-baseer-server.hf.space/run_step" \
     [10.0, 0.10]
   ],
   "dashboard_b64": "a-very-long-base64-string-representing-the-dashboard-image...",
-  "reason": "Red Light"
+  "reason": "Following vehicle ID 15"
 }
 ```
 
@@ -145,7 +156,7 @@ curl -X POST "https://BaseerAI-baseer-server.hf.space/run_step" \
 - **`scene_analysis`**: Probabilities for different road hazards. A high `traffic_light_state` value (e.g., > 0.5) indicates a red light.
 - **`predicted_waypoints`**: The model's intended path, relative to the vehicle.
 - **`dashboard_b64`**: A Base64-encoded JPEG image of the full dashboard view, which can be directly displayed in a client application.
-- **`reason`**: A human-readable string explaining the primary reason for the control action (e.g., "Following ID 12", "Red Light", "Cruising").
+- **`reason`**: A human-readable string explaining the primary reason for the control action (e.g., "Following vehicle ID 15", "Slowing for red light", "Cautious: Lost track of lead vehicle").
 
 ### 3. End the Session
 
@@ -153,7 +164,7 @@ This will clean up the session data from the server.
 
 **Request:**
 ```bash
-curl -X POST "https://BaseerAI-baseer-server.hf.space/end_session?session_id=a1b2c3d4-e5f6-7890-1234-567890abcdef"
+curl -X POST "https://baseerai-baseer-server.hf.space/end_session?session_id=a1b2c3d4-e5f6-7890-1234-567890abcdef"
 ```
 
 **Example Response:**
@@ -180,32 +191,39 @@ curl -X POST "https://BaseerAI-baseer-server.hf.space/end_session?session_id=a1b
 
 ## 🎯 Intended Use Cases & Limitations
 
-### ✅ Optimal Use Cases
-- Simulating driving in CARLA environments.
-- Research in end-to-end autonomous driving.
-- Testing perception and control modules in a closed-loop system.
-- Real-time object detection and trajectory planning.
+✅ **Optimal Use Cases**
+- **Closed-loop simulation** and evaluation of full-stack driving agents in CARLA.
+- **Researching the interplay between advanced perception and intelligent control.**
+- **Rapid prototyping** of complex driving behaviors (like cautious following, yielding, etc.).
+- Serving as a "smart agent" for creating dynamic traffic scenarios.
 
-### ⚠️ Limitations
-- **Simulation-Only:** Trained exclusively on CARLA data. Not suitable for real-world driving.
-- **Vision-Based:** Relies on a single front-facing camera and has inherent blind spots.
-- **No LiDAR:** Lacks the robustness of sensor fusion in adverse conditions.
+⚠️ **Limitations**
+- **Simulation-Only:** Designed for CARLA. Not for real-world vehicles.
+- **Rule-Based High-Level Logic:** The controller's decision-making, while advanced, is based on a deterministic, hierarchical rule set, not end-to-end learning.
+- **Vision-Based:** Inherits the limitations of its camera-only perception model in adverse weather or lighting.
 
 ---
 
-## 🛠️ Development
+## 🛠️ Development & Relation to Research
+
+This API is the practical, deployed application of the research conducted for an Artificial Intelligence graduation thesis. It serves as the "brain" that utilizes the perception outputs from our foundational model.
+
+- **Core Perception Model:** **[Interfuser-HDPE (Model Weights & Research)](https://huggingface.co/BaseerAI/Interfuser-Baseer-v1)**
+- **Core Logic:** The Tracker and Controller modules are custom Python implementations hosted in this Space.
+- **API Framework:** FastAPI
+
+## 👨‍💻 Development
 
-This project is part of a graduation thesis in Artificial Intelligence.
-- **Deep Learning:** PyTorch
-- **API Server:** FastAPI
-- **Image Processing:** OpenCV
-- **Scientific Computing:** NumPy
+- **Lead Researcher:** Adam Altawil
+- **Project Type:** Graduation Project - AI & Autonomous Driving
+- **Contact:** [Your Contact Information]
 
-## 📞 Contact
+## 📄 License
 
-For inquiries or support, please use the **Community** tab in this Space or open an issue in the project's GitHub repository (if available).
+This project is licensed under the MIT License.
 
 ---
 
-**Developed by:** Adam Altawil  
-**License:** MIT
+<div align="center">
+  <strong>🚗 Driving the Future with Hierarchical Intelligence 🚗</strong>
+</div>