Architect Media Artifact Contract

Architect media intelligence stays Rust-native. The tracked contract is data/framework/agent-media-artifact-contract-v1.json; it records the Rust feature gates, model artifact paths, and environment variables the runtime checks before enabling speech-to-text, image OCR, scanned-PDF OCR, or NVIDIA Riva speech.

MEDIA_ROOT is the independent per-app directory for uploaded media; MODEL_ROOT is Architect’s directory for model weights and manifests. Models are never served through media URLs.

The repository does not track model weights, Riva clients, or operator credentials. Model weights are distributed separately from the Architect app and installed outside app source and bundle directories. Local development uses the ignored .deps/agent-media/ tree; installed servers configure an absolute external root such as /var/lib/pharos/models/architect through MODEL_ROOT or PHAROS_ARCHITECT_ARTIFACT_ROOT. Use pharos agent media-artifacts prepare to copy operator-provided local artifacts into that external tree and write SHA-256 manifests without downloading remote files. App rebuilds, source imports and exports contain no model weights.

Do not use C or C++ wrapper crates for this path. whisper-rs, mutter, pdfium-render, leptess, Tesseract, PDFium, whisper.cpp, Candle/tokenizer feature graphs that pull onig or esaxx, and runtime shell-outs to ffmpeg, tesseract, ocrmypdf, pdftotext, or whisper are outside the Architect Rust-native boundary.

Use agent-stt-rust for built-in offline speech-to-text. The runtime uses OxiWhisper with an operator-provided external GGML/GGUF model from MEDIA_STT_MODEL, PHAROS_ARCHITECT_STT_MODEL, or .deps/agent-media/rust-stt/*ggml*.bin|gguf. The default Architect app config expects /var/lib/pharos/models/architect/rust-stt/ggml-tiny.en.bin. OxiWhisper and its selected audio dependencies are Rust-native and do not require whisper.cpp or external audio binaries.

Use agent-ocr-rust for image OCR. The runtime uses OCRS, RTen, and Image with RTen or ONNX detection and recognition models from MEDIA_OCR_DETECTION_MODEL and MEDIA_OCR_RECOGNITION_MODEL, the matching PHAROS_ARCHITECT_* environment variables, or matching files under .deps/agent-media/ocrs/. The default Architect app config expects /var/lib/pharos/models/architect/ocrs/text-detection.onnx and .deps/agent-media/ocrs/text-recognition.onnx.

Use agent-pdf-ocr-rust for scanned-PDF OCR. The runtime rasterizes bounded PDF pages with karet-pdf/Hayro and passes the grayscale page images to OCRS. MEDIA_RUST_PDF_RASTERIZER_MANIFEST, PHAROS_ARCHITECT_RUST_PDF_RASTERIZER_MANIFEST, or .deps/agent-media/pdf-rasterizer/manifest.json must exist so operators can audit which rasterizer path was approved. The default Architect app config expects /var/lib/pharos/models/architect/pdf-rasterizer/manifest.json.

Use PHAROS_ARCHITECT_RIVA_CLIENT_MANIFEST only after a Rust-native Riva client manifest exists. A configured endpoint by itself does not make Riva speech available. The crates.io nvidia_riva crate exists, but it uses a build script that needs protoc on this host, so this repo keeps Riva behind a pre-generated Rust client artifact gate instead of making local builds depend on an external protobuf compiler.

pharos agent media-artifacts report is the local artifact check. Environment variables named PHAROS_ARCHITECT_* take precedence; otherwise Architect reads MODEL_ROOT, MEDIA_STT_MODEL, MEDIA_OCR_DETECTION_MODEL, MEDIA_OCR_RECOGNITION_MODEL, MEDIA_RUST_PDF_RASTERIZER_MANIFEST, MEDIA_PDF_OCR_PAGE_LIMIT, MEDIA_RIVA_CLIENT_MANIFEST, and MEDIA_RIVA_ENDPOINT from apps/architect/app.conf. Relative model paths resolve below the artifact root. pharos agent media-artifacts prepare --stt-model PATH --ocr-detection-model PATH --ocr-recognition-model PATH copies existing local model files into the configured artifact root, writes STT/OCR/PDF rasterizer manifests, and returns the same readiness report against the prepared root. Add --riva-client-manifest PATH --riva-endpoint URL only when an approved Rust-native Riva client artifact and endpoint proof exist.

pharos.production_readiness is the operator-facing product check. It reports feature flags, detected artifacts, available adapters, and blocked prerequisites without reading or printing model contents or secrets. External model files remain unopened during ordinary app startup and are loaded only when speech-to-text, image OCR or scanned-PDF OCR is requested.

Installing or updating external models

Extract the separately distributed model ZIP outside the Architect app directory. Prepare those local files with the existing CLI, for example:

pharos agent media-artifacts prepare --artifact-root /var/lib/pharos/models/architect --stt-model /path/to/unpacked/ggml-tiny.en.bin --ocr-detection-model /path/to/unpacked/text-detection.onnx --ocr-recognition-model /path/to/unpacked/text-recognition.onnx

The prepared tree contains rust-stt/ggml-tiny.en.bin, ocrs/text-detection.onnx, ocrs/text-recognition.onnx and pdf-rasterizer/manifest.json. Set MODEL_ROOT=/var/lib/pharos/models/architect in the installed Architect app.conf, replacing the path with your chosen absolute directory. The service account must have read access to the models; preparation requires write access to the destination. PHAROS_ARCHITECT_ARTIFACT_ROOT overrides app.conf when set in the service environment. For repository development, explicitly pass --artifact-root .deps/agent-media during preparation and use that directory in the local runtime app.conf or set PHAROS_ARCHITECT_ARTIFACT_ROOT to its absolute path. Model changes require restarting the local runtime so subsequent extraction uses the updated assets; they do not require rebuilding the app. Existing GGML/ONNX model compatibility requirements remain unchanged.