tensor-spec 0.1.0

Framework-agnostic deep learning API quality verification tool

tensor-spec

Overview

tensor-spec is a framework-agnostic deep learning API quality verification tool. It compares tensor operation precision across deep learning frameworks (currently PaddlePaddle vs PyTorch) using process isolation and CUDA IPC zero-copy GPU data sharing.

Features

• Framework-agnostic -- Pluggable backend architecture supporting PaddlePaddle and PyTorch
• Process isolation -- Each framework runs in its own subprocess to avoid CUDA/import conflicts
• CUDA IPC zero-copy -- GPU tensor sharing via CUDA IPC handles (1000x faster than CPU roundtrip)
• Secure config parsing -- Whitelist recursive descent parser (no eval())
• Constraint-driven data generation -- Generate test tensors from specs with composable constraints
• Per-API tolerance -- Configurable atol/rtol with TOML-based overrides per operator
• Structured logging -- JSON Lines output for machine-parseable test results
• CLI interface -- run, validate, and accuracy commands via Typer

Installation

pip install tensor-spec

Or with uv:

uv add tensor-spec

Quick Start

# Validate a case config (parse-only, no framework needed)
tensor-spec validate "abs(x=Tensor.float32((2, 3)))"

# Run single-backend execution
tensor-spec run --backend paddle "abs(x=Tensor.float32((2, 3)))"

# Cross-framework accuracy comparison (subprocess-isolated)
tensor-spec accuracy "matmul(x=Tensor.float32((2, 3)), y=Tensor.float32((3, 4)))"

Development

Prerequisites

• Python >= 3.12
• uv for dependency management
• just for task running

Setup

just install

Common Commands

just            # List all available commands
just format     # Format code (Python + justfile)
just lint       # Run linter
just check      # Type checking (pyright)
just test       # Run all tests
just cov        # Run tests with coverage
just docs       # Serve docs locally
just ci         # Full CI check (format + check + lint + cov)

Architecture

The project follows a 10-layer modular architecture:

Layer	Module	Responsibility
1	spec	Pure data structures for tensor specifications
2	config	Secure whitelist recursive descent parser
3	datagen	Constraint-driven numpy array generation
4	backend	Pluggable framework backends (Paddle, PyTorch)
5	mapping	API name/argument mapping between frameworks
6	compare	Tensor comparison with configurable tolerance
7	tester	Test execution modes (in-process, isolated)
8	worker	Subprocess management and IPC protocol
9	ipc	SharedMemory (CPU) and CUDA IPC (GPU) transport
10	cli	Typer-based CLI entry point

Documentation

For detailed usage and API documentation, please visit our documentation site.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup and contribution guidelines.