generative-computing
diff --git a/‎cli/decompose/README.md‎
Lines changed: 99 additions & 0 deletions b/‎cli/decompose/README.md‎
Lines changed: 99 additions & 0 deletions
diff --git a/‎cli/decompose/decompose.py‎
Lines changed: 39 additions & 39 deletions b/‎cli/decompose/decompose.py‎
Lines changed: 39 additions & 39 deletions
diff --git a/‎cli/decompose/logging.py‎
Lines changed: 35 additions & 0 deletions b/‎cli/decompose/logging.py‎
Lines changed: 35 additions & 0 deletions
@@ -1 +1,100 @@
 # Mellea Decomp
+
+This automatic pipeline demonstrates **task decomposition and execution** built with *Mellea generative programs*.
+
+Instead of solving a complex task with a single prompt, the system first **decomposes the task into subtasks**, then executes them sequentially through a assembled pipeline.
+
+This pattern improves reasoning quality, interpretability, and modularity in LLM-powered systems.
+
+---
+
+# Overview
+
+Many complex tasks contain multiple reasoning steps.  
+The `m_decompose` pipeline handles this by splitting the task into smaller units.
+
+```
+User Request
+     ↓
+Task Decomposition
+     ↓
+Subtasks
+     ↓
+Task Execution
+     ↓
+Final Result
+```
+
+Rather than writing a large prompt, the workflow uses **generative modules and reusable prompts**.
+
+---
+
+# Directory
+
+```
+m_decompose/
+├── decompose.py
+├── pipeline.py
+├── prompt_modules
+└── README.md
+```
+
+**decompose.py**
+
+Generates the refined subtasks from the user request.
+
+**pipeline.py**
+
+Runs the full workflow:
+
+1. decompose the task  
+2. execute subtasks  
+3. aggregate results
+
+**prompt_modules**
+
+Reusable prompt components used by the pipeline.
+
+**m_decomp_result_v1.py.jinja2**
+
+Template used to format the final output.
+
+---
+
+# Quick Start
+
+Example usage:
+
+```python
+from mellea.cli.decompose.pipeline import decompose, DecompBackend
+import json
+
+query = """I will visit Grand Canyon National Park for 3 days in early May. Please create a travel itinerary that includes major scenic viewpoints and short hiking trails. The daily walking distance should stay under 6 miles, and each day should include at least one sunset or sunrise viewpoint."""
+
+result = decompose(
+    task_prompt=query,
+    model_id="mistralai/Mistral-Small-3.2-24B-Instruct-2506",
+    backend=DecompBackend.openai,
+    backend_endpoint="http://localhost:8000/v1",
+    backend_api_key="EMPTY",
+)
+
+print(json.dumps(result, indent=2, ensure_ascii=False))
+```
+
+
+The pipeline then executes each step and produces the final answer.
+
+---
+
+# Highlights
+
+- **Task Decomposition and Execution** — analyze complex problems into smaller planning and execution steps.  
+- **Generative Mellea Program** — conduct LLM workflows as an programmatic pipeline instead of single call.  
+- **Instruction Modular** — separate instruction design from execution logic using reusable modules.
+
+---
+
+# Summary
+
+`m_decompose` shows how to build **LLM pipelines** using task decomposition.
@@ -27,14 +27,16 @@
 
 
 class DecompVersion(StrEnum):
-    """Available versions of the decomposition pipeline template.
+    """Available template versions for generated decomposition programs.
 
-    Newer versions must be declared last to ensure ``latest`` always resolves to
-    the most recent template.
+    Newer concrete versions must be declared after older ones so that
+    ``latest`` can resolve to the most recently declared template version.
 
