SemantiFX inference worker

This directory contains the local JSONL worker described by ../protocol. It has no runtime dependencies for the protocol, CLI, or deterministic mock backend. The Text2FX backend loads the sibling checkout and therefore needs Text2FX's Python 3.9 dependencies.

Run without installing

From this directory:

Pass --progress-file /tmp/semantifx-progress.json to atomically publish the latest phase, optimizer step, total step count, and intermediate parameters. Progress is advisory and never replaces the final protocol result on stdout.

Run a persistent worker and send one JSON request per line:

Stdout is reserved for JSONL responses. Diagnostics from Text2FX and progress bars are captured so they cannot corrupt the stream. Use --diagnostics to copy captured diagnostics to stderr after each response.

Install the lightweight worker

Use the sibling Text2FX checkout

If Text2FX already has a working environment, invoke this package with that interpreter while adding this package's source directory:

The default sibling checkout is resolved as ../../oss/text2fx relative to this repository. Override it with SEMANTIFX_TEXT2FX_REPO=/absolute/path. Model caches remain controlled by Text2FX and its ML libraries; do not place them in this repository.

Progress preview and cooperative interruption require the sibling checkout's text2fx.apply.main(..., progress_callback=...) interface. The adapter fails with an actionable error when that interface is missing instead of silently running without interruption support.

A persistent worker reuses each loaded CLAP model within its process. Result metrics report model_cache_hit and model_cache_miss; terminating the worker releases the model. Optional options.random_seed makes cold and warm optimization requests start from the same random state.

The development plugin uses a private atomic-file adapter around that same long-lived process:

It consumes one request.json at a time and publishes request-correlated progress.json and result.json snapshots. A matching stop.json interrupts at the next optimizer progress callback without unloading the model. This spool interface is intentionally not part of the public protocol; it exists because JUCE's child-process interface cannot write to a worker's stdin.

Benchmark

Manifest-driven mock and Text2FX benchmark examples, including a two-request model-cache smoke, are documented in benchmarks/README.md. The runner writes JSONL and CSV summaries and never copies audio into results.

Test