Update docs with A-Z guide

PROJECT_DOCS.md

@@ -1,87 +1,116 @@
-# 📘 SEO Keyword Analyzer API - Project Documentation
+# 📘 SEO Keyword Analyzer API - Complete Development Guide
 
 ## 1. Project Overview
-This project is a high-performance **Microservice** built with **FastAPI**. Its purpose is to act as an intelligent SEO (Search Engine Optimization) consultant. It accepts raw text (like a video topic or blog idea) and uses Google's **Gemini Generative AI** to output a structured strategy containing keywords, viral hashtags, and target audience analysis.
+This project is an **AI-Powered Microservice** built with **FastAPI**. It serves as an intelligent SEO consultant that accepts a topic (e.g., "Digital Marketing") and generates a comprehensive strategy including:
+- High-volume Keywords
+- Viral Hashtags
+- Competition Analysis
+- Strategic Tips
+
+**Key Feature:** Unlike traditional wrapper APIs, this project uses a **Local LLM (TinyLlama-1.1B)** embedded directly within the application. It does **not** rely on external paid APIs (like OpenAI or Gemini), ensuring it is:
+- **Free to run** (no per-token cost).
+- **Private** (data doesn't leave the container).
+- **Self-contained**.
+
+---
+
+## 2. Technology Stack used
+We used the following technologies to build this application from scratch:
+
+| Component | Technology | Purpose |
+| :--- | :--- | :--- |
+| **Framework** | **FastAPI** | High-performance web framework for building the API endpoints. |
+| **AI Model** | **TinyLlama-1.1B-Chat** | A compact, powerful open-source LLM optimized for chat and instruction following. |
+| **ML Library** | **Hugging Face Transformers** | To load and run the model locally. |
+| **Compute** | **PyTorch (CPU/GPU)** | The underlying tensor computation engine. |
+| **Container** | **Docker** | To package the application with all dependencies for cloud deployment. |
+| **Deployment** | **Hugging Face Spaces** | The cloud platform hosting the Docker container. |
 
 ---
 
-## 2. Directory Structure & File Explanation
+## 3. Directory Structure Explaination
+Here is how the project files are organized:
 
 ```
 SEO_Analyzer_FastAPI/
-├── main.py                 # 🚀 The Entry Point
-├── requirements.txt        # 📦 Dependencies
+├── main.py                 # � Entry Point: Defines the API routes & server.
+├── requirements.txt        # 📦 Dependencies: Lists libraries (torch, fastapi, etc.).
+├── Dockerfile              # 🐳 Deployment: Instructions to build the Linux container.
 ├── models/
-│   └── schemas.py          # 🏗️ Data Structure (Validation)
+│   └── schemas.py          # 📝 Data Models: Pydantic classes to validate input/output.
 └── services/
-    └── analyzer.py         # 🧠 The Brain (AI Logic)
+    └── analyzer.py         # 🧠 The Brain: Loads the AI model and handles inference.
 ```
 
-### A. `main.py` (The Traffic Controller)
-This is where the application starts.
-- **FastAPI App**: Initializes the web server.
-- **Endpoint `/analyze-seo`**: A specific "door" where users send data.
-- **Logic**: When a request comes in, it checks the data format and passes it to the *Brain* (`analyzer.py`).
-
-### B. `models/schemas.py` (The Blueprint)
-This file defines exactly what data looks like using **Pydantic**.
-- `SEORequest`: Ensures the user sends a JSON with a `"content"` field (String).
-- `SEOResponse`: Ensures the API returns a standard format (Keywords, Hashtags, Tips) so the frontend never crashes.
+---
 
-### C. `services/analyzer.py` (The Brain)
-This contains the core business logic.
-- **Loading Environment**: Finds your `.env` file to get the Secret Key.
-- **Prompt Engineering**: Constructs a strict prompt telling the AI to act as an "SEO Strategist".
-- **AI Call**: Sends the prompt to Google Gemini.
-- **JSON Parsing**: Takes the AI's raw text response and converts it into a clean Python Dictionary.
+## 4. How It Was Built (A to Z)
+
+### Step 1: Defining the Data Structure (`models/schemas.py`)
+Before writing code, we defined what the "Input" and "Output" should look like using **Pydantic**.
+- **Input**: A simple JSON object `{"content": "..."}`.
+- **Output**: A strict JSON schema ensuring the UI always receives `core_keywords`, `hashtags`, etc.
+
+### Step 2: Building the Logic Core (`services/analyzer.py`)
+This is the most complex part. Instead of calling an external API, we:
+1.  **Initialize the Model**: On startup, we download `TinyLlama/TinyLlama-1.1B-Chat-v1.0` using `AutoModelForCausalLM`.
+2.  **Pipeline Creation**: We set up a Hugging Face `pipeline("text-generation")` to handle the complexity of tokenization and prediction.
+3.  **Prompt Engineering**: We crafted a specific "System Prompt" that forces the AI to act as an SEO expert and output **strict JSON**.
+    > *"You are a professional SEO Data Scientist. You ONLY speak in valid JSON..."*
+4.  **Parsing**: The model outputs raw text. We wrote a helper function `clean_json_string` to strip away markdown code blocks and extract the pure JSON data for the API response.
+
+### Step 3: Creating the API Endpoints (`main.py`)
+We created a FastAPI app with two routes:
+- `GET /`: A health check to confirm the server is running.
+- `POST /analyze-seo`: The main worker. It:
+    1.  Receives the user's text.
+    2.  Validates it against our Schema.
+    3.  Passes it to the `analyzer.py` brain.
+    4.  Returns the structured results.
+
+### Step 4: Dockerization (`Dockerfile`)
+To make this run anywhere (local PC, Cloud, Hugging Face), we packaged it in a Docker container.
+- **Base Image**: `python:3.9`
+- **User Permissions**: Sets up a non-root user (id 1000) for security (required by HF Spaces).
+- **Commands**: Installs `requirements.txt` and starts the `uvicorn` server on port **7860**.
 
 ---
 
-## 3. How the Logic Works (A to Z)
-
-1.  **Request**: You send `POST /analyze-seo` with `{"content": "youtube automation"}`.
-2.  **Validation**: `main.py` uses `schemas.py` to confirm you sent text, not a number or empty file.
-3.  **Processing**:
-    - The code calls `analyze_seo_content("youtube automation")`.
-    - It builds a prompt: *"Analyze 'youtube automation' and give me high-volume keywords..."*
-4.  **AI Interaction**:
-    - The system tries to connect to `gemini-2.0-flash`.
-    - If that model is busy or broken (404), it automatically loops to the next backup model (`gemini-flash-latest`).
-    - This "Fallback Loop" ensures high reliability.
-5.  **Response Handling**:
-    - The AI returns a JSON-formatted string.
-    - Python parses this string.
-    - The function returns the data.
-6.  **Response**: You receive the JSON data with code `200 OK`.
+## 5. How It Works (The Flow)
+
+1.  **User Action**: Sends a request: `POST {"content": "dropshipping"}`.
+2.  **API Layer**: FastAPI validates the request.
+3.  **Buisness Logic**:
+    - The `analyzer` constructs a prompt.
+    - The **TinyLlama** model runs the prompt through its neural network (locally on CPU).
+    - The model generates a comprehensive analysis in text format.
+4.  **Processing**: Python extracts the JSON from the text.
+5.  **Response**: The user receives a clean JSON response with keywords, hashtags, and tips.
 
 ---
 
-## 4. How to Use & Run (Step-by-Step)
+## 6. How to Run Locally
 
-### Step 1: Install Requirements
-Open your terminal in the project folder and run:
-```bash
-pip install -r requirements.txt
-```
+1.  **Install Requirements**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+    *(Note: This installs PyTorch, which is large ~2GB)*
 
-### Step 2: Run the Server
-Start the API server (Uvicorn):
-```bash
-python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
-```
-- `host 0.0.0.0`: Allows it to work on LAN (WiFi).
-- `reload`: Updates automatically when you save code.
+2.  **Run the Server**:
+    ```bash
+    python -m uvicorn main:app --reload
+    ```
 
-### Step 3: Test with Swagger UI
-1.  Open your browser to: **[http://localhost:8000/docs](http://localhost:8000/docs)**
-2.  Click **POST /analyze-seo**.
-3.  Click **Try it out**.
-4.  Enter your topic in the "content" field.
-5.  Click **Execute**.
-6.  See the results below!
+3.  **Access Documentation**:
+    Open your browser to `http://localhost:8000/docs` to see the interactive Swagger UI.
 
 ---
 
-## 5. Troubleshooting
-- **Error 500 "GEMINI_API_KEY not found"**: correct: Ensure your `.env` file is in the parent directory or properly loaded in `analyzer.py`.
-- **404 Model Not Found**: The code handles this by trying multiple models, but ensure `MODELS_FALLBACK` contains valid model names correctly.
+## 7. Configuration Limitations
+- **Hardware**: Running a 1.1 Billion parameter model requires about **3GB of RAM**.
+- **Speed**: On a standard CPU, generation might take 10-30 seconds. On a GPU, it takes <2 seconds.
+- **Max Length**: The model is configured to generate up to 1024 new tokens.
+
+---
+**Developed by Ihtesham | Powered by Open Source AI**