Add Colab setup guide and tested environment configuration

README.md

@@ -129,6 +129,32 @@ Python interface --> [![Open In Colab](https://colab.research.google.com/assets/
 
 The python interface is useful in case you want to reuse the model for multiple transliterations and do not want to reinitialize the model each time.
 
+### Installation Issues and Setup Guide
+
+Some users may face installation issues due to Python and dependency compatibility, especially when running the library in Google Colab.
+
+A tested setup guide is available here:
+
+➡ **[Setup Guide](docs/setup_guide.md)**
+
+The guide includes:
+
+* Compatible environment versions
+* Google Colab installation workaround
+* Local machine setup instructions
+* A working transliteration example
+
+#### Tested Configuration
+
+| Component | Version |
+| --------- | ------- |
+| Python    | 3.9     |
+| pip       | 21.1.1  |
+| torch     | 2.1.2   |
+| numpy     | < 2.0   |
+
+If you encounter installation errors, follow the instructions in the setup guide.
+
 
 ## Details of models and hyperparameters
 <!-- network and training details and link to the paper -->

docs/setup_guide.md

@@ -0,0 +1,201 @@
+# IndicXlit Setup Guide
+
+This guide provides a **tested configuration and workaround** to successfully install and run IndicXlit, especially in **Google Colab**, where users often face dependency and Python version compatibility issues.
+
+The steps below describe:
+
+* the **tested environment**
+* a **working setup for Google Colab**
+* how to **run transliteration correctly**
+* how to **set up the library on a local machine**
+
+---
+
+# Tested Environment
+
+The following configuration has been verified to work:
+
+| Component | Version |
+| --------- | ------- |
+| Python    | 3.9     |
+| pip       | 21.1.1  |
+| torch     | 2.1.2   |
+| numpy     | < 2.0   |
+
+Using newer versions may lead to dependency conflicts or installation failures.
+
+---
+
+# Running IndicXlit in Google Colab
+
+Google Colab currently runs newer Python versions by default, which may cause the installation of IndicXlit to fail.
+
+The following steps install **Python 3.9 and compatible dependencies**.
+
+Run the following cells sequentially.
+
+---
+
+# Step 1 — Install Python 3.9
+
+```bash
+!python --version
+
+!sudo apt-get update
+!sudo apt-get install python3.9 python3.9-distutils python3.9-dev -y
+
+!sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.9 1
+!sudo update-alternatives --config python3
+```
+
+Verify Python version:
+
+```bash
+!python3 --version
+```
+
+---
+
+# Step 2 — Install pip
+
+```bash
+!wget https://bootstrap.pypa.io/get-pip.py
+!python3.9 get-pip.py
+
+!python3 --version
+!pip --version
+```
+
+Install a compatible pip version:
+
+```bash
+!python3.9 -m pip install pip==21.1.1
+```
+
+---
+
+# Step 3 — Install IndicXlit
+
+```bash
+!python3.9 -m pip install ai4bharat-transliteration --ignore-installed
+```
+
+---
+# Step 6 — Remove conflicting torch build
+
+```bash
+!pip uninstall torch -y
+```
+---
+# Step 4 — Install compatible torch
+
+```bash
+!pip install torch==2.1.2
+```
+
+Reinstall the transliteration package:
+
+```bash
+!python3.9 -m pip install ai4bharat-transliteration --ignore-installed
+```
+
+---
+
+# Step 5 — Install compatible numpy
+
+```bash
+%%capture
+!pip install "numpy<2.0"
+```
+
+---
+
+# Running Transliteration in Colab
+
+Even after installing Python 3.9, running the transliteration code **directly inside a notebook cell may still fail**.
+
+This happens because Colab notebook cells continue using the **default runtime Python**, which may be a newer version.
+
+To ensure the program runs with **Python 3.9**, create a Python script and execute it using `python3.9`.
+
+---
+
+# Create a Python script
+
+```bash
+%%writefile temp.py
+from ai4bharat.transliteration import XlitEngine
+
+engine = XlitEngine("hi")
+
+word = "namaste"
+print(engine.translit_word(word))
+```
+
+---
+
+# Run the script
+
+```bash
+!python3.9 temp.py
+```
+
+Expected output:
+
+```
+नमस्ते
+```
+
+---
+
+# Local Machine Setup
+
+If you are installing the library on your personal machine, ensure the following versions are used:
+
+* Python 3.9
+* pip 21.1.1
+* torch 2.1.2
+* numpy < 2.0
+
+Example setup:
+
+```bash
+python3.9 -m venv indicxlit_env
+source indicxlit_env/bin/activate
+
+python -m pip install pip==21.1.1
+pip install "numpy<2.0"
+pip install torch==2.1.2
+pip install ai4bharat-transliteration --ignore-installed
+```
+
+---
+
+# Verification Example
+
+```python
+from ai4bharat.transliteration import XlitEngine
+
+engine = XlitEngine("hi")
+
+words = ["namaste", "bharat", "duniya"]
+
+for w in words:
+    print(w, "->", engine.translit_word(w))
+```
+
+Example output:
+
+```
+namaste -> नमस्ते
+bharat -> भारत
+duniya -> दुनिया
+```
+
+---
+
+# Notes
+
+This setup was created after resolving installation issues encountered while running IndicXlit in Google Colab.
+
+Future updates to dependencies or the library may remove the need for these workarounds.