Metadata-Version: 2.4
Name: hugpy-core
Version: 0.1.49
Summary: hugpy central, minimal: live worker registry (register/heartbeat), model->worker pick, and the OpenAI /v1 relay to workers. Lifted from legacy hugpy central without evict-to-fit, discovery, admission or DB state.
Author-email: putkoff <support@hugpy.ai>
License: Proprietary
Project-URL: UI, https://www.npmjs.com/package/@hugpy/ui
Project-URL: Homepage, https://hugpy.ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: flask>=2
Requires-Dist: abstract_flask
Requires-Dist: psycopg[binary]>=3
Requires-Dist: hugpy-storage
Requires-Dist: hugpy-engine>=0.3.1
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: video
Requires-Dist: hugpy-video>=0.2.7; extra == "video"
Provides-Extra: media
Requires-Dist: hugpy-media>=0.2.7; extra == "media"

# hugpy_core

hugpy central, minimal. Workers (`hugpy_worker`, one per box, over fitevict)
register and heartbeat here; the registry is live in memory. `/v1/chat/completions`
picks an online worker that has the model (resident first; `alloc.worker` pins one)
and relays to its `/infer/stream`. No evict-to-fit, discovery, admission or DB
state — each box's fitevict owns placement and the call log.

    hugpy-core --host 127.0.0.1 --port 7020


### Benchmark call-log history

`POST /llm/benchmark/run` opens a core call-log row before validation or planning.
Accepted runs keep that row pending until their asynchronous outcome is known.
Rejected plans retain their constraint reasons in the core response and error.
The response and `X-Hugpy-Request-Id` expose its request ID.

Benchmark history/status read `call_log`; the JSON state and run archives are no
longer read or written. Existing files are left intact as legacy evidence and
are not converted into invented historical call records. Grading entries store
call pointers and verdicts. History resolves answers and measurements from the
referenced execution records. Each benchmark inference core row points back to
the orchestration row, and its execution pointer identifies the wrapper row.
Pending benchmark rows from a previous core process are marked interrupted.


### The brain (failure auto-evaluation)

Ruling: toolserver `instructions/hugpy/brain/brain-established-2026-10-06`.
A brain lives in core: always present, callable, and it evaluates every
model-load failure automatically. hugpy-agent, when installed, adds features and
access on top (the agent-station TUI); without it, this brain does the work.

- **Event:** a `hugpy_wrapper.residents` row whose `load_error` changes fires
  `pg_notify('model_rows')`; `brain.ensure()` (started by `app.main`) listens
  and evaluates it. No polling.
- **Classify:** rules first, from the legacy taxonomy (`hard_load_failure`,
  `vram_fit`, `engine_unavailable`, `unreachable`, `vision_needs_slot`,
  `missing_dependency`, `other`), plus pip-shaped signals (`pip install X`,
  `No module named 'x'`, transformers' "requires the following packages").
- **Infer:** the brain model is asked only when the rules leave something open
  (class `other`, or an import name with no package name, e.g. `cv2` →
  `opencv-python`). The call goes through core's own `/v1/chat/completions`
  with `metadata.intent = "brain-evaluate"`, so it is a `call_log` row. The
  brain never overrules a class the rules determined.
- **Record:** every evaluation is a Help ticket (`help_tickets`, kind
  `load-failure`), de-duplicated per model/worker/error via `occurrences`.
- **Call it:** `POST /llm/brain/evaluate {error, worker?, model_key?, file?}`;
  `GET /llm/brain` shows the model, policy and listener state.

Settings → Policies → **Brain** (`settings_policies`):

| key | meaning |
|---|---|
| `brain.model` | the brain's model (fallback `HUGPY_BRAIN_MODEL`, then the help agent's model) |
| `brain.auto` | auto-evaluate load failures (default on) |
| `brain.auto_grade_min` | grader score (0–100) a fix must reach to apply without approval; unset = every fix needs approval |

Not automated yet (same ruling, next step): the venv ladder for
`missing_dependency` — existing env profiles → a new overlay profile → an
isolated profile — each candidate test-loaded and graded, then designated
(`model_workers.env_profile`) only when the grade meets `brain.auto_grade_min`.
Never pip-install into a shared venv.

### Verdicts priced at the pair's ctx and KV type

`planner.refresh_worker` passes each pair's `user_settings` to
`measured_verdict.price`: the verdict is priced at the pair's `ctx_pct`
(k% of the trained window, floored to 1024) and `kv_cache_type`
(f16 / q8_0 / q4_0). A knob write that touches either re-plans that worker
at once (`modeldb.pair_knobs` → `planner.replan`), so the console's Memory
distribution follows the knobs.
