machineconfig 3.7__py3-none-any.whl → 7.69__py3-none-any.whl

machineconfig/scripts/python/helpers/repo_rag.py

@@ -0,0 +1,325 @@
+# #!/usr/bin/env python3
+# from pathlib import Path
+# from typing import Annotated
+# import subprocess
+# import typer
+# from rich.console import Console
+# from rich.progress import Progress, SpinnerColumn, TextColumn
+# from rich.table import Table
+# from rich.syntax import Syntax
+
+# import chromadb
+# from chromadb.config import Settings
+# from sentence_transformers import SentenceTransformer
+
+
+# app = typer.Typer(help="Semantic search over your repository using local RAG")
+# console = Console()
+
+
+# DEFAULT_EXTENSIONS = [".py", ".sh", ".ps1", ".md", ".toml", ".yaml", ".yml", ".json"]
+# DEFAULT_MODEL = "all-MiniLM-L6-v2"
+# DEFAULT_DB_PATH = Path.home() / ".cache" / "repo_rag"
+
+
+# class RepoRAG:
+#     def __init__(self, db_path: Path, model_name: str = DEFAULT_MODEL) -> None:
+#         self.db_path = db_path
+#         self.db_path.mkdir(parents=True, exist_ok=True)
+        
+#         with console.status(f"[bold green]Loading embedding model: {model_name}..."):
+#             self.model = SentenceTransformer(model_name)
+        
+#         self.client = chromadb.PersistentClient(
+#             path=str(db_path),
+#             settings=Settings(anonymized_telemetry=False)
+#         )
+        
+#     def _get_or_create_collection(self, repo_path: Path) -> chromadb.Collection:
+#         collection_name = f"repo_{repo_path.name}".replace("-", "_").replace(".", "_")
+#         return self.client.get_or_create_collection(
+#             name=collection_name,
+#             metadata={"repo_path": str(repo_path)}
+#         )
+    
+#     def _chunk_file_content(self, content: str, chunk_size: int = 500, overlap: int = 50) -> list[str]:
+#         lines = content.split("\n")
+#         chunks: list[str] = []
+#         current_chunk: list[str] = []
+#         current_size = 0
+        
+#         for line in lines:
+#             line_size = len(line)
+#             if current_size + line_size > chunk_size and current_chunk:
+#                 chunks.append("\n".join(current_chunk))
+#                 overlap_lines = current_chunk[-overlap:] if len(current_chunk) > overlap else current_chunk
+#                 current_chunk = overlap_lines
+#                 current_size = sum(len(line_text) for line_text in current_chunk)
+            
+#             current_chunk.append(line)
+#             current_size += line_size
+        
+#         if current_chunk:
+#             chunks.append("\n".join(current_chunk))
+        
+#         return chunks if chunks else [content]
+    
+#     def index_repo(self, repo_path: Path, extensions: list[str], max_file_size_kb: int = 500) -> None:
+#         collection = self._get_or_create_collection(repo_path)
+        
+#         files_to_index: list[Path] = []
+#         for ext in extensions:
+#             files_to_index.extend(repo_path.rglob(f"*{ext}"))
+        
+#         files_to_index = [
+#             f for f in files_to_index 
+#             if not any(part.startswith('.') for part in f.relative_to(repo_path).parts[:-1])
+#             and f.stat().st_size < max_file_size_kb * 1024
+#         ]
+        
+#         console.print(f"[bold cyan]Found {len(files_to_index)} files to index")
+        
+#         with Progress(
+#             SpinnerColumn(),
+#             TextColumn("[progress.description]{task.description}"),
+#             console=console
+#         ) as progress:
+#             task = progress.add_task("Indexing files...", total=len(files_to_index))
+            
+#             for file_path in files_to_index:
+#                 try:
+#                     content = file_path.read_text(encoding="utf-8", errors="ignore")
+#                     rel_path = str(file_path.relative_to(repo_path))
+                    
+#                     chunks = self._chunk_file_content(content)
+                    
+#                     for i, chunk in enumerate(chunks):
+#                         doc_id = f"{rel_path}::chunk_{i}"
+#                         embedding = self.model.encode(chunk).tolist()
+                        
+#                         collection.upsert(
+#                             ids=[doc_id],
+#                             embeddings=[embedding],
+#                             documents=[chunk],
+#                             metadatas=[{
+#                                 "file_path": rel_path,
+#                                 "chunk_index": i,
+#                                 "total_chunks": len(chunks),
+#                                 "extension": file_path.suffix
+#                             }]
+#                         )
+                    
+#                 except Exception as e:
+#                     console.print(f"[yellow]Warning: Failed to index {file_path}: {e}")
+                
+#                 progress.advance(task)
+        
+#         console.print("[bold green]✓ Indexing complete!")
+    
+#     def search(self, repo_path: Path, query: str, n_results: int = 20) -> list[dict[str, str | dict[str, str | int]]]:
+#         collection = self._get_or_create_collection(repo_path)
+        
+#         with console.status("[bold green]Searching..."):
+#             query_embedding = self.model.encode(query).tolist()
+#             results = collection.query(
+#                 query_embeddings=[query_embedding],
+#                 n_results=n_results
+#             )
+        
+#         if not results["ids"] or not results["ids"][0]:
+#             return []
+        
+#         search_results: list[dict[str, str | dict[str, str | int]]] = []
+#         for i, doc_id in enumerate(results["ids"][0]):
+#             search_results.append({
+#                 "id": doc_id,
+#                 "file_path": results["metadatas"][0][i]["file_path"],
+#                 "content": results["documents"][0][i],
+#                 "distance": results["distances"][0][i] if results.get("distances") else 0.0,
+#                 "metadata": results["metadatas"][0][i]
+#             })
+        
+#         return search_results
+    
+#     def delete_index(self, repo_path: Path) -> None:
+#         collection_name = f"repo_{repo_path.name}".replace("-", "_").replace(".", "_")
+#         try:
+#             self.client.delete_collection(name=collection_name)
+#             console.print(f"[bold green]✓ Deleted index for {repo_path.name}")
+#         except Exception as e:
+#             console.print(f"[bold red]Error deleting index: {e}")
+
+
+# @app.command()
+# def index(
+#     repo_path: Annotated[Path, typer.Argument(help="Path to repository to index")] = Path.cwd(),
+#     extensions: Annotated[str, typer.Option("--ext", "-e", help="Comma-separated list of extensions")] = ",".join(DEFAULT_EXTENSIONS),
+#     model: Annotated[str, typer.Option("--model", "-m", help="Sentence transformer model name")] = DEFAULT_MODEL,
+#     db_path: Annotated[Path, typer.Option("--db", help="Database path")] = DEFAULT_DB_PATH,
+#     max_size_kb: Annotated[int, typer.Option("--max-size", help="Max file size in KB")] = 500,
+# ) -> None:
+#     repo_path = repo_path.resolve()
+    
+#     if not repo_path.exists():
+#         console.print(f"[bold red]Error: Repository path does not exist: {repo_path}")
+#         raise typer.Exit(1)
+    
+#     ext_list = [ext.strip() if ext.startswith(".") else f".{ext.strip()}" for ext in extensions.split(",")]
+    
+#     console.print(f"[bold cyan]Repository:[/] {repo_path}")
+#     console.print(f"[bold cyan]Extensions:[/] {', '.join(ext_list)}")
+#     console.print(f"[bold cyan]Model:[/] {model}")
+#     console.print(f"[bold cyan]Database:[/] {db_path}")
+#     console.print()
+    
+#     rag = RepoRAG(db_path, model)
+#     rag.index_repo(repo_path, ext_list, max_size_kb)
+
+
+# @app.command()
+# def search(
+#     query: Annotated[str, typer.Argument(help="Search query")],
+#     repo_path: Annotated[Path, typer.Option("--repo", "-r", help="Path to repository")] = Path.cwd(),
+#     n_results: Annotated[int, typer.Option("--num", "-n", help="Number of results")] = 20,
+#     model: Annotated[str, typer.Option("--model", "-m", help="Sentence transformer model name")] = DEFAULT_MODEL,
+#     db_path: Annotated[Path, typer.Option("--db", help="Database path")] = DEFAULT_DB_PATH,
+#     use_fzf: Annotated[bool, typer.Option("--fzf", help="Use fzf for interactive selection")] = True,
+#     show_content: Annotated[bool, typer.Option("--content", "-c", help="Show content snippets")] = True,
+# ) -> None:
+#     repo_path = repo_path.resolve()
+    
+#     if not repo_path.exists():
+#         console.print(f"[bold red]Error: Repository path does not exist: {repo_path}")
+#         raise typer.Exit(1)
+    
+#     rag = RepoRAG(db_path, model)
+#     results = rag.search(repo_path, query, n_results)
+    
+#     if not results:
+#         console.print("[yellow]No results found")
+#         raise typer.Exit(0)
+    
+#     if use_fzf:
+#         _search_with_fzf(results, repo_path, show_content)
+#     else:
+#         _display_results(results, show_content)
+
+
+# def _display_results(results: list[dict[str, str | dict[str, str | int]]], show_content: bool) -> None:
+#     table = Table(title="Search Results", show_header=True, header_style="bold magenta")
+#     table.add_column("#", style="cyan", width=4)
+#     table.add_column("File", style="green")
+#     table.add_column("Chunk", style="yellow", width=8)
+#     table.add_column("Score", style="blue", width=8)
+#     if show_content:
+#         table.add_column("Content Preview", style="white", width=60)
+    
+#     for i, result in enumerate(results, 1):
+#         file_path = str(result["file_path"])
+#         metadata = result["metadata"]
+#         chunk_info = f"{int(metadata['chunk_index']) + 1}/{int(metadata['total_chunks'])}"
+#         score = f"{float(result['distance']):.3f}"
+        
+#         row = [str(i), file_path, chunk_info, score]
+        
+#         if show_content:
+#             content = str(result["content"])
+#             preview = content[:200].replace("\n", " ") + ("..." if len(content) > 200 else "")
+#             row.append(preview)
+        
+#         table.add_row(*row)
+    
+#     console.print(table)
+
+
+# def _search_with_fzf(results: list[dict[str, str | dict[str, str | int]]], repo_path: Path, show_content: bool) -> None:
+#     try:
+#         fzf_input_lines: list[str] = []
+#         for i, result in enumerate(results, 1):
+#             file_path = str(result["file_path"])
+#             metadata = result["metadata"]
+#             chunk_info = f"{int(metadata['chunk_index']) + 1}/{int(metadata['total_chunks'])}"
+#             score = f"{float(result['distance']):.3f}"
+            
+#             if show_content:
+#                 content = str(result["content"]).replace("\n", " ")[:100]
+#                 line = f"{i:3d} │ {score:6s} │ {chunk_info:5s} │ {file_path:60s} │ {content}"
+#             else:
+#                 line = f"{i:3d} │ {score:6s} │ {chunk_info:5s} │ {file_path}"
+            
+#             fzf_input_lines.append(line)
+        
+#         fzf_input = "\n".join(fzf_input_lines)
+        
+#         result = subprocess.run(
+#             ["fzf", "--ansi", "--multi", "--reverse", "--header=Select files to open (TAB for multi-select)"],
+#             input=fzf_input.encode(),
+#             capture_output=True
+#         )
+        
+#         if result.returncode != 0:
+#             console.print("[yellow]Selection cancelled")
+#             return
+        
+#         selected_lines = result.stdout.decode().strip().split("\n")
+        
+#         for line in selected_lines:
+#             if not line:
+#                 continue
+            
+#             parts = line.split("│")
+#             if len(parts) < 4:
+#                 continue
+            
+#             file_path_str = parts[3].strip().split()[0]
+            
+#             idx = int(parts[0].strip()) - 1
+#             if idx < len(results):
+#                 content = str(results[idx]["content"])
+                
+#                 console.print(f"\n[bold green]File:[/] {file_path_str}")
+#                 console.print("[bold cyan]Content:[/]")
+                
+#                 syntax = Syntax(content, "python", theme="monokai", line_numbers=True)
+#                 console.print(syntax)
+#                 console.print("\n" + "─" * 80 + "\n")
+    
+#     except FileNotFoundError:
+#         console.print("[bold red]Error: fzf not found. Install fzf or use --no-fzf flag")
+#         _display_results(results, show_content)
+
+
+# @app.command()
+# def delete(
+#     repo_path: Annotated[Path, typer.Argument(help="Path to repository")] = Path.cwd(),
+#     db_path: Annotated[Path, typer.Option("--db", help="Database path")] = DEFAULT_DB_PATH,
+#     model: Annotated[str, typer.Option("--model", "-m", help="Sentence transformer model name")] = DEFAULT_MODEL,
+# ) -> None:
+#     repo_path = repo_path.resolve()
+#     rag = RepoRAG(db_path, model)
+#     rag.delete_index(repo_path)
+
+
+# @app.command()
+# def info() -> None:
+#     console.print("[bold cyan]Repo RAG - Semantic Code Search[/]\n")
+    
+#     info_table = Table(show_header=False, box=None)
+#     info_table.add_column("Key", style="cyan")
+#     info_table.add_column("Value", style="white")
+    
+#     info_table.add_row("Embedding Model", DEFAULT_MODEL)
+#     info_table.add_row("Vector Store", "ChromaDB (embedded)")
+#     info_table.add_row("Default Extensions", ", ".join(DEFAULT_EXTENSIONS))
+#     info_table.add_row("Database Path", str(DEFAULT_DB_PATH))
+    
+#     console.print(info_table)
+    
+#     console.print("\n[bold green]Quick Start:[/]")
+#     console.print("1. Index your repo:     [yellow]repo-rag index[/]")
+#     console.print("2. Search semantically: [yellow]repo-rag search 'your query'[/]")
+#     console.print("3. Delete index:        [yellow]repo-rag delete[/]")
+
+
+# if __name__ == "__main__":
+#     app()

