# parthganeriwala/soartoprismtranslator architecture

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

- Interactive diagram: https://gitdiagram.com/parthganeriwala/soartoprismtranslator
- Repository: https://github.com/parthganeriwala/soartoprismtranslator

## Overview

1. **Purpose and top-level shape**
   - This is a **Java 17 / Maven** command-line translator that converts **Soar production-rule models** into **PRISM** model files.
   - The architecture is a pipeline: **Soar source + optional JSON config → ANTLR parse tree → internal rule model → PRISM text output**.

2. **Entry point and orchestration**
   - The runtime entry point is `edu.fit.assist.translator.soar.main`.
   - It coordinates reading the Soar input, loading optional configuration, deciding which translation path to use, and writing the generated PRISM model to `output1.pm` and stdout.

3. **Parsing boundary: Soar grammar**
   - The parser is defined in `src/main/antlr4/.../Soar.g4`.
   - Maven generates the ANTLR runtime classes under `src/main/java/.../translator/gen/`:
     - lexer/parser
     - listener/visitor interfaces
     - generated tokens/interp metadata
   - This is the hard boundary between **textual Soar syntax** and the tool’s internal representation.

4. **Rule extraction layer**
   - The `soar` package contains the domain objects used after parsing:
     - `Rule`, `Variable`, `Input`, `Output`, `SoarRules`, `MergedTransition`
   - These classes act as the translator’s intermediate model: they normalize parsed Soar productions into rule/variable structures that can be analyzed independently from the grammar.

5. **Parse-tree walking and semantic collection**
   - `Visitor.java` is the main semantic extractor over the ANTLR parse tree.
   - Its role is to populate the internal Soar rule structures from production rules and state/operator/goal patterns.
   - `TranslatorUtils.java` likely supports helper logic for pattern handling, normalization, and value inference across rules.

6. **Translation subsystem split**
   - There are two translator paths:
     - `Translate.java` for the **general** Soar-to-PRISM translation path
     - `TimeBasedTranslator.java` for the **time-based** path
   - The README states the **general translator is currently not functional**, so the effective architecture today is centered on the time-based translator.

7. **Time-based model specialization**
   - The tool detects models with time-related state such as `time-counter` or `total-time`.
   - `TimeBasedTranslator` is the working implementation and is responsible for emitting PRISM modules that represent time progression and state transitions.
   - This creates an important architectural constraint: supported models are not arbitrary Soar programs, but those that fit the translator’s time-centric assumptions.

8. **Configuration and external parameters**
   - `PrismConfig.java` and `test_config.json` indicate support for external model parameters.
   - The README and `CONFIG_GUIDE.md` show that the config file is used for things like:
     - probability distributions
     - response-time distributions
     - error rates
     - sickness/probability tables
   - This is an input boundary separate from the Soar source itself, used to enrich the translation with numeric semantics.

9. **Outputs and generated artifacts**
   - The translated PRISM model is emitted as plain `.pm` text.
   - `output.pm` / `output1.pm` are repository-level output artifacts, showing the translator’s expected product format.
   - The output target is **PRISM DTMC/MDP syntax**, with the current examples emphasizing deterministic/time-stepped DTMC-style generation.

10. **Example and validation corpus**
   - The `models/` directory is not core runtime code; it is a collection of sample and reference models used to exercise and validate translation behavior.
   - Subfolders like `attention`, `physiology`, and `translated soar models` suggest multiple model families used to test coverage and compare against manual translations.

11. **Build-time tooling**
   - Maven manages compilation and ANTLR code generation.
   - The generated parser code is checked into the tree under `gen`, so the architecture includes both source grammar and generated parser artifacts as first-class components.

12. **Key architectural constraint**
   - The most important boundary for diagramming is:
     - **Soar input parsing and rule normalization** on one side
     - **PRISM model emission** on the other
   - In the current repo state, only the **time-based translation pipeline** should be shown as operational; the general translation path should be shown as present but not currently reliable.

