Polish and harden ACCL-Q: security, testing, code quality

.github/workflows/python-tests.yml

@@ -0,0 +1,68 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [main, corrina, dev]
+    paths:
+      - 'driver/python/**'
+      - 'test/quantum/**'
+      - 'api_server.py'
+      - 'pyproject.toml'
+      - 'requirements.txt'
+  pull_request:
+    branches: [main, corrina]
+    paths:
+      - 'driver/python/**'
+      - 'test/quantum/**'
+      - 'api_server.py'
+      - 'pyproject.toml'
+      - 'requirements.txt'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest-cov ruff
+
+      - name: Run quantum driver tests with coverage
+        run: |
+          python -m pytest test/quantum/ -v --tb=short --cov=accl_quantum --cov-report=term-missing
+        env:
+          PYTHONPATH: driver/python
+
+      - name: Run demo script
+        run: |
+          python demo_accl_q.py
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Check formatting
+        run: ruff check driver/python/ api_server.py --select E,W,F --ignore E501

INSTALL.md

@@ -1,12 +1,42 @@
-# Installation instructions
+# Installation Instructions
 
-## Pull project
+## ACCL-Q Python Driver (Quick Start)
+
+```sh
+git clone https://github.com/The-AI-Cowboys-Projects/ACCL_NEW.git
+cd ACCL_NEW
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Run the demo
+python demo_accl_q.py
+
+# Run the test suite
+python -m pytest test/quantum/ -v
+
+# Start the API server
+python -m uvicorn api_server:app --host 0.0.0.0 --port 8080
+```
+
+### Requirements
+
+- Python 3.11+
+- numpy >= 1.24
+- fastapi, uvicorn, pydantic (for API server)
+- pytest, pytest-asyncio, httpx (for tests)
+
+---
+
+## ACCL Hardware Build (Original)
+
+### Pull project
 ```sh
 git clone https://github.com/Xilinx/ACCL.git
 git submodule update --init --recursive
 ```
 
-## Install dependencies
+### Install dependencies
 The project has been tested with Xilinx Vitis 2022.1 on Ubuntu 20.04.
 ```sh
 sudo apt update

README.md

@@ -133,7 +133,8 @@ This demonstrates sufficient margin for multi-round QEC within coherence limits.
 │  Operation Modes                                                │
 │  ├── STANDARD         - Default operation                       │
 │  ├── DETERMINISTIC    - Hardware-synchronized, minimal jitter   │
-│  └── LOW_LATENCY      - Optimized for speed over consistency    │
+│  ├── LOW_LATENCY      - Optimized for speed over consistency    │
+│  └── ULTRA_LOW_LATENCY - Hardware-autonomous sub-50ns feedback  │
 ├─────────────────────────────────────────────────────────────────┤
 │  Infrastructure                                                 │
 │  └── IBM Cloud Code Engine (Serverless Container)               │
@@ -181,6 +182,27 @@ curl -X POST ".../qec/syndrome" \
   -d '{"num_ranks": 8, "syndrome_bits": 4}'
 ```
 
+### ULL Pipeline
+
+```bash
+# Configure ULL pipeline
+curl -X POST ".../ull/configure" \
+  -H "Content-Type: application/json" \
+  -d '{"syndrome_bits": 16, "coherence_time_us": 50.0}'
+
+# Run autonomous feedback cycle
+curl -X POST ".../ull/feedback?num_cycles=1"
+
+# Run 100 continuous cycles
+curl -X POST ".../ull/feedback?num_cycles=100"
+
+# Check ULL status
+curl ".../ull/status"
+
+# Disarm pipeline
+curl -X POST ".../ull/disarm"
+```
+
 ### Qubit Emulator
 
 ```bash
@@ -266,23 +288,34 @@ docker run -p 8080:8080 accl-q
 
 ```
 ACCL_NEW/
-├── api_server.py              # FastAPI REST API server
-├── demo_accl_q.py             # Comprehensive demo script
+├── api_server.py              # FastAPI REST API (includes ULL endpoints)
+├── demo_accl_q.py             # Comprehensive demo (6 demos incl. ULL)
+├── pyproject.toml             # Python packaging configuration
+├── requirements.txt           # Python dependencies
 ├── Dockerfile                 # Production container definition
-├── .dockerignore              # Docker build exclusions
 ├── driver/
 │   └── python/
 │       └── accl_quantum/      # Core ACCL-Q driver
 │           ├── __init__.py    # Package exports
 │           ├── driver.py      # ACCLQuantum main class
+│           ├── constants.py   # Enums, ULL config, latency budgets
+│           ├── hardware_accel.py  # DMA pool, LUT decoder, FPGA regs
+│           ├── feedback.py    # Feedback pipelines (std + ULL)
 │           ├── emulator.py    # RealisticQubitEmulator
-│           ├── feedback.py    # MeasurementFeedbackPipeline
+│           ├── profiler.py    # Critical path profiler
 │           ├── stats.py       # LatencyMonitor
-│           └── constants.py   # Enums and configuration
+│           ├── deployment.py  # Multi-board RFSoC deployment
+│           ├── integrations.py # QubiC/QICK integrations
+│           └── docs/          # Documentation
+├── kernels/cclo/hls/quantum/  # HLS constants
+│   └── quantum_hls_constants.h
 ├── test/
-│   └── quantum/               # Test suite
+│   └── quantum/               # Test suite (~200 tests)
 │       ├── test_collective_ops.py
 │       ├── test_integration.py
+│       ├── test_ull_optimization.py
+│       ├── test_ull_latency_validation.py
+│       ├── test_module_coverage.py
 │       └── test_latency_validation.py
 └── README.md                  # This file
 ```
@@ -303,6 +336,38 @@ This experimental deployment validates that FPGA-based collective communication
 
 ---
 
+## Ultra-Low-Latency (ULL) Mode
+
+ACCL-Q v0.3.0 introduces ULL mode for hardware-autonomous feedback execution targeting **<50ns latency** (0.1% of 50us coherence time) — a 10x improvement over standard feedback.
+
+| Component | Standard | ULL Target |
+|-----------|----------|-----------|
+| Multicast | 300ns | 10ns |
+| Reduce | 400ns | 4ns |
+| Decode | 50-200ns | 8ns |
+| Trigger | 50ns | 2ns |
+| **Total** | **~500ns** | **~34ns** |
+
+```python
+from accl_quantum import ACCLQuantum, ACCLMode
+from accl_quantum.feedback import HardwareFeedbackEngine
+from accl_quantum.constants import ULLPipelineConfig
+
+# Zero-copy ULL collectives
+accl = ACCLQuantum(num_ranks=4, local_rank=0)
+accl.configure(mode=ACCLMode.ULTRA_LOW_LATENCY)
+result = accl.broadcast(data, root=0)  # 10ns, zero-copy
+
+# Autonomous hardware feedback
+engine = HardwareFeedbackEngine(ULLPipelineConfig())
+engine.program_pipeline(decoder_fn=my_decoder, syndrome_bits=16)
+result = engine.run_autonomous_cycle()  # ~34ns per cycle
+```
+
+See [Performance Tuning Guide](driver/python/accl_quantum/docs/performance_tuning.md) for details.
+
+---
+
 ## Future Work
 
 - Integration with IBM Quantum systems via Qiskit