machineconfig/scripts/python/helpers/symantic_search.py

@@ -0,0 +1,25 @@
+"""
+please fully read docs of https://github.com/meilisearch/meilisearch-python
+
+then make a cli using typer in this file
+
+I want commands to
+create-index (pass name of index)
+command to populate the index with files in folder
+command is add-to-index
+--directory [str] and --extensions .py,.ps1,.sh
+
+command to rebuild index
+
+coimmand to search
+command show stats and rop index
+
+learn from my style of building apps like this #file:msearch.py 
+
+and add option when building index to say --symantic (means use ai locall embedding to build the index)
+
+in all cases we should be able to pass
+MEILI_URL="http://localhost:7700" (default)
+MEILI_MASTER_KEY="YOUR_MASTER_KEY"
+
+"""

machineconfig/scripts/python/helpers_agents/agentic_frameworks/fire_crush.json

@@ -0,0 +1,14 @@
+{
+    "models": {
+        "large": {
+            "model": "{model}",
+            "provider": "{provider}",
+            "max_tokens": 100000
+        }
+    },
+    "providers": {
+        "openrouter": {
+            "api_key": "{api_key}"
+        }
+    }
+}

machineconfig/scripts/python/helpers_agents/agentic_frameworks/fire_crush.py

@@ -0,0 +1,37 @@
+
+from pathlib import Path
+# import shlex
+from machineconfig.scripts.python.helpers_agents.fire_agents_helper_types import AI_SPEC
+
+
+def fire_crush(ai_spec: AI_SPEC, prompt_path: Path, repo_root: Path) -> str:
+    match ai_spec["machine"]:
+        case "local":
+            cmd = f"""
+crush run {prompt_path}
+"""
+        case "docker":
+            assert ai_spec["api_key"] is not None, "API key is required for Crush agent in docker mode."
+            json_path = Path(__file__).parent / "fire_crush.json"
+            json_template = json_path.read_text(encoding="utf-8")
+            json_filled = json_template.replace("{api_key}", ai_spec["api_key"]).replace("{model}", ai_spec["model"]).replace("{provider}", ai_spec["provider"])
+            from machineconfig.utils.accessories import randstr
+            temp_config_file_local = Path.home().joinpath("tmp_results/tmp_files/crush_" + randstr(8) + ".json")
+            temp_config_file_local.parent.mkdir(parents=True, exist_ok=True)
+            Path(temp_config_file_local).write_text(json_filled, encoding="utf-8")            
+            cmd = f"""
+
+#   -e "PATH_PROMPT=$PATH_PROMPT"
+#   opencode --model "{ai_spec["provider"]}/{ai_spec["model"]}" run {prompt_path}
+  
+
+echo "Running prompt @ {prompt_path.relative_to(repo_root)} using Docker with Crush..."
+docker run -it --rm \
+  -v "{repo_root}:/workspace/{repo_root.name}" \
+  -v "{temp_config_file_local}:/root/.local/share/crush/crush.json" \
+  -w "/workspace/{repo_root.name}" \
+  statistician/machineconfig-ai:latest \
+  bash -i -c "source ~/.bashrc && cd /workspace/{repo_root.name} && cat /root/.local/share/crush/crush.json && crush run 'Please act on contents of this prompt ./{prompt_path.relative_to(repo_root)}'"
+
+"""
+    return cmd

