--- title: CV to CSV Extraction App emoji: 📄 colorFrom: blue colorTo: green sdk: gradio sdk_version: 5.29.0 python_version: 3.13 app_file: app.py pinned: false short_description: Extract scholarly accomplishments from faculty CVs --- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference # CV to CSV Extraction App A Gradio application that extracts publications, talks, and other scholarly accomplishments from faculty CVs (PDFs) using Google's Gemini API with native PDF understanding and native structured output. The app now defaults to `gemini-3-flash-preview`, with an optional `GEMINI_MODEL` environment override so the Space can be updated without editing code again. Recommended deployment: - Google Cloud Run for the most reliable hosted behavior - Hugging Face Spaces for lightweight/demo hosting ## Features - Extract scholarly accomplishments from faculty CVs in PDF format - Categorize accomplishments into different types (books, journal articles, conference presentations, etc.) - Display results in a tabular format - Download results as CSV - Password protection using Hugging Face secrets - Native Gemini PDF extraction via the Files API - Native Gemini structured-output extraction with Pydantic schemas - Request-scoped logging for extraction timing and fallback behavior ## Installation 1. Clone this repository: ``` git clone cd CV_to_CSV ``` 2. Install the required dependencies: ``` pip install -r requirements.txt ``` The project is configured and tested against Python 3.13. 3. Create a `.env` file in the root directory with your Gemini API key: ``` GOOGLE_API_KEY=your_google_api_key_here APP_PASSWORD=your_app_password_here GEMINI_MODEL=gemini-3-flash-preview ``` Optional tuning: ``` GEMINI_TIMEOUT_SECONDS=120 GEMINI_FILE_READY_TIMEOUT_SECONDS=60 GEMINI_THINKING_LEVEL=high GEMINI_TEMPERATURE= ``` ## Usage ### Running Locally 1. Run the application: ``` python cv_extraction_app.py ``` 2. Open your browser and navigate to `http://localhost:7860` 3. Enter the password (if set in the environment variable `APP_PASSWORD`) 4. Upload one or more faculty CV PDFs and click "Extract Accomplishments" 5. View the extracted accomplishments and download as CSV if desired ### Using the Gradio API The extraction endpoint accepts both the uploaded PDFs and the app password: ```python from gradio_client import Client, handle_file client = Client("Zwounds/cv-to-csv-extractor") results, csv_file = client.predict( [handle_file("ZweibelCV.pdf")], "your_app_password_here", api_name="/extract_accomplishments", ) ``` Browser users can still log in normally; the UI reuses the same password internally for extraction. ### Deploying on Google Cloud Run Cloud Run is the recommended production deployment target for this app. The repo includes a `Dockerfile` and binds Gradio to `0.0.0.0:$PORT` automatically when `PORT` is present. Recommended deployment: ```bash gcloud run deploy cv-to-csv-extractor \ --source . \ --region us-central1 \ --allow-unauthenticated \ --cpu 1 \ --memory 1Gi \ --concurrency 10 \ --max-instances 1 \ --timeout 900 \ --set-secrets APP_PASSWORD=your_app_password_here,GEMINI_API_KEY=your_gemini_key_here ``` Notes: - `--concurrency 10` with `--max-instances 1` keeps Gradio queue/SSE traffic on one instance while still allowing the browser and API client to open multiple HTTP connections. - Prefer `--set-secrets` over plain `--set-env-vars` for `APP_PASSWORD` and `GEMINI_API_KEY`. - The app logs request IDs, per-file timing, model/fallback behavior, and CSV output paths, which makes Cloud Run logs useful for debugging slow or inconsistent runs. ### Deploying on Hugging Face Spaces 1. Create a new Space on Hugging Face Spaces with the Gradio SDK 2. Upload your code to the Space 3. Set up the following secrets in your Space settings: - `GOOGLE_API_KEY`: Your Google Gemini API key - `APP_PASSWORD`: The password you want to use for app authentication 4. Optional environment variable: - `GEMINI_MODEL`: Override the default model name if you want to move off `gemini-3-flash-preview` later without changing code Hugging Face Spaces remains supported, but hosted behavior may be more variable under repeated runs than Cloud Run. ## How It Works 1. **Authentication**: The app checks if the provided password matches the one stored in the environment variable `APP_PASSWORD` 2. **PDF Processing**: - The app uploads each PDF directly to Gemini using the Files API - PDF metadata is still read locally with PyPDF2 for faculty-name fallback when needed 3. **LLM Processing with Native Structured Output**: - The uploaded PDF is processed with `google-genai` using Gemini's native `response_schema` support - Pydantic models define the expected structured output shape - The app sets explicit upload, timeout, and thinking controls for hosted reliability - If the primary extraction fails, the app falls back to a shorter structured-output prompt against the same uploaded PDF before giving up 4. **Categorization**: Accomplishments are categorized into different types based on a decision tree approach 5. **Results Display**: The extracted accomplishments are displayed in a tabular format and can be downloaded as CSV ## Structured Output The app uses Gemini's native structured-output support to improve extraction reliability: - **Defined Data Models**: Clear Pydantic schemas for faculty data and accomplishments - **Type Validation**: Ensures fields like years and confidence scores are properly typed - **Schema-Guided Output**: Gemini is constrained by `response_schema` instead of prompt-shaped JSON - **Native PDF Understanding**: Gemini sees the original PDF rather than a local text extraction - **Fallback Mechanism**: If the primary structured extraction fails, the app retries with a shorter structured prompt against the uploaded PDF ## Customization ### Changing the Password To change the password, update the `APP_PASSWORD` environment variable: - Locally: Modify the `.env` file - On Hugging Face Spaces: Update the secret in the Space settings ### Modifying Categories To modify the categories of scholarly accomplishments, edit the `MAIN_CATEGORIES` and `SCHOLARLY_WORK_TYPES` lists in `cv_extraction_app.py`. ## Troubleshooting - **API Key Issues**: Ensure `GOOGLE_API_KEY` or `GEMINI_API_KEY` is correctly set in the environment variables - **PDF Upload Errors**: Some PDFs may be password-protected or otherwise fail Gemini file processing - **LLM Processing Errors**: If the LLM fails to extract accomplishments, try adjusting `GEMINI_TIMEOUT_SECONDS`, `GEMINI_FILE_READY_TIMEOUT_SECONDS`, `GEMINI_THINKING_LEVEL`, or `GEMINI_MODEL` - **Repeated Hosted Hangs**: Prefer Cloud Run if repeated requests on Hugging Face Spaces become inconsistent ## License This project is licensed under the MIT License.