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.
Orchestration runs
A tool call is one request and one answer. An orchestration is several
dependent calls that outlive a request, so the oracle holds the goal: one row
per run (who asked, for what, with which steps) beside the durable DAG journal,
in orchestrations.sqlite.
POST /oracle/runs {objective, steps, max_parallel?} -> 202
GET /oracle/runs[/<run_id>] state, per-step state, what awaits approval
GET /oracle/runs/<run_id>/steps/<step> one step's result and receipt
POST /oracle/runs/<run_id>/control {action, step?, note?}
GET /oracle/runs/<run_id>/artifacts[/<artifact_id>]
GET /oracle/grants POST /oracle/grants POST /oracle/grants/<id>/revoke
Paths are relative to where the host mounts its API. Core serves it under
/api (a bare path there is the console's static files), so a client calls
/api/oracle/runs; through a public front, /api/ takes a console session and
a key-holding client uses whichever door that front gives keys.
A step is any POST route the wrapper serves, or a catalog capability:
{"objective": "narrate a summary",
"steps": [
{"id": "summary", "endpoint": "/v1/summarize", "body": {"model": "…", "input": "…"}},
{"id": "speech", "endpoint": "/v1/audio/speech",
"body": {"model": "…", "input": {"$ref": "summary.summaries.0"}}},
{"id": "check", "capability": "audio.transcribe", "prompt": "…",
"inputs": [{"kind": "audio", "uri": {"$ref": "speech.artifacts.0.path"}}], "approval": true}
]}
{"$ref": "<step>.<path>"}reads an earlier step's reply;afterorders steps that pass no data.candidatesruns N takes ({"$candidate": base}varies a seed),attemptsandtimeout_sbound a step. There is no request deadline: the run continues in the background and a restart never repeats a finished step.- Steps go to one front door: a wrapper, or the Core that fronts several (both
serve the same
/v1routes). It isHUGPY_ORACLE_WRAPPER_URL, elseHUGPY_CORE_URL/HUGPY_FITEVICT_FRONT_DOORwhen set, else the hosting Core when Core hosts the oracle, else theurlin/etc/hugpy/wrapper.endpoint.json. Each call carries the credential its front door is owed, from what the installers already provisioned and nothing set for the oracle: to the configured Core, the engine's own (hugpy_engine.core_auth:HUGPY_PUBLIC_API_KEYorHUGPY_ROUTER_KEY); to this box's wrapper, the key in its endpoint record (token_env/token_file) when it issues one. The front door's operator controls (/v1/load,/v1/rehome,/v1/requests/…) are not steps. - An artifact is read from the reply when the front door delivered it inline
(Core does this for audio and images), from its path when that file is
readable here, else from
<front door>/v1/artifacts/<id>. - File inputs are a path on the wrapper's box, inline base64 (the plan is journaled, so it is capped at 8 MB) or an earlier step's artifact.
Authority is looked up, never sent. A step that conditions on a reference
voice, or names an identity_profile: / voice_profile: subject, runs only
under a grant an operator filed for the caller. authorized in a step body and
rights on /oracle/route are refused from a caller that is not an operator;
the oracle sets authorized on the outgoing call itself. Grants are checked at
submit and again when the step dispatches, so revoking one stops a run in
flight. A reference clip is granted by what it is — sha256:<hex> or
file:<path> — not by a label; a clip produced earlier in the run needs a
blanket (*) voice grant.
A gate is an operator's. approval: true holds a step until an operator
approves or rejects it. The caller may cancel, pause, resume or retry
its own run, and sees only its own runs.
Callers are attributed by providers.PrincipalSource. The default uses what
the stack already has. The operator is a request that proves it: its bearer or
X-Operator-Token equals ORACLE_OPERATOR_KEY or the host's
HUGPY_OPERATOR_TOKEN, or the console session the Video arm resolves is an
admin; or, hosted in a Core that supplies its key-gate verdict
(hugpy_core.web.api_access.principal), an admin-scope key from a caller
outside the box. Admin scope from inside the box is not proof — Core reads
every direct caller there, and every request its front passed through /api/,
as admin. Anyone else is that session's user, else their bearer key by digest,
else the shared anonymous. The Video arm's hosted-in-Core open mode, which
treats every admitted request as the operator, is deliberately not carried
over: it would let any tool call file its own grants. A host that knows more
installs its own source with providers.set_principal_source. The command line
on the box that holds the store is always the operator.
The routes are mounted where the rest of the oracle's are — nested in the Video
arm's blueprint, behind its gate. When that arm loads it calls
hugpy_oracle:on_arm_load, which starts the runner, so a run that was moving
when its process stopped continues in the next one.
Command line
hugpy-oracle steward [--apply] [--api URL | --local] [--ledger PATH] [--timeout S] [--compact]
hugpy-oracle grants add --principal ID --kind KIND (--subject S | --file CLIP) --evidence TEXT
hugpy-oracle grants list [--principal ID] [--all]
hugpy-oracle grants revoke GRANT_ID
hugpy-oracle runs list | show RUN | approve RUN STEP | reject RUN STEP | retry RUN STEP
hugpy-oracle runs cancel RUN | pause RUN | resume RUN
hugpy-oracle install-hooks
hugpy-oracle --version
-
grantsandrunsact on the orchestration store as the operator. A run approved here is continued by the serving process within a few seconds. -
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 |
ORACLE_ORCHESTRATION_DB |
<oracle_home>/orchestrations.sqlite |
orchestration runs, grants and their DAG journal |
HUGPY_ORACLE_WRAPPER_URL |
HUGPY_CORE_URL when set, else the url in /etc/hugpy/wrapper.endpoint.json |
the front door run steps are sent to (a wrapper or Core) |
HUGPY_PUBLIC_API_KEY / HUGPY_ROUTER_KEY |
unset | the bearer sent with step calls to the configured Core |
ORACLE_OPERATOR_KEY / HUGPY_OPERATOR_TOKEN |
unset | a bearer or X-Operator-Token equal to either is the operator |
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.27
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.27.tar.gz | 835.8 kB | Without provenance | Details for hugpy_oracle-0.3.27.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hugpy_oracle-0.3.27-py3-none-any.whl | Python 3 | none | any | Details for hugpy_oracle-0.3.27-py3-none-any.whl |
Total release size: 1.5 MB
Release files / hugpy_oracle-0.3.27.tar.gz
| Download URL | hugpy_oracle-0.3.27.tar.gz |
|---|---|
| Size | 835.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fdacc1e546b1c9fc639d2a26d05ac01a9e73d0ee2520a48fbe6c33d451c0f50a
|
|
BLAKE2b-256 checksum How to use checksums |
6b24fca26fba53af00b3213f3dbc43d1e2d4e045d43596b20d4d19f75be349d4
|
| 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.27-py3-none-any.whl
| Download URL | hugpy_oracle-0.3.27-py3-none-any.whl |
|---|---|
| Size | 684.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
23ac61be448033f857a88011a2f2b2d7bedb362933df3b819b0724ff69926b0d
|
|
BLAKE2b-256 checksum How to use checksums |
b001d52787fea94db7a73bfe9bf908f9a1ef79b2945ec5e73c508d241969c027
|
| 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.27
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.