machineconfig/scripts/python/helpers_agents/agentic_frameworks/fire_cursor_agents.py

@@ -0,0 +1,22 @@
+
+
+from pathlib import Path
+# import shlex
+from machineconfig.scripts.python.helpers_agents.fire_agents_helper_types import AI_SPEC
+
+def fire_cursor(ai_spec: AI_SPEC, prompt_path: Path) -> str:
+    match ai_spec["machine"]:
+        case "local":
+            # Export the environment variable so it's available to subshells
+            cmd = f"""
+
+cursor-agent --print --output-format text {prompt_path}
+
+"""
+        case "docker":
+            cmd = f"""
+
+cursor-agent --print --output-format text {prompt_path}
+
+"""
+    return cmd

machineconfig/scripts/python/helpers_agents/agentic_frameworks/fire_gemini.py

@@ -0,0 +1,42 @@
+
+from pathlib import Path
+import shlex
+from machineconfig.scripts.python.helpers_agents.fire_agents_helper_types import AI_SPEC
+
+
+def fire_gemini(ai_spec: AI_SPEC, prompt_path: Path, repo_root: Path) -> str:
+    _ = ai_spec["provider"]
+    # model = "gemini-2.5-flash-lite"
+    # model = None  # auto-select
+    # if model is None:
+    #     model_arg = ""
+    # else:
+    model_arg = f"--model {shlex.quote(ai_spec['model'])}"
+    # Need a real shell for the pipeline; otherwise '| gemini ...' is passed as args to 'cat'
+    safe_path = shlex.quote(str(prompt_path))
+
+    match ai_spec["machine"]:
+        case "local":
+            # Export the environment variable so it's available to subshells
+            if ai_spec["api_key"] is not None:
+                define_api_key = f"""export GEMINI_API_KEY="{shlex.quote(ai_spec['api_key'])}" """
+            else:
+                define_api_key = "echo 'Warning: No GEMINI_API_KEY provided, hoping it is set in the environment.'"
+            cmd = f"""
+{define_api_key}
+echo "Using Gemini API key $GEMINI_API_KEY"
+gemini {model_arg} --yolo --prompt {safe_path}
+"""
+            
+
+        case "docker":
+            assert ai_spec["api_key"] is not None, "When using docker, api_key must be provided."
+            cmd = f"""
+docker run -it --rm \
+  -e GEMINI_API_KEY="{ai_spec['api_key']}" \
+  -v "{repo_root}:/workspace/{repo_root.name}" \
+  -w "/workspace/{repo_root.name}" \
+  statistician/machineconfig-ai:latest  \
+  gemini --prompt "$PATH_PROMPT"
+"""
+    return cmd

