Metadata-Version: 2.4
Name: hugpy-oracle
Version: 0.3.20
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 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.

## 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 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 |
| `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`, `hugpy-media` and
`abstract-flask`; exact constraints and extras 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).
