Skip to main content

hugpy-oracle

The staged HTTP Blueprint is bundled under hugpy_video.routes:video_bp. It supplies /oracle/* and /video/script/*, with the host's /api prefix when mounted by Core or the standalone Video app. Oracle publishes planner hooks, but no separate hugpy.arms entry point: Video mounts these routes once.

The decision layer above Hugpy's execution packages (import name hugpy_oracle). The package metadata records the source version. 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 HTTP integration).

Relationship to hugpy-video

  • video → oracle is a required dependency. See Video's package metadata for the supported Oracle version range.
  • 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.11,<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      frozen contracts shared across the domain packages
  planning/         plan graphs, validation, prompt compilation, schema export
  cinema/           audio masters, production locks, scripts, segments, storyboards,
                    studio plans, world building, post-production, performance runs
  routing/          capability catalog, authority gates, router, selection, routing matrix
  execution/        dispatch runtime, durable DAG journal, repairs, interim ledger
  assessment/       evaluator, benchmarks and cases, probes, scorecards, speech and
                    spatial checks, stationary scenario, selection steward
  geometry/         spatial contracts and scene-source adapters
  recipes/          executable production recipes
  web/              api.py (oracle_bp), http_routes.py (request and inspection endpoints),
                    script_routes.py, request_planning.py, routes.py (Video integration)
  cli.py            `hugpy-oracle`
deploy/             hugpy-steward.service / .timer (not installed by anything)

Import modules from these packages directly; the old flat module paths have been removed without compatibility aliases. Name-matching primitives live in hugpy_engine.name_match.

HTTP integration

Video mounts Oracle's native Blueprint beneath hugpy_video.routes:video_bp. Core or the standalone Video app supplies the /api prefix. This exposes /api/oracle/* and /api/video/script/* alongside Video's planning and job APIs. Oracle does not publish a separate hugpy.arms entry point; mounting it twice would duplicate routes.

Planner hooks bind Oracle implementations into Video's studio/producer planning paths. Capability responses describe available bindings; they do not prove a successful render on a particular worker.

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 serving the Video/Oracle composite Blueprint.
    • 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.

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.

Variable Default Store
HUGPY_ORACLE_HOME <hugpy_home>/oracle small stores
HUGPY_ORACLE_RUNS_ROOT <models_root>/video_intel run journals
ORACLE_LEDGER_PATH <oracle_home>/reliability.sqlite reliability ledger
ORACLE_BENCHMARK_ROOT the legacy benchmark root if that directory exists, else <oracle_home>/model-battery benchmark sweeps
ORACLE_ROUTING_MATRIX unset (use the newest registry-verified matrix under the benchmark root) pinned routing matrix
HUGPY_PERFORMANCE_RUN_ROOT, HUGPY_SCRIPT_FIRST_RUN_ROOT, HUGPY_INTERIM_LEDGER_ROOT the runs root per-feature run stores
HUGPY_API unset steward remote mode
HUGPY_CORE_URL http://127.0.0.1:7020 engine calls (through hugpy_engine.execute_prompt)

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

Install

python -m pip install hugpy-oracle
python -m pip install 'hugpy-oracle[video]'  # Video-backed studio workflows

For source development, run python -m pip install -e '.[test]' from this Python package directory. The Video Debian installer also bundles Oracle.

Dependencies and entry points

Runtime dependencies are hugpy-platform, hugpy-engine, flask, werkzeug and numpy (not hugpy-media: Media is reached through Core). Pillow, pynvml, hugpy-agent and hugpy-video are optional extras; exact constraints are in pyproject.toml. The console script is hugpy-oracle; the hugpy.video.hooks entry point registers hugpy_oracle:install_hooks.

See Video, its UI, and the Core route convention.

Metadata

Release files for hugpy-oracle 0.3.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hugpy-oracle 0.3.22
File Size Uploaded Provenance Actions
hugpy_oracle-0.3.22.tar.gz 801.0 kB Without provenance Details for hugpy_oracle-0.3.22.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hugpy-oracle 0.3.22
File Interpreter ABI Platform Actions
hugpy_oracle-0.3.22-py3-none-any.whl Python 3 none any Details for hugpy_oracle-0.3.22-py3-none-any.whl

Total release size: 1.5 MB

Release files / hugpy_oracle-0.3.22.tar.gz

Download URL hugpy_oracle-0.3.22.tar.gz
Size 801.0 kB
Tags Source
SHA-256 checksum
How to use checksums
0781090a3b2dee0924ba377464a3270e6985d7379de75aa9f6efa697b6aab454
BLAKE2b-256 checksum
How to use checksums
3d3070180dc25dc25d0114d55ed6605bb6ffeea72609cb0b49db92c1725e5b33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / hugpy_oracle-0.3.22-py3-none-any.whl

Download URL hugpy_oracle-0.3.22-py3-none-any.whl
Size 656.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
76b5bea3736aef738d903028709ebf110a23537f2ab6da133ec971d1231911ed
BLAKE2b-256 checksum
How to use checksums
eea608c707eb4eb6a0b6e47dcb83a1dd5eef677f34e3e3f7fcce1eca445992ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for hugpy-oracle 0.3.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.22 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page