machineconfig/scripts/python/helpers_agents/agentic_frameworks/fire_qwen.py

@@ -0,0 +1,30 @@
+
+from pathlib import Path
+import shlex
+from machineconfig.scripts.python.helpers_agents.fire_agents_helper_types import AI_SPEC
+
+
+def fire_qwen(ai_spec: AI_SPEC, prompt_path: Path, repo_root: Path, config_dir: str | None) -> str:
+    _ = ai_spec["provider"]
+    safe_path = shlex.quote(str(prompt_path))
+    match ai_spec["machine"]:
+        case "local":
+            cmd = f"""
+qwen --yolo --prompt {safe_path}
+    """
+        case "docker":
+            assert config_dir is not None, "When using docker, config_dir must be provided."
+            assert Path(config_dir).exists(), f"Provided config_dir {config_dir} does not exist."
+            oauth_creds = Path(config_dir).joinpath("oauth_creds.json")
+            settings = Path(config_dir).joinpath("settings.json")
+
+            cmd = f"""
+docker run -it --rm \
+  -v "{repo_root}:/workspace/{repo_root.name}" \
+  -v {shlex.quote(str(oauth_creds))}:/root/.qwen/oauth_creds.json \
+  -v {shlex.quote(str(settings))}:/root/.qwen/settings.json \
+  -w "/workspace/{repo_root.name}" \
+  statistician/machineconfig-ai:latest \
+  qwen --prompt "$PATH_PROMPT"
+"""
+    return cmd

