fournex 0.1.1__tar.gz

fournex-0.1.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: fournex
+Version: 0.1.1
+Summary: Open-source GPU performance profiler and bottleneck analyzer for PyTorch.
+Author-email: Fournex <hello@fournex.com>
+License: MIT
+Project-URL: Homepage, https://fournex.com
+Project-URL: Repository, https://github.com/jorgevee/fournex
+Project-URL: Documentation, https://fournex.com/docs
+Project-URL: Bug Tracker, https://github.com/jorgevee/fournex/issues
+Keywords: pytorch,gpu,profiling,cuda,performance,mlops,bottleneck,optimization,training
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: System :: Monitoring
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+
+# Fournex
+
+**Open-source GPU performance profiler and bottleneck analyzer for PyTorch.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/jorgevee/fournex/blob/main/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+
+Fournex wraps your training script, collects GPU telemetry, and tells you exactly what is slowing it down — with ranked, actionable recommendations.
+
+## Install
+
+```bash
+pip install fournex
+```
+
+## Quick start
+
+```bash
+# Profile your workload
+frx collect --name my-run -- python train.py
+
+# Analyze and get recommendations
+frx analyze runs/run-<id>
+
+# Check your environment
+frx doctor
+
+# Validate the pipeline end-to-end
+frx smoke-test
+```
+
+## Detected bottleneck types
+
+| Label | Signal |
+|---|---|
+| `input_bound` | DataLoader wait ≥ 20% of step time |
+| `copy_bound` | H2D transfer ≥ 15% of step time |
+| `sync_bound` | Sync wait ≥ 10% of step time |
+| `underutilized_gpu` | GPU utilization < 35% |
+| `memory_pressure` | Peak memory ratio ≥ 90% |
+| `shape_instability` | Shape volatility ≥ 30% |
+| `launch_bound` | Low utilization + profiler windows, no dominant stall |
+| `insufficient_telemetry` | No timing or GPU utilization data |
+
+## Safe config benchmarking
+
+```bash
+frx tune --safe --max-trials 12 -- python train.py
+```
+
+Fournex sweeps DataLoader and runtime configs, benchmarks each one, and recommends the fastest safe candidate — without changing your code.
+
+Interrupted or repeated tune runs can reuse completed trial artifacts:
+
+```bash
+frx tune --resume runs/tune-<id> -- python train.py
+```
+
+`--resume` reuses a trial only when the saved `config.yaml`, `benchmark_window.json`, and `metrics.json` match the current workload command and benchmark settings.
+
+## Links
+
+- [GitHub](https://github.com/jorgevee/fournex)
+- [Documentation](https://fournex.com/docs)
+- [Website](https://fournex.com)

fournex-0.1.1/README.md

@@ -0,0 +1,65 @@
+# Fournex
+
+**Open-source GPU performance profiler and bottleneck analyzer for PyTorch.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/jorgevee/fournex/blob/main/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+
+Fournex wraps your training script, collects GPU telemetry, and tells you exactly what is slowing it down — with ranked, actionable recommendations.
+
+## Install
+
+```bash
+pip install fournex
+```
+
+## Quick start
+
+```bash
+# Profile your workload
+frx collect --name my-run -- python train.py
+
+# Analyze and get recommendations
+frx analyze runs/run-<id>
+
+# Check your environment
+frx doctor
+
+# Validate the pipeline end-to-end
+frx smoke-test
+```
+
+## Detected bottleneck types
+
+| Label | Signal |
+|---|---|
+| `input_bound` | DataLoader wait ≥ 20% of step time |
+| `copy_bound` | H2D transfer ≥ 15% of step time |
+| `sync_bound` | Sync wait ≥ 10% of step time |
+| `underutilized_gpu` | GPU utilization < 35% |
+| `memory_pressure` | Peak memory ratio ≥ 90% |
+| `shape_instability` | Shape volatility ≥ 30% |
+| `launch_bound` | Low utilization + profiler windows, no dominant stall |
+| `insufficient_telemetry` | No timing or GPU utilization data |
+
+## Safe config benchmarking
+
+```bash
+frx tune --safe --max-trials 12 -- python train.py
+```
+
+Fournex sweeps DataLoader and runtime configs, benchmarks each one, and recommends the fastest safe candidate — without changing your code.
+
+Interrupted or repeated tune runs can reuse completed trial artifacts:
+
+```bash
+frx tune --resume runs/tune-<id> -- python train.py
+```
+
+`--resume` reuses a trial only when the saved `config.yaml`, `benchmark_window.json`, and `metrics.json` match the current workload command and benchmark settings.
+
+## Links
+
+- [GitHub](https://github.com/jorgevee/fournex)
+- [Documentation](https://fournex.com/docs)
+- [Website](https://fournex.com)

fournex-0.1.1/fournex/__init__.py

@@ -0,0 +1,168 @@
+from .sdk import (
+    EVENT_LEVELS,
+    EVENT_SOURCES,
+    EVENT_TYPES,
+    SCHEMA_VERSION,
+    begin_span,
+    build_runtime_event,
+    clear_local_events,
+    emit_event,
+    end_span,
+    flush,
+    get_local_events,
+    get_runtime_config,
+    init,
+    make_event,
+    shutdown,
+)
+from .dataloader import InstrumentedDataLoader, instrument_dataloader
+from .analysis import (
+    build_diagnosis_result,
+    classify_bottlenecks,
+    derive_run_summary,
+    derive_step_metrics,
+    select_steady_state_step_ids,
+    summarize_run,
+    summarize_run_with_steady_state,
+    summarize_steady_state,
+    summarize_step_scope,
+)
+from .common_ir_analysis import (
+    derive_ir_bottleneck_annotations,
+    derive_ir_run_summary,
+    derive_ir_step_summaries,
+    summarize_ir_run,
+)
+from .common_ir import (
+    AnnotationRecord,
+    BOTTLENECK_CLASSES,
+    EVENT_FAMILIES,
+    EventRecord,
+    JobInfo,
+    MEMORY_OPS,
+    MODEL_FAMILIES,
+    MetricRecord,
+    RunRecord,
+    WORKLOAD_CLASSES,
+    WorkloadInfo,
+    validate_run_dict,
+)
+from .common_ir_validators import (
+    semantic_warnings_for_run,
+    validate_annotation_record,
+    validate_event_record,
+    validate_metric_record,
+    validate_run_payload,
+    validate_run_record,
+)
+from .cuda_timers import time_memcpy, time_phase, time_region
+from .storage import (
+    persist_local_trace,
+    persist_run_artifacts,
+    persist_run_summary,
+    persist_run_with_steady_state_summary,
+)
+from .profiler import (
+    ProfilerSchedule,
+    configure_sampled_profiler,
+    get_profiler_controller,
+    profiler_step_end,
+    profiler_step_start,
+    profiler_window,
+)
+from .pytorch_profiler_ir import (
+    PytorchProfilerTrace,
+    PytorchProfilerTraceEvent,
+    map_pytorch_profiler_to_ir,
+)
+from .nvml_ir import NvmlSampleRecord, map_nvml_sample_to_ir
+from .distributed_ir import DistributedCommRecord, map_distributed_record_to_ir
+from .data_pipeline_ir import DataPipelineRecord, map_data_pipeline_record_to_ir
+from .step_context import phase, step_context
+from .shapes import (
+    describe_batch,
+    extract_dtypes,
+    extract_shapes,
+    infer_batch_size,
+    infer_sequence_length,
+)
+
+__all__ = [
+    "AnnotationRecord",
+    "BOTTLENECK_CLASSES",
+    "DataPipelineRecord",
+    "DistributedCommRecord",
+    "EVENT_LEVELS",
+    "EVENT_FAMILIES",
+    "EVENT_SOURCES",
+    "EVENT_TYPES",
+    "EventRecord",
+    "InstrumentedDataLoader",
+    "JobInfo",
+    "MEMORY_OPS",
+    "MODEL_FAMILIES",
+    "MetricRecord",
+    "NvmlSampleRecord",
+    "ProfilerSchedule",
+    "PytorchProfilerTrace",
+    "PytorchProfilerTraceEvent",
+    "RunRecord",
+    "SCHEMA_VERSION",
+    "WORKLOAD_CLASSES",
+    "WorkloadInfo",
+    "begin_span",
+    "build_diagnosis_result",
+    "build_runtime_event",
+    "classify_bottlenecks",
+    "clear_local_events",
+    "derive_ir_bottleneck_annotations",
+    "derive_ir_run_summary",
+    "derive_ir_step_summaries",
+    "describe_batch",
+    "derive_run_summary",
+    "derive_step_metrics",
+    "emit_event",
+    "end_span",
+    "extract_dtypes",
+    "flush",
+    "get_local_events",
+    "get_profiler_controller",
+    "get_runtime_config",
+    "init",
+    "make_event",
+    "configure_sampled_profiler",
+    "profiler_step_end",
+    "profiler_step_start",
+    "profiler_window",
+    "select_steady_state_step_ids",
+    "shutdown",
+    "phase",
+    "map_pytorch_profiler_to_ir",
+    "map_nvml_sample_to_ir",
+    "map_distributed_record_to_ir",
+    "map_data_pipeline_record_to_ir",
+    "persist_local_trace",
+    "persist_run_artifacts",
+    "persist_run_summary",
+    "persist_run_with_steady_state_summary",
+    "step_context",
+    "summarize_run",
+    "summarize_run_with_steady_state",
+    "summarize_steady_state",
+    "summarize_step_scope",
+    "summarize_ir_run",
+    "extract_shapes",
+    "infer_batch_size",
+    "infer_sequence_length",
+    "instrument_dataloader",
+    "time_memcpy",
+    "time_phase",
+    "time_region",
+    "validate_run_dict",
+    "validate_annotation_record",
+    "validate_event_record",
+    "validate_metric_record",
+    "validate_run_payload",
+    "validate_run_record",
+    "semantic_warnings_for_run",
+]

fournex-0.1.1/fournex/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fournex-0.1.1/fournex/_native.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+try:
+    from . import _fournex_native as native
+except ImportError:
+    native = None
+
+
+HAS_NATIVE = native is not None