An auditable research prototype for reasoning over longitudinal systemic lupus erythematosus (SLE) reports. It combines deterministic trajectory rules, optional model overlays, decision tables, and bounded LLM report rendering.
Warning
This repository is not a medical device, diagnostic tool, or clinically validated prediction system. Outputs are for research and engineering only. Do not use them for patient care, treatment selection, or medication dosing.
Python 3.10 through 3.12 is supported. The default Demo is offline and does not need an API key.
git clone https://github.com/xhu014183-cmd/SLE-Trajectory.git
cd SLE-Trajectory
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
sle-trajectory-demo --no-llmOn macOS or Linux, activate with source .venv/bin/activate. The Demo writes a
complete audit trail to build/e2e/sle_renal_demo/ and prints the selected
trajectory state, model routing, LLM status, and report safety result.
Open the generated summary:
build/e2e/sle_renal_demo/00_e2e_summary.md
See the installation guide for direct-environment commands, optional ML/RAG dependencies, and troubleshooting.
Raw LLM generation is fluent but difficult to audit when the important signal is a trend such as rising proteinuria, falling complement, changing creatinine, or infection overlap. Snapshot rule tables are inspectable, but they can miss the meaning of a time series.
This project keeps clinical-state assignment outside the LLM:
| Layer | Responsibility | Auditable output |
|---|---|---|
| Fact extraction | Convert host-style JSON into structured SLE evidence | Extracted facts and normalized case JSON |
| Rule engine | Assign a bounded trajectory state and evidence gates | State, confidence, evidence, contradictions, missing evidence |
| Model overlays | Add eligible engineering probabilities and review signals | Routing decisions, features, probabilities, model versions |
| Decision tables | Map organ/state facts to structured suggestions | Matched rules and rendered table output |
| LLM renderer | Turn the structured anchor into readable prose | Exact messages, endpoint status, raw/fallback report |
| Safety guardrails | Remove or flag unsupported report language | Machine-readable safety check |
flowchart LR
A[Host JSON] --> B[Fact extraction]
B --> C[Deterministic trajectory engine]
C --> D[Optional model overlays]
C --> E[Decision tables]
D --> F[Structured anchor]
E --> F
F --> G[Bounded LLM renderer]
G --> H[Report safety guardrails]
H --> I[Final report and audit trail]
The LLM never receives responsibility for assigning the primary trajectory state. When live rendering is disabled or unavailable, the pipeline produces a deterministic fallback report.
sle-trajectory-demo --no-llmThe audit directory contains:
build/e2e/sle_renal_demo/
|-- 00_e2e_summary.md
|-- 01_input_host_raw.json
|-- 02_extracted_facts.json
|-- 03_adapter_case.json
|-- 04_small_model_output.json
|-- 05_decision_table_output.json
|-- 06_framework.json
|-- 07_anchor.md
|-- 07_anchor_for_llm.md
|-- 08_llm_prompt.md
|-- 08_llm_prompt_messages.json
|-- 09_llm_call_status.json
|-- 10_final_report.md
`-- 11_final_report_safety_check.json
--input accepts any of these JSON shapes:
- a checked-in batch example containing
firewall_ctx - a firewall context containing
_raw_input - a raw host payload, which the runner wraps automatically
sle-trajectory-demo --no-llm `
--input examples/e2e_cases/case_02_infection_overlap.json `
--out-dir build/e2e/infection_overlapThe command exits non-zero if the final report fails its safety check. Do not use real patient identifiers or protected health information in examples, issues, commits, or shared audit bundles.
Eight synthetic scenarios cover renal flare, infection overlap, severe organ threat, serologic activity, remission, limited evidence, and the pediatric boundary.
sle-trajectory-batch --no-llm --strict--strict exits non-zero when an expected state differs or a report safety
check fails. Results are written to build/e2e_batch/sle_cases/, including a
CSV and Markdown summary.
python -m pip install -e ".[demo]"
streamlit run apps/streamlit_demo.pyThe Streamlit app accepts editable host-style JSON, exposes every pipeline stage in separate tabs, reports the final safety status, and downloads the current audit trail as a ZIP file. Live LLM calls are off by default. When enabled, endpoint, model, and password-masked API-key fields can be supplied for the current Streamlit session; the API key is excluded from audit outputs.
Editable installs are recommended because scripts and resources remain linked to the repository checkout.
| Use case | Command |
|---|---|
| Core engine, tests, and CLI Demo | python -m pip install -e . |
| Streamlit Demo | python -m pip install -e ".[demo]" |
| ML training/evaluation | python -m pip install -e ".[ml]" |
| Local guideline RAG | python -m pip install -e ".[rag]" |
| Multiple extras | python -m pip install -e ".[demo,ml]" |
The equivalent standalone requirement files are requirements.txt,
requirements-demo.txt, requirements-ml.txt, and requirements-rag.txt.
Each optional requirements file includes the core dependencies, so one install
command is sufficient.
Installed CLI commands:
sle-trajectory Evaluate a normalized longitudinal case JSON.
sle-trajectory-demo Run one auditable end-to-end host-report case.
sle-trajectory-batch Run and summarize a directory of Demo cases.
The standalone state engine itself uses only the Python standard library:
sle-trajectory examples/renal_flare_case.input.json `
--out build/renal_flare_case.state.jsonThe bounded states are:
insufficient_evidence
treatment_response_or_remission
remission_or_low_activity
serologic_activity
non_renal_flare_likely
renal_flare_suspected
severe_organ_threatening_flare
infection_mimic_or_overlap
Live rendering uses an OpenAI-compatible chat-completions endpoint. No endpoint or credential is hardcoded.
$env:LLM_BASE_URL = "http://localhost:8000/v1"
$env:LLM_MODEL_NAME = "local-model"
$env:LLM_API_KEY = "EMPTY"
sle-trajectory-demoIf the endpoint fails, the Demo records the error in
09_llm_call_status.json and uses the bounded fallback report. The report is
still passed through the same safety sanitizer and checker.
For the optional rule-engine gateway integration, use
SLE_LLM_GATEWAY_BASE_URL and SLE_LLM_GATEWAY_API_KEY. RAG remains disabled
unless explicitly configured; see docs/sle_rag.md.
| Layer | Model family | Population/data | Status and limitation |
|---|---|---|---|
| Rule trajectory engine | Deterministic rules | Structured SLE facts and trends | Stable backbone; implemented |
| Structured trajectory overlay | Logistic Regression, XGBoost | Weakly labeled PubMed case reports | Engineering baseline; case-report bias |
| Binary risk overlays | Logistic Regression | Structured fact features | Engineering review signals only |
| Synthetic transition models | Logistic Regression | Simulated longitudinal events | Demonstrates transition plumbing only |
| Pediatric flare reference | Logistic Regression with feature selection | GSE65391 pediatric/pediatric-onset SLE | Not an adult or renal-trajectory model |
Large model files are intentionally not committed. A fresh clone always runs the deterministic backbone; model-dependent probability fields appear only when compatible local artifacts are available. Model routing remains visible so an unavailable or ineligible overlay is auditable.
The published engineering snapshot reported the following smoke-test results. These are not clinical validation:
| Evaluation | Metric | Result | Main caveat |
|---|---|---|---|
| Held-out PubMed trajectory, XGBoost | Accuracy / weighted F1 | 0.80 / 0.801 | 300 weak/semi-curated train cases and 50 biased case reports |
| Held-out PubMed trajectory, Logistic Regression | Accuracy / weighted F1 | 0.70 / 0.709 | Weak labels and small held-out set |
| Synthetic renal transition | AUROC / AUPRC / Brier | 0.677 / 0.300 / 0.248 | Simulated data only |
| Synthetic infection transition | AUROC / AUPRC / Brier | 0.515 / 0.159 / 0.240 | Intentionally weak synthetic signal |
| Synthetic severe transition | AUROC / AUPRC / Brier | 0.757 / 0.109 / 0.219 | Rare synthetic positive class |
| GSE65391 pediatric pre-flare | AUROC / AUPRC / Brier | 0.556 / 0.179 / 0.267 | Pediatric general flare, not adult renal trajectory |
Training commands, provenance, and interpretation limits are documented in docs/training.md, docs/data_sources.md, and docs/ml_public_data_pipeline.md.
sle-trajectory-reasoning/
|-- apps/ # Streamlit visual Demo
|-- configs/ # trajectory thresholds and state definitions
|-- docs/ # design, installation, data, training, and RAG notes
|-- examples/ # synthetic inputs and the eight-case matrix
|-- prompts/ # bounded report-rendering prompt
|-- schemas/ # JSON contracts
|-- scripts/ # E2E, training, PubMed, and RAG commands
|-- src/ # engines, adapters, inference, and output contracts
|-- tests/ # stdlib unittest suite
`-- vendor/sle_panel/ # minimal host-panel integration snapshot
Generated outputs, virtual environments, downloaded data, local models, RAG
indexes, and guideline text are excluded by .gitignore.
Run the same offline checks used by CI:
python -m unittest discover -s tests -v
python scripts/check_text_encoding.py --root .
sle-trajectory-demo --no-llm --out-dir build/ci/e2e
sle-trajectory-batch --no-llm --strict --out-dir build/ci/batchCI tests Python 3.10 and 3.12, never calls a live LLM, and uploads the generated audit artifacts from the Python 3.12 job.
The report layer must not:
- state a final diagnosis from model output alone
- claim infection has been excluded from limited evidence
- prescribe medication, dosing, duration, or treatment changes
- invent dates, laboratory values, pathology, culture, or imaging findings
- present PubMed, pediatric, or synthetic probabilities as clinically validated
Do not commit protected health information, secrets, private datasets, large artifacts, or licensed guideline full text. Report security or privacy issues privately as described in .github/SECURITY.md.
Bug reports and pull requests are welcome. Keep behavior changes auditable, add tests proportional to the safety impact, and document population/data limitations. See CONTRIBUTING.md before opening a pull request.
GitHub can generate BibTeX and other citation formats from CITATION.cff. The preferred software citation is:
xhu014183-cmd (2026). SLE Trajectory Reasoning (Version 0.1.0) [Computer software].
https://github.com/xhu014183-cmd/SLE-Trajectory
When reporting model results, also cite the underlying datasets and methods listed in docs/data_sources.md; citing this software does not replace source-dataset attribution.
Repository-authored code and documentation are licensed under the Apache License 2.0. External datasets, downloaded models, guideline texts, and third-party services retain their own terms and are not relicensed by this repository.