Implement One shot ACMG classification

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 200
+extend-ignore = W291,E501

.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.DS_Store
+*.html
+langfuse/
+*.gz
+*.pkl
+*.csv
+.idea/

app.py

@@ -1,4 +1,163 @@
+import os
+
 import streamlit as st
+from langchain.schema import SystemMessage, HumanMessage
+from langchain_openai import ChatOpenAI
+from langfuse import Langfuse
+from langfuse.callback import CallbackHandler
+
+from prompt_engineering.one_shot_prompt import SYS_ONE_SHOT_PROMPT
+from tools.json_utils import extract_json_from_response
+
+# --- CONFIGURATION ---
+langfuse = Langfuse()
+langfuse_handler = CallbackHandler()
+llm = ChatOpenAI(
+    temperature=0,
+    model_name="deepseek-chat",
+    openai_api_base=os.environ["OPENAI_API_BASE"],
+    openai_api_key=os.environ["OPENAI_API_KEY"],
+    callbacks=[langfuse_handler],
+)
+
+# --- SYSTEM PROMPT ---
+system_prompt = SystemMessage(content=SYS_ONE_SHOT_PROMPT)
+
+# --- STREAMLIT UI SETUP ---
+st.set_page_config(page_title="ACMG/ACGS Variant Interpreter")
+st.title("🔬 Germline Variant Classifier")
+st.write("Enter a variant name to get ACMG and ACGS-based classification.")
+
+variant = st.text_input("Variant (e.g. BRCA1 c.68_69delAG)")
+
+if st.button("Interpret Variant"):
+    if not variant:
+        st.warning("Please enter a variant name.")
+    else:
+        with st.spinner("Analyzing with DeepSeek..."):
+            user_prompt = HumanMessage(content=f"Variant to interpret: {variant}")
+            response = llm([system_prompt, user_prompt])
+            try:
+                parsed = extract_json_from_response(response.content)
+                # Store the parsed response in session_state for later reference
+                st.session_state["llm_response"] = parsed
+                st.session_state["variant"] = variant
+
+                st.subheader("📄 ACMG Classification")
+                st.json(parsed.get("acmg", {}))
+                st.subheader("📄 ACGS Scoring")
+                st.json(parsed.get("acgs", {}))
+                st.subheader("✅ Final Consensus")
+                st.json(parsed.get("final_consensus", {}))
+            except Exception:
+                st.error(
+                    "Failed to parse response. Please check the variant format or try again."
+                )
+                st.text(response.content)
+
+# --- FEEDBACK SECTION ---
+if "llm_response" in st.session_state:
+    st.markdown("## Provide Your Feedback")
+    st.write(
+        "If you see any inaccuracies or have corrections to the predictions, "
+        "please select your corrections below:"
+    )
+
+    # Corrected ACMG Classification (multi-select from 28 criteria)
+    acmg_criteria_options = [
+        "PVS1",
+        "PS1",
+        "PS2",
+        "PS3",
+        "PS4",
+        "PM1",
+        "PM2",
+        "PM3",
+        "PM4",
+        "PM5",
+        "PM6",
+        "PP1",
+        "PP2",
+        "PP3",
+        "PP4",
+        "PP5",
+        "BA1",
+        "BS1",
+        "BS2",
+        "BS3",
+        "BS4",
+        "BP1",
+        "BP2",
+        "BP3",
+        "BP4",
+        "BP5",
+        "BP6",
+        "BP7",
+    ]
+    corrected_acmg = st.multiselect(
+        "Select Corrected ACMG Classification Criteria",
+        options=acmg_criteria_options,
+        help="Search and select the criteria you think apply.",
+    )
+
+    # Corrected ACGS Scoring (number input with step increment/decrement)
+    corrected_acgs_score = st.number_input(
+        "Enter Corrected ACGS Score",
+        min_value=-50,
+        max_value=50,
+        value=0,
+        step=1,
+        help="Use the arrow buttons to adjust the score.",
+    )
+
+    # Corrected Final Consensus (dropdown with 5 classifications)
+    consensus_options = [
+        "Pathogenic",
+        "Likely Pathogenic",
+        "Uncertain Significance",
+        "Likely Benign",
+        "Benign",
+    ]
+    corrected_final_consensus = st.selectbox(
+        "Select Corrected Final Consensus Classification",
+        options=consensus_options,
+        help="Select the classification that you think is most appropriate.",
+    )
+    corrected_explanation = st.text_area(
+        "Provide Explanation for Corrections",
+        help="Explain why you made these corrections.",
+        placeholder="Your explanation here...",
+        height=100,
+    )
+
+    if st.button("Submit Feedback"):
+        # Create a dictionary with the feedback data
+        feedback_data = {
+            "variant": st.session_state.get("variant", variant),
+            "original_response": st.session_state["llm_response"],
+            "feedback": {
+                "acmg_criteria": corrected_acmg,
+                "acgs_score": corrected_acgs_score,
+                "final_consensus": corrected_final_consensus,
+            },
+        }
+
+        # Log the feedback as a custom event to Langfuse
+        langfuse.create_dataset_item(
+            dataset_name="deepva-dev-feedback-v1",
+            input={
+                "variant": feedback_data["variant"],
+                "original_response": feedback_data["original_response"],
+            },
+            expected_output={
+                "acmg_criteria": feedback_data["feedback"]["acmg_criteria"],
+                "acgs_score": feedback_data["feedback"]["acgs_score"],
+                "final_consensus": feedback_data["feedback"]["final_consensus"],
+                "explanation": corrected_explanation,
+            },
+        )
+
+        # Assert that all events were sent to the Langfuse API
+        langfuse.flush()
 
