nCompass Python SDK

The Python SDK powering our Performance Optimization IDE—bringing seamless profiling and performance analysis directly into your development workflow.

Built by nCompass Technologies.

What are we building?

We're building a Performance Optimization IDE that improves developer productivity by 100x when profiling and analyzing performance of GPU and other accelerator systems. Our IDE consists of two integrated components:

🎯 VSCode Extension

Unify your profiling workflow with seamless integration between traces and codebases:

• No more context switching — profile, analyze, and optimize all in one place
• Zero-copy workflow — visualize traces directly in your editor without transferring files between machines
• Code-to-trace navigation — jump seamlessly between your codebase and performance traces
• AI-powered insights — get intelligent suggestions for performance improvements and bottleneck identification

⚙️ SDK (this repo)

The Python SDK that powers the extension with powerful automation features:

• Zero-instrumentation profiling — AST-level code injection means you never need to manually add profiling statements
• Universal trace conversion — convert traces from nsys and other formats to Chrome traces for integrated visualization
• Extensible architecture — built for customization and extension (contributions welcome!)

Installation

Install via pip:

pip install ncompass

⚠️ Troubleshooting: If you run into issues with ncompasslib or pydantic, ensure that:

1. You are running Python 3.10+
2. You have Pydantic>=2.0 installed

Examples

Refer to our open source GitHub repo for examples. Our examples are built to work together with the VSCode extension. For instance, with adding tracepoints to the code, you can add/remove tracepoints using the extension and then run profiling using our examples.

• vLLM Profiling Example — Profile vLLM using .pth-based auto-initialization with NCU, Nsys, and Torch profilers
• Running remotely on Modal — Run profiling sessions on Modal cloud infrastructure
• Unified Docker Environment — Shared Docker setup with all profiling tools (CUDA, Nsys, NCU, PyTorch)

Online Resources

• 🌐 Website: ncompass.tech
• 📚 Documentation: Documentation
• 💬 Community: community.ncompass.tech
• 🐛 Issues: GitHub Issues
• __ Discord: Join our discord

Requirements

• Python 3.10 or higher
• Nsight Systems CLI installed (for .nsys-rep to .json.gz conversion features)

Building without packaging

Because of Rust dependencies for the fast .nsys-rep to .json.gz converter, -e (editable) builds aren't setup. To build you have to just pip install ./ and use the package from your python env.

To run tests, run the following:

nix develop
pytest tests/ # python tests
cd ncompass_rust/trace_converters/
cargo test --target=x86_64-unknown-linux-musl # rust tests

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Made with ⚡ by nCompass Technologies