gitradar 0.1.5__py3-none-any.whl

demo/gitradar/web/app.py

@@ -0,0 +1,173 @@
+import asyncio
+import concurrent.futures
+from pathlib import Path
+from flask import Flask, render_template, request, jsonify, send_from_directory
+from gitradar.config import settings
+from gitradar.services.github import GitHubService
+from gitradar.services.llm import LLMService
+
+BASE_DIR = Path(__file__).parent
+
+
+def safe_run_async(coro):
+    """Run an async coroutine safely, handling cases where an asyncio event loop is already running (e.g. Vercel / ASGI)."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+            return executor.submit(asyncio.run, coro).result()
+    else:
+        return asyncio.run(coro)
+
+
+def create_app() -> Flask:
+    """Create and configure the Flask web application instance."""
+    app = Flask(
+        __name__,
+        template_folder=str(BASE_DIR / "templates"),
+        static_folder=str(BASE_DIR / "static"),
+    )
+
+    @app.route("/")
+    def index():
+        return render_template("index.html")
+
+    @app.route("/<path:filename>")
+    def serve_static_root(filename):
+        target = BASE_DIR / "static" / filename
+        if target.is_file():
+            return send_from_directory(BASE_DIR / "static", filename)
+        return jsonify({"error": "Not found"}), 404
+
+    @app.route("/api/config", methods=["GET"])
+    def get_config():
+        return jsonify({
+            "openai_configured": bool(settings.openai_api_key or settings.groq_api_key),
+            "groq_configured": bool(settings.groq_api_key),
+            "github_configured": bool(settings.github_token),
+            "default_model": settings.default_model,
+            "default_language": settings.default_language,
+            "max_repos_to_analyze": settings.max_repos_to_analyze,
+            "base_url": settings.openai_base_url,
+        })
+
+    @app.route("/api/analyze", methods=["POST"])
+    def analyze_idea():
+        data = request.get_json() or {}
+        idea = data.get("idea", "").strip()
+        limit = int(data.get("limit", 10))
+        model = data.get("model") or settings.default_model
+        language = data.get("language") or settings.default_language
+
+        def clean_key(v):
+            if not v:
+                return None
+            cleaned = str(v).replace("\r", "").replace("\n", "").replace("\t", "").strip().strip("'\"")
+            return cleaned if cleaned else None
+
+        # Extract user credentials and OpenAI-compatible endpoint from headers or JSON payload
+        api_key = clean_key(
+            request.headers.get("X-OpenAI-Api-Key")
+            or request.headers.get("X-Groq-Api-Key")
+            or data.get("openai_key")
+            or data.get("openaiKey")
+            or data.get("api_key")
+            or data.get("groq_key")
+            or data.get("groqKey")
+            or settings.openai_api_key
+            or settings.groq_api_key
+        )
+        base_url = clean_key(
+            request.headers.get("X-OpenAI-Base-Url")
+            or data.get("base_url")
+            or data.get("baseUrl")
+            or settings.openai_base_url
+        )
+        github_token = clean_key(
+            request.headers.get("X-Github-Token")
+            or data.get("github_token")
+            or data.get("githubToken")
+            or settings.github_token
+        )
+
+        if not idea:
+            return jsonify({"error": "Project idea parameter is required."}), 400
+
+        try:
+            llm_service = LLMService(api_key=api_key, base_url=base_url, model=model, language=language)
+            github_service = GitHubService(token=github_token)
+
+            # 1. Expand Queries
+            queries = llm_service.expand_idea_to_queries(idea, language=language)
+
+            # 2. Search GitHub Repositories
+            raw_repos = safe_run_async(
+                github_service.search_and_enrich(
+                    keywords=queries.search_keywords,
+                    topics=queries.github_topics,
+                    limit=max(limit * 2, 15),
+                )
+            )
+
+            try:
+                min_relevance = int(data.get("min_relevance") or data.get("minRelevance") or settings.min_relevance_threshold)
+            except (ValueError, TypeError):
+                min_relevance = settings.min_relevance_threshold
+
+            # 3. Relevance Evaluation & Hybrid Ranking
+            eval_repos = llm_service.evaluate_repository_relevance(idea, raw_repos, language=language)
+            repos = github_service.rank_and_sort_by_relevance(eval_repos, limit=limit, min_relevance=min_relevance)
+
+            # 4. Perform Gap Analysis
+            report = llm_service.analyze_market_and_gaps(idea, repos, language=language)
+
+            return jsonify({
+                "queries": queries.model_dump(),
+                "repositories": [r.model_dump() for r in repos],
+                "report": report.model_dump(),
+            })
+
+        except ValueError as ve:
+            return jsonify({"error": str(ve)}), 400
+        except Exception as e:
+            err_msg = str(e)
+            if any(k in err_msg.lower() for k in ["invalid_api_key", "invalid api key", "authentication", "unauthorized"]):
+                err_msg = "Invalid AI API Key! Please click the Settings Modal (⚙️) in the top-right corner and enter a valid API Key."
+            return jsonify({"error": err_msg}), 400
+
+    @app.route("/api/search", methods=["POST"])
+    def search_repos():
+        data = request.get_json() or {}
+        query = data.get("query", "").strip()
+        limit = int(data.get("limit", 10))
+        sort = data.get("sort", "stars")
+
+        def clean_key(v):
+            if not v:
+                return None
+            cleaned = str(v).replace("\r", "").replace("\n", "").replace("\t", "").strip().strip("'\"")
+            return cleaned if cleaned else None
+
+        github_token = clean_key(
+            request.headers.get("X-Github-Token")
+            or data.get("github_token")
+            or data.get("githubToken")
+            or settings.github_token
+        )
+
+        if not query:
+            return jsonify({"error": "Search query parameter is required."}), 400
+
+        try:
+            github_service = GitHubService(token=github_token)
+            repos = safe_run_async(github_service.search_repositories(query, limit=limit, sort=sort))
+            return jsonify({
+                "repositories": [r.model_dump() for r in repos]
+            })
+        except Exception as e:
+            return jsonify({"error": str(e)}), 500
+
+    return app

examples/python_sdk_usage.py

@@ -0,0 +1,48 @@
+"""
+Example script demonstrating programmatic usage of GitRadar Python SDK services.
+"""
+
+import asyncio
+from gitradar.services.github import GitHubService
+from gitradar.services.llm import LLMService
+from gitradar.utils import ui
+
+
+async def main():
+    idea = "AI powered automated documentation generator for Python repositories"
+    target_language = "Turkish"
+    
+    print(f"📡 Analyzing Project Idea via GitRadar SDK: '{idea}' (Language: {target_language})\n")
+
+    # 1. Initialize Services with custom response language
+    github_service = GitHubService()
+    llm_service = LLMService(language=target_language)
+
+    # 2. Expand Idea into Search Strategy
+    print("1️⃣ Generating search queries with LLM...")
+    queries = llm_service.expand_idea_to_queries(idea, language=target_language)
+    print(f"   Keywords: {queries.search_keywords}")
+    print(f"   Topics: {queries.github_topics}\n")
+
+    # 3. Search & Enrich Repositories
+    print("2️⃣ Fetching GitHub repositories asynchronously...")
+    repos = await github_service.search_and_enrich(
+        keywords=queries.search_keywords,
+        topics=queries.github_topics,
+        limit=5,
+    )
+    print(f"   Found {len(repos)} relevant repositories.\n")
+
+    # 4. Perform Gap Analysis & Implementation Guidance
+    print("3️⃣ Running Market & Gap Analysis...")
+    report = llm_service.analyze_market_and_gaps(idea, repos, language=target_language)
+
+    if report.implementation_guide:
+        print(f"   Recommended Stack: {report.implementation_guide.recommended_tech_stack}")
+
+    # 5. Display with GitRadar UI
+    ui.display_gap_report(report)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

gitradar/__init__.py

@@ -0,0 +1,22 @@
+"""
+GitRadar: Smart GitHub Market & Gap Analysis CLI tool.
+"""
+
+import sys
+import typing
+
+# Fix compatibility issue on Python < 3.11 where third-party packages (e.g. litellm)
+# attempt to import 'NotRequired' or other PEP 655/673 types directly from 'typing'.
+if sys.version_info < (3, 11):
+    try:
+        import typing_extensions
+
+        for _name in ("NotRequired", "Required", "Self", "Never", "LiteralString", "TypeAlias", "Override", "dataclass_transform"):
+            if not hasattr(typing, _name) and hasattr(typing_extensions, _name):
+                setattr(typing, _name, getattr(typing_extensions, _name))
+    except ImportError:
+        pass
+
+__version__ = "0.1.5"
+__author__ = "GitRadar Developer"
+

gitradar/cli.py

@@ -0,0 +1,214 @@
+import asyncio
+import webbrowser
+from typing import Optional
+import typer
+from rich.console import Console
+from rich.status import Status
+
+from gitradar import __version__
+from gitradar.config import settings, save_setting
+from gitradar.services.github import GitHubService
+from gitradar.services.llm import LLMService
+from gitradar.utils import ui
+from gitradar.web import create_app
+
+app = typer.Typer(
+    name="gitradar",
+    help="📡 GitRadar: GitHub Market & Gap Analysis CLI tool driven by AI & GitHub REST API.",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command(name="analyze", help="💡 Analyze a project idea, scan candidate repos, and generate a Market & Gap Report.")
+def analyze(
+    idea: str = typer.Argument(..., help="Project idea to analyze (e.g. 'AI code review tool for git hooks')"),
+    limit: int = typer.Option(10, "--limit", "-l", help="Maximum repositories to fetch and evaluate"),
+    min_relevance: int = typer.Option(50, "--min-relevance", "-r", help="Minimum relevance score threshold (0-100%)"),
+    model: Optional[str] = typer.Option(None, "--model", "-m", help="Override AI model (e.g. 'gpt-4o-mini', 'llama-3.3-70b-versatile')"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="Override OpenAI or compatible API Key"),
+    base_url: Optional[str] = typer.Option(None, "--base-url", "-u", help="Override OpenAI-compatible base URL"),
+    language: Optional[str] = typer.Option(None, "--lang", "--language", help="Output language for AI report (e.g. 'Turkish', 'English', 'Spanish')"),
+):
+    """Run full AI-driven market and gap analysis workflow on a project idea."""
+    ui.display_banner()
+
+    try:
+        llm_service = LLMService(api_key=api_key, base_url=base_url, model=model, language=language)
+        github_service = GitHubService()
+
+        # Step 1: Query Expansion with LLM
+        with Status("[bold cyan]🧠 Analyzing project idea with LLM & deriving search strategy...[/bold cyan]", spinner="dots"):
+            queries = llm_service.expand_idea_to_queries(idea, language=language)
+        
+        ui.display_query_strategy(queries)
+
+        # Step 2: GitHub Search & Enrichment
+        with Status(f"[bold cyan]🔍 Scanning GitHub repositories via REST API (Max: {limit})...[/bold cyan]", spinner="earth"):
+            candidate_repos = asyncio.run(
+                github_service.search_and_enrich(
+                    keywords=queries.search_keywords,
+                    topics=queries.github_topics,
+                    limit=max(limit * 2, 15),
+                )
+            )
+
+        if not candidate_repos:
+            ui.display_error("No relevant repositories found. Try phrasing your project idea with different terms.")
+            raise typer.Exit(code=1)
+
+        # Step 2b: Relevance Evaluation & Hybrid Ranking
+        with Status(f"[bold cyan]⚖️ Evaluating relevance match & filtering by threshold (≥{min_relevance}%)...[/bold cyan]", spinner="dots"):
+            evaluated_repos = llm_service.evaluate_repository_relevance(idea, candidate_repos, language=language)
+            repos = github_service.rank_and_sort_by_relevance(evaluated_repos, limit=limit, min_relevance=min_relevance)
+
+        ui.display_repo_table(repos, title=f"Repositories Related to '{idea}' (Threshold: ≥{min_relevance}%)")
+
+        # Step 3: Semantic Gap Analysis with LLM
+        with Status("[bold cyan]🎯 Semantically evaluating candidate repos & synthesizing Market & Gap Report...[/bold cyan]", spinner="bouncingBar"):
+            report = llm_service.analyze_market_and_gaps(idea, repos, language=language)
+
+        # Step 4: Display Final Report
+        ui.display_gap_report(report)
+
+    except ValueError as ve:
+        ui.display_error(str(ve))
+        raise typer.Exit(code=1)
+    except Exception as e:
+        ui.display_error(f"An unexpected error occurred: {str(e)}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="search", help="🔍 Perform a quick standalone GitHub repository search.")
+def search(
+    query: str = typer.Argument(..., help="Search query string or keywords"),
+    limit: int = typer.Option(10, "--limit", "-l", help="Maximum repositories to return"),
+    sort: str = typer.Option("stars", "--sort", "-s", help="Sort field (stars, forks, updated)"),
+):
+    """Fast standalone repository search without LLM synthesis."""
+    ui.display_banner()
+    github_service = GitHubService()
+
+    try:
+        with Status(f"[bold cyan]🔍 Searching GitHub for '{query}'...[/bold cyan]", spinner="dots"):
+            repos = asyncio.run(github_service.search_repositories(query, limit=limit, sort=sort))
+
+        ui.display_repo_table(repos, title=f"Search Results: '{query}'")
+
+    except Exception as e:
+        ui.display_error(f"GitHub Search Failed: {str(e)}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="ui", help="🌐 Launches local GitRadar web dashboard in your browser.")
+def ui_command(
+    port: int = typer.Option(5000, "--port", "-p", help="Port to run the local web server on"),
+    host: str = typer.Option("127.0.0.1", "--host", "-h", help="Host address to bind the web server"),
+    open_browser: bool = typer.Option(True, "--open/--no-open", help="Automatically open browser tab"),
+):
+    """Launch local Flask web application dashboard."""
+    ui.display_banner()
+    url = f"http://{host}:{port}"
+    console.print(f"[bold green]🚀 Launching GitRadar Web Dashboard at:[/bold green] [bold cyan]{url}[/bold cyan]")
+
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+
+    flask_app = create_app()
+    flask_app.run(host=host, port=port, debug=False)
+
+
+@app.command(name="config", help="⚙️ View or configure GitRadar API credentials and preferences.")
+def config_command(
+    show: bool = typer.Option(False, "--show", help="Display current configuration"),
+    openai_api_key: Optional[str] = typer.Option(None, "--openai-api-key", "-k", help="Save OpenAI or compatible API Key credential"),
+    base_url: Optional[str] = typer.Option(None, "--base-url", "-u", help="Save custom OpenAI-compatible Base URL (e.g. https://api.groq.com/openai/v1, http://localhost:11434/v1)"),
+    groq_api_key: Optional[str] = typer.Option(None, "--groq-api-key", help="Save Groq API Key credential (legacy / fallback)"),
+    github_token: Optional[str] = typer.Option(None, "--github-token", help="Save GitHub Access Token credential"),
+    default_model: Optional[str] = typer.Option(None, "--model", help="Save default AI model identifier (e.g. gpt-4o-mini, llama-3.3-70b-versatile)"),
+    default_language: Optional[str] = typer.Option(None, "--lang", "--language", help="Save default response language for AI reports"),
+):
+    """Manage GitRadar configuration."""
+    ui.display_banner()
+
+    updated = False
+    if openai_api_key:
+        save_setting("OPENAI_API_KEY", openai_api_key)
+        ui.display_info("OPENAI_API_KEY successfully saved! 🔑")
+        updated = True
+
+    if base_url:
+        save_setting("OPENAI_BASE_URL", base_url)
+        ui.display_info(f"OPENAI_BASE_URL saved as '{base_url}'! 🌐")
+        updated = True
+
+    if groq_api_key:
+        save_setting("GROQ_API_KEY", groq_api_key)
+        ui.display_info("GROQ_API_KEY successfully saved! 🔑")
+        updated = True
+
+    if github_token:
+        save_setting("GITHUB_TOKEN", github_token)
+        ui.display_info("GITHUB_TOKEN successfully saved! 🐙")
+        updated = True
+
+    if default_model:
+        save_setting("DEFAULT_MODEL", default_model)
+        ui.display_info(f"Default model saved as '{default_model}'! 🤖")
+        updated = True
+
+    if default_language:
+        save_setting("DEFAULT_LANGUAGE", default_language)
+        ui.display_info(f"Default language saved as '{default_language}'! 🌐")
+        updated = True
+
+    if show or not updated:
+        curr_settings = settings
+        grid = ui.Table(title="⚙️ Current GitRadar Configuration", header_style="bold yellow", expand=True)
+        grid.add_column("Parameter", style="bold cyan")
+        grid.add_column("Value", style="white")
+
+        openai_val = curr_settings.openai_api_key
+        masked_openai = f"{openai_val[:6]}...{openai_val[-4:]}" if openai_val and len(openai_val) > 10 else ("Configured" if openai_val else "[red]Not Configured[/red]")
+
+        groq_val = curr_settings.groq_api_key
+        masked_groq = f"{groq_val[:6]}...{groq_val[-4:]}" if groq_val and len(groq_val) > 10 else ("Configured" if groq_val else "[dim]Not Configured[/dim]")
+
+        base_url_val = curr_settings.openai_base_url or (
+            "https://api.groq.com/openai/v1 (Auto-routed from Groq Key)"
+            if not curr_settings.openai_api_key and curr_settings.groq_api_key
+            else "https://api.openai.com/v1 (Default)"
+        )
+
+        gh_val = curr_settings.github_token
+        masked_gh = f"{gh_val[:4]}...{gh_val[-4:]}" if gh_val and len(gh_val) > 8 else ("Configured (Anonymous Mode)" if not gh_val else "Configured")
+
+        grid.add_row("OPENAI_API_KEY", masked_openai)
+        if groq_val:
+            grid.add_row("GROQ_API_KEY (Legacy)", masked_groq)
+        grid.add_row("OPENAI_BASE_URL", base_url_val)
+        grid.add_row("GITHUB_TOKEN", masked_gh)
+        grid.add_row("DEFAULT_MODEL", curr_settings.default_model)
+        grid.add_row("DEFAULT_LANGUAGE", curr_settings.default_language)
+        grid.add_row("MAX_REPOS_TO_ANALYZE", str(curr_settings.max_repos_to_analyze))
+        grid.add_row("MIN_RELEVANCE_THRESHOLD", f"{curr_settings.min_relevance_threshold}%")
+
+        console.print(grid)
+
+
+@app.command(name="version", help="ℹ️ Display GitRadar version information.")
+def version():
+    """Display CLI version."""
+    ui.display_banner()
+    console.print(f"[bold cyan]GitRadar CLI Version:[/bold cyan] [bold white]v{__version__}[/bold white]")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

gitradar/config.py

@@ -0,0 +1,117 @@
+import os
+from pathlib import Path
+from typing import Optional
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+CONFIG_DIR = Path.home() / ".config" / "gitradar"
+CONFIG_FILE = CONFIG_DIR / "config.env"
+
+
+class Settings(BaseSettings):
+    openai_api_key: Optional[str] = None
+    openai_base_url: Optional[str] = None
+    groq_api_key: Optional[str] = None
+    github_token: Optional[str] = None
+    default_model: str = "gpt-4o-mini"
+    default_language: str = "English"
+    max_repos_to_analyze: int = 50
+    min_relevance_threshold: int = 50
+
+    model_config = SettingsConfigDict(
+        env_file=(str(CONFIG_FILE), ".env"),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @property
+    def effective_api_key(self) -> Optional[str]:
+        return self.openai_api_key or self.groq_api_key
+
+    @property
+    def effective_base_url(self) -> Optional[str]:
+        if self.openai_base_url:
+            return self.openai_base_url
+        if not self.openai_api_key and self.groq_api_key:
+            return "https://api.groq.com/openai/v1"
+        return None
+
+    @field_validator("max_repos_to_analyze", "min_relevance_threshold", mode="before")
+    @classmethod
+    def validate_int_settings(cls, v):
+        if v is None or (isinstance(v, str) and v.strip() == ""):
+            return 50 if "min_relevance" in str(v) else 10
+        try:
+            return int(v)
+        except (ValueError, TypeError):
+            return 50
+
+    @field_validator("openai_api_key", "openai_base_url", "groq_api_key", "github_token", "default_model", "default_language", mode="before")
+    @classmethod
+    def validate_empty_strings(cls, v):
+        if isinstance(v, str) and v.strip() == "":
+            return None
+        return v
+
+
+def load_settings() -> Settings:
+    """Load settings from env vars or config files safely."""
+    try:
+        s = Settings()
+    except Exception:
+        try:
+            s = Settings(_env_file=None)
+        except Exception:
+            s = Settings.model_construct(
+                openai_api_key=None,
+                openai_base_url=None,
+                groq_api_key=None,
+                github_token=None,
+                default_model="gpt-4o-mini",
+                default_language="English",
+                max_repos_to_analyze=50,
+                min_relevance_threshold=50,
+            )
+
+    if not s.openai_base_url:
+        s.openai_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get("OPENAI_API_BASE")
+    if not s.openai_api_key:
+        s.openai_api_key = os.environ.get("OPENAI_API_KEY")
+    if s.default_model == "gpt-4o-mini" and os.environ.get("OPENAI_MODEL"):
+        s.default_model = os.environ["OPENAI_MODEL"]
+    return s
+
+
+def save_setting(key: str, value: str) -> None:
+    """Save a setting key-value pair to user config file (~/.config/gitradar/config.env)."""
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        
+        existing_lines = []
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                existing_lines = f.readlines()
+                
+        key_upper = key.upper()
+        found = False
+        new_lines = []
+        
+        for line in existing_lines:
+            if line.strip().startswith(f"{key_upper}="):
+                new_lines.append(f"{key_upper}={value}\n")
+                found = True
+            else:
+                new_lines.append(line)
+                
+        if not found:
+            if new_lines and not new_lines[-1].endswith("\n"):
+                new_lines.append("\n")
+            new_lines.append(f"{key_upper}={value}\n")
+            
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            f.writelines(new_lines)
+    except Exception:
+        pass
+
+
+settings = load_settings()

gitradar/models.py

@@ -0,0 +1,67 @@
+from typing import Optional, List
+from pydantic import BaseModel, Field
+
+
+class RepositoryInfo(BaseModel):
+    """Model representing a GitHub repository summary."""
+    full_name: str
+    name: str
+    owner: str
+    html_url: str
+    description: Optional[str] = "No description provided"
+    stars: int = 0
+    forks: int = 0
+    language: Optional[str] = "Unspecified"
+    topics: List[str] = Field(default_factory=list)
+    updated_at: Optional[str] = ""
+    open_issues: int = 0
+    readme_snippet: Optional[str] = None
+    relevance_score: Optional[int] = Field(default=None, description="LLM evaluated relevance score 0-100%")
+    is_direct_competitor: Optional[bool] = Field(default=True, description="Whether repo directly addresses user idea concept")
+    relevance_reason: Optional[str] = Field(default=None, description="Brief explanation of relevance fit")
+    hybrid_score: Optional[float] = Field(default=0.0, description="Calculated hybrid ranking score")
+
+
+class ExpandedQueries(BaseModel):
+    """Model for LLM generated search strategy."""
+    search_keywords: List[str] = Field(default_factory=list, description="Optimized search keywords for GitHub REST API")
+    github_topics: List[str] = Field(default_factory=list, description="Relevant GitHub topics/tags")
+    target_languages: List[str] = Field(default_factory=list, description="Suggested or target programming languages")
+    search_explanation: str = Field(default="Search strategy generated.", description="Explanation of the search strategy")
+
+
+class CompetitorSummary(BaseModel):
+    """Model for a key competitor identified in gap analysis."""
+    repo_name: str = Field(default="Unknown Repository")
+    key_strengths: List[str] = Field(default_factory=list)
+    weaknesses_or_gaps: List[str] = Field(default_factory=list)
+
+
+class OpenSourceTool(BaseModel):
+    """Model representing a recommended open-source library or tool to build the project."""
+    name: str = Field(default="Open-Source Tool", description="Name of the open-source tool or library (e.g. Typer, Qdrant, Tree-sitter)")
+    category: str = Field(default="General", description="Category (e.g. CLI Framework, Vector DB, LLM SDK, Parser)")
+    description_and_usage: str = Field(default="", description="How to leverage this tool in building the project idea")
+    repo_url: Optional[str] = Field(default=None, description="GitHub repository or URL link if applicable")
+
+
+class ImplementationGuide(BaseModel):
+    """Model for architecture and technical implementation guidance."""
+    recommended_tech_stack: List[str] = Field(default_factory=list, description="Recommended technology stack (languages, frameworks, DBs)")
+    architecture_overview: str = Field(default="", description="High-level architecture and how the system should be structured")
+    open_source_building_blocks: List[OpenSourceTool] = Field(default_factory=list, description="Key open-source tools to use during development")
+
+
+class GapAnalysisReport(BaseModel):
+    """Model for LLM generated Market and Gap Analysis Report."""
+    idea_summary: str = Field(default="Project Idea Summary", description="Summary of the analyzed project idea")
+    market_saturation: str = Field(default="Moderate", description="Market Saturation level: Low, Moderate, or High")
+    saturation_score: int = Field(default=50, description="Market saturation score from 1-100")
+    market_summary: str = Field(default="Market analysis completed.", description="Overview of the current market and ecosystem")
+    top_competitors: List[CompetitorSummary] = Field(default_factory=list, description="Top competitor repositories and analysis")
+    unmet_needs: List[str] = Field(default_factory=list, description="Unmet needs and open gaps identified in existing repos")
+    differentiators: List[str] = Field(default_factory=list, description="Key differentiators to make your project stand out")
+    actionable_recommendations: List[str] = Field(default_factory=list, description="Actionable recommendations for the developer")
+    opportunity_score: int = Field(default=80, description="Opportunity potential score from 1-100")
+    implementation_guide: Optional[ImplementationGuide] = Field(default=None, description="Architecture, tech stack, and open source building blocks")
+

gitradar/prompts/__init__.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+from jinja2 import Environment, FileSystemLoader
+
+PROMPTS_DIR = Path(__file__).parent
+
+env = Environment(
+    loader=FileSystemLoader(PROMPTS_DIR),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+def render_prompt(template_name: str, **kwargs) -> str:
+    """Render a Jinja2 prompt template with the provided context variables."""
+    if not template_name.endswith(".j2"):
+        template_name += ".j2"
+    template = env.get_template(template_name)
+    return template.render(**kwargs)