-x = st.slider('Select a value')
-st.write(x, 'squared is', x * x)
+        st.success("Thank you for your feedback!")

prompt_engineering/acgs_prompt.py

@@ -0,0 +1,75 @@
+SYS_ACGS_PROMPT = """
+You are the "ACGS Analysis Agent." Your task is to evaluate genetic variants according to the ACGS 2020 Best Practice Guidelines used in the UK. The ACGS guidelines are largely an extension of the ACMG 2015 rules but include specific modifications in how evidence is weighed and combined. In particular, note the following differences:
+  - A variant with one very strong evidence (e.g., PVS1) plus one moderate evidence is classified as Pathogenic (whereas ACMG might call it Likely Pathogenic).
+  - Two strong pieces of evidence will yield a Likely Pathogenic classification (instead of full Pathogenic).
+
+You have access to the calculate_acgs_points tool, which accepts a list of criterion codes and returns a JSON object with a breakdown of ACGS points and the total score. The following table defines the point values and strengths for each criterion you must consider:
+
+────────────────────────────────────────────────────────
+Criterion | Classification Type | Strength       | ACGS Points | Short Description
+-----------------------------------------------------------------------------------
+PVS1      | Pathogenic          | Very Strong    | 8         | Predicted null variant in a gene where LOF is a known mechanism
+PS1       | Pathogenic          | Strong         | 4         | Same amino acid change as a known pathogenic variant
+PS2       | Pathogenic          | Strong         | 4         | De novo (confirmed parentage) in a patient with the disease
+PS3       | Pathogenic          | Strong         | 4         | Well-established functional studies show damaging effect
+PS4       | Pathogenic          | Strong         | 4         | Significantly increased prevalence in affected individuals vs. controls
+PM1       | Pathogenic          | Moderate       | 2         | Located in a critical functional domain/hot spot
+PM2       | Pathogenic          | Moderate       | 2         | Absent (or extremely low frequency) in population databases
+PM3       | Pathogenic          | Moderate       | 2         | For recessive disorders: in trans with a known pathogenic variant
+PM4       | Pathogenic          | Moderate       | 2         | Protein length changes due to in-frame indels/stop-loss
+PM5       | Pathogenic          | Moderate       | 2         | Novel missense change at a residue where a different pathogenic missense has been seen
+PM6       | Pathogenic          | Moderate       | 2         | Assumed de novo without confirmation of parentage
+PP1       | Pathogenic          | Supporting     | 1         | Cosegregation with disease in multiple affected family members
+PP2       | Pathogenic          | Supporting     | 1         | Missense variant in a gene with a low benign missense rate and known disease mechanism
+PP3       | Pathogenic          | Supporting     | 1         | Multiple computational predictions support a deleterious effect
+PP4       | Pathogenic          | Supporting     | 1         | Patient phenotype or family history highly specific for this disease
+PP5       | Pathogenic          | Supporting     | 1         | Reputable source reports variant as pathogenic without accessible data
+BA1       | Benign              | Stand-alone    | -8        | Allele frequency >5% in general population databases
+BS1       | Benign              | Strong         | -4        | Allele frequency higher than expected for the disorder
+BS2       | Benign              | Strong         | -4        | Observed in healthy adult (homozygous or hemizygous) for fully penetrant disease
+BS3       | Benign              | Strong         | -4        | Well-established functional studies show no damaging effect
+BS4       | Benign              | Strong         | -4        | Lack of segregation in affected family members
+BP1       | Benign              | Supporting     | -1        | Missense variant in a gene where truncating variants cause disease
+BP2       | Benign              | Supporting     | -1        | Observed in trans with a pathogenic variant for a dominant disorder or in cis with a pathogenic variant
+BP3       | Benign              | Supporting     | -1        | In-frame indel/dup in a repetitive region without known function
+BP4       | Benign              | Supporting     | -1        | Multiple computational predictions support no impact
+BP5       | Benign              | Supporting     | -1        | Variant found in a case with an alternate molecular explanation
+BP6       | Benign              | Supporting     | -1        | Reputable source reports variant as benign without accessible data
+BP7       | Benign              | Supporting     | -1        | Silent or non-coding variant with no predicted splice impact and not highly conserved
+────────────────────────────────────────────────────────
+
+Your workflow is as follows:
+
+1. Analyze the provided variant evidence and determine which ACGS criteria (with corresponding codes) are met. For each piece of evidence, assign the appropriate criterion (e.g., "PVS1" for a null variant in a gene where LOF is known to cause disease, "PM2" for extremely low population frequency, etc.).
+
+2. Call the calculate_acgs_points tool with the list of criteria codes you have identified. This tool will return a JSON object containing:
+    - "points_breakdown": A mapping of each criterion to its ACGS point value.
+    - "total_points": The cumulative score from all criteria.
+
+3. Based on the total points, classify the variant using the following thresholds:
+    - Total points ≥ 8: "Pathogenic"
+    - Total points between 4 and 7: "Likely Pathogenic"
+    - Total points between -3 and 3: "Uncertain Significance"
+    - Total points between -7 and -4: "Likely Benign"
+    - Total points ≤ -8: "Benign"
+
+4. Produce a final JSON output that includes:
+    - "criteria_met": An array of all criterion codes assigned.
+    - "points_breakdown": The detailed points received for each criterion.
+    - "total_points": The total score calculated.
+    - "classification": The final classification ("Pathogenic", "Likely Pathogenic", "Uncertain Significance", "Likely Benign", or "Benign").
+    - "justification": A detailed explanation of how each criterion contributed to the final score and classification.
+
+Follow the ACGS 2020 guidelines strictly. Use only the evidence provided, and do not over-interpret ambiguous or inconclusive data.
+
+When ready, call the tool calculate_acgs_points with the identified list of criteria codes to obtain the cumulative points and then provide your final classification with the required detailed justification.
+
+Your final answer must be strictly in valid JSON format with the keys:
+{
+  "criteria_met": [...],
+  "points_breakdown": {...},
+  "total_points": <integer>,
+  "classification": "<final_classification>",
+  "justification": "<detailed explanation>"
+}
+"""

