"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
feat(macrocli): add interactive and Gemini-assisted macro parameterization
haorui-harry4cef98473b73
diff --git a/macrocli/agent-harness/cli_anything/macrocli/core/parameterize.py b/macrocli/agent-harness/cli_anything/macrocli/core/parameterize.pynew file mode 100644index 000000000..85191ed4d--- /dev/null+++ b/macrocli/agent-harness/cli_anything/macrocli/core/parameterize.py@@ -0,0 +1,300 @@+"""Parameterization helpers — interactive and Gemini-assisted.++Interactive flow (no external deps):+ assignments = interactive_parameterize(type_steps)+ parameters = recorder.apply_parameterization(assignments)+ recorder.save(parameters=parameters)++Post-hoc flow on an existing YAML file:+ parameterize_yaml_file(yaml_path) # modifies in-place++Gemini-assisted flow (optional, requires google-generativeai):+ assignments = gemini_suggest_parameters(type_steps, api_key=...)+ # returns same shape as interactive_parameterize, can be passed directly+"""++from __future__ import annotations++import re+import sys+from pathlib import Path+from typing import Optional++try:+ import yaml+except ImportError:+ raise ImportError("PyYAML required: pip install PyYAML")+++# ── Parameter name validation ─────────────────────────────────────────────────++_PARAM_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")+++def _valid_param_name(name: str) -> bool:+ return bool(_PARAM_NAME_RE.match(name))+++def _prompt_param_name(prompt: str) -> Optional[str]:+ """Prompt user for a parameter name. Return None if skipped (empty input)."""+ while True:+ try:+ raw = input(prompt).strip()+ except (EOFError, KeyboardInterrupt):+ print()+ return None++ if not raw:+ return None # skip++ if _valid_param_name(raw):+ return raw++ print(f" ✗ '{raw}' is not valid. Use lowercase letters, digits, "+ f"underscores only (must start with a letter). "+ f"Press Enter to skip.")+++# ── Interactive parameterization ──────────────────────────────────────────────++def interactive_parameterize(+ type_steps: list[tuple[int, object]],+ existing_params: Optional[set[str]] = None,+) -> dict[int, str]:+ """Interactively ask the user which type_text steps to parameterize.++ Args:+ type_steps: List of (list_index, RecordedStep) from recorder.get_type_steps().+ existing_params: Already-used parameter names (to avoid duplicates).++ Returns:+ {list_index: param_name} — only for steps the user chose to parameterize.+ """+ if not type_steps:+ print(" No type_text steps found to parameterize.")+ return {}++ used_names: set[str] = set(existing_params or [])+ assignments: dict[int, str] = {}++ print()+ print("─" * 60)+ print(" Parameterization — press Enter to keep a value hardcoded,")+ print(" or type a parameter name (e.g. output_path) to make it dynamic.")+ print("─" * 60)++ for n, (idx, step) in enumerate(type_steps, 1):+ value = step.text # type: ignore[attr-defined]+ # Truncate long values for display+ display = value if len(value) <= 50 else value[:47] + "..."++ print(f"\n [{n}/{len(type_steps)}] step typed: {display!r}")++ while True:+ name = _prompt_param_name(" → Parameter name (Enter to skip): ")+ if name is None:+ break # skip+ if name in used_names:+ print(f" ✗ '{name}' already used. Choose a different name.")+ continue+ used_names.add(name)+ assignments[idx] = name+ print(f" ✓ Will become: ${{{{name}}}}")+ break++ print()+ if assignments:+ print(f" Parameterized {len(assignments)} step(s): "+ f"{', '.join(assignments.values())}")+ else:+ print(" No steps parameterized — macro will use hardcoded values.")+ print("─" * 60)++ return assignments+++# ── Post-hoc YAML parameterization ───────────────────────────────────────────++class _YamlTypeStep:+ """Lightweight wrapper for a type_text step found inside a YAML dict."""+ def __init__(self, step_idx: int, step_dict: dict):+ self.list_index = step_idx+ self._step = step_dict+ self.text: str = step_dict["params"]["text"]++ def apply(self, param_name: str) -> None:+ self._step["params"]["text"] = f"${{{param_name}}}"+++def parameterize_yaml_file(yaml_path: str) -> bool:+ """Interactively parameterize an existing macro YAML file in-place.++ Finds all steps with action=type_text, runs the interactive flow,+ updates the file, and returns True if any changes were made.+ """+ p = Path(yaml_path)+ if not p.is_file():+ raise FileNotFoundError(f"Macro file not found: {yaml_path}")++ with open(p, encoding="utf-8") as f:+ macro = yaml.safe_load(f)++ if not isinstance(macro, dict):+ raise ValueError("Invalid macro YAML: expected a mapping at top level.")++ steps: list[dict] = macro.get("steps") or []+ type_steps_raw = [+ (i, s) for i, s in enumerate(steps)+ if isinstance(s, dict)+ and s.get("action") == "type_text"+ and s.get("params", {}).get("text", "").strip()+ # Skip already-parameterized steps+ and not s["params"]["text"].startswith("${")+ ]++ if not type_steps_raw:+ print(" No hardcoded type_text steps found to parameterize.")+ return False++ # Wrap in lightweight objects for interactive_parameterize+ wrapped = [+ (i, _YamlTypeStep(i, s))+ for i, s in type_steps_raw+ ]++ existing_params = set((macro.get("parameters") or {}).keys())+ assignments = interactive_parameterize(wrapped, existing_params)++ if not assignments:+ return False++ # Apply in-place and collect parameter specs+ parameters: dict = dict(macro.get("parameters") or {})+ for idx, param_name in assignments.items():+ yw = next(w for i, w in wrapped if i == idx)+ original = yw.text+ yw.apply(param_name)++ # Infer type+ ptype = "string"+ try:+ int(original); ptype = "integer"+ except ValueError:+ try:+ float(original); ptype = "float"+ except ValueError:+ pass++ parameters[param_name] = {+ "type": ptype,+ "required": True,+ "description": f"Value typed at step {idx + 1}",+ "example": original,+ }++ macro["parameters"] = parameters++ with open(p, "w", encoding="utf-8") as f:+ yaml.dump(macro, f, allow_unicode=True, sort_keys=False,+ default_flow_style=False)++ print(f"\n ✓ Updated: {p.resolve()}")+ return True+++# ── Gemini-assisted parameterization ─────────────────────────────────────────++def gemini_suggest_parameters(+ type_steps: list[tuple[int, object]],+ api_key: Optional[str] = None,+ model: str = "gemini-1.5-flash",+) -> dict[int, str]:+ """Use Gemini to suggest which type_text steps should be parameterized+ and what to name the parameters.++ Args:+ type_steps: Same format as interactive_parameterize input.+ api_key: Gemini API key. Falls back to GEMINI_API_KEY env var.+ model: Gemini model name.++ Returns:+ {list_index: suggested_param_name} — same shape as interactive output.+ The caller can pass this directly to recorder.apply_parameterization()+ or show it to the user for confirmation first.+ """+ import json+ import os++ try:+ import google.generativeai as genai+ except ImportError:+ raise ImportError(+ "google-generativeai required for auto-parameterization.\n"+ " pip install google-generativeai"+ )++ key = api_key or os.environ.get("GEMINI_API_KEY", "")+ if not key:+ raise ValueError(+ "Gemini API key required. Pass --api-key or set GEMINI_API_KEY.\n"+ " https://aistudio.google.com/app/apikey"+ )++ genai.configure(api_key=key)++ _SYSTEM = """\+You are a macro parameterization assistant. Given a list of text values+that a user typed during a GUI recording session, decide which ones should+become CLI parameters (so the macro can be reused with different values)+and suggest a snake_case parameter name for each.++Rules:+- File paths, URLs, usernames, numeric sizes/counts → ALWAYS parameterize+- Generic user content (e.g. document body text) → parameterize if variable+- Fixed UI inputs that never change (e.g. "OK", "yes", "1") → do NOT parameterize+- Parameter names: lowercase, snake_case, descriptive (e.g. output_path, width)++Output ONLY a JSON object mapping the step index (as a string) to the+parameter name, for steps that SHOULD be parameterized.+Steps that should NOT be parameterized must be omitted entirely.+Example: {"0": "output_path", "2": "export_width"}+"""++ items = "\n".join(+ f' index {idx}: {step.text!r}' # type: ignore[attr-defined]+ for idx, step in type_steps+ )+ prompt = f"Typed values from the recording:\n{items}\n\nOutput JSON only."++ gem = genai.GenerativeModel(model_name=model, system_instruction=_SYSTEM)+ response = gem.generate_content(prompt)+ raw = response.text.strip()++ # Strip markdown fences if present+ if raw.startswith("```"):+ raw = "\n".join(+ line for line in raw.split("\n")+ if not line.startswith("```")+ ).strip()++ try:+ raw_dict: dict = json.loads(raw)+ except json.JSONDecodeError as e:+ raise ValueError(+ f"Gemini returned invalid JSON: {e}\nRaw: {raw[:300]}"+ )++ # Convert string keys to int, validate names+ result: dict[int, str] = {}+ for k, v in raw_dict.items():+ try:+ idx = int(k)+ except ValueError:+ continue+ if not isinstance(v, str) or not _valid_param_name(v):+ continue+ # Check the index is actually in the provided steps+ if any(i == idx for i, _ in type_steps):+ result[idx] = v++ return resultdiff --git a/macrocli/agent-harness/cli_anything/macrocli/core/recorder.py b/macrocli/agent-harness/cli_anything/macrocli/core/recorder.pyindex ce75bfa5f..0285e65bc 100644--- a/macrocli/agent-harness/cli_anything/macrocli/core/recorder.py+++ b/macrocli/agent-harness/cli_anything/macrocli/core/recorder.py@@ -519,8 +519,14 @@ class MacroRecorder:# ── YAML output ───────────────────────────────────────────────────────────- def to_yaml(self) -> str:- """Generate macro YAML from recorded steps."""+ def to_yaml(self, parameters: Optional[dict] = None) -> str:+ """Generate macro YAML from recorded steps.++ Args:+ parameters: Dict of {param_name: spec} built by+ apply_parameterization(). If None, all type_text+ values remain hardcoded.+ """steps = [s.to_step_dict() for s in self._steps if s.to_step_dict()]macro = {@@ -528,7 +534,7 @@ class MacroRecorder:"version": "1.0","description": f"Recorded macro: {self.macro_name}","tags": ["recorded", "visual_anchor"],- "parameters": {},+ "parameters": parameters or {},"preconditions": [],"steps": steps,"postconditions": [],@@ -540,13 +546,64 @@ class MacroRecorder:"recorded": True,},}- return yaml.dump(macro, allow_unicode=True, sort_keys=False, default_flow_style=False)+ return yaml.dump(macro, allow_unicode=True, sort_keys=False,+ default_flow_style=False)- def save(self, output_path: Optional[str] = None) -> str:+ def save(self, output_path: Optional[str] = None,+ parameters: Optional[dict] = None) -> str:"""Write the generated YAML to a file. Returns the path."""if output_path is None:output_path = str(self.output_dir / f"{self.macro_name}.yaml")Path(output_path).parent.mkdir(parents=True, exist_ok=True)- Path(output_path).write_text(self.to_yaml(), encoding="utf-8")+ Path(output_path).write_text(+ self.to_yaml(parameters=parameters), encoding="utf-8"+ )print(f"[recorder] Saved macro to: {output_path}", flush=True)return output_path++ # ── Parameterization ──────────────────────────────────────────────────────++ def get_type_steps(self) -> list[tuple[int, "RecordedStep"]]:+ """Return (list_index, step) for every non-empty type_text step."""+ return [+ (i, s) for i, s in enumerate(self._steps)+ if s.kind == "type" and s.text.strip()+ ]++ def apply_parameterization(+ self, assignments: dict[int, str]+ ) -> dict[str, dict]:+ """Replace type_text values with ${param} placeholders in-place.++ Args:+ assignments: {list_index: param_name} for steps to parameterize.+ Steps not present keep their hardcoded value.++ Returns:+ parameters block ready to pass into to_yaml().+ """+ parameters: dict[str, dict] = {}+ for idx, param_name in assignments.items():+ step = self._steps[idx]+ original = step.text+ step.text = f"${{{param_name}}}"++ # Infer type from the original value+ ptype = "string"+ try:+ int(original)+ ptype = "integer"+ except ValueError:+ try:+ float(original)+ ptype = "float"+ except ValueError:+ pass++ parameters[param_name] = {+ "type": ptype,+ "required": True,+ "description": f"Value typed at step {idx + 1}",+ "example": original,+ }+ return parametersdiff --git a/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py b/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.pyindex 17ce9fbb5..e47697310 100644--- a/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py+++ b/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py@@ -18,6 +18,7 @@ Usage (REPL):import sysimport osimport json+from pathlib import Pathimport clickfrom typing import Optional@@ -432,14 +433,32 @@ def macro_define(name, output):help="Directory to write <name>.yaml and <name>_templates/.")@click.option("--timeout", default=0, type=float,help="Auto-stop after N seconds (0 = wait for Ctrl+Alt+S).")[email protected]("--parameterize", "do_parameterize", is_flag=True,+ help="After recording, interactively choose which typed values "+ "become CLI parameters.")[email protected]("--auto-parameterize", "do_auto_param", is_flag=True,+ help="After recording, use Gemini to automatically suggest "+ "parameter names (requires --api-key or GEMINI_API_KEY).")[email protected]("--api-key", default=None, envvar="GEMINI_API_KEY",+ help="Gemini API key for --auto-parameterize.")@handle_error-def macro_record(name, output_dir, timeout):+def macro_record(name, output_dir, timeout, do_parameterize, do_auto_param, api_key):"""Record GUI interactions and generate a macro YAML.\bStart recording, perform your GUI workflow, then press Ctrl+Alt+S to stop.- Each mouse click is saved with a screenshot template so the macro is- robust to window position changes.+ Each click is anchored to the focused window (robust to window movement).++ \b+ Examples:+ # Basic recording+ macro record my_export++ # Record + interactively parameterize typed values+ macro record my_export --parameterize++ # Record + auto-parameterize with Gemini+ macro record my_export --auto-parameterize --api-key $GEMINI_API_KEYRequires: pip install mss Pillow pynput"""@@ -449,6 +468,13 @@ def macro_record(name, output_dir, timeout):click.echo(f"Error: {e}", err=True)sys.exit(1)+ if do_parameterize and do_auto_param:+ click.echo(+ "Error: --parameterize and --auto-parameterize are mutually exclusive.",+ err=True,+ )+ sys.exit(1)+recorder = MacroRecorder(macro_name=name, output_dir=output_dir)if not _json_output:@@ -456,7 +482,6 @@ def macro_record(name, output_dir, timeout):try:recorder.record(timeout_s=timeout if timeout > 0 else None)- yaml_path = recorder.save()except Exception as e:if _json_output:output({"error": str(e), "success": False})@@ -466,22 +491,202 @@ def macro_record(name, output_dir, timeout):sys.exit(1)return+ # ── Parameterization phase ────────────────────────────────────────────────+ parameters = None+ type_steps = recorder.get_type_steps()++ if do_auto_param and type_steps:+ try:+ from cli_anything.macrocli.core.parameterize import (+ gemini_suggest_parameters,+ interactive_parameterize,+ )+ if not _json_output:+ click.echo(f"\nAsking Gemini to suggest parameters for "+ f"{len(type_steps)} type_text step(s)...")+ suggestions = gemini_suggest_parameters(+ type_steps, api_key=api_key+ )+ if suggestions and not _json_output:+ click.echo(" Gemini suggestions:")+ for idx, pname in suggestions.items():+ step = recorder._steps[idx]+ click.echo(f" step {idx+1} {step.text!r} → ${{{pname}}}")+ click.echo()+ # Still allow user to confirm/adjust+ confirmed = interactive_parameterize(+ [(i, s) for i, s in type_steps if i in suggestions],+ existing_params=set(),+ )+ # For steps Gemini suggested but user skipped, remove them+ final = {i: n for i, n in suggestions.items() if i in confirmed}+ # For steps user renamed, use their name+ final.update(confirmed)+ parameters = recorder.apply_parameterization(final)+ elif not suggestions and not _json_output:+ click.echo(" Gemini found no values to parameterize.")+ except Exception as e:+ click.echo(f" Warning: Gemini parameterization failed: {e}", err=True)+ click.echo(" Falling back to interactive mode...")+ do_parameterize = True++ if do_parameterize and type_steps:+ from cli_anything.macrocli.core.parameterize import interactive_parameterize+ assignments = interactive_parameterize(type_steps)+ if assignments:+ parameters = recorder.apply_parameterization(assignments)++ try:+ yaml_path = recorder.save(parameters=parameters)+ except Exception as e:+ if _json_output:+ output({"error": str(e), "success": False})+ else:+ click.echo(f"Error saving macro: {e}", err=True)+ if not _repl_mode:+ sys.exit(1)+ return+if _json_output:output({"success": True,"yaml_path": yaml_path,"steps": len(recorder._steps),+ "parameters": list((parameters or {}).keys()),"templates_dir": str(recorder.templates_dir),})else:click.echo(f"✓ Saved {len(recorder._steps)} steps to: {yaml_path}")+ if parameters:+ click.echo(f" Parameters: {', '.join(parameters.keys())}")click.echo(f" Templates: {recorder.templates_dir}/")click.echo(- "\n Next: register the macro in macro_definitions/manifest.yaml\n"- " or run it directly with: macro run --macro-file " + yaml_path+ "\n Run it with:\n"+ f" macro run {name} --macro-file {yaml_path}"+ + (+ "".join(f" --param {k}=<value>" for k in (parameters or {}))+ if parameters else ""+ ))[email protected]("parameterize")[email protected]("yaml_file")[email protected]("--auto", "do_auto", is_flag=True,+ help="Use Gemini to suggest parameter names automatically.")[email protected]("--api-key", default=None, envvar="GEMINI_API_KEY",+ help="Gemini API key for --auto.")+@handle_error+def macro_parameterize(yaml_file, do_auto, api_key):+ """Interactively parameterize typed values in an existing macro YAML.++ \b+ Finds all hardcoded type_text steps in the file and lets you choose+ which values become CLI parameters (e.g. ${output_path}).++ \b+ Examples:+ macro parameterize /tmp/recording/my_export.yaml+ macro parameterize my_export.yaml --auto --api-key $GEMINI_API_KEY+ """+ from cli_anything.macrocli.core.parameterize import (+ parameterize_yaml_file,+ gemini_suggest_parameters,+ interactive_parameterize,+ _YamlTypeStep,+ )++ p = Path(yaml_file)+ if not p.is_file():+ click.echo(f"Error: file not found: {yaml_file}", err=True)+ if not _repl_mode:+ sys.exit(1)+ return++ if do_auto:+ # Load the file, extract type_text steps, ask Gemini, then apply+ import yaml as _yaml+ with open(p, encoding="utf-8") as f:+ macro_dict = _yaml.safe_load(f)++ steps = macro_dict.get("steps") or []+ type_steps_raw = [+ (i, s) for i, s in enumerate(steps)+ if isinstance(s, dict)+ and s.get("action") == "type_text"+ and not s.get("params", {}).get("text", "").startswith("${")+ ]+ if not type_steps_raw:+ click.echo("No hardcoded type_text steps found.")+ return++ wrapped = [(i, _YamlTypeStep(i, s)) for i, s in type_steps_raw]++ try:+ click.echo(f"Asking Gemini to suggest parameters for "+ f"{len(wrapped)} type_text step(s)...")+ suggestions = gemini_suggest_parameters(wrapped, api_key=api_key)+ except Exception as e:+ click.echo(f"Gemini failed: {e}\nFalling back to interactive.", err=True)+ suggestions = {}+ do_auto = False++ if suggestions:+ click.echo(" Suggestions:")+ for idx, pname in suggestions.items():+ w = next(w for i, w in wrapped if i == idx)+ click.echo(f" step {idx+1} {w.text!r} → ${{{pname}}}")+ click.echo()++ # Let user confirm (pre-fill Gemini suggestions as defaults)+ existing = set((macro_dict.get("parameters") or {}).keys())+ confirmed = interactive_parameterize(+ [(i, w) for i, w in wrapped if i in suggestions],+ existing_params=existing,+ )+ final = {**suggestions, **confirmed}++ if not final:+ click.echo("No parameters applied.")+ return++ # Apply and save+ import yaml as _yaml+ from cli_anything.macrocli.core.recorder import MacroRecorder+ parameters: dict = dict(macro_dict.get("parameters") or {})+ for idx, param_name in final.items():+ w = next(w for i, w in wrapped if i == idx)+ original = w.text+ w.apply(param_name)+ ptype = "string"+ try:+ int(original); ptype = "integer"+ except ValueError:+ try:+ float(original); ptype = "float"+ except ValueError:+ pass+ parameters[param_name] = {+ "type": ptype, "required": True,+ "description": f"Value typed at step {idx+1}",+ "example": original,+ }+ macro_dict["parameters"] = parameters+ with open(p, "w", encoding="utf-8") as f:+ _yaml.dump(macro_dict, f, allow_unicode=True,+ sort_keys=False, default_flow_style=False)+ if _json_output:+ output({"success": True, "file": str(p.resolve()),+ "parameters": list(final.values())})+ else:+ click.echo(f"✓ Updated: {p.resolve()}")+ click.echo(f" Parameters added: {', '.join(final.values())}")+ else:+ changed = parameterize_yaml_file(yaml_file)+ if _json_output:+ output({"success": True, "changed": changed, "file": str(p.resolve())})++@macro.command("assist")@click.argument("name")@click.option("--goal", "-g", required=True,