PET — Prime Exponent Tree

PET is a Python CLI and operator-side toolkit for encoding, validating, rendering, measuring, explaining, running structural factorization, and triaging Prime Exponent Tree artifacts.

It treats an integer not only as a value, but also as a structured multiplicative object. The project studies that structure at three levels:

• PET-Base — canonical recursive representation
• PET-Metrics — structural observation and comparison
• PET-METICA — rewrite geometry on canonical PET shapes

PET is not presented as a replacement for classical arithmetic and not as a claimed solution to a major open problem. It is best understood as an artifact, validation, measurement, and explanation layer for known PET structures.

Why this is interesting

PET gives you a way to explore integers through their recursive prime-factorization structure.

It is useful as:

• a canonical representation of integers based on prime factorization
• a CLI for inspecting structural properties and metrics
• a reproducible lab for scans, queries, summaries, and empirical reports
• a first-class structural factorization CLI for single-number PET routes
• operator-side triage tooling for bounded classic handoff and diagnostics
• a rewrite-geometric playground for studying paths, asymmetries, and families of PET shapes

Try it in 30 seconds

Install locally

pip install -e .

Inspect a number

pet encode 72

Output:

N = 72
[
  {
    "p": 2,
    "e": [
      {
        "p": 3,
        "e": null
      }
    ]
  },
  {
    "p": 3,
    "e": [
      {
        "p": 2,
        "e": null
      }
    ]
  }
]
decoded = 72

Inspect structural metrics

pet metrics 256

Output:

N = 256
node_count = 3
leaf_count = 1
height = 3
max_branching = 1
branch_profile = [1, 1, 1]
recursive_mass = 2
average_leaf_depth = 3.0
leaf_depth_variance = 0.0

Run a small bounded scan

pet scan 2 1000 --jsonl docs/reports/data/scan-2-1000.jsonl

Query the scan

pet query filter docs/reports/data/scan-2-1000.jsonl --where "height=2" --limit 5

What is stable today

Stable / core

• recursive encoding based on prime factorization
• canonical representation
• invertibility / roundtrip behavior
• machine-facing JSON representation
• CLI-based inspection and dataset generation

Active observational layer

• PET-derived structural metrics
• structural comparison across families
• scan / query / atlas-style workflows

Structural factorization and operator-side triage

• first-class structural factorization via pet structural-factorization N
• PET race diagnostics via tools/pet_triage_pipeline.sh
• PET shape diagnostics mapped to bounded classic handoff policy
• classic divisors accepted only when explicitly verified

Live research line

• PET-METICA as rewrite geometry on canonical PET shapes
• PET/PEG 2.0 foundations as conceptual research material for object structure, connectivity dynamics, path-history, and projection semantics

Operational PET-METICA CLI core:

pet branch-neighbors 12
pet rewrite pair 12 9 --overscan 120
pet rewrite explain 12 9 --overscan 120
pet rewrite friction --n-max 10 --overscan 40 --limit 3
pet rewrite scan --n-max 20 --overscan 60
pet rewrite matrix --n-max 10 --overscan 60 --json

PET-METICA is operational but still research-facing: rewrite scans and hub/friction observations are bounded empirical results, not general theorems.

• local rewrite moves such as NEW, DROP, INC, DEC
• shortest paths, canonical paths, asymmetries, and rewrite friction
• empirical family behavior in explored ranges

Still exploratory

• broad mathematical generalization beyond explored ranges
• shape algebra and related experimental operations

Project map

Start here depending on what you need:

• docs/README.md — documentation entry point
• docs/foundations/README.md — PET/PEG 2.0 conceptual foundations and roadmap
• docs/VISION.md — project vision and layer structure
• docs/reports/STATUS.md — what is stable, empirical, or exploratory
• docs/ROADMAP.md — post-release development roadmap
• docs/research/notes/PET-METICA.md — current rewrite-geometric research line
• docs/reference/SPEC.md — formal PET-Base specification
• docs/reference/CLI.md — command-line usage
• docs/reports/README.md — reports, generated summaries, and report data
• docs/research/README.md — research notes, experiments, partial-shape material, and datasets
• ROADMAP.md — current priorities and next directions
• CHANGELOG.md — public release history
• CONTRIBUTING.md — contribution guide

Typical workflow

A small practical PET workflow looks like this:

1. encode or inspect specific integers
2. compute structural metrics
3. run pet structural-factorization N for stable structural routes
4. run PET triage for deeper operator-side diagnostics where useful
5. generate a bounded JSONL scan
6. query or group the scan
7. summarize the dataset with report tooling
8. explore rewrite neighborhoods and paths where relevant

A current structural factorization CLI smoke run is:

pet structural-factorization 24680 --max-depth 4

A current operator-side triage smoke run is:

tools/pet_triage_pipeline.sh 10007 --no-fork --no-fork-follow --no-recursive

Current scope

PET is currently best understood as:

• a small Python CLI
• a reproducible PET artifact and report tooling project
• a project for studying structural properties of integers through PET representations
• an emerging rewrite-geometric framework through PET-METICA

It is not yet a polished end-user product.

Development

The project targets Python 3.10+.

Local install:

pip install -e .

Run tests:

pytest -q

License

MIT