add README

README.md

@@ -1,12 +1,115 @@
----
-title: Rag Qa System
-emoji: 🌖
-colorFrom: pink
-colorTo: green
-sdk: gradio
-sdk_version: 6.9.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# RAG Question Answering System
+
+Sistema de preguntas y respuestas basado en Retrieval-Augmented
+Generation (RAG) que utiliza una pequeña base de conocimiento en inglés
+almacenada en `documents.json`.
+
+La aplicación permite realizar preguntas en inglés y obtiene la
+respuesta utilizando: - Recuperación de documentos relevantes mediante
+embeddings. - Generación de respuesta usando un modelo de lenguaje. -
+Una interfaz web interactiva desarrollada con **Gradio**.
+
+------------------------------------------------------------------------
+
+## Estructura del proyecto
+
+    app.py
+    rag_engine.py
+    documents.json
+    requirements.txt
+    README.md
+    /tests
+        test_api.py
+
+-   **app.py**: interfaz web con Gradio.
+-   **rag_engine.py**: lógica del sistema RAG (recuperación de
+    documentos y generación de respuestas).
+-   **documents.json**: base de conocimiento utilizada por el sistema.
+-   **requirements.txt**: dependencias necesarias para ejecutar el
+    proyecto.
+-   **tests/test_api.py**: script para probar la API del sistema
+    desplegado.
+
+------------------------------------------------------------------------
+
+## Instalación
+
+Clonar el repositorio o descargar los archivos y crear un entorno
+virtual:
+
+``` bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Instalar las dependencias:
+
+``` bash
+pip install -r requirements.txt
+```
+
+------------------------------------------------------------------------
+
+## Ejecución local
+
+Para ejecutar la aplicación localmente:
+
+``` bash
+python app.py
+```
+
+Luego abrir el navegador en:
+
+    http://127.0.0.1:7860
+
+Desde la interfaz se pueden realizar preguntas en inglés sobre la base
+de conocimiento.
+
+------------------------------------------------------------------------
+
+## Despliegue
+
+La aplicación está desplegada en **Hugging Face Spaces** utilizando el
+SDK de Gradio.
+
+URL del Space:
+
+https://adrianpalmadev-rag-qa-system.hf.space
+
+------------------------------------------------------------------------
+
+## Uso de la API
+
+El sistema también puede utilizarse mediante la API generada
+automáticamente por Gradio.
+
+Ejemplo de cliente en Python:
+
+``` python
+from gradio_client import Client
+
+client = Client("https://adrianpalmadev-rag-qa-system.hf.space")
+
+result = client.predict(
+    query="Where is the hospital?",
+    top_k=2,
+    umbral=0.5,
+    api_name="/ask"
+)
+
+print(result)
+```
+
+Este script devuelve: - La respuesta generada por el modelo. - Los
+documentos recuperados utilizados como contexto.
+
+------------------------------------------------------------------------
+
+## Tecnologías utilizadas
+
+-   Python
+-   Transformers
+-   Sentence Transformers
+-   Scikit-learn
+-   Gradio
+-   Hugging Face Spaces