Main entry points: [`src/main/java/edu/fit/assist/translator/soar/SoarRules.java`](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/SoarRules.java) (Rule model), [`src/main/java/edu/fit/assist/translator/soar/main.java`](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/main.java) (CLI entry), [`src/main/java/edu/fit/assist/translator/soar/TimeBasedTranslator.java`](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/TimeBasedTranslator.java) (Time-based), [`src/main/java/edu/fit/assist/translator/soar/Visitor.java`](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Visitor.java) (Parse visitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["CLI entry<br/>entrypoint<br/>[main.java]"]
  node_visitor["Parse visitor<br/>semantic extractor<br/>[Visitor.java]"]
  node_translator_utils["Utils<br/>helper logic"]
  node_soar_rules["Rule model<br/>intermediate model<br/>[SoarRules.java]"]
  node_rule["Rule<br/>[Rule.java]"]
  node_variable["Variable<br/>state entity<br/>[Variable.java]"]
  node_input["Input<br/>fact entity<br/>[Input.java]"]
  node_output["Output<br/>fact entity<br/>[Output.java]"]
  node_merged_transition["Merged trans.<br/>transition model"]
  node_prism_config["PRISM config<br/>external params<br/>[PrismConfig.java]"]
  node_time_translator["Time-based<br/>working translator"]
  node_general_translator["General path<br/>translator<br/>[Translate.java]"]
end

subgraph group_grammar["Grammar"]
  node_soar_grammar["Soar grammar<br/>antlr grammar<br/>[Soar.g4]"]
  node_generated_parser["Generated parser<br/>antlr runtime<br/>[SoarParser.java]"]
end

subgraph group_examples["Examples"]
  node_models[("Models<br/>examples")]
  node_pm_outputs["PM outputs<br/>artifacts<br/>[output1.pm]"]
end

node_main -->|"parse input"| node_soar_grammar
node_soar_grammar -.->|"generate"| node_generated_parser
node_main -->|"walk parse tree"| node_visitor
node_visitor -->|"build model"| node_soar_rules
node_soar_rules -->|"contains"| node_rule
node_soar_rules -->|"contains"| node_variable
node_soar_rules -->|"contains"| node_input
node_soar_rules -->|"contains"| node_output
node_soar_rules -->|"derives"| node_merged_transition
node_visitor -->|"uses"| node_translator_utils
node_main -->|"load config"| node_prism_config
node_main -->|"translate"| node_time_translator
node_main -.->|"translate"| node_general_translator
node_time_translator -->|"reads params"| node_prism_config
node_time_translator -->|"emit from"| node_merged_transition
node_general_translator -->|"consumes"| node_soar_rules
node_time_translator -->|"writes"| node_pm_outputs
node_main -->|"save output"| node_pm_outputs
node_models -.->|"reference"| node_pm_outputs

click node_main "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/main.java"
click node_visitor "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Visitor.java"
click node_translator_utils "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/TranslatorUtils.java"
click node_soar_rules "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/SoarRules.java"
click node_rule "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Rule.java"
click node_variable "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Variable.java"
click node_input "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Input.java"
click node_output "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Output.java"
click node_merged_transition "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/MergedTransition.java"
click node_prism_config "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/PrismConfig.java"
click node_time_translator "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/TimeBasedTranslator.java"
click node_general_translator "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Translate.java"
click node_soar_grammar "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/antlr4/edu/fit/assist/soar/Soar.g4"
click node_generated_parser "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/gen/SoarParser.java"
click node_models "https://github.com/parthganeriwala/soartoprismtranslator/tree/main/models"
click node_pm_outputs "https://github.com/parthganeriwala/soartoprismtranslator/blob/main/output1.pm"

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_main,node_visitor,node_translator_utils,node_soar_rules,node_rule,node_variable,node_input,node_output,node_merged_transition,node_prism_config,node_time_translator,node_general_translator toneBlue
class node_soar_grammar,node_generated_parser toneAmber
class node_models,node_pm_outputs toneMint
```

## Components

### Runtime

Command-line translation pipeline and semantic model

- [CLI entry](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/main.java): entrypoint · Java main program that coordinates loading input, config, translation, and output · `src/main/java/edu/fit/assist/translator/soar/main.java`
- [Parse visitor](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Visitor.java): semantic extractor · Walks the ANTLR parse tree and builds internal Soar rule structures · `src/main/java/edu/fit/assist/translator/soar/Visitor.java`
- [Utils](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/TranslatorUtils.java): helper logic · Shared normalization and pattern-handling helpers used during translation · `src/main/java/edu/fit/assist/translator/soar/TranslatorUtils.java`
- [Rule model](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/SoarRules.java): intermediate model · Normalizes Soar productions into rule, variable, input, and output structures · `src/main/java/edu/fit/assist/translator/soar/SoarRules.java`
- [Rule](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Rule.java): rule entity · Represents a translated Soar production rule · `src/main/java/edu/fit/assist/translator/soar/Rule.java`
- [Variable](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Variable.java): state entity · Represents a variable used in extracted Soar rules · `src/main/java/edu/fit/assist/translator/soar/Variable.java`
- [Input](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Input.java): fact entity · Represents input-side facts or conditions from parsed Soar structures · `src/main/java/edu/fit/assist/translator/soar/Input.java`
- [Output](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Output.java): fact entity · Represents output-side effects or actions from parsed Soar structures · `src/main/java/edu/fit/assist/translator/soar/Output.java`
- [Merged trans.](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/MergedTransition.java): transition model · Combines related transitions for downstream PRISM emission · `src/main/java/edu/fit/assist/translator/soar/MergedTransition.java`
- [PRISM config](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/PrismConfig.java): external params · Loads probability and timing parameters used to enrich translation · `src/main/java/edu/fit/assist/translator/soar/PrismConfig.java`
- [Time-based](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/TimeBasedTranslator.java): working translator · Operational translation path that emits time-centric PRISM models · `src/main/java/edu/fit/assist/translator/soar/TimeBasedTranslator.java`
- [General path](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/soar/Translate.java): translator · Alternative Soar-to-PRISM path present in the repo but not currently reliable · `src/main/java/edu/fit/assist/translator/soar/Translate.java`

### Grammar

Soar ANTLR grammar and generated parser artifacts

- [Soar grammar](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/antlr4/edu/fit/assist/soar/Soar.g4): antlr grammar · ANTLR grammar defining the textual Soar syntax boundary · `src/main/antlr4/edu/fit/assist/soar/Soar.g4`
- [Generated parser](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/src/main/java/edu/fit/assist/translator/gen/SoarParser.java): antlr runtime · Checked-in lexer, parser, visitor, and token artifacts generated from the grammar · `src/main/java/edu/fit/assist/translator/gen/SoarParser.java`

### Examples

Sample models and reference PRISM outputs

- [Models](https://github.com/parthganeriwala/soartoprismtranslator/tree/main/models): examples · Sample Soar/PRISM models used for validation and reference · `models`
- [PM outputs](https://github.com/parthganeriwala/soartoprismtranslator/blob/main/output1.pm): artifacts · Example generated PRISM model files at the repository root · `output1.pm`

## Connections

- CLI entry → Soar grammar: parse input · Reads Soar source through the grammar boundary
- Soar grammar → Generated parser: generate · ANTLR grammar produces lexer/parser artifacts
- CLI entry → Parse visitor: walk parse tree · Uses the visitor to extract semantic rule data
- Parse visitor → Rule model: build model · Populates the internal Soar rule representation
- Rule model → Rule: contains · Stores normalized production rules
- Rule model → Variable: contains · Stores rule variables and state references
- Rule model → Input: contains · Stores parsed input conditions
- Rule model → Output: contains · Stores parsed outputs/actions
- Rule model → Merged trans.: derives · Collapses related rule behavior into merged transitions
- Parse visitor → Utils: uses · Applies helper normalization during extraction
- CLI entry → PRISM config: load config · Optionally loads external numeric parameters
- CLI entry → Time-based: translate · Primary operational translation path
- CLI entry → General path: translate · Alternative path kept in the codebase
- Time-based → PRISM config: reads params · Uses config values for probabilities and timing
- Time-based → Merged trans.: emit from · Generates PRISM transitions from normalized rule structure
- General path → Rule model: consumes · Uses the internal rule model when invoked
- Time-based → PM outputs: writes · Produces PRISM .pm model text
- CLI entry → PM outputs: save output · Writes the translated model to output file and stdout
- Models → PM outputs: reference · Sample models and translated outputs for validation