# GEMINI.md

## Project Overview

**ParamManagerScripts** is a comprehensive script management and execution system. It provides a web-based interface to organize, configure, and run various types of scripts (Python, C#, etc.) in a controlled and structured manner. The system is designed to work with specific working directories where scripts process files, making it ideal for data processing and automation tasks.

### Key Features

*   **Hierarchical Configuration:** A three-level configuration system (Global, Group, and Work) allows for flexible and granular control over script parameters.
*   **Script Management by Categories:** The system supports different types of scripts, including traditional Python scripts, Python scripts with GUIs, C# projects, and specialized Python projects.
*   **Web-based Frontend:** The application is accessible via a web browser at `http://127.0.0.1:5000/` and includes a real-time log panel using WebSockets, working directory management for each script group, and integration with popular code editors (VS Code, Cursor, Visual Studio).
*   **System Tray Icon:** A system tray icon provides quick access to the application.
*   **Launcher System:** The application includes a launcher system for executing scripts, with specific launchers for different script types.
*   **Shared Services:** The project provides a set of shared services for common tasks, including an `ExcelService` for working with Excel files, a `LanguageService` for language detection, and an `LLMService` for integrating with large language models.

## Building and Running

### Dependencies

The project requires the following Python libraries:

*   flask
*   flask_sock
*   pystray
*   Pillow
*   requests
*   psutil

Install them using pip:

```bash
pip install flask flask_sock pystray Pillow requests psutil
```

### Running the Application

To run the application, execute the following command in the project's root directory:

```bash
python app.py
```

The application will be accessible at `http://127.0.0.1:5000/`.

## Development Conventions

### Configuration Hierarchy

The system uses a cascading configuration model to manage script parameters. The configuration is merged from three levels, with each level overriding the previous one:

1.  **Level 1 (Global):** `data/data.json` - Stores global variables available to all scripts.
2.  **Level 2 (Group):** `backend/script_groups/<GroupName>/script_config.json` - Defines parameters shared by all scripts within a group.
3.  **Level 3 (Work):** `<WorkingDirectory>/work_dir.json` - Contains the specific input data for a script's execution.

Before execution, the launcher reads these files, combines them, and generates a single `script_config.json` in the script's folder. The `load_configuration()` utility function in `backend.script_utils` is used to read this consolidated configuration.

### Script Documentation

The launcher uses JSON files to display information about script groups and individual scripts in the web interface.

*   **`description.json`:** Located in the root of a script group's directory, this file contains the group's name, description, version, and author.
*   **`scripts_description.json`:** Also in the group's root, this file provides details for each script, including a display name, short and long descriptions, and a `hidden` flag to control visibility in the UI.

### Output Encoding

All standard output (`stdout`) from scripts is captured and displayed in the frontend's log panel. To ensure proper rendering, all script output **must** be UTF-8 encoded. The execution environment is automatically configured to use UTF-8, so in most cases, a simple `print()` is sufficient.

### Shared Services

The project includes a `services` directory with reusable components for common tasks.

#### ExcelService

The `ExcelService` (`services/excel/excel_service.py`) simplifies reading and writing Excel files, with features like retry-on-open and formatting options.

#### LanguageService

The `LanguageService` (`services/language/`) provides language detection capabilities.

#### LLMService

The `LLMService` (`services/llm/`) offers a factory for creating clients for various Large Language Models (OpenAI, Groq, Claude, etc.). API keys for these services should be stored in a `.env` file in the project's root directory.