Metadata-Version: 2.4
Name: TACHY-Compiler
Version: 0.1.7
Summary: TACHY model compiler and platform conversion tools.
Author: Deeper-I
License: BSD-3-Clause
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: networkx
Requires-Dist: onnx
Requires-Dist: onnxruntime
Requires-Dist: commentjson
Requires-Dist: ordered-set
Requires-Dist: easydict
Requires-Dist: DDesignerAPI
Provides-Extra: yolov9
Requires-Dist: torch; extra == "yolov9"

# TACHY-Compiler

TACHY-Compiler is a comprehensive deep learning compiler and platform conversion framework developed by Deeper-I. It is designed to bridge the gap between popular deep learning frameworks (like PyTorch) and the TACHY hardware accelerator runtime environment.

This compiler handles model parsing, optimization, tensor alignment, and binary generation. It robustly supports large-scale models, complex operators, and dual-checkpoint pipelines out of the box.

## Key Features

- **PyTorch to ONNX to TACHY**: Seamless end-to-end compilation pipeline.
- **Dual Checkpoint Compilation (`compile-dual`)**: Takes pre- and post-optimization parameters and produces the full set of NPU-runnable instructions **and** parameters (vs **single compile**, which takes only pre-optimization parameters and produces instructions only — a temporary usability check). Reference (`eval` / `pre`) and Target (`comp` / `opt`) go into a unified output structure. **eval** (evaluation) artifacts allow inference verification; **comp** (compile) artifacts do not — they are temporary files for the next compile stage. **pre** is scratch (no transform/pruning); **opt** has transform and/or pruning. Dual compile needs both. When pruning follows transform, **pre** must still be the pre-transform scratch checkpoint, not the transform-trained one.
- **Large Model Support**: Built-in mechanisms to handle models larger than the Protobuf 2GB limit using `external_data` mapping.
- **Robust ONNX Versioning**: Automatically utilizes ONNX Opset 18 for stability, equipped with automatic version conversion and fallback mechanisms to mitigate `onnxscript` conversion issues.
- **MCP Server Integrated**: Exposes tools to LLMs and agentic frameworks via the Model Context Protocol (MCP) using `FastMCP`.
- **Dynamic Binary Resolution**: Intelligently locates dependency binaries utilizing environment variables (`TACHY_UTIL_PATH`) and relative package paths.

## Installation

You can install TACHY-Compiler directly via PyPI:

```bash
pip install TACHY-Compiler
```

### Requirements
- Python >= 3.8
- `numpy`, `networkx`, `onnx`, `commentjson`, `ordered-set`, `easydict`, `DDesignerAPI`
- (Optional) `torch` if utilizing the PyTorch to ONNX conversion pipeline.

## CLI Usage

TACHY-Compiler provides a simple, unified command-line interface under the `tachy` command.

### 1. Dual Checkpoint Compilation
Takes pre- and post-optimization parameters and produces full NPU-runnable instructions and parameters. `eval` artifacts allow inference verification; `comp` artifacts do not (temporary files for the next compile stage). Intermediate files are automatically managed and cleaned up if requested.

```bash
tachy compile-dual \
    --eval_model ./eval_model.pth \
    --comp_model ./comp_model.pth \
    --input_shape "[1,3,224,224]" \
    --output_dir ./dual_output \
    --cleanup
```
Outputs will be cleanly structured into `./dual_output/final_binaries/eval/` and `./dual_output/final_binaries/comp/`.

### 2. Single Model Pipeline Steps
If you need granular control, you can execute the pipeline steps individually.

**Convert PyTorch to ONNX**
```bash
tachy convert-pt2onnx ./model.pth ./model.onnx "[1,3,224,224]" False
```

**Lint ONNX Model** (`--format table|markdown|json`, `--strict` treats WARN as failure, `--buffer_size N` for width check)
```bash
tachy lint ./model.onnx
tachy lint ./model.onnx --suggest                   # search remedies for failed checks
tachy lint ./model.onnx --fix ./model_fixed.onnx    # repeat lint -> remedy until clean (--iterate N, default 5)
```
Each check lives in `src/tachy_compiler/compiler/lint/rules/<id>_*.py` together with its remedies
(`exact`: same I/O, `layout`: host must permute the input, `advisory`: retraining needed).
Remedies are verified by a full re-lint and an onnxruntime equivalence check.
`compile-dual --auto_fix` applies the best remedy before ONNX → TACHY conversion.

**Convert ONNX to TACHY Format**
```bash
tachy convert-onnx ./model.onnx ./model.json
```

**Compile TACHY JSON to Runtime Binaries**
```bash
tachy compile ./model.json ./output_bin_dir
```

### 3. Model Context Protocol (MCP) Server
You can spin up the built-in MCP server to allow LLMs and AI Agents to compile models on your behalf.
```bash
tachy mcp
```

## Environment Variables
- `TACHY_UTIL_PATH` (Optional): An absolute path to the directory containing external utility binaries (`fc.out`, `block_4bit.out`). If not set, the compiler will intelligently look for the `optional` directory within the installed package. Download these binaries from https://gofile.me/5NFjK/PXXLhuIqj, then set `TACHY_UTIL_PATH` to that directory or place them under `optional/`.

## License

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.
