README.md

metadata

title: TRACER-Net
emoji: 🧪
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 4.44.1
python_version: '3.10'
app_file: run.py
pinned: false
startup_duration_timeout: 30m
preload_from_hub:
  - BAAI/bge-m3

TRACER-Net

TRACER-Net is a Gradio application for pigment spectral recognition, CRN pathway tracing, and evidence-backed mural material analysis.

Run

python app.py

or:

python run.py

Demo Examples

Both analysis tabs ship with clickable examples and an Instructions accordion, so the app can be tried without preparing any data.

• Spectral Identification: four modalities (Raman, ATR-FTIR, XRD, FORS) measured on the same specimen, under examples/. Click one row of Demo spectra and press Upload for a single-spectrum run, or press Load 4-modality demo set to stage all four for the multimodal fusion run.
• Pathway Tracing: example queries such as p-As₄S₄, As₂O₃, PbO₂, HgS. The first one continues the spectral demo above.

See examples/README.md for file formats, expected columns, and what each example demonstrates.

Matching Metric

Spectral Identification matches on full-spectrum cosine similarity by default, a pragmatic implementation choice for the present normalized spectral dataset rather than evidence of universal superiority. Matching configuration in that tab also offers Pearson correlation, which performs closely, is mean-centred and therefore insensitive to an additive baseline offset, and may be preferable under partial spectral-region loss. Negative correlation is reported as 0, so both metrics stay on the same 0-100% scale. The selected metric applies to every staged file, is named in the on-screen report, and is recorded as metadata.similarity_metric in the saved JSON report under reports/.

Main Files

• app.py: Gradio UI wiring and application callbacks.
• search_subgraph.py: CRN tracing and pathway visualization.
• spectral_recognition.py: spectral database loading, preprocessing, matching, and reporting.
• rag_module.py: retrieval and generated pathway interpretation.
• mural_copilot.py: chat/copilot response orchestration.
• tracernet/: shared configuration, loaders, and utilities.

Useful Environment Variables

• PATHWAY_LAYOUT_STYLE: pathway-figure layout. Default: reference, a compact white-background CRN matching the original application style. Use layered for the labelled column view or legacy for the old renderer.
• PATHWAY_VISIBLE_NODES: fixed total node budget for the reference renderer. Default: 15. The selected path is always preserved; remaining places are filled by complete related routes and then nearest CRN nodes. Use 0 for the selected path only or -1 for the full component.
• PATHWAY_CONTEXT_PATHS: maximum related routes used by the optional layered renderer. Default: 8.
• PATHWAY_CONTEXT_NODES: node cap used by the optional layered renderer. Default: 14.
• PATHWAY_STABLE_LAYOUT: legacy-layout option; set to 0 to disable it.
• PATHWAY_SHOW_FIGURES: set to 1 to open rendered pathway images from CLI.
• TRACE_DEBUG: set to 1 to print verbose trace callback state.
• COPILOT_RETRIEVAL_THRESHOLD: minimum normalized retrieval score used by Mural Copilot. Default: 0.38.
• COPILOT_VERIFY_CLAIMS: set to 0 only to disable the second-pass, quote-grounded sentence verification. Default: enabled.
• COPILOT_EXPAND_QUERIES: set to 1 to enable optional LLM query expansion. It is disabled by default to reduce latency and API usage.
• COPILOT_DEBUG: set to 1 to append the underlying error class and message to a failed Mural Copilot reply, so a backend failure can be diagnosed from the chat without opening the Space runtime logs. Off by default.

Hugging Face deployment

Configure DEEPSEEK_API_KEY in Space Settings → Variables and secrets as a secret. Never commit the key, a .env file, or DEEPSEEK_API_KEY.txt to the Space repository. If the language-model backend or evidence service is still starting, Mural Copilot returns a non-fatal availability message; spectral identification and pathway tracing remain usable.