hugpy-oracle

The decision layer above Hugpy's execution packages (import name hugpy_oracle). The source tree is at 0.3.11; the copy bundled in the installed hugpy-video deb on this host is 0.3.10. The oracle owns:

• creative planning (studio generation plans, producer plans, screenplay, storyboard, script-first runs);
• model selection, with the reliability ledger, routing matrix and steward;
• the plan DAG runtime, repair and evaluation, benchmarks and scorecards;
• authority and rights checks, and the audio master.

It produces immutable plans and specs and submits them to hugpy_video through video's public job API. It never writes video's state files.

hugpy_oracle is a library, not an arm. It has no toolset, no standalone server, no Debian package and no arms.d file. Its features reach users through the video arm (see What is live).

Relationship to hugpy-video

• video → oracle is the hard edge. hugpy-video 0.3.5 depends on hugpy-oracle>=0.3.11,<0.4 (0.3.4 required >=0.3.10).
• oracle → video is lazy and optional. hugpy-video is not a dependency of this package. Install the video extra (hugpy-oracle[video], which pulls hugpy-video>=0.3.4,<0.4) for the full studio path. The oracle reaches video's studio registry, runners and media bus only inside the functions that need them, with the import path named once in imports/constants.py (VIDEO_PACKAGE, VIDEO_STUDIO_ENUMS). If video is absent, the planning/evaluation core still imports and runs, and video-backed calls fail as data. imports.functions.lazy() raises ToolError with the real cause, so hosts see {"error": ...}, not a bare ImportError.
• import hugpy_oracle is cheap. Every public name in __all__ resolves lazily on first attribute access (PEP 562), so the import loads no registry, no catalog and no third-party stack.

Layout

src/hugpy_oracle/
  imports/          shared layer (imports no heavy backend)
    constants.py    ARM_NAME="oracle", VIDEO_PACKAGE, VIDEO_STUDIO_ENUMS
    functions.py    lazy()/first_lazy(): optional backends become ToolError
    classes.py      OracleError, ToolError
    init_imports.py explicit stdlib + shared re-exports (wildcards are forbidden)
  __init__.py       lazy public API + install_hooks()
  config.py         every state root, resolved in one place (see Environment)
  providers.py      Protocols for what the oracle must not import: DossierSource,
                    DoctrineSource, TaskCapabilityGate, LoadStateSource (set_*() installs them)
  relay/            hooks.py (install_hooks: video's PromptCoordinator, studio and producer
                    planners, execution observer, the `video_performance` bus job),
                    performance_relay.py (probe), prompt_coordination.py
  contracts.py plan.py validator.py dag_runtime.py router.py runtime.py selection.py
  steward.py scorecard.py evaluation.py repair.py repair_controller.py catalog.py
  probes.py schema_export.py authority.py speech.py audio_master.py production.py
  segments.py spatial*.py storyboard.py screenplay.py script_first.py
  studio_generation.py studio_producer.py request_planning.py recipes/ ...
  api.py            oracle_bp, the optional HTTP Blueprint (see below)
  http_routes.py    capability, route, selection, producer and ledger endpoints on oracle_bp
  script_routes.py  the /video/script/... script-first endpoints on oracle_bp
  cli.py            `hugpy-oracle`
deploy/             hugpy-steward.service / .timer (not installed by anything)

What is live

On this host (2026-10-15), oracle functionality is served through the video arm's toolset (hugpy-video 0.3.4, :7341, proxied by core):

The probe on this host reports ready: false. The gen_clip and judge_clip seams are unbound, and a full performance needs image generation and judging, clip generation and judging, audio and assembly all bound. An unbound clip seam is a capability gap, not a successful render.

Not live:

• The oracle_bp Blueprint (hugpy.arms entry point oracle = hugpy_oracle.api:oracle_bp) carries /oracle/status, /oracle/studio/plan, /oracle/studio/production, /oracle/steward (GET reports, POST applies bounded rebalancing), /oracle/capabilities, /oracle/route, /oracle/selection, /oracle/producers, /oracle/ledger/summary, and the full script-first tree /video/script/runs/<run_id>/{plot,screenplay,audio_master,preproduction,lock,revise,segments,promote}. Only a host that mounts hugpy.arms Blueprints in-process serves it: the legacy Flask core did. The live Basic Core proxies arms through arms.d instead, and the oracle has none, so GET /api/oracle/status is 404 on :7020 and on :7341.
• POST /video/jobs/performance, the Oracle station's performance submit, has no route in hugpy-video 0.3.4 (404). This is pending.

Command line

hugpy-oracle steward [--apply] [--api URL | --local] [--ledger PATH] [--timeout S] [--compact]
hugpy-oracle install-hooks
hugpy-oracle --version

• steward runs one self-check pass of the selection system. It checks calibration, failure streaks, starvation, gap share, matrix staleness and cache honesty. With --apply it also applies bounded rebalancing.
  • Remote mode (--api URL or $HUGPY_API) GETs, or with --apply POSTs, <api>/api/oracle/steward. That needs a host that serves oracle_bp, so it does not work against this host's core today.
  • Local mode (no API, or --local) runs in-process over the shared reliability ledger.
  • Output is JSON. The exit code is 0 when ok, 2 on an alarm and 1 on a transport or ledger failure.
• install-hooks installs the oracle's implementations into video's seams in this process and prints what was wired.

deploy/hugpy-steward.{service,timer} schedules hugpy-oracle steward --apply every 15 minutes against HUGPY_API=http://127.0.0.1:7002 (the legacy central port). The units are not installed on this host. Review them before you install them, because they target a legacy API port.

Environment

State roots (config.py) resolve in this order: the module's own variable, then HUGPY_ORACLE_HOME / HUGPY_ORACLE_RUNS_ROOT, then hugpy_platform.app_dirs.

Other knobs read in the code: ORACLE_SYNC_DEADLINE_S, ORACLE_SELECTION_DISABLE, ORACLE_PROBE_TTL_S, ORACLE_LEDGER_REMOTE, ORACLE_DAG_RECIPE.

Install

There is no deb. The oracle travels as a bundled wheel inside the hugpy-video deb (/opt/hugpy-video/venv, which has hugpy-oracle 0.3.10 today). To develop on it, install it from source (pip install -e packages/hugpy_oracle[test]), adding the video extra or a local hugpy_video checkout for the studio-backed paths.

Dependencies

Runtime (pyproject.toml, 0.3.11): hugpy-platform, hugpy-engine, hugpy-media. 0.3.11 dropped hugpy-control, which nothing in the oracle imported; 0.3.10 still declared it. Flask is not declared directly. api.py imports it, and it arrives through hugpy-media. Extras: video (hugpy-video>=0.3.4,<0.4) and test.

Entry points

Related

docs/arms.md · docs/execute_prompt.md · hugpy-video README · video UI