Metadata-Version: 2.4
Name: hugpy-oracle
Version: 0.3.24
Summary: Hugpy oracle: creative planning, model selection, screenplay and storyboard generation, DAG runtime, repair, evaluation and ledgers over the video pipeline
Author-email: putkoff <support@hugpy.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://hugpy.ai
Project-URL: Documentation, https://github.com/hugpy/hugpy/blob/main/py/cinema/hugpy_oracle/README.md
Project-URL: Repository, https://github.com/hugpy/hugpy
Project-URL: Source, https://github.com/hugpy/hugpy/tree/main/py/cinema/hugpy_oracle
Project-URL: Issues, https://github.com/hugpy/hugpy/issues
Project-URL: Changelog, https://github.com/hugpy/hugpy/releases
Project-URL: Architecture, https://github.com/hugpy/hugpy/blob/main/PARTITION.md
Keywords: hugpy,llm,self-hosted,planning,video,orchestration,evaluation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hugpy-platform
Requires-Dist: hugpy-engine
Requires-Dist: flask>=2
Requires-Dist: werkzeug
Requires-Dist: numpy
Provides-Extra: video
Requires-Dist: hugpy-video<0.4,>=0.3.20; extra == "video"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: images
Requires-Dist: Pillow; extra == "images"
Provides-Extra: nvml
Requires-Dist: pynvml; extra == "nvml"
Provides-Extra: agent
Requires-Dist: hugpy-agent; extra == "agent"
Dynamic: license-file

# 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](#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:

```json
{"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

```bash
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

```sh
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](../../hugpy-video/package/README.md), its
[UI](../../hugpy-video/ui/README.md), and the
[Core route convention](../../hugpy-core/package/docs/ROUTES-CONVENTION.md).
