.. WiMarka documentation master file

WiMarka Documentation
=====================

**WiMarka** is a comprehensive Python library and CLI tool designed for evaluating machine translations with advanced syntactic and semantic analysis, providing detailed interpretability for Philippine Languages.

.. image:: https://img.shields.io/badge/python-%3E%3D3.12-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python Version

.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://github.com/wimarka-uic/WiMarka/blob/main/LICENSE
   :alt: License: MIT

Overview
--------

WiMarka addresses the critical need for accurate machine translation evaluation in Philippine languages. It goes beyond simple metrics by providing:

* **Error Detection**: Identifies specific translation errors between source and target texts
* **Multi-dimensional Scoring**: Evaluates translations across fluency, adequacy, and overall quality
* **Explainability**: Generates human-readable explanations for detected errors
* **Correction Suggestions**: Provides corrected translation alternatives
* **Philippine Language Focus**: Specialized support for Cebuano (CEB), Ilocano (ILO), and Tagalog (TGT)

Key Features
------------

✨ **Advanced Error Detection**
   Sophisticated algorithms identify translation inconsistencies and errors

📊 **Multi-dimensional Scoring**
   - Fluency Score: Measures how natural the translation reads
   - Adequacy Score: Evaluates semantic completeness and accuracy
   - Overall Quality Score: Comprehensive translation quality assessment

💡 **Explainable Results**
   Detailed explanations for each detected error

🔧 **Correction Suggestions**
   AI-powered suggestions for improving translations

🖥️ **Dual Interface**
   Both Python library and CLI for flexible integration

🌏 **Philippine Language Support**
   Specialized models for CEB, ILO, and TGT

Quick Start
-----------

Installation
~~~~~~~~~~~~

.. code-block:: bash

   pip install git+https://github.com/wimarka-uic/WiMarka.git

Basic Usage
~~~~~~~~~~~

**Python Library:**

.. code-block:: python

   from wimarka.main import wmk_eval

   wmk_eval(
       src_file_path='source_file.txt',
       src_lang='EN',
       tgt_file_path='target_file.txt',
       tgt_lang='CEB'
   )

**Command Line:**

.. code-block:: bash

   wimarka --src_file_path source_file.txt \\
           --src_lang EN \\
           --tgt_file_path target_file.txt \\
           --tgt_lang CEB

Documentation Structure
-----------------------

This documentation is organized into two main sections:

**User Manual**
   Complete guide for using WiMarka, including installation, usage examples, and best practices.

**Technical Manual**
   In-depth technical documentation covering architecture, API reference, and development guidelines.

.. toctree::
   :maxdepth: 2
   :caption: User Manual

   user/index
   user/installation
   user/quickstart
   user/usage_library
   user/usage_cli
   user/supported_languages
   user/output_format
   user/examples

.. toctree::
   :maxdepth: 2
   :caption: Technical Manual

   tech/index
   tech/architecture
   tech/api_reference
   tech/tasks
   tech/utils
   tech/models
   tech/development
   tech/extending

Support & Contributing
----------------------

For questions, issues, or suggestions:

* **Issues**: `GitHub Issues <https://github.com/wimarka-uic/WiMarka/issues>`_
* **Discussions**: `GitHub Discussions <https://github.com/wimarka-uic/WiMarka/discussions>`_

We welcome contributions! See the :doc:`tech/development` guide for details.

License
-------

This project is licensed under the **MIT License**. See the `LICENSE <https://github.com/wimarka-uic/WiMarka/blob/main/LICENSE>`_ file for details.

Citation
--------

If you use WiMarka in your research, please cite:

.. code-block:: bibtex

   @software{wimarka2025,
     title={WiMarka: A Reference-free Evaluation Metric for Machine 
   Translation of Philippine Languages},
     author={University of the Immaculate Conception},
     year={2025},
     url={https://github.com/wimarka-uic/WiMarka}
   }

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`