epochly 0.6.16

Epochly - Transparent performance optimization for Python applications

Epochly

Epochly is a drop-in Python performance overlay. It accelerates workloads via GPU acceleration and multicore parallelism when safe and beneficial, and yields to normal execution when it cannot help. No code changes required.

Installation

From PyPI:

pip install epochly

From source:

git clone https://github.com/chandlercvaughn/epochly.git
cd epochly
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Quick Start

Default Decorator (Monitor-First)

The plain @optimize decorator runs your function on the transparent monitor-only path by default. Epochly observes the workload and adds bounded instrumentation; on a fresh default install it does not automatically JIT-compile, and epochly.stats() reflects LEVEL_0_MONITOR (no acceleration by default). This is intentional: the default path never changes results and never pays a cold-start cost you did not ask for.

import epochly

@epochly.optimize
def numeric_kernel(n):
    total = 0.0
    for i in range(n):
        total += (i * 1.5) ** 0.5
    return total

# Runs on the transparent monitor path by default (no acceleration).
for _ in range(50):
    numeric_kernel(10000)

status = epochly.stats()
print("realized level:", status.get("realized_level"))

To turn observation into measurable speedups, opt in to an explicit level (next example) or lower the JIT hot-path threshold with EPOCHLY_JIT_HOT_PATH_THRESHOLD.

Explicit JIT (Measurable Speedups, level=2)

Pass level=2 to request JIT compilation of numeric inner loops. The first call pays a one-time compilation cost; subsequent calls run compiled. On numeric-heavy loops this is where the headline JIT speedups (see docs/benchmarks.md) are realized.

import epochly

@epochly.optimize(level=2)
def numeric_kernel(n):
    total = 0.0
    for i in range(n):
        total += (i * 1.5) ** 0.5
    return total

# Warmup triggers compilation; later calls run the compiled kernel.
for _ in range(5):
    numeric_kernel(50000)

status = epochly.stats()
print("realized level:", status.get("realized_level"))
print("optimization effective:", status.get("optimization_effective"))

Context Manager

from epochly import optimize_context

with optimize_context(level=2):
    result = numeric_kernel(50000)

Key Capabilities

The default decorator path is monitor-only: it observes and never changes results, but it does not accelerate by default. The speedup figures below are realized on the explicit, opt-in paths named in each bullet (and detailed with their reproduction recipes in docs/benchmarks.md).

• Drop-in overlay: no code changes required; Epochly decides whether to accelerate
• GPU acceleration (L4): up to 64x on large array workloads, on the explicit level=4 path when CUDA hardware is available (requires EPOCHLY_GPU_ENABLED=true and an NVIDIA GPU; not active by default)
• Multicore parallelism (L3): up to 8x per core on CPU-heavy tasks via the explicit level=3 process-pool path (not active by default)
• JIT prefilter (L1/L2): bytecode prefilter classifies eligible kernels; the explicit level=2 path JIT-compiles admitted numeric inner loops (the default path stays at L0 monitoring until you opt in)
• Monitoring (L0): the default path; pass-through with instrumentation; bounded overhead (< 5%) on unsuitable workloads
• Rollback safety: circuit breaker with cache invalidation; on failure, execution rolls back to the unmodified path without silent misclassification
• Truth surface: unified status/metrics/inspect surface reflects measured execution, never heuristics

Enhancement Levels

Epochly operates through five progressive enhancement levels:

Level	Name	Behavior
L0	Monitoring	Pass-through with instrumentation; no acceleration
L1	Prefilter	Bytecode prefilter classifies eligible kernels; threading for admitted ones
L2	JIT	JIT compilation of prefilter-admitted kernels
L3	Multicore	Process pool dispatch with shared memory for parallel workloads
L4	GPU	CUDA acceleration via CuPy when NVIDIA GPU is detected

Unsuitable workloads receive L0 pass-through with bounded overhead (5% wall-clock budget verified in tests/validation/test_acceleration_proof.py).

Level 3 requires a __main__ guard

The Level 3 multicore path dispatches work to a process pool. On macOS and Windows (and any platform where the multiprocessing start method is spawn or forkserver), each pool worker re-imports your program's main module during startup. If your script runs at module top level with no if __name__ == "__main__": guard, that re-import would replay your module-level side effects (file writes, network calls, payments) once per worker.

Epochly will not silently replay those side effects. When it detects an unguarded __main__ (or a script fed via stdin / python -c, whose module path resolves to <stdin>) under a spawn-class start method, it refuses Level 3 process-pool dispatch, emits one warning, records the UNSAFE_MAIN_MODULE fallback reason on the truth surface, and falls back to a lower level. Wrap your entry point to enable Level 3:

