ACR-reasoner

Ontology-driven clinical reasoning engine for ACRAgent, combining SWRL/SQWRL rule logic, Bayesian enhancement, CDS result schemas, and an interim integration bridge toward MVP.

Purpose

ACR-reasoner is the dedicated reasoning-engine repository for ACRAgent.

This repository is separate from ACR-platform, which contains the working demo platform and website stack. The purpose of ACR-reasoner is to develop, validate, and version the clinical reasoning layer independently from the public/demo web platform.

The repository currently supports:

• ACR Ontology reasoning assets
• SWRL rule development and maintenance
• SQWRL query development and maintenance
• Bayesian probabilistic enhancement layer
• CDS result schema design
• Bayesian test harness and coverage validation
• Interim JavaScript bridge logic for acr_pathway.html
• Migration path toward the eventual native ontology reasoner

Scope

This repository is for reasoning logic and validation, not for production patient-data custody.

ACRAgent follows the principle:

Data Stays. Rules Travel.

This means:

• patient data should remain within the hospital, clinic, doctor, or patient-controlled environment
• ACRAgent reasoning assets travel securely to the data environment
• this repository does not define a central live production patient repository
• any local/demo/test database structures are for MVP, testing, and partner guidance only

Relationship to ACR-platform

• ACR-platform contains the demo platform and web application for www.acragent.com
• ACR-reasoner contains the reasoning engine workstream

Typical integration flow:

1. reasoning assets are developed and validated in ACR-reasoner
2. stable outputs are packaged
3. selected outputs are integrated into ACR-platform
4. demo/MVP release candidates are tested locally before deployment

Current Development Phase

Current phase focus:

• maintain and extend the ACR Ontology reasoning model
• validate the current 22 SWRL rules and 15 SQWRL queries
• integrate Bayesian posterior reasoning into the interim CDS flow
• maintain a hard-coded JavaScript bridge in acr_pathway.html until the native ontology reasoner is complete
• build a formal Bayesian test harness with before/after comparison and rule coverage tracking
• align CDS output with an explicit machine-readable schema

Repository Structure

ACR-reasoner/
├── ontology/
│   ├── swrl/
│   ├── sqwrl/
│   ├── mappings/
│   └── docs/
├── bayes/
│   ├── js/
│   ├── python/
│   ├── config/
│   └── tests/
├── harness/
│   ├── cases/
│   ├── coverage/
│   ├── ui/
│   └── schemas/
├── integration/
│   ├── acr_pathway/
│   └── bridge/
├── docs/
├── examples/
└── README.md

Recommended Working Layout

ontology/

Contains the formal knowledge layer.

Suggested contents:

• native .swrl files
• native .sqwrl files
• English and Chinese rule/query versions where needed
• ontology-to-JS bridge mappings
• ontology notes and design documentation

bayes/

Contains the Bayesian enhancement layer.

Suggested contents:

• JavaScript Bayes engine
• Python Bayes engine
• evidence-weight configuration
• prior probability configuration
• unit tests for posterior calculations
• reference examples

harness/

Contains the ACRAgent Bayesian validation framework.

Suggested contents:

• named clinical test cases
• 22-rule SWRL coverage table
• 15-query SQWRL coverage table
• deterministic vs Bayes comparison cases
• harness UI page
• revised CDS result schemas

integration/

Contains interim integration assets for the current MVP bridge.

Suggested contents:

• acr_pathway integration logic
• Bayes ON/OFF bridge
• schema adapters
• packaging notes for ACR-platform

docs/

Contains technical and product documentation.

Suggested contents:

• architecture notes
• workflow and SOP documents
• release procedures
• validation strategy
• mapping documents

examples/

Contains demonstration outputs and sample data.

Suggested contents:

• sample CDS result JSON
• example patient test payloads
• example posterior calculations
• example before/after outputs

---

Full folder and files structure