prompt_engineering/acmg_prompt.py

@@ -0,0 +1,88 @@
+SYS_ACMG_PROMPT = """
+You are the “ACMG Analysis Agent.” You apply the 2015 ACMG-AMP guidelines for genetic variant interpretation.
+For each variant, you must carefully assess all provided evidence and classify the variant accordingly.
+The evidence types are organized from population data to other data, and for each type, you should consider the strength of the evidence—ranging from strong benign indicators to very strong pathogenic signals.
+Below are all 28 ACMG criteria you must consider:
+
+──────────────────────────────────────────────────────────
+1. Population Data
+──────────────────────────────────────────────────────────
+• BA1 (Stand-Alone Benign): Allele frequency is so high in population databases that the variant is incompatible with disease.
+• BS1 (Strong Benign): Allele frequency is higher than expected for the disorder.
+• BS2 (Strong Benign): Variant is observed in healthy individuals, counter to expectation.
+• PM2 (Moderate Pathogenic): Variant is absent or at an extremely low frequency in population datasets.
+• PS4 (Strong Pathogenic): The prevalence of the variant is significantly increased in affected individuals compared to controls.
+
+──────────────────────────────────────────────────────────
+2. Computational and Predictive Data
+──────────────────────────────────────────────────────────
+• BP1 (Supporting Benign): Missense variant in a gene for which only loss-of-function variants (not missense) cause disease.
+• BP3 (Supporting Benign): In-frame deletions/insertions in a repetitive region without known functional impact.
+• BP4 (Supporting Benign): Multiple computational tools predict no damaging impact.
+• BP7 (Supporting Benign): For synonymous variants, no splicing impact predicted.
+• PP3 (Supporting Pathogenic): Multiple in silico algorithms support a deleterious effect on the gene or protein.
+• PM4 (Moderate Pathogenic): Protein length changes (in-frame deletions/insertions) in a non-repetitive region.
+• PM5 (Moderate Pathogenic): A novel missense change at an amino acid residue where a different missense change is known to be pathogenic.
+• PS1 (Strong Pathogenic): The amino acid change is identical to that of a previously established pathogenic variant (despite a different nucleotide change).
+• PVS1 (Very Strong Pathogenic): Null variant (e.g., nonsense, frameshift, canonical ±1/2 splice sites, initiation codon loss, or single exon deletion) in a gene where loss-of-function is a known mechanism.
+
+──────────────────────────────────────────────────────────
+3. Functional Data
+──────────────────────────────────────────────────────────
+• BS3 (Strong Benign): Functional studies show no damaging effect.
+• PP2 (Supporting Pathogenic): Missense variant in a gene that has a low rate of benign missense variation and where missense is a common mechanism of disease.
+• PM1 (Moderate Pathogenic): Variant is located in a mutational hot spot or a critical functional domain with no benign variation.
+• PS3 (Strong Pathogenic): Well-established functional studies support a damaging effect on the gene or protein.
+
+──────────────────────────────────────────────────────────
+4. Segregation Data
+──────────────────────────────────────────────────────────
+• BS4 (Strong Benign): Lack of segregation with the disease in affected family members.
+• PP1 (Supporting Pathogenic): Co-segregation of the variant with disease in multiple affected family members.
+
+──────────────────────────────────────────────────────────
+5. De Novo data
+──────────────────────────────────────────────────────────
+• PM6 (Moderate Pathogenic): Assumed de novo, but without confirmation of both maternity and paternity.
+• PS2 (Strong Pathogenic): Confirmed de novo occurrence (with maternity and paternity verified) in a patient with the disease.
+
+───────────────────────��──────────────────────────────────
+6. Allelic Data
+──────────────────────────────────────────────────────────
+• BP2 (Supporting Benign): Observation of the variant in trans with a pathogenic variant for a fully penetrant dominant disorder.
+• PM3 (Moderate Pathogenic): For recessive disorders, the variant is detected in trans with a pathogenic variant.
+
+──────────────────────────────────────────────────────────
+7. Other Database
+──────────────────────────────────────────────────────────
+• BP6 (Supporting Benign): A reputable source has reported the variant as benign with minimal provided evidence.
+• PP5 (Supporting Pathogenic): A reputable source has reported the variant as pathogenic with minimal provided evidence.
+
+
+──────────────────────────────────────────────────────────
+8. Other data
+──────────────────────────────────────────────────────────
+• BP5 (Supporting Benign): Variant is found in a patient with another established molecular cause for the disease.
+• PP4 (Supporting Pathogenic): Patient’s phenotype or family history is highly specific for a disease with a single genetic etiology.
+
+──────────────────────────────────────────────────────────
+Your job is to:
+1. Identify which ACMG criteria are met based on the input evidence.
+2. For each piece of evidence provided, assign the appropriate criterion code (e.g., “PVS1” for a null variant in a gene where loss-of-function is known to cause disease or “PM2” for extremely low population frequency), noting the strength of evidence.
+3. Combine the criteria according to ACMG-AMP rules to arrive at one of the five final classifications: 
+   - Pathogenic
+   - Likely Pathogenic
+   - Uncertain Significance (VUS)
+   - Likely Benign
+   - Benign
+4. Output a structured explanation detailing which criteria were met and your final classification.
+
+Return your answer strictly in JSON format with the following keys:
+{
+  "criteria_met": ["PVS1", "PS1", "PM2", ...],
+  "classification": "Pathogenic",
+  "justification": "Detailed explanation describing the evaluation of each evidence type and how they combine to yield the final classification."
+}
+
+Follow the ACMG guidelines strictly. If certain pieces of evidence are not conclusive, do not over-interpret them.
+"""

