hack/tools/scripts/llm-key-hunter/results/_cache/content/ac-ciano_msc-dissertation.json

{"repo": "ac-ciano/msc-dissertation", "files": {"SETUP.md": {"26a835ae541421f345553cbeeaf4859a5fd4e174": {"t": 1785674533.0024734, "n": 5744, "h": "faf964b492f019e1", "c": "# Setup Guide\n\nThis guide will help you set up the environment and configure API keys for the MSc Dissertation project on suicide risk prediction using Machine Learning and Large Language Models.\n\n## Table of Contents\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [API Configuration](#api-configuration)\n- [Troubleshooting](#troubleshooting)\n\n## Prerequisites\n\n- Python 3.8 or higher\n- pip (Python package installer)\n- Git (for version control)\n- API keys for the following services (only if running LLM experiments):\n  - xAI (Grok) API\n  - Google (Gemini) API\n  - DeepSeek API\n\n## Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/ac-ciano/MSc-dissertation.git\ncd MSc-dissertation\n```\n\n### 2. Create a Virtual Environment (Recommended)\n\n**Windows:**\n```cmd\npython -m venv venv\nvenv\\Scripts\\activate\n```\n\n**Linux/Mac:**\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n### 3. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\nThis will install all required packages including:\n- pandas, numpy (data processing)\n- torch, transformers (deep learning)\n- scikit-learn (metrics and evaluation)\n- openai (API client for xAI and DeepSeek)\n- google-generativeai (Google Gemini API)\n- python-dotenv (environment variable management)\n\n## API Configuration\n\nThe project uses a centralized configuration system to manage API keys securely.\n\n### 1. Create Environment File\n\nCopy the example environment file to create your own:\n\n**Windows:**\n```cmd\ncopy .env.example .env\n```\n\n**Linux/Mac:**\n```bash\ncp .env.example .env\n```\n\n### 2. Add Your API Keys\n\nOpen the `.env` file in a text editor and replace the placeholder values with your actual API keys:\n\n```env\n# xAI (Grok) API Configuration\nXAI_API_KEY=xai-your_actual_key_here\nXAI_BASE_URL=https://api.x.ai/v1\n\n# Google (Gemini) API Configuration\nGOOGLE_API_KEY=your_actual_google_api_key_here\n\n# DeepSeek API Configuration\nDEEPSEEK_API_KEY=sk-your_actual_deepseek_key_here\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n```\n\n### 3. Obtaining API Keys\n\n#### xAI (Grok) API\n1. Visit [xAI Console](https://console.x.ai/)\n2. Sign up or log in\n3. Navigate to API Keys section\n4. Create a new API key\n5. Copy the key (format: `xai-...`)\n\n#### Google Gemini API\n1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Sign in with your Google account\n3. Click \"Create API Key\"\n4. Copy the generated key\n\n#### DeepSeek API\n1. Visit [DeepSeek Platform](https://platform.deepseek.com/)\n2. Sign up or log in\n3. Go to API Keys section\n4. Generate a new key\n5. Copy the key (format: `sk-...`)\n\n### 4. Verify Configuration\n\nThe `config.py` module automatically loads and validates your API keys. When you run any script that uses LLM APIs, it will check if the required keys are present.\n\n**Security Best Practices:**\n- ✅ **NEVER** commit your `.env` file to version control\n- ✅ The `.gitignore` file already excludes `.env` files\n- ✅ Only share `.env.example` as a template\n- ✅ Keep your API keys confidential\n- ✅ Rotate keys if they are accidentally exposed\n\n## Project Configuration System\n\nThe project uses a modular configuration approach:\n\n- **config.py**: Central configuration module that reads from `.env`\n- **Config class**: Provides methods to access API configurations:\n  - `Config.get_xai_config()` - Returns xAI API configuration\n  - `Config.get_google_config()` - Returns Google API configuration\n  - `Config.get_deepseek_config()` - Returns DeepSeek API configuration\n  - `Config.validate_api_keys()` - Validates required API keys\n\nAll scripts in `src/NO-fold/Grok/`, `src/NO-fold/Google/`, and `src/NO-fold/DeepSeek/` automatically import and use this configuration.\n\n## Data Setup\n\nThe raw dataset is not included in this repository due to data use agreements. To obtain access:\n\n1. Contact **hialex.li@connect.polyu.hk**\n2. CC **xinhong.chen@my.cityu.edu.hk**\n3. Request access to the suicide risk prediction dataset\n4. Sign the Data Use Agreement (DUA) they provide\n5. Once received, place the data in the appropriate directory and run `preprocessing.ipynb`\n\n## Running Experiments\n\n### RoBERTa Fine-Tuning (K-Fold)\n\nNavigate to the appropriate directory and run the training script:\n\n```bash\ncd src/K-fold/large-cross-entropy--5e-5\npython finetune_roberta.py\n```\n\n### LLM Inference\n\nFor running LLM-based experiments:\n\n```bash\ncd src/NO-fold/Grok\npython grok-3.py\n```\n\n```bash\ncd src/NO-fold/Google\npython gemini-2.5-flash.py\n```\n\n```bash\ncd src/NO-fold/DeepSeek\npython deepseek-reasoner.py\n```\n\n## Troubleshooting\n\n### Missing API Keys Error\n```\nValueError: Missing required API key(s): XAI_API_KEY\n```\n**Solution**: Ensure your `.env` file exists and contains the correct API key.\n\n### Import Error for dotenv\n```\nModuleNotFoundError: No module named 'dotenv'\n```\n**Solution**: Install python-dotenv:\n```bash\npip install python-dotenv\n```\n\n### API Rate Limiting\nIf you encounter rate limit errors, the scripts include automatic retry logic. You may need to:\n- Wait and retry later\n- Upgrade your API tier\n- Reduce concurrent requests\n\n### Virtual Environment Issues\nIf packages aren't found after installation, ensure your virtual environment is activated:\n- Windows: `venv\\Scripts\\activate`\n- Linux/Mac: `source venv/bin/activate`\n\n## Need Help?\n\nFor issues related to:\n- **Code/Repository**: Open an issue on GitHub\n- **Data Access**: Contact the data providers listed above\n- **API Issues**: Consult the respective API documentation:\n  - [xAI API Docs](https://docs.x.ai/)\n  - [Google Gemini Docs](https://ai.google.dev/docs)\n  - [DeepSeek API Docs](https://platform.deepseek.com/api-docs/)\n\n---\n\n## License & Citation\n\nPlease refer to the main README for license information and citation guidelines.\n"}, "22a22b018244000030ffd510f512555f55a52716": {"t": 1785770784.1821995, "n": 5744, "h": "faf964b492f019e1", "c": "# Setup Guide\n\nThis guide will help you set up the environment and configure API keys for the MSc Dissertation project on suicide risk prediction using Machine Learning and Large Language Models.\n\n## Table of Contents\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [API Configuration](#api-configuration)\n- [Troubleshooting](#troubleshooting)\n\n## Prerequisites\n\n- Python 3.8 or higher\n- pip (Python package installer)\n- Git (for version control)\n- API keys for the following services (only if running LLM experiments):\n  - xAI (Grok) API\n  - Google (Gemini) API\n  - DeepSeek API\n\n## Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/ac-ciano/MSc-dissertation.git\ncd MSc-dissertation\n```\n\n### 2. Create a Virtual Environment (Recommended)\n\n**Windows:**\n```cmd\npython -m venv venv\nvenv\\Scripts\\activate\n```\n\n**Linux/Mac:**\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n### 3. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\nThis will install all required packages including:\n- pandas, numpy (data processing)\n- torch, transformers (deep learning)\n- scikit-learn (metrics and evaluation)\n- openai (API client for xAI and DeepSeek)\n- google-generativeai (Google Gemini API)\n- python-dotenv (environment variable management)\n\n## API Configuration\n\nThe project uses a centralized configuration system to manage API keys securely.\n\n### 1. Create Environment File\n\nCopy the example environment file to create your own:\n\n**Windows:**\n```cmd\ncopy .env.example .env\n```\n\n**Linux/Mac:**\n```bash\ncp .env.example .env\n```\n\n### 2. Add Your API Keys\n\nOpen the `.env` file in a text editor and replace the placeholder values with your actual API keys:\n\n```env\n# xAI (Grok) API Configuration\nXAI_API_KEY=xai-your_actual_key_here\nXAI_BASE_URL=https://api.x.ai/v1\n\n# Google (Gemini) API Configuration\nGOOGLE_API_KEY=your_actual_google_api_key_here\n\n# DeepSeek API Configuration\nDEEPSEEK_API_KEY=sk-your_actual_deepseek_key_here\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n```\n\n### 3. Obtaining API Keys\n\n#### xAI (Grok) API\n1. Visit [xAI Console](https://console.x.ai/)\n2. Sign up or log in\n3. Navigate to API Keys section\n4. Create a new API key\n5. Copy the key (format: `xai-...`)\n\n#### Google Gemini API\n1. Visit [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Sign in with your Google account\n3. Click \"Create API Key\"\n4. Copy the generated key\n\n#### DeepSeek API\n1. Visit [DeepSeek Platform](https://platform.deepseek.com/)\n2. Sign up or log in\n3. Go to API Keys section\n4. Generate a new key\n5. Copy the key (format: `sk-...`)\n\n### 4. Verify Configuration\n\nThe `config.py` module automatically loads and validates your API keys. When you run any script that uses LLM APIs, it will check if the required keys are present.\n\n**Security Best Practices:**\n- ✅ **NEVER** commit your `.env` file to version control\n- ✅ The `.gitignore` file already excludes `.env` files\n- ✅ Only share `.env.example` as a template\n- ✅ Keep your API keys confidential\n- ✅ Rotate keys if they are accidentally exposed\n\n## Project Configuration System\n\nThe project uses a modular configuration approach:\n\n- **config.py**: Central configuration module that reads from `.env`\n- **Config class**: Provides methods to access API configurations:\n  - `Config.get_xai_config()` - Returns xAI API configuration\n  - `Config.get_google_config()` - Returns Google API configuration\n  - `Config.get_deepseek_config()` - Returns DeepSeek API configuration\n  - `Config.validate_api_keys()` - Validates required API keys\n\nAll scripts in `src/NO-fold/Grok/`, `src/NO-fold/Google/`, and `src/NO-fold/DeepSeek/` automatically import and use this configuration.\n\n## Data Setup\n\nThe raw dataset is not included in this repository due to data use agreements. To obtain access:\n\n1. Contact **hialex.li@connect.polyu.hk**\n2. CC **xinhong.chen@my.cityu.edu.hk**\n3. Request access to the suicide risk prediction dataset\n4. Sign the Data Use Agreement (DUA) they provide\n5. Once received, place the data in the appropriate directory and run `preprocessing.ipynb`\n\n## Running Experiments\n\n### RoBERTa Fine-Tuning (K-Fold)\n\nNavigate to the appropriate directory and run the training script:\n\n```bash\ncd src/K-fold/large-cross-entropy--5e-5\npython finetune_roberta.py\n```\n\n### LLM Inference\n\nFor running LLM-based experiments:\n\n```bash\ncd src/NO-fold/Grok\npython grok-3.py\n```\n\n```bash\ncd src/NO-fold/Google\npython gemini-2.5-flash.py\n```\n\n```bash\ncd src/NO-fold/DeepSeek\npython deepseek-reasoner.py\n```\n\n## Troubleshooting\n\n### Missing API Keys Error\n```\nValueError: Missing required API key(s): XAI_API_KEY\n```\n**Solution**: Ensure your `.env` file exists and contains the correct API key.\n\n### Import Error for dotenv\n```\nModuleNotFoundError: No module named 'dotenv'\n```\n**Solution**: Install python-dotenv:\n```bash\npip install python-dotenv\n```\n\n### API Rate Limiting\nIf you encounter rate limit errors, the scripts include automatic retry logic. You may need to:\n- Wait and retry later\n- Upgrade your API tier\n- Reduce concurrent requests\n\n### Virtual Environment Issues\nIf packages aren't found after installation, ensure your virtual environment is activated:\n- Windows: `venv\\Scripts\\activate`\n- Linux/Mac: `source venv/bin/activate`\n\n## Need Help?\n\nFor issues related to:\n- **Code/Repository**: Open an issue on GitHub\n- **Data Access**: Contact the data providers listed above\n- **API Issues**: Consult the respective API documentation:\n  - [xAI API Docs](https://docs.x.ai/)\n  - [Google Gemini Docs](https://ai.google.dev/docs)\n  - [DeepSeek API Docs](https://platform.deepseek.com/api-docs/)\n\n---\n\n## License & Citation\n\nPlease refer to the main README for license information and citation guidelines.\n"}}}}