Structured, AI-readable knowledge bases for fluorescence microscopes.

Quick Start • What Is This • Structure • Build Your Own • Contributing

---

What Is This

ScopeAId is a schema and toolkit for turning microscope documentation into structured YAML knowledge bases that AI systems can reliably query. Instead of feeding an LLM a 40-page manual and hoping for the best, you give it a compact, cross-referenced, machine-readable representation of everything about your instrument: hardware specs, calibrations, procedures, safety rules, troubleshooting trees, experiment recipes, and performance limits.

The result: an AI that can answer "Can I image synaptic vesicles with STED on this system?", walk a user through troubleshoots "suddenly my confocal image is black", or confirm whether a proposed experiment is within the system's capabilities -- all grounded in verified, structured facts rather than hallucinated guesses.

Covers the full fluorescence microscopy landscape:

Camera-based	Point-scanning	Super-resolution
Widefield	Confocal (CLSM)	STED / RESOLFT
TIRF	Multiphoton (2P, 3P)	SIM
Spinning-disk	FLIM	SMLM (PALM/STORM/PAINT)
Light-sheet (SPIM)	FCS / FCCS	MINFLUX

Quick Start

Use an existing Knowledge Base(KB) (e.g., the included etSTED example):

git clone https://github.com/LREIN663/ScopeAId.git
cd ScopeAId/setups/etsted_knowledge_base

Give the _index.yaml and relevant files to your AI of choice as context, then ask questions about the microscope.

Build a KB for your own microscope:

1. Copy the template folder
2. Gather your source documents (papers, protocols, config files, calibration data)
3. Paste the generation prompt into an AI session
4. Use the schemas as reference while generating each file
5. Generate files one at a time, review each, validate the YAML
6. Test by asking the AI questions with only the KB as context

See the usage guide for the full step-by-step walkthrough.

KB File Overview

File	Purpose	Key content
_index.yaml	Entry point for AI	System summary, file map, example queries
hardware.yaml	What's on the optical table	Every component: lasers, detectors, filters, stages, DAQ
concepts.yaml	How the modalities work	Physics + system-specific implementation
calibrations.yaml	Mapping setpoints to reality	Power curves, position conversions, with source data links
software_config.yaml	Control software internals	Device wiring, DAQ channels, presets, what's safe to change
procedures.yaml	How to operate	Step-by-step: startup, shutdown, alignment, diagnostics
safety.yaml	How to not get hurt	Laser classes, PPE, emergency procedures, checklists
troubleshooting.yaml	What to do when it breaks	Symptom → ranked causes → step-by-step fixes → escalation
limits.yaml	What the system can and can't do	Resolution, FOV, speeds, power limits, stage travel
recipes.yaml	How to run experiments	Complete configs: sample, lasers, detection, analysis, pitfalls
faq.yaml	Quick answers	10-20 common questions with canonical answers

Documentation

Document	What it covers
Microscope Families	Classification reference — identify your system's architecture and modalities
Schemas	File structure and complete YAML schemas for every KB file
Generation Prompt	Ready-to-paste AI prompt for generating a KB from source docs
Usage Guide	Step-by-step walkthrough + tips for multi-system facilities
System Prompt	Ready-to-paste prompt that constrains an LLM to reason only from the KB
Google Form Script	Apps Script that auto-generates a Google Form for collecting system data

Why YAML?

YAML is hierarchical, human-readable, and trivially parseable by any programming language or AI system. Compared to alternatives:

• vs. free-text manuals: Structured fields eliminate ambiguity. An AI doesn't have to figure out that "the 775" means "the 775 nm pulsed STED depletion laser controlled via AOM."
• vs. JSON: YAML supports comments (critical for calibration caveats and safety notes) and is easier to read/edit by hand.
• vs. databases: No infrastructure needed. The KB is a folder of text files that lives in git, diffs cleanly, and can be attached to any AI conversation.

Building a KB for Your Microscope

The complete guide is in the docs/ folder. The short version:

1. Classify your system: camera-based vs. scanning, diffraction-limited vs. super-resolution, which modality families. See microscope-families.md.
2. Gather sources: publications, protocols, config files, calibration CSVs, manuals, tribal knowledge.
3. Use the generation prompt: paste the generation prompt into an AI session, attach your docs, generate one file at a time.
4. Use only the relevant conditional sections: a widefield system skips STED beam shaping; a STORM system skips scan settings but adds buffer chemistry and localization parameters. See schemas.md.
5. Review, validate, test: check YAML syntax, spot-check specs against hardware, smoke-test with questions.

Validating Your KB

# Check all YAML files parse correctly
python3 -c "
import yaml, os, sys
errors = 0
for f in sorted(os.listdir('.')):
    if f.endswith('.yaml'):
        try:
            yaml.safe_load(open(f))
            print(f'  OK  {f}')
        except Exception as e:
            print(f'FAIL  {f} -- {e}')
            errors += 1
print(f'\n{errors} errors.' if errors else '\nAll files valid.')
"

Contributing

Contributions welcome — especially:

• New system KBs: Add your microscope's knowledge base under setups/
• Schema improvements: Better conditional sections, new modality support
• Tooling: Scripts for calibration ingestion, YAML validation, cross-reference checking
• Shared safety/concepts libraries: Reusable boilerplate for common microscopy families

License

MIT