Initial commit of SEO Analyzer FastAPI

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.env
+venv/
+.DS_Store

PROJECT_DOCS.md

@@ -0,0 +1,87 @@
+# 📘 SEO Keyword Analyzer API - Project Documentation
+
+## 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.
+
+---
+
+## 2. Directory Structure & File Explanation
+
+```
+SEO_Analyzer_FastAPI/
+├── main.py                 # 🚀 The Entry Point
+├── requirements.txt        # 📦 Dependencies
+├── models/
+│   └── schemas.py          # 🏗️ Data Structure (Validation)
+└── services/
+    └── analyzer.py         # 🧠 The Brain (AI Logic)
+```
+
+### 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.
+
+---
+
+## 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`.
+
+---
+
+## 4. How to Use & Run (Step-by-Step)
+
+### Step 1: Install Requirements
+Open your terminal in the project folder and run:
+```bash
+pip install -r requirements.txt
+```
+
+### 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.
+
+### 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!
+
+---
+
+## 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.

main.py

@@ -0,0 +1,30 @@
+from fastapi import FastAPI, HTTPException
+from models.schemas import SEORequest, SEOResponse
+from services.analyzer import analyze_seo_content
+import uvicorn
+import os
+
+app = FastAPI(
+    title="SEO Keyword Analyzer API",
+    description="Professional SEO Analysis using Generative AI",
+    version="1.0.0"
+)
+
+@app.get("/")
+def read_root():
+    return {"status": "active", "service": "SEO Analyzer API"}
+
+@app.post("/analyze-seo", response_model=SEOResponse)
+def analyze_seo(request: SEORequest):
+    """
+    Analyzes the provided content and returns a detailed SEO strategy.
+    """
+    result = analyze_seo_content(request.content)
+    
+    if "error" in result and result["error"]:
+        raise HTTPException(status_code=500, detail=result["error"])
+        
+    return result
+
+if __name__ == "__main__":
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

models/schemas.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+class KeywordData(BaseModel):
+    keyword: str
+    search_volume: str
+    competition: str
+    relevance: int
+
+class HashtagData(BaseModel):
+    tag: str
+    post_count: str
+
+class SEORequest(BaseModel):
+    content: str
+
+class SEOResponse(BaseModel):
+    core_keywords: List[KeywordData]
+    related_phrases: List[str]
+    viral_hashtags: List[HashtagData]
+    strategy_tips: List[str]
+    target_audience: str
+    error: Optional[str] = None

requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn
+google-generativeai
+python-dotenv
+pydantic

services/analyzer.py

@@ -0,0 +1,84 @@
+import os
+import json
+import google.generativeai as genai
+from dotenv import load_dotenv
+
+from pathlib import Path
+
+# Load .env from parent directory
+env_path = Path(__file__).resolve().parent.parent.parent / ".env"
+load_dotenv(dotenv_path=env_path)
+
+API_KEY = os.getenv("GEMINI_API_KEY")
+
+if API_KEY:
+    genai.configure(api_key=API_KEY)
+
+MODELS_FALLBACK = [
+    'gemini-2.0-flash',
+    'gemini-flash-latest',
+    'gemini-pro-latest'
+]
+
+def handle_api_error(e, model_name):
+    print(f"❌ Error with {model_name}: {e}")
+
+def analyze_seo_content(content: str) -> dict:
+    """
+    Analyzes content to generate SEO keywords, hashtags, and strategy.
+    Returns a dictionary matching the SEOResponse schema.
+    """
+    if not API_KEY:
+        return {"error": f"GEMINI_API_KEY not found. Looked in: {env_path}, File exists: {env_path.exists()}"}
+
+    prompt = f"""
+    You are a World-Class SEO Strategist & Data Scientist.
+    Analyze the following content/topic and generate a professional Keyword Strategy Report.
+    
+    Topic/Content: "{content[:2000]}"
+    
+    Output strictly valid JSON with this structure:
+    {{
+        "core_keywords": [
+            {{"keyword": "example 1", "search_volume": "High", "competition": "Medium", "relevance": 95}},
+            {{"keyword": "example 2", "search_volume": "Very High", "competition": "High", "relevance": 90}}
+        ],
+        "related_phrases": [
+            "phrase 1", "phrase 2", "phrase 3", "phrase 4", "phrase 5"
+        ],
+        "viral_hashtags": [
+            {{"tag": "#Example", "post_count": "1M+"}},
+            {{"tag": "#NicheTag", "post_count": "50K+"}}
+        ],
+        "strategy_tips": [
+            "Tip 1...", "Tip 2..."
+        ],
+        "target_audience": "Describe the ideal audience for this content."
+    }}
+
+    CRITICAL:
+    - METRICS: Estimate 'search_volume' (Low/Medium/High/Very High) and 'competition' based on industry knowledge.
+    - RELEVANCE: 0-100 score.
+    - Do NOT use markdown code blocks. Output RAW JSON only.
+    """
+
+    last_error = "No models attempted"
+    for model_name in MODELS_FALLBACK:
+        try:
+            model = genai.GenerativeModel(model_name)
+            response = model.generate_content(prompt)
+            
+            if response and response.text:
+                text = response.text.replace("```json", "").replace("```", "").strip()
+                try:
+                    data = json.loads(text)
+                    return data
+                except json.JSONDecodeError:
+                    last_error = "JSON Decode Error"
+                    continue # Try next model if JSON is broken
+        except Exception as e:
+            handle_api_error(e, model_name)
+            last_error = str(e)
+            continue
+            
+    return {"error": f"Analysis failed. Last error: {last_error}"}