Skip to content

"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.py
new file mode 100644
index 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 result
diff --git a/macrocli/agent-harness/cli_anything/macrocli/core/recorder.py b/macrocli/agent-harness/cli_anything/macrocli/core/recorder.py
index 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 parameters
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py b/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py
index 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 sys
import os
import json
+from pathlib import Path
import click
from 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.
\b
Start 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_KEY
Requires: 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,