GEMINI.md

# Project Gemini: YouTube Dual-Language Subtitle Backend Service

This document outlines the development guidelines, architecture, and technology stack for the YouTube Dual-Language Subtitle translation service.

## 1. Core Mission

To create a free, open-source, and self-hosted backend service that provides English-to-Chinese translation for a companion browser extension. The service is designed for efficient deployment on **Hugging Face Spaces**.

## 2. Architecture Overview

The project is a standalone Python-based microservice built with FastAPI. It exposes a single API endpoint to receive text, translates it using a pre-loaded Hugging Face model, and returns the result. This design allows the heavy lifting of AI translation to be handled by a dedicated, scalable server.

## 3. Technology Stack

### Backend (Translation Service)
-   **Framework**: Python with FastAPI (for creating a high-performance API)
-   **AI/ML Library**: Hugging Face `transformers` and `torch`
-   **Translation Model**: `Helsinki-NLP/opus-mt-en-zh` (A lightweight, high-quality model for English-to-Chinese translation)
-   **Server**: Uvicorn

## 4. Deployment & Development on Hugging Face Spaces

### Primary Hosting & Version Control
-   **Platform**: **Hugging Face Spaces** is used for both hosting the service and the Git repository.
-   **Deployment Trigger**: Pushing code to the `main` branch of the Hugging Face repository automatically triggers a new build and deployment on the Space.

### Hugging Face Spaces Best Practices
1.  **`app.py`**: The main application file must be named `app.py` and located at the root of the repository. It will contain the FastAPI application logic.
2.  **`requirements.txt`**: All Python dependencies must be listed in a `requirements.txt` file. The Space will automatically install these dependencies upon deployment.
3.  **Secrets Management**: Use Hugging Face Space Secrets for storing any sensitive information. Do not hardcode secrets in the source code. For local development, `huggingface-cli login` can be used to manage credentials.
4.  **Resource Configuration**: The `README.md` file's metadata block (YAML front matter) is used to configure the Space's hardware. For this project, a CPU instance is sufficient and should be specified to optimize resource allocation.
5.  **Health Checks**: FastAPI provides a default `/docs` endpoint which serves as a basic health check to verify the service is running.

### API Workflow
1.  **Request**: The service waits for a POST request to its `/translate` endpoint. The request body should contain the English text to be translated.
2.  **Translate**: The service utilizes the `Helsinki-NLP/opus-mt-en-zh` model to translate the received text into Chinese.
3.  **Respond**: The service returns a JSON object containing the translated text.

### Error Handling
-   The backend will include robust error handling for invalid requests, translation failures, or other server-side issues. It will return appropriate HTTP status codes and clear error messages in the response body.

## 5. Code Quality & Conventions

-   **Naming**: Use descriptive and clear names for variables and functions (e.g., `translate_text`, `translation_router`).
-   **Comments**: Add comments to explain the "why" behind complex logic, not the "what".
-   **Style**: Follow standard Python (PEP 8) and FastAPI best practices.
-   **Commit Messages**: Keep commit titles concise, lowercase, and under 70 characters.