{"id":29704292,"url":"https://github.com/mindscope-world/ovarian-cyst-detection","last_synced_at":"2025-07-23T14:10:00.100Z","repository":{"id":301152010,"uuid":"1008229166","full_name":"mindscope-world/Ovarian-Cyst-Detection","owner":"mindscope-world","description":"Ovarian Cyst Analysis API","archived":false,"fork":false,"pushed_at":"2025-07-02T12:06:21.000Z","size":128,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-02T13:24:57.233Z","etag":null,"topics":["llms"],"latest_commit_sha":null,"homepage":"https://ovarian-cyst-detection.onrender.com/docs","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mindscope-world.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T08:17:47.000Z","updated_at":"2025-07-02T12:06:24.000Z","dependencies_parsed_at":"2025-06-25T12:37:28.152Z","dependency_job_id":null,"html_url":"https://github.com/mindscope-world/Ovarian-Cyst-Detection","commit_stats":null,"previous_names":["mindscope-world/ovarian-cyst-detection"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mindscope-world/Ovarian-Cyst-Detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindscope-world%2FOvarian-Cyst-Detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindscope-world%2FOvarian-Cyst-Detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindscope-world%2FOvarian-Cyst-Detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindscope-world%2FOvarian-Cyst-Detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mindscope-world","download_url":"https://codeload.github.com/mindscope-world/Ovarian-Cyst-Detection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindscope-world%2FOvarian-Cyst-Detection/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266691580,"owners_count":23969182,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["llms"],"created_at":"2025-07-23T14:09:59.338Z","updated_at":"2025-07-23T14:10:00.078Z","avatar_url":"https://github.com/mindscope-world.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"Of course. That's an excellent and crucial addition. A user needs to know exactly what data to provide to the prediction endpoint.\n\nI will update the `README.md` to include a detailed table explaining each field for the `/predict` endpoint, including the data type and the specific, allowed string values for categorical features. This makes the documentation much more useful.\n\nHere is the complete, updated `README.md` file. The changes are in the **\"API Usage\" -\u003e \"ML Prediction Endpoint\"** section.\n\n---\n\n# Ovarian Cyst Analysis API\n\nThis project provides a powerful API for analyzing ovarian cyst data, built with Python and FastAPI. It offers two primary functionalities:\n1.  **Machine Learning Prediction:** An endpoint that uses a pre-trained scikit-learn model to predict the recommended management plan for a patient based on their clinical data.\n2.  **AI-Powered Chatbot:** An intelligent chatbot, powered by Google's Gemini Pro model, that allows users to ask natural language questions about the entire patient dataset.\n\nThe application is built with a modular and scalable structure, making it easy to maintain and extend.\n\n## ✨ Features\n\n- **ML-Powered Predictions**: Get instant recommendations for patient management (`Observation`, `Surgery`, `Medication`, etc.).\n- **Conversational AI Chatbot**: Interact with your data using natural language. Ask for statistics, filter data, or look up specific patient information.\n- **FastAPI Backend**: A high-performance, easy-to-use asynchronous API framework.\n- **Interactive Documentation**: Automatic, interactive API documentation powered by Swagger UI and ReDoc.\n- **Modular Project Structure**: Code is organized by feature (`api`, `services`, `core`, `models`) for better maintainability.\n- **Environment-based Configuration**: Securely manage API keys and settings using a `.env` file.\n\n## 🛠️ Tech Stack\n\n- **Backend**: FastAPI, Uvicorn\n- **Machine Learning**: Scikit-learn, Pandas, Joblib\n- **Generative AI**: Google Gemini Pro (`google-generativeai`)\n- **Language**: Python 3.10+\n\n## 📁 Project Structure\n\nThe project is organized into distinct modules for clear separation of concerns.\n\n```\n/\n├── .env                  # Environment variables (API keys, settings)\n├── main.py               # Main application entrypoint\n├── build.sh              # Deployment build script for Render\n├── requirements.txt      # Project dependencies\n├── ovarian_cyst_inference_artifacts.joblib # The trained ML model\n|\n├── data/\n│   └── Ovarian_Cyst_Track_Data.csv  # The dataset for the chatbot\n|\n├── api/                  # API endpoint definitions (routers)\n│   ├── ...\n|\n├── services/             # Business logic (e.g., calling Gemini)\n│   ├── ...\n|\n├── core/                 # Application configuration\n│   ├── ...\n|\n└── models/               # Pydantic data models (schemas)\n    ├── ...\n```\n\n## 🚀 Getting Started (Local Development)\n\nFollow these instructions to get the project up and running on your local machine.\n\n### 1. Prerequisites\n\n- Python 3.10 or newer\n- A Google API Key with the \"Generative Language API\" enabled. You can get one from [Google AI Studio](https://makersuite.google.com/app/apikey).\n\n### 2. Installation \u0026 Configuration\n\n1.  **Clone the repository** and navigate into the project directory.\n2.  **Create and activate a virtual environment** (e.g., `python3 -m venv venv` and `source venv/bin/activate`).\n3.  **Install dependencies:** `pip install -r requirements.txt`.\n4.  **Create a `.env` file** in the root directory and add your Google API key: `GOOGLE_API_KEY=YOUR_ACTUAL_API_KEY_HERE`.\n\n### 3. Running the Application\n\nStart the FastAPI server using Uvicorn:\n\n```bash\nuvicorn main:app --reload\n```\n\n- **Interactive Docs (Swagger UI)**: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)\n\n## ☁️ Deployment (to Render)\n\nThis application is ready to be deployed for free on [Render](https://render.com/).\n\n1.  **Prepare:** Make sure you have `requirements.txt` and a `build.sh` file in your repository.\n    - `build.sh` should contain:\n      ```sh\n      #!/usr/bin/env bash\n      set -o errexit\n      pip install -r requirements.txt\n      ```\n2.  **Deploy on Render:**\n    - Create a new **Web Service** and connect your GitHub repo.\n    - **Build Command:** `./build.sh`\n    - **Start Command:** `uvicorn main:app --host 0.0.0.0 --port $PORT`\n    - **Instance Type:** `Free`\n    - **Add Environment Variable:** `GOOGLE_API_KEY` with your key as the value.\n    - Click **Create Web Service**.\n\n## 📖 API Usage\n\nYou can use the interactive `/docs` page on your live URL to test the endpoints or use a tool like `curl`.\n\n### 1. AI Chatbot Endpoint\n\n- **Endpoint:** `POST /chatbot`\n- **Purpose:** Ask a natural language question about the ovarian cyst dataset.\n\n### 2. ML Prediction Endpoint\n\n- **Endpoint:** `POST /predict`\n- **Purpose:** Get a recommended management plan for a single patient based on clinical features.\n\nThe endpoint requires a JSON object with the following fields:\n\n| Field                       | Data Type | Description / Valid Values                                                                                             |\n| :-------------------------- | :-------- | :--------------------------------------------------------------------------------------------------------------------- |\n| `Age`                       | `integer` | The patient's age in years.                                                                                            |\n| `Menopause_Status`          | `string`  | The patient's menopausal status. **Must be one of:**\u003cbr\u003e`\"Pre-menopausal\"` or `\"Post-menopausal\"`                          |\n| `Cyst_Size_cm`              | `float`   | The size of the cyst in centimeters (e.g., `5.5`).                                                                     |\n| `Cyst_Growth_Rate_cm_month` | `float`   | The rate of cyst growth per month (e.g., `0.5`).                                                                       |\n| `CA_125_Level`              | `integer` | The CA 125 cancer antigen level.                                                                                       |\n| `Ultrasound_Features`       | `string`  | The observed features from the ultrasound. **Must be one of:**\u003cbr\u003e`\"Simple cyst\"`, `\"Complex cyst\"`, `\"Septated cyst\"`, `\"Hemorrhagic cyst\"`, `\"Solid mass\"` |\n| `Reported_Symptoms`         | `string`  | A single, comma-separated string of symptoms. Can be an empty string (`\"\"`) if there are no symptoms.\u003cbr\u003e_Example: `\"Pelvic pain, Nausea, Bloating\"`_ |\n\n\u003cbr\u003e\n\n**Example Request Body:**\n\n```json\n{\n  \"Age\": 59,\n  \"Menopause_Status\": \"Post-menopausal\",\n  \"Cyst_Size_cm\": 2.2,\n  \"Cyst_Growth_Rate_cm_month\": 0.5,\n  \"CA_125_Level\": 123,\n  \"Ultrasound_Features\": \"Hemorrhagic cyst\",\n  \"Reported_Symptoms\": \"Pelvic pain, Irregular periods, Bloating\"\n}\n```\n\n**Success Response:**\n\n```json\n{\n  \"recommended_management\": \"Referral\"\n}\n```\n\n## 🚑 Troubleshooting\n\n- **Problem:** `FATAL ERROR: ... InconsistentVersionWarning`\n  - **Cause:** The `.joblib` model file was created with a different `scikit-learn` version.\n  - **Solution (Recommended):** Re-run the model training script to generate a new, compatible `.joblib` file and push it to your repository.\n  - **Solution (Quick Fix):** Downgrade your scikit-learn version in `requirements.txt` to match the version the model was saved with (e.g., `scikit-learn==1.6.1`).\n\n- **Problem:** Chatbot returns configuration errors.\n  - **Solution:**\n    1. Ensure the `data/Ovarian_Cyst_Track_Data.csv` file exists in your repository.\n    2. Ensure the `GOOGLE_API_KEY` environment variable is set correctly on Render.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindscope-world%2Fovarian-cyst-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmindscope-world%2Fovarian-cyst-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindscope-world%2Fovarian-cyst-detection/lists"}