phonetic mcp

.dockerignore

@@ -0,0 +1,91 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+
+# CI
+.codeclimate.yml
+.travis.yml
+.taskcluster.yml
+
+# Docker
+docker-compose.yml
+Dockerfile
+.docker
+.dockerignore
+
+# Byte-compiled / optimized / DLL files
+**/__pycache__/
+**/*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Virtual environment
+.env
+.venv/
+venv/
+
+# PyCharm
+.idea
+
+# Python mode for VIM
+.ropeproject
+**/.ropeproject
+
+# Vim swap files
+**/*.swp
+
+# VS Code
+.vscode/
+
+tmp

.gemini/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}

.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+tmp
+.gemini/

.python-version

@@ -0,0 +1 @@
+3.13

Dockerfile

@@ -0,0 +1,20 @@
+#FROM 3.13.9-trixie
+FROM ghcr.io/astral-sh/uv:trixie-slim
+
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+
+#COPY --chown=user ./requirements.txt requirements.txt
+COPY --chown=user ./ .
+RUN uv sync --dev --no-cache
+
+COPY --chown=user . /app
+CMD ["uv", "run", "python", "app.py"]

GEMINI.md

@@ -0,0 +1,45 @@
+# Project Overview
+
+This is a Python-based web application that uses the Gradio framework to create a user interface for a machine learning model. The project includes LiteLLM, which suggests it interacts with various Large Language Model (LLM) APIs. The application is containerized using Docker and is likely intended for deployment on a platform like Hugging Face Spaces.
+
+**Key Technologies:**
+
+*   **Python:** The core programming language.
+*   **Gradio:** Used to build the web-based UI for the machine learning model.
+*   **LiteLLM:** A library to simplify calls to various LLM APIs.
+*   **Uvicorn:** An ASGI server used to run the Gradio application.
+*   **Docker:** Used for containerizing the application for deployment.
+*   **uv:** A fast Python package installer and resolver, used for dependency management.
+
+# Building and Running
+
+The project is set up to be run as a Docker container.
+
+**Running the Application:**
+
+The `Dockerfile` specifies the command to run the application using `uvicorn`:
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+This command starts the Uvicorn server, which serves the Gradio application defined in `app.py`.
+
+**Dependencies:**
+
+Project dependencies are managed in the `pyproject.toml` file and installed using `uv`. The main dependencies are:
+
+*   `gradio`
+*   `litellm`
+
+To install dependencies, you can use the following command:
+
+```bash
+uv sync --dev
+```
+
+# Development Conventions
+
+*   **Application Entrypoint:** The main application logic is expected to be in `app.py`. The Gradio application instance should be named `app`.
+*   **Dependency Management:** Dependencies are managed with `uv` and the `pyproject.toml` file.
+*   **Containerization:** The application is designed to be built and run as a Docker container. The `Dockerfile` in the root of the project defines the container image.

README.md

@@ -7,4 +7,98 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Phonetics MCP
+
+This is a Gradio application that provides two tools for working with phonetics:
+
+1.  **Text to Phonetics:** Converts a given text into a dictionary of possible phonetic pronunciations and their probabilities.
+2.  **Phonetics to Text:** Converts an International Phonetic Alphabet (IPA) expression into a list of possible dictations.
+
+## MCP Tools
+
+This application is designed to be used as a Model-centric Programming (MCP) service on Hugging Face Spaces. The following tools are available:
+
+### `text_to_phonetics`
+
+This tool takes a string of text and a language code and returns a dictionary of possible phonetic pronunciations and their probabilities.
+
+**Inputs:**
+
+*   `text` (string): The text to convert.
+*   `language` (string): The 2-letter language code of the text (e.g., 'en' for English).
+
+**Output:**
+
+*   `pronunciations` (dict): A dictionary where keys are phonetic pronunciations and values are their probabilities.
+
+**Example:**
+
+```json
+{
+  "text": "hello",
+  "language": "en"
+}
+```
+
+```json
+{
+  "hello": 0.99,
+  "hel": 0.01
+}
+```
+
+### `phonetics_to_text`
+
+This tool takes an International Phonetic Alphabet (IPA) expression and a language and returns a list of all possible dictations of it in that language.
+
+**Inputs:**
+
+*   `ipa` (string): The IPA expression to convert.
+*   `language` (string): The 2-letter language code of the expression (e.g., 'en' for English).
+
+**Output:**
+
+*   `dictations` (list): A list of possible dictations.
+
+**Example:**
+
+```json
+{
+  "ipa": "həˈloʊ",
+  "language": "en"
+}
+```
+
+```json
+[
+  "dictation one",
+  "dictation two"
+]
+```
+
+## Development
+
+This project is set up to be run as a Docker container.
+
+**Running the Application:**
+
+The `Dockerfile` specifies the command to run the application using `uvicorn`:
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+This command starts the Uvicorn server, which serves the Gradio application defined in `app.py`.
+
+**Dependencies:**
+
+Project dependencies are managed in the `pyproject.toml` file and installed using `uv`. The main dependencies are:
+
+*   `gradio`
+*   `litellm`
+
+To install dependencies, you can use the following command:
+
+```bash
+uv sync --dev
+```

app.py

@@ -0,0 +1,41 @@
+import gradio as gr
+from src.phonetics_mcp.phoneference import LANGUAGES, text_to_phonetics, phonetics_to_text
+
+# Create a list of tuples for the dropdown choices
+language_choices = list(LANGUAGES.items())
+
+with gr.Blocks() as demo:
+    gr.Markdown("# Phonetics MCP")
+    
+    with gr.Tab("Text to Phonetics"):
+        with gr.Row():
+            text_input = gr.Textbox(label="Text")
+            language_input_ttp = gr.Dropdown(choices=language_choices, label="Language")
+        
+        phonetics_output = gr.JSON(label="Phonetic Pronunciations")
+        
+        ttp_button = gr.Button("Convert to Phonetics")
+        ttp_button.click(
+            fn=text_to_phonetics,
+            inputs=[text_input, language_input_ttp],
+            outputs=phonetics_output,
+            api_name="text_to_phonetics"
+        )
+
+    with gr.Tab("Phonetics to Text"):
+        with gr.Row():
+            ipa_input = gr.Textbox(label="IPA Expression")
+            language_input_ptt = gr.Dropdown(choices=language_choices, label="Language")
+            
+        dictation_output = gr.JSON(label="Possible Dictations")
+        
+        ptt_button = gr.Button("Convert to Text")
+        ptt_button.click(
+            fn=phonetics_to_text,
+            inputs=[ipa_input, language_input_ptt],
+            outputs=dictation_output,
+            api_name="phonetics_to_text"
+        )
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860, mcp_server=True)

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "phonetics-mcp"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Soroush", email = "soroush@example.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "gradio[mcp]>=6.0.1",
+    "litellm>=1.80.7",
+    "pydantic>=2.12.4",
+    "python-dotenv>=1.2.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"

src/phonetics_mcp/phoneference.py

@@ -0,0 +1,140 @@
+import os
+from dotenv import load_dotenv
+import litellm
+from typing import Dict, List
+import json
+
+load_dotenv()
+
+litellm.api_key = os.getenv("NEBIUS_API_KEY")
+litellm.base_url = "https://llm.api.cloud.yandex.net/v1"
+
+TEXT_TO_PHONETICS_MODEL = os.getenv("TEXT_TO_PHONETICS_MODEL")
+TEXT_TO_PHONETICS_TEMPERATURE = float(os.getenv("TEXT_TO_PHONETICS_TEMPERATURE", 0.8))
+PHONETICS_TO_TEXT_MODEL = os.getenv("PHONETICS_TO_TEXT_MODEL")
+PHONETICS_TO_TEXT_MODEL_TEMPERATURE = float(os.getenv("PHONETICS_TO_TEXT_MODEL_TEMPERATURE", 0.6))
+
+LANGUAGES = {
+    "English": "en", "Mandarin Chinese": "zh", "Hindi": "hi", "Spanish": "es", "French": "fr",
+    "Standard Arabic": "ar", "Bengali": "bn", "Russian": "ru", "Portuguese": "pt", "Urdu": "ur",
+    "Indonesian": "id", "German": "de", "Japanese": "ja", "Swahili": "sw", "Marathi": "mr",
+    "Telugu": "te", "Turkish": "tr", "Tamil": "ta", "Punjabi": "pa", "Korean": "ko",
+    "Vietnamese": "vi", "Italian": "it", "Thai": "th", "Gujarati": "gu", "Persian": "fa",
+    "Bhojpuri": "bh", "Polish": "pl", "Odia": "or", "Maithili": "mai", "Ukrainian": "uk",
+    "Burmese": "my", "Romanian": "ro", "Dutch": "nl", "Pashto": "ps", "Kannada": "kn",
+    "Malayalam": "ml", "Sindhi": "sd", "Cambodian": "km", "Somali": "so", "Nepali": "ne",
+    "Assamese": "as", "Sinhalese": "si", "Cebuano": "ceb", "Kurdish": "ku", "Uzbek": "uz",
+    "Greek": "el", "Czech": "cs", "Swedish": "sv", "Hungarian": "hu", "Azerbaijani": "az"
+}
+
+
+async def text_to_phonetics(text: str, language_code: str) -> dict:
+    """
+    Converts text to a dictionary of possible phonetic pronunciations and their probabilities.
+    """
+    if not text:
+        return {}
+
+    try:
+        print(f"text_to_phonetics called with text: '{text}', language_code: '{language_code}'")
+        system_prompt = """
+You are an expert linguist and phonetician. Your task is to provide a detailed breakdown of possible phonetic pronunciations for a given text in a specified language.
+The output should be a JSON object where the keys are the phonetic representations in the International Phonetic Alphabet (IPA), and the values are the probabilities of that pronunciation being the correct one.
+Consider all possible nuances, dialects, and variations in pronunciation. For example, the word 'advocate' in English can be a noun or a verb, and its pronunciation changes accordingly.
+"""
+        user_prompt = f"""
+Please provide the phonetic pronunciations for the text: '{text}'
+Language: {language_code}
+
+Return the result as a JSON object with a 'pronunciations' key, which is a dictionary of IPA strings to their probabilities.
+For example for the word "advocate":
+{{
+  "pronunciations": {{
+    "/ˈæd.və.kət/": 0.7,
+    "/ˈæd.və.keɪt/": 0.3
+  }}
+}}
+
+For a word with a single pronunciation like "her", the output should be:
+{{
+  "pronunciations": {{
+    "/hɜːr/": 1.0
+  }}
+}}
+"""
+        print(f"Model: {TEXT_TO_PHONETICS_MODEL}, Temperature: {TEXT_TO_PHONETICS_TEMPERATURE}")
+        response = await litellm.acompletion(
+            model=TEXT_TO_PHONETICS_MODEL,
+            messages=[{
+                "role": "system",
+                "content": system_prompt
+            }, {
+                "role": "user",
+                "content": user_prompt
+            }],
+            temperature=TEXT_TO_PHONETICS_TEMPERATURE,
+            response_format={"type": "json_object"}
+        )
+        print("LiteLLM raw response:", response)
+        
+        response_content = response.choices[0].message.content
+        print("LiteLLM message content:", response_content)
+
+        # The response from the LLM should be a JSON string.
+        # Let's parse it to get the dictionary.
+        data = json.loads(response_content)
+        return data.get("pronunciations", {})
+
+    except Exception as e:
+        print(f"An error occurred in text_to_phonetics: {e}")
+        return {}
+
+async def phonetics_to_text(ipa: str, language_code: str) -> list:
+    """
+    Converts an International Phonetic Alphabet (IPA) expression to a list of possible dictations.
+    """
+    if not ipa:
+        return []
+
+    try:
+        print(f"phonetics_to_text called with ipa: '{ipa}', language_code: '{language_code}'")
+        system_prompt = """
+You are an expert linguist and phonetician. Your task is to provide a list of possible words or phrases (dictations) that match a given International Phonetic Alphabet (IPA) expression in a specified language.
+Consider all possible homophones and variations in spelling.
+"""
+        user_prompt = f"""
+Please provide the possible dictations for the IPA expression: '{ipa}'
+Language: {language_code}
+
+Return the result as a JSON object with a 'dictations' key, which is a list of strings.
+For example for the IPA "/həˈloʊ/":
+{{
+  "dictations": [
+    "hello",
+    "hallo"
+  ]
+}}
+"""
+        print(f"Model: {PHONETICS_TO_TEXT_MODEL}, Temperature: {PHONETICS_TO_TEXT_MODEL_TEMPERATURE}")
+        response = await litellm.acompletion(
+            model=PHONETICS_TO_TEXT_MODEL,
+            messages=[{
+                "role": "system",
+                "content": system_prompt
+            }, {
+                "role": "user",
+                "content": user_prompt
+            }],
+            temperature=PHONETICS_TO_TEXT_MODEL_TEMPERATURE,
+            response_format={"type": "json_object"}
+        )
+        print("LiteLLM raw response:", response)
+
+        response_content = response.choices[0].message.content
+        print("LiteLLM message content:", response_content)
+
+        data = json.loads(response_content)
+        return data.get("dictations", [])
+    except Exception as e:
+        print(f"An error occurred in phonetics_to_text: {e}")
+        return []