Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arg-tech/xaif/llms.txt

Use this file to discover all available pages before exploring further.

The xAIF library provides two export mechanisms: get_csv for exporting argument or locution pairs as a pandas DataFrame ready for downstream analysis or machine-learning pipelines, and XAIF.format for serialising a freshly assembled set of components into a standards-compliant xAIF JSON string.

​
get_csv(relation_type)

aif.get_csv(relation_type: str) -> pd.DataFrame
Exports the argument graph as a flat pandas DataFrame. Each row represents a directed pair of propositions and the relation (if any) between them. The method always includes all possible proposition pairs so that the resulting DataFrame can be used directly as a labelled dataset for binary or multi-class classification.
​
relation_type
str
required
Controls which pair type to export:
  • "argument-relation" — pairs I-nodes through RA, CA, or MA relation nodes. Unrelated I-node pairs are included with relation="None".
  • "locution" — pairs L-nodes with their downstream I-nodes through YA nodes. Useful for illocution classification tasks.
Returns: A pd.DataFrame with five columns:
ColumnTypeDescription
proposition1_idintnodeID of the source node
proposition1_textstrText content of the source node
proposition2_idintnodeID of the target node
proposition2_textstrText content of the target node
relationstrRelation node text ("Default Inference", "Default Conflict", "Default Rephrase", or "None")

​
Example

from xaif import AIF

aif = AIF("First Sentence. ")
aif.add_component(component_type="locution", text="Second Sentence.", speaker="Default Speaker")
aif.add_component(component_type="proposition", Lnode_ID=0, proposition="First sentence.")
aif.add_component(component_type="proposition", Lnode_ID=1, proposition="Second sentence.")
aif.add_component(component_type="argument_relation", relation_type="RA", iNode_ID1=4, iNode_ID2=2)

# Argument-relation export
df = aif.get_csv("argument-relation")
print(df.columns.tolist())
# ['proposition1_id', 'proposition1_text', 'proposition2_id', 'proposition2_text', 'relation']

# Filter to only related pairs
related = df[df["relation"] != "None"]
print(related)

# Locution export — pairs L-nodes with their I-nodes
df_loc = aif.get_csv("locution")
print(df_loc)
get_csv always includes all proposition pairs — both related and unrelated — in the returned DataFrame. Unrelated pairs are labelled relation="None". This design means the DataFrame can be used directly as a binary classification training set without any additional negative-sampling step.

​
XAIF.format(...) (static)

from xaif.xaif_templates import XAIF

XAIF.format(
    nodes,
    edges,
    locutions,
    schemefulfillments,
    descriptorfulfillments,
    participants,
    OVA,
    text_with_span,
    dialog=False,
    aif={},
    x_aif={}
) -> str
Assembles the provided components into a complete xAIF document and returns it as a JSON string. The method mutates the aif and x_aif dicts in place before serialising, so pass fresh empty dicts (the defaults) unless you intentionally want to merge into an existing structure. This is called internally by initilise_empty when an AIF object is constructed from plain text, but it can be invoked directly whenever you need to serialise a custom-assembled set of components.
​
nodes
list
required
List of node dicts. Each dict must have nodeID, text, and type keys.
​
edges
list
required
List of edge dicts. Each dict must have edgeID, fromID, and toID keys.
​
locutions
list
required
List of locution dicts. Each dict must have nodeID and personID keys.
​
schemefulfillments
list | None
required
Scheme fulfilment entries, or an empty list if none apply.
​
descriptorfulfillments
list | None
required
Descriptor fulfilment entries, or an empty list if none apply.
​
participants
list
required
List of participant dicts. Each dict must have participantID, firstname, and surname keys.
​
OVA
dict
required
OVA metadata dict. Pass an empty dict {} if OVA metadata is not required.
​
text_with_span
str
required
The HTML-annotated source text string stored under xaif["text"]["txt"]. Span tags carry the nodeID of each corresponding L-node.
​
dialog
bool
Set to True to mark the document as a dialogue. Stored under xaif["dialog"]. Defaults to False.
​
aif
dict
An existing dict to populate as the AIF section. Defaults to a new empty dict.
​
x_aif
dict
An existing dict to populate as the top-level xAIF document. Defaults to a new empty dict.

​
Example

from xaif.xaif_templates import XAIF
import json

json_str = XAIF.format(
    nodes=[{"nodeID": 0, "text": "Example.", "type": "L"}],
    edges=[],
    locutions=[{"nodeID": 0, "personID": 1}],
    schemefulfillments=[],
    descriptorfulfillments=[],
    participants=[{"participantID": 1, "firstname": "John", "surname": "Doe"}],
    OVA={},
    text_with_span='<span class="highlighted" id="0">Example.</span>',
    dialog=False
)

xaif_dict = json.loads(json_str)
print(xaif_dict["AIF"]["nodes"])
# [{'nodeID': 0, 'text': 'Example.', 'type': 'L'}]
If you already have a constructed AIF instance, aif.xaif is the live in-memory dict and can be serialised directly without calling XAIF.format again:
import json
json_str = json.dumps(aif.xaif)
Use XAIF.format only when you are assembling components from scratch outside of an AIF instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us