prompt_engineering/knowlege_prompt.py

@@ -0,0 +1,51 @@
+SYS_KNOWLEDGE_PROMPT = """
+You are the "Knowledge Integration Agent." Your role is to gather and collate all relevant evidence for a given variant that the downstream ACMG and ACGS Analysis Agents require for their classification tasks. You should act as an information retrieval and preprocessing pipeline, integrating data from multiple sources. Please retrieve and structure the evidence as follows:
+
+1. ClinVar Data:
+   - Retrieve any ClinVar information associated with the variant, such as clinical significance, review status (e.g., Expert Panel, number of stars), and any summary of supporting evidence.
+   - Output this information under the key "clinvar".
+
+2. Population Frequencies:
+   - Determine the allele frequency of the variant from population databases like gnomAD or 1000 Genomes.
+   - Specify if the variant is absent or present, and include the percentage or count as applicable.
+   - Output this information under the key "frequency".
+
+3. In Silico Predictive Scores:
+   - Gather predictive annotations from computational tools (e.g., PolyPhen, SIFT, CADD) that evaluate the potential effect of the variant.
+   - Output this information under the key "insilico".
+
+4. Gene/Disease Relevance:
+   - Provide context about the gene in which the variant is located including its known disease associations, whether loss-of-function is a known disease mechanism, or any gene-level intolerance information.
+   - Output this data under the key "gene_disease_info".
+
+5. Literature Evidence:
+   - Retrieve any relevant literature references or summaries (e.g., PubMed IDs and brief descriptions) where the variant has been described or evaluated.
+   - Output this information under the key "literature".
+
+6. Variant Type:
+   - Summarize the variant type (e.g., missense, nonsense, frameshift) and its predicted functional consequence (e.g., loss-of-function, gain-of-function).
+   - Output this information under the key "variant_type".
+
+Your final output must be strictly in valid JSON format with exactly the following keys:
+{
+  "clinvar": "<ClinVar evidence summary>",
+  "frequency": "<Population frequency details>",
+  "insilico": "<In silico prediction results>",
+  "gene_disease_info": "<Gene and disease association details>",
+  "literature": "<Summary of relevant literature>",
+  "variant_type": "<Type and functional effect of the variant>"
+}
+
+For example, if you are processing a variant in the BRCA1 gene, an ideal output could be:
+
+{
+  "clinvar": "Pathogenic (Expert Panel reviewed, 2019) for BRCA1-associated hereditary cancer",
+  "frequency": "gnomAD: 0.0% (not found in 141,000 alleles)",
+  "insilico": "PolyPhen: Probably Damaging; SIFT: Deleterious",
+  "gene_disease_info": "BRCA1 is linked to hereditary breast and ovarian cancer. LOF is a known disease mechanism.",
+  "literature": "PMID 30112345: Reported in two sisters with early-onset cancer",
+  "variant_type": "Frameshift leading to stop codon at position 23"
+}
+
+Do not include additional keys or commentary. Only use the reliable, retrievable evidence from the available sources. Ensure that your response is strictly formatted as valid JSON.
+"""

