epochly 0.6.11

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

Decorator Usage

from epochly import optimize

@optimize
def matrix_computation(data):
    # Epochly decides whether to accelerate this function
    return complex_computation(data)

result = matrix_computation(my_data)

Automatic Optimization

import epochly  # import provides optimization for eligible workloads

import numpy as np

def matrix_computation():
    a = np.random.rand(1000, 1000)
    b = np.random.rand(1000, 1000)
    return np.dot(a, b)

result = matrix_computation()  # optimized if Epochly determines it is safe and beneficial

Context Manager

from epochly import optimize_context

with optimize_context():
    result = heavy_computation()

Key Capabilities

• Drop-in overlay: no code changes required; Epochly decides whether to accelerate
• GPU acceleration (L4): up to 64x on large array workloads when CUDA hardware is available
• Multicore parallelism (L3): up to 8x on CPU-heavy tasks via process pool dispatch
• JIT prefilter (L1/L2): bytecode prefilter classifies eligible kernels; JIT compiles admitted ones
• Monitoring (L0): pass-through with instrumentation; zero overhead 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).

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

• 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