Initial commit for text translation app

Dockerfile

@@ -0,0 +1,22 @@
+# Choose an appropriate Python base image
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container
+# Ensure this requirements.txt is in your GitHub repo and lists streamlit, requests, python-dotenv
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy your application code (app.py and any other needed files) into the container
+COPY . .
+
+# Expose the port Streamlit runs on (default is 8501)
+EXPOSE 8501
+
+# Command to run your Streamlit application
+# Ensure HUGGING_FACE_API_TOKEN is set as a secret in your HF Space settings
+CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

README.md

@@ -0,0 +1,142 @@
+---
+title: HF Sentiment Analyzer
+emoji: 🤗 # You can choose an emoji
+colorFrom: blue # Or any color
+colorTo: green # Or any color
+sdk: docker
+app_file: app.py
+# For Docker, you don't usually specify sdk_version directly here
+# unless the template specifically requires it.
+# If your Dockerfile handles Python/Streamlit versions, that's usually enough.
+# If the Streamlit Docker Template implies a specific Dockerfile or setup,
+# then 'sdk: docker' and 'app_file: app.py' are key.
+# The template might also have set 'dockerfile: Dockerfile' if it expects one.
+pinned: false
+---
+
+# 🌍 Hugging Face Text Translation Tool
+
+An interactive web application that translates text into various languages using Hugging Face's state-of-the-art translation models via the Inference API. This project is part of a 4-week AI project portfolio building challenge.
+
+**Live Demo:** [Link to your Deployed App on Hugging Face Spaces]
+
+**Project Repository:** `https://github.com/dylangamachefl/hf-text-translator` (Or your actual repo name)
+
+![Screenshot of Text Translator App](translator-screenshot.png)
+*(Replace `translator-screenshot.png` with the actual path/name if different, or embed the image directly if preferred by dragging it into the GitHub text editor for the README)*
+
+## 📖 Overview
+
+This application provides a simple and intuitive interface for users to:
+1.  Input text they wish to translate.
+2.  Select a target language from a predefined list.
+3.  Receive the translated text, processed by powerful models hosted on Hugging Face.
+
+The primary goal is to demonstrate the ability to integrate with external AI services (Hugging Face Inference API) and build a functional NLP application with a user-friendly UI.
+
+## 🎯 Problem Solved
+
+In an increasingly globalized world, language barriers can hinder communication and access to information. This tool offers a quick and accessible way to translate text, helping to bridge these gaps. It showcases how pre-trained AI models can be leveraged to build practical solutions for common language-related tasks.
+
+## ✨ Skills Showcased
+
+*   **AI/ML Implementation:** Utilizing pre-trained NLP models for a specific task (translation).
+*   **Python:** Core programming language for backend logic and API interaction.
+*   **ML Libraries (Conceptual):** Understanding the role and use of Hugging Face Transformers (even if used via API).
+*   **API Integration:** Connecting to and consuming the Hugging Face Inference API.
+*   **Data Handling:** Sending text data to the API and parsing JSON responses.
+*   **NLP (using APIs):** Practical application of Natural Language Processing for translation.
+*   **Web Development (UI):** Building an interactive user interface with Streamlit.
+*   **Environment Management:** Use of `.env` for API keys.
+*   **Version Control:** Git and GitHub for project management.
+*   **Deployment:** Deploying the application to Hugging Face Spaces.
+*   **Documentation:** Creating clear and concise project documentation (this README).
+
+## 🛠️ How It Works
+
+1.  **User Input:** The user types or pastes the text they want to translate into a text area.
+2.  **Language Selection:** The user selects the desired target language from a dropdown menu. Each language option is mapped to a specific Hugging Face translation model ID (primarily from the Helsinki-NLP group, e.g., `Helsinki-NLP/opus-mt-en-es` for English to Spanish).
+3.  **API Call:** When the "Translate" button is clicked:
+    *   The Python backend (using the `requests` library) constructs a POST request to the Hugging Face Inference API endpoint for the selected model.
+    *   The input text is sent in the JSON payload.
+    *   The Hugging Face API token (loaded securely from environment variables) is included in the request headers for authentication.
+4.  **Processing:** The Hugging Face infrastructure runs the inference on the chosen translation model.
+5.  **Response Handling:** The application receives the API's JSON response, which contains the translated text (typically within a list and dictionary structure like `[{'translation_text': '...'}]`).
+6.  **Display Output:** The translated text is extracted from the response and displayed to the user in the Streamlit interface. Error handling is implemented to manage API issues or unexpected responses.
+
+## 💻 Technologies Used
+
+*   **Programming Language:** Python 3.x
+*   **AI Models/API:**
+    *   Hugging Face Hub
+    *   Hugging Face Inference API (Free Tier)
+    *   Helsinki-NLP Translation Models (e.g., `opus-mt-*`)
+*   **Python Libraries:**
+    *   `streamlit`: For building the web application UI.
+    *   `requests`: For making HTTP requests to the Hugging Face API.
+    *   `python-dotenv`: For managing environment variables (like the API token) locally.
+*   **Version Control:** Git & GitHub
+*   **Deployment:** Hugging Face Spaces
+*   **Development Environment:** Visual Studio Code (or your preferred IDE), Python Virtual Environment (`venv`)
+
+## 🚀 Setup and Local Development
+
+To run this project locally, follow these steps:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/[Your GitHub Username]/hf-text-translator.git
+    cd hf-text-translator
+    ```
+
+2.  **Set up a Python virtual environment:**
+    (Assuming you have a shared `venv` in a parent `ai-portfolio` directory as per the overall plan)
+    ```bash
+    # From within hf-text-translator directory:
+    # For macOS/Linux:
+    source ../venv/bin/activate
+    # For Windows (Git Bash or PowerShell):
+    # source ../venv/Scripts/activate
+    # For Windows (Command Prompt):
+    # ..\venv\Scripts\activate
+    ```
+    If you don't have the shared venv or prefer a dedicated one for this project:
+    ```bash
+    python -m venv venv
+    # Activate it:
+    # macOS/Linux: source venv/bin/activate
+    # Windows: venv\Scripts\activate
+    ```
+
+3.  **Install dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4.  **Set up your Hugging Face API Token:**
+    *   Create a `.env` file in the root of your main `ai-portfolio` project directory (i.e., one level above this `hf-text-translator` project).
+    *   Add your Hugging Face API token to the `.env` file:
+        ```
+        HUGGING_FACE_API_TOKEN="your_hf_api_token_here"
+        ```
+    *   *Note: The `app.py` is configured to look for `.env` in the parent directory. If your `.env` file is elsewhere, you might need to adjust the `load_dotenv()` path in `app.py`.*
+
+5.  **Run the Streamlit application:**
+    ```bash
+    streamlit run app.py
+    ```
+    The application should open in your web browser.
+
+## 🔮 Future Enhancements (Optional)
+
+*   **Auto-detect source language:** Implement a feature to automatically detect the language of the input text.
+*   **Support more languages:** Expand the list of available target languages by adding more Helsinki-NLP models.
+*   **Batch translation:** Allow users to upload a file for translating multiple pieces of text.
+*   **Improved UI/UX:** Further refine the user interface for better aesthetics and usability.
+
+## 🙏 Acknowledgements
+
+*   The Hugging Face team for their incredible models, Inference API, and Spaces platform.
+*   The developers of Streamlit for making web app creation in Python so accessible.
+
+---

app.py

@@ -0,0 +1,175 @@
+import streamlit as st
+import requests
+import os
+from dotenv import load_dotenv
+
+# --- Configuration ---
+# Attempt to load .env file.
+# Assumes .env is in the parent directory of this script's location (e.g., ../.env)
+# If your app.py is in the root of your project (where .env also is),
+# load_dotenv() without arguments might work.
+# For Hugging Face Spaces, you'll set secrets directly in the Space settings.
+dotenv_path = os.path.join(
+    os.path.dirname(__file__), "..", ".env"
+)  # Path to .env in parent directory
+if os.path.exists(dotenv_path):
+    load_dotenv(dotenv_path=dotenv_path)
+else:
+    # Fallback if .env is in the current directory (less likely for multi-project setup)
+    load_dotenv()
+
+
+API_TOKEN = os.getenv("HUGGING_FACE_API_TOKEN")
+API_URL_BASE = "https://api-inference.huggingface.co/models/"
+HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}
+
+# Define available models (user-friendly name: model_id)
+# You can find more models at https://huggingface.co/models?pipeline_tag=translation
+# Filter by source language and target language.
+TRANSLATION_MODELS = {
+    "English to Spanish": "Helsinki-NLP/opus-mt-en-es",
+    "English to French": "Helsinki-NLP/opus-mt-en-fr",
+    "English to German": "Helsinki-NLP/opus-mt-en-de",
+    "English to Chinese (Simplified)": "Helsinki-NLP/opus-mt-en-zh",
+    "English to Japanese": "Helsinki-NLP/opus-mt-en-jap",  # Check model hub for exact ID if this doesn't work
+    "Spanish to English": "Helsinki-NLP/opus-mt-es-en",
+    "French to English": "Helsinki-NLP/opus-mt-fr-en",
+    # Add more models/languages as desired
+}
+
+
+# --- Hugging Face API Call Function ---
+def query_translation(text_to_translate, model_id):
+    """
+    Sends a request to the Hugging Face Inference API for translation.
+    """
+    if not API_TOKEN:  # Check if token was loaded
+        st.error(
+            "Hugging Face API Token not found. Please configure it in your .env file or Space secrets."
+        )
+        return None
+
+    api_url = API_URL_BASE + model_id
+    payload = {"inputs": text_to_translate}
+
+    try:
+        response = requests.post(
+            api_url, headers=HEADERS, json=payload, timeout=30
+        )  # Added timeout
+        response.raise_for_status()  # Raises an HTTPError for bad responses (4XX or 5XX)
+        return response.json()
+    except requests.exceptions.HTTPError as errh:
+        st.error(f"Translation API HTTP Error: {errh}")
+        error_details = "No additional details from API."
+        try:
+            error_details = response.json().get("error", response.text)
+        except ValueError:  # If response.text is not JSON
+            error_details = response.text
+        st.info(f"Details: {error_details}")
+        return None
+    except requests.exceptions.ConnectionError as errc:
+        st.error(f"Translation API Connection Error: {errc}")
+        return None
+    except requests.exceptions.Timeout as errt:
+        st.error(f"Translation API Timeout Error: {errt}")
+        return None
+    except requests.exceptions.RequestException as err:
+        st.error(f"Translation API Request Error: {err}")
+        return None
+    except (
+        ValueError
+    ):  # If response is not JSON (should be caught by response.json() above but good to have)
+        st.error("Error: Received non-JSON response from translation API.")
+        st.info(
+            f"Raw Response: {response.text if 'response' in locals() else 'No response object'}"
+        )
+        return None
+
+
+# --- Streamlit UI ---
+st.set_page_config(page_title="🌍 Text Translator", layout="wide")
+
+st.title("🌍 Text Translation Tool")
+st.markdown(
+    "Translate text into various languages using Hugging Face's Inference API. "
+    "This app demonstrates API integration for NLP tasks."
+)
+
+# Check for API token at the beginning of UI rendering
+if not API_TOKEN:
+    st.error("Hugging Face API Token not configured. The application cannot function.")
+    st.markdown(
+        "Please ensure your `HUGGING_FACE_API_TOKEN` is set in a `.env` file "
+        "in the root of your `ai-portfolio` project or as a secret if deploying on Hugging Face Spaces."
+    )
+    st.stop()  # Stop further execution of the script if token is missing
+
+# Layout columns
+col1, col2 = st.columns([2, 1])  # Text area takes 2/3, selectbox takes 1/3
+
+with col1:
+    text_input = st.text_area(
+        "Enter text to translate:",
+        height=200,
+        key="text_input_translate",
+        placeholder="Type or paste your text here...",
+    )
+
+with col2:
+    selected_language_name = st.selectbox(
+        "Select target language:",
+        options=list(TRANSLATION_MODELS.keys()),
+        index=0,  # Default to the first language in the list
+        key="lang_select",
+    )
+    model_id_to_use = TRANSLATION_MODELS[selected_language_name]
+    st.caption(f"Using model: `{model_id_to_use}`")
+
+
+if st.button("Translate Text", key="translate_button", type="primary"):
+    if text_input:
+        if not API_TOKEN:  # Redundant check, but good for safety
+            st.error("API Token is missing. Cannot proceed.")
+        else:
+            with st.spinner(f"Translating to {selected_language_name}... Please wait."):
+                translation_result = query_translation(text_input, model_id_to_use)
+
+            if translation_result:
+                # The API returns a list with a dictionary inside
+                if (
+                    isinstance(translation_result, list)
+                    and len(translation_result) > 0
+                    and "translation_text" in translation_result[0]
+                ):
+                    translated_text = translation_result[0]["translation_text"]
+                    st.subheader("📜 Translation:")
+                    st.success(translated_text)
+                # Sometimes the API might return a dictionary directly with an error
+                elif isinstance(translation_result, dict) and translation_result.get(
+                    "error"
+                ):
+                    # Error is already displayed by the query_translation function
+                    st.warning("Translation failed. See error message above.")
+                else:
+                    st.error(
+                        "Translation failed or the API returned an unexpected format."
+                    )
+                    st.json(translation_result)  # Show the raw response for debugging
+            # If translation_result is None, query_translation already showed an error
+    else:
+        st.warning("Please enter some text to translate.")
+
+st.divider()
+st.sidebar.header("ℹ️ About This App")
+st.sidebar.info(
+    "This tool demonstrates the use of the Hugging Face Inference API "
+    "for text translation. It allows users to input text and select a target "
+    "language, then displays the translated output."
+    "\n\n**Key Skills Showcased:**"
+    "\n- Python & Streamlit for UI"
+    "\n- Hugging Face API Integration"
+    "\n- Handling API responses & errors"
+    "\n- Basic NLP application"
+)
+st.sidebar.markdown("---")
+st.sidebar.markdown("Project for **AI Project Portfolio (4 Weeks)**")

requirements.txt

@@ -0,0 +1,3 @@
+streamlit
+requests
+python-dotenv