Open
Conversation
added 6 commits
December 4, 2025 10:28
…ith provided PV/Description database which has about 60K PVs now.
…retriaval, and fixed the core dump error in plot pv data.
- Add PyQt5 GUI interface with multi-project support - Include GUI components, workers, and event bus architecture - Add conversation management and LLM client integration - Add routing analytics and feedback systems - Update pyproject.toml to include PyQt files in distribution - Add PyQt5 as optional dependency (install with: pip install osprey-framework[gui]) - Add GUI tests for core components - Update .gitignore to exclude development files and agent directories - Improve orchestrator and task extraction prompts with formatting and multi-question handling
- Remove deprecated manual streaming code - Remove progress tracking (0.1, 0.5, 1.0) - Migrate to unified logger system with automatic streaming - Fix duplicate 'starting error response generation' messages - Simplify to clean status/success/error logging pattern
Implements a two-tier approval detection system in Gateway: 1. Fast path: Explicit pattern matching for simple yes/no responses - Approval words: yes, y, yep, yeah, ok, okay - Rejection words: no, n, nope, nah, cancel - Case-insensitive with optional punctuation (., !, ?) - Instant, deterministic responses without LLM calls 2. Fallback: LLM-powered detection for complex natural language - Only invoked when user response doesn't match simple patterns - Handles nuanced responses like 'I think we should proceed' Benefits: - Faster approval workflow for common responses - Reduced LLM API calls for simple yes/no answers - More predictable behavior for explicit responses - Maintains flexibility for complex natural language Testing: - 9 unit tests covering explicit detection patterns - 11 integration tests validating complete approval workflow - All existing Gateway tests pass Documentation: - Updated Gateway architecture guide with two-tier system details - Updated API reference with approval detection description - Added CHANGELOG entry
The @infrastructure_node decorator already handles start/completion logging automatically. The ErrorNode was manually logging these same messages, causing duplicate output.
Implements comprehensive runtime validation for control system channel writes with failsafe design. Validates min/max boundaries, step sizes, and writable status against configurable JSON database. Key features: - Synchronous validation to keep code simple and predictable - Failsafe: blocks unlisted channels and JSON errors by default - Optional max_step checking (adds I/O overhead, logs warnings) - Configurable policy: strict mode (error) vs skip mode (log + continue) - New exception: ChannelLimitsViolationError with detailed context Designed for integration with Python executor wrapper via monkeypatching. Documentation: - Added ChannelLimitsViolationError to exception reference
Adds runtime validation for all channel writes performed via epics.caput() by monkeypatching at execution time. Configuration is embedded directly into wrapper code for container isolation. Implementation: - Wrapper serializes validator config to JSON and embeds in wrapper - Monkeypatch intercepts epics.caput() and PV.put() before execution - Raises ChannelLimitsViolationError if validation fails - Control/node/container_engine pass validator through pipeline All epics writes now automatically checked against configured limits. Documentation: - Updated Python execution service documentation - Added limits checking integration examples
Modernizes control system connector API with unified "channel" naming (replacing EPICS-specific "PV" terminology) and comprehensive write verification support. API changes: - Renamed methods: read_pv → read_channel, write_pv → write_channel - Renamed classes: PVValue → ChannelValue, PVMetadata → ChannelMetadata - write_channel() now returns ChannelWriteResult instead of bool - New verification_level and tolerance parameters New classes: - WriteVerification: Verification result with level/verified/readback - ChannelWriteResult: Complete write status with optional verification All connectors updated: - EPICSConnector: Full callback and readback verification - MockConnector: Simulates verification for development Backward compatibility: - Deprecated methods emit DeprecationWarning at runtime - Deprecated classes (PVValue, PVMetadata) emit DeprecationWarning on instantiation - All deprecated APIs will be removed in v0.10 - Tests updated to use new API Documentation: - Comprehensive migration guide with before/after examples - Updated connector API reference with new classes - Write verification configuration guide
Implements human approval workflow for channel write operations with structured interrupts and comprehensive operation context. New function: create_channel_write_approval_interrupt() - Shows all pending write operations with values - Lists identified safety concerns - Provides clear yes/no approval prompt - Includes resume payload for continuation Integrated with approval_manager for consistent workflow patterns. Tests updated for new approval scenarios. Documentation: - Added channel write approval workflow guide - Integration examples with capabilities
Adds convenience method for capabilities to access step inputs provided
by orchestrator. Useful for building context descriptions, validation,
and informing LLMs about available data.
Features:
- Returns list of {context_type: context_key} mappings from step
- Handles missing/None inputs with configurable default
- Clear error if called outside execute()
- Follows same pattern as get_task_objective()
Includes comprehensive tests for common patterns and edge cases.
Documentation:
- Added to BaseCapability API reference
- Usage examples for capability development
Implements production-ready channel capabilities for Control Assistant template with comprehensive safety controls and LLM-based value parsing. New capabilities: - channel_read: Reads current values using connector abstraction - channel_write: Writes with three safety layers (flag/limits/approval) Safety features: 1. Global writes_enabled flag (master safety switch) 2. Channel limits validation (boundaries, step, writable) 3. Human approval workflow (asks before executing) 4. Write verification (callback or readback confirmation) channel_write uses LLM to parse values from task and contexts, supporting direct values, calculated results, and statistics. Replaces channel_value_retrieval with simpler channel_read. Includes example limits database and comprehensive safety tests. Documentation: - Updated Control Assistant tutorial (parts 1-3) - Safety features integration guide - Production deployment best practices
Updates minimal template, project config, and framework components to support new control system safety features and connector API. Changes: - Project config template: Add control_system configuration section * Control system type selector (mock/epics) * writes_enabled master safety switch * Limits checking configuration * Write verification settings * Connector-specific config with EPICS gateway setup * Pattern detection for code analysis - Minimal template: Update README and integration guide - Framework capabilities: Update for read_pv → read_channel rename - Pattern detection: Add read_channel/write_channel patterns for new API - Registry: Support new context types - Utils: Configuration helpers for limits checking - Module exports: Update __init__ files for new classes - Tests: Update for new APIs All framework components now use consistent channel terminology. Documentation: - Configuration system reference updated - Quick-start patterns updated for new API - Context management system updates
Consolidates Python execution documentation from standalone file to directory structure with focused sub-pages for better organization. Changes: - Remove obsolete standalone 03_python-execution-service.rst * Leftover from before Code Generator reorganization * Caused conflicting URLs and navigation issues - Streamline service-overview.rst (793 → 452 lines, 40% reduction) * Focus on generator extensibility (main developer use case) * Remove redundant integration patterns (now in main guide) * Add strategic cross-references to avoid duplication - Update all documentation links (13 files) * Change 03_python-execution-service → 03_python-execution-service/index * Fix API reference links * Fix developer guide cross-references * Fix tutorial references This cleanup improves documentation discoverability by consolidating the Python execution service docs into a clear hierarchy: - index.rst: Overview and generator comparison - service-overview.rst: Service architecture and custom generators - generator-*.rst: Individual generator documentation All links now correctly point to the directory structure, fixing navigation and sidebar rendering issues.
Adds comprehensive developer guide for organizing uncommitted Git changes into atomic, logical commits with proper CHANGELOG entries. Contents: - Complete workflow from analysis to execution - Atomic commit principles and grouping strategies - CHANGELOG entry guidelines with examples - Commit strategy document template - Common patterns and edge cases - Real-world examples Designed to help developers create clean, reviewable commit history by planning before executing commits. Also updates CHANGELOG formatting to use consistent bold bullet style throughout all entries.
Update core documentation to emphasize Osprey's focus on large-scale, safety-critical control system deployments. Highlights control-specific features including PV boundary checking, hardware-write detection, and protocol-agnostic integration with EPICS/LabVIEW/Tango. Updates terminology from 'orchestrator-first' to 'plan-first' and adds reference to ALS production deployment.
Implements osprey.runtime module providing control-system-agnostic utilities for generated Python code. These utilities enable LLMs to interact with control systems through a simple synchronous API similar to EPICS caput/caget commands. Key features: - Synchronous API (write_channel, read_channel) that handles async internally - Automatic configuration from execution context snapshots - Protocol-agnostic (works with EPICS, Mock, Tango, etc.) - Proper cleanup and resource management - Fallback chain: context config → global config → error Includes comprehensive test coverage and API reference documentation: - Unit tests for configuration and API functions - Integration tests with Mock connector - Tests for context-based configuration and fallback behavior - API reference docs with usage examples in generated code
Connects osprey.runtime utilities to the execution system for automatic configuration and lifecycle management. Changes: - ContextManager: Added add_execution_config() to preserve control system config - ExecutionWrapper: Inject runtime configuration after context load - ExecutionWrapper: Add cleanup_runtime() in finally block for resource safety - NotebookManager: Include runtime configuration in generated notebooks - E2E conftest: Add .py files to artifacts for test verification - Developer guide: Document integration with Python execution service This ensures generated code using runtime utilities receives proper configuration automatically and resources are cleaned up even on errors.
Implements custom prompt builders that teach LLMs how to use osprey.runtime utilities for control system operations. Components: - ControlSystemPythonPromptBuilder: Extends framework defaults with control system guidance (write_channel, read_channel examples) - PythonCapability: Integrated prompt builder system for dynamic instruction injection - BasicLLMCodeGenerator: Simplified prompt building to rely on capability-specific prompts from builder system - Tests: Verify prompt builder integration and graceful fallback - Tutorial: Comprehensive guide on framework prompt customization This enables LLMs to generate code using runtime utilities without needing explicit control system knowledge in every request.
Comprehensive end-to-end test suite validating the complete runtime utilities workflow from LLM code generation through execution. Test Coverage: - test_runtime_utilities_basic_write: Verify LLM learns osprey.runtime API - test_runtime_utilities_respects_channel_limits: CRITICAL SAFETY test ensuring runtime writes respect channel boundary validation - test_runtime_utilities_within_limits_succeeds: Positive case for valid writes - test_runtime_utilities_calculation_with_write: Complex workflow combining calculation and write operations - test_runtime_limits_e2e.py: Full integration tests with limits validator These tests ensure runtime utilities provide safety without compromising the control system's boundary checking mechanisms.
Updated README and getting-started tutorials to emphasize Osprey's role as a production-ready framework for safety-critical control system environments, with comprehensive explanation of runtime utilities integration. Changes: - README: Updated tagline to highlight large-scale control systems - README: Emphasized plan-first orchestration and safety features - README: Added protocol-agnostic integration capabilities - README: Noted production deployment at major facilities - README: Refined feature list for control system operators - Part 3 Tutorial: Added detailed dropdown explaining osprey.runtime usage - Part 3 Tutorial: Shows why generated code uses runtime utilities vs direct imports - Part 3 Tutorial: Explains automatic configuration and safety integration Also includes CHANGELOG entries for runtime utilities feature.
- Replace absolute path in INSTALLATION_GUIDE.md with generic placeholder - Change gui_config.yml project_root from absolute to relative path (.)
- Remove trailing whitespace from blank lines - Add missing newlines at end of files - Affects all Python files and .gitignore in src/osprey/interfaces/pyqt/
- Add blank line between stdlib and third-party imports - Sort imports alphabetically within each group - Follow PEP 8 import ordering guidelines
- Created GUIPreferences system for user interface settings - Stores preferences in ~/.osprey/gui_preferences.yml - Includes conversation storage, display prefs, memory monitoring - Created RuntimeOverrideManager for execution behavior - Manages overrides in memory only (never written to disk) - Includes agent control, approval modes, execution limits - Removed settings_manager.save_to_config() method - GUI no longer writes to project config.yml files - Prevents version control pollution - Updated project_context_manager - Removed file writing from _ensure_correct_project_root() - Now only updates in-memory configuration - Updated gui.py to use new preference system - Replaced _save_settings_to_config() with _save_gui_preferences() - Uses runtime_overrides for agent control defaults Benefits: - No version control pollution (project configs untouched) - Multi-project consistency (overrides apply to all projects) - Proper separation of concerns (UI vs execution settings) - User preferences persist without file modifications Fixes multi-project config writing bug where only first project's config.yml was modified, causing inconsistency across projects.
- Update imports to use collections.abc.Callable instead of typing.Callable - Replace deprecated typing generics (Dict, List, Set) with built-in types - Fix import sorting order - Use Python 3.9+ style type annotations throughout
- Updated README.md with pip install osprey-framework[gui] installation - Added osprey-gui command as recommended launch method - Updated gui_config.yml.example with placeholder values and all required sections - Organized documentation into docs/ directory - Added gui_config.yml to .gitignore (site-specific config) - Removed development utility scripts (dead_code_analyzer.py, unreferenced_files_analysis.py, remove_unused_imports.py) - Updated documentation references to point to docs/ directory
- Updated MULTI_PROJECT_GUIDE.md to reference docs/ directory - Updated USER_GUIDE.md to reference docs/ directory
- Apply ruff formatting to all 54 GUI files (PEP 8 compliance) - Fix import violations in launcher.py (use importlib.util.find_spec) - Add Python 3.11 compatibility (from __future__ import annotations) - Enhance docstrings with Google-style formatting - Modernize type hints (list, dict, X | None syntax) - Fix test_singleton_free_routing to properly test LLM routing - Move test file to correct location (osprey/tests/gui/) All ruff checks pass, all tests pass (6/6), Python 3.11 compatible. Changes: 55 files, 3,315 insertions(+), 3,036 deletions(-)
- Add 16 new test files covering all GUI components - Update 5 existing test files with improvements - Add shared test base class for routing tests - All tests pass ruff linting and formatting checks - No duplicate or dead code found
- Update imports: use collections.abc.Callable instead of typing.Callable - Modernize type annotations: use X | None instead of Optional[X] - Remove trailing whitespace from blank lines in docstrings - All 15 Ruff errors resolved
- Fix W293: Remove whitespace from blank line in gui.py docstring - Fix B904: Add exception chaining in llm_client.py FileNotFoundError
- Copied from my_gui_config.yml to provide default GUI configuration - Force-added despite .gitignore to ensure configuration is available
- INSTALLATION_GUIDE.md - Installation and setup instructions - MULTI_PROJECT_GUIDE.md - Multi-project orchestration guide - README_GUI_CONFIG.md - GUI configuration documentation - USER_GUIDE.md - Complete user manual Restored from commit b007895 (previous aps main branch)
- Implement lazy loading for sentence-transformers in SemanticContextAnalyzer - Defer PyTorch import until first use to avoid Windows DLL conflict - Move SemanticContextAnalyzer import to conditional lazy load in MultiProjectRouter - Add _load_model() method to load model only when encode() is called - Use importlib.util.find_spec() for availability check without importing - Fixes GUI startup errors on Windows when semantic context is disabled
- Created new theme system (themes.py) for cross-platform color consistency - Implemented DarkTheme with QPalette and comprehensive stylesheet - Fixed Windows issue where menus, tabs, and dialogs showed white backgrounds - Applied theme globally to QApplication for all widgets and dialogs - Added ThemeManager for future theme selection capability - Documented theme system in docs/THEME_SYSTEM.md The theme system ensures consistent dark theme appearance across Windows, Linux, and macOS by combining QPalette (for Qt widget colors) with a comprehensive stylesheet (for Windows compatibility where Qt's default styling may not apply palette settings correctly). Future developers can easily add new themes (light, high-contrast, etc.) by extending the Theme base class and registering in ThemeManager.
- Added comprehensive QCheckBox styling to DarkTheme - Ensures uniform appearance across all tabs (Agent Control, Approval, Execution Limits, GUI Settings, Development/Debug, Advanced Routing) - Consistent 18x18px checkbox size with dark theme colors - Interactive states: hover (blue border), checked (blue background), disabled - Improves visual consistency and professional appearance of settings dialog
…essage attributes instead of dict methods
- Updated conversation preprocessor to detect questions about previous conversations - Instead of trying to query historical data (which doesn't exist), retrieve the answer directly from conversation history - Prevents orchestrator from hallucinating non-existent capabilities like 'historical_weather_data_retrieval' - GUI now returns previous answers immediately without calling the framework
- Enhanced pattern matching to catch more variations of history references - Added better logging to debug detection issues - Improved logic to find user-assistant pairs in conversation history - Now checks patterns BEFORE searching history for better efficiency
…ge types - Fixed bug where preprocessor was only checking for 'assistant' type messages - Now checks for 'agent', 'assistant', or 'project' message types - Resolves issue where questions about previous conversations weren't being answered from GUI history - Prevents orchestrator from hallucinating non-existent capabilities like 'data_query'
- Reformatted 6 files with ruff format - Fixed type annotations (Optional[X] -> X | None) - Fixed import sorting - Removed whitespace from blank lines in all files
Add pytest.importorskip('PyQt5') to skip tests when PyQt5 is not available,
preventing ModuleNotFoundError during test collection in CI environments.
This matches the pattern used in test_conversation_preprocessor_integration.py
and ensures tests are properly skipped rather than failing when PyQt5 is not
installed.
The test was trying to patch SentenceTransformer at the module level, but it's only imported inside the _load_model() method. Changed the patch target from 'osprey.interfaces.pyqt.semantic_context_analyzer.SentenceTransformer' to 'sentence_transformers.SentenceTransformer' to patch where it's actually imported. This fixes the AttributeError during test setup in CI.
- Added pytest.importorskip for sentence-transformers in similarity_calculator_with_model fixture - Fixed patch target to use correct import location (sentence_transformers.SentenceTransformer) - Ensures tests are properly skipped when sentence-transformers is not available in CI environment
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PyQt GUI Interface - Pre-Release for Testing
Related to #38
Overview
This PR implements a comprehensive PyQt5-based graphical user interface for the Osprey Framework, providing a modern, feature-rich alternative to the CLI. The implementation goes significantly beyond the original feature request (#38) with advanced multi-project support, intelligent routing, conversation management, and extensive monitoring capabilities.
Key Features
Core Functionality
1. Multi-Project Architecture
config.ymlfiles2. Advanced Conversation Management
_gui_data/conversations/3. Intelligent Multi-Project Routing
4. Multi-Project Orchestration
User Experience
Main Window Tabs
Conversation Tab
LLM Details Tab
Tool Usage Tab
Discovered Projects Tab
System Information Tab
Memory Monitoring Tab (💾 Memory)
Analytics Dashboard Tab (📊 Analytics)
Settings Management
Comprehensive settings dialog with 6 tabs:
1. Agent Control
2. Approval Settings
3. Execution Limits
4. GUI Settings
5. Development/Debug
6. Advanced Routing
Settings Persistence: All settings saved to
gui_config.ymland persist across restarts.Advanced Features
Model Preferences System
Image/Plot Display
Event Bus Architecture
Implementation Details
Files Added/Modified
Core GUI Components
gui.py- Main GUI application (2,125 lines)launcher.py- Application launcher with dependency checking__init__.py- Package exportsMulti-Project Support (Phase 1)
project_manager.py- Project discovery and lifecycle managementcapability_registry.py- Centralized capability registrationmulti_project_router.py- Intelligent query routingproject_context_manager.py- Project context isolationRouting & Orchestration (Phase 2)
routing_cache.py- Query caching with similarity matchingrouting_analytics.py- Performance trackingrouting_feedback.py- User feedback collectionrouting_ui.py- Routing UI componentsorchestration_ui.py- Multi-project orchestration UImulti_project_orchestrator.py- Orchestration logicsemantic_context_analyzer.py- Context analysisadvanced_cache_invalidation.py- Advanced caching strategiesConversation Management
conversation_manager.py- Conversation lifecycle and storageconversation_display.py- Display managementconversation_management.py- UI operationsconversation_history.py- History persistenceconversation_context.py- Context trackingSettings & Configuration
settings_manager.py- Centralized settings managementsettings_dialog.py- Settings UImodel_preferences.py- Model preference storagemodel_preferences_manager.py- Model preference UIgui_config.yml.example- Configuration templateUI Components
event_bus.py- Event-driven architectureenums.py- Shared enumerationsgui_utils.py- Utility functionsgui_constants.py- Constants and colorsmessage_formatter.py- Rich text formattingmessage_handlers.py- Message processingcollapsible_widget.py- Collapsible message groupsimage_display.py- Image/plot displayplot_viewer.py- Plot viewer dialogTab Components (gui_components/)
tabs/system_info_tab.pytabs/analytics_tab.pytabs/llm_details_tab.pytabs/tool_usage_tab.pytabs/projects_tab.pytabs/memory_tab.pyWorker Threads
worker_thread.py- Agent execution workerbase_worker.py- Base worker classorchestration_worker.py- Orchestration workerDialogs
help_dialog.py- Help documentationabout_dialog.py- About dialogmodel_config_dialog.py- Model configurationProject Control
project_control.py- Project control panelAnalytics & Monitoring
analytics_dashboard.py- Analytics visualizationrealtime_analytics_websocket.py- WebSocket supportPrerequisites
Install GUI Dependencies
# From project root pip install -r src/osprey/interfaces/pyqt/requirements-gui.txtOr install manually:
pip install PyQt5>=5.15.0 python-dotenvConfiguration
Copy the example configuration:
cd osprey/src/osprey/interfaces/pyqt cp gui_config.yml.example gui_config.ymlSet up environment variables:
Create or update
.envfile in project root:ANTHROPIC_API_KEY=your-key-here # or OPENAI_API_KEY=your-key-hereEdit
gui_config.yml:Configure your LLM provider and models (see
README_GUI_CONFIG.md)Launch
Testing Checklist
Core Functionality
Advanced Features
UI/UX
Error Handling
Known Limitations & Future Enhancements
Current Limitations
Breaking Changes
None - this is a new feature addition that doesn't affect existing CLI or API functionality.
Documentation
README.md(301 lines)USER_GUIDE.md(877 lines)INSTALLATION_GUIDE.md(294 lines)MULTI_PROJECT_GUIDE.md(206 lines)README_GUI_CONFIG.md(505 lines)Migration Notes
For users of the previous
osprey-apsGUI:gui_config.ymlinstead of project-specific configs_gui_data/conversations/Feedback Welcome
This is a comprehensive implementation that significantly extends the original feature request. All feedback, bug reports, and feature requests are appreciated as we continue development!
Note: This PR represents a major addition to the Osprey Framework, providing a production-ready GUI with enterprise features including multi-project support, intelligent routing, comprehensive monitoring, and extensive configuration options.
Version
GUI Version: 0.1.0
Framework Version: 0.9.2+
Related Issues