Programmatic API Usage

The programmatic surface of Pyvorin Native is the package itself. There is no HTTP client to configure, no endpoint to pass and no job object to poll: you import pyvorin into your process, hand it source, and receive callable compiled functions plus structured diagnostics objects. Every signature and attribute quoted below was probed directly against the installed pyvorin-native 1.0.9 build — import pyvorin and check for yourself.

The previous version of this page documented a client that uploaded source to a remote compiler and polled for an artefact. No such client is part of this product. What follows is the real surface.

The public surface

The package root exports a deliberately small set of names. Verified via dir(pyvorin) and the package's __all__:

from pyvorin import (
    PyvorinCompiler,      # unified compile/router entry point
    CompiledFunction,     # compiled-callable type
    CompilationCache,     # in-process artefact cache
    kernel,               # @kernel marker decorator
    # integrated analysis helpers
    ETLCompatAssessor, ETLAssessment, CompatibilityVerdict, Finding,
    HotLoopDetector, KernelCandidate, ExtractionResult,
    build_simd_registry,
)

Everything in this page hangs off PyvorinCompiler, so start there. One preliminary worth thirty seconds of your time: pin the version you built against and assert it at import, because the compiled surface changes between releases.

import pyvorin
assert pyvorin.__version__ == "1.0.9"   # the build this page was verified against

Compiling in-process

The constructor takes a backend choice, a fallback policy and optional compiler options:

PyvorinCompiler(
    backend="auto",            # "auto" or "native"
    allow_fallback=True,       # divert to honest CPython on failure
    compiler_options=None,     # per-compiler option dict
)

The methods that matter, with their verified signatures:

A minimal session, run for real while writing this page:

from pyvorin import PyvorinCompiler

src = '''
def square_sum(n):
    total = 0
    for i in range(n):
        total += i * i
    return total
'''

compiler = PyvorinCompiler(backend="auto")
result = compiler.compile(src, function_name="square_sum")
print(result.backend_used)          # pyvorin-native-llvm
print(compiler.call("square_sum", 1000))   # 332833500

# execute() is the list-argument variant:
print(compiler.execute("square_sum", args=[1000]))   # 332833500

What compile hands back

The returned object carries both the callable and its own report card. The attribute list is long; these are the fields we found most useful, all read from a live object:

The design intent shows in the separation: compilation cost, first-call cost and steady-state cost are three different numbers on the same object, so an integration can amortise honestly instead of averaging the warm-up into the measurement.

Reading the diagnostics objects

compile_with_report returns a CompileResult — the same record the CLI's JSON report serialises. Its fields include status (a CompilationStatus such as COMPILED_FULLY or COMPATIBILITY_EXECUTED), compiled, failed, compatibility_executed, error_message, fallback_events, fallback_count, guard_failures, deopt_count, vectorized and to_dict() for serialisation. get_execution_report() returns an ExecutionReport with overall, per_function and tier_summary views plus to_json().

Watch the fallback path behave correctly, captured from a real session. The function below uses a global statement — an unsupported AST pattern in this build:

src = '''
g = 0
def bump():
    global g
    g += 1
    return g
'''

compiler = PyvorinCompiler(backend="auto")
report = compiler.compile_with_report(src, function_name="bump")
print(report.status)          # CompilationStatus.COMPATIBILITY_EXECUTED
print(report.error_message)   # None — nothing crashed

result = compiler.compile(src, function_name="bump")
print(result.backend_used)    # pyvorin-cpython-fallback
print(result.fallback_reason) # Native compilation produced compatibility-mode execution
print(compiler.call("bump"))  # 1 — original Python, correct
print(compiler.call("bump"))  # 2 — state carries across calls

The important properties, all demonstrated above: the fallback is the original source executed as ordinary CPython, so semantics — including mutable state — survive untouched; the diversion is recorded rather than silent, on both fallback_reason and the report's fallback_events; and nothing raises, because correctness was never at risk. When you would rather the failure be loud, strict=True raises on compilation failure and native_only=True refuses the compatibility path. Those two flags are how you turn a forgiving library into a gate. The full taxonomy of statuses, reasons and exit behaviour lives on the error handling and diagnostics page.

Serialising and reusing reports

The diagnostics objects are built to leave your process. CompileResult carries to_dict() and from_dict() for serialisation, merge() for combining records, and pretty_print() for logs; the compiler also exposes export_compilation_report(). ExecutionReport.to_json() produces a document shaped like the capture below, truncated to the fields that matter:

{
  "overall": {
    "tier": "compiled_full",
    "compiled": true,
    "compile_time_ms": 163.12,
    "fallback_count": 0,
    "guard_failures": [],
    "unsupported_features": []
  },
  "per_function": {
    "square_sum": { "...": "..." }
  }
}

The overall and per_function split means a monitoring integration can alarm on the aggregate while still attributing a regression to one function. One habit worth copying from the CLI: record compile_time_ms and the cache flag alongside your timings, so a deploy that silently lost its cache shows up as a latency step you can explain.

Precompiling and the kernel marker

For services with a warm-up phase, precompile(source_code, ["fn_a", "fn_b"]) compiles a batch up front, and the disk cache then amortises that cost across process restarts — a repeated compile of unchanged source comes back with cache_hit: True and compile_time_ms: 0.0 in our runs. The mechanics of that cache, including its LRU cap and checksum validation, are covered on the warm-up and caching strategies page.

The @kernel decorator is a marker, nothing more — and knowing that saves you debugging time:

from pyvorin import kernel

@kernel
def discount(price, rate):
    return price * (1.0 - rate)

print(discount._nexus_kernel)   # True

It sets func._nexus_kernel = True, a one-line attribute the kernel-substitution pipeline looks for when it decides which functions are substitution candidates. It does not compile anything at decoration time. If you decorate and expect magic at import, you will wait a long while.

CompilationCache is the lower-level artefact store for integrations that manage caching themselves: CompilationCache(max_size=1000, so_cache_dir=None) with get/put/invalidate/stats/clear and get_cached_so/put_cached_so for the shared-object payloads. Most applications should leave caching to the compiler's own disk cache and treat this as an escape hatch.

Analysis helpers

The remaining exports support the assess-and-extract workflow: ETLCompatAssessor grades code for compilation compatibility and returns an ETLAssessment with Finding records and a CompatibilityVerdict; HotLoopDetector surfaces KernelCandidate hot loops as an ExtractionResult; build_simd_registry exposes the SIMD kernel catalogue. These mirror the developer CLI's assess, hotspot and simd-info commands if you prefer building that review step into your own tooling.

A worked judgement call

One decision will shape your integration more than any API choice: where to put the compiler in your architecture. Our recommendation from building against this surface: instantiate PyvorinCompiler once per process, compile at startup or first use with allow_fallback=True, and record backend_used per function into your own metrics. The fallback is a safety net, not a secret — if your dashboard shows a hot function quietly living on pyvorin-cpython-fallback for a week, that is a deployment smell, not a statistic. Flip native_only=True in pre-production CI to catch regressions while they are still diffs. Keep production forgiving and observable. Keep CI strict.

Where to go next

• Error handling and diagnostics — statuses, fallback reasons and exit codes for the same API.
• Warm-up and caching strategies — precompilation, cache hits and CI cache keys.
• How local compilation works — what the compiler does inside your process.
• Debugging compiled code — when the compiled result needs investigating.

Last reviewed 20 April 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Every signature, attribute list and output value on this page was captured by executing the code shown against the installed build on 13 September 2026.