import epochly


@epochly.optimize(level=3)
def crunch(n):
    total = 0
    for i in range(n):
        total += (i * i) % 7
    return total


if __name__ == "__main__":  # required for Level 3 on spawn/forkserver platforms
    for _ in range(8):
        crunch(200000)

This is the standard Python multiprocessing "safe importing of the main module" requirement; Epochly enforces it rather than letting it corrupt your program.

Architecture

• Truth surface: single unified schema for status, metrics, and inspect outputs. optimization_effective and optimization_summary reflect measured execution, not heuristics. Rollback events, fallback reason codes, admission decisions, and realized enhancement level are surfaced in machine-readable artifacts.
• Circuit breaker: bounded HALF_OPEN probe concurrency; on failure, execution rolls back to the unmodified code path with full cache invalidation. No silent drift.
• Inference plugin: optimizes .generate/.encode/__call__ on ML model objects when safe; falls back otherwise.
• Prefilter correctness: all rejection paths emit explicit, machine-readable fallback reason codes. No silent false rejects on known-valid numeric workloads.
• Memory safety: adjacent-block coalescing in HybridLargeBlockManager; real OS mprotect(PROT_NONE) guard pages; serialized FastMemoryPool bookkeeping under contention; TOCTOU guards in stale shared-memory cleanup.

Environment

• Python 3.9 through 3.14
• Linux, macOS, or Windows
• NVIDIA GPU optional (required for L4)
• Project virtual environment: .venv at project root
• Cross-version development venvs: .venv-py38 through .venv-py313 alongside .venv

Running Tests

Always activate the virtual environment first.

source .venv/bin/activate
pytest tests/unit/<module>/ -v

Examples:

source .venv/bin/activate
pytest tests/unit/core/ -v
pytest tests/unit/jit/ -v
pytest tests/unit/memory/ -v

Never use pytest --cov. The pytest-cov plugin imports Epochly before environment variables are set, causing OpenBLAS thread creation and memory exhaustion. Use coverage.py directly instead:

source .venv/bin/activate
coverage run -m pytest tests/unit/<module>/ -v
coverage report --include="src/epochly/<module>/*" --show-missing

Project Structure

epochly/
├── src/epochly/           # Main source code
│   ├── core/             # Core runtime, enhancement levels, decorator
│   ├── jit/              # JIT compilation, artifact store, compilation queue
│   ├── memory/           # Memory management, shared memory, circuit breaker
│   ├── gpu/              # GPU detection, CUDA acceleration (L4)
│   ├── inference/        # ML model inference plugin
│   ├── monitoring/       # Metrics, telemetry, Prometheus exporter
│   ├── security/         # Signed pickle, AST sanitizer, access control
│   ├── licensing/        # License validation, trial endpoint hardening
│   ├── cli/              # Command-line interface
│   ├── config.py         # Configuration system
│   ├── bytecode_prefilter.py  # L1/L2 eligibility classification
│   └── ...
├── tests/
│   ├── unit/             # Unit tests (per-module)
│   ├── integration/     # Integration tests
│   ├── validation/      # Validation contract tests
│   └── e2e/             # End-to-end tests
├── .github/workflows/   # GitHub Actions CI/CD workflows
├── benchmarks/          # Benchmarking system
├── scripts/             # Helper scripts
├── dashboard/           # Dashboard application
└── docs/                # Documentation

CI/CD

Epochly uses GitHub Actions with self-hosted runners:

• 16 self-hosted Linux runners on 192.168.1.17 (NVIDIA RTX 4070, Python 3.9-3.14, GPU label)
• Self-hosted macOS runners on Mac-Studio
• GitHub-hosted Windows runners

Key workflows:

• release-gate.yml — tier-1/tier-2 test matrix across all platforms and Python versions
• post-merge-assurance.yml — commit-scoped PMA on every main merge
• full-matrix-validation.yml — nightly full matrix across all OS/Python combinations
• security-scan.yml — Bandit + dependency audit
• smoke-tests.yml — quick smoke validation
• wheels.yml — build and test wheels
• publish-pypi.yml — publish to PyPI after release gate passes

Security

For Epochly's security policy, vulnerability reporting process, threat model, and per-field telemetry data flow, see SECURITY.md and docs/security/. The latter contains threat-model.md and telemetry-data-flow.md.

