Metadata-Version: 2.4
Name: kcuda-validate
Version: 0.1.2
Summary: CUDA LLM Hardware Validation Tool for WSL2
Project-URL: Homepage, https://github.com/kenhia/kcuda
Project-URL: Documentation, https://github.com/kenhia/kcuda/blob/main/specs/001-cuda-llm-validation/quickstart.md
Project-URL: Repository, https://github.com/kenhia/kcuda
Project-URL: Bug Tracker, https://github.com/kenhia/kcuda/issues
Project-URL: Changelog, https://github.com/kenhia/kcuda/releases
Author-email: Ken Hiatt <ken.hiatt@gmail.com>
License: MIT
Keywords: cuda,gguf,gpu,inference,llm,nvidia,validation,wsl2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: huggingface-hub>=0.19.0
Requires-Dist: llama-cpp-python>=0.2.0
Requires-Dist: nvidia-ml-py>=12.535.0
Requires-Dist: rich>=13.0.0
Requires-Dist: torch>=2.1.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.14.14; extra == 'dev'
Description-Content-Type: text/markdown

# CUDA LLM Hardware Validation

A minimal Python CLI tool to validate NVIDIA GPU hardware accessibility in WSL2 for LLM inference using CUDA acceleration.

## Quick Start

See the [Quickstart Guide](specs/001-cuda-llm-validation/quickstart.md) for installation and usage.

## Overview

This tool validates that your WSL2 environment can:
- ✅ Detect NVIDIA GPU hardware via CUDA
- ✅ Download and load GGUF model files into GPU memory
- ✅ Execute GPU-accelerated inference for text generation

## Installation

### Prerequisites

1. Install [uv](https://github.com/astral-sh/uv) if not already installed:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. Ensure NVIDIA drivers are installed on Windows host (for WSL2)

### Install from Source

```bash
# Clone repository
git clone https://github.com/kenhia/kcuda.git
cd kcuda

# Install with uv (creates virtual environment automatically)
uv sync

# Run the tool
uv run kcuda-validate --version
```

### Verify Installation

```bash
# Check all dependencies are installed
uv run kcuda-validate --version

# Run GPU detection to verify CUDA setup
uv run kcuda-validate detect
```

## Usage

### Quick Validation

Run the complete validation pipeline in one command:

```bash
uv run kcuda-validate validate-all
```

This will:
1. Detect your NVIDIA GPU and verify CUDA availability
2. Download a test model (first run only, ~4GB)
3. Load the model into GPU memory
4. Run a simple inference test

### Individual Commands

```bash
# Detect GPU hardware only
uv run kcuda-validate detect

# Load a specific model
uv run kcuda-validate load \
  --repo-id TheBloke/Mistral-7B-Instruct-v0.2-GGUF \
  --filename mistral-7b-instruct-v0.2.Q4_K_M.gguf

# Run inference with custom prompt
uv run kcuda-validate infer "Explain quantum computing in simple terms"

# Run inference with options
uv run kcuda-validate infer \
  --max-tokens 100 \
  --temperature 0.8 \
  "Tell me a story"
```

### Global Options

```bash
# Verbose output (DEBUG logging)
uv run kcuda-validate -v detect

# Quiet mode (ERROR only)
uv run kcuda-validate -q validate-all

# Custom log file
uv run kcuda-validate --log-file /tmp/kcuda.log detect

# Show version and dependencies
uv run kcuda-validate --version
```

### Environment Variables

```bash
# Custom log directory
export KCUDA_LOG_DIR=~/logs
uv run kcuda-validate detect

# Custom log level
export KCUDA_LOG_LEVEL=DEBUG
uv run kcuda-validate detect
```

## Requirements

- **WSL2** with Ubuntu 20.04+ or Debian 11+
- **NVIDIA GPU** with 6GB+ VRAM
- **NVIDIA Driver** 510.06+ on Windows host
- **Python 3.11+**
- **uv** package manager

## Documentation

- [Specification](specs/001-cuda-llm-validation/spec.md) - Feature requirements and user stories
- [Quickstart Guide](specs/001-cuda-llm-validation/quickstart.md) - Setup and troubleshooting
- [Implementation Plan](specs/001-cuda-llm-validation/plan.md) - Technical architecture
- [CLI Contracts](specs/001-cuda-llm-validation/contracts/cli.md) - Command interface specification

## Development

```bash
# Run tests
uv run pytest tests/ -v

# Format code
uv run ruff format .

# Lint code
uv run ruff check --fix .

# Pre-commit checks (constitution requirement)
uv run ruff format . && uv run ruff check --fix . && uv run pytest
```

## License

MIT
