# decompositional-semantics-initiative/decomp architecture

> Architecture diagram of the GitHub repository decompositional-semantics-initiative/decomp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/decompositional-semantics-initiative/decomp
- Repository: https://github.com/decompositional-semantics-initiative/decomp

## Overview

Decomp is a Python toolkit for loading and exploring Universal Decompositional Semantics (UDS) corpora: it builds sentence graphs combining Universal Dependencies syntax with semantic annotations, which users can inspect, query, serialize, and visualize. A separate PredPatt subsystem extracts predicate–argument structures from dependency parses and can represent them as graphs. The README documents RDF/SPARQL interoperability and multiple serialization formats. Some subsystem wiring is inferred only from package structure and documentation; unsampled implementation details are not represented as specific call edges.

Main entry points: [`decomp/semantics/uds/corpus.py`](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/corpus.py) (UDS Corpus), [`decomp/semantics/uds/graph.py`](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/graph.py) (Sentence Graph), [`decomp/semantics/predpatt/corpus.py`](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/corpus.py) (PredPatt Corpus), [`decomp/semantics/predpatt/extraction/engine.py`](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/extraction/engine.py) (Extraction Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Corpus Loading"]
  node_uds_corpus["UDS Corpus<br/>[corpus.py]"]
  node_corpus_base["Corpus Container<br/>[corpus.py]"]
  node_dependency_trees["Dependency Trees<br/>[dependency.py]"]
end

subgraph group_graphs["UDS Graph Model"]
  node_sentence_graph["Sentence Graph<br/>[graph.py]"]
  node_document_graph["Document Graph<br/>[document.py]"]
  node_annotation_model["Annotations<br/>[annotation.py]"]
  node_annotation_metadata["Annotation Metadata<br/>[metadata.py]"]
  node_graph_types["Graph Types<br/>[types.py]"]
end

subgraph group_predpatt["Predicate Extraction"]
  node_predpatt_corpus["PredPatt Corpus<br/>[corpus.py]"]
  node_ud_parse["UD Parse<br/>[udparse.py]"]
  node_parse_loader["Parse Loader<br/>[loader.py]"]
  node_extraction_engine["Extraction Engine<br/>[engine.py]"]
  node_predicates_arguments["Predicates And Arguments<br/>[predicate.py]"]
  node_extraction_rules["Extraction Rules"]
  node_extraction_filters["Extraction Filters"]
  node_predpatt_graph["PredPatt Graph<br/>[graph.py]"]
  node_linearization["Linearized Output<br/>[linearization.py]"]
end

subgraph group_interop["Query And Export"]
  node_nx_graph["NetworkX Graph Support<br/>[nx.py]"]
  node_rdf_conversion["RDF Conversion<br/>[rdf.py]"]
  node_rdf_store[("RDF Graph")]
end

subgraph group_visualization["Graph Visualization"]
  node_visualizer["UDS Visualizer<br/>[uds_vis.py]"]
end

node_researcher(("Researcher"))
node_ud_treebank["UD Treebank"]
node_uds_annotations["UDS Annotations"]
node_graph_formats["Graph Formats"]

node_researcher -->|"loads corpus"| node_uds_corpus
node_ud_treebank -->|"provides parses"| node_dependency_trees
node_uds_annotations -->|"provides annotations"| node_uds_corpus
node_uds_corpus -->|"uses container"| node_corpus_base
node_uds_corpus -->|"builds syntax"| node_dependency_trees
node_uds_corpus -->|"builds graphs"| node_sentence_graph
node_uds_corpus -->|"provides documents"| node_document_graph
node_sentence_graph -->|"models attributes"| node_annotation_model
node_sentence_graph -->|"uses metadata"| node_annotation_metadata
node_sentence_graph -->|"uses types"| node_graph_types
node_researcher -->|"extracts predicates"| node_predpatt_corpus
node_parse_loader -->|"loads parse"| node_ud_parse
node_predpatt_corpus -->|"loads parses"| node_parse_loader
node_predpatt_corpus -->|"runs extraction"| node_extraction_engine
node_extraction_engine -->|"builds structures"| node_predicates_arguments
node_extraction_engine -->|"applies rules"| node_extraction_rules
node_extraction_engine -->|"filters results"| node_extraction_filters
node_predpatt_corpus -->|"builds graphs"| node_predpatt_graph
node_predpatt_graph -->|"combines syntax"| node_dependency_trees
node_researcher -->|"formats extraction"| node_linearization
node_researcher -->|"queries graph"| node_nx_graph
node_nx_graph -->|"operates on"| node_sentence_graph
node_researcher -->|"converts graph"| node_rdf_conversion
node_rdf_conversion -->|"creates triples"| node_rdf_store
node_researcher -.->|"queries with SPARQL"| node_rdf_store
node_researcher -->|"serializes graph"| node_graph_formats
node_nx_graph -->|"exports formats"| node_graph_formats
node_researcher -->|"views graphs"| node_visualizer
node_visualizer -->|"renders graph"| node_sentence_graph

click node_uds_corpus "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/corpus.py"
click node_corpus_base "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/corpus/corpus.py"
click node_dependency_trees "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/syntax/dependency.py"
click node_sentence_graph "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/graph.py"
click node_document_graph "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/document.py"
click node_annotation_model "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/annotation.py"
click node_annotation_metadata "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/metadata.py"
click node_graph_types "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/types.py"
click node_predpatt_corpus "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/corpus.py"
click node_ud_parse "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/parsing/udparse.py"
click node_parse_loader "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/parsing/loader.py"
click node_extraction_engine "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/extraction/engine.py"
click node_predicates_arguments "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/core/predicate.py"
click node_extraction_rules "https://github.com/decompositional-semantics-initiative/decomp/tree/master/decomp/semantics/predpatt/rules"
click node_extraction_filters "https://github.com/decompositional-semantics-initiative/decomp/tree/master/decomp/semantics/predpatt/filters"
click node_predpatt_graph "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/graph.py"
click node_linearization "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/utils/linearization.py"
click node_nx_graph "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/graph/nx.py"
click node_rdf_conversion "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/graph/rdf.py"
click node_visualizer "https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/vis/uds_vis.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_uds_corpus,node_corpus_base,node_dependency_trees toneBlue
class node_sentence_graph,node_document_graph,node_annotation_model,node_annotation_metadata,node_graph_types toneAmber
class node_predpatt_corpus,node_ud_parse,node_parse_loader,node_extraction_engine,node_predicates_arguments,node_extraction_rules,node_extraction_filters,node_predpatt_graph,node_linearization toneMint
class node_nx_graph,node_rdf_conversion,node_rdf_store toneRose
class node_visualizer,node_researcher,node_ud_treebank,node_uds_annotations,node_graph_formats toneIndigo
```

## Components

### Corpus Loading

- [UDS Corpus](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/corpus.py): `decomp/semantics/uds/corpus.py`
- [Corpus Container](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/corpus/corpus.py): `decomp/corpus/corpus.py`
- [Dependency Trees](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/syntax/dependency.py): `decomp/syntax/dependency.py`

### UDS Graph Model

- [Sentence Graph](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/graph.py): `decomp/semantics/uds/graph.py`
- [Document Graph](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/document.py): `decomp/semantics/uds/document.py`
- [Annotations](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/annotation.py): `decomp/semantics/uds/annotation.py`
- [Annotation Metadata](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/metadata.py): `decomp/semantics/uds/metadata.py`
- [Graph Types](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/uds/types.py): `decomp/semantics/uds/types.py`

### Predicate Extraction

- [PredPatt Corpus](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/corpus.py): `decomp/semantics/predpatt/corpus.py`
- [UD Parse](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/parsing/udparse.py): `decomp/semantics/predpatt/parsing/udparse.py`
- [Parse Loader](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/parsing/loader.py): `decomp/semantics/predpatt/parsing/loader.py`
- [Extraction Engine](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/extraction/engine.py): `decomp/semantics/predpatt/extraction/engine.py`
- [Predicates And Arguments](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/core/predicate.py): `decomp/semantics/predpatt/core/predicate.py`
- [Extraction Rules](https://github.com/decompositional-semantics-initiative/decomp/tree/master/decomp/semantics/predpatt/rules): `decomp/semantics/predpatt/rules`
- [Extraction Filters](https://github.com/decompositional-semantics-initiative/decomp/tree/master/decomp/semantics/predpatt/filters): `decomp/semantics/predpatt/filters`
- [PredPatt Graph](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/graph.py): `decomp/semantics/predpatt/graph.py`
- [Linearized Output](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/semantics/predpatt/utils/linearization.py): `decomp/semantics/predpatt/utils/linearization.py`

### Query And Export

- [NetworkX Graph Support](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/graph/nx.py): `decomp/graph/nx.py`
- [RDF Conversion](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/graph/rdf.py): `decomp/graph/rdf.py`
- **RDF Graph**

### Graph Visualization

- [UDS Visualizer](https://github.com/decompositional-semantics-initiative/decomp/blob/master/decomp/vis/uds_vis.py): `decomp/vis/uds_vis.py`

### Other components

- **Researcher**
- **UD Treebank**
- **UDS Annotations**
- **Graph Formats**

## Connections

- Researcher → UDS Corpus: loads corpus
- UD Treebank → Dependency Trees: provides parses
- UDS Annotations → UDS Corpus: provides annotations
- UDS Corpus → Corpus Container: uses container
- UDS Corpus → Dependency Trees: builds syntax
- UDS Corpus → Sentence Graph: builds graphs
- UDS Corpus → Document Graph: provides documents
- Sentence Graph → Annotations: models attributes
- Sentence Graph → Annotation Metadata: uses metadata
- Sentence Graph → Graph Types: uses types
- Researcher → PredPatt Corpus: extracts predicates
- Parse Loader → UD Parse: loads parse
- PredPatt Corpus → Parse Loader: loads parses
- PredPatt Corpus → Extraction Engine: runs extraction
- Extraction Engine → Predicates And Arguments: builds structures
- Extraction Engine → Extraction Rules: applies rules
- Extraction Engine → Extraction Filters: filters results
- PredPatt Corpus → PredPatt Graph: builds graphs
- PredPatt Graph → Dependency Trees: combines syntax
- Researcher → Linearized Output: formats extraction
- Researcher → NetworkX Graph Support: queries graph
- NetworkX Graph Support → Sentence Graph: operates on
- Researcher → RDF Conversion: converts graph
- RDF Conversion → RDF Graph: creates triples
- Researcher → RDF Graph: queries with SPARQL
- Researcher → Graph Formats: serializes graph
- NetworkX Graph Support → Graph Formats: exports formats
- Researcher → UDS Visualizer: views graphs
- UDS Visualizer → Sentence Graph: renders graph