discqua 0.0.1
Discussion Quality Aspects
License: Apache-2.0
Requires Python: <=3.12,>=3.10

# DiscQuA: Discussion Quality Aspects
![Alt Text](https://github.com/nikos-Gk/dialogue-quality-measures/raw/408bb90c79d6b8a428e9d34ed2434ec5edde56c8/images/discqua.png)

# Saving
-By default, output files are saved to the current working directory (cwd).

-Users can choose to disable automatic saving of output files.
```python
from discqua import utils
utils.set_saving_enabled(False)
```
-To specify a custom save path:
```python
from discqua import utils
saving_path = ""
utils.set_output_path(saving_path)
```
# Logging
-A logger is used to display informational and error messages. Logging level can be customized by the user.

```python
import logging
logging.basicConfig(level=logging.ERROR)
logging.basicConfig(level=logging.INFO)
```

# Description of input parameters

-message_list: The list of utterances in the discussion. 

-speakers_list: The corresponding list of speakers for each utterance.

-msgsid_list: List of messages ids corresponding to each utterance.

-replyto_list: List indicating the message ID each utterance is replying to.

-disc_id: A unique identifier for the discussion.

-conver_topic: The topic of the discussion.

-discussion_level: A boolean flag; if True, the annotations are applied at the discussion level; otherwise at the utterance level.

-ctx: Number of previous utterances to include as context for each input.

-openAIKEY: OpenAI API key, required if using OpenAI-based models.

-model_type: Specifies the model to use; options are "openai" or "transformers" .

-model_path:  Path to the local LlaMA model directory, used only if model_type is "transformers".

-gpu: A boolean flag; if True, utilizes GPU (when available); otherwise defaults to CPU.

-device: The device to load the model on. If None, the device will be inferred. Defaults to cpu.

# Argument Quality
## arg_dimensions: Argument Quality Aspects (Turn-Level)
This module evaluates the quality of argumentation in individual discussion turns using the taxonomy proposed by Wachsmuth et al. (2017). Leveraging either OpenAI's language models or a locally hosted Llama model, it assigns scores across multiple dimensions of argument quality, with each dimension rated on a scale from 1 (low) to 3 (high).

#### Logic Dimensions:
-Label 1a-Local Acceptability: Premises of the argument worthy of being believed.

-Label 1b-Local Relevance: Premises support/attack the conclusion of the argument. 

-Label 1c-Local Sufficiency: Premises enough to draw the conclusion of the argument. 

-Label 1_overall-Cogency: Argument has locally acceptable, relevant, and sufficient premises. 

#### Rhetoric Dimensions:
-Label 2a-Credibility: Argument makes the author worthy of credence. 

-Label 2b-Emotional Appeal: Argument creates emotions that make the audience open to it. 

-Label 2c-Clarity: Argument avoids deviation from the issue, and uses correct and unambiguous language. 

-Label 2d-Appropriateness: Language proportional to the issue, supports credibility and emotions. 

-Label 2e-Arrangement: Discussion topic, arguments and conlusions are presented in the right order. 

-Label 2_overall-Effectiveness: Argument persuades the audience. 

#### Dialectic Dimensions:
-Label 3a-Global Acceptability: Audience accepts the use of the argument. 

-Label 3b-Global Relevance: Argument helps arrive at an agreement. 

-Label 3c-Global Sufficiency: Argument adequately rebuts the anticipated counter-arguments to its conclusion. 

-Label 3_overall-Reasonableness: Argument is (globally) acceptable, relevant, and sufficient.

#### Overall Quality:

-Label 4-overall quality: The holistic quality of the argument across all dimensions.

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
 from discqua import arg_dimensions
    arg_dim_scores = arg_dimensions(
                                    message_list=message_list,
                                    speakers_list=speakers_list,
                                    msgsid_list=msgsid_list,
                                    disc_id=disc_id,
                                    conver_topic=conver_topic,
                                    openAIKEY="your key",
                                    model_type="openai",
                                    model_path="",
                                    gpu=False,
                                    ctx=1,
                                    dimension="logic",
                                    )
    arg_dim_scores = arg_dimensions(
                                    message_list=message_list,
                                    speakers_list=speakers_list,
                                    msgsid_list=msgsid_list,
                                    disc_id=disc_id,
                                    conver_topic=conver_topic,
                                    openAIKEY="",
                                    model_type="transformers",
                                    model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                    gpu=True,
                                    ctx=1,
                                    dimension="logic",
                                    )

where dimension (str): The argument quality dimension to evaluate. Choose from:
            - "logic": Evaluates the internal structure and reasoning of the argument.
            - "rhetoric": Assesses the persuasive and stylistic elements.
            - "dialectic": Measures how well the argument contributes to discussion and resolution.
            - "overall": Provides a holistic score across all dimensions.

```
## overall_arg_quality: Overall Argument Quality (Discussion-Level)
This module evaluates the average overall quality of argumentation across the entire discussion. Leveraging either OpenAI’s language models or a locally hosted Llama model, it returns a discussion-level score that reflects the holistic strength of arguments exchanged throughout the discussion.

#### Scoring Modes:

-mode="real": Returns a real-valued score (e.g., 2.7) on a scale from 1 to 5.

-mode="rating": Returns a discrete integer score on a scale from 1 (low) to 3 (high).

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import overall_arg_quality

    overall_argument_quality_score = overall_arg_quality(
                                                        message_list=message_list,
                                                        speakers_list=speakers_list,
                                                        disc_id=disc_id,
                                                        conver_topic=conver_topic,
                                                        openAIKEY="your key",
                                                        model_type="openai",
                                                        model_path="",
                                                        mode="real",
                                                        gpu=False,
                                                        )

    overall_argument_quality_score = overall_arg_quality(
                                                        message_list=message_list,
                                                        speakers_list=speakers_list,
                                                        disc_id=disc_id,
                                                        conver_topic=conver_topic,
                                                        openAIKEY="",
                                                        model_type="transformers",
                                                        model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                                        mode="real",
                                                        gpu=True,
                                                        )
            
```
# Coherence
## coherence_disc: Coherence Analysis (Discussion-Level)
This module assesses the overall coherence of a discussion using OpenAI's language models or a locally hosted Llama model (Zhang et al., 2024). It assesses how logically and contextually connected the messages are across the discussion. The model assigns a coherence score (integer) to the entire discussion on a 1-to-5 scale, where:

- **1** – Poor coherence (incoherent or disjointed)
- **5** – Strong coherence (well-structured and contextually consistent)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import coherence_disc

    coherence_disc_score=coherence_disc(
                                        message_list=message_list,
                                        speakers_list=speakers_list,
                                        disc_id=disc_id,
                                        conver_topic=conver_topic,
                                        openAIKEY="you key",
                                        model_type="openai",
                                        model_path="",
                                        gpu=False,
                                        )

    coherence_disc_score=coherence_disc(
                                        message_list=message_list,
                                        speakers_list=speakers_list,
                                        disc_id=disc_id,
                                        conver_topic=conver_topic,
                                        openAIKEY="",
                                        model_type="transformers",
                                        model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                        gpu=True,
                                        )
```
## coherence_response: Coherence Analysis (Turn-Level) 
This module evaluates the coherence of individual responses within a discussion. Using OpenAI's language models or a locally hosted Llama model, it examines how well a message aligns with its conversational context. The model assigns a coherence score (integer number) to each response on a 1-to-5 scale:

- **1** – Incoherent response (off-topic, confusing, or disjointed)
- **5** – Coherent (well-aligned with context, clear, and logically structured)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import coherence_response

    score = coherence_response(
                                message_list=message_list,
                                speakers_list=speakers_list,
                                msgsid_list=msgsid_list,
                                disc_id=disc_id,
                                conver_topic=conver_topic,
                                openAIKEY="you key",
                                model_type="openai",
                                model_path="",
                                gpu=False,
                                ctx=1,
                              )
    score = coherence_response(
                                message_list=message_list,
                                speakers_list=speakers_list,
                                msgsid_list=msgsid_list,
                                disc_id=disc_id,
                                conver_topic=conver_topic,
                                openAIKEY="",
                                model_type="transformers",
                                model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                gpu=True,
                                ctx=1,
                              )
```
## coherence_ecoh: Coherence Analysis (Turn-Level) 

This module evaluates the coherence of individual responses within a discussion. Using a locally hosted model presented at Mendonça, Trancoso and Lavie (2024), it examines how well a comment aligns with its conversational context. The model assigns a binary coherence label to each response, where:

- **0** – Incoherent response (off-topic, confusing, or disjointed)
- **1** – Coherent (well-aligned with context, clear, and logically structured)


```python
from discqua import coherence_ecoh

    coherence_booleans = coherence_ecoh(
                                        message_list=message_list,
                                        speaker_list=speakers_list,
                                        disc_id=disc_id,
                                        device="cuda",
                                        )
```
# Controversy
## controversy: Controversy Analysis (Discussion and Turn Level)
This module quantifies the level of controversy in a discussion by analyzing the standard deviation of sentiment scores assigned to individual comments (Avalle et al., 2024). Sentiment scores are derived using a pretrained BERT model.

#### Outputs:

-controversy_per_disc_unorm (discussion_level=True): Sample standard deviation of the unnormalized sentiment scores across all comments in the discussion.

-controversy_per_disc_norm (discussion_level=True): Sample standard deviation of the normalized sentiment scores across the discussion.

-controversy_per_utt_unorm (discussion_level=False): Rolling standard deviation of the unnormalized sentiment scores.

-controversy_per_utt_norm (discussion_level=False): Rolling standard deviation of the normalized sentiment scores.


```python
from discqua import controversy

    unorm_scores, norm_scores = controversy(
                                            message_list=message_list, 
                                            disc_id=disc_id, 
                                            msgsid_list=msgsid_list,
                                            discussion_level=True
                                            )
```

# Dialogue Acts
## dialogue_acts: Dialogue Acts Analysis (Turn-Level).
This module analyzes utterances in a discussion to identify dialogue acts that indicate the deliberative quality of communicative exchanges, following the frameworks presented by Fournier-Tombs and MacKenzie (2021) and Zhang, Culbertson & Paritosh (2017). Leveraging either OpenAI’s language models or a locally hosted Llama model, each utterance is assigned a binary label (1 or 0) to indicate the presence or absence of a specific dialogue act.

#### Dialogue Act Labels:

-Label 0: Interruption - Comment that interrupts a previous utterance.

-Label 1: Explanation - Comment that provides a minimum level of context for the claims or opinions that are expressed.

-Label 2: Causal reasoning - Comment that makes explicit causal connections between any observations, values, or objectives and the claims, conclusions, or recommendations that are made.

-Label 3: Narrative - Comment that employs personall story telling to justify claims or values.

-Label 4: Question - Comment that asks for clarifications or input.

-Label 5: Response - Comment that replies to a question directed toward it.

-Label 6: Advocacy - Comment that explicitly defends or advances the interests or claims of identifiable groups or communities.

-Label 7: Public interest - Comment that attempts to connect claims, policies, or recommendations to the interests of the community as a whole.

-Label 8: Disrespect - Comment that contains insults, dispersions, misrepresentations, name calling, and dismissive or disrespectful statements.

-Label 9: Respect - Comment that contains explicit shows of respect, such as salutations, complements, or apologies.

-Label 10: Counterarguments - Comment that engages with critiques made by other comments or attempts to address or respond to counter claims, concerns, or countervailing evidence.

-Label 11: Constructive proposal - Comment that proposes solutions to shared problems, alternative options, or compromises.

-Label 12: Sarcasm (mocking)- Comment that is primarily a joke, a piece of sarcasm, or a pun intended to get a laugh or be silly but not trying to add information. 

-Label 13: Sarcasm (nomocking)- Comment that uses sarcasm in a non-mocking way (e.g., aimed at devaluing the reference object) but just as a communication function that aligns with the nature of the point that is being made, or necessary to communicate to a particular audience.

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*


```python
from discqua import dialogue_acts

    dialogue_acts_scores = dialogue_acts(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            msgsid_list=msgsid_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="your key",
                                            model_type="openai",
                                            model_path="",
                                            gpu=False,
                                            ctx=1,
                                        )

    dialogue_acts_scores = dialogue_acts(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            msgsid_list=msgsid_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="",
                                            model_type="transformers",
                                            model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                            gpu=True,
                                            ctx=1,
                                        )
```

# Dispute Tactics
## dispute_tactics: Disagreement Levels and Coordination Labels Analysis (Turn-Level).
This module analyzes utterances in a discussion to identify levels of disagreement and markers of coordination, based on the annotation framework introduced by De Kock and Vlachos (2022). Leveraging either OpenAI’s language models or a locally hosted Llama model, each utterance is assigned a binary label (1 or 0) to indicate the presence or absence of a specific disagreement level or coordination label.
#### Disagreement levels:

-Level 0-Name calling/hostility: Comment with direct insults, or use of an equally hostile tone or language. 

-Level 1-Ad hominem/ad argument: Comment that attacks other users to discredit them or their arguments without addressing the content. 

-Level 2-Attempted derailing/off-topic: Comment that is unrelated to the current line of discussion.

-Level 3-Policing the discussion: Comment that does not address (opposing) arguments’ content but mainly try to "policy" the discussion (e.g., telling people to "calm down").

-Level 4a-Stating your stance: Comment that states an opposing view (stance), with little or no supporting evidence.

-Level 4b-Repeated argument: Comment that re-states a previously expressed argument, potentially using different words, but without furthering the discussion.

-Level 5-Counterargument: Comment that states an opposing view (stance), while providing supporting reasoning and/or evidence.

-Level 6-Refutation: Comment that responds to an argument and explains why it is mistaken, using new evidence or reasoning.

-Level 7-Refuting the central point: Comment that directly refutes the central point of an argument, explaining why it is mistaken, using new evidence or reasoning.

### Coordination labels (attempts to promote understanding and consensus):

-Label A-Bailing out: An indication that a person is giving up on a discussion and will no longer engage.

-Label B-Contextualisation: Usually in the first utterance, an individual “sets the stage" by describing what aspect they are 
challenging.

-Label C-Asking questions: Seeking to understand another person’s opinion better. This does not include rhetorical questions, which are generally disagreement moves.

-Label D-Providing clarification: Answering questions or providing information which seeks to create understanding, rather than only furthering a point.

-Label E-Suggesting a compromise: An attempt to find a midway between one’s own point and the opposer’s.

-Label F-Coordinating: In disagreement threads, discussions about edits that may indicate a compromise.

-Label G-Conceding/recanting: An explicit admission that an interlocutor is willing to relinquish their point.

-Label H-I don't know: Admitting that one is uncertain-a signal that the speaker is receptive to the idea that there are unknowns which may impact their argument.

-Label I-Other: For utterances not covered by any other class, for instance, social niceties. 

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*


```python
from discqua import dispute_tactics

    disp_tact = dispute_tactics(
                                message_list=message_list,
                                speakers_list=speakers_list,
                                msgsid_list=msgsid_list,
                                disc_id=disc_id,
                                conver_topic=conver_topic,
                                openAIKEY="your key",
                                model_type="openai",
                                model_path="",
                                gpu=False,
                                ctx=1,
                                )

    disp_tact = dispute_tactics(
                                message_list=message_list,
                                speakers_list=speakers_list,
                                msgsid_list=msgsid_list,
                                disc_id=disc_id,
                                conver_topic=conver_topic,
                                openAIKEY="",
                                model_type="transformers",
                                model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                gpu=True,
                                ctx=1,
                                )
```
# Diversity
## diversity_disc: Diversity Analysis (Discussion-Level)
This module assesses the diversity of arguments within a discussion using OpenAI's language models or a locally hosted Llama model (Zhang et al., 2024). Diversity in arguments reflects the presence of multiple perspectives, contributing to a richer and more balanced exchange. The model assigns a diversity score (integer number) to the entire discussion on a 1-to-5 scale, where:

- **1** – Poor diversity (high similarity or repetition in arguments)
- **5** – High diversity (broad range of perspectives and reasoning styles)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import diversity_disc


    diversity_disc_score = diversity_disc(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="your key",
                                            model_type="openai",
                                            model_path="",
                                            gpu=False,
                                         )
    diversity_disc_score = diversity_disc(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="",
                                            model_type="transformers",
                                            model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                            gpu=True,
                                         )
```
## diversity_response: Diversity Analysis (Turn-Level)
This module computes diversity scores for each response within a discussion using OpenAI's language models or a locally hosted Llama model. The model assigns a diversity score (integer number) to each response on a 1-to-5 scale, where:

- **1** – Poor diversity (high similarity or repetition in arguments)
- **5** – High diversity (broad range of perspectives and reasoning styles)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import diversity_response

    diversity_resp_score = diversity_response(
                                                message_list=message_list,
                                                speakers_list=speakers_list,
                                                msgsid_list=msgsid_list,
                                                disc_id=disc_id,
                                                conver_topic=conver_topic,
                                                openAIKEY="your key",
                                                model_type="openai",
                                                model_path="",
                                                gpu=False,
                                                ctx=1,
                                             )
    diversity_resp_score = diversity_response(
                                                message_list=message_list,
                                                speakers_list=speakers_list,
                                                msgsid_list=msgsid_list,
                                                disc_id=disc_id,
                                                conver_topic=conver_topic,
                                                openAIKEY="",
                                                model_type="transformers",
                                                model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                                gpu=True,
                                                ctx=1,
                                             )
```
## ngramdiversity: Ngram diversity based on word overlap (Turn-level).
This module analyzes ngram diversity by measuring word overlap between consecutive messages within a discussion (Tan et al., 2016). It focuses on:

-common words (comwords),

-stopwords,

-content words (contwords).

### Labels: Let utt_i, and utt_i+1 two consecutive utterances in the discussion. 
-n_comwords, n_stopwords, n_contwords: Count of overlapping words between utt_i and utt_i+1 (i.e., |utt_i ∩ utt_i+1|).

-reply_fra_comwords, reply_fra_stopwords, reply_fra_contwords: Proportion of overlapping words relative to the reply (i.e., |utt_i ∩ utt_i+1|/|utt_i+1|).

-op_fra_comwords, op_fra_stopwords, op_fra_contwords: Proportion of overlapping words relative to the original message (i.e., |utt_i ∩ utt_i+1|/|utt_i|).

-jac_comwords, jac_stopwords, jac_contwords: Jaccard similarity between the two utterances (i.e., |utt_i ∩ utt_i+1|/|utt_i ∪ utt_i+1|). 


```python
from discqua import ngramdiversity

    lexical_diversity=ngramdiversity(
                                        message_list=message_list,
                                        msgsid_list=msgsid_list,
                                        disc_id=disc_id,
                                    )
```

# Empathy
## empathy: Empathy Analysis (Turn–Level)
This module analyzes utterances in a discussion to identify empathetic traits, based on the taxonomy introduced by Welivita and Pu (2020). Leveraging either OpenAI’s language models or a locally hosted Llama model, each utterance is assigned a binary label (1 or 0) indicating the presence or absence of a specific empathetic intent.
#### Labels:

-Label 0-Questioning: Seeks clarification or additional information.

-Label 1–Acknowledging: Recognizes or validates another’s feelings, experiences, or perspective without implying agreement.

-Label 2-Agreeing: Shows support or alignment with another’s viewpoint, statement, or emotion.

-Label 3–Consoling: Offers comfort or emotional support in response to distress or hardship.

-Label 4–Encouraging: Provides support or affirmation in response to hopeful or uplifting content.

-Label 5–Sympathizing: Expresses pity, sorrow, or shared concern in response to distressing content.

-Label 6-Wishing: Expresses hope, goodwill, or kind intentions toward another participant.

-Label 7-Suggesting: Offers advice, recommendations, or possible actions in response to a shared concern or situation.

-Label 8–Sharing Own Thoughts: Expresses personal views or reflections, often without directly replying to others.

-Label 9-Sharing Experience: Recounts a personal story or experience to connect with or illustrate a point.

-Label 10-Advising: Provides guidance, recommendations, or suggestions.

-Label 11-Expressing Care: Shows concern or compassion toward another participant.

-Label 12–Expressing Relief: Conveys relief in response to another’s stressful or emotionally intense situation.

-Label 13–Disapproving: Expresses disagreement, criticism, or concern toward another’s viewpoint or actions.

-Label 14–Appreciating: Expresses gratitude, admiration, or positive recognition toward another participant.

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import empathy

    expr_empathy_labels = empathy(
                                    message_list=message_list,
                                    speakers_list=speakers_list,
                                    msgsid_list=msgsid_list,
                                    disc_id=disc_id,
                                    conver_topic=conver_topic,
                                    openAIKEY="your key",
                                    model_type="openai",
                                    model_path="",
                                    gpu=False,
                                    ctx=1,
                                 )
    expr_empathy_labels = empathy(
                                    message_list=message_list,
                                    speakers_list=speakers_list,
                                    msgsid_list=msgsid_list,
                                    disc_id=disc_id,
                                    conver_topic=conver_topic,
                                    openAIKEY="",
                                    model_type="transformers",
                                    model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                    gpu=True,
                                    ctx=1,
                                 )
```
# Engagement
## engagement_disc: Engagement Analysis (Discussion–Level)
This module assesses the level of engagement within a discussion using OpenAI's language models or a locally hosted Llama model (Zhang et al., 2024). Engagement captures how actively participants contribute and how sustained the interaction is across the discussion. The model assigns an engagement score (integer number) to the entire discussion on a 1-to-5 scale, where:

- **1** – Law engagement (limited interaction, short or shallow exchanges)
- **5** – High engagement (frequent, sustained, and reciprocal participation)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import engagement_disc

    engagement_disc_score = engagement_disc(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="your key",
                                            model_type="openai",
                                            model_path="",
                                            gpu=False,
                                           )
    engagement_disc_score = engagement_disc(
                                            message_list=message_list,
                                            speakers_list=speakers_list,
                                            disc_id=disc_id,
                                            conver_topic=conver_topic,
                                            openAIKEY="",
                                            model_type="transformers",
                                            model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                            gpu=True,
                                           )
```
## engagement_response: Engagement Analysis (Turn–Level)
This module assigns engagement scores for each response in a discussion using OpenAI's language models or a locally hosted Llama model. Each response is evaluated in context for its engagement quality based on characteristics of variety of response according to the context, likelihood of encouraging the other participant to respond, likelihood of encouraging a quality response from the other participants, interestingness, specificity, and likelihood of creating a sense of belonging for the other participants (Ferron et al., 2023).  The model assigns an engagement score to each response on a continuous scale from 0 to 100, where:
- **0** – disengaging.
- **100** – very engaging.

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import engagement_response

     engagement_resp_score = engagement_response(
                                                    message_list=message_list,
                                                    speakers_list=speakers_list,
                                                    msgsid_list=msgsid_list,
                                                    disc_id=disc_id,
                                                    conver_topic=conver_topic,
                                                    openAIKEY="your key",
                                                    model_type="openai",
                                                    model_path="",
                                                    gpu=False,
                                                    ctx=1,
                                                )
                                                            
     engagement_resp_score = engagement_response(
                                                    message_list=message_list,
                                                    speakers_list=speakers_list,
                                                    msgsid_list=msgsid_list,
                                                    disc_id=disc_id,
                                                    conver_topic=conver_topic,
                                                    openAIKEY="",
                                                    model_type="transformers",
                                                    model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                                    gpu=True,
                                                    ctx=1,
                                                )
```
## reciprocity: Reciprocity Motifs: Serve as proxies for engagement (Discussion and Turn Level)
This module gives the reciprocity motifs proposed by Zhang et al. (2018). These features help uncover participation patterns and interactional dynamics.

-Reciprocity motif: Occurs when the target of a reply returns to respond to the replier.

-External reciprocity motif: Captures the tedency of a comment to draw responses from speakers beyond its explicit target.

-Dyadic interaction motif: Tracks dyadic (back-and-forth) interactions between pairs of participants across the entire discussion.

-Incoming triads: Cases where a speaker receives replies from two different participants.

-Outgoing triads: Instances where a speaker replies to two different participants.

```python
from discqua import reciprocity
 structure_features =reciprocity(
                                    message_list=message_list,
                                    speakers_list=speakers_list,
                                    msgsid_list=msgsid_list,
                                    replyto_list=replyto_list,
                                    disc_id=disc_id,
                                    discussion_level=True,
                                )
```
# Informativeness
## informativeness_disc: Informativeness Analysis (Discussion-Level)

This module evaluates the informativeness of a discussion using OpenAI's language models or a locally hosted Llama model (Zhang et al., 2024). It estimates how much relevant, useful, and novel information is conveyed by the participants throughout the discussion. The model assigns an informativeness score (integer) to the entire discussion on a 1-to-5 scale, where:

- **1** – Low informativeness (vague, repetitive, or off-topic discussion)
- **5** – High informativeness (substantive, relevant, and information-rich discussion)

*Note: Requires access to OpenAI’s language models via API, or a locally hosted Llama model.*

```python
from discqua import informativeness_disc

    informativeness_disc_score = informativeness_disc(
                                                        message_list=message_list,
                                                        speakers_list=speakers_list,
                                                        disc_id=disc_id,
                                                        conver_topic=conver_topic,
                                                        openAIKEY="your key",
                                                        model_type="openai",
                                                        model_path="",
                                                        gpu=False,
                                                     )
    informativeness_disc_score = informativeness_disc(
                                                        message_list=message_list,
                                                        speakers_list=speakers_list,
                                                        disc_id=disc_id,
                                                        conver_topic=conver_topic,
                                                        openAIKEY="",
                                                        model_type="transformers",
                                                        model_path="unsloth/Meta-Llama-3.1-8B-Instruct",
                                                        gpu=True,
                                                     )
```
## informat