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-videois not a dependency of this package. Install thevideoextra (hugpy-oracle[video], which pullshugpy-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 inimports/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()raisesToolErrorwith the real cause, so hosts see{"error": ...}, not a bareImportError. import hugpy_oracleis 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
stewardruns one self-check pass of the selection system. It checks calibration, failure streaks, starvation, gap share, matrix staleness and cache honesty. With--applyit also applies bounded rebalancing.- Remote mode (
--api URLor$HUGPY_API) GETs, or with--applyPOSTs,<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.
- Remote mode (
install-hooksinstalls 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.21
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hugpy_oracle-0.3.21.tar.gz | 800.9 kB | Without provenance | Details for hugpy_oracle-0.3.21.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hugpy_oracle-0.3.21-py3-none-any.whl | Python 3 | none | any | Details for hugpy_oracle-0.3.21-py3-none-any.whl |
Total release size: 1.5 MB
Release files / hugpy_oracle-0.3.21.tar.gz
| Download URL | hugpy_oracle-0.3.21.tar.gz |
|---|---|
| Size | 800.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49a0eb9a068c5f4f78c32c34adbf414ac101049f22419bf93ec0073ce687280e
|
|
BLAKE2b-256 checksum How to use checksums |
36ab4ad085e5fb7d346a44f83891e4bb0b8528f2c7affb11a0fbfb5390b9e870
|
| 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.21-py3-none-any.whl
| Download URL | hugpy_oracle-0.3.21-py3-none-any.whl |
|---|---|
| Size | 656.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eb4989331430bd4bb0348694c294826345ca1d374ed8feec19f48a5cc2312f5a
|
|
BLAKE2b-256 checksum How to use checksums |
18f0f4817a11d2b13e921f6f45d84608ac5a63e43e1b21680e7c4aef385348b0
|
| 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.21
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.