search-swe 0.1.0__tar.gz

search_swe-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 VectorSpaceLab
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

search_swe-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE docs/cli.md
+recursive-include src/search_swe *.py
+global-exclude *.pyc

search_swe-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: search-swe
+Version: 0.1.0
+Summary: Configure and run Search-SWE coding-agent evaluations
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/VectorSpaceLab/Search-SWE
+Project-URL: Homepage, https://search-swe.github.io/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: harbor==0.22.0
+Requires-Dist: huggingface_hub<2.0,>=1.0
+Requires-Dist: questionary<3,>=2.1
+Requires-Dist: prompt_toolkit<4,>=3.0.48
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: psutil<8,>=7
+Requires-Dist: PyYAML<7,>=6
+Dynamic: license-file
+
+# Search-SWE CLI
+
+Configure coding-agent evaluations interactively, restore fixed inputs, and run
+one model setting across selected Search-SWE tasks sequentially or concurrently.
+For agent-driven operation, install the [evaluation skill](https://github.com/VectorSpaceLab/Search-SWE/blob/main/docs/agent-evaluations.md)
+and describe the settings and tasks to your agent.
+
+## Installation
+
+The distribution name and command are both `search-swe`. Install from PyPI:
+
+```bash
+python -m pip install search-swe
+```
+
+For local CLI development, install from the repository root:
+
+```bash
+python -m pip install -e .
+search-swe --help
+```
+
+Python 3.12+ is required. Package dependencies are declared in
+`pyproject.toml`, including the pinned Harbor version. Use a virtual
+environment to isolate these dependencies. The wheel contains the CLI; task
+definitions, Docker integration and fixed assets live in a Search-SWE checkout.
+Start the wizard to choose or prepare that checkout:
+
+```bash
+search-swe run
+```
+
+When no checkout is found, interactive `run` and `configure` offer three choices:
+clone to `~/Search-SWE`, clone to a custom path, or select an existing checkout.
+Git is required for cloning. Accept the clone destination to download the
+repository's latest `main` snapshot with a shallow clone, then continue with model configuration. A valid
+checkout at the chosen path is reused; cloning uses a new or empty directory.
+
+The selected path is saved in `$XDG_CONFIG_HOME/search-swe/repository.json`
+(default `~/.config/search-swe/repository.json`) and reused by future commands.
+Repository setup completes before model configuration; task assets and results
+belong to the selected checkout, while the CLI stays in the Python environment.
+
+Repository discovery uses `--repo`, then `SEARCH_SWE_REPO`, then the current
+directory and its parents. Editable installations also recognize their source
+checkout, followed by the remembered path. To override discovery, use
+`search-swe --repo /path/to/Search-SWE run`. Scripted commands (`--yes`), dry runs,
+`list` and `doctor` require an existing checkout. With `--offline`, the interactive
+selector offers existing checkouts only.
+
+## Interactive setup
+
+`search-swe` or `search-swe run` opens the terminal wizard:
+
+1. Choose the harness, then a supported provider. Search/select an OpenRouter
+   model, enter a direct-endpoint model ID, or select a supported Pi model.
+   Then choose its reasoning or thinking level.
+2. Enter the coding-agent API key using hidden input, or retain an existing key.
+3. Filter and select tasks with Space, then press Enter. The menu shows their
+   CPU, RAM, GPU and asset requirements.
+4. Configure the selected tasks' required judge credentials. Optional APIs for
+   submitted programs have a separate opt-in prompt.
+5. Choose sequential execution or a maximum parallelism, review the setting and
+   resource requirements, select an idle GPU pool for GPU tasks, then confirm
+   saving and starting.
+
+`search-swe configure` uses the same configuration flow without starting an
+evaluation. Model/harness compatibility follows the existing backend: Codex
+supports OpenRouter and direct endpoints; Claude Code supports its direct
+Anthropic API and Anthropic models through OpenRouter; Pi uses the repository's
+DeepSeek/Z.ai direct adapters.
+
+The default is Codex + OpenRouter + `openai/gpt-6-luna`, with `max` reasoning.
+Custom models must support the selected harness/API; choosing a model does not
+perform a paid connectivity test. Existing task-specific verifier models and
+network allowlists continue to apply.
+
+### OpenRouter model search
+
+The model field searches the public OpenRouter directory by name and model ID
+as you type, including multiple keywords. Use ↓/↑ to highlight a result and
+Enter to select its full ID; matching rows show the name and context length.
+Enter on an empty field keeps the displayed current/default model. A complete
+model ID can also be typed manually for newly available or custom models.
+
+The directory is fetched once and searched locally; typing does not issue API
+requests. Metadata is cached for 24 hours under
+`$XDG_CACHE_HOME/search-swe/openrouter-models.json` (default
+`~/.cache/search-swe/openrouter-models.json`). Use `search-swe run --refresh-models`
+to refresh it, or `--offline` to use the cache without a catalog request. If the
+directory is unavailable, cached results or manual model input remain usable.
+Catalog requests use the public endpoint and carry no API keys.
+
+Suggestions use the selected harness and available text/tool/API metadata;
+Claude Code suggestions are limited to Anthropic models. Metadata filtering
+does not replace an actual harness/model compatibility test. The directory may
+not expose every supported reasoning level. When selecting a new model, the
+wizard starts with **Model/config default**, which omits the explicit effort
+override. Models that list no reasoning support use that setting automatically.
+Other models offer an explicit level selection; choose a level supported by the
+model/provider. The saved model setting is reused on subsequent runs.
+
+`--reasoning-effort default` selects the same behavior in scripted runs. This
+uses the model/harness configuration, including any custom Codex configuration;
+it does not mean that reasoning is disabled. Catalog selection and configuration
+do not start paid model requests.
+
+## Credentials and configuration
+
+Configuration is read from the checkout `.env`, or `--env-file PATH`. Command-line
+and explicit wizard answers take priority over exported variables, then file
+values, then defaults. A saved configuration does not override exported shell
+variables in a later invocation; the wizard identifies conflicting variable names.
+
+Keys are hidden during entry and summaries contain no key values. Saving uses an
+atomic replacement with mode `0600`, preserves unrelated dotenv settings/comments,
+and treats values literally. Saved environment files inside the checkout must be
+Git-ignored. Cancelling before the final confirmation leaves the
+file unchanged. Choose not to save to use entered values only for this run.
+
+`SEARCH_SWE_AGENT`, `SEARCH_SWE_PROVIDER`, `AGENT_MODEL`,
+`AGENT_REASONING_EFFORT` / `PI_THINKING`, and `SEARCH_SWE_CONCURRENCY` hold the
+selected defaults. Keys retain their existing purpose-specific variable names.
+Reusing the OpenRouter agent key for the trajectory judge requires an explicit
+choice; submitted programs receive only their task-declared credentials.
+
+## Scripted runs
+
+```bash
+search-swe run reasoning-query-rewriting --yes
+search-swe run agentic-search agentic-search-vectorless \
+  --agent codex --provider openrouter --model openai/gpt-6-luna \
+  --reasoning-effort max --concurrency 2 --yes
+search-swe run code-embedding-finetuning --gpu-devices 0 --yes
+search-swe run reasoning-query-rewriting --dry-run
+search-swe list --hardware cpu
+search-swe list --json
+search-swe doctor
+```
+
+`--task NAME` may also be repeated. Non-interactive runs use `--yes`; missing keys
+produce a configuration error instead of waiting for input. `--dry-run` previews
+configuration and commands without writing files, downloading assets, allocating
+devices or calling model APIs. `--offline` uses local asset caches; evaluation
+still requires access to the selected model APIs. Asset restoration verifies
+SHA-256 and replaces corrupt manifest-owned files with verified copies.
+
+## Parallel execution and results
+
+`--concurrency N` limits simultaneous tasks. The scheduler allocates disjoint
+logical CPU sets and one idle physical GPU per GPU task, and admits tasks only
+within the RAM pool. It preserves each task's CPU quota, memory cap, storage and
+scoring rules. Fixed task CPU-set environment variables remain respected.
+Use `--cpu-set 0-31`, `--gpu-devices 0,1`, and `--memory-gb 64` to bound the pool.
+RAM accounting leaves 2 GiB for the host and 512 MiB per running task for trusted
+infrastructure. GPUs with more than 512 MiB used or over 5% utilization are
+considered busy at startup.
+GPU availability is checked again while scheduling, so a GPU taken by another
+process during asset preparation stays out of the next allocation.
+
+Allocations coordinate this CLI invocation. They do not reserve the machine
+against other users or independent launchers; select a dedicated resource pool
+on shared hosts. CPU placement can affect timing, so retain allocations when
+reproducing performance measurements.
+
+Runs use fresh `jobs/evaluations/<unique-run>/` directories, or a new `--output`
+directory. `run.json` records the model setting, checkout revision/dirty state,
+per-task resource allocation, process status, log and result paths. A `completed`
+status means the launcher exited successfully; inspect Harbor results for task
+scores and verifier health. Asset logs and evaluation logs are under `logs/`.
+
+Ctrl-C / SIGTERM stops launching new tasks, forwards cancellation to running
+launchers and allows teardown before releasing managed storage. Retained Docker
+containers prevent storage unmounting and produce a recovery instruction.
+Tasks using bounded filesystems need the host prerequisites described in the
+repository evaluation guide. Their storage helpers run with root/sudo while
+Harbor retains the invoking user's identity. For unattended runs, arrange
+non-interactive sudo access in advance.
+
+## Building for publication
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```
+
+Inspect both wheel and sdist before publishing. They should contain the CLI,
+metadata, license and documentation, with no `.env`, task datasets, trajectories
+or job outputs. Keep `pyproject.toml` and `src/search_swe/__init__.py` versions
+aligned before building.
+Upload the checked wheel and sdist with Twine using a PyPI API token.

search_swe-0.1.0/README.md

@@ -0,0 +1,163 @@
+<p align="center">
+  <img src="assets/hero.png" alt="Search-SWE — Benchmarking coding agents on building search engines">
+</p>
+
+<h1 align="center">
+  Search-SWE
+  <br>
+  <sub>🔍 Benchmarking coding agents on building search engines. 🤖</sub>
+</h1>
+
+<p align="center">
+  <a href="https://search-swe.github.io/"><img src="https://img.shields.io/badge/Homepage-Search--SWE-0E9B9B?style=for-the-badge&logo=githubpages&logoColor=white" alt="Search-SWE homepage"></a>
+  <a href="https://search-swe.github.io/tasks.html"><img src="https://img.shields.io/badge/Task_Gallery-Browse-5865F2?style=for-the-badge" alt="Search-SWE task gallery"></a>
+  <a href="https://huggingface.co/datasets/search-swe/Search-SWE"><img src="https://img.shields.io/badge/HuggingFace-Search--SWE-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="Search-SWE dataset on Hugging Face"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-lightgrey?style=for-the-badge&logo=apache&logoColor=white" alt="License: Apache 2.0"></a>
+</p>
+
+<p align="center">
+  <b>English</b> · <a href="README_zh.md">简体中文</a>
+</p>
+
+> *Note: Search-SWE is an ongoing project; tasks, documentation, and results
+> are still evolving.*
+
+## 📖 Overview
+
+Search-SWE evaluates whether coding agents can **implement and optimize** real
+search systems under fixed resource constraints. Agents inspect an environment,
+write and run code, test their systems, and iterate toward an executable
+submission. Evaluation measures the behavior of the resulting system, including
+retrieval quality, functional correctness, and resource use.
+
+Tasks cover reasoning-assisted retrieval, memory-constrained vector search,
+long-document reranking, embedding fine-tuning, and query-encoder alignment.
+
+Each task specifies its inputs, submission interface, evaluation criteria, and
+resource budget. See the [benchmark design](docs/benchmark.md) for how
+evaluation works, how the repository is organized, and where fixed data and
+models come from.
+
+## 🚀 Quick Start
+
+Install the `search-swe` CLI from PyPI in a Python 3.12+ environment:
+
+```bash
+python -m pip install search-swe
+```
+
+### Run with the CLI
+
+```bash
+search-swe run
+```
+
+On first use, choose where to keep the task repository: accept `~/Search-SWE`,
+enter a custom clone path, or select an existing checkout. Git is needed for
+cloning. The CLI remembers the selected path for later commands; task assets and
+results are stored in that checkout. An existing checkout in the current
+directory is used directly.
+
+The wizard guides you through harness, provider, searchable model selection,
+reasoning level and API keys, followed by tasks and sequential or parallel execution. Its
+default setting is **Codex + OpenRouter + GPT-6 Luna (max)**. Keys use hidden
+input; configuration is saved to the ignored `.env` only after confirmation.
+You can also keep entered credentials only for the current run.
+
+Use a native Linux x86_64 Docker host with enough CPU, RAM, disk and optional GPU
+capacity. The CLI restores and checks selected task assets, assigns resources,
+and prepares bounded task storage when needed. Those tasks require root/sudo
+and FUSE; see [host setup](docs/evaluation.md#bounded-task-storage).
+
+After configuration, scripted runs are short:
+
+```bash
+search-swe run reasoning-query-rewriting --yes
+search-swe run agentic-search agentic-search-vectorless --concurrency 2 --yes
+search-swe run code-embedding-finetuning --gpu-devices 0 --yes
+```
+
+Parallel tasks receive separate CPU sets and GPUs within the selected resource
+pool. Results, per-task logs and a `run.json` summary are written to a fresh
+`jobs/evaluations/` directory. Use `search-swe list` to browse tasks,
+`search-swe configure` to save settings without running, and `--dry-run` to
+preview. Task definitions remain in the checkout; use `--repo PATH` when running
+an installed CLI from elsewhere.
+
+See the [quick start](docs/quickstart.md), [CLI reference](docs/cli.md), and
+[full evaluation guide](docs/evaluation.md) for custom providers, resource pools,
+network configuration and the underlying single-task launcher.
+For local CLI development, use `python -m pip install -e .` from the repository root.
+
+### Run through your agent
+
+Install [run-searchswe-evaluation](skills/run-searchswe-evaluation/SKILL.md) into
+your coding agent, then tell it which settings and tasks to run. Use either
+installer (Codex shown here):
+
+```bash
+npx skills add VectorSpaceLab/Search-SWE --skill run-searchswe-evaluation -a codex
+```
+
+```bash
+gh skill install VectorSpaceLab/Search-SWE skills/run-searchswe-evaluation --agent codex
+```
+
+Then ask your agent:
+
+> Use run-searchswe-evaluation with my Search-SWE checkout. Run agentic-search
+> and agentic-search-vectorless with Codex + OpenRouter + openai/gpt-6-luna,
+> max reasoning and concurrency 2. Reuse my .env, monitor the runs and report
+> scores, verifier health and result paths.
+
+The skill guides setup, resource checks, execution and monitoring through the
+same CLI. It prompts you to configure missing keys locally. The
+[agent evaluation guide](docs/agent-evaluations.md) covers local checkout
+installation, other agents, user-wide installation and installer prerequisites.
+
+## 📚 Documentation
+
+| Document | Contents |
+| --- | --- |
+| [Quick start guide](docs/quickstart.md) | A first CPU evaluation, end to end |
+| [Run with your agent](docs/agent-evaluations.md) | Install the evaluation skill and describe settings/tasks |
+| [Evaluation guide](docs/evaluation.md) | Credential setup, coding agents, GPU, network policy, and custom providers |
+| [Network policy](docs/network-policy.md) | Phase-specific allowlists, default direct gateway, and optional proxy egress |
+| [Asset guide](docs/assets.md) | Downloading, verifying, and restoring fixed data and models |
+| [Benchmark design](docs/benchmark.md) | Evaluation, repository layout, and data provenance |
+| [Contributing guide](docs/contributing.md) | Task-authoring workflow, validation, and PR expectations |
+
+For task descriptions and results, visit the
+[project website](https://search-swe.github.io/), maintained in a
+[separate repository](https://github.com/search-swe/search-swe.github.io).
+
+## 🤝 Contributing
+
+Contributions are welcome. For new or substantially revised tasks, start with
+the workflow and skills in [`.agents/`](.agents/AGENTS.md), including
+[`create-searchswe-task`](.agents/skills/create-searchswe-task/SKILL.md) for task authoring
+and [`maintain-searchswe-task`](.agents/skills/maintain-searchswe-task/SKILL.md) for
+PR review and publication. See the
+[contribution entry](CONTRIBUTING.md) and [guide](docs/contributing.md) for validation and PR requirements.
+
+Task authoring includes running a configured coding model, inspecting its
+trajectory and evaluation results, and using that feedback to refine the task
+setting. Revalidate any changes that affect the task or scoring and report the
+final tested revision. If required API keys are missing, the authoring agent
+asks the contributor to configure them locally before the trial.
+
+Create tasks directly at `tasks/<task-name>` in your contribution branch. Choose
+a descriptive name of at most five lowercase, hyphen-separated words, and use
+it for the package and its official data. One PR may add multiple tasks. Review
+and validate each package, then merge with a merge commit to preserve original
+authors.
+
+Public upstream HF datasets may be used directly with immutable commit pins,
+exact filenames, sizes and SHA-256 hashes. Verify downloads, provenance and usage
+terms before merging; official re-upload is optional. When official publication
+is needed, publish under `tasks/<task-name>/` and pin the merged HF SHA first.
+Use `--task <task-name>` for downloads and local trials.
+
+## Citation
+
+TBA