---
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

```powershell
python app.py
```

or:

```powershell
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.