Update docs to reflect Qwen-0.5B Local CPU architecture

PROJECT_DOCS.md

@@ -7,10 +7,10 @@ This project is an **AI-Powered Microservice** built with **FastAPI**. It serves
 - Competition Analysis
 - Strategic Tips
 
-**Key Feature:** This project leverages the **Qwen2.5-7B-Instruct** model, a state-of-the-art open-source LLM. Instead of running a heavy model locally, it connects to **Hugging Face's Serverless Inference API** to provide:
-- **High Intelligence**: Comparable to GPT-3.5/4 for reasoning.
-- **Speed**: Massive GPU acceleration without needing a local GPU.
-- **Reliability**: Always-on availability.
+**Key Feature:** This project runs the **Qwen2.5-0.5B-Instruct** model **LOCALLY** inside the container.
+- **Zero External Dependencies**: It does NOT use an external API. The brain lives inside the app.
+- **100% Free**: No rate limits, no credit usage.
+- **Privacy**: Data never leaves your container.
 
 ---
 
@@ -33,12 +33,12 @@ Here is how the project files are organized:
 ```
 SEO_Analyzer_FastAPI/
 ├── main.py                 # 🚦 Entry Point: Defines the API routes & server.
-├── requirements.txt        # 📦 Dependencies: Lists libraries (huggingface_hub, fastapi, etc.).
+├── requirements.txt        # 📦 Dependencies: Lists libraries (torch, transformers, fastapi).
 ├── Dockerfile              # 🐳 Deployment: Instructions to build the Linux container.
 ├── models/
 │   └── schemas.py          # 📝 Data Models: Pydantic classes to validate input/output.
 └── services/
-    └── analyzer.py         # 🧠 The Brain: Loads the AI model and handles inference.
+    └── analyzer.py         # 🧠 The Brain: Loads the Local Model and handles inference.
 ```
 
 ---
@@ -51,23 +51,21 @@ Before writing code, we defined what the "Input" and "Output" should look like u
 - **Output**: A strict JSON schema ensuring the UI always receives `core_keywords`, `hashtags`, `relevance` scores, etc.
 
 ### Step 2: Building the Logic Core (`services/analyzer.py`)
-This is the most complex part. We use the **Hugging Face Inference Client**:
-1.  **Connection**: We initialize `InferenceClient(model="Qwen/Qwen2.5-7B-Instruct")`. This connects roughly to a cluster of A100 GPUs.
-2.  **Prompt Engineering (The "Big Brain")**: We don't just ask "give me keywords". We send a **System Prompt** that instructs the AI:
-    > *"You are a World-Class SEO Strategist & Data Scientist... Analyze User Intent... Estimate metrics..."*
-    This ensures the output is professional-grade, not generic.
-3.  **Chat Completion**: We use the `chat_completion` API format (`messages=[{"role": "system"...}, {"role": "user"...}]`) which Qwen understands perfectly.
-4.  **Parsing**: The model outputs a JSON string. We parse this into a Python dictionary.
+This is the heart of the "Local AI" engine:
+1.  **Loading**: On startup, we use `transformers.pipeline` to download `Qwen2.5-0.5B` (approx 1GB).
+2.  **Inference**: When a request comes in, the **CPU** runs the mathematical calculations to generate text.
+3.  **Optimization**: We use `torch_dtype=bfloat16` to make it run faster and use less RAM.
+4.  **Temperature Control**: We set `temperature=0.3` to make the AI strict and reliable for JSON.
 
 ### Step 3: Creating the API Endpoints (`main.py`)
 We created a FastAPI app with two routes:
 - `GET /`: A health check.
-- `POST /analyze-seo`: The main worker. It has robust error handling (`try/except`) to catch any API issues and report them clearly.
+- `POST /analyze-seo`: The main worker. It includes a **Safety Net** that auto-fills missing data if the AI makes a mistake.
 
 ### Step 4: Dockerization (`Dockerfile`)
 To make this run on the cloud:
 - **Base Image**: `python:3.9`
-- **Optimization**: We removed heavy libraries like `torch` and `transformers`. The container is now very small and fast because the AI runs remotely.
+- **Dependency**: We install `torch` (PyTorch) so the AI can run mathematically.
 - **Port**: Exposes port **7860** for Hugging Face Spaces.
 
 ---
@@ -75,14 +73,13 @@ To make this run on the cloud:
 ## 5. How It Works (The Flow)
 
 1.  **User Action**: Sends a request: `POST {"content": "dropshipping"}`.
-2.  **API Layer**: FastAPI validates the request.
-3.  **Business Logic**:
-    - The `analyzer` constructs the detailed "Strategic Prompt".
-    - It sends this prompt securely to Hugging Face's API.
-    - **Qwen-7B** (running on powerful cloud GPUs) analyzes the text.
-    - It returns a structured JSON response.
-4.  **Processing**: Python validates the fields.
-5.  **Response**: The user receives the data with keyword volumes, competition, and strategy.
+2.  **API Layer**: FastAPI receives it.
+3.  **Local Inference**:
+    - The server passes the text to the loaded Qwen model.
+    - The **CPU** generates the response token-by-token.
+    - This takes ~10-20 seconds.
+4.  **Parsing & Repair**: The app cleans the JSON and fixes any syntax errors automatically.
+5.  **Response**: The user receives the data.
 
 ---
 
@@ -93,16 +90,13 @@ To make this run on the cloud:
     pip install -r requirements.txt
     ```
 
-2.  **Set Environment Variables**:
-    Create a `.env` file and add your token:
-    ```
-    HF_TOKEN=hf_...
-    ```
+2.  **No Keys Needed**: You do NOT need an API key. It runs locally.
 
 3.  **Run the Server**:
     ```bash
     python -m uvicorn main:app --reload
     ```
+    *Note: The first run will download the model (1GB).*
 
 4.  **Access Documentation**:
     Open `http://localhost:8000/docs`.
@@ -110,8 +104,8 @@ To make this run on the cloud:
 ---
 
 ## 7. Configuration Limitations
-- **Rate Limits**: The free Serverless API has rate limits. If you spam it, you might get a 429 error. Adding your `HF_TOKEN` increases these limits.
-- **Model Choice**: We selected `Qwen2.5-7B-Instruct` because it is currently the best performing 7B model available on the free tier.
+- **CPU Speed**: Since it runs on a free CPU, we limit generation to **30 keywords** to ensure it finishes quickly.
+- **Model Choice**: We used the **0.5B (Nano)** model because it is the only modern LLM that fits comfortably in the free tier RAM while remaining fast.
 
 ---
 **Developed by Ihtesham | Powered by Open Source AI**