---
title: Really AI
emoji: 🚀
colorFrom: indigo
colorTo: blue
sdk: docker
app_file: home.py
pinned: false
---

# Really AI

Really AI is an intelligent, direct-access conversational engine designed for technical support, Q&A, and general chat. It combines a sophisticated custom NLP pipeline with real-time system monitoring and secure user authentication.

## 🌟 Key Features

*   **Intelligent NLP Pipeline:** Advanced Arabic/English text normalization, tokenization, and intent classification.
*   **Direct Knowledge Access:** Real-time search across the `data.json` knowledge base for consistent and instant responses.
*   **Real-Time Processing:** Visual feedback of the generation process, including steps and progress.
*   **Performance Metadata:** Detailed info for every message, including generation time (duration) and token count.
*   **Secure & Private:** Implements robust password hashing and persistent conversation history.
*   **System Awareness:** Real-time monitoring of CPU/RAM usage and built-in tools for time/date reporting.
*   **Resilient Design:** Data synchronization with Hugging Face Hub, ensuring persistence even in ephemeral deployment environments (e.g., Dockerized Spaces).
*   **Multi-Tier Model Selection:** Five processing tiers balancing speed and depth:
    *   **Flash Lite (10s)**: High-speed optimized search.
    *   **Flash (30s)**: Standard balanced search.
    *   **Medium (10m)**: Deep background processing.
    *   **Pro (30m)**: Advanced background analysis.
    *   **Pro Max (5h)**: Exhaustive background processing.
*   **Modern UI:** A polished, glassmorphism-based interface with smooth stream-processing and interactive feedback.

## 🛠 Tech Stack

*   **Backend:** Python 3.9+, Flask, Flask-Session, Werkzeug
*   **Search/NLP:** Custom engine using `SequenceMatcher`, `re`, `Counter`
*   **Monitoring:** `psutil`
*   **Integrations:** `huggingface_hub` for dataset/model storage
*   **Frontend:** Vanilla HTML/CSS/JS, FontAwesome, Google Fonts
*   **Deployment:** Docker, optimized for Hugging Face Spaces

## 🏗 System Architecture

The application operates as an event-driven system:

1.  **Request Flow:** User input is processed via a multi-stage pipeline (Normalization → Direct Data Search → Sentiment Analysis).
2.  **Streaming:** Responses are streamed back via NDJSON for a fluid user experience.
3.  **Background Tasks:** A worker thread handles long-running "Medium", "Pro", and "Pro Max" queries, allowing users to return later for their answers.
4.  **Sync & Persistence:** All state (users, conversations, knowledge data) is persisted in local JSON files and synced to a remote Hugging Face dataset repository.

## 📜 API Reference

| Endpoint | Method | Description |
| :--- | :--- | :--- |
| `/chat` | POST | Main interface; streams AI responses as NDJSON. |
| `/auth/login` | POST | Authenticates user and initializes session. |
| `/auth/signup` | POST | Registers new user credentials. |
| `/status` | GET | Returns real-time system metrics and usage quota. |
| `/tasks` | GET | Returns current user's background task status. |
| `/history` | GET | Returns current user's conversation history. |

## 🤝 Contribution

Contributions to the NLP core or the UI/UX are highly appreciated. Please open an issue to discuss significant changes before submitting a PR.