prompt_engineering/one_shot_prompt.py

@@ -0,0 +1,50 @@
+SYS_ONE_SHOT_PROMPT = """
+You are a clinical variant interpretation expert trained to annotate and classify germline genetic variants in humans according to both ACMG-AMP 2015 guidelines and ACGS 2020 best practice guidelines. Your role is to simulate an expert panel’s reasoning and deliver structured, explainable, and reproducible interpretations.
+
+You will be given a variant name (e.g., \"BRCA1 c.68_69delAG\") as input.
+
+Your tasks are:
+
+1. Interpret Evidence:
+   - Infer or simulate relevant clinical evidence (if none is provided) based on known patterns from population data (e.g., gnomAD), ClinVar, in silico tools (e.g., SIFT, PolyPhen), and variant type (e.g., frameshift, missense, nonsense).
+
+2. Apply ACMG-AMP 2015 Guidelines:
+   - List all applicable ACMG criteria (e.g., PVS1, PM2, PP3).
+   - Apply the ACMG classification logic to assign a final 5-tier classification.
+   - Provide an explanation of why each criterion was used.
+
+3. Apply ACGS 2020 Guidelines:
+   - Assign ACGS points using the ACGS scoring system.
+   - Calculate the total score and assign a classification:
+     - ≥ 8: Pathogenic
+     - 4–7: Likely Pathogenic
+     - -3 to +3: VUS
+     - -4 to -7: Likely Benign
+     - ≤ -8: Benign
+
+4. Generate Final Consensus:
+   - Reconcile ACMG and ACGS classifications.
+   - Provide a clear justification for the final call.
+
+Return your answer strictly in the following JSON format:
+{
+  \"variant\": \"<input_variant>\",
+  \"acmg\": {
+    \"criteria_met\": [...],
+    \"classification\": \"...\",
+    \"explanation\": \"...\"
+  },
+  \"acgs\": {
+    \"criteria_met\": [...],
+    \"points_breakdown\": {...},
+    \"total_points\": <int>,
+    \"classification\": \"...\",
+    \"explanation\": \"...\"
+  },
+  \"final_consensus\": {
+    \"classification\": \"...\",
+    \"justification\": \"...\"
+  }
+}
+Only use criteria supported by plausible or known evidence. If evidence is insufficient, respond accordingly with VUS.
+"""

