parthganeriwala/soartoprismtranslator

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.