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 AIF class is the central object in the xAIF library. It lets you build argument graphs programmatically by adding components step by step — starting from raw text or an existing xAIF JSON structure and progressively attaching locutions, propositions, and argument relations until the full graph is formed. Each addition automatically assigns the next available ID and wires the necessary edges, so you never need to manage node or edge counters manually.
Installing xAIF
The Four Component Types
Every element of an argument graph is added through a single entry point: aif.add_component(component_type, **kwargs). The four supported component_type values are described below.
locution
Adds a new L-node (locution node) representing a spoken or written statement attributed to a named participant.
| Keyword argument | Type | Description |
|---|
text | str | The raw text of the utterance |
speaker | str | Full name of the speaker (firstname + surname, space-separated) |
aif.add_component(component_type="locution", text="Second Sentence.", speaker="Default Speaker")
AIF["participants"] if they do not already exist, and a corresponding locution entry is appended to AIF["locutions"].
proposition
Links a logical proposition (I-node) to an existing L-node. xAIF follows Inference Anchoring Theory, where the raw locution text and its “neutralised” semantic content are kept in separate nodes. Calling this component type creates:
- An I-node containing the proposition text.
- A YA-node (
"Default Illocuting") that anchors the L-node to the I-node.
- Two directed edges:
L-node → YA-node → I-node.
| Keyword argument | Type | Description |
|---|
Lnode_ID | int | The node ID of the L-node to link from |
proposition | str | The proposition text for the new I-node |
aif.add_component(component_type="proposition", Lnode_ID=0, proposition="First sentence.")
argument_relation
Creates a relation node (RA, CA, or MA) between two I-nodes and wires both directed edges.
| Keyword argument | Type | Description |
|---|
relation_type | str | One of "RA", "CA", or "MA" |
iNode_ID1 | int | The node ID of the source I-node (the premise) |
iNode_ID2 | int | The node ID of the target I-node (the conclusion) |
aif.add_component(component_type="argument_relation", relation_type="RA", iNode_ID2=2, iNode_ID1=4)
iNode_ID1 → relation node → iNode_ID2.
segment
Splits an existing L-node into multiple new L-nodes (one per segment string), each inheriting the original speaker’s attribution. The original L-node, its linked I-node, YA-node, and all connected edges are removed via remove_entry after the new nodes are added.
| Keyword argument | Type | Description |
|---|
Lnode_ID | int | The node ID of the L-node to split |
segments | List[str] | The list of text strings to create as new L-nodes |
aif.add_component(
component_type="segment",
Lnode_ID=2,
segments=["the third text.", "fourth text"]
)
After segment is called, the original L-node no longer exists in the graph.
Any propositions or relations that were linked to it must be re-attached to the
newly created L-nodes.
Relation Types
When adding an argument_relation, the relation_type controls which AIF scheme node is inserted between the two I-nodes:
relation_type | Node text | Node type | Meaning |
|---|
RA | "Default Inference" | RA | One proposition supports or follows from another |
CA | "Default Conflict" | CA | One proposition attacks or contradicts another |
MA | "Default Rephrase" | MA | One proposition is a paraphrase of another |
Automatic ID Assignment
xAIF never requires you to pick node or edge IDs. The internal get_next_max_id(component_type, id_key_word) method scans the relevant list (nodes or edges), finds the current maximum ID, and returns max + 1. This works whether IDs are plain integers or strings in the "<int>_<suffix>" format used by OVA-exported graphs.
Full Worked Example
The example below builds a three-step argument from scratch: two locutions, two propositions, and one inference relation.
from xaif import AIF
import json
# Step 1: initialise from raw text — creates L-node 0 attributed to "Default Speaker"
aif = AIF("First Sentence. ")
# Step 2: add a second locution (L-node 1)
aif.add_component(component_type="locution", text="Second Sentence.", speaker="Default Speaker")
# Step 3: attach propositions to each locution
# - creates I-node 2, YA-node 3, edges 0→3→2
aif.add_component(component_type="proposition", Lnode_ID=0, proposition="First sentence.")
# - creates I-node 4, YA-node 5, edges 1→5→4
aif.add_component(component_type="proposition", Lnode_ID=1, proposition="Second sentence.")
# Step 4: link the propositions with a Default Inference relation
# iNode_ID1=4 (premise) → RA node 6 → iNode_ID2=2 (conclusion)
aif.add_component(component_type="argument_relation", relation_type="RA", iNode_ID2=2, iNode_ID1=4)
print(json.dumps(aif.xaif, indent=2))
aif.xaif["AIF"]["nodes"] will contain two L-nodes, two I-nodes, two YA-nodes, and one RA-node. The edges list will have six directed edges connecting them into a complete AIF graph.
Removing Entries
To delete a locution and all the graph elements anchored to it, call aif.remove_entry(Lnode_ID). It traverses the edge list to locate the YA-node and I-node connected to the given L-node, then removes:
- The L-node itself.
- The associated I-node.
- The associated YA-node.
- All edges that have the L-node or I-node as a
fromID or toID.
# Remove locution 0 and everything linked to it
aif.remove_entry(0)
For the full list of accepted keyword arguments and return values for
add_component and its underlying helpers, see the API reference. 