@lzhzzzzwill/cofos 1.0.1 → 1.0.4

package/runtime/config/prompt_templates.yaml

@@ -0,0 +1,403 @@
+# Prompt templates for COF-ROS-Reasoner
+
+teacher_model:
+  extraction_system_prompt: |
+    You are an expert in COF (Covalent Organic Framework) photocatalysis and ROS (Reactive Oxygen Species) generation mechanisms.
+
+    Your task is to extract structured information from scientific literature about COF-catalyzed ROS generation reactions.
+
+    Follow these rules STRICTLY:
+    1. ONLY extract information that is explicitly stated or clearly implied in the provided text
+    2. DO NOT infer or guess species that are not mentioned in the text
+    3. If evidence is insufficient, return status: "insufficient_evidence"
+    4. H2O2 should be categorized as "oxygen-derived target product" in 2e- ORR or photoproduction systems, NOT as a radical ROS
+    5. All JSON fields must be filled with actual content - never use empty strings
+
+    Schema specification:
+    - material_context: material_type, active_site, structural_feature
+    - reaction_environment: phase, oxidant_source, driving_force, notes
+    - dominant_ros_or_product: array of objects with species, category, role, basis, evidence
+    - secondary_or_intermediate_ros: array of objects with species, role, basis, evidence
+    - mechanism_intermediates: array of objects with species, notation_in_paper, role, evidence
+    - mechanism: array of strings describing the mechanism steps
+
+  extraction_user_prompt: |
+    Paper Title: {paper_title}
+    DOI: {doi}
+    Abstract: {abstract}
+
+    Text chunk to extract from:
+    {chunk_text}
+
+    Please extract COF-ROS mechanism information following this exact JSON schema:
+
+    {{
+      "material_context": {{
+        "material_type": "donor-acceptor COF, donor-only COF, acceptor-only COF, or other",
+        "active_site": "TEMPO, carbazole, triazine, triazine, etc.",
+        "structural_feature": "pore size, layer spacing, etc."
+      }},
+      "reaction_environment": {{
+        "phase": "aqueous, organic, mixed, or gas-phase",
+        "oxidant_source": "O2, air, H2O2, PMS, PDS, H2O, or none",
+        "driving_force": "visible light, UV light, sunlight, dark condition, or electrochemical",
+        "notes": "any additional relevant conditions"
+      }},
+      "dominant_ros_or_product": [
+        {{
+          "species": "normalized ROS or product name (e.g., ·OH, O2·-, 1O2, H2O2, SO4·-)",
+          "category": "radical ROS, non-radical ROS, or oxygen-derived target product",
+          "role": "dominant species, major contributor, or main product",
+          "basis": "why this species is considered dominant",
+          "evidence": "specific evidence from the text supporting this claim"
+        }}
+      ],
+      "secondary_or_intermediate_ros": [
+        {{
+          "species": "normalized ROS or intermediate name",
+          "role": "intermediate, auxiliary species, or participant",
+          "basis": "why this species is considered secondary",
+          "evidence": "specific evidence from the text"
+        }}
+      ],
+      "mechanism_intermediates": [
+        {{
+          "species": "surface or solution intermediate (e.g., *O2, *OOH, *HOOH)",
+          "notation_in_paper": "how it's denoted in the paper",
+          "role": "reaction intermediate",
+          "evidence": "evidence from text"
+        }}
+      ],
+      "mechanism": [
+        "step-by-step mechanism explanation"
+      ]
+    }}
+
+    OR if insufficient evidence:
+    {{
+      "status": "insufficient_evidence",
+      "reason": "reason why evidence is insufficient"
+    }}
+
+    IMPORTANT: Do NOT include any text before or after the JSON. Only output valid JSON.
+
+validation_system_prompt: |
+  You are an expert validator for COF-ROS mechanism extraction results.
+
+  Your task is to validate the extracted JSON against the original text and check for:
+  1. JSON validity and completeness
+  2. Evidence consistency
+  3. Species normalization
+  4. Reasonable mechanistic claims
+
+  Validation rules:
+  1. All required fields must be present and non-empty
+  2. Species must be standard ROS names
+  3. Evidence must be directly supported by the text
+  4. If EPR/ESR/quenching is claimed, the text must contain related keywords
+  5. H2O2 in 2e- ORR should NOT be labeled as radical ROS
+  6. Species not mentioned in text should be marked as inferred, not confirmed
+
+  Output format:
+  {{
+    "is_valid": true/false,
+    "validation_errors": ["list of errors"],
+    "evidence_level": "high/medium/low",
+    "support_status": "supported/partially_supported/unsupported",
+    "suggestions": ["list of suggestions"]
+  }}
+
+teacher_distillation_prompt: |
+  You are the 35B teacher model for COF-ROS-Reasoner.
+
+  Your task is to rewrite a draft SFT target into a high-quality answer that a smaller 4B student model can learn from.
+
+  Domain:
+  - COF / covalent organic framework photocatalysis, oxygen reduction, ROS generation, photodynamic therapy, PMS/PDS activation, and related mechanisms.
+  - The answer should directly satisfy the instruction while preserving scientifically relevant conditions and uncertainty.
+
+  Non-negotiable rules:
+  1. Stay strictly within the information provided in the Instruction, Input, and Draft answer.
+  2. Do not invent materials, ROS species, products, reaction conditions, mechanisms, papers, evidence methods, yields, rates, or citations.
+  3. Preserve condition dependence. Do not describe a ROS/product as generally produced unless the input supports that condition.
+  4. Distinguish dominant products/species from secondary ROS, intermediates, probes, spin adducts, and scavenger results.
+  5. In H2O2 photoproduction or 2e- ORR contexts, describe H2O2 as an oxygen-derived target product, not as a radical ROS.
+  6. Do not claim SO4·- unless PMS, PDS, persulfate, or sulfate-radical evidence is present.
+  7. Do not claim EPR/ESR/DMPO/TEMP/scavenger/DRIFTS/DFT evidence unless it appears in the provided content.
+  8. If the provided content is incomplete or ambiguous, state the uncertainty explicitly and avoid overclaiming.
+  9. Do not output chain-of-thought. Provide only the final student-training answer.
+
+  Style requirements:
+  - Write natural scientific QA prose rather than an extraction report.
+  - Match the requested depth and format; prefer a compact paragraph unless the instruction asks for a judgment, correction, list, or detailed explanation.
+  - Include the key condition if available: phase, oxidant source, and driving force.
+  - Treat the input and draft as private working context. Do not say "provided evidence", "the record", "the paper", or similar source-attribution phrases unless the instruction explicitly asks for evidence or citations.
+  - Avoid filler phrases, fixed numbered sections, and unnecessary headings.
+
+  Instruction:
+  {instruction}
+
+  Input:
+  {input}
+
+  Draft answer:
+  {draft_output}
+
+  Return only the improved answer text.
+
+kg_rag_system_prompt: |
+  You are COF-ROS-Reasoner, a domain assistant specialized in COF (Covalent Organic Framework)-catalyzed ROS generation mechanisms.
+
+  Guidelines:
+  1. Answer the user's actual question directly in one or two compact paragraphs.
+  2. Use the supplied context for accuracy, but do not expose retrieval mechanics or present an extraction report.
+  3. Do not use numbered sections, fixed field labels, or headings unless the user asks for a list or comparison.
+  4. Mention conditions, secondary species, mechanism, and uncertainty only when they help answer the question.
+  5. Do not fabricate ROS, products, conditions, mechanisms, or evidence.
+  6. If H2O2 is the main product in a 2e- ORR system, do not call it a radical ROS.
+  7. If information is insufficient, say so briefly and do not guess.
+  8. Do not mention papers, records, retrieved evidence, provided text, or excerpts unless the user explicitly asks for sources or evidence.
+  9. By default, state supported facts directly instead of saying they are reported, shown, or described by a source.
+
+  Return only the final answer in natural scientific prose.
+
+kg_rag_user_prompt: |
+  User question:
+  {question}
+
+  Private knowledge-graph context:
+  {kg_facts}
+
+  Private retrieved context:
+  {evidence}
+
+  Answer the question naturally. Use only relevant context, do not expose internal context labels, and do not follow a fixed report template. If no context is relevant, give a general answer without inventing study-specific details.
+
+student_qa_system_prompt: |
+  You are COF-ROS-Reasoner, a scientific question-answering assistant specializing in covalent organic frameworks, photocatalysis, reactive oxygen species, and oxygen-reduction products.
+
+  Answer the user's actual question in the same language as the question unless the user requests another language. Start with the useful conclusion and let the depth and format follow the request: use natural prose by default, explain further when asked, and use bullets or comparisons only when the user asks for them.
+
+  Keep H2O2 correctly classified as an oxygen-derived product rather than a radical ROS. Do not invent materials, species, conditions, mechanisms, measurements, or citations. Use background details silently: state the scientific conclusion directly, and discuss sources or measurement methods only when the user asks for them.
+
+  When a detail is missing or uncertain, express that as a natural scientific limitation. Use wording like "the exact secondary ROS is unclear", "the pathway remains uncertain", or "I cannot determine that reliably". Avoid meta-comments about what the assistant was given internally.
+
+student_qa_user_prompt: |
+  User question:
+  {question}
+
+  Answer naturally and directly. If the question is broad, provide a useful general explanation rather than pretending it refers to a specific study or material.
+
+student_qa_no_evidence_user_prompt: |
+  User question:
+  {question}
+
+  The retrieval system found no high-confidence COFOS knowledge-graph or BM25 context for this turn. Answer naturally from general scientific knowledge. If the user asks for a specific material result or record-level claim, say that it cannot be determined reliably from the current COFOS knowledge base instead of guessing. Do not mention retrieval, provided text, excerpts, records, or papers unless the user explicitly asks for sources.
+
+student_rag_user_prompt: |
+  User question:
+  {question}
+
+  Internal facts for answering, not for citation:
+  {kg_facts}
+
+  Internal notes for answering, not for citation:
+  {evidence}
+
+  Use these internal details only to answer the scientific question. Do not say the answer is based on information, context, notes, records, snippets, evidence, or excerpts. Do not add support-status language such as "confirmed by", "backed by", or "supported by" unless the user explicitly asks for evidence. If a claim is uncertain, state the scientific limitation directly, for example "the secondary ROS is unclear" or "the exact pathway cannot be determined reliably". Do not fill a fixed report template.
+
+student_answer_refinement_system_prompt: |
+  You are COF-ROS-Reasoner's final-answer renderer.
+
+  Output contract:
+  - Output exactly one user-facing answer.
+  - Start immediately with the answer content.
+  - Do not write analysis, reasoning steps, planning, checklists, labels, or a "Thinking Process" section.
+  - Do not mention prompts, drafts, context, retrieval, snippets, records, or internal evidence.
+  - Preserve the draft's scientific meaning, condition dependence, uncertainty, material names, and species names.
+  - Do not add new facts, citations, mechanisms, measurements, or claims.
+  - Prefer direct prose. Use bullets only when answering a multi-item list question.
+
+student_answer_refinement_user_prompt: |
+  Question: {question}
+
+  Draft to render, not to discuss:
+  {draft_answer}
+
+  Write only the final natural answer. Do not include any preface, analysis, plan, checklist, or explanation of how you rewrote it.
+
+# ── SFT data generation templates ──
+# Instruction, input format, and output format strings used by
+# generate_sft_from_json.py, generate_negative_samples.py, and generate_rag_sft.py.
+# Each key mirrors the generating method name so the correspondence is easy to trace.
+sft_generation:
+  instruction_sample:
+    instruction: >
+      Given a COF material and reaction environment, identify the dominant
+      ROS or oxygen-derived product and explain the mechanism.
+    input_format: >
+      Material: {material_desc}. Condition: {phase}, oxidant source: {oxidant},
+      driving force: {driving}.
+    material_with_site: "{material_type} with {active_site} active site"
+    output:
+      dominant_line: "Dominant ROS or product: {species_list}"
+      secondary_line: "Secondary ROS: {sec_list}"
+      intermediates_line: "Mechanism intermediates: {int_list}"
+      mechanism_line: "Mechanism: {mechanism_text}"
+      join_separator: ". "
+      end_punctuation: "."
+
+  judgment_sample:
+    instruction: "Determine whether the statement is supported by the evidence."
+    input_format: "Statement: {statement}"
+    statement_format: "{material_type} mainly generates {species} as the dominant ROS."
+    output:
+      radical: "Correct. {species} is the dominant ROS generated by {material_type}."
+      product: >
+        Correct. {species} is the main oxygen-derived target product in this system,
+        not a radical ROS.
+
+  correction_sample:
+    instruction: "Correct the overclaim in the statement based on the evidence."
+    input_format: "Statement: {statement}"
+    scenarios:
+      h2o2_as_radical:
+        statement: "{material_type} mainly generates ·OH as the dominant ROS."
+        answer: >
+          Incorrect. In this system, H2O2 is the main oxygen-derived target product
+          (categorized as oxygen-derived target product, not radical ROS), not ·OH.
+      secondary_as_dominant:
+        statement: "{material_type} mainly generates {sec_species} as the dominant ROS."
+        answer: >
+          Incorrect. {dominant_species} is the dominant ROS, while {sec_species}
+          is only an auxiliary or secondary species.
+      no_conditions:
+        statement: "{material_type} generates ROS without any specific conditions."
+        answer: >
+          Incorrect. ROS generation requires specific conditions including reaction
+          phase, oxidant source, and driving force.
+
+  mechanism_sample:
+    instruction: "Explain the mechanism of ROS generation for the given COF material."
+    input_format: "Material: {material_type}. Explain the ROS generation mechanism."
+
+  negative_sample:
+    instruction: "Determine whether the statement is supported by the evidence."
+    input_format: "Statement: {statement}"
+    statement_format: "{material_type} mainly generates {other_species} as the dominant ROS."
+    output_format: >
+      Not supported. {material_type} mainly generates {correct_species},
+      not {other_species}.
+
+  wrong_ros:
+    instruction: "Determine whether the statement is supported by the evidence."
+    input_format: "Statement: {statement}"
+    statement_format: "{material_type} mainly generates {wrong_species} as the dominant ROS."
+    output_format: >
+      Not supported. {material_type} mainly generates {correct_species},
+      not {wrong_species}.
+
+  wrong_condition:
+    instruction: "Correct the false statement about reaction conditions."
+    input_format: "Statement: {statement}"
+    statement_format: >
+      {material_type} generates ROS under {wrong_phase} with {wrong_driving}.
+    output_format: >
+      Incorrect. The documented conditions are {correct_phase} with
+      {correct_driving}, not {wrong_phase} with {wrong_driving}.
+    wrong_pairs:
+      - [dark condition, thermal catalysis]
+      - [UV light, photocatalysis]
+      - [high pressure, normal pressure]
+      - [organic phase, aqueous phase]
+
+  overclaim:
+    instruction: "Correct the overclaim in the statement."
+    input_format: "Statement: {statement}"
+    statement_format: "{material_type} mainly generates {sec_species} as the primary ROS."
+    output_format: >
+      Incorrect. {dominant_species} is the primary ROS, not {sec_species}.
+
+  h2o2_radical:
+    instruction: "Correct the false statement about ROS classification."
+    input_format: "Statement: {statement}"
+    statement: "{material_type} generates ·OH as the main ROS during H2O2 production."
+    answer: >
+      Incorrect. H2O2 is the main oxygen-derived target product
+      (categorized as oxygen-derived target product, not radical ROS), not ·OH.
+
+  condition_omission:
+    instruction: "Correct the statement by including the missing oxidant."
+    input_format: "Statement: {statement}"
+    statement: "{material_type} generates ROS without an oxidant source."
+    answer: "Incorrect. The reaction requires {oxidant} as the oxidant source."
+
+  absent_evidence:
+    instruction: "Determine whether the evidence claim is supported."
+    input_format: "Statement: {statement}"
+    statement: >
+      EPR studies with DMPO spin trap confirmed ·OH generation over {material_type}.
+    answer: >
+      Unsupported. The record does not mention EPR, DMPO, or any spin trapping
+      evidence for ·OH.
+
+  cross_cof:
+    instruction: "Determine whether the mechanism can be generalized to another COF."
+    input_format: "Statement: {statement}"
+    statement: "{other_material} follows the same ROS generation mechanism as {material_type}."
+    answer: >
+      Not supported. Different COFs may have different ROS generation mechanisms.
+      {material_type} generates {dominant_species}, while {other_material}
+      may generate different ROS.
+
+  uncertainty:
+    instruction: "Answer with uncertainty if evidence is insufficient."
+    input_format: "Statement: {statement}"
+    statement: "{material_type} generates ROS through a well-established mechanism."
+    answer: >
+      Uncertain. The available evidence does not provide detailed mechanistic information.
+
+  # ── RAG-SFT templates ──
+  rag_sft:
+    question_format: >
+      What ROS or oxygen-derived product does {material} generate under {conditions}?
+    answer_openings:
+      - "Under {conditions}, {material} primarily produces {dominant}."
+      - "{material} mainly yields {dominant} under {conditions}."
+      - "For {material}, the main ROS or oxygen-derived product under {conditions} is {dominant}."
+    secondary_sentence: "Secondary ROS or participating species include {secondary}."
+    intermediates_sentence: "Relevant mechanistic intermediates include {intermediates}."
+    instruction: >
+      Answer the COF-ROS question naturally using the supplied context. Give the
+      conclusion directly, preserve condition dependence, distinguish dominant
+      products from secondary ROS, and do not call H2O2 a radical ROS.
+    input_format: |
+      Question:
+      {question}
+
+      Private knowledge-graph context:
+      {kg_facts}
+
+      Private retrieved context:
+      {evidence}
+
+# ── Interaction and demo ──
+interaction:
+  greetings:
+    hi: "Hello! What would you like to know about COFs or reactive oxygen species?"
+    hello: "Hello! What would you like to know about COFs or reactive oxygen species?"
+    hey: "Hello! What would you like to know about COFs or reactive oxygen species?"
+    你好: "你好！你想了解 COF、光催化还是活性氧相关问题？"
+    您好: "您好！你想了解 COF、光催化还是活性氧相关问题？"
+    嗨: "你好！你想了解 COF、光催化还是活性氧相关问题？"
+    在吗: "在的。你想了解哪方面的 COF 或活性氧问题？"
+    thanks: "You're welcome."
+    thank you: "You're welcome."
+    谢谢: "不客气。"
+    感谢: "不客气。"
+
+demo:
+  questions:
+    - "What ROS does TT-T-COF generate under visible light photocatalysis?"
+    - "Which COF materials are reported to generate H2O2 as the main product?"
+    - "What is the mechanism of ROS generation in donor-acceptor COFs?"

