vramd 0.1.0__tar.gz

vramd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maikeu Locatelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vramd-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: vramd
+Version: 0.1.0
+Summary: Controlo de admissão de VRAM para inferência generativa em GPUs de consumo
+Author: Maikeu Locatelli
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/maikramer/vramd
+Project-URL: Repository, https://github.com/maikramer/vramd
+Project-URL: Issues, https://github.com/maikramer/vramd/issues
+Project-URL: Changelog, https://github.com/maikramer/vramd/blob/main/CHANGELOG.md
+Keywords: gpu,vram,inference,scheduler,admission-control,diffusion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: rich-click>=1.8.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: nvidia-ml-py>=12.535.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff==0.16.2; extra == "dev"
+Dynamic: license-file
+
+# vramd
+
+[![CI](https://github.com/maikramer/vramd/actions/workflows/ci.yml/badge.svg)](https://github.com/maikramer/vramd/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vramd.svg)](https://pypi.org/project/vramd/)
+[![Python](https://img.shields.io/pypi/pyversions/vramd.svg)](https://pypi.org/project/vramd/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Controlo de admissão de VRAM para inferência generativa em GPUs de consumo.**
+
+Um processo detém a GPU e decide quem entra. Admite pelo **pico real** — pesos +
+activação + margem, não só pesos — põe em fila com prioridade e afinidade,
+evicta por peso+LRU, e corre cada modelo num processo e venv próprios.
+
+Feito para inferência que dura **segundos a minutos** numa placa que não chega
+para tudo. Não é um servidor de LLM: não optimiza throughput de tokens, optimiza
+*caber*.
+
+```bash
+pip install vramd          # 9 MB — o supervisor não importa torch
+vramd start &
+vramd submit meu-modelo --prompt "…" --wait
+```
+
+## O problema
+
+Tens 6 GB de VRAM e cinco modelos que, somados, pedem 40. Cada um corre bem
+sozinho. Juntos, o segundo job entra a meio do primeiro e ambos morrem com
+`CUDA out of memory` — depois de já terem carregado os pesos.
+
+As soluções habituais assumem o que aqui não se verifica: que o modelo cabe
+(vLLM, TGI), que o ambiente é homogéneo (Ray Serve, Triton), ou que a unidade de
+trabalho é um token e não um job de dois minutos.
+
+## O que o vramd faz de diferente
+
+**Admite pelo pico, não pelos pesos.** A pergunta não é "o modelo cabe" — é
+"cabe o pico da inferência". É a diferença entre recusar em 0.2 s e morrer a 80%
+do job com os pesos já carregados.
+
+**Cada modelo no seu venv.** Um backend é um processo com o seu próprio
+interpretador. Modelos com dependências incompatíveis — torch 2.x contra 2.y,
+wheels CUDA diferentes — coexistem sem se verem.
+
+**Afinidade na fila.** Se a cabeça precisa de um modelo frio e mais atrás há um
+job cujo modelo já está em VRAM, o scheduler salta a cabeça (até 3 vezes, depois
+força). Onde um load custa 60 s, isto muda um batch de 40 minutos para 10.
+
+**Cancelamento cooperativo.** Jobs longos reportam progresso por fase e param
+*entre* fases — sem matar kernels CUDA a meio.
+
+**Mede em vez de adivinhar.** `vramd calibrate` corre um job real, amostra a
+VRAM por processo a 20 Hz e escreve o footprint medido. Sobre dez modelos reais
+numa RTX 4050, os valores escritos à mão erravam entre −3154 e +22448 MiB.
+
+## Integrar um modelo
+
+Três métodos:
+
+```python
+from vramd.worker import WorkerAdapter, run_worker_loop
+
+
+class Adapter(WorkerAdapter):
+    name = "meu-modelo"
+
+    def load(self, **kw):
+        import torch, meulib
+
+        return meulib.load(device=kw.get("device", "cuda"))
+
+    def generate(self, model, request):
+        if self.should_abort(request):
+            return self.cancelled_response()
+        self.report_progress(request, 0.0, "a gerar")
+        return {"status": "ok", "output": model(request["prompt"])}
+
+    def unload(self, model):
+        del model
+
+
+if __name__ == "__main__":
+    run_worker_loop(Adapter, backend_name="meu-modelo")
+```
+
+E registá-lo — sem tocar no código do vramd:
+
+```yaml
+# ~/.config/vramd/backends.d/meu-modelo.yaml
+version: 2
+backends:
+  - name: meu-modelo
+    adapter: meu_pacote.adapter
+    vram_mib: 4200
+    priority: 20
+    runtime:
+      command: ["/opt/meu-modelo/venv/bin/python", "-m", "meu_pacote.worker"]
+      env: { HF_HOME: ~/hf-cache }
+    load_keys: [device, compute_type]
+    shape_keys: [device]
+```
+
+Exemplo completo e executável: [`examples/echo-backend/`](examples/echo-backend/).
+
+## Calibração
+
+O atrito de qualquer sistema destes é a pergunta "que números meto no
+descriptor?". A resposta do vramd é: nenhum — mede-se.
+
+```bash
+vramd calibrate meu-modelo --repeats 3 --out ~/.config/vramd/backends.d/medido.yaml
+```
+
+Corre o job, separa **contexto CUDA / pesos / activação** pelas fronteiras de
+fase, e escreve o descriptor. O que apanha, e que uma estimativa não apanha:
+
+| Sinal | Porque importa |
+|---|---|
+| pico no **load** acima do da inferência | carregar fp16 e quantizar depois OOMa antes de gerar |
+| activação ≫ pesos | o modelo carrega outro modelo dentro do `generate` |
+| nada residente após o load | carga preguiçosa: não há o que evictar |
+| `unload` que não devolve VRAM | evictar este backend não liberta nada — o plano de evicção seria ficção |
+| fuga por repetição | o residente cresce a cada job |
+| warmup na 1.ª inferência | calibrar com `--repeats 1` inflaciona o número |
+
+Cada medição guarda as amostras cruas: `vramd recalibrate relatorio.json` refaz
+os números quando a análise melhora, sem voltar a ocupar a GPU.
+
+## Comandos
+
+```
+start stop status queue wait cancel flush backends preload evict reap
+respawn zero stats debug bench doctor calibrate recalibrate
+```
+
+- `vramd status` / `queue` — quem tem a GPU e o que espera
+- `vramd zero` — liberta toda a VRAM ociosa sem parar o supervisor
+- `vramd respawn <backend>` — reinicia só um worker (código novo) sem parar a fila
+- `vramd doctor` — diagnóstico de ambiente
+
+**Nunca é preciso `kill`.** Matar processos GPU corre contra a fila e mata o
+workload errado.
+
+## Configuração
+
+```
+data/backends.yaml (exemplo)  →  $VRAMD_BACKENDS_FILE  →  ~/.config/vramd/backends.d/*.yaml
+```
+
+Sobreposição **por chave**: um ficheiro com `{name: x, vram_mib: 5632}` corrige
+só esse campo e herda o resto. É assim que um descriptor calibrado entra em
+vigor sem editar o pacote.
+
+Variáveis: `VRAMD_BACKENDS_FILE`, `VRAMD_BACKENDS_DIR`, `VRAMD_TOOLS_ROOT`,
+`VRAMD_MAX_INFLIGHT`, `VRAMD_MAX_QUEUE_DEPTH`, `VRAMD_VRAM_SAFETY_MIB`,
+`VRAMD_PRIORITY`.
+
+## Limites conhecidos
+
+Vale a pena saber antes de adoptar:
+
+- **`MAX_INFLIGHT=1` por omissão** — uma geração de cada vez. É a escolha certa
+  para 6 GB e subutiliza uma A100. Há suporte para >1 com verificação de VRAM,
+  mas falta *packing* a sério.
+- **Multi-GPU sem placement central.** `gpu_ids` é passado ao worker; o
+  supervisor não decide colocação nem contabiliza por device.
+- **POSIX.** A leitura dos pipes usa `select`/`O_NONBLOCK`. Windows precisa de
+  uma camada de IO diferente.
+- **Sem autenticação.** Socket unix com permissões de utilizador. Local, não
+  partilhado.
+- **A calibração não faz milagres.** Mede o que o teu pipeline faz. Um modelo
+  que carrega tudo em fp16 de uma vez não passa a caber por ser medido — só
+  passas a saber que não cabe, e em 0.2 s em vez de a meio do job.
+
+## Origem
+
+Extraído do [AiGameKit](https://github.com/maikramer), onde nasceu para pôr dez
+modelos generativos (texto→imagem, →3D, →áudio, →movimento) a partilhar uma RTX
+4050 de 6 GB sem intervenção manual. Os números deste README são medições dessa
+placa.
+
+## Contribuir
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) — arrancar, estilo, e o que este projeto
+valoriza. A suite corre em ~27 s sem GPU.
+
+## Licença
+
+MIT — ver [LICENSE](LICENSE).

vramd-0.1.0/README.md

@@ -0,0 +1,188 @@
+# vramd
+
+[![CI](https://github.com/maikramer/vramd/actions/workflows/ci.yml/badge.svg)](https://github.com/maikramer/vramd/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vramd.svg)](https://pypi.org/project/vramd/)
+[![Python](https://img.shields.io/pypi/pyversions/vramd.svg)](https://pypi.org/project/vramd/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Controlo de admissão de VRAM para inferência generativa em GPUs de consumo.**
+
+Um processo detém a GPU e decide quem entra. Admite pelo **pico real** — pesos +
+activação + margem, não só pesos — põe em fila com prioridade e afinidade,
+evicta por peso+LRU, e corre cada modelo num processo e venv próprios.
+
+Feito para inferência que dura **segundos a minutos** numa placa que não chega
+para tudo. Não é um servidor de LLM: não optimiza throughput de tokens, optimiza
+*caber*.
+
+```bash
+pip install vramd          # 9 MB — o supervisor não importa torch
+vramd start &
+vramd submit meu-modelo --prompt "…" --wait
+```
+
+## O problema
+
+Tens 6 GB de VRAM e cinco modelos que, somados, pedem 40. Cada um corre bem
+sozinho. Juntos, o segundo job entra a meio do primeiro e ambos morrem com
+`CUDA out of memory` — depois de já terem carregado os pesos.
+
+As soluções habituais assumem o que aqui não se verifica: que o modelo cabe
+(vLLM, TGI), que o ambiente é homogéneo (Ray Serve, Triton), ou que a unidade de
+trabalho é um token e não um job de dois minutos.
+
+## O que o vramd faz de diferente
+
+**Admite pelo pico, não pelos pesos.** A pergunta não é "o modelo cabe" — é
+"cabe o pico da inferência". É a diferença entre recusar em 0.2 s e morrer a 80%
+do job com os pesos já carregados.
+
+**Cada modelo no seu venv.** Um backend é um processo com o seu próprio
+interpretador. Modelos com dependências incompatíveis — torch 2.x contra 2.y,
+wheels CUDA diferentes — coexistem sem se verem.
+
+**Afinidade na fila.** Se a cabeça precisa de um modelo frio e mais atrás há um
+job cujo modelo já está em VRAM, o scheduler salta a cabeça (até 3 vezes, depois
+força). Onde um load custa 60 s, isto muda um batch de 40 minutos para 10.
+
+**Cancelamento cooperativo.** Jobs longos reportam progresso por fase e param
+*entre* fases — sem matar kernels CUDA a meio.
+
+**Mede em vez de adivinhar.** `vramd calibrate` corre um job real, amostra a
+VRAM por processo a 20 Hz e escreve o footprint medido. Sobre dez modelos reais
+numa RTX 4050, os valores escritos à mão erravam entre −3154 e +22448 MiB.
+
+## Integrar um modelo
+
+Três métodos:
+
+```python
+from vramd.worker import WorkerAdapter, run_worker_loop
+
+
+class Adapter(WorkerAdapter):
+    name = "meu-modelo"
+
+    def load(self, **kw):
+        import torch, meulib
+
+        return meulib.load(device=kw.get("device", "cuda"))
+
+    def generate(self, model, request):
+        if self.should_abort(request):
+            return self.cancelled_response()
+        self.report_progress(request, 0.0, "a gerar")
+        return {"status": "ok", "output": model(request["prompt"])}
+
+    def unload(self, model):
+        del model
+
+
+if __name__ == "__main__":
+    run_worker_loop(Adapter, backend_name="meu-modelo")
+```
+
+E registá-lo — sem tocar no código do vramd:
+
+```yaml
+# ~/.config/vramd/backends.d/meu-modelo.yaml
+version: 2
+backends:
+  - name: meu-modelo
+    adapter: meu_pacote.adapter
+    vram_mib: 4200
+    priority: 20
+    runtime:
+      command: ["/opt/meu-modelo/venv/bin/python", "-m", "meu_pacote.worker"]
+      env: { HF_HOME: ~/hf-cache }
+    load_keys: [device, compute_type]
+    shape_keys: [device]
+```
+
+Exemplo completo e executável: [`examples/echo-backend/`](examples/echo-backend/).
+
+## Calibração
+
+O atrito de qualquer sistema destes é a pergunta "que números meto no
+descriptor?". A resposta do vramd é: nenhum — mede-se.
+
+```bash
+vramd calibrate meu-modelo --repeats 3 --out ~/.config/vramd/backends.d/medido.yaml
+```
+
+Corre o job, separa **contexto CUDA / pesos / activação** pelas fronteiras de
+fase, e escreve o descriptor. O que apanha, e que uma estimativa não apanha:
+
+| Sinal | Porque importa |
+|---|---|
+| pico no **load** acima do da inferência | carregar fp16 e quantizar depois OOMa antes de gerar |
+| activação ≫ pesos | o modelo carrega outro modelo dentro do `generate` |
+| nada residente após o load | carga preguiçosa: não há o que evictar |
+| `unload` que não devolve VRAM | evictar este backend não liberta nada — o plano de evicção seria ficção |
+| fuga por repetição | o residente cresce a cada job |
+| warmup na 1.ª inferência | calibrar com `--repeats 1` inflaciona o número |
+
+Cada medição guarda as amostras cruas: `vramd recalibrate relatorio.json` refaz
+os números quando a análise melhora, sem voltar a ocupar a GPU.
+
+## Comandos
+
+```
+start stop status queue wait cancel flush backends preload evict reap
+respawn zero stats debug bench doctor calibrate recalibrate
+```
+
+- `vramd status` / `queue` — quem tem a GPU e o que espera
+- `vramd zero` — liberta toda a VRAM ociosa sem parar o supervisor
+- `vramd respawn <backend>` — reinicia só um worker (código novo) sem parar a fila
+- `vramd doctor` — diagnóstico de ambiente
+
+**Nunca é preciso `kill`.** Matar processos GPU corre contra a fila e mata o
+workload errado.
+
+## Configuração
+
+```
+data/backends.yaml (exemplo)  →  $VRAMD_BACKENDS_FILE  →  ~/.config/vramd/backends.d/*.yaml
+```
+
+Sobreposição **por chave**: um ficheiro com `{name: x, vram_mib: 5632}` corrige
+só esse campo e herda o resto. É assim que um descriptor calibrado entra em
+vigor sem editar o pacote.
+
+Variáveis: `VRAMD_BACKENDS_FILE`, `VRAMD_BACKENDS_DIR`, `VRAMD_TOOLS_ROOT`,
+`VRAMD_MAX_INFLIGHT`, `VRAMD_MAX_QUEUE_DEPTH`, `VRAMD_VRAM_SAFETY_MIB`,
+`VRAMD_PRIORITY`.
+
+## Limites conhecidos
+
+Vale a pena saber antes de adoptar:
+
+- **`MAX_INFLIGHT=1` por omissão** — uma geração de cada vez. É a escolha certa
+  para 6 GB e subutiliza uma A100. Há suporte para >1 com verificação de VRAM,
+  mas falta *packing* a sério.
+- **Multi-GPU sem placement central.** `gpu_ids` é passado ao worker; o
+  supervisor não decide colocação nem contabiliza por device.
+- **POSIX.** A leitura dos pipes usa `select`/`O_NONBLOCK`. Windows precisa de
+  uma camada de IO diferente.
+- **Sem autenticação.** Socket unix com permissões de utilizador. Local, não
+  partilhado.
+- **A calibração não faz milagres.** Mede o que o teu pipeline faz. Um modelo
+  que carrega tudo em fp16 de uma vez não passa a caber por ser medido — só
+  passas a saber que não cabe, e em 0.2 s em vez de a meio do job.
+
+## Origem
+
+Extraído do [AiGameKit](https://github.com/maikramer), onde nasceu para pôr dez
+modelos generativos (texto→imagem, →3D, →áudio, →movimento) a partilhar uma RTX
+4050 de 6 GB sem intervenção manual. Os números deste README são medições dessa
+placa.
+
+## Contribuir
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) — arrancar, estilo, e o que este projeto
+valoriza. A suite corre em ~27 s sem GPU.
+
+## Licença
+
+MIT — ver [LICENSE](LICENSE).

vramd-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vramd"
+version = "0.1.0"
+description = "Controlo de admissão de VRAM para inferência generativa em GPUs de consumo"
+readme = "README.md"
+authors = [{ name = "Maikeu Locatelli" }]
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["gpu", "vram", "inference", "scheduler", "admission-control", "diffusion"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Distributed Computing",
+]
+
+# Núcleo leve de propósito: o supervisor não importa torch e nem cria contexto
+# CUDA. Os modelos vivem nos workers, cada um no seu venv.
+dependencies = [
+    "click>=8.1.0",
+    "rich>=13.0.0",
+    "rich-click>=1.8.0",
+    "PyYAML>=6.0",
+    "psutil>=5.9.0",
+    "nvidia-ml-py>=12.535.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4.0", "pytest-cov>=4.0.0", "ruff==0.16.2"]
+
+[project.scripts]
+vramd = "vramd.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/maikramer/vramd"
+Repository = "https://github.com/maikramer/vramd"
+Issues = "https://github.com/maikramer/vramd/issues"
+Changelog = "https://github.com/maikramer/vramd/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+vramd = ["data/*.yaml", "py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+
+[tool.coverage.run]
+source = ["src/vramd"]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.",
+]

vramd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vramd-0.1.0/src/vramd/__init__.py

@@ -0,0 +1,23 @@
+"""vramd — controlo de admissão de VRAM para inferência generativa.
+
+Um processo detém a GPU e decide **quem entra**: admite pelo pico real
+(pesos + activação + margem), põe em fila com prioridade e afinidade, evicta
+por peso+LRU, e corre cada modelo num processo/venv próprio.
+
+Feito para inferência que dura segundos a minutos numa GPU de consumo — não
+para throughput de tokens em datacenter.
+
+Três peças:
+
+- **supervisor** (:mod:`vramd.server`, :mod:`vramd.cli`) — fila, admissão, evicção;
+- **worker SDK** (:mod:`vramd.worker`) — 3 métodos para embrulhar qualquer modelo;
+- **cliente** (:mod:`vramd.client`) — submeter, esperar, cancelar.
+
+E um calibrador (:mod:`vramd.calibrate`) que **mede** o footprint em vez de o
+adivinhar: o número que o admit usa vem do driver, não de uma estimativa.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

vramd-0.1.0/src/vramd/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point: python -m vramd"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

vramd-0.1.0/src/vramd/adapter.py

@@ -0,0 +1,154 @@
+"""Contrato do adapter **in-process** — backends sem subprocesso.
+
+Gémeo de :class:`vramd.worker.adapter.WorkerAdapter`, para backends que
+correm dentro do próprio supervisor (descriptor sem ``tool:``/``runtime:``).
+É o caminho legado: sem isolamento de venv e a partilhar o processo com a
+fila. Prefere-se o worker em subprocesso — ver :mod:`vramd.worker`.
+
+O adapter é **stateless quanto ao modelo**: o ciclo de vida (criar/manter/
+evictar) é do ``BackendManager``; o adapter só sabe *como* carregar, usar
+e libertar.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from . import protocol as P
+from .errors import GenerationAborted
+
+__all__ = ["BackendAdapter", "GenerationAborted"]
+
+
+class BackendAdapter(ABC):
+    """Contrato canónico que cada adapter de tool implementa.
+
+    O adapter é **stateless quanto ao modelo**: não retém o objeto carregado.
+    O ciclo de vida (criar/manter/evictar o model object) é responsabilidade do
+    ``BackendManager``. O adapter apenas sabe *como* carregar/usar/libertar um
+    modelo dessa tool.
+
+    Implementações concretas devem ser instanciáveis sem argumentos (o Registry
+    faz ``Adapter()``) e exportar a classe com o nome ``Adapter``.
+    """
+
+    name: str = ""
+
+    @abstractmethod
+    def load(self, **kwargs: Any) -> Any:
+        """Carrega e devolve o model object (pipeline/gerador pronto a gerar)."""
+
+    @abstractmethod
+    def generate(self, model: Any, request: dict[str, Any]) -> dict[str, Any]:
+        """Executa uma geração sobre o model object.
+
+        O request pode incluir:
+          - ``_progress``: ``(pct|None, msg|None) -> None``
+          - ``_abort``: ``() -> bool`` (True = cancel pedido)
+        """
+
+    @abstractmethod
+    def unload(self, model: Any) -> None:
+        """Liberta o model object (VRAM). Idempotente e à prova de exceções."""
+
+    @staticmethod
+    def report_progress(request: dict[str, Any], pct: float | None = None, msg: str | None = None) -> None:
+        """Helper: reporta progresso se o request trouxer ``_progress``."""
+        cb = request.get("_progress")
+        if callable(cb):
+            with contextlib.suppress(Exception):
+                cb(pct, msg)
+
+    @staticmethod
+    def should_abort(request: dict[str, Any]) -> bool:
+        """True se o vramd pediu cancel (``request["_abort"]``)."""
+        cb = request.get("_abort")
+        if not callable(cb):
+            return False
+        try:
+            return bool(cb())
+        except Exception:
+            return False
+
+    @staticmethod
+    def cancelled_response(reason: str = "cancelled") -> dict[str, Any]:
+        """Resposta canónica de cancel cooperativo."""
+        return {
+            "status": P.STATUS_ERROR,
+            "error": reason,
+            "error_code": P.ERR_CANCELLED,
+        }
+
+    @classmethod
+    def abort_hooks(
+        cls,
+        request: dict[str, Any],
+        *,
+        num_inference_steps: int,
+    ) -> tuple[Callable[[], bool] | None, Callable[[int, int], None] | None]:
+        """Constrói ``should_abort`` / ``on_step`` para generators 2D."""
+
+        def _abort() -> bool:
+            return cls.should_abort(request)
+
+        def _on_step(step: int, total: int) -> None:
+            pct = step / max(1, total)
+            cls.report_progress(request, pct, f"step {step}/{total}")
+
+        has_abort = callable(request.get("_abort"))
+        has_progress = callable(request.get("_progress"))
+        return (
+            _abort if has_abort else None,
+            _on_step if has_progress else None,
+        )
+
+    @classmethod
+    def apply_runtime_budget(
+        cls,
+        model: Any,
+        request: dict[str, Any],
+        *,
+        progress_pct: float | None = None,
+        **hints: Any,
+    ) -> dict[str, Any] | None:
+        """Reaplica o runtime VRAM budget do model object, se suportado.
+
+        Contrato canónico: model objects que suportam re-orçamento pós-load
+        (Paint3D ``PaintBatchProcessor``, Text3D ``HunyuanTextTo3DGenerator``, …)
+        expõem ``refresh_runtime_budget(**hints)`` e devolvem o dict do budget
+        (um dict livre, definido pelo model object). O adapter chama isto antes da
+        inferência; o BackendManager guarda o resultado em ``stats``.
+
+        Args:
+            model: model object carregado pelo adapter.
+            request: request (para ``report_progress``).
+            progress_pct: se dado, reporta o budget como progresso.
+            **hints: overrides por-request (ex: ``requested_views=...``).
+                Ignorados se o método do model não os aceitar.
+
+        Returns:
+            Dict do budget, ou ``None`` se o model não suporta / falhou.
+        """
+        refresh = getattr(model, "refresh_runtime_budget", None)
+        if not callable(refresh):
+            return None
+        try:
+            try:
+                budget = refresh(**hints) if hints else refresh()
+            except TypeError:
+                # Model object antigo sem suporte a hints — retry sem overrides.
+                budget = refresh()
+        except (RuntimeError, MemoryError):
+            # Gate VRAM (MeshRender headroom, OOM) — NÃO engolir; adapter aborta.
+            raise
+        except Exception:
+            return None
+        if budget and progress_pct is not None:
+            summary = ", ".join(
+                f"{k}={v}" for k, v in budget.items() if k in ("num_chunks", "max_views", "dino_device")
+            )
+            cls.report_progress(request, progress_pct, f"vram_budget {summary}" if summary else "vram_budget")
+        return budget if isinstance(budget, dict) else None