machineconfig/scripts/python/helpers_agents/fire_agents_help_launch.py

@@ -0,0 +1,110 @@
+
+import random
+import shlex
+from pathlib import Path
+from machineconfig.scripts.python.helpers_agents.fire_agents_helper_types import AGENTS, AGENT_NAME_FORMATTER, HOST, PROVIDER, AI_SPEC
+
+
+def get_api_keys(provider: PROVIDER) -> list[str]:
+    from machineconfig.utils.io import read_ini
+    config = read_ini(Path.home().joinpath(f"dotfiles/creds/llm/{provider}/api_keys.ini"))
+    res: list[str] = []
+    for a_section_name in list(config.sections()):
+        a_section = config[a_section_name]
+        if "api_key" in a_section:
+            api_key = a_section["api_key"].strip()
+            if api_key:
+                res.append(api_key)
+    print(f"Found {len(res)} {provider} API keys configured.")
+    return res
+
+
+def prep_agent_launch(repo_root: Path, agents_dir: Path, prompts_material: list[str], prompt_prefix: str, keep_material_in_separate_file: bool,
+                      machine: HOST, model: str, provider: PROVIDER, agent: AGENTS, *, job_name: str) -> None:
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    prompt_folder = agents_dir / "prompts"
+    prompt_folder.mkdir(parents=True, exist_ok=True)
+
+    for idx, a_prompt_material in enumerate(prompts_material):
+        prompt_root = prompt_folder / f"agent_{idx}"
+        prompt_root.mkdir(parents=True, exist_ok=True)
+        prompt_path = prompt_root / f"agent_{idx}_prompt.txt"
+        if keep_material_in_separate_file:
+            prompt_material_path = prompt_root / f"agent_{idx}_material.txt"
+            prompt_material_path.write_text(a_prompt_material, encoding="utf-8")
+            prompt_path.write_text(prompt_prefix + f"""\nPlease only look @ {prompt_material_path.relative_to(repo_root)}. You don't need to do any other work beside the content of this material file.""", encoding="utf-8")
+        else:
+            prompt_material_path = prompt_path
+            prompt_path.write_text(prompt_prefix + """\nPlease only look @ the following:\n""" + a_prompt_material, encoding="utf-8")
+
+        agent_cmd_launch_path = prompt_root / AGENT_NAME_FORMATTER.format(idx=idx)  # e.g., agent_0_cmd.sh
+        random_sleep_time = random.uniform(0, 5)
+        cmd_prefix = f"""#!/usr/bin/env bash
+
+echo "Using machine: {machine}, model: {model}, provider: {provider}, and agent: {agent}"
+echo "{job_name}-{idx} CMD {agent_cmd_launch_path}"
+echo "{job_name}-{idx} PROMPT {prompt_path}"
+echo "{job_name}-{idx} CONTEXT {prompt_material_path}"
+echo "Starting agent {agent} in 5 seconds... Press Ctrl+C to cancel."
+# sleep 5
+# timeout 3 copilot --banner
+
+export FIRE_AGENTS_AGENT_NAME="{agent}"
+export FIRE_AGENTS_JOB_NAME="{job_name}"
+export FIRE_AGENTS_PROMPT_FILE="{prompt_path}"
+export FIRE_AGENTS_MATERIAL_FILE="{prompt_material_path}"
+export FIRE_AGENTS_AGENT_LAUNCHER="{agent_cmd_launch_path}"
+
+echo "Sleeping for {random_sleep_time:.2f} seconds to stagger agent startups..."
+sleep {random_sleep_time:.2f}
+echo "--------START OF AGENT OUTPUT--------"
+sleep 0.1
+
+"""
+        match agent:
+            case "gemini":
+                assert provider == "google", "Gemini agent only works with google provider."
+                api_keys = get_api_keys(provider="google")
+                api_key = api_keys[idx % len(api_keys)] if len(api_keys) > 0 else None
+                ai_spec: AI_SPEC = AI_SPEC(provider=provider, model="gemini-2.5-pro", agent=agent, machine=machine, api_key=api_key, api_name="gemini")
+                from machineconfig.scripts.python.helpers_agents.agentic_frameworks.fire_gemini import fire_gemini
+                cmd = fire_gemini(ai_spec=ai_spec, prompt_path=prompt_path, repo_root=repo_root)
+            case "cursor-agent":
+                ai_spec: AI_SPEC = AI_SPEC(provider=provider, model=model, agent=agent, machine=machine, api_key=None, api_name="cursor")
+                from machineconfig.scripts.python.helpers_agents.agentic_frameworks.fire_cursor_agents import fire_cursor
+                cmd = fire_cursor(ai_spec=ai_spec, prompt_path=prompt_path)
+                raise NotImplementedError("Cursor agent is not implemented yet, api key missing")
+            case "crush":
+                api_keys = get_api_keys(provider=provider)
+                api_key = api_keys[idx % len(api_keys)] if len(api_keys) > 0 else None
+                ai_spec: AI_SPEC = AI_SPEC(provider=provider, model=model, agent=agent, machine=machine, api_key=api_key, api_name="crush")
+                from machineconfig.scripts.python.helpers_agents.agentic_frameworks.fire_crush import fire_crush
+                cmd = fire_crush(ai_spec=ai_spec, prompt_path=prompt_path, repo_root=repo_root)
+            # case "q":
+            #     from machineconfig.scripts.python.helpers_fire.fire_q import fire_q
+            #     cmd = fire_q(api_key="", prompt_path=prompt_path, machine=machine)
+            case _:
+                raise ValueError(f"Unsupported agent type: {agent}")
+
+        cmd_postfix = """
+sleep 0.1
+echo "---------END OF AGENT OUTPUT---------"
+"""
+        agent_cmd_launch_path.write_text(cmd_prefix + cmd + cmd_postfix, encoding="utf-8")
+    return None
+
+
+def get_agents_launch_layout(session_root: Path):
+    from machineconfig.utils.schemas.layouts.layout_types import TabConfig, LayoutConfig, LayoutsFile
+
+    tab_config: list[TabConfig] = []
+    prompt_root = session_root / "prompts"
+    all_dirs_under_prompts = [d for d in prompt_root.iterdir() if d.is_dir()]
+    for a_prompt_dir in all_dirs_under_prompts:
+        idx = a_prompt_dir.name.split("_")[-1]  # e.g., agent_0 -> 0
+        agent_cmd_path = a_prompt_dir / AGENT_NAME_FORMATTER.format(idx=idx)
+        fire_cmd = f"bash {shlex.quote(str(agent_cmd_path))}"
+        tab_config.append(TabConfig(tabName=f"Agent{idx}", startDir=str(session_root.parent.parent.parent), command=fire_cmd))
+    layout = LayoutConfig(layoutName="Agents", layoutTabs=tab_config)
+    layouts_file: LayoutsFile = LayoutsFile(version="1.0", layouts=[layout])
+    return layouts_file

