Metadata-Version: 2.4
Name: hugpy-oracle
Version: 0.3.17
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: hugpy-media
Requires-Dist: abstract-flask>=0.0.0.1052
Provides-Extra: video
Requires-Dist: hugpy-video<0.4,>=0.3.11; extra == "video"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
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 source tree is at **0.3.11**; the copy bundled in the
installed `hugpy-video` deb on this host is **0.3.10**. The 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 [What is live](#what-is-live)).

## Relationship to hugpy-video

* **video → oracle** is the hard edge. `hugpy-video` 0.3.5 depends on
  `hugpy-oracle>=0.3.11,<0.4` (0.3.4 required `>=0.3.10`).
* **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.4,<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`.

## What is live

On this host (2026-10-15), oracle functionality is served **through the video
arm's toolset** (`hugpy-video` 0.3.4, `:7341`, proxied by core):

| Video route | Oracle backend |
|---|---|
| `video/studio/plan` | `hugpy_oracle.cinema.studio_generation.plan_studio_generation` (installed into video's studio-planner hook) |
| `video/producer/plan` | `hugpy_oracle.cinema.studio_producer.produce_studio_plan` (producer-planner hook) |
| `video/performance/probe` | `hugpy_oracle.relay.performance_relay.probe`: which seams the performance runner needs are bound on this box, reported as data |
| `video/script/runs` | `hugpy_oracle.cinema.script_first` (`GET` lists runs and promoted sources; `POST` starts a run) |
| `video/script/sources` | `hugpy_oracle.cinema.script_first.list_promoted_sources` |

The probe on this host reports `ready: false`. The `gen_clip` and `judge_clip`
seams are unbound, and a full performance needs image generation and judging,
clip generation and judging, audio and assembly all bound. An unbound clip seam
is a capability gap, not a successful render.

**Not live:**

* **The `oracle_bp` Blueprint** (`hugpy.arms` entry point `oracle =
  hugpy_oracle.web.api:oracle_bp`) carries `/oracle/status`, `/oracle/studio/plan`,
  `/oracle/studio/production`, `/oracle/steward` (GET reports, POST applies
  bounded rebalancing), `/oracle/capabilities`, `/oracle/route`,
  `/oracle/selection`, `/oracle/producers`, `/oracle/ledger/summary`, and the
  full script-first tree `/video/script/runs/<run_id>/{plot,screenplay,audio_master,preproduction,lock,revise,segments,promote}`.
  Only a host that mounts `hugpy.arms` Blueprints in-process serves it: the
  legacy Flask core did. The live Basic Core proxies arms through `arms.d`
  instead, and the oracle has none, so `GET /api/oracle/status` is **404** on
  `:7020` and on `:7341`.
* **`POST /video/jobs/performance`**, the Oracle station's performance submit,
  has no route in hugpy-video 0.3.4 (404). This is pending.

## Command line

```bash
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 that serves `oracle_bp`, so it
    does not work against this host's core today.
  * **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.

`deploy/hugpy-steward.{service,timer}` schedules `hugpy-oracle steward --apply`
every 15 minutes against `HUGPY_API=http://127.0.0.1:7002` (the legacy central
port). The units are **not installed** on this host. Review them before you
install them, because they target a legacy API port.

## 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

There is no deb. The oracle travels as a bundled wheel inside the
`hugpy-video` deb (`/opt/hugpy-video/venv`, which has `hugpy-oracle` 0.3.10
today).
To develop on it, install it from source (`pip install -e
packages/hugpy_oracle[test]`), adding the `video` extra or a local
`hugpy_video` checkout for the studio-backed paths.

## Dependencies

Runtime (`pyproject.toml`, 0.3.11): `hugpy-platform`, `hugpy-engine`,
`hugpy-media`. 0.3.11 dropped `hugpy-control`, which nothing in the oracle
imported; 0.3.10 still declared it. Flask is not declared directly. `api.py` imports it, and it
arrives through `hugpy-media`. Extras: `video` (`hugpy-video>=0.3.4,<0.4`) and
`test`.

## Entry points

| Group | Name → target |
|---|---|
| `console_scripts` | `hugpy-oracle` → `hugpy_oracle.cli:main` |
| `hugpy.video.hooks` | `oracle` → `hugpy_oracle:install_hooks` (loaded by `hugpy_video.web.api`) |
| `hugpy.arms` | `oracle` → `hugpy_oracle.web.api:oracle_bp` (in-process hosts only; see What is live) |

## Related

[docs/arms.md](../../docs/arms.md) ·
[docs/execute_prompt.md](../../docs/execute_prompt.md) ·
[hugpy-video README](../hugpy_video/README.md) ·
[video UI](../../ui/video_intelligence_ui/README.md)