-    Args:
-        latest (str): Sentinel value that resolves to the last declared version.
-        v1 (str): Version 1 of the decomposition pipeline template.
+    Attributes:
+        latest: Sentinel value that resolves to the last declared concrete
+            template version.
+        v1: Version 1 of the decomposition program template.
+        v2: Version 2 of the decomposition program template.
     """
 
     latest = "latest"
@@ -225,44 +227,42 @@ def run(
         ),
     ] = LogMode.demo,
 ) -> None:
-    """Decompose one or more user queries into subtasks with constraints and dependency metadata.
-
-    Reads user queries either from a file or interactively, runs the LLM
-    decomposition pipeline to produce subtask descriptions, Jinja2 prompt templates,
-    constraint lists, and dependency metadata, and writes one ``.json`` result file
-    plus one rendered ``.py`` script per task job to the output directory.
+    """Runs the ``m decompose`` CLI workflow and writes generated outputs.
 
-    If ``input_file`` contains multiple non-empty lines, each line is treated as a
-    separate task job.
+    Reads user queries from a file or interactive input, runs the decomposition
+    pipeline for each task job, and writes one JSON file, one rendered Python
+    program, and any generated validation modules under a per-job output
+    directory.
 
     Args:
-        out_dir: Path to an existing directory where output files are saved.
-        out_name: Base name (no extension) for the output files. Defaults to
-            ``"m_decomp_result"``.
-        input_file: Optional path to a text file containing one or more user
-            queries. If the file contains multiple non-empty lines, each line is
-            treated as a separate task job. If omitted, the query is collected
-            interactively.
-        model_id: Model name or ID used for all decomposition pipeline steps.
-        backend: Inference backend -- ``"ollama"``, ``"openai"``, or ``"rits"``.
-        backend_req_timeout: Request timeout in seconds for model inference calls.
-        backend_endpoint: Base URL of the configured endpoint. Required when
-            ``backend="openai"`` or ``backend="rits"``.
-        backend_api_key: API key for the configured endpoint. Required when
-            ``backend="openai"`` or ``backend="rits"``.
-        version: Version of the decomposition pipeline template to use.
-        input_var: Optional list of user-input variable names (e.g. ``"DOC"``).
-            Each name must be a valid Python identifier. Pass this option
-            multiple times to define multiple variables.
-        log_mode: Logging detail mode for CLI and pipeline output.
+        out_dir: Existing directory under which per-job output directories are
+            created.
+        out_name: Base name used for the per-job output directory and generated
+            files.
+        input_file: Optional path to a text file containing one or more task
+            prompts. Each non-empty line is processed as a separate task job.
+            When omitted, the command prompts interactively for one task.
+        model_id: Model identifier used for all decomposition pipeline stages.
+        backend: Inference backend used to execute model calls.
+        backend_req_timeout: Request timeout in seconds for backend inference calls.
+        backend_endpoint: Endpoint URL or base URL required by remote backends.
+        backend_api_key: API key required by remote backends.
+        version: Template version used to render the generated Python program.
+            ``latest`` resolves to the most recently declared concrete version.
+        input_var: Optional user input variable names to expose in generated
+            prompts and programs. Each name must be a valid non-keyword Python
+            identifier.
+        log_mode: Logging verbosity for CLI and pipeline execution.
 
     Raises:
-        AssertionError: If ``out_name`` contains invalid characters, if
-            ``out_dir`` does not exist or is not a directory, or if any
-            ``input_var`` name is not a valid Python identifier.
-        ValueError: If the input file contains no non-empty task lines.
-        Exception: Re-raised from the decomposition pipeline after cleaning up
-            any partially written output directories.
+        AssertionError: If ``out_name`` is invalid, ``out_dir`` does not name an
+            existing directory, ``input_file`` does not name an existing file,
+            or any declared ``input_var`` is not a valid Python identifier.
+        ValueError: If ``input_file`` exists but contains no non-empty task
+            lines.
+        Exception: Propagates pipeline, rendering, parsing, or file-writing
+            failures. Any output directories created earlier in the run are
+            removed before the exception is re-raised.
     """
     created_dirs: list[Path] = []
 
 
@@ -4,6 +4,13 @@
 
 
 class LogMode(StrEnum):
+    """Logging verbosity modes used across the CLI and pipeline.
+
+    Attributes:
+        demo: Standard readable logs with moderate detail.
+        debug: Verbose logs including internal state and intermediate outputs.
+    """
+
     demo = "demo"
     debug = "debug"
 
@@ -12,6 +19,17 @@ class LogMode(StrEnum):
 
 
 def configure_logging(log_mode: LogMode = LogMode.demo) -> None:
+    """Configures root logging handlers and log levels for the application.
+
+    Initializes a single stdout stream handler on first invocation and updates
+    log levels on subsequent calls. This function is safe to call multiple times.
+
+    Args:
+        log_mode: Logging verbosity mode controlling the global log level.
+
+    Returns:
+        None.
+    """
     global _CONFIGURED
 
     level = logging.DEBUG if log_mode == LogMode.debug else logging.INFO
@@ -34,10 +52,27 @@ def configure_logging(log_mode: LogMode = LogMode.demo) -> None:
 
 
 def get_logger(name: str) -> logging.Logger:
+    """Returns a logger instance with the given name.
+
+    Args:
+        name: Logger name, typically a module or component identifier.
+
+    Returns:
+        A configured ``logging.Logger`` instance.
+    """
     return logging.getLogger(name)
 
 
 def log_section(logger: logging.Logger, title: str) -> None:
+    """Emits a formatted section header to visually separate log output.
+
+    Args:
+        logger: Logger used to emit the section lines.
+        title: Section title displayed between separator lines.
+
+    Returns:
+        None.
+    """
     logger.info("")
     logger.info("=" * 72)
     logger.info(title)