Built-in security properties of the runtime:

• Memory isolation between interpreters
• Access control for shared memory
• Audit logging for all operations
• HMAC-signed pickle helper for trusted IPC boundaries (epochly.security.signed_pickle)
• Hardened AST sanitizer for dynamically-compiled user code paths
• Prometheus exporter defaults to loopback (127.0.0.1) with explicit warning on 0.0.0.0
• Bounded Prometheus metric-name cardinality (user-input hashing + 1000-name ceiling)

Stabilization Evidence

P0 Stabilization (2026-04-16)

24 behavioral assertions in validation-contract.md, 30+ new regression tests:

• Bounded HALF_OPEN probe concurrency in memory circuit breaker
• Adjacent-block coalescing in HybridLargeBlockManager
• Real OS mprotect(PROT_NONE) enforcement on memory-pool guard pages
• Fixed small-slab bitmap math
• Serialized FastMemoryPool bookkeeping under contention
• Linux RTX 4070 verification: 1012 passed, 90 skipped, 0 failed
• 5% wall-clock overhead budget preserved on non-beneficial workloads

Phase 2 Stabilization (M5-M13)

116 additional behavioral assertions across 9 milestones:

• NUMA-aware memory placement and monitoring hardening (M5-M6)
• Runtime, JIT, and ML-path correctness (M7-M8)
• Licensing integrity (M9)
• Boot-sequence, core, and config robustness (M10)
• CLI, Jupyter, and deployment paths (M11)
• GPU and native inference sweep on RTX 4070 (M12)
• Progression integrity, hygiene, Cython wheel verification (M13)
• Hygiene guardrails as executable tests: tests/validation/test_no_mocks_in_src.py, tests/validation/test_no_banned_env_writes.py

Transparent-Optimizer Trust Mission (M1-M9)

107 features across 9 milestones making Epochly a trustworthy transparent optimizer for the qeval evaluation corpus:

• M1: Baseline gap map and ranked failure classification
• M2: Truth surface unification — single schema, measured-only reporting
• M3: Prefilter correctness — no silent false rejects, machine-readable fallback reason codes
• M4: L3 multicore and shared memory — TOCTOU race fix, process pool caching fix
• M5: L4 GPU admission — duplicate-init fix, numerical tolerance tightening, cross-version validation
• M6: Rollback and circuit breaker — cache invalidation on rollback, drift detection
• M7: optimize/wrap() bootstrap and inference plugin — 4-step bootstrap fix, ML model optimization
• M8: Stability hardening — numerical differential tests, concurrency/memory safety, packaging/API verification
• M9: Final qeval-gated verification — all P0 regression families HELD/PASS or CLOSED

Configuration

from epochly import configure, EnhancementLevel

# Set optimization level
configure(enhancement_level=EnhancementLevel.LEVEL_3_FULL)

# Enable profiling
configure(profile_enabled=True)

# Control worker threads
configure(max_workers=8)

Monitoring

import epochly

# Get performance metrics
metrics = epochly.get_metrics()
print(f"Enhancement level: {metrics.get('enhancement_level')}")
print(f"Functions optimized: {metrics.get('functions_optimized', 0)}")

# Check current status
status = epochly.get_status()
print(f"Enabled: {status['enabled']}")

Deployment

# Selective activation by environment
export EPOCHLY_ENABLED=1
python your_app.py

# Inspect deployment state
epochly-deploy status

# Enable or disable deployment
epochly-deploy enable
epochly-deploy disable

# Select a deployment mode
epochly-deploy set-mode monitor

# Monitor deployment for 60 seconds
epochly-deploy monitor --duration 60

# Emergency stop
epochly-deploy emergencystop

Contributing

# Development setup
git clone https://github.com/chandlercvaughn/epochly.git
cd epochly
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pre-commit install

# Run tests (always activate the venv first)
source .venv/bin/activate
pytest tests/unit/<module>/ -v

# Cross-version testing
.venv-py39/bin/python -m pytest tests/unit/cli/ -v
.venv-py310/bin/python -m pytest tests/unit/cli/ -v

# Coverage (use coverage.py directly, NOT pytest --cov)
source .venv/bin/activate
coverage run -m pytest tests/unit/<module>/ -v
coverage report --include="src/epochly/<module>/*" --show-missing

Cython extensions build with python setup.py build_ext --inplace.

License

Epochly is proprietary commercial software licensed under the Epochly Software License Agreement (ESLA). See LICENSE for the complete license terms.

• Terms of Service
• Privacy Policy