ACR-reasoner
├── README.md
├── .gitignore
├── docs
│   ├── architecture
│   │   ├── ACRAgent_reasoner_architecture.md
│   │   ├── bayes_integration_architecture.md
│   │   ├── cds_output_formulation.md
│   │   └── data_stays_rules_travel.md
│   ├── workflow
│   │   ├── local_development_workflow.md
│   │   ├── release_workflow.md
│   │   ├── regression_test_checklist.md
│   │   └── github_desktop_workflow.md
│   ├── mappings
│   │   ├── swrl_to_js_mapping.md
│   │   ├── sqwrl_to_js_mapping.md
│   │   ├── pathway_bayes_mapping.md
│   │   └── ui_to_cds_schema_mapping.md
│   └── validation
│       ├── bayesian_test_harness_specification.md
│       ├── swrl_22_rule_coverage_table.csv
│       ├── sqwrl_15_query_coverage_table.csv
│       └── test_cases_catalogue.md
├── ontology
│   ├── swrl
│   │   ├── acr_rules_native.swrl
│   │   ├── acr_rules_bayesian_bridge.swrl
│   │   ├── acr_swrl_rules_zh.swrl
│   │   └── acr_swrl_rules_en.swrl
│   ├── sqwrl
│   │   ├── acr_queries_native.sqwrl
│   │   ├── acr_queries_bayesian_bridge.sqwrl
│   │   ├── acr_sqwrl_queries_zh.sqwrl
│   │   └── acr_sqwrl_queries_en.sqwrl
│   ├── json
│   │   ├── rules.json
│   │   ├── queries.json
│   │   ├── rules.en.json
│   │   ├── rules.zh.json
│   │   ├── queries.en.json
│   │   └── queries.zh.json
│   ├── mappings
│   │   ├── swrl_rule_map.json
│   │   ├── sqwrl_query_map.json
│   │   ├── rule_evidence_map.json
│   │   └── ontology_bridge_map.json
│   └── notes
│       ├── ontology_design_notes.md
│       ├── swrl_rule_rationale.md
│       └── sqwrl_query_rationale.md
├── bayes
│   ├── js
│   │   ├── bayesEngine.js
│   │   ├── bayesEvidenceMapper.js
│   │   ├── bayesAssessmentRunner.js
│   │   └── bayesDebugView.js
│   ├── python
│   │   ├── bayes_engine.py
│   │   ├── posterior_examples.py
│   │   └── validation_runner.py
│   ├── config
│   │   ├── bayes-config.json
│   │   ├── priors.json
│   │   ├── likelihood_ratios.json
│   │   └── hypothesis_catalogue.json
│   ├── tests
│   │   ├── bayesEngine.test.js
│   │   ├── evidenceMapper.test.js
│   │   ├── posterior_regression_cases.json
│   │   └── bayes_expected_outputs.json
│   └── examples
│       ├── simple_posterior_example.json
│       ├── breast_case_example_1.json
│       └── breast_case_example_2.json
├── harness
│   ├── ui
│   │   ├── acr_bayes_test_harness.html
│   │   ├── harness.css
│   │   └── harness.js
│   ├── cases
│   │   ├── case_library.json
│   │   ├── subtype_cases.json
│   │   ├── treatment_cases.json
│   │   ├── mdt_cases.json
│   │   ├── staging_cases.json
│   │   └── followup_cases.json
│   ├── coverage
│   │   ├── swrl_22_rule_coverage_table.csv
│   │   ├── sqwrl_15_query_coverage_table.csv
│   │   ├── swrl_coverage_status.json
│   │   └── sqwrl_coverage_status.json
│   ├── schemas
│   │   ├── cds-result.schema.json
│   │   ├── cds-result.bayes.schema.json
│   │   ├── case.schema.json
│   │   └── bayes_assessment.schema.json
│   └── reports
│       ├── expected_vs_actual_template.md
│       ├── regression_results_template.md
│       └── test_execution_log_template.md
├── integration
│   ├── acr_pathway
│   │   ├── acr_pathway.html
│   │   ├── acr_pathway_bayes_modified.html
│   │   ├── acr_pathway_bayes_bridge.js
│   │   ├── cds-result.schema.json
│   │   └── acr_pathway_cds_logic_notes.md
│   ├── platform_bridge
│   │   ├── export_for_acr_platform.md
│   │   ├── file_replacement_map.md
│   │   ├── local_test_integration_steps.md
│   │   └── regression_test_matrix.md
│   └── demo_assets
│       ├── sample_outputs
│       ├── screenshots
│       └── before_after_examples
├── examples
│   ├── sample_cds_output_deterministic.json
│   ├── sample_cds_output_bayes.json
│   ├── sample_patient_payload.json
│   └── sample_reasoning_trace.json
└── scripts
    ├── generate-swrl-json.js
    ├── generate-swrl-languages.js
    ├── validate-cds-schema.js
    ├── run-harness.js
    └── export-integration-bundle.js