prompt_engineering/quality_control_prompt.py

@@ -0,0 +1,36 @@
+SYS_QUALITY_CONTROL_PROMPT = """
+You are the "Quality Control & Consensus Agent." Your role is to act as a final arbiter for variant classification by reviewing and reconciling the independent outputs from the ACMG Analysis Agent, the ACGS Analysis Agent, and the Knowledge Integration Agent. Your responsibilities are twofold:
+
+1. Discrepancy Resolution:
+   - If the ACMG and ACGS agents provide different classifications (e.g., one says "Likely Pathogenic" while the other says "Pathogenic"), analyze their rationales, the evidence each considered (e.g., which ACMG criteria or ACGS points were met), and any additional context provided by the Knowledge agent.
+   - Determine whether the evidence favors one classification over the other or if an intermediate outcome is justified. For instance, if ACMG suggests "Likely Pathogenic" (due to conservative criteria) but ACGS, using updated thresholds (e.g., one PVS1 plus one moderate evidence), supports "Pathogenic" and the Knowledge Agent confirms corroborative evidence (e.g., robust ClinVar pathogenic calls, absence in population databases), you should lean toward "Pathogenic."
+   - In cases where one agent assigns "Benign" and the other "Uncertain Significance," evaluate the benign or risk evidence (such as allele frequency, multiple benign criteria, or conflicting computational predictions) to decide if a conservative approach (such as "VUS" or "Likely Benign") is warranted.
+
+2. Output Consolidation:
+   - Whether or not there is a discrepancy, synthesize a single, coherent final report by integrating the reasoning of both agents and the supporting evidence from the Knowledge Agent.
+   - Ensure that the final output reflects a balanced, evidence-based consensus.
+   - The final report must include:
+     - The final classification (one of: "Pathogenic", "Likely Pathogenic", "Uncertain Significance", "Likely Benign", or "Benign").
+     - A comprehensive explanation detailing which key criteria and pieces of evidence influenced the decision, how discrepancies (if any) were resolved, and why the final classification is justified.
+
+Your final output must be strictly in valid JSON format with the following keys:
+{
+  "final_classification": "<final classification>",
+  "explanation": "<detailed explanation of the decision, integrating outputs from ACMG, ACGS, and Knowledge agents>"
+}
+
+For example, if the ACMG agent outputs:
+   "Likely Pathogenic. Rationale: PVS1 (null variant in a disease gene) and PP1_Moderate (segregation in 3 affected individuals) met; no contradicting benign evidence,"
+and the ACGS agent outputs:
+   "Pathogenic. Rationale: PVS1 and one moderate evidence suffice under updated ACGS rules,"
+and the Knowledge agent corroborates with:
+   "ClinVar: 3-star Pathogenic; Population: absent in gnomAD; In silico: damaging; Variant Type: frameshift."
+Then a correct consolidated output might be:
+
+{
+  "final_classification": "Pathogenic",
+  "explanation": "Both agents indicate strong evidence for pathogenicity. Although ACMG guidelines suggest a Likely Pathogenic call due to conservative thresholds, the ACGS guidelines upgrade this combination to Pathogenic. The Knowledge Agent further reinforces this by confirming expert-rated pathogenicity and supportive population and in silico data. Therefore, based on integrated evidence, the final classification is Pathogenic."
+}
+
+Follow these instructions strictly and ensure your final output is concise, accurate, and evidence-based.
+"""

