Bachelor Thesis — TH Köln — Grade 1.0
Experimental pipeline for combining semantic and graph-structural context in representations of argumentative discourse.
Python · Neo4j Graph Data Science · SentenceTransformers · GraphSAGE · FastRP · scikit-learn
The repository is a compact research artifact: it constructs a typed argument graph, persists it in Neo4j, learns three node-representation spaces, and compares their behavior through visualization and exploratory clustering. The experiment uses a small synthetic debate about Universal Basic Income (UBI).
Can semantic representations of argumentative units be enriched with graph context so that the resulting representation captures both semantic and structural information?
The code tests this by passing sentence-level node features through GraphSAGE neighborhood aggregation. It also learns a separate FastRP representation to inspect graph topology independently.
flowchart TD
D[Synthetic UBI debate<br/>section CSV files] --> C[Typed argument-graph construction]
C --> N[(Neo4j property graph)]
N -->|Content| S[SentenceTransformer<br/>all-mpnet-base-v2<br/>768-d, normalized]
S --> P[PCA<br/>retain 99% variance]
P --> G[GraphSAGE<br/>semantic neighborhood aggregation]
N -->|Topology| F[FastRP<br/>structural embeddings]
S --> E[Embedding-space analysis]
G --> E
F --> V[PCA where configured<br/>3D t-SNE visualization]
E --> V
E --> K[K-means across candidate k]
K --> Q[Silhouette-score comparison]
FastRP and GraphSAGE serve different purposes here. FastRP produces a standalone structural representation. GraphSAGE does not consume the FastRP vectors; it uses PCA-reduced semantic vectors as node features and introduces structural context through message passing over selected graph relationships.
The versioned CSV data contains 99 argumentative units and 141 explicit discourse relationships. Graph construction also creates four shared author nodes and one AUTHORED_BY edge per argumentative unit.
| Element | Types | Count in source data |
|---|---|---|
| Argumentative nodes | 34 Claims, 50 Premises, 15 Questions | 99 |
| Author nodes | Moderator and three fictional participants | 4 generated |
| Discourse edges | 67 Support, 19 Attack, 39 Answers, 16 Questions | 141 |
| Authorship edges | Argumentative unit → Author | 99 generated |
The five section folders are the source of truth. all_nodes.csv and all_edges.csv are derived convenience exports. The audit found no duplicate node IDs, orphaned edge endpoints, duplicate edges, or self-loops in the source files.
all-mpnet-base-v2 generates a normalized 768-dimensional vector from the Content property of every Claim, Premise, and Question. These vectors are stored on Neo4j nodes as semantic_embedding.
Neo4j GDS FastRP generates 768-dimensional structural_embedding vectors for argumentative and Author nodes. The experiment uses a random seed of 42 and normalization strength 0.5. Support, Attack, Questions, and Answers are projected as undirected; AUTHORED_BY is projected in reverse.
PCA first reduces semantic vectors while retaining 99% of their variance. GraphSAGE then aggregates those features over:
- naturally directed Support and Attack relationships;
- undirected Questions and Answers relationships.
The recorded configuration uses a mean aggregator, neighborhood samples [10, 5], 768 output dimensions, 40 epochs, learning rate 0.01, and random seed 42. The resulting node property is named hybrid_embedding in the code; “graph-contextualized semantic embedding” is the more precise description.
The notebooks provide two forms of exploratory analysis:
- three-dimensional t-SNE projections for all three spaces, with PCA preprocessing enabled for the recorded semantic and structural visualizations and disabled for the graph-contextualized visualization;
- K-means clustering of semantic and graph-contextualized semantic vectors, evaluated by Silhouette score over candidate cluster counts.
The clustering analysis does not compare clusters against ground-truth argumentative roles, stances, or topics. Silhouette score measures geometric cohesion and separation only, so it is a proxy for representation quality—not validation of usefulness on an argument-understanding task.
| Representation | Peak Silhouette score | Number of clusters |
|---|---|---|
| Semantic embeddings | 0.0682 | 43 |
| Graph-contextualized semantic embeddings | 0.2910 | 21 |
In this exploratory synthetic dataset, graph-contextualized semantic embeddings produced substantially stronger K-means cluster separation than semantic embeddings alone. The values above are recorded in the thesis; the 0.2910 result is also retained in the executed clustering notebook.
This is a result for one small constructed graph, one semantic model, one graph schema, and selected hyperparameters. It does not establish that GraphSAGE is generally superior, and choosing the best score across many candidate values of k makes the comparison descriptive rather than confirmatory.
- Synthetic-data bias: the LLM-generated UBI debate is cleaner and more regular than real discourse.
- Small sample: 99 argumentative units are insufficient for broad generalization and make clustering sensitive to individual nodes.
- Topology dependence: relationship selection, orientation, and graph construction directly affect neighborhood aggregation.
- Model dependence: only
all-mpnet-base-v2was evaluated as the semantic encoder. - Hyperparameter sensitivity: FastRP, GraphSAGE, PCA, t-SNE, K-means, and the chosen search over
kintroduce configuration sensitivity. - Proxy evaluation: cluster separation does not show performance on stance detection, argument classification, relation prediction, or another validated downstream task.
- Environment uncertainty: the exact Neo4j server and GDS plugin versions/edition used for the thesis were not recorded in the repository.
These constraints make the evidence preliminary. The main engineering contribution is the explicit, inspectable path from structured discourse data to graph-backed representation experiments.
.
├── resources/
│ ├── data/ # section-level source CSVs and merged exports
│ ├── prompt.md # synthetic-data generation prompt
│ └── visualisations/ # committed reference figures
├── src/
│ ├── embeddings/
│ │ ├── semantic/ # SentenceTransformer generation and t-SNE
│ │ ├── structural/ # FastRP generation and t-SNE
│ │ ├── hybrid/ # PCA preprocessing, GraphSAGE, and t-SNE
│ │ └── cluster_analysis.ipynb
│ ├── utils/ # CSV merge, Neo4j loading, shared configuration
│ └── main.py # graph-to-embedding pipeline orchestration
├── requirements.txt
└── thesis.pdf
- Python 3.12 (the version recorded by the analysis notebook);
- a Neo4j server compatible with the pinned Python driver;
- the server-side Neo4j Graph Data Science plugin with the FastRP and
beta.graphSageAPIs used by the code; - access to the GDS features/edition required for GraphSAGE;
- network access on first use to download
all-mpnet-base-v2.
The Python GDS client is pinned to 1.13, but that does not identify the original server-side GDS version. Check API compatibility if using a newer server. Use a dedicated local database: graph construction merges this project's entities but does not delete unrelated or stale data.
git clone https://github.com/Voidcake/Argument-Networks.git
cd Argument-Networks
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD='your-local-password'requirements.txt now lists the direct packages used by the pipeline and notebooks at their recorded versions. It is an environment snapshot, not a hash-locked specification of every transitive dependency.
The merged CSVs are already committed. To regenerate them from the five section folders:
python -m src.utils.merge_dataWith Neo4j running and GDS installed, execute the graph and embedding stages in order:
python -m src.mainThe command constructs the graph, writes semantic and FastRP vectors to Neo4j, applies PCA, and writes GraphSAGE outputs. Embeddings remain in Neo4j; the pipeline does not export a portable embedding snapshot.
To inspect stages independently, use this order:
python -m src.utils.construct_graph
python -m src.embeddings.semantic.semantic_embeddings
python -m src.embeddings.structural.structural_embeddings
python -m src.embeddings.hybrid.preprocess_embeddings
python -m src.embeddings.hybrid.hybrid_embeddingsStart Jupyter from the repository root so src imports resolve:
jupyter labRun the three visualization notebooks after the pipeline, then src/embeddings/cluster_analysis.ipynb. Every notebook queries a live Neo4j database. The one-command Python pipeline does not execute the notebooks or regenerate the committed PNG figures.
Seeds are set where the libraries expose them, but exact numerical reproduction is not guaranteed across unrecorded GDS server versions, hardware, and stochastic implementations. The committed figures and thesis are the reference artifacts for the reported run.
The full thesis—Argument Networks: Structural and Semantic Exploration of Argumentative Discourse (submitted January 2025)—is included as thesis.pdf. It contains the argumentation-theory background, methodology, qualitative interpretation, and extended discussion intentionally omitted from this engineering overview.
The synthetic dataset prompt is versioned in resources/prompt.md.
This is an archival bachelor-thesis research prototype, not a deployed application. Possible uses such as stance detection, debate summarization, semantic search, decision support, or RAG are future directions rather than implemented features.
Code and repository materials are provided under the MIT License.