Metadata-Version: 2.4
Name: ncompass
Version: 0.1.7
Summary: Profiling and trace analysis SDK
Author-email: nCompass Technologies <support@ncompass.tech>
Maintainer-email: nCompass Technologies <support@ncompass.tech>
License: Apache-2.0
Project-URL: Homepage, https://ncompass.tech
Project-URL: Documentation, https://docs.ncompass.tech
Project-URL: Repository, https://github.com/ncompass-tech/ncompass
Project-URL: Community, https://community.ncompass.tech
Project-URL: Bug Tracker, https://github.com/ncompass-tech/ncompass/issues
Keywords: ai,inference,profiling,tracing,performance,gpu,pytorch,cuda
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: ncompasslib>=0.0.1.post7
Requires-Dist: pydantic>2.0.0
Requires-Dist: torch>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: interrogate>=1.5.0; extra == "dev"
Requires-Dist: pyright>=1.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Dynamic: license-file

# nCompass Python SDK

[![PyPI](https://img.shields.io/pypi/v/ncompass.svg)](https://pypi.org/project/ncompass/)
[![Downloads](https://static.pepy.tech/badge/ncompass)](https://pepy.tech/project/ncompass)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Profiling and trace analysis SDK. Built by [nCompass Technologies](https://ncompass.tech).

## Features

- **📊 Advanced Profiling** - Built-in performance monitoring and health metrics
- **🤖 AI-Powered Analysis** - Intelligent trace analysis and bottleneck identification
- **🔄 Iterative Optimization** - Progressive profiling workflow for targeted improvements
- **🎯 AST-Level Instrumentation** - Automatic code instrumentation without manual changes
- **⚡ Production-Ready** - Separate development and production configurations

## Installation

Install via pip:

```bash
pip install ncompass
```

## Examples
<!-- TODO: Update readme after setting up actual examples -->
Refer to our [open source GitHub repo](https://github.com/nCompass-tech/ncompass) for examples.

## Documentation

- **[Getting Started](docs/getting_started.md)** - Installation and basic usage
- **[API Reference](docs/api_reference.md)** - Complete API documentation  
- **[Advanced Usage](docs/advanced_usage.md)** - Advanced features and best practices
- **[Examples](examples/)** - Working code examples

## Online Resources

- 🌐 **Website**: [ncompass.tech](https://ncompass.tech)
- 📚 **Documentation**: [docs.ncompass.tech](https://docs.ncompass.tech)
- 💬 **Community**: [community.ncompass.tech](https://community.ncompass.tech)
- 🐛 **Issues**: [GitHub Issues](https://github.com/ncompass-tech/ncompass/issues)

## Why nCompass?

- AI assisted bottleneck identification
- Intelligent profiling marker suggestions
- Progressive optimization guidance

## Requirements

- Python 3.9 or higher
- PyTorch 2.0+ (optional, for torch profiling features)
- CUDA-capable GPU (optional, for GPU profiling)

## Examples

See the [examples](examples/) directory for complete working examples:

- **[basic_usage.py](examples/basic_usage.py)** - Simple profiling session
- **[profiling_session.py](examples/profiling_session.py)** - Complete workflow
- **[advanced_tracing.py](examples/advanced_tracing.py)** - Iterative optimization

## Development

### Coverage & Quality Tools

All development and coverage tools are in the **`tools/`** directory:

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run coverage checks (from tools/ directory)
cd tools
make all-checks         # Run all checks
make coverage           # Unit test coverage
make docstring-coverage # Docstring coverage
make type-stats         # Type hint coverage
make lint               # Run linters
make format             # Auto-format code
```

See **[tools/COVERAGE.md](tools/COVERAGE.md)** for comprehensive documentation.

### Project Structure

```
ncompass/
├── pyproject.toml      # Project config (only root file)
├── ncompass/           # Main package
├── tests/              # Test suite
├── examples/           # Usage examples
├── docs/               # Documentation
└── tools/              # All development tools
    ├── Makefile
    ├── COVERAGE.md
    ├── pyrightconfig.json
    └── .coveragerc
```

## License

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

## Support

- **Documentation**: [docs.ncompass.tech](https://docs.ncompass.tech)
- **Community Forum**: [community.ncompass.tech](https://community.ncompass.tech)
- **Email**: support@ncompass.tech

## About nCompass Technologies

We are building tools that allow GPU kernel developers save hours of dev time every week. Write code that runs twice as fast, twice as quickly.

Learn more at [ncompass.tech](https://ncompass.tech).

---

Made with ⚡ by [nCompass Technologies](https://ncompass.tech)
