added all files

README.md

@@ -1,14 +1,69 @@
----
-title: ContribNavigator
-emoji: 🦀
-colorFrom: green
-colorTo: gray
-sdk: gradio
-sdk_version: 5.33.0
-app_file: app.py
-pinned: false
-license: mit
-short_description: 'AI copilot: Start OS contributions with AI-planned kits.'
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ContribNavigator
+
+ContribNavigator is an AI-assisted tool designed to help developers, especially newcomers, find and begin contributing to open-source projects on GitHub. It streamlines issue discovery and provides an intelligently generated onboarding kit.
+
+## Core Features
+
+*   **Targeted Issue Search:** Filters GitHub issues by programming language and user-specified topics (e.g., "python" + "machine-learning"), prioritizing beginner-friendly labels like "good first issue."
+*   **AI-Powered Issue Suggestion:** Leverages an LLM (OpenAI GPT-4o class) to analyze fetched issues and recommend the most suitable starting point for a beginner, with clear reasoning.
+*   **Intelligent Onboarding Kit:**
+    *   **AI-Planned Components:** An LLM planner dynamically determines the most relevant sections to include in the kit based on the selected issue.
+    *   **Essential Information:** Direct links to the issue and repository, `git clone` command.
+    *   **Contribution Guidelines Analysis:**
+        *   Link to the project's `CONTRIBUTING.md` (or similar).
+        *   AI-generated summary of key contribution procedures (setup, coding style, PR process).
+    *   **Repository Overview (via Modal):**
+        *   Top-level file and directory listing from a sandboxed `git clone` operation executed on Modal.
+        *   AI-suggested relevant files/folders to investigate for the specific issue.
+*   **First Steps Checklist:** An interactive checklist in the UI to guide users through their initial contribution actions.
+*   **Agentic Design:** Built with an agentic architecture where an LLM plans and orchestrates the use of internal "tools" (GitHub API client, Modal repo inspector, LLM analysis functions), aligning with Model Context Protocol (MCP) principles.
+
+## Tech Stack
+
+*   **UI:** Gradio
+*   **Backend & Orchestration:** Python
+*   **Language Models:** OpenAI API (GPT-4o class)
+*   **Sandboxed Operations:** Modal (for `git clone`)
+*   **Data Source:** GitHub API
+
+## Local Development Setup
+
+1.  **Prerequisites:**
+    *   Git
+    *   Python (3.10+)
+    *   Modal Account & CLI (`modal token new`)
+
+2.  **Clone & Install Dependencies:**
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/ContribNavigator.git # Replace with your repo URL
+    cd ContribNavigator
+    python -m venv .venv
+    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+    ```
+
+3.  **Environment Variables:**
+    *   Create a `.env` file in the project root (refer to `.env.example` if provided).
+    *   Add your API keys:
+        ```env
+        GITHUB_PAT="your_github_pat"
+        OPENAI_API_KEY="sk-your_openai_key"
+        # MODAL_TOKEN_ID="mi_..." # Optional for local if `modal token new` was used
+        # MODAL_TOKEN_SECRET="ms_..." # Optional for local
+        ```
+
+4.  **Run the Application:**
+    ```bash
+    python app.py
+    ```
+
+## Hackathon Context
+
+*   **Project:** ContribNavigator
+*   **Event:** Agents & MCP Hackathon
+*   **Primary Track Submission:** Agentic Demos Track
+    *   *Demonstrates an end-to-end AI agent application using Gradio that assists with open-source contributions through intelligent planning and tool utilization (GitHub API, Modal, LLM analysis), reflecting MCP principles.*
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

core/github_client.py

@@ -0,0 +1,268 @@
+import requests
+import os # Good practice
+# from urllib.parse import quote # We are letting requests handle most param encoding
+
+# Import the GITHUB_PAT from our config loader
+from utils.config_loader import GITHUB_PAT # Make sure this path is correct for your setup
+
+BASE_SEARCH_URL = "https://api.github.com/search/issues"
+BASE_REPO_URL = "https://api.github.com/repos"
+
+def _make_github_request(url: str, params: dict = None, headers: dict = None) -> dict | None:
+    """
+    Helper function to make authenticated GitHub API GET requests expecting JSON response.
+    Handles potential request errors.
+    """
+    if not GITHUB_PAT:
+        print("ERROR (github_client._make_github_request): GITHUB_PAT is not configured.")
+        return None
+
+    default_headers = {
+        "Authorization": f"token {GITHUB_PAT}",
+        "Accept": "application/vnd.github.v3+json",
+        "X-GitHub-Api-Version": "2022-11-28"
+    }
+    if headers:
+        default_headers.update(headers)
+
+    try:
+        # print(f"Debug GitHub Request: URL={url}, Params={params}, Headers={default_headers}") # Uncomment for deep debugging
+        response = requests.get(url, headers=default_headers, params=params, timeout=15) # Increased timeout slightly
+        response.raise_for_status()
+        return response.json() # Expecting JSON
+    except requests.exceptions.Timeout:
+        print(f"ERROR (github_client._make_github_request): GitHub API request timed out for URL: {url}")
+        return None
+    except requests.exceptions.HTTPError as http_err:
+        # Log specific error details, especially for common issues like 401, 403, 404, 422
+        error_message = f"ERROR (github_client._make_github_request): GitHub API HTTP error for URL {url}: {http_err}."
+        try:
+            # Attempt to get more detailed error message from GitHub's JSON response
+            error_details = http_err.response.json()
+            error_message += f" Details: {error_details.get('message', 'No specific message')} Docs: {error_details.get('documentation_url', 'N/A')}"
+        except ValueError: # If response is not JSON
+            error_message += f" Response: {http_err.response.text}"
+        print(error_message)
+        return None # For HTTP errors, generally return None
+    except requests.exceptions.RequestException as req_err:
+        print(f"ERROR (github_client._make_github_request): GitHub API request failed for URL {url}: {req_err}")
+        return None
+    except ValueError as json_err: # Includes JSONDecodeError if response.json() fails
+        print(f"ERROR (github_client._make_github_request): Failed to decode JSON response from URL {url}: {json_err}")
+        return None
+
+def fetch_beginner_issues(
+        language: str,
+        topics: list[str] | None = None,
+        labels: list[str] | None = None, # This allows explicit override of default label logic
+        sort: str = "updated",
+        order: str = "desc",
+        per_page: int = 10,
+        page: int = 1
+    ) -> list[dict] | None:
+    """
+    Fetches beginner-friendly issues for a given language, optional topics,
+    and optional explicit labels from GitHub's public repositories.
+    """
+    if not language:
+        print("ERROR (github_client.fetch_beginner_issues): Language parameter is required.")
+        return None
+
+    current_labels_to_use = [] # Initialize
+
+    if labels is not None: # If labels are explicitly passed, use them
+        current_labels_to_use = labels
+        print(f"GitHub Client: Using explicitly passed labels: {current_labels_to_use}")
+    else: # No explicit labels passed, use our default logic based on topics
+        if topics:
+            # When topics are specified, be more focused.
+            current_labels_to_use = ["good first issue"]
+            # Optionally, could expand to: current_labels_to_use = ["good first issue", "help wanted"]
+            # Let's start with just "good first issue" when topics are present for max precision.
+            print(f"GitHub Client: Topics specified, using focused labels: {current_labels_to_use}")
+        else:
+            # No topics specified, cast a slightly wider net with labels.
+            current_labels_to_use = ["good first issue", "help wanted", "beginner", "first-timers-only"]
+            print(f"GitHub Client: No topics specified, using broader default labels: {current_labels_to_use}")
+
+    query_parts = [
+        f"language:{language.strip().lower()}", # Normalize language
+        "state:open",
+        "is:issue",
+        "is:public"
+    ]
+
+    # Add label query parts only if current_labels_to_use is not empty
+    if current_labels_to_use:
+        for label_name in current_labels_to_use:
+            if label_name.strip(): # Ensure label is not just whitespace
+                query_parts.append(f'label:"{label_name.strip()}"')
+    else: # If current_labels_to_use ended up empty (e.g., if explicitly passed as []), don't add label filter
+        print("GitHub Client: No labels will be applied to the search query.")
+
+
+    # Add topics to query if provided
+    if topics:
+        for topic_name_raw in topics:
+            topic_name = topic_name_raw.strip().lower() # Assuming topics from dropdown are already slugs or correct phrases
+            if topic_name:
+                if " " in topic_name: # If the topic phrase itself has a space
+                    query_parts.append(f'topic:"{topic_name}"')
+                else: # Assumed to be a slug or single word
+                    query_parts.append(f'topic:{topic_name}')
+
+    q_string = " ".join(query_parts)
+    params = {"q": q_string, "sort": sort, "order": order, "per_page": per_page, "page": page}
+
+    print(f"GitHub Client: Fetching issues with q_string: '{q_string}'")
+    data = _make_github_request(BASE_SEARCH_URL, params=params)
+
+    if data and "items" in data:
+        issues_list = []
+        for item in data["items"]:
+            repo_html_url = "/".join(item.get("html_url", "").split('/')[:5])
+            issues_list.append({
+                "title": item.get("title"), "html_url": item.get("html_url"),
+                "state": item.get("state"), "number": item.get("number"),
+                "created_at": item.get("created_at"), "updated_at": item.get("updated_at"),
+                "labels": [label_item.get("name") for label_item in item.get("labels", [])],
+                "repository_api_url": item.get("repository_url"),
+                "repository_html_url": repo_html_url,
+                "user_login": item.get("user", {}).get("login"),
+                "body_snippet": item.get("body", "")[:300] + "..." if item.get("body") else "No body provided."
+            })
+        return issues_list
+    elif data and "items" not in data:
+        print(f"GitHub Client: No 'items' in API response for query '{q_string}'. API Message: {data.get('message', 'N/A')}")
+        return []
+    return None
+
+
+def get_repository_details(repo_api_url: str) -> dict | None:
+    """
+    Fetches details for a specific repository using its API URL.
+    Primarily used to get the default_branch.
+    """
+    if not repo_api_url:
+        print("ERROR (github_client.get_repository_details): No repository API URL provided.")
+        return None
+    print(f"GitHub Client: Fetching repository details from: {repo_api_url}")
+    return _make_github_request(repo_api_url)
+
+
+def get_file_url_from_repo(repo_full_name: str, file_paths_to_check: list[str], default_branch: str | None = None) -> str | None:
+    """
+    Checks for the existence of a file in a list of possible paths within a repository
+    and returns its HTML URL if found.
+    """
+    if not repo_full_name or not file_paths_to_check:
+        print("ERROR (github_client.get_file_url_from_repo): repo_full_name and file_paths_to_check are required.")
+        return None
+
+    branch_to_use = default_branch
+    if not branch_to_use:
+        print(f"GitHub Client (get_file_url): No default branch provided for {repo_full_name}, attempting to fetch it.")
+        repo_api_url_for_details = f"{BASE_REPO_URL}/{repo_full_name}"
+        repo_details = get_repository_details(repo_api_url_for_details)
+        if repo_details and repo_details.get("default_branch"):
+            branch_to_use = repo_details.get("default_branch")
+            print(f"GitHub Client (get_file_url): Fetched default branch '{branch_to_use}' for {repo_full_name}.")
+        else:
+            print(f"GitHub Client (get_file_url): Could not determine default branch for {repo_full_name}. Will try common fallbacks.")
+            # If default branch still not found, function will iterate through fallbacks next.
+
+    # Define branches to try: the determined/passed one, then common fallbacks if needed.
+    branches_to_attempt = []
+    if branch_to_use:
+        branches_to_attempt.append(branch_to_use)
+    # Add fallbacks if the initial branch_to_use was None OR if we want to always check fallbacks (but usually not)
+    if not branch_to_use: # Only add fallbacks if we couldn't determine one
+        branches_to_attempt.extend(["main", "master"])
+
+
+    for current_branch_attempt in branches_to_attempt:
+        print(f"GitHub Client (get_file_url): Trying branch '{current_branch_attempt}' for {repo_full_name}.")
+        for file_path in file_paths_to_check:
+            file_api_url = f"{BASE_REPO_URL}/{repo_full_name}/contents/{file_path}?ref={current_branch_attempt}"
+            # print(f"GitHub Client (get_file_url): Checking for file at API URL: {file_api_url}") # Can be verbose
+            file_metadata = _make_github_request(file_api_url) # This expects JSON
+            if file_metadata and isinstance(file_metadata, dict) and file_metadata.get("html_url"):
+                print(f"GitHub Client (get_file_url): Found '{file_path}' in {repo_full_name} on branch '{current_branch_attempt}'.")
+                return file_metadata.get("html_url")
+            # else: # No need to print "not found" for every path/branch combination, becomes too noisy.
+                 # _make_github_request will print if it's a 404 or other HTTP error.
+    
+    print(f"GitHub Client (get_file_url): Could not find any of {file_paths_to_check} in {repo_full_name} on attempted branches.")
+    return None
+
+# --- NEW FUNCTION ---
+def get_file_content(repo_full_name: str, file_path: str, branch: str | None = None) -> str | None:
+    """
+    Fetches the raw text content of a specific file from a repository.
+    Args:
+        repo_full_name: The repository name in "owner/repo" format.
+        file_path: The path to the file within the repository (e.g., "CONTRIBUTING.md").
+        branch: The branch to fetch from. If None, attempts to find default branch.
+    Returns:
+        The text content of the file, or None if not found or an error occurs.
+    """
+    if not repo_full_name or not file_path:
+        print("ERROR (github_client.get_file_content): repo_full_name and file_path are required.")
+        return None
+
+    current_branch = branch
+    if not current_branch:
+        print(f"GitHub Client (get_file_content): No branch specified for {repo_full_name}/{file_path}, finding default.")
+        repo_api_url_for_details = f"{BASE_REPO_URL}/{repo_full_name}"
+        repo_details = get_repository_details(repo_api_url_for_details)
+        if repo_details and repo_details.get("default_branch"):
+            current_branch = repo_details.get("default_branch")
+            print(f"GitHub Client (get_file_content): Using default branch '{current_branch}' for {repo_full_name}/{file_path}")
+        else:
+            # Try common fallbacks if default cannot be determined
+            print(f"GitHub Client (get_file_content): Could not determine default branch for {repo_full_name}. Trying 'main', then 'master' for {file_path}.")
+            # Attempt 'main' first for get_file_content call
+            current_branch = "main" 
+            # If 'main' fails, we could try 'master' subsequently, but let's try one at a time.
+            # The request below will try current_branch. If it fails with 404, we could then retry with 'master'.
+            # For now, let's simplify: try determined default, else 'main'. If that 404s, the user gets None.
+
+    file_api_url = f"{BASE_REPO_URL}/{repo_full_name}/contents/{file_path}?ref={current_branch}"
+    print(f"GitHub Client (get_file_content): Fetching raw content for '{file_path}' from '{repo_full_name}' on branch '{current_branch}'.")
+
+    if not GITHUB_PAT:
+        print("ERROR (github_client.get_file_content): GITHUB_PAT is not configured.")
+        return None
+    
+    headers = {
+        "Authorization": f"token {GITHUB_PAT}",
+        "Accept": "application/vnd.github.raw", # Key header for raw content
+        "X-GitHub-Api-Version": "2022-11-28"
+    }
+
+    try:
+        response = requests.get(file_api_url, headers=headers, timeout=15) # Increased timeout
+        response.raise_for_status()
+        return response.text # Return raw text content
+    except requests.exceptions.Timeout:
+        print(f"ERROR (github_client.get_file_content): GitHub API request timed out for URL: {file_api_url}")
+        return None
+    except requests.exceptions.HTTPError as http_err:
+        if http_err.response.status_code == 404:
+            print(f"INFO (github_client.get_file_content): File not found (404) at {file_api_url}")
+            # If default branch was 'main' and failed, we could try 'master' here as a fallback
+            if current_branch == "main" and (not branch or branch == "main"): # Check if we already tried specific branch or if 'main' was a fallback
+                print(f"GitHub Client (get_file_content): '{file_path}' not found on 'main', trying 'master' as fallback.")
+                return get_file_content(repo_full_name, file_path, branch="master") # Recursive call with 'master'
+        else:
+            error_message = f"ERROR (github_client.get_file_content): GitHub API HTTP error for URL {file_api_url}: {http_err}."
+            try:
+                error_details = http_err.response.json() # Some errors might still be JSON
+                error_message += f" Details: {error_details.get('message', http_err.response.text)}"
+            except ValueError:
+                error_message += f" Response: {http_err.response.text}"
+            print(error_message)
+        return None
+    except requests.exceptions.RequestException as req_err:
+        print(f"ERROR (github_client.get_file_content): GitHub API request failed for URL {file_api_url}: {req_err}")
+        return None

core/kit_generator.py

@@ -0,0 +1,244 @@
+# core/kit_generator.py
+from .github_client import get_repository_details, get_file_url_from_repo, get_file_content
+from .modal_processor import get_repo_file_listing_via_modal
+from .llm_handler import summarize_text_content, suggest_relevant_code_locations
+
+# --- Helper function to get common repo info needed by multiple sections ---
+def _get_common_repo_info(issue_data: dict) -> tuple[str | None, str | None, str]:
+    """Extracts/derives repo_full_name, repo_api_url, and default_branch_name."""
+    repo_html_url = issue_data.get("repository_html_url", "#")
+    repo_api_url = issue_data.get("repository_api_url")
+    
+    repo_full_name = None
+    if repo_html_url and repo_html_url.startswith("https://github.com/"):
+        parts = repo_html_url.split('/')
+        if len(parts) >= 5:
+            repo_full_name = f"{parts[3]}/{parts[4]}"
+
+    branch_from_api = None
+    default_branch_name = "main (assumed)" # Fallback
+    if repo_full_name:
+        # Use the direct repo_api_url from issue_data if available and valid
+        current_repo_api_url = repo_api_url
+        if not current_repo_api_url or not current_repo_api_url.startswith("https://api.github.com/repos/"):
+            # If not valid, construct it from repo_full_name
+            current_repo_api_url = f"https://api.github.com/repos/{repo_full_name}"
+            print(f"Kit Generator (_get_common_repo_info): Constructed repo_api_url: {current_repo_api_url}")
+
+        repo_details = get_repository_details(current_repo_api_url)
+        if repo_details and repo_details.get("default_branch"):
+            branch_from_api = repo_details.get("default_branch")
+            default_branch_name = branch_from_api
+    
+    return repo_full_name, branch_from_api, default_branch_name
+
+# --- Helper functions for generating individual kit sections ---
+
+def _generate_repo_details_section(issue_data: dict, default_branch_name: str) -> str:
+    issue_title = issue_data.get("title", "N/A")
+    issue_html_url = issue_data.get("html_url", "#")
+    repo_html_url = issue_data.get("repository_html_url", "#")
+    
+    # Ensure .git suffix for clone command displayed to user
+    clone_url_display = repo_html_url if repo_html_url.endswith(".git") else repo_html_url + ".git"
+    repo_name_for_cd = repo_html_url.split('/')[-1] if repo_html_url != "#" else "repository-name"
+
+
+    return f"""
+## 🔗 Issue Details
+- **Issue Link:** [{issue_title}]({issue_html_url})
+- **Repository:** [{repo_html_url}]({repo_html_url})
+
+## 🛠️ Initial Setup Guide
+1.  **Clone the Repository:**
+    Open your terminal and run the following command to clone the repository to your local machine:
+    ```bash
+    git clone {clone_url_display}
+    ```
+    *(Note: Ensure you have Git installed. The repository might use a different default branch name than '{default_branch_name}'.)*
+
+2.  **Navigate into the Project Directory:**
+    ```bash
+    cd {repo_name_for_cd}
+    ```
+    *(This assumes the directory name matches the repository name. Adjust if needed.)*
+"""
+
+def _generate_contribution_guidelines_section(
+    repo_full_name: str | None,
+    branch_from_api: str | None
+) -> str:
+    section_title = "## 📖 Contribution Guidelines\nIt's highly recommended to read the project's contribution guidelines before you start coding.\n"
+    guidelines_link_markdown = "- **Guidelines Link:** _Could not find contribution guidelines in common locations._"
+    summary_markdown = ""
+
+    if repo_full_name:
+        contributing_paths_to_check = [
+            "CONTRIBUTING.md", ".github/CONTRIBUTING.md", "docs/CONTRIBUTING.md",
+            "CONTRIBUTING.rst", ".github/CONTRIBUTING.rst", "CONTRIBUTING"
+        ]
+        
+        found_contrib_display_url = get_file_url_from_repo(repo_full_name, contributing_paths_to_check, default_branch=branch_from_api)
+        
+        if found_contrib_display_url:
+            guidelines_link_markdown = f"- **Guidelines Link:** [{found_contrib_display_url}]({found_contrib_display_url})"
+            
+            path_that_worked = None
+            for p in contributing_paths_to_check: # Try to infer path for content fetching
+                if p.lower() in found_contrib_display_url.lower():
+                    path_that_worked = p
+                    break
+            
+            if path_that_worked:
+                print(f"Kit Generator (_contrib_guidelines): Found guidelines at '{path_that_worked}'. Fetching content...")
+                contrib_content_text = get_file_content(repo_full_name, path_that_worked, branch=branch_from_api)
+                if contrib_content_text:
+                    print("Kit Generator (_contrib_guidelines): Content fetched. Requesting LLM summary...")
+                    summary = summarize_text_content(contrib_content_text, purpose="contribution guidelines")
+                    if summary and "LLM Client not initialized" not in summary and "LLM API error" not in summary and "No content provided" not in summary:
+                        summary_markdown = f"\n\n**Key Takeaways (AI Summary):**\n{summary}"
+                    else:
+                        summary_markdown = "\n\n_AI summary for contribution guidelines could not be generated at this time._"
+                        print(f"Kit Generator (_contrib_guidelines): LLM summary failed or returned error: {summary}")
+                else:
+                    summary_markdown = "\n\n_Could not fetch content of contribution guidelines for AI summary._"
+            else:
+                summary_markdown = "\n\n_Could not determine specific path of contribution file for AI summary, but a link was found._"
+    
+    return f"{section_title}{guidelines_link_markdown}{summary_markdown}"
+
+def _generate_modal_repo_structure_section(
+    issue_data: dict, # Contains repo_html_url and issue_body_snippet
+    language_searched: str
+) -> str:
+    section_title = "## 📂 Quick Look: Repository Structure (via Modal)\n"
+    modal_file_listing_text = "_Could not retrieve repository file listing at this time._"
+    ai_suggested_files_text = ""
+
+    repo_html_url = issue_data.get("repository_html_url", "#")
+    issue_body_snippet = issue_data.get("body_snippet", "No issue description snippet available.")
+
+    if repo_html_url and repo_html_url != "#":
+        print(f"Kit Generator (_modal_structure): Requesting file listing for '{repo_html_url}' via Modal...")
+        clone_url_for_modal = repo_html_url if repo_html_url.endswith(".git") else repo_html_url + ".git"
+        modal_response = get_repo_file_listing_via_modal(clone_url_for_modal)
+
+        if modal_response and modal_response.get("status") == "success":
+            files_from_modal = modal_response.get("files", [])
+            if files_from_modal:
+                max_files_to_display = 15
+                file_list_items = [f"- `{item}`" for item in files_from_modal[:max_files_to_display]]
+                if len(files_from_modal) > max_files_to_display:
+                    file_list_items.append(f"- ... and {len(files_from_modal) - max_files_to_display} more.")
+                modal_file_listing_text = ("Here's a quick look at some top-level files and folders:\n" +
+                                           "\n".join(file_list_items))
+
+                print("Kit Generator (_modal_structure): Sending file list and issue snippet to LLM for relevant file suggestions.")
+                ai_suggestions = suggest_relevant_code_locations(
+                    issue_snippet=issue_body_snippet,
+                    file_list=files_from_modal,
+                    language=language_searched
+                )
+                if ai_suggestions and "LLM Client not initialized" not in ai_suggestions and "LLM API error" not in ai_suggestions:
+                    ai_suggested_files_text = f"\n\n**💡 AI Suggested Starting Points (based on issue & file list):**\n{ai_suggestions}"
+                else:
+                    ai_suggested_files_text = "\n\n_AI could not suggest specific files to start with for this issue at this time._"
+            else:
+                modal_file_listing_text = "_Repository cloned successfully via Modal, but no files were found at the top level._"
+        elif modal_response:
+            modal_file_listing_text = f"_Could not retrieve repository file listing via Modal: {modal_response.get('message', 'Unknown error from Modal')}_"
+    else:
+        modal_file_listing_text = "_Repository URL not available to fetch file listing._"
+        
+    return f"{section_title}{modal_file_listing_text}{ai_suggested_files_text}"
+
+
+# --- Main New Orchestrating Function ---
+def generate_kit_from_plan(
+    issue_data: dict,
+    language_searched: str,
+    components_to_include: list[str]
+) -> str:
+    """
+    Generates Markdown content for an onboarding kit for a given issue,
+    based on a plan specifying which components to include.
+    """
+    if not issue_data:
+        return "Error: No issue data provided to generate kit."
+    if not components_to_include:
+        return "Error: No components specified for kit generation plan."
+
+    print(f"Kit Generator (plan): Starting kit generation with components: {components_to_include}")
+
+    # Fetch common repo info once
+    repo_full_name, branch_from_api, default_branch_name = _get_common_repo_info(issue_data)
+    
+    # Header for the kit
+    issue_title = issue_data.get("title", "N/A")
+    kit_header = f"""
+# 👋 Onboarding Kit for: {issue_title}
+
+Congratulations on choosing this issue! Here's some information to help you get started.
+"""
+    markdown_parts = [kit_header.strip()]
+
+    # Generate sections based on the plan
+    if "repo_details_and_clone_command" in components_to_include:
+        print("Kit Generator (plan): Adding repo details and clone command.")
+        markdown_parts.append(_generate_repo_details_section(issue_data, default_branch_name))
+
+    # For guidelines, we handle link and summary together if summary is requested
+    # The LLM planner should ideally request "contribution_guidelines_summary_ai" which implies needing the link.
+    # If only "contribution_guidelines_link" is requested, we can adapt.
+    generate_guidelines_link = "contribution_guidelines_link" in components_to_include
+    generate_guidelines_summary = "contribution_guidelines_summary_ai" in components_to_include
+
+    if generate_guidelines_link or generate_guidelines_summary:
+        print("Kit Generator (plan): Adding contribution guidelines section (link and/or summary).")
+        # The helper function _generate_contribution_guidelines_section now handles both
+        # and will only generate summary if content is fetched.
+        # We can refine it to only fetch/summarize if generate_guidelines_summary is true.
+        # For now, let's make the helper smarter or adjust the planner.
+        #
+        # Simplified: Let _generate_contribution_guidelines_section do its thing.
+        # If only link was asked, it will still try to get content for summary but summary_markdown will be empty if not asked.
+        # This needs further refinement if we want to strictly adhere to planner *not* doing summary if not asked.
+        #
+        # Let's adjust the helper to accept a flag for summary.
+        # For now, the existing _generate_contribution_guidelines_section will attempt summary if content is found.
+        # We will rely on the LLM planner to be smart. If it asks for summary, it implies link is also useful.
+        guidelines_section_md = _generate_contribution_guidelines_section(repo_full_name, branch_from_api)
+        
+        # Temporary fix: if only link is requested, strip summary if it was generated.
+        # This is a bit hacky, better to pass a flag to the helper.
+        if generate_guidelines_link and not generate_guidelines_summary:
+            if "**Key Takeaways (AI Summary):**" in guidelines_section_md:
+                guidelines_section_md = guidelines_section_md.split("**Key Takeaways (AI Summary):**")[0].strip()
+        
+        markdown_parts.append(guidelines_section_md)
+
+
+    if "repository_structure_modal_ai" in components_to_include:
+        print("Kit Generator (plan): Adding repository structure (Modal) and AI file suggestions.")
+        markdown_parts.append(_generate_modal_repo_structure_section(issue_data, language_searched))
+
+    # Footer
+    markdown_parts.append("\nHappy contributing! Remember to communicate with the project maintainers if you have questions.")
+    
+    return "\n\n".join(markdown_parts).strip()
+
+
+# --- Keep your old generate_basic_kit_content for now, or comment out/remove if fully replaced ---
+# def generate_basic_kit_content(issue_data: dict, language_searched: str) -> str:
+#    # ... your previous full implementation ...
+#    # This will eventually be replaced by calls to generate_kit_from_plan
+#    print("WARNING: generate_basic_kit_content is called, should be generate_kit_from_plan")
+#    # For now, let it be, app.py will call the new one once updated.
+#    # To avoid breaking app.py immediately, we can have it call the new function with a default plan.
+    default_plan_for_basic = [
+        "repo_details_and_clone_command",
+        "contribution_guidelines_link", # Basic just wants the link
+        # "contribution_guidelines_summary_ai", # Not in "basic"
+        "repository_structure_modal_ai" # Basic had the modal files and AI suggestions
+    ]
+    return generate_kit_from_plan(issue_data, language_searched, default_plan_for_basic)

core/llm_handler.py

@@ -0,0 +1,317 @@
+import openai # Using the openai library for Nebius's OpenAI-compatible API
+import os     # For environment variables if not using config_loader directly here
+import json
+# Import API key and base URL from our config loader
+from utils.config_loader import OPENAI_API_KEY
+
+# Initialize the OpenAI client
+client = None
+if OPENAI_API_KEY:
+    try:
+        client = openai.OpenAI(
+            api_key=OPENAI_API_KEY
+            # No base_url needed for direct OpenAI
+        )
+        print("OpenAI client initialized successfully in llm_handler.")
+    except Exception as e:
+        print(f"Error initializing OpenAI client in llm_handler: {e}")
+        client = None
+else:
+    print("WARNING (llm_handler): OPENAI_API_KEY not configured. LLM calls will fail.")
+
+
+def get_simple_issue_suggestion(
+        issues_data: list[dict],
+        language: str,
+        target_count: int = 1,
+        model_name: str = "gpt-4o-mini", # Or your preferred model
+        additional_prompt_context: str = "" # NEW parameter
+    ) -> str | None:
+    """
+    Sends issue data to OpenAI API to suggest which one(s) might be best for a beginner.
+    """
+    if not client:
+        print("LLM client (OpenAI) in get_simple_issue_suggestion is not initialized.")
+        return "LLM client (OpenAI) not initialized. Check API Key configuration."
+    if not issues_data:
+        print("No issues provided to LLM for suggestion.")
+        return "No issues provided to LLM for suggestion."
+
+    prompt_issues_str = "" # Rebuild this based on your existing logic
+    for i, issue in enumerate(issues_data):
+        snippet = issue.get('body_snippet', 'No description available.')
+        title = issue.get('title', 'No title')
+        url = issue.get('html_url', '#')
+        labels = ", ".join(issue.get('labels', [])) if issue.get('labels') else "No labels"
+        prompt_issues_str += (
+            f"\n--- Issue {i+1} ---\n"
+            f"Title: {title}\nURL: {url}\nLabels: {labels}\nSnippet from body: {snippet}\n-----------------\n"
+        )
+
+    system_prompt = (
+        "You are an expert assistant helping a new open-source contributor. "
+        "Your task is to analyze the provided list of GitHub issues and recommend "
+        f"the top {target_count} that would be most suitable for a beginner ideally in {language} (if specified and makes sense for the issues). "
+        "Consider factors like clarity, labels, and apparent scope. "
+        f"{additional_prompt_context}" # ADDED additional context here
+        " If the user-specified language seems mismatched with the provided issues, please make your best judgment "
+        "based on the issue content itself or note the potential mismatch in your recommendation."
+    )
+    user_prompt = (
+        # ... (user prompt construction as before, including prompt_issues_str) ...
+        f"Here is a list of GitHub issues found when searching for the language '{language}'. "
+        # (The additional_prompt_context is now in the system prompt)
+        f"Please review them and suggest the top {target_count} issue(s) that seem most suitable for a beginner. "
+        f"For each suggested issue, provide a concise explanation (1-2 sentences) stating *why* it's a good choice for a beginner. "
+        f"If you suggest an issue, please refer to it by its number (e.g., 'Issue 1')."
+        f"\nHere are the issues:\n{prompt_issues_str}"
+    )
+
+    temperature_val = 0.4
+    max_tokens_val = 200 + (target_count * 150)
+    top_p_val = 0.9 # Usually 1.0 for temperature-based sampling, or 0.9 if also using top_p
+
+    print(f"\nSending request to OpenAI LLM for issue suggestion...")
+    print(f"Model: {model_name}, Temp: {temperature_val}, MaxTokens: {max_tokens_val}")
+
+    try:
+        completion = client.chat.completions.create( # Ensure client is defined
+            model=model_name,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt}
+            ],
+            # ... other params
+            temperature=0.4,
+            max_tokens=200 + (target_count * 150),
+            top_p=0.9
+        )
+
+        suggestion_text = completion.choices[0].message.content
+        print("OpenAI LLM Suggestion Received.")
+        return suggestion_text.strip()
+
+    except openai.APIConnectionError as e:
+        print(f"OpenAI API Connection Error: {e}")
+        return f"LLM suggestion failed due to connection error: {e}"
+    except openai.RateLimitError as e: # Good to handle this explicitly
+        print(f"OpenAI API Rate Limit Error: {e}")
+        return f"LLM suggestion failed due to rate limit: {e}. Check your OpenAI plan and usage."
+    except openai.AuthenticationError as e: # Added for bad API key
+        print(f"OpenAI API Authentication Error: {e}. Check your OPENAI_API_KEY.")
+        return f"LLM suggestion failed due to authentication error: {e}."
+    except openai.APIStatusError as e:
+        print(f"OpenAI API Status Error: Status {e.status_code} - Response: {e.response}")
+        return f"LLM suggestion failed due to API status error: {e.status_code}"
+    except Exception as e:
+        print(f"LLM API call to OpenAI failed with an unexpected error: {e}")
+        print(f"Type of error: {type(e)}")
+        return f"LLM suggestion failed with an unexpected error: {e}"
+
+# --- NEW FUNCTION 1: Summarize Text Content ---
+def summarize_text_content(
+        text_content: str,
+        purpose: str = "contribution guidelines", # e.g., "issue description", "documentation section"
+        max_summary_tokens: int = 200, # Adjust as needed
+        model_name: str = "gpt-4o-mini" # Or your preferred model
+    ) -> str | None:
+    """
+    Summarizes a given text content using an LLM.
+    """
+    if not client:
+        print("ERROR (llm_handler.summarize_text_content): LLM client not initialized.")
+        return "LLM Client not initialized. Cannot summarize."
+    if not text_content or not text_content.strip():
+        print("Warning (llm_handler.summarize_text_content): No text content provided to summarize.")
+        return "No content provided for summarization."
+
+    # Heuristic: If text is already short, just return it or a small part.
+    # This avoids wasting API calls on tiny texts. (Count words approx)
+    if len(text_content.split()) < 75 : # Arbitrary threshold for "short"
+        print("Info (llm_handler.summarize_text_content): Content too short, returning as is or snippet.")
+        return f"The {purpose} document is brief: \"{text_content[:500]}...\"" if len(text_content) > 500 else text_content
+
+
+    system_prompt = (
+        f"You are an expert summarizer. Your task is to provide a concise summary of the following '{purpose}' document. "
+        "Focus on the most critical information a new contributor would need. "
+        "For contribution guidelines, highlight key setup steps, coding style conventions, testing requirements, and pull request procedures. "
+        "Keep the summary brief and actionable."
+    )
+    user_prompt = (
+        f"Please summarize the key points of the following {purpose} document:\n\n"
+        f"```text\n{text_content[:8000]}\n```" # Limit context sent to LLM
+        # Using 8000 characters as a rough limit to fit within context windows & manage cost.
+        # Adjust this based on typical CONTRIBUTING.md length and model context limits.
+    )
+
+    print(f"LLM Handler: Sending request to summarize {purpose}. Model: {model_name}")
+    try:
+        completion = client.chat.completions.create(
+            model=model_name,
+            messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+            temperature=0.2, # Lower temperature for factual summarization
+            max_tokens=max_summary_tokens,
+            top_p=1.0
+        )
+        summary_text = completion.choices[0].message.content
+        print(f"LLM Handler: Summary for {purpose} received.")
+        return summary_text.strip()
+    except Exception as e:
+        print(f"ERROR (llm_handler.summarize_text_content): LLM API call failed: {e}")
+        return f"Could not summarize the {purpose}: LLM API error."
+
+# --- NEW FUNCTION 2: Suggest Relevant Code Locations ---
+def suggest_relevant_code_locations(
+        issue_snippet: str,
+        file_list: list[str],
+        language: str, # Language of the project
+        max_suggestion_tokens: int = 200, # Adjust as needed
+        model_name: str = "gpt-4o-mini" # Or your preferred model
+    ) -> str | None:
+    """
+    Suggests relevant files/folders based on an issue snippet and a list of files.
+    """
+    if not client:
+        print("ERROR (llm_handler.suggest_relevant_code_locations): LLM client not initialized.")
+        return "LLM Client not initialized. Cannot suggest locations."
+    if not issue_snippet or not issue_snippet.strip():
+        return "No issue description provided to suggest locations."
+    if not file_list:
+        return "No file list provided to suggest locations from."
+
+    # Format file list for the prompt
+    formatted_file_list = "\n".join([f"- `{f}`" for f in file_list])
+    if not formatted_file_list: # Should not happen if file_list is not empty
+        formatted_file_list = "No files listed."
+
+    system_prompt = (
+        f"You are an AI assistant helping a software developer navigate a new '{language}' codebase. "
+        "Your goal is to identify potentially relevant files or folders for a given issue, based on a provided list of top-level project files/folders."
+    )
+    user_prompt = (
+        f"A developer is starting work on an issue with the following description snippet:\n"
+        f"'''\n{issue_snippet}\n'''\n\n"
+        f"The top-level files and folders available in the repository are:\n"
+        f"{formatted_file_list}\n\n"
+        f"Based *only* on the issue snippet and this file list, please suggest 2-3 files or folders that might be most relevant for investigating this issue. "
+        f"For each suggestion, provide a brief (1-sentence) explanation of why it might be relevant. "
+        f"If no files seem obviously relevant from the top-level list, say so."
+    )
+
+    print(f"LLM Handler: Sending request to suggest relevant code locations. Model: {model_name}")
+    try:
+        completion = client.chat.completions.create(
+            model=model_name,
+            messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+            temperature=0.5, # Moderate temperature for some reasoning
+            max_tokens=max_suggestion_tokens,
+            top_p=1.0
+        )
+        suggestion_text = completion.choices[0].message.content
+        print("LLM Handler: Code location suggestions received.")
+        return suggestion_text.strip()
+    except Exception as e:
+        print(f"ERROR (llm_handler.suggest_relevant_code_locations): LLM API call failed: {e}")
+        return f"Could not suggest code locations: LLM API error."
+
+def plan_onboarding_kit_components(
+        issue_data: dict,
+        language_searched: str,
+        model_name: str = "gpt-4.1-mini" # Or your preferred model
+    ) -> dict | None:
+    """
+    Uses an LLM to decide which onboarding kit components are most relevant for a given issue.
+    Returns a dictionary based on the LLM's JSON output.
+    """
+    if not client:
+        print("ERROR (llm_handler.plan_kit): LLM client not initialized.")
+        return None # Or: {"error": "LLM Client not initialized"}
+    if not issue_data:
+        print("ERROR (llm_handler.plan_kit): No issue data provided for planning.")
+        return None # Or: {"error": "No issue data"}
+
+    issue_title = issue_data.get("title", "N/A")
+    issue_snippet = issue_data.get("body_snippet", "No description available.")
+    issue_labels = issue_data.get("labels", [])
+
+    # Define available kit components for the LLM to choose from
+    available_components = [
+        "repo_details_and_clone_command",      # Basic repo info, clone command
+        "contribution_guidelines_link",        # Link to CONTRIBUTING.md
+        "contribution_guidelines_summary_ai",  # AI Summary of CONTRIBUTING.md
+        "repository_structure_modal_ai",       # File listing via Modal + AI suggested files
+        # We could break down "repository_structure_modal_ai" further if needed:
+        # "repository_files_modal_raw_list",
+        # "ai_suggested_start_files_from_list"
+    ]
+    components_description = (
+        "- repo_details_and_clone_command: Basic repository information and git clone command.\n"
+        "- contribution_guidelines_link: A direct link to the project's CONTRIBUTING.md file (if found).\n"
+        "- contribution_guidelines_summary_ai: An AI-generated summary of the key points from CONTRIBUTING.md.\n"
+        "- repository_structure_modal_ai: A top-level file/folder listing from a repository clone (via Modal), followed by AI suggestions for relevant files based on the issue."
+    )
+
+    system_prompt = (
+        "You are an expert onboarding assistant for open-source contributors. Your task is to intelligently plan "
+        "the components of an onboarding kit that would be most helpful for a developer tackling a specific GitHub issue. "
+        "You must respond ONLY with a valid JSON object containing a single key 'include_components' whose value is a list of strings, "
+        "where each string is one of the component names provided."
+    )
+    user_prompt = (
+        f"Based on the following GitHub issue details for a project searched under the language context '{language_searched}':\n"
+        f"Issue Title: \"{issue_title}\"\n"
+        f"Issue Snippet: \"{issue_snippet}\"\n"
+        f"Issue Labels: {issue_labels}\n\n"
+        f"And considering the following available onboarding kit components and their descriptions:\n"
+        f"{components_description}\n\n"
+        f"Which components should be included in the onboarding kit for this specific issue to be most helpful? "
+        f"For example, if the issue is a very simple documentation typo, a full 'repository_structure_modal_ai' might be overkill. "
+        f"If no contribution guidelines are typically found for a project, 'contribution_guidelines_summary_ai' would not be applicable. (You don't know this yet, but keep it in mind for general reasoning). "
+        f"Prioritize helpfulness for a beginner. Respond ONLY with a JSON object in the format: "
+        f"{{\"include_components\": [\"component_name_1\", \"component_name_2\", ...]}}"
+    )
+
+    print(f"LLM Handler (plan_kit): Sending request to plan kit components. Model: {model_name}")
+    try:
+        # Forcing JSON response mode if available and model supports it well
+        # gpt-4o-mini and newer gpt-3.5-turbo models usually handle "Respond ONLY with a valid JSON" well.
+        # For stronger enforcement, you can use response_format={"type": "json_object"} with compatible models.
+        completion_params = {
+            "model": model_name,
+            "messages": [{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
+            "temperature": 0.2, # Low temperature for more deterministic structural output
+            "max_tokens": 200, # JSON output should be relatively small
+            "top_p": 1.0,
+        }
+        # Check if the model might be one that supports explicit JSON mode via response_format
+        if "gpt-4o" in model_name or "gpt-3.5-turbo-0125" in model_name or "gpt-3.5-turbo-1106" in model_name: # Add other compatible models if known
+             completion_params["response_format"] = {"type": "json_object"}
+
+
+        completion = client.chat.completions.create(**completion_params)
+        
+        raw_response_content = completion.choices[0].message.content
+        print(f"LLM Handler (plan_kit): Raw JSON response received: {raw_response_content}")
+
+        # Attempt to parse the JSON
+        parsed_plan = json.loads(raw_response_content)
+        if "include_components" in parsed_plan and isinstance(parsed_plan["include_components"], list):
+            # Further validation: ensure all component names are valid (optional but good)
+            valid_components = [comp for comp in parsed_plan["include_components"] if comp in available_components]
+            if len(valid_components) != len(parsed_plan["include_components"]):
+                print("Warning (llm_handler.plan_kit): LLM returned some invalid component names.")
+            
+            final_plan = {"include_components": valid_components}
+            print(f"LLM Handler (plan_kit): Parsed plan: {final_plan}")
+            return final_plan
+        else:
+            print("ERROR (llm_handler.plan_kit): LLM response was not in the expected JSON format (missing 'include_components' list).")
+            return {"error": "LLM response format error", "details": "Missing 'include_components' list."}
+
+    except json.JSONDecodeError as json_e:
+        print(f"ERROR (llm_handler.plan_kit): Failed to decode JSON from LLM response. Error: {json_e}. Response was: {raw_response_content}")
+        return {"error": "JSON decode error", "details": str(json_e), "raw_response": raw_response_content}
+    except Exception as e:
+        print(f"ERROR (llm_handler.plan_kit): LLM API call failed: {e}")
+        return {"error": f"LLM API call failed: {str(e)}"}

core/modal_processor.py

@@ -0,0 +1,51 @@
+# core/modal_processor.py
+
+# CHANGE THIS IMPORT:
+# from ..modal_definitions import stub as an_individual_modal_app_instance_name
+# from ..modal_definitions import clone_and_list_files_on_modal
+# TO THIS (assuming modal_definitions.py is in the project root):
+from modal_definitions import stub as an_individual_modal_app_instance_name
+from modal_definitions import clone_and_list_files_on_modal
+
+# (get_repo_file_listing_via_modal function definition remains the same)
+def get_repo_file_listing_via_modal(repo_url: str) -> dict | None:
+    if not repo_url:
+        print("Error (modal_processor): No repository URL provided.")
+        return {"status": "error", "message": "No repository URL provided."}
+
+    print(f"Modal Processor: Attempting to get file listing for {repo_url} via Modal...")
+    try:
+        with an_individual_modal_app_instance_name.run():
+            result_dict = clone_and_list_files_on_modal.remote(repo_url)
+        print(f"Modal Processor: Result received from Modal for {repo_url}: {result_dict}")
+        return result_dict
+    except Exception as e:
+        print(f"Error (modal_processor): Failed to invoke or communicate with Modal function for {repo_url}. Exception: {e}")
+        return {"status": "error", "message": f"Failed to invoke Modal function: {str(e)}"}
+
+
+if __name__ == '__main__':
+    # This block is for when you run `python core/modal_processor.py` OR `python -m core.modal_processor`
+    # FROM THE PROJECT ROOT (contrib_navigator/)
+    # The imports at the top of the file (`from modal_definitions import ...`) should now work
+    # because Python adds the directory of the script being run (or -m target) to sys.path.
+    # If running `python -m core.modal_processor` from `contrib_navigator/`, then `contrib_navigator/` is in sys.path.
+
+    print("Running modal_processor.py directly for testing...")
+    test_url_gradio = "https://github.com/gradio-app/gradio.git"
+
+    print(f"\nTesting with URL: {test_url_gradio}")
+    response = get_repo_file_listing_via_modal(test_url_gradio)
+    if response and response.get("status") == "success":
+        print(f"Success! Files for {test_url_gradio}: {response.get('files')[:5]}...") # Print first 5 files
+    else:
+        print(f"Failed or got unexpected response for {test_url_gradio}: {response}")
+
+    # You can add back other test cases here if desired, for example:
+    # test_url_problematic = "https://github.com/git-guides/install-git.git"
+    # print(f"\nTesting with problematic URL: {test_url_problematic}")
+    # response_problem = get_repo_file_listing_via_modal(test_url_problematic)
+    # if response_problem and response_problem.get("status") == "error":
+    #     print(f"Correctly received error for {test_url_problematic}: {response_problem.get('message')}")
+    # else:
+    #     print(f"Unexpected response for {test_url_problematic}: {response_problem}")

modal_definitions.py

@@ -0,0 +1,78 @@
+# modal_definitions.py
+import modal
+import subprocess
+import tempfile
+import os
+
+# (stub and git_image definitions remain the same)
+stub = modal.App(name="contrib-navigator-repo-inspector")
+git_image = (
+    modal.Image.debian_slim(python_version="3.12")
+    .apt_install("git")
+)
+
+# (clone_and_list_files_on_modal function remains the same)
+@stub.function(
+    image=git_image,
+    timeout=120,
+    retries=modal.Retries(max_retries=1, initial_delay=2.0, backoff_coefficient=1.0)
+)
+def clone_and_list_files_on_modal(repo_url: str) -> dict:
+    # ... (function body is correct as you have it) ...
+    print(f"Modal function received URL to clone: {repo_url}")
+    with tempfile.TemporaryDirectory() as tmpdir:
+        repo_subdir_name = "cloned_repo"
+        clone_target_path = os.path.join(tmpdir, repo_subdir_name)
+        try:
+            command = ["git", "clone", "--depth", "1", repo_url, clone_target_path]
+            print(f"Executing command in Modal: {' '.join(command)}")
+            result = subprocess.run(
+                command, check=True, capture_output=True, text=True, timeout=90
+            )
+            cloned_files = os.listdir(clone_target_path)
+            print(f"Successfully cloned and listed files for {repo_url}. Files: {cloned_files}")
+            return {"status": "success", "files": cloned_files, "cloned_path_on_modal": clone_target_path}
+        except subprocess.TimeoutExpired:
+            error_message = f"Git clone command timed out in Modal for {repo_url}."
+            print(error_message)
+            return {"status": "error", "message": error_message}
+        except subprocess.CalledProcessError as e:
+            error_message = (
+                f"Failed to clone {repo_url} in Modal. "
+                f"Git command return code: {e.returncode}. "
+                f"Stderr: {e.stderr.strip() if e.stderr else 'N/A'}. "
+                f"Stdout: {e.stdout.strip() if e.stdout else 'N/A'}."
+            )
+            print(error_message)
+            return {"status": "error", "message": error_message}
+        except FileNotFoundError:
+            error_message = "Git command not found in Modal environment. Image build issue."
+            print(error_message)
+            return {"status": "error", "message": error_message}
+        except Exception as e:
+            error_message = f"An unexpected error occurred in Modal function for {repo_url}: {str(e)}"
+            print(error_message)
+            return {"status": "error", "message": error_message}
+
+
+# --- Optional: Local testing entrypoint for this Modal function ---
+@stub.local_entrypoint()
+async def test_clone_function_on_modal():
+    # Test with a known public repository that works
+    test_repo_url_successful = "https://github.com/gradio-app/gradio.git"
+    print(f"\n[Local Test] Calling Modal function for successful clone: {test_repo_url_successful}")
+    result_successful = await clone_and_list_files_on_modal.remote.aio(test_repo_url_successful)
+    print(f"[Local Test] Result from Modal for successful clone: {result_successful}\n")
+
+    # --- This section is now fully commented out to avoid NameError ---
+    # test_repo_url_small = "https://github.com/git-guides/install-git.git" # A very small repo
+    # print(f"\n[Local Test] Calling Modal function for: {test_repo_url_small}")
+    # result_small = await clone_and_list_files_on_modal.remote.aio(test_repo_url_small)
+    # print(f"[Local Test] Result from Modal for small repo: {result_small}\n")
+    # --- End of commented out section ---
+
+    # Test with a non-existent repo URL (expecting an error)
+    # non_existent_repo_url = "https://github.com/this/repo-does-not-exist12345.git"
+    # print(f"\n[Local Test] Calling Modal function for non-existent repo: {non_existent_repo_url}")
+    # result_non_existent = await clone_and_list_files_on_modal.remote.aio(non_existent_repo_url)
+    # print(f"[Local Test] Result from Modal for non-existent repo: {result_non_existent}\n")

requirements.txt

@@ -0,0 +1,5 @@
+python-dotenv
+requests
+openai
+gradio
+modal

run_day1_tests.py

@@ -0,0 +1,66 @@
+from core.github_client import fetch_beginner_issues
+from core.llm_handler import get_simple_issue_suggestion
+import utils.config_loader # This loads .env and makes variables available
+
+def main_test_runner():
+    print("--- ContribNavigator Day 1 Test Runner ---")
+
+    # Check for GitHub PAT
+    if not utils.config_loader.GITHUB_PAT:
+        print("CRITICAL: GITHUB_PAT not loaded. Please check your .env file.")
+        return # Stop if GitHub PAT is missing, as it's essential for the first step
+
+    # Check for OpenAI API Key
+    if not utils.config_loader.OPENAI_API_KEY: # CHANGED from Nebius check
+        print("CRITICAL: OPENAI_API_KEY not loaded. LLM calls will fail. Please check your .env file.")
+        # We might still want to see GitHub issues, so we don't return immediately,
+        # but the LLM part will be skipped or will show an error from llm_handler.
+    else:
+        print("OpenAI API Key found. Ready for LLM tests.")
+
+
+    print("\n--- Testing GitHub Issue Fetching ---")
+    target_language = "python"
+    print(f"Attempting to fetch up to 5 '{target_language}' issues with default labels...")
+    # Using default labels from fetch_beginner_issues: ["good first issue", "help wanted"]
+    issues = fetch_beginner_issues(target_language, per_page=5)
+
+    if issues is None:
+        print("Failed to fetch issues from GitHub. There might have been an API request error. Check console for details from github_client.")
+    elif not issues:
+        print(f"No issues found for '{target_language}' with the default labels. Cannot proceed to LLM test.")
+    else:
+        print(f"\nSuccessfully fetched {len(issues)} issues for '{target_language}':")
+        for i, issue_item in enumerate(issues):
+            print(f"  {i+1}. Title: {issue_item.get('title')}")
+            print(f"      URL: {issue_item.get('html_url')}")
+            print(f"      Repo: {issue_item.get('repository_html_url')}")
+            print(f"      Labels: {issue_item.get('labels')}")
+            print("-" * 20)
+
+        # --- NOW TESTING LLM Handler with OpenAI ---
+        print("\n--- Testing LLM Suggestion (OpenAI) ---")
+        if not utils.config_loader.OPENAI_API_KEY: # CHANGED from Nebius check
+            print("OPENAI_API_KEY not configured in .env. Skipping LLM test.")
+        else:
+            # Let's send the first 2 or 3 issues to the LLM for suggestion
+            issues_for_llm = issues[:3] # Send up to the first 3 issues
+            if issues_for_llm:
+                print(f"\nSending {len(issues_for_llm)} issue(s) to OpenAI LLM for suggestion (expecting 1 suggestion)...")
+                # Get 1 suggestion for these issues
+                suggestion = get_simple_issue_suggestion(issues_for_llm, target_language, target_count=1) # Uses default model "gpt-3.5-turbo"
+
+                print("\nLLM Suggestion Output:")
+                if suggestion:
+                    print(suggestion)
+                else:
+                    # llm_handler should print specific errors if any occurred during the API call
+                    print("LLM did not return a suggestion or an error occurred (see logs above from llm_handler).")
+            else:
+                # This case should not happen if 'issues' list was populated
+                print("No issues were available to send to LLM for suggestion.")
+
+    print("\n--- Day 1 Full Test Complete ---")
+
+if __name__ == "__main__":
+    main_test_runner()

utils/config_loader.py

@@ -0,0 +1,19 @@
+import os
+from dotenv import load_dotenv
+
+def load_app_config():
+    """Loads environment variables from .env file.""" # Corrected docstring quotes
+    load_dotenv()
+
+# Load config immediately when this module is imported
+load_app_config()
+
+# Expose specific config values
+GITHUB_PAT = os.getenv("GITHUB_PAT")
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+
+# Add MODAL keys here later when we get to Modal setup (e.g., MODAL_TOKEN_ID, MODAL_TOKEN_SECRET if needed for scripts)
+
+# Optional: Add checks or print statements for debugging if values are None during startup
+if not GITHUB_PAT: print("WARNING: GITHUB_PAT not found in .env")
+if not OPENAI_API_KEY: print("WARNING: OPENAI_API_KEY not found in .env")