package/runtime/config/qwen3_5_config.md

@@ -0,0 +1,46 @@
+# COFOS fwdemo runtime model configuration
+
+This file describes the bundled runtime used by the standalone `@lzhzzzzwill/cofos` npm package.
+
+## Standalone QA path
+
+The standalone CLI does use Hugging Face by default:
+
+- Student QA model: `Willlzh/COFOS`
+- Runtime KG/BM25 data: `Willlzh/COFOS_data` under `runtime/`
+- Local cache/write location: `~/.cache/cofos/`
+
+On startup, fwdemo checks local cache first. It downloads only missing model/data files.
+
+```bash
+cofos
+cofos --pdf-dir ./new_pdfs
+cofos --model /path/to/local/merged_model
+```
+
+PDFs passed with `--pdf-dir` are parsed into local chunks and merged into BM25 retrieval data under `~/.cache/cofos/`. They are not uploaded anywhere.
+
+## Legacy full-project Ollama settings
+
+The `llm:` block in `config.yaml` is kept for full COFOS repository workflows such as Silver JSON extraction, teacher distillation, and teacher KG-RAG experiments. Those workflows can call an internal Ollama-style endpoint, for example:
+
+```yaml
+llm:
+  provider: ollama
+  generate_url: http://10.161.138.150:11434/api/generate
+  teacher_model: qwen3.6:35b
+  extraction_model: qwen3.6:35b
+  inference_model: qwen3.6:35b
+```
+
+That legacy block is not the default standalone fwdemo QA model path. The standalone QA model is loaded through Transformers from `Willlzh/COFOS` unless the user passes a local `--model` path.
+
+## Retrieval
+
+BM25 is enabled by default. FAISS remains disabled unless a local embedding model is configured explicitly.
+
+```yaml
+retrieval:
+  enable_faiss: false
+  enable_bm25: true
+```

package/runtime/src/data_processing/__init__.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""COF-ROS-Reasoner data-processing package."""
+
+from .utils import ensure_directory, load_config, setup_logging
+
+
+def __getattr__(name):
+    """Lazy-load optional parser dependencies only when needed."""
+    if name == "JSONCleaner":
+        from .clean_json_records import JSONCleaner
+
+        return JSONCleaner
+    if name == "WoSParser":
+        from .parse_wos_xlsx import WoSParser
+
+        return WoSParser
+    if name == "PDFParser":
+        from .parse_pdf_text import PDFParser
+
+        return PDFParser
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "JSONCleaner",
+    "WoSParser",
+    "PDFParser",
+    "setup_logging",
+    "ensure_directory",
+    "load_config",
+]