PrecisionAI: Examples

License, version, and the canned training-data smoke profile

-- Act 1 - What ships --
  -> PrecisionAI profiles FP64 training columns and recommends the narrowest safe dtype so DataLoaders stop loading wasted precision.
  package_version: 0.1.0
  native_version: 0.1.0
  license_valid: True

-- Act 2 - Smoke profile --
  -> precisionai_run profiles two canned sensor columns under the license gate.
  survived: True
  message: profiled 2 columns; 2 reducible (temp->float16, press->float16)

-- Run complete --
  survived: True
  next_journey: 02_core_path.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/01_first_contact.py
 
# Production one-liner — same API call you ship:
python -c "import precisionai as pai; print(pai.__version__, pai.run_smoke())"

Profile a toy training batch and read the recommendations

-- Act 1 - The batch --
  -> Three FP64 columns that look like sensor / score features. Models usually train at FP16/BF16 — storing them as FP64 wastes bandwidth.
  n_columns: 3
  n_rows: 128
  stored: float64

-- Act 2 - Profile --
  -> profile_training_data walks each column through the C analyzer.
  temperature.recommended: float16
  temperature.reduction: 4.0x
  temperature.sig_digits: 15.8
  pressure.recommended: float16
  pressure.reduction: 4.0x
  pressure.sig_digits: 15.9
  label_score.recommended: float16
  label_score.reduction: 4.0x
  label_score.sig_digits: 15.8

-- Act 3 - Headline numbers --
  -> Overall storage reduction and estimated load speedup.
  overall_storage_reduction: 4.0
  estimated_load_speedup: 4.0
  n_reducible: 3

-- Run complete --
  overall_storage_reduction: 4.0
  next_journey: 03_configuration.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_core_path.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, precisionai as pai; m=pai.profile_training_data({'temp':np.linspace(0,10,64)},'toy'); print(m.overall_storage_reduction, m.n_reducible)"

error_tolerance and target_model_dtype are the knobs that matter

-- Act 1 - Tolerance dial --
  -> Looser relative-error tolerance lets the analyzer pick a narrower dtype. Tighter tolerance keeps more precision (or refuses reduction).
  tol_0.01: float16
  tol_0.001: float16
  tol_1e-06: float32
  tol_1e-12: float64

-- Act 2 - Model precision context --
  -> target_model_dtype records what the trainer actually uses (fp16/bf16/fp32) on the manifest for DataLoader consumers.
  target_model_dtype: float16
  recommended: float16

-- Run complete --
  next_journey: 04_diagnostics.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_configuration.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, precisionai as pai; x=np.linspace(0,5,32); print(pai.analyze_column(x,1e-2).target_dtype)"

Emit a DataLoader YAML manifest and an AI-readiness summary

-- Act 1 - YAML manifest --
  -> emit_manifest_yaml writes a per-column spec DataLoaders can consume — stored vs recommended dtype, sig digits, and reduction. dataset: diag_batch overall_storage_reduction: 4.0x estimated_load_speedup: 4.0x n_columns: 3 n_reducible: 3 columns: temperature: stored: float64
  manifest_path: ~\AppData\Local\Temp\precisionai_diag_manifest.yaml

-- Act 2 - AI-readiness score --
  -> readiness_score folds the manifest into a compact ops / CDAO-style summary.
  dataset: diag_batch
  n_columns: 3
  n_reducible: 3
  storage_reduction_x: 4.0
  estimated_load_speedup_x: 4.0
  precision_waste_fraction: 0.75
  target_model_dtype: unspecified

-- Run complete --
  manifest_path: ~\AppData\Local\Temp\precisionai_diag_manifest.yaml
  next_journey: 05_feature_store.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/04_diagnostics.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, precisionai as pai; m=pai.profile_training_data({'a':np.ones(16)},'d'); print(pai.readiness_score(m))"

Profile → apply manifest → measured compression on a store-shaped batch

-- Act 1 - Feature store pain --
  -> Feature stores often keep every numeric as FP64. PrecisionAI identifies which columns can shrink before the DataLoader.
  n_features: 4
  n_rows: 256

-- Act 2 - Profile --
  -> Build the manifest at a training-friendly tolerance.
  n_reducible: 4
  overall_storage_reduction: 4.0

-- Act 3 - Apply --
  -> apply_manifest casts via the C engine and verifies round-trip within tolerance.
  original_bytes: 8192
  reduced_bytes: 2048
  compression_ratio: 4.0
  dtypes: {'temp_c': 'float16', 'press_kpa': 'float16', 'rpm': 'float16', 'soc': 'float16'}

-- Run complete --
  compression_ratio: 4.0
  next_journey: 06_limits.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/05_feature_store.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, precisionai as pai; f={'temp':np.round(np.linspace(18,28,100),1)}; m=pai.profile_training_data(f,'fs'); print(pai.apply_manifest(f,m).compression_ratio)"

What PrecisionAI is not — and how it refuses unsafe reductions

-- Act 1 - Data layer only --
  -> PrecisionAI does not train models, quantize weights (GPTQ/AWQ), or replace your optimizer. It right-sizes training *data* before the first cast.

-- Act 2 - Missing column --
  -> apply_manifest requires every field to appear in the manifest — mismatches raise.
  missing_column: KeyError: "column 'x' missing from manifest"

-- Act 3 - Tight tolerance refuses reduction --
  -> At an absurdly tight tolerance the analyzer keeps float64 rather than lie.
  target_dtype: float64
  safe: True

-- Run complete --
  takeaway: Optimize the data layer; keep model quantization as a separate tool.

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_limits.py
 
# Production one-liner — same API call you ship:
python -c "import precisionai as pai; ..."