Metadata-Version: 2.4
Name: lightfall
Version: 0.1.1
Summary: Lightfall - control system for the ALS facility
Project-URL: Homepage, https://github.com/als-controls/lightfall
Project-URL: Documentation, https://als-controls.github.io/lightfall
Project-URL: Repository, https://github.com/als-controls/lightfall
Author: ALS Controls Team
License-Expression: BSD-3-Clause
License-File: LEGAL.md
License-File: LICENSE.md
Keywords: beamline,control-system,data-acquisition,lightfall,scientific-instruments
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: aiohttp-socks>=0.8
Requires-Dist: aiohttp>=3.8
Requires-Dist: bluesky-tiled-plugins>=2.0
Requires-Dist: bluesky>=1.10
Requires-Dist: caproto>=1.1
Requires-Dist: claude-agent-sdk>=0.2.82
Requires-Dist: h5py>=3.0
Requires-Dist: happi>=2.0
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: ipykernel>=6.0
Requires-Dist: loguru>=0.7
Requires-Dist: mistune>=3.0
Requires-Dist: nats-py>=2.0
Requires-Dist: netifaces>=0.11; sys_platform != 'darwin'
Requires-Dist: ophyd>=1.7
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyqtgraph>=0.13
Requires-Dist: pyqttoast-enhanced>=2.0
Requires-Dist: pyside6>=6.6
Requires-Dist: pysocks>=1.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: qtawesome>=1.3
Requires-Dist: qtconsole>=5.5
Requires-Dist: scipy>=1.11
Requires-Dist: sentry-sdk[loguru]>=2.0
Requires-Dist: tiled[client]>=0.2.5
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest-qt>=4.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-immaterial>=0.12; extra == 'docs'
Requires-Dist: sphinx<9.0,>=7.0; extra == 'docs'
Description-Content-Type: text/markdown

# Lightfall

<!-- badges:start -->
[![CI](https://github.com/als-controls/lightfall/actions/workflows/ci.yml/badge.svg)](https://github.com/als-controls/lightfall/actions/workflows/ci.yml)
[![Docs](https://github.com/als-controls/lightfall/actions/workflows/docs.yml/badge.svg)](https://als-controls.github.io/lightfall/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://github.com/als-controls/lightfall/blob/master/pyproject.toml)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE.md)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20545717.svg)](https://doi.org/10.5281/zenodo.20545717)
<!-- badges:end -->

A modern, unified control system for synchrotron lightsource facilities that provides facility-wide consistency with beamline-specific customization.

## Overview

Lightfall is designed for the Advanced Light Source (ALS) facility, providing:

- **Unified Interface**: Consistent look-and-feel across beamlines with skinnable themes
- **API-First Architecture**: Modular, extensible design enabling automation and integration
- **LLM/AI Integration**: Claude-powered chatbot for natural language control and assistance
- **FAIR-Compliant Data Management**: Integration with Tiled for data cataloging and access
- **Secure Remote Operations**: Full remote operation capability with fine-grained access control

## Features

### User Interface
- Progressive disclosure: user panels with expert panels behind authorization
- Scripting panel with Jupyter-lab style interface
- LLM panel for controlling panels via natural language
- GUI Builder for drag-and-drop interface creation
- Persistent user preferences saved across sessions

### Device Management
- Centralized device catalog with lifecycle tracking
- Real-time monitoring via EPICS Channel Access
- Version-controlled device configurations
- Rich high-level controls integrated into workflows

### Data Acquisition
- Bluesky-based acquisition engine
- Flexible signal/stream selection with real-time visualization
- Interactive, pausable, restartable acquisition
- Automatic data persistence to Tiled catalog

### Data Browser
- Browse and search data stored in Tiled server
- Filter by date range, plan type, exit status
- Pagination for large datasets
- Click/double-click signals for integration with analysis tools

## Installation

```bash
pip install lightfall
```

### BCS backend (ALS-internal)

The BCS device backend requires `bcsophyd-zmq`, which is distributed from ALS
GitLab rather than PyPI:

```bash
pip install "bcsophyd @ git+https://git.als.lbl.gov/bcs/bluesky/bcsophyd-zmq"
```

Without it, Lightfall runs normally; only the BCS backend is unavailable.

### Development Installation

```bash
# Clone the repository
git clone https://github.com/als-controls/lightfall.git
cd lightfall

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Unix

# Install in development mode with dev dependencies
pip install -e ".[dev]"
```

### Running the Application

```bash
lightfall
```

## Configuration

Lightfall uses a layered configuration system:

1. **System defaults** - Built-in defaults
2. **Site configuration** - Facility-wide settings
3. **User preferences** - Personal customizations

Configuration files are stored in:
- Windows: `%APPDATA%\lightfall\`
- Linux/Mac: `~/.config/lightfall/`

## Architecture

Lightfall is built on:

- **PySide6** - Qt for Python GUI framework
- **Bluesky** - Data acquisition framework
- **Ophyd** - Device abstraction layer
- **Tiled** - Data catalog and access
- **EPICS** - Control system communication

### Plugin System

Lightfall supports plugins for:
- **Panels** - Custom UI panels
- **Settings** - Preference pages
- **Status Bar** - Status indicators
- **Engines** - Acquisition backends
- **Plans** - Scan procedures

## Development

### Running Tests

```bash
pytest
```

### Code Quality

```bash
# Linting
ruff check src tests

# Type checking
mypy src
```

## Project Structure

```
ncs/
├── src/ncs/
│   ├── acquire/      # Data acquisition engine
│   ├── auth/         # Authentication & authorization
│   ├── config/       # Configuration management
│   ├── core/         # Core application classes
│   ├── devices/      # Device catalog & backends
│   ├── plugins/      # Plugin system
│   ├── services/     # Application services (Tiled, etc.)
│   ├── ui/           # User interface
│   │   ├── panels/   # Panel implementations
│   │   ├── widgets/  # Reusable widgets
│   │   ├── preferences/  # Settings UI
│   │   └── theme/    # Theming system
│   └── utils/        # Utilities
└── tests/            # Test suite
```

