An AI-powered analysis and intelligence system for Bluesky-based data acquisition instruments at the Advanced Photon Source (APS) at Argonne National Laboratory.
Key Scope: bAIt is a separate analysis package that analyzes existing deployments and answers questions about them. It does NOT control any hardware or systems.
This repository uses git submodules to manage multiple related repositories. Each component is maintained in its own repository with proper access controls.
- analyzers/ - Analysis engines for different components
- agents/ - AI agents for specialized analysis tasks
- MCP/ - Model Context Protocol servers for Claude Code integration
- knowledge/ - RAG knowledge system for intelligent querying
- visualization/ - Tools for generating system diagrams and visualizations
- docs/ - bAIt framework documentation
- BITS - Main apsbits package with instrument templates and framework
- apstools - Library of Python tools for Bluesky Framework at APS
- guarneri - Instrument configuration management
- BITS-Starter - Template for creating new instruments
- ophyd-registry - Device registry and management
- 12id-bits - 12-ID beamline deployment
- 16bm-bits - 16-BM beamline deployment
- 28id-bits - 28-ID beamline deployment
- 8id-bits - 8-ID beamline deployment
- 9id_bits - 9-ID beamline deployment
- bluesky-mic - Microscopy beamline deployment
- haven - Haven beamline framework
- polar-bits - Polar beamline deployment
- tomo-bits - Tomography beamline deployment
- usaxs-bits - USAXS beamline deployment
- bluesky_training - Training materials and examples
- eureka_beamline - Eureka beamline utilities
- epics-podman - EPICS container configurations
- Analysis configurations for each beamline
- Points to IOCs, BITS deployments, MEDM screens
- Contains metadata and analysis cache
git clone --recursive https://github.com/your-org/bAIt.git
cd bAIt
python scripts/check-submodule-access.py
pip install -e ./bait_base/git clone https://github.com/your-org/bAIt.git
cd bAIt
python scripts/init-accessible-submodules.py
pip install -e ./bait_base/git clone https://github.com/your-org/bAIt.git
cd bAIt
pip install -e ./bait_base/
# Use bAIt with external repository references only- Submodule Management Guide - Comprehensive guide to working with submodules
- Access Requirements - Repository access requirements and troubleshooting
- Migration Notes - Information about the submodule migration
# Check access to all submodules
python scripts/check-submodule-access.py
# Get detailed troubleshooting help
python scripts/check-submodule-access.py --fix-permissions
# Check only specific category
python scripts/check-submodule-access.py --category bits_base# Initialize only repositories you have access to
python scripts/init-accessible-submodules.py
# Dry run to see what would be initialized
python scripts/init-accessible-submodules.py --dry-run
# Force initialization (ignore access checks)
python scripts/init-accessible-submodules.py --force# Run comprehensive diagnostics
python scripts/diagnose-submodule-issues.py
# Diagnose specific submodule
python scripts/diagnose-submodule-issues.py --submodule bits_base/BITS
# Get detailed fix suggestions
python scripts/diagnose-submodule-issues.py --fix-suggestions# Update all initialized submodules
git submodule update --recursive
# Initialize specific submodule
git submodule update --init bits_base/BITS
# Update to latest commits
git submodule update --remote
# Pull changes in submodule and commit reference
cd bits_base/BITS
git pull origin main
cd ../..
git add bits_base/BITS
git commit -m "Update BITS submodule"- Most BCDA-APS repositories on GitHub
- No special access required
- BCDA-APS organization: Request membership from APS team
- spc-group organization: Request access for Haven repository
- APS GitLab (
git.aps.anl.gov): APS network access + repository permissions - Contact repository owners for access
# Analyze deployment
bait-analyze [deployment-name]
# Interactive query
bait-query [deployment-name]
# Generate visualization
bait-visualize [deployment-name] --type network# Work in specific submodule
cd bits_base/BITS
# Make changes, commit normally
git add .
git commit -m "Add new feature"
git push origin main
# Update main repository with new submodule commit
cd ../..
git add bits_base/BITS
git commit -m "Update BITS submodule to include new feature""fatal: repository not found"
- Repository may be private - request access
- Check repository URL spelling
- Verify GitHub organization membership
"Permission denied (publickey)"
- SSH key not configured or not added to GitHub
- Run:
ssh -T git@github.comto test - Generate key:
ssh-keygen -t ed25519 -C "your_email@example.com"
"Submodule directory is empty"
- Run:
git submodule update --init [path] - Or use:
python scripts/init-accessible-submodules.py
"APS GitLab repositories not accessible"
- Must be on APS network or VPN
- Contact APS IT for repository access
- Some repositories require special permissions
- Run diagnostics:
python scripts/diagnose-submodule-issues.py --fix-suggestions - Check access:
python scripts/check-submodule-access.py --fix-permissions - Contact repository owners for access to specific repositories
- Join GitHub organizations (BCDA-APS, spc-group) as needed
- Fork this repository
- Make changes to
bait_base/core framework - Test with available submodules
- Submit pull request
- Navigate to specific submodule:
cd bits_base/BITS - Make changes and commit in submodule
- Push to submodule repository
- Update main repository submodule reference if needed
# Add new beamline as submodule
git submodule add https://github.com/org/new-beamline.git bits_deployments/new-beamline
# Commit the submodule addition
git add .gitmodules bits_deployments/new-beamline
git commit -m "Add new beamline deployment"See individual submodule repositories for their respective licenses.
- bAIt Framework: Contact bAIt development team
- BITS/apstools: Contact BCDA-APS team
- Individual Beamlines: Contact respective beamline teams
- Access Issues: Contact repository owners or APS IT