feat: add a README file for the auto search

Author: shangkunwang01

MaxKernel/auto_search/README.md

@@ -0,0 +1,68 @@
+# MaxKernel Auto-Search
+
+This directory contains the automated search orchestration framework for `MaxKernel`. It leverages autonomous LLM-based worker agents to systematically search for optimized kernel implementations (like Pallas or Triton) for reference JAX benchmark problems. 
+
+## Search Algorithms
+The framework currently supports two primary search topologies:
+1. **Parallel Search (`--algorithm parallel`)**: Dispatches multiple independent worker agents in parallel to optimize the reference kernel. The best performing candidate across all parallel runs is returned.
+2. **Beam Search (`--algorithm beam`)**: A more structured tree-search approach that explores multiple optimization strategies (branches) concurrently, evaluates their latency, and keeps only the top `beam_size` candidates at each depth before expanding further.
+
+---
+
+## Usage
+
+### 1. Run Search on a Single Problem
+Use `run_search.py` to optimize a single benchmark directory. The directory must contain a valid `reference.py` file.
+
+**Example (Beam Search):**
+```bash
+python -m auto_search.run_search \
+  --problem_dir /path/to/problem_dir \
+  --algorithm beam \
+  --beam_size 2 \
+  --branches_per_node 2 \
+  --max_depth 3 \
+  --max_concurrency 4
+```
+
+### 2. Run Batch Search on a Dataset
+Use `run_batch_search.py` to optimize an entire dataset containing multiple problem directories concurrently.
+
+**Example (Parallel Search):**
+```bash
+python -m auto_search.run_batch_search \
+  --data_dir /path/to/dataset_dir \
+  --algorithm parallel \
+  --num_parallel_runs 4 \
+  --num_problem_concurrency 2 \
+  --max_concurrency 8
+```
+
+---
+
+## Key Arguments
+
+### General Orchestration Arguments
+* `--algorithm` : The algorithm to use (`parallel`, `beam`). Default is `parallel`.
+* `--max_concurrency`: The maximum number of concurrent LLM agent workers to spawn at any given time.
+* `--max_worker_retries`: Maximum times a worker is allowed to retry if the generated kernel crashes or fails syntax checks.
+* `--strategies`: (Optional) Space-separated list of explicit strategies to explore (e.g., `--strategies "Fuse operations" "Vectorize loops"`).
+* `--agent_config`: (Optional) JSON string of internal agent parameters. Available parameters:
+  * `"max_iterations"` (int): Maximum number of improvement loop iterations (default: 2).
+  * `"end_agent"` (string): The sub-agent pipeline stage at which to terminate early (e.g., `"validate_agent"`, `"test_run_agent"`).
+  * `"session_dir"` (string): Explicit path for session artifacts (usually auto-generated by the worker).
+  * Example: `'{"max_iterations": 5, "end_agent": "validate_agent"}'`.
+* `--log_file`: File path to save the orchestration logs (creates separate `agent.log` and main logs).
+* `--graph_db_path`: *(Single-problem only)* Explicit path to a `search_graph.json` file to resume a previously interrupted search.
+
+### Parallel Search Specific Arguments
+* `--num_parallel_runs`: Number of independent agents to spawn to tackle the problem simultaneously.
+
+### Beam Search Specific Arguments
+* `--beam_size`: Number of top-performing candidates to retain at each depth of the search tree.
+* `--branches_per_node`: Number of new optimization strategies to explore from each retained node.
+* `--max_depth`: Maximum depth of the beam search tree before terminating.
+* `--keep_factor`: Factor of parent latency required to keep a candidate. For example, `1.0` means the child must be strictly faster (lower latency) than its parent to survive pruning.
+
+### Batch Search Specific Arguments
+* `--num_problem_concurrency`: Number of distinct dataset problems to optimize concurrently.