Current Reasoning Architecture

At present, ACRAgent uses an interim phased approach:

1. structured patient facts are prepared
2. interim hard-coded JavaScript logic mirrors part of the SWRL/SQWRL reasoning
3. Bayesian reasoning performs posterior update on selected hypotheses
4. CDS output is assembled into a structured result
5. the long-term target is to replace the interim JS reasoning core with the native ontology reasoner

This means the current JS logic is a temporary bridge, not the final ontology implementation.

CDS Output Philosophy

The CDS result should not be presented as isolated raw rule firings.

The preferred result structure is:

• inferred clinical state
• recommendation package
• Bayesian confidence package
• explanation and provenance package
• operational next steps

Rule-level detail should remain available for traceability, testing, and audit.

Testing Strategy

This repository should use layered validation:

1. Unit Tests

For:

• Bayes theorem calculations
• prior/odds/posterior conversions
• evidence combination
• edge cases

2. Integration Tests

For:

• patient fact mapping
• JS bridge to Bayes module
• CDS schema output structure
• pathway alignment with intended rule logic

3. Coverage Tests

For:

• all 22 SWRL rules
• all 15 SQWRL queries
• explicit status:
  • implemented
  • partial
  • not yet mirrored
  • pending ontology-native support

4. Harness Demonstration Tests

For:

• Bayes OFF deterministic result
• Bayes ON posterior-enhanced result
• expected vs actual comparison
• pass/fail outcome

Local Development Workflow

Local development is expected to use:

• GitHub Desktop
• local development machine
• sync to GitHub repository
• controlled export/integration into ACR-platform

Recommended cycle:

1. create or update reasoning assets in ACR-reasoner
2. validate locally with tests and harness
3. package selected integration outputs
4. update local test copy of ACR-platform
5. run platform-level regression tests
6. promote approved changes to the hosted demo platform

Branching Recommendation

Recommended branch model:

• main — stable validated reasoning assets
• develop — active integration work
• feature branches, for example:
  • feature/bayes-engine
  • feature/swrl-coverage
  • feature/cds-schema
  • feature/pathway-bridge
  • feature/harness-ui

Initial Priorities

Suggested first milestones:

Milestone 1

Repository setup and baseline import

Milestone 2

SWRL/SQWRL canonical organisation

Milestone 3

Bayesian engine and evidence mappings

Milestone 4

Bayesian test harness and coverage tables

Milestone 5

acr_pathway interim integration bridge

Milestone 6

CDS schema revision and validation

Compliance and Data Boundary

This repository must remain aligned with the ACRAgent operating principle:

Data Stays. Rules Travel.

Therefore:

• no assumption of central production access to live patient records
• no design dependency on central patient-data custody
• demo/test/local database structures are for validation and partner guidance only
• deployment models must support local reasoning execution within partner environments

Status

This repository is part of phased development toward MVP.

It supports:

• current ontology and rule work
• Bayesian enhancement
• interim bridge logic
• validation and test harness development

It does not yet represent the final native ontology runtime.

Maintainer

ACRAgent development team
Repository owner: KY-BChain

License

To be defined according to project and partner requirements.