[ggma] Add gyu (ggma yielding utility) tool

Implement gyu CLI tool to automate GGMA model package creation:

- Merge prefill.py and decode.py into unified export.py
- Create modular gpm tool structure:
  - gyu/init.py: Setup venv, install deps (CPU-only torch), clone TICO, extract o2o tools
  - gyu/import.py: Download complete model from HuggingFace
  - gyu/export.py: Run conversion pipeline and create .ggma package
  - gyu/common.py: Shared utilities and constants
  - gyu/clean.py: Remove building directory
  - gyu/gyu: Bash wrapper to dispatch commands

Documentation:
- Rename README.md → DEVELOPER.md (technical guide)
- Add USER.md (user-facing guide)

Author: Sanggyu Lee

runtime/ggma/examples/generate_text/README.md renamed to runtime/ggma/examples/generate_text/DEVELOPER.md

@@ -1,6 +1,6 @@
-# TinyLlama Text Generation Example
+# TinyLlama Text Generation Developer Guide
 
-This document provides a step‑by‑step guide for generating and processing a TinyLlama text‑generation model.
+This document provides a detailed technical guide for generating, processing, and optimizing the TinyLlama text-generation model. For basic usage, see [USER.md](USER.md).
 
 ## Summary
 
@@ -22,14 +22,6 @@ source _/bin/activate
 pip install -r requirements.txt
 ```
 
-### 3. Install TICO (Torch IR to Circle ONE)
-```bash
-# Clone the repository
-git clone https://github.com/Samsung/TICO.git
-# Install it in editable mode
-pip install -e TICO
-```
-
 ### 4. Get [o2o](https://github.com/Samsung/ONE/pull/16233) in PATH
 *Requires the GitHub CLI (`gh`).*
 ```bash
@@ -41,8 +33,8 @@ export PATH=../../../../tools/o2o:$PATH
 
 ### 1. Create the prefill and decode Circle model files
 ```bash
-python prefill.py   # Generates prefill.circle
-python decode.py    # Generates decode_.circle
+python tinyllama.py --mode prefill   # Generates prefill.circle
+python tinyllama.py --mode decode    # Generates decode_.circle
 ```
 
 Verify the generated files:

runtime/ggma/examples/generate_text/USER.md

@@ -0,0 +1,51 @@
+# TinyLlama Text Generation User Guide
+
+This guide shows how to create a GGMA package for the TinyLlama model using the `gyu` (GGMA Yielding Utility) tool.
+
+## Quick Start
+
+```bash
+cd runtime/ggma/examples/generate_text/
+
+# 1. Initialize environment (one-time setup)
+gyu/gyu init
+
+# Clean up everything (including venv and tools)
+gyu/gyu clean --all
+
+# 2. Import model from HuggingFace
+gyu/gyu import Maykeye/TinyLLama-v0
+
+# 3. Export to GGMA package
+gyu/gyu export -s tinyllama.py -p tinyllama.pipeline
+
+# 4. Your package is ready at: build/tinyllama-v0.ggma/
+```
+
+## Result
+
+After running the commands above, you'll have a complete GGMA package:
+
+```bash
+$ tree build/tinyllama-v0.ggma/
+build/tinyllama-v0.ggma/
+├── config.json
+├── model.circle
+├── tokenizer.json
+└── tokenizer.model
+```
+
+The package is ready to use with `ggma_run`.
+
+## Build ggma and Run the ggma package
+
+```bash
+# Build ggma_run (from ONE root)
+make -j$(nproc)
+make install
+
+# Run the model
+Product/out/bin/ggma_run build/tinyllama-v0.ggma
+```
+
+For developers who want to understand what happens under the hood, see [DEVELOPER.md](DEVELOPER.md).

runtime/ggma/examples/generate_text/decode.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+import shutil
+import os
+
+import argparse
+from common import VENV_DIR
+
+def main():
+    parser = argparse.ArgumentParser(description="Clean build artifacts")
+    parser.add_argument("--all", action="store_true", help="Remove all generated files including venv, TICO, and o2o")
+    args = parser.parse_args()
+
+    # Always remove build directory
+    build_dir = "build"
+    if os.path.exists(build_dir):
+        print(f"Removing {build_dir} directory...")
+        shutil.rmtree(build_dir)
+    else:
+        print(f"{build_dir} directory does not exist.")
+
+    if args.all:
+        dirs_to_remove = ["TICO", "o2o", VENV_DIR]
+        for d in dirs_to_remove:
+            if os.path.exists(d):
+                print(f"Removing {d} directory...")
+                shutil.rmtree(d)
+        print("Full clean complete.")
+    else:
+        print("Clean complete.")
+
+if __name__ == "__main__":
+    main()

runtime/ggma/examples/generate_text/gyu/clean.py

@@ -0,0 +1,11 @@
+import subprocess
+
+# Constants
+VENV_DIR = "venv"
+PR_WORKTREE = "_pr_16233"
+PR_BRANCH = "pr-16233"
+PR_REF = "refs/pull/16233/head"
+
+def run_command(cmd, cwd=None, env=None, check=True):
+    print(f"Running: {cmd}")
+    subprocess.run(cmd, shell=True, cwd=cwd, env=env, check=check)

