docs: aligner la configuration build v1.5.0

Author: raidos23

README.md

@@ -19,7 +19,8 @@ Build Python apps with a predictable workflow, a configurable pre-compile pipeli
 - **BuildContext-driven builds**: engines receive a normalized project context, abstracting away the source of configuration (YAML vs. Lock files).
 - **Multi-engine support**: switch between PyInstaller, Nuitka, and cx_Freeze seamlessly.
 - **Extensible SDKs**: create new engines and BCASL plugins using simplified, consolidated APIs.
-- **Auto-detection for tricky dependencies**: engine-specific auto-args based on requirements or import scanning.
+- **Zero-Config auto-mapping for 80+ libraries**: automatic import detection covers major AI, modern web, data science, and automation stacks, with engine-specific arguments applied without manual tuning.
+- **Simplified build inclusions**: `build.include` forces package bundling and ARK translates it automatically per engine.
 - **Workspace-first UI**: filter files, manage exclusions, and follow progress and logs in one place.
 - **Venv-aware execution**: engines can use the project virtual environment automatically.
 - **Theme-aware dynamic UI**: 100% dynamic integration using QPalette and themed SVGs.
@@ -136,7 +137,7 @@ python3 pycompiler_ark.py init --entry main.py --json
 
 ## Configuration
 
-- **`ark.yml`**: Project metadata, build entrypoint, build/workspace exclusions, and global BCASL activation.
+- **`ark.yml`**: Project metadata, build entrypoint, build include/exclude rules, and global BCASL activation.
 - **`bcasl.yml`**: Detailed BCASL pipeline configuration, plugin settings, and execution order.
 
 ---

docs/ark_main_config.md

@@ -22,6 +22,8 @@ build:
   engine: pyinstaller
   output: dist/
   icon: assets/icon.ico
+  include:
+    - "ma_bibliotheque"
   exclude:
     - "tkinter"
     - "unittest"
@@ -64,12 +66,37 @@ Determines which **Python packages/modules** are ignored by the compiler.
 - **Restriction**: This is **NOT** a general folder excluder. It should **NEVER** contain technical patterns like `*.pyc`, `__pycache__`, or `.git`. These are handled automatically by the Core or should be hidden via `workspace.exclude`.
 
 ⚠️ **CRITICAL WARNING: Name Collisions**
-Patterns in `build.exclude` are passed to engines (like Nuitka or PyInstaller) as **logical module exclusions**. 
+Entries in `build.exclude` are passed to engines (like Nuitka or PyInstaller) as **logical package exclusions**. 
 
 If you have a local folder named `venv` (your virtual environment) and you add `venv` to `build.exclude` thinking you are excluding a directory, you are actually telling the compiler: *"Do not bundle the Python package named 'venv'"*. 
 If your project or any dependency uses `import venv` (the standard library), your application **will crash** because the library was removed from the bundle. 
 
-**Rule of thumb**: Only use `build.exclude` for real Python modules you want to remove (e.g., `tkinter`, `unittest`, or a specific large sub-package). For everything else, use `workspace.exclude`.
+**Rule of thumb**: Only use `build.exclude` for real Python packages you want to remove (e.g., `tkinter`, `unittest`, or a specific large sub-package). For everything else, use `workspace.exclude`.
+
+## Build Inclusions vs Build Exclusions
+
+ARK v1.5.0 introduces a dedicated `build.include` section to force package inclusion during compilation.
+
+```yaml
+build:
+  include:
+    - "ma_bibliotheque"
+    - "langchain"
+  exclude:
+    - "unittest"
+```
+
+- `build.include` forces Python packages to be bundled even when automatic detection is not enough.
+- `build.exclude` ignores Python packages that should not be bundled.
+- `build.include` is the complement of `build.exclude`, not a UI filter and not a generic file/folder rule.
+
+ARK translates `build.include` automatically according to the selected engine:
+
+- Nuitka: `--include-package`
+- PyInstaller: `--collect-all`
+- cx_Freeze: `--includes`
+
+This keeps the configuration zero-config for the user while preserving engine-specific control under the hood.
 
 ## Build Entrypoint
 
@@ -95,12 +122,13 @@ The fields in `ark.yml` are mapped directly to the `BuildContext` data structure
 | :--- | :--- |
 | `project.name` | `project_name` |
 | `project.entry` | `entry_point` |
+| `build.include` | `include_packages` |
 | `build.exclude` | `exclude_patterns` |
 | `build.output` | `output_dir` |
 | `build.data` | `data_mappings` |
 | `build.icon` | `icon` |
 
-> **Note**: `workspace.exclude` is used only for the GUI workspace view filter. `build.exclude` determines which files are ignored during compilation and BCASL phases.
+> **Note**: `workspace.exclude` is used only for the GUI workspace view filter. `build.exclude` determines which Python packages are ignored during compilation and BCASL phases, while `build.include` forces package bundling when needed.
 
 ## Plugins Configuration
 
@@ -116,3 +144,6 @@ If `bcasl_enabled` is set to `false`, the entire pipeline is skipped during comp
 ## Advanced Config Editor (GUI)
 
 The main GUI has a **Configurations avancées** button that opens a dedicated editor for `ark.yml` managed by PyCompiler ARK.
+
+- A dedicated **Inclusions Build** field is now available for `build.include`.
+- The **Exclusions Build** label now explicitly means "Python packages to ignore" to avoid ambiguity with workspace filters.

docs/dev_docs/PyCompiler_ARK_BuildContext_v1.0.md

@@ -38,7 +38,8 @@ class BuildContext:
     project_name: str       # Name of the project (used for executable naming)
     entry_point: str        # Main script path (relative to workspace root)
     output_dir: str         # Directory where artifacts should be placed
