Metadata-Version: 2.4
Name: hydraedge
Version: 0.1.0
Summary: HydraEdge: cross-document linker (VSA × RL) – EMNLP 2025 system demo
Author-email: Pak Kin Lau <pakkin.lau@link.cuhk.edu.hk>
License: Copyright 2025 Pak Kin LAU
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Homepage, https://github.com/pakkinlau/hydraedge
Project-URL: Repository, https://github.com/pakkinlau/hydraedge.git
Keywords: hydra,cross-document,linking,VSA,reinforcement-learning
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: pydantic>=2.7
Requires-Dist: torch>=2.2
Requires-Dist: numpy>=1.26
Requires-Dist: pytest>=8.2
Requires-Dist: structlog>=24.1
Dynamic: license-file

Below is a **drop-in `README.md`** that rolls together **everything we have discussed so far**— Docker-image build, run, VS Code attachment, interpreter selection, GPU / FAISS sanity checks, and an optional dev-container recipe—so a fresh collaborator can be productive in minutes.

````markdown
# HydraEdge Rapid-Startup Environment  
### (Python 3.10 · CUDA 12.1 · FAISS GPU 1.11 · VS Code ready)

> *Goal *: give reviewers / team-mates a **one-shot, GPU-enabled dev box** with the exact stack we used for the EMNLP-2025 system-demo paper—no local Python conflicts, no CUDA hell.

---

## 0 · Prerequisites

| Tool | Minimum version | Notes |
|------|-----------------|-------|
| **Docker** | 20.10+ | *Docker Desktop* is fine (enable **GPU support** in Settings → Resources → GPU). |
| **NVIDIA Driver** | R525+ | Must support CUDA ≥ 12.1. |
| **VS Code** | 1.85+ | Plus the **Remote - Containers** extension. |

---

## 1 · Build the image (one-off)  

We pin Python 3.10 on top of a small CUDA runtime base and add FAISS-GPU.

```bash
# inside the repo root (contains Dockerfile)
docker build -t py310-cuda-faiss:12.1 .
````

If you prefer to **pull** rather than build, grab our pre-built image:

```bash
docker pull ghcr.io/your-org/py310-cuda-faiss:12.1
```

---

## 2 · Run the container

```bash
docker run --gpus all \
  -v "C:/Documents/All_github_repo/hydraedge:/workspace" \
  -p 8888:8888 -p 6006:6006 \
  --name hydraedge-dev \
  -it py310-cuda-faiss:12.1 bash
```

| Flag                        | Why                                                                     |
| --------------------------- | ----------------------------------------------------------------------- |
| `--gpus all`                | exposes every GPU to the container.                                     |
| `-v local: /workspace`      | your code lives in the container.                                       |
| `-p 8888:8888 -p 6006:6006` | ready for Jupyter & TensorBoard.                                        |
| `-it … bash`                | drop into a shell immediately; feel free to swap for `python` or `zsh`. |

---

## 3 · GPU / FAISS sanity check (optional)

Inside the container run:

```bash
python - <<'PY'
import faiss, numpy as np, torch, os
print("Python  :",  os.sys.version)
print("CUDA    :",  torch.version.cuda)
print("GPUs    :",  faiss.get_num_gpus())
xb = np.random.rand(2,128).astype('float32')
index = faiss.index_cpu_to_all_gpus(faiss.index_factory(128, "Flat"))
index.add(xb)
print("Distances", index.search(xb, 1)[0].ravel())
PY
```

You should see **`GPUs : 1`** (or more) and finite self-distances.

---

## 4 · Attach VS Code (Remote-Containers)

1. **Install** *Remote - Containers* extension (once).
2. **Command Palette → “Remote-Containers: Attach to Running Container…”**
   choose **`hydraedge-dev`** → VS Code reloads into `/workspace`.

### 4.1 Install the Python extension in the container

The first reload shows *“Extensions (in Container)”* at the top of the sidebar.

* Search **Python** → **Install** (again – this time inside the container).
* Reload when prompted.

### 4.2 Pick the interpreter

*Command Palette → Python: Select Interpreter → `/usr/bin/python`*
The green ▶︎ **Run / Debug** buttons now appear.

---

## 5 · Dev-container auto-setup (optional but recommended)

Put this in **`.devcontainer/devcontainer.json`** so newcomers get the tools automatically:

```jsonc
{
  "name": "hydraedge-dev",
  "image": "py310-cuda-faiss:12.1",
  "extensions": [
    "ms-python.python",
    "ms-toolsai.jupyter"
  ],
  "settings": {
    "python.defaultInterpreterPath": "/usr/bin/python"
  },
  "postCreateCommand": "python -m pip install -r requirements.txt || true"
}
```

---

## 6 · Shut-down & cleanup

```bash
# inside the container
exit               # or Ctrl-D

# on host
docker stop hydraedge-dev
docker rm   hydraedge-dev     # optional
```

---

## 7 · Troubleshooting

| Symptom                                      | Fix                                                                                                                                                                                                      |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`faiss.get_num_gpus() -> 0`**              | The Docker runtime cannot see your GPU.<br/>• Check `docker info --format '{{json .Runtimes}}'` shows *nvidia*.<br/>• On Windows / WSL: enable *“Use the WSL 2 based engine”* + *GPU* in Docker Desktop. |
| **No ▶︎ Run button in VS Code**              | Install the *Python* extension **inside** the container (see § 4.1).                                                                                                                                     |
| **`AssertionError` during FAISS test**       | Means `faiss.index_cpu_to_all_gpus` got **0 GPUs**. Fix GPU visibility then rerun.                                                                                                                       |
| **Slow build (downloads huge cuBLAS wheel)** | First build always pulls ≥ 500 MB CUDA libraries. They are cached afterwards.                                                                                                                            |