runtime/ggma/examples/generate_text/gyu/common.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+import argparse
+import shutil
+import json
+import yaml
+import os
+from common import VENV_DIR, run_command
+
+def main():
+    parser = argparse.ArgumentParser(description="Export model to GGMA package")
+    parser.add_argument("-s", "--script", required=True, help="Export script to use (e.g., tinyllama.py)")
+    parser.add_argument("-p", "--pipeline", required=True, help="Pipeline configuration file (e.g., tinyllama.pipeline)")
+    args = parser.parse_args()
+    
+    export_script_name = args.script
+    pipeline_config_path = os.path.abspath(args.pipeline)
+
+    # Change to build directory
+    build_dir = "build"
+    if not os.path.exists(build_dir):
+        print(f"Error: {build_dir} directory does not exist. Run 'gyu import' first.")
+        return
+    
+    os.chdir(build_dir)
+    
+    # Load pipeline configuration
+    if not os.path.exists(pipeline_config_path):
+        print(f"Error: Pipeline configuration file {pipeline_config_path} not found.")
+        return
+        
+    with open(pipeline_config_path, "r") as f:
+        pipeline_config = yaml.safe_load(f)
+
+    # Find model directory by config.json
+    model_dir = None
+    model_id = None
+    for d in os.listdir("."):
+        config_path = os.path.join(d, "config.json")
+        if os.path.isdir(d) and os.path.exists(config_path):
+            model_dir = d
+            # Read model ID from config.json
+            with open(config_path, "r") as f:
+                config = json.load(f)
+                model_id = config.get("_name_or_path", d)
+            print(f"Using local model directory: {model_dir}")
+            print(f"Model ID from config: {model_id}")
+            break
+    
+    if not model_dir:
+        raise ValueError("No local model directory found (directory with config.json)")
+    
+    # Add o2o tools to PATH
+    env = os.environ.copy()
+    o2o_path = os.path.abspath("../o2o")
+    env["PATH"] = f"{o2o_path}:{env['PATH']}"
+    
+    python_bin = os.path.join("..", VENV_DIR, "bin", "python3")
+    export_script = os.path.join("..", export_script_name)
+    
+    # 1. Generate prefill and decode circles
+    print(f"Running {export_script_name} (prefill)...")
+    run_command(f"{python_bin} {export_script} --mode prefill --model {model_dir}", env=env)
+    
+    print(f"Running {export_script_name} (decode)...")
+    run_command(f"{python_bin} {export_script} --mode decode --model {model_dir}", env=env)
+    
+    # Helper to run pipeline command
+    def run_pipeline_step(step_name):
+        if step_name in pipeline_config:
+            print(f"Running {step_name} pipeline...")
+            cmd = pipeline_config[step_name]
+            # If cmd is a multiline string (from YAML |), it might contain newlines.
+            # We can replace newlines with spaces or let the shell handle it if it's a single command string.
+            # For safety with pipes, we replace newlines with spaces if they are meant to be a single line command.
+            # But YAML block scalar preserves newlines.
+            # If the user wrote it with pipes at the start of lines, we should join them.
+            cmd = cmd.replace("\n", " ")
+            run_command(cmd, env=env)
+
+    # 2. Pipeline (decode)
+    run_pipeline_step("decode")
+    
+    # 3. Merge
+    run_pipeline_step("merge")
+    
+    # 4. Create package directory and copy files
+    # Find source directory with tokenizer.json
+    source_dir = None
+    for d in os.listdir("."):
+        if os.path.isdir(d) and os.path.exists(os.path.join(d, "tokenizer.json")):
+            source_dir = d
+            break
+    
+    if source_dir:
+        package_dir = f"{source_dir}.ggma"
+        print(f"Creating package directory {package_dir}...")
+        os.makedirs(package_dir, exist_ok=True)
+        
+        # Copy tokenizer and config files
+        for filename in ["tokenizer.json", "tokenizer.model", "config.json"]:
+            src = os.path.join(source_dir, filename)
+            if os.path.exists(src):
+                shutil.copy2(src, package_dir)
+        
+        # Move model.circle
+        print(f"Moving model.circle to {package_dir}...")
+        shutil.move("model.circle", os.path.join(package_dir, "model.circle"))
+    else:
+        print("Warning: Could not find source directory (directory with tokenizer.json). Leaving model.circle in current dir.")
+
+if __name__ == "__main__":
+    main()

runtime/ggma/examples/generate_text/gyu/export.py

@@ -0,0 +1,14 @@
+#!/bin/bash
+SCRIPT_DIR=$(dirname "$0")
+COMMAND="$1"
+shift  # Remove command from arguments
+
+if [ "$COMMAND" == "init" ]; then
+    python3 "$SCRIPT_DIR/$COMMAND.py" "$@"
+else
+    if [ ! -f "venv/bin/python3" ]; then
+        echo "Error: Environment not initialized. Run 'gyu init' first."
+        exit 1
+    fi
+    venv/bin/python3 "$SCRIPT_DIR/$COMMAND.py" "$@"
+fi

runtime/ggma/examples/generate_text/gyu/gyu

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+import sys
+import os
+from huggingface_hub import snapshot_download
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: gyu import <model_id>")
+        sys.exit(1)
+    
+    model_id = sys.argv[1]
+    model_basename = model_id.split("/")[-1].lower()
+    
+    # Create build directory
+    build_dir = "build"
+    os.makedirs(build_dir, exist_ok=True)
+    
+    # Download into build directory
+    target_dir = os.path.join(build_dir, model_basename)
+    print(f"Downloading model files for {model_id} into {target_dir}...")
+    
+    snapshot_download(repo_id=model_id, local_dir=target_dir)
+
+if __name__ == "__main__":
+    main()