Metadata-Version: 2.4
Name: swc-runtime
Version: 0.3.0
Summary: TrueLoop Compute client with Envelope V2 assessment
Author: NEOTECH Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://trueloopcompute.com
Project-URL: Docs, https://trueloopcompute.com/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# swc-runtime — TrueLoop Compute client

This is the thin, standard-library client for the hosted TrueLoop runtime. The private update law remains server-side. Runtime calls keep the substrate-agnostic `start → measure → step → end` contract; Envelope V2 separately describes the application, substrate, hardware timing, coupling structure, and evidence boundary.

## Install

    python -m pip install swc-runtime

For a local/manual installation, download the reviewed client bundle, verify
`HASHES.sha256`, and install its wheel:

    python -m pip install ./swc_runtime/dist/swc_runtime-*-py3-none-any.whl

For source-only manual use, place the bundled `swc/` folder beside your code.

## Runtime quickstart

    from swc import SWCOptimizer

    opt = SWCOptimizer(license_key="EVAL-...", n=len(x0), mode="regulation", target=target)
    x = opt.start(x0)
    for _ in range(rounds):
        x = opt.step(measure(x), target=target)
    opt.end()

The legacy `jacobian=` constructor argument is reserved and deprecated. The hosted runtime never consumed it, and this client no longer transmits it. Supplying it emits a nonfatal warning and does not change hosted execution or install a new controller.

## Envelope V2

`assess_envelope()` returns the complete structured report. `check_envelope()` still returns only `"USE"`, `"MARGINAL"`, or `"DECLINE"` for legacy callers.

    from swc import SWCOptimizer, EnvelopeProfile

    opt = SWCOptimizer(license_key="EVAL-...", n=4096, mode="regulation")
    profile = EnvelopeProfile(
        application="photonic.mesh.regulation",
        substrate="photonic",
        mode="regulation",
        n_controls=4096,
        n_measurements=4096,
        measurement={
            "shape": "vector", "parallel": True, "direction_rich": True,
            "action_consistent": True, "objective_observable": True,
            "semantics": "full_vector_residual", "noise_sigma": 0.02,
        },
        plant={
            "drifting": True, "drift_per_round": 0.01, "locally_monotone": True,
            "retainable_configuration": True, "target_type": "vector_setpoint",
        },
        coupling={
            "present": True, "structure": "banded", "bandwidth": 3,
            "normalized_mass": 0.3, "conditioning_known": False,
        },
        hardware={"parallel_readout": True, "physical_hardware": False},
        baseline={"type": "unknown", "tuned": False, "model_access": "none",
                  "demonstrated_performance": "unknown"},
        budget={"measurements_per_round": 1, "total_measurements": 300,
                "rounds": 300},
        evidence_profile="photonic.mesh.regulation.banded.v1",
    )
    report = opt.assess_envelope(profile)
    assert report["verdict"] == "USE"
    assert report["decision_scope"] == "pilot"

Legacy `Regime` requests remain accepted:

    from swc import Regime
    verdict = opt.check_envelope(Regime(drifting=True, coupled_plant=True,
                                        have_calibration=False,
                                        per_channel_error=True))

Unknown coupling structure is `MARGINAL`, not an automatic decline. Absence of calibration alone never triggers `DECLINE`.

## Evidence boundary

The mesh scaling evidence uses a simulated nonlinear photonic-mesh plant with the live production TrueLoop runtime. Exact registered cells are M=0.3 at n=64, 256, 512, 1024, and 4096, plus M=0.7 only at n=256, with ±3 banding, measurement noise sigma 0.02, drift sigma 0.01 radians per round, three seeds, and 300 rounds.

Physical photonic-hardware transfer remains unverified. The n=4096, M=0.7 combination was not tested. Discrete cells are not a continuous performance guarantee.

Full docs: https://trueloopcompute.com/docs/envelope
