ARES Usage
============

.. image:: _static/ares-programming-model.png
            :width: 100%
            :align: center

|


.. note::
    ARES requires **Python 3.10+**.


Setup
-----

.. code-block:: bash

   git clone https://github.com/IBM/ares.git
   cd ares
   python -m venv .venv
   source .venv/bin/activate
   pip install .

.. note::
  Optional extras: use ``.[dev]`` for development (tests, linting) or ``ares-redteamer[dev]`` for a pinned version.

Create a config file `my-example.yaml`:

.. code-block:: yaml

   target:
     huggingface:

   red-teaming:
     prompts: assets/pii-seeds.csv

Run ARES:

.. code-block:: bash

   ares evaluate example_configs/my-example.yaml --limit

To learn how to configure ARES for different use cases, see the :doc:`ARES Configuration <configuration>`.

Limiting Attack Goals
---------------------

To limit the number of attack goals tested, use the ``--limit`` and ``--first`` options:

.. code-block:: bash

   ares evaluate example_configs/minimal.yaml --limit         # Limits to first 5 goals
   ares evaluate example_configs/minimal.yaml --limit --first 3  # Limits to first 3 goals

Dashboard Visualization
-----------------------

ARES includes a built-in dashboard to visualize configurations and evaluation results.

To enable the dashboard during evaluation:

.. code-block:: bash

   ares evaluate example_configs/minimal.yaml --dashboard

To visualize a report independently after evaluation:

.. code-block:: bash

   ares show-report example_configs/minimal.yaml --dashboard


Notebook
--------

ARES can also be run interactively via Jupyter notebooks. See:

- `notebooks/Red Teaming with ARES.ipynb`

This notebook walks through the Goal, Strategy, and Evaluation components in detail.


Assets
------

ARES uses datasets stored in the `assets/` folder. To run example configs, download the following file from HarmBench:

- `harmbench_behaviors_text_all.csv` from:
  https://github.com/centerforaisafety/HarmBench/blob/main/data/behavior_datasets/harmbench_behaviors_text_all.csv

Place it in the `assets/` directory.

Customizing the Target Model
----------------------------

You can change the target model by editing the config file. For example:

.. code-block:: yaml

   target:
     huggingface:
       model_config:
         pretrained_model_name_or_path: ibm-granite/granite-3.3-8b-instruct
       tokenizer_config:
         pretrained_model_name_or_path: ibm-granite/granite-3.3-8b-instruct

Refer to `example_configs/connectors.yaml` for more options.


Plugins
-------

ARES supports a modular plugin architecture that allows you to extend its functionality without modifying the core codebase.

Plugins can be used to:

- Connect to external targets (e.g., APIs, LLMs, agentic apps)
- Define custom attack goals
- Implement new attack strategies
- Evaluate model responses with specialized metrics

To learn how to install, configure, and create plugins, see :ref:`plugin-overview`.


Next Steps
----------

- Explore example configs in `example_configs/`
- Try different goals, strategies, and evaluators
- Visualize results using the built-in dashboard

.. admonition:: Common Issues

   - **Missing `.env` file**  

     Create one with required keys (e.g., API tokens).


   - **`ModuleNotFoundError`**  

     Run:

     .. code-block:: bash

        pip install .
        pip install .[dev]

   - **Dashboard not launching**  
      
      Check for:
       - Port conflicts
       - Missing dependencies

   - **Plugins not available**

      Ensure plugins are installed, for example:

      .. code-block:: bash

         pip install plugins/ares-garak

      Or use ARES built-in installer:

      .. code-block:: bash

         ares install-plugin ares-garak
         ares install-plugin ares-human-jailbreak