machineconfig/scripts/python/helpers_agents/fire_agents_helper_types.py

@@ -0,0 +1,34 @@
+
+from typing import Literal, TypeAlias, TypedDict
+
+
+# Vscode extensions for AI-assisted coding.
+# Github copilot
+# Roo
+# Cline
+# Kilocode
+# Continue
+# CodeGPT
+# qodo (and cli)
+
+# Editors based on AI
+# Kiro
+# Cursor
+# Warp
+
+AGENTS: TypeAlias = Literal["cursor-agent", "gemini", "qwen-code", "copilot", "crush", "q", "opencode", "kilocode", "cline", "auggie", "warp", "droid"]
+HOST: TypeAlias = Literal["local", "docker"]
+PROVIDER: TypeAlias = Literal["azure", "google", "aws", "openai", "anthropic", "openrouter", "xai"]
+
+class AI_SPEC(TypedDict):
+    provider: PROVIDER
+    model: str
+    agent: AGENTS
+    machine: HOST
+    api_key: str | None
+    api_name: str
+
+
+AGENT_NAME_FORMATTER = "agent_{idx}_cmd.sh"  # e.g., agent_0_cmd.sh
+SEARCH_STRATEGIES: TypeAlias = Literal["file_path", "keyword_search", "filename_pattern"]
+