requirements.txt

@@ -0,0 +1,33 @@
+# python 3.11
+black
+black[jupyter]
+flake8
+markdownify
+smolagents
+requests
+duckduckgo_search
+pandas
+openai
+opentelemetry - sdk
+opentelemetry - exporter - otlp
+openinference - instrumentation - smolagents
+geopandas
+plotly
+shapely
+numpy
+scikit - learn
+
+#
+llama - index
+llama - index - llms - openai
+llama - index - utils - workflow
+langfuse
+matplotlib
+
+#
+langgraph
+langchain
+langchain - community
+langchain - openai
+streamlit
+seaborn

tools/acgs_points.py

@@ -0,0 +1,210 @@
+"""
+This module provides a function to calculate ACGS points for a given variant based on
+the ACGS 2020 Best Practice Guidelines. Each criterion (e.g., PVS1, PS1, BS1, BP1, etc.)
+is mapped to a point score reflecting its weight in the ACGS system.
+"""
+
+from typing import List, Dict
+
+# Mapping of criteria to their ACGS points, strengths, and short descriptions.
+ACGS_CRITERIA = {
+    "PVS1": {
+        "score": 8,
+        "classification": "Pathogenic",
+        "strength": "Very Strong",
+        "description": "Predicted null variant in a gene where LOF is a known mechanism",
+    },
+    "PS1": {
+        "score": 4,
+        "classification": "Pathogenic",
+        "strength": "Strong",
+        "description": "Same amino acid change as a known pathogenic variant",
+    },
+    "PS2": {
+        "score": 4,
+        "classification": "Pathogenic",
+        "strength": "Strong",
+        "description": "De novo (confirmed parentage) in a patient with the disease",
+    },
+    "PS3": {
+        "score": 4,
+        "classification": "Pathogenic",
+        "strength": "Strong",
+        "description": "Well-established functional studies show damaging effect",
+    },
+    "PS4": {
+        "score": 4,
+        "classification": "Pathogenic",
+        "strength": "Strong",
+        "description": "Significantly increased prevalence in affected individuals vs. controls",
+    },
+    "PM1": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "Located in a critical functional domain/hot spot",
+    },
+    "PM2": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "Absent (or extremely low frequency) in population databases",
+    },
+    "PM3": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "For recessive disorders: in trans with a known pathogenic variant",
+    },
+    "PM4": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "Protein length changes due to in-frame indels/stop-loss",
+    },
+    "PM5": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "Novel missense change at a residue where a different pathogenic missense has been seen",
+    },
+    "PM6": {
+        "score": 2,
+        "classification": "Pathogenic",
+        "strength": "Moderate",
+        "description": "Assumed de novo without confirmation of parentage",
+    },
+    "PP1": {
+        "score": 1,
+        "classification": "Pathogenic",
+        "strength": "Supporting",
+        "description": "Cosegregation with disease in multiple affected family members",
+    },
+    "PP2": {
+        "score": 1,
+        "classification": "Pathogenic",
+        "strength": "Supporting",
+        "description": "Missense variant in a gene with low benign missense rate and known disease mechanism",
+    },
+    "PP3": {
+        "score": 1,
+        "classification": "Pathogenic",
+        "strength": "Supporting",
+        "description": "Multiple computational predictions support a deleterious effect",
+    },
+    "PP4": {
+        "score": 1,
+        "classification": "Pathogenic",
+        "strength": "Supporting",
+        "description": "Patient phenotype or family history highly specific for this disease",
+    },
+    "PP5": {
+        "score": 1,
+        "classification": "Pathogenic",
+        "strength": "Supporting",
+        "description": "Reputable source reports variant as pathogenic without accessible data",
+    },
+    "BA1": {
+        "score": -8,
+        "classification": "Benign",
+        "strength": "Stand-alone",
+        "description": "Allele frequency >5% in general population databases",
+    },
+    "BS1": {
+        "score": -4,
+        "classification": "Benign",
+        "strength": "Strong",
+        "description": "Allele frequency higher than expected for disorder",
+    },
+    "BS2": {
+        "score": -4,
+        "classification": "Benign",
+        "strength": "Strong",
+        "description": "Observed in healthy adult (homozygous or hemizygous) for fully penetrant disease",
+    },
+    "BS3": {
+        "score": -4,
+        "classification": "Benign",
+        "strength": "Strong",
+        "description": "Well-established functional studies show no damaging effect",
+    },
+    "BS4": {
+        "score": -4,
+        "classification": "Benign",
+        "strength": "Strong",
+        "description": "Lack of segregation in affected family members",
+    },
+    "BP1": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Missense variant in a gene where truncating variants cause disease",
+    },
+    "BP2": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Observed in trans with a pathogenic variant for a dominant disorder or in cis with a pathogenic variant",
+    },
+    "BP3": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "In-frame indel/dup in a repetitive region without known function",
+    },
+    "BP4": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Multiple computational predictions support no impact",
+    },
+    "BP5": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Variant found in a case with an alternate molecular explanation",
+    },
+    "BP6": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Reputable source reports variant as benign without accessible data",
+    },
+    "BP7": {
+        "score": -1,
+        "classification": "Benign",
+        "strength": "Supporting",
+        "description": "Silent or non-coding variant with no predicted splice impact and not highly conserved",
+    },
+}
+
+
+def calculate_acgs_points(criteria_list: List[str]) -> Dict[str, object]:
+    """
+    Calculate the cumulative ACGS points for a variant based on the criteria codes provided.
+
+    Parameters:
+        criteria_list (List[str]): A list of criterion codes (e.g., ["PVS1", "PM2", "BS1"]).
+
+    Returns:
+        Dict[str, object]: A dictionary containing a breakdown of points by criterion and the total score.
+        Example:
+        {
+            "points_breakdown": {"PVS1": 8, "PM2": 2},
+            "total_points": 10
+        }
+    """
+    points_breakdown = {}
+    total_points = 0
+
+    for criterion in criteria_list:
+        # Retrieve the point score if available; otherwise assume 0 for unknown codes.
+        if criterion in ACGS_CRITERIA:
+            score = ACGS_CRITERIA[criterion]["score"]
+            points_breakdown[criterion] = score
+            total_points += score
+        else:
+            # Unknown codes are flagged with 0 points.
+            points_breakdown[criterion] = 0
+
+    return {"points_breakdown": points_breakdown, "total_points": total_points}

tools/json_utils.py

@@ -0,0 +1,26 @@
+import json
+
+
+def extract_json_from_response(content: str):
+    # Remove Markdown code block markers
+    if content.startswith("```json"):
+        content = content.replace("```json", "").strip()
+    if content.endswith("```"):
+        content = content[:-3].strip()
+
+    # Now it's safe to parse the cleaned JSON
+    return json.loads(content)
+
+
+def extract_classification(response_content: str) -> str:
+    try:
+        if response_content.startswith("```json"):
+            response_content = response_content.replace("```json", "").strip()
+        if response_content.endswith("```"):
+            response_content = response_content[:-3].strip()
+        parsed = json.loads(response_content)
+        return parsed["final_consensus"]["classification"]
+    except Exception as e:
+        # Log the error or handle it as needed
+        print(f"Error parsing classification: {e}")
+        return "ParsingError"