-    exclude_patterns: list  # List of glob patterns for files to ignore
+    exclude_patterns: list  # List of Python packages to ignore
+    include_packages: list  # List of Python packages to force into the bundle
     data_mappings: list     # List of source/destination/type dicts for raw assets
     icon: str | None        # Optional path to an icon file
 
@@ -57,7 +58,8 @@ Each dictionary in `data_mappings` follows this structure:
 | `project_name` | `project.name` | `project.name` |
 | `entry_point` | `project.entry` | `project.entry` |
 | `output_dir` | `build.output` | `build.output` |
-| `exclude_patterns` | `build.exclude` | `build.exclude` (or `workspace.exclude_patterns` fallback) |
+| `include_packages` | `build.include` | `build.include` |
+| `exclude_patterns` | `build.exclude` | `build.exclude` |
 | `data_mappings` | `build.data` | `build.data` |
 | `icon` | `build.icon` | `build.icon` |
 
@@ -70,9 +72,10 @@ An engine implementation MUST adhere to the following rules when processing a `B
 1. **Name Application**: Use `project_name` for the final executable (e.g., `MyApp.exe` or `MyApp`).
 2. **Entry Point**: Treat `entry_point` as the primary script to compile/bundle.
 3. **Output Path**: Place all generated artifacts and temporary files inside `output_dir`.
-4. **Exclusions**: Respect `exclude_patterns` by preventing those modules/files from being bundled.
-5. **Assets**: Copy all items defined in `data_mappings` from their source to the appropriate relative destination within the bundle.
-6. **Icon**: Apply the file specified in `icon` to the executable metadata/resource if supported by the target OS.
+4. **Inclusions**: Respect `include_packages` by forcing those packages to be bundled, even when the engine would not infer them automatically.
+5. **Exclusions**: Respect `exclude_patterns` by preventing the listed Python packages from being bundled.
+6. **Assets**: Copy all items defined in `data_mappings` from their source to the appropriate relative destination within the bundle.
+7. **Icon**: Apply the file specified in `icon` to the executable metadata/resource if supported by the target OS.
 
 ---
 
@@ -89,11 +92,14 @@ class MyEngine(CompilerEngine):
     def build_command(self, context: BuildContext) -> list[str]:
         # Start with base command
         cmd = ["nuitka", context.entry_point]
+
+        # Force package inclusions
+        for package in context.include_packages:
+            cmd.append(f"--include-package={package}")
 
         # Convert exclusions
-        for pattern in context.exclude_patterns:
-            module = pattern.replace("/**/*", "").replace("**/*", "")
-            cmd.append(f"--nofollow-import-to={module}")
+        for package in context.exclude_patterns:
+            cmd.append(f"--nofollow-import-to={package}")
 
         # Add data files
         for mapping in context.data_mappings:

docs/dev_docs/PyCompiler_ARK_Locking_v1.2.md

@@ -47,13 +47,15 @@ project:
   git_branch: main         # Current git branch name
 
 workspace:
-  exclude_patterns:        # Copied from build.exclude (legacy support)
+  exclude_patterns:        # Workspace filter snapshot
     - tkinter
     - unittest
 
 build:
   output: dist/            # Copied from build.output
-  exclude:                 # Copied from build.exclude
+  include:                 # Copied from build.include
+    - langchain
+  exclude:                 # Python packages to ignore, copied from build.exclude
     - tkinter
     - unittest
   data:                    # Copied from build.data
@@ -104,7 +106,7 @@ A build is considered equivalent if the following sections match exactly:
 1.  **Engine**: name, version, and full configuration (`engine.config`).
 2.  **Dependencies**: all package versions must match.
 3.  **Project**: name, version, entry point, and Git commit.
-4.  **Build**: output path, data mappings, exclusion patterns, and icon.
+4.  **Build**: output path, data mappings, inclusion packages, package exclusions, and icon.
 5.  **Platform**: OS, architecture, and Python version.
 
 **Ignored fields**: `build_id`, `git_branch`, `resolved_command`, and other volatile metadata.

docs/how_to_create_a_bc_plugin.md

@@ -141,6 +141,7 @@ Key properties and methods.
 - `name`: Workspace folder name.
 - `config`: Full `bcasl.yml` configuration dictionary.
 - `build_context`: `BuildContext` with compilation settings, when available.
+- `build_context.include_packages`: Packages that ARK has been told to force into the bundle via `build.include`.
 - `file_patterns`: Configured include patterns.
 - `exclude_patterns`: Configured exclude patterns.
 - `iter_files(include, exclude)`: Optimized iterator that respects exclusions by default.

docs/how_to_create_an_engine.md

@@ -356,6 +356,12 @@ The auto-builder is integrated into the core compilation pipeline. It can read
 folder, or the `PYCOMPILER_MAPPING` environment variable to generate options
 from detected modules.
 
+ARK v1.5.0 expands this layer into a Zero-Config auto-mapping system covering
+80+ widely used libraries across AI, modern web, data science, and automation.
+When ARK detects an import, it applies the engine-specific flags automatically,
+so engine authors only need to fill the gaps that are not covered by the core
+mapping catalog.
+
 You no longer need to call `compute_auto_for_engine` manually in your `build_command`. The core runner will:
 
 1. Prefer `requirements.txt` or `requirements.in` when present.
@@ -384,6 +390,8 @@ Key points.
 - Top-level keys are package names.
 - Engine values accept `str`, `list[str]`, or `dict` with `args` or `flags`.
 - `"{import_name}"` is replaced by the matched import name.
+- Use `build.include` when a package must be bundled even if the core mapping
+  or import scanner does not trigger it automatically.
 - For advanced logic, expose `AUTO_BUILDER`, `get_auto_builder()`, or
   `register_auto_builder()` in `engines/<engine_id>/auto_plugins.py`.