gitradar 0.1.5__py3-none-any.whl

demo/api/index.py

@@ -0,0 +1,14 @@
+import os
+import sys
+from pathlib import Path
+
+# Add demo directory to sys.path so bundled gitradar package is importable on Vercel
+DEMO_DIR = Path(__file__).parent.parent
+if str(DEMO_DIR) not in sys.path:
+    sys.path.insert(0, str(DEMO_DIR))
+
+# Import monkeypatch for Python compatibility
+import gitradar  # noqa: F401
+from gitradar.web.app import create_app
+
+app = create_app()

demo/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.2.0"
+__author__ = "GitRadar Developer"
+

demo/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()

demo/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()

demo/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")
+

demo/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)

demo/gitradar/services/github.py

@@ -0,0 +1,179 @@
+import asyncio
+from typing import List, Optional, Dict, Any
+import httpx
+from gitradar.config import settings
+from gitradar.models import RepositoryInfo
+
+GITHUB_API_BASE = "https://api.github.com"
+
+
+class GitHubService:
+    """Asynchronous client for interacting with the GitHub REST API."""
+
+    def __init__(self, token: Optional[str] = None):
+        self.token = token or settings.github_token
+        self.headers = {
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "GitRadar-CLI/0.1.0",
+        }
+        if self.token:
+            self.headers["Authorization"] = f"Bearer {self.token}"
+
+    async def search_repositories(
+        self,
+        query: str,
+        limit: int = 10,
+        sort: str = "stars",
+        order: str = "desc"
+    ) -> List[RepositoryInfo]:
+        """Search GitHub repositories based on query string."""
+        url = f"{GITHUB_API_BASE}/search/repositories"
+        params = {
+            "q": query,
+            "sort": sort,
+            "order": order,
+            "per_page": min(limit, 100),
+        }
+
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            response = await client.get(url, headers=self.headers, params=params)
+            
+            if response.status_code == 403:
+                raise RuntimeError(
+                    "GitHub API Rate Limit Exceeded. "
+                    "Please configure a GITHUB_TOKEN (`gitradar config --github-token YOUR_TOKEN`)."
+                )
+            elif response.status_code != 200:
+                raise RuntimeError(f"GitHub API Error ({response.status_code}): {response.text}")
+
+            data = response.json()
+            items = data.get("items", [])
+
+            results: List[RepositoryInfo] = []
+            for item in items[:limit]:
+                repo = RepositoryInfo(
+                    full_name=item.get("full_name", ""),
+                    name=item.get("name", ""),
+                    owner=item.get("owner", {}).get("login", ""),
+                    html_url=item.get("html_url", ""),
+                    description=item.get("description") or "No description provided",
+                    stars=item.get("stargazers_count", 0),
+                    forks=item.get("forks_count", 0),
+                    language=item.get("language") or "Unspecified",
+                    topics=item.get("topics", []),
+                    updated_at=item.get("updated_at", "")[:10] if item.get("updated_at") else "",
+                    open_issues=item.get("open_issues_count", 0),
+                )
+                results.append(repo)
+
+            return results
+
+    async def fetch_readme_snippet(self, owner: str, repo: str, max_chars: int = 800) -> Optional[str]:
+        """Fetch README content snippet for a repository."""
+        url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/readme"
+        headers = {**self.headers, "Accept": "application/vnd.github.v3.raw"}
+
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            try:
+                response = await client.get(url, headers=headers)
+                if response.status_code == 200:
+                    text = response.text
+                    cleaned = text.strip()
+                    return cleaned[:max_chars] + "..." if len(cleaned) > max_chars else cleaned
+            except Exception:
+                pass
+        return None
+
+    async def search_and_enrich(
+        self,
+        keywords: List[str],
+        topics: List[str] = None,
+        limit: int = 10,
+        fetch_readmes: bool = True
+    ) -> List[RepositoryInfo]:
+        """
+        Execute smart combined search using keywords & topics, deduplicate results,
+        and enrich top results with README snippets asynchronously.
+        """
+        all_repos: Dict[str, RepositoryInfo] = {}
+
+        queries = []
+        if keywords:
+            for kw in keywords:
+                kw_clean = kw.strip()
+                if kw_clean and kw_clean not in queries:
+                    queries.append(kw_clean)
+
+        if topics:
+            for topic in topics[:3]:
+                topic_clean = topic.strip().replace(" ", "-").lower()
+                if topic_clean and topic_clean not in ["python", "machine-learning", "deep-learning", "ai", "artificial-intelligence"]:
+                    t_query = f"topic:{topic_clean}"
+                    if t_query not in queries:
+                        queries.append(t_query)
+
+        tasks = [self.search_repositories(q, limit=limit) for q in queries]
+        search_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for res in search_results:
+            if isinstance(res, list):
+                for repo in res:
+                    if repo.full_name not in all_repos:
+                        all_repos[repo.full_name] = repo
+
+        sorted_repos = sorted(all_repos.values(), key=lambda r: (r.stars, r.forks, r.full_name), reverse=True)[:limit]
+
+        if fetch_readmes and sorted_repos:
+            readme_tasks = [
+                self.fetch_readme_snippet(repo.owner, repo.name)
+                for repo in sorted_repos[:5]
+            ]
+            readmes = await asyncio.gather(*readme_tasks, return_exceptions=True)
+            
+            for i, readme in enumerate(readmes):
+                if isinstance(readme, str) and readme:
+                    sorted_repos[i].readme_snippet = readme
+
+        return sorted_repos
+
+    def rank_and_sort_by_relevance(
+        self,
+        repos: List[RepositoryInfo],
+        limit: int = 10,
+        min_relevance: int = 50,
+    ) -> List[RepositoryInfo]:
+        """
+        Calculate hybrid score for each repository, filter out repos below min_relevance threshold,
+        and sort by hybrid score desc.
+        Hybrid Score = (Relevance Score * 0.7) + (Normalized Star Score * 0.3)
+        """
+        if not repos:
+            return repos
+
+        import math
+        max_stars = max((r.stars for r in repos), default=1)
+
+        for r in repos:
+            rel_score = r.relevance_score if r.relevance_score is not None else 50
+            star_score = min(100.0, (math.log10(r.stars + 1) / math.log10(max(max_stars, 10) + 1)) * 100.0) if max_stars > 0 else 50.0
+            r.hybrid_score = round((rel_score * 0.7) + (star_score * 0.3), 1)
+
+        # Enforce minimum relevance threshold filtering
+        filtered_repos = [
+            r for r in repos
+            if r.relevance_score is not None and r.relevance_score >= min_relevance
+        ]
+
+        if not filtered_repos:
+            fallback_threshold = max(30, min_relevance - 20)
+            filtered_repos = [
+                r for r in repos
+                if r.relevance_score is not None and r.relevance_score >= fallback_threshold
+            ]
+
+        sorted_repos = sorted(
+            filtered_repos if filtered_repos else repos,
+            key=lambda r: (r.hybrid_score, r.stars, r.forks, r.full_name),
+            reverse=True
+        )
+        return sorted_repos[:limit]