# Contributing to Q-TensorFormer

Thank you for your interest in contributing to **Q-TensorFormer**! We welcome contributions from researchers, systems engineers, and open-source practitioners in tensor networks, efficient inference, and hardware-aware computing.

---

## 🛠️ Development Environment Setup

1. **Clone the repository**:
   ```bash
   git clone https://huggingface.co/Premchan369/Q-TensorFormer
   cd Q-TensorFormer
   ```

2. **Create a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

---

## 🧪 Running the Test Suite

Before submitting any Pull Request, ensure that all unit and integration tests pass:

```bash
pytest -v
```

The test suite covers:
* `tests/test_model.py`: Forward pass shapes, causal mask handling, GQA attention, attention sinks, and PID stability.
* `tests/test_frontier_v10.py`: Triton/JIT kernels, GGUF serialization, ONNX export, and Multimodal Vision-Language reasoning.

---

## 📐 Guidelines for Contributions

1. **Scientific Integrity**:
   * Never fabricate or invent benchmark numbers.
   * Every result must be explicitly tagged as `[MEASURED]`, `[ESTIMATED]`, `[SIMULATED]`, or `[PROJECTED]`.
2. **Zero-Overhead Contract**:
   * Dynamic rank switching must remain $\mathcal{O}(1)$ without runtime SVD or memory allocations.
3. **Backward Compatibility**:
   * Preserve Hugging Face Hub `trust_remote_code=True` compatibility with `AutoConfig` and `AutoModelForCausalLM`.

---

## 📬 Submitting Changes

1. Create a feature branch: `git checkout -b feat/my-improvement`.
2. Commit your changes with clear semantic commit messages (`feat: ...`, `fix: ...`, `docs: ...`).
3. Push to your branch and open a Pull Request.