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.

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; after orders steps that pass no data. candidates runs N takes ({"$candidate": base} varies a seed), attempts and timeout_s bound 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 /v1 routes). It is HUGPY_ORACLE_WRAPPER_URL, else HUGPY_CORE_URL / HUGPY_FITEVICT_FRONT_DOOR when set, else the hosting Core when Core hosts the oracle, else the url in /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_KEY or HUGPY_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
  • grants and runs act on the orchestration store as the operator. A run approved here is continued by the serving process within a few seconds.

  • 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
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.24

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.24
File Size Uploaded Provenance Actions
hugpy_oracle-0.3.24.tar.gz 833.1 kB Without provenance Details for hugpy_oracle-0.3.24.tar.gz

Built distribution (wheel)

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

Total release size: 1.5 MB

Release files / hugpy_oracle-0.3.24.tar.gz

Download URL hugpy_oracle-0.3.24.tar.gz
Size 833.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a3a54e918cf903324a253dd436746d46e3364c9dc0d174af626483a0d3e989d9
BLAKE2b-256 checksum
How to use checksums
61ca894703e179c8970dc4957791e6b46260757fb8c6dacec2b57fb5c47098df
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.24-py3-none-any.whl

Download URL hugpy_oracle-0.3.24-py3-none-any.whl
Size 682.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5627624166e620ae9e6a2719731854e41c02455583fbe8c99917bc89e169e67d
BLAKE2b-256 checksum
How to use checksums
e4219669f92dbad2ec52b9716d2433c1e92d1911a5463917bdb7a7d8b7f46ce4
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.24

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.24 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