machineconfig/scripts/python/helpers_agents/fire_agents_load_balancer.py

@@ -0,0 +1,22 @@
+# from math import ceil
+from pathlib import Path
+
+
+def chunk_prompts(prompt_material_path: Path, joiner: str, *, tasks_per_prompt: int) -> list[str]:
+    """Chunk prompts based on splitting strategy.
+
+    Args:
+        prompts: List of prompts to chunk
+        strategy: Either 'agent_cap' or 'task_rows'
+        agent_cap: Maximum number of agents (used with 'agent_cap' strategy)
+        task_rows: Number of rows/tasks per agent (used with 'task_rows' strategy)
+    """
+    prompts = [p for p in prompt_material_path.read_text(encoding="utf-8", errors="ignore").split(joiner) if p.strip() != ""]  # drop blank entries
+    if tasks_per_prompt >= len(prompts):
+        print("No need to chunk prompts, as tasks_per_prompt >= total prompts.", f"({tasks_per_prompt} >= {len(prompts)})")
+        return prompts
+    print(f"Chunking {len(prompts)} prompts into groups of {tasks_per_prompt} rows/tasks each.")
+    grouped: list[str] = []
+    for i in range(0, len(prompts), tasks_per_prompt):
+        grouped.append(joiner.join(prompts[i : i + tasks_per_prompt]))
+    return grouped