Karry-coder-dev / RAVEL

# RAVEL
This directory is the curated project snapshot for Retrieval-Aware Verbal
Evidence Learning for Interactive Person Re-Identification. The source tree is self-contained; large datasets, base models, and
retriever checkpoints are configured as external assets.
## Environment setup
RAVEL is intended to run on Linux with an NVIDIA GPU. Use Python 3.10 or
3.11 and install a PyTorch build that matches the CUDA driver on the target
machine. PyTorch and CUDA are intentionally not pinned here because the
correct wheel depends on the machine.
Create and activate an isolated environment, then install PyTorch from the
official selector for the target CUDA version:
 [code] 
Check the environment before launching a long job:
 [code] 
The YAML files use http://localhost:10500/v1 and the API key Qwen-7B by
default. Verify the endpoint before running RAVEL:
 [code] 
The usual execution order is:
1. Start the SGLang answerer service.
2. Run supervised cold start with code/main/train-question.sh if the SFT
 adapter is not already available.
3. Run the three-thousand-state RL experiment with
 code/main/run-ravel-main.sh.
4. Run evaluation with the selected YAML configuration.
If torch.compile fails during SFT, set torch_compile: false in the SFT
configuration. If a module is not found, check that the environment is
activated and that PYTHONPATH points to code/main. If CUDA memory is
insufficient, reduce the configured batch size or group size before changing
the model code.
## Layout
- code/: training, evaluation, motivation, behavior-analysis, transfer, and
 ablation code.
- dataset/: documentation and mount points for external data assets. The
 actual Interactive-PEDES files, RL state pools, Qwen3-VL audit records, and
 human-review records are not tracked in this repository.
- weight/: external model and retriever checkpoint mount points. Weight files
 are intentionally not tracked.
The public source tree contains code and lightweight documentation only. Raw
images, benchmark annotations, RL pools, audit records, human annotations,
base LLMs, and model checkpoints must be downloaded separately and placed at
the paths described in dataset/README.md and the configuration files.
## Reproduction switches
code/ablation/llava_reid_top4_64.yaml uses direct Top-4 candidates.
code/main/config/llava_reid_selector_64.yaml uses the selector protocol.
The main evaluator selects the retriever from YAML; code/ablation/ravel-rde.yaml
selects the RDE replacement with retriever_type: rde.
The RL trainer switches between the state pools through --states and
--limit-states:
- 3K: dataset/rl-3k/state-pool-3k.jsonl with --limit-states 3000
- 5K: dataset/rl-5k/state-pool-5k.jsonl with --limit-states 5000
The reward combines reciprocal-rank change,
the Rank-1 transition term, the invalid-question penalty, and the repeat penalty.
Rank-5/Rank-10 terms and regression penalties are excluded from the
curated trainer.
## External assets
The main code does not depend on sibling reposit