HFL — Arquitectura Completa

1. Visión General y Propósito

HFL (HuggingFace Local) es una herramienta CLI y servidor API que permite descargar, gestionar y ejecutar modelos de inteligencia artificial de HuggingFace Hub directamente en la máquina local del usuario. Su diseño aspira a ser un drop-in replacement de Ollama, pero conectado al ecosistema de HuggingFace con más de 500.000 modelos.

2. Stack Tecnológico

3. Estructura de Archivos del Proyecto

hfl/
├── pyproject.toml           — Definición del paquete, deps, scripts, herramientas
├── hfl.spec                 — PyInstaller spec para ejecutable standalone
├── LICENSE                  — Apache-2.0
├── LICENSE-DEPENDENCIES.md  — Licencias de todas las dependencias
├── PRIVACY.md               — Política de privacidad
├── NOTICE-EU-AI-ACT.md     — Cumplimiento EU AI Act
├── DISCLAIMER.md            — Exención de responsabilidad
├── README.md                — Documentación principal
├── README.es.md             — Documentación principal (español)
├── LICENSE-FAQ.md            — Texto de la licencia Apache-2.0
├── CONTRIBUTING.md           — Guía de contribución
├── CODE_OF_CONDUCT.md        — Código de conducta (Contributor Covenant 2.1)
├── CHANGELOG.md              — Historial de cambios (Keep a Changelog)
├── SECURITY.md               — Política de seguridad
│
├── src/hfl/                 — CÓDIGO FUENTE PRINCIPAL
│   ├── __init__.py          — Versión del paquete (0.14.0)
│   ├── config.py            — HFLConfig dataclass — configuración global
│   ├── exceptions.py        — Jerarquía completa de excepciones
│   ├── events.py            — EventBus para pub/sub interno
│   ├── metrics.py           — Métricas de rendimiento
│   ├── plugins.py           — Sistema de plugins con entry_points
│   ├── security.py          — Sanitización y validación de seguridad
│   ├── validators.py        — Validadores de datos comunes
│   ├── logging_config.py    — Configuración centralizada de logging
│   │
│   ├── core/                — NÚCLEO DEL SISTEMA
│   │   ├── __init__.py
│   │   ├── container.py     — Contenedor DI con Singleton thread-safe
│   │   ├── observability_setup.py — Setup de listeners de observabilidad
│   │   └── tracing.py       — Request tracing con IDs
│   │
│   ├── cli/                 — INTERFAZ DE LÍNEA DE COMANDOS
│   │   ├── __init__.py
│   │   ├── main.py          — 12 comandos: pull, run, serve, list, search, rm, inspect, alias, login, logout, version, compliance-report
│   │   └── commands/        — Comandos modularizados
│   │       └── _utils.py    — Utilidades compartidas CLI
│   │
│   ├── api/                 — SERVIDOR REST API
│   │   ├── __init__.py
│   │   ├── server.py        — FastAPI app, CORS, disclaimer, lifespan
│   │   ├── state.py         — ServerState con async locks para LLM/TTS
│   │   ├── streaming.py     — SSE streaming helpers
│   │   ├── model_loader.py  — Carga dinámica de modelos
│   │   ├── helpers.py       — ensure_llm_loaded, ensure_tts_loaded
│   │   ├── errors.py        — Manejo centralizado de errores HTTP
│   │   ├── middleware.py    — Logging privacy-safe
│   │   ├── rate_limit.py    — Rate limiting por IP/token
│   │   ├── routes_openai.py — /v1/chat/completions, /v1/completions, /v1/models
│   │   ├── routes_native.py — /api/generate, /api/chat, /api/tags (Ollama-compatible)
│   │   ├── routes_tts.py    — /v1/audio/speech, /api/tts (TTS endpoints)
│   │   ├── routes_health.py — /health, /ready, /live (healthchecks)
│   │   ├── routes_metrics.py — /metrics (Prometheus + JSON)
│   │   ├── exception_handlers.py — Manejo global de excepciones HFLError
│   │   └── timeout.py       — Decorator @with_timeout + timeout configurable
│   │
│   ├── engine/              — MOTORES DE INFERENCIA
│   │   ├── __init__.py
│   │   ├── base.py          — InferenceEngine + AudioEngine ABCs + dataclasses
│   │   ├── selector.py      — Selección automática de backend LLM/TTS
│   │   ├── llama_cpp.py     — LlamaCppEngine (GGUF, CPU/GPU)
│   │   ├── transformers_engine.py — TransformersEngine (safetensors, GPU)
│   │   ├── vllm_engine.py   — VLLMEngine (producción GPU)
│   │   ├── bark_engine.py   — BarkEngine (TTS via transformers)
│   │   ├── coqui_engine.py  — CoquiEngine (TTS XTTS-v2)
│   │   ├── async_wrapper.py — Wrapper sync→async para engines
│   │   ├── model_pool.py    — Pool de modelos con LRU eviction
│   │   ├── dependency_check.py — Verificación de dependencias opcionales
│   │   ├── failover.py      — FailoverEngine (multi-engine retry con sticky routing)
│   │   ├── memory.py        — Tracking de memoria RAM/GPU en tiempo real
│   │   ├── observability.py — Métricas de rendimiento del engine
│   │   └── prompt_builder.py — Formatos de prompt + escape de delimitadores
│   │
│   ├── hub/                 — INTEGRACIÓN HUGGINGFACE
│   │   ├── __init__.py
│   │   ├── auth.py          — Autenticación y tokens
│   │   ├── client.py        — Cliente HTTP para HF Hub
│   │   ├── downloader.py    — Descarga con resume y rate limiting
│   │   ├── license_checker.py — Clasificación de licencias (5 niveles)
│   │   └── resolver.py      — Resolución inteligente de modelos
│   │
│   ├── models/              — MODELOS DE DATOS
│   │   ├── __init__.py
│   │   ├── manifest.py      — ModelManifest — metadata completa
│   │   ├── provenance.py    — ConversionRecord + ProvenanceLog
│   │   ├── registry.py      — ModelRegistry — inventario local JSON
│   │   └── backends/        — Backends de almacenamiento (File + SQLite)
│   │
│   ├── converter/           — CONVERSIÓN DE FORMATOS
│   │   ├── __init__.py
│   │   ├── formats.py       — ModelFormat + ModelType enums
│   │   └── gguf_converter.py — GGUFConverter — conversión + cuantización
│   │
│   ├── utils/               — UTILIDADES TRANSVERSALES
│   │   ├── __init__.py
│   │   ├── circuit_breaker.py — Circuit breaker para resiliencia
│   │   └── retry.py         — Retry con exponential backoff
│   │
│   └── i18n/                — INTERNACIONALIZACIÓN
│       ├── __init__.py      — t(), get_language(), set_language()
│       └── locales/         — Archivos de traducción
│           ├── en.json      — Traducciones en inglés
│           └── es.json      — Traducciones en español
│
├── docs/                    — DOCUMENTACIÓN
│   ├── adr/                 — Architecture Decision Records
│   │   ├── 0001-singleton-pattern.md
│   │   ├── 0002-async-api-sync-engines.md
│   │   ├── 0003-gguf-default-format.md
│   │   ├── 0004-ollama-compatibility.md
│   │   ├── 0005-license-classification.md
│   │   └── 0006-rate-limiting-strategy.md
│   └── *.html               — Documentación arquitectura
│
└── tests/                   — SUITE DE TESTS (~200 archivos, ~89% cobertura)
    ├── conftest.py          — Fixtures compartidas
    ├── test_api*.py         — Tests API (5 archivos)
    ├── test_cli*.py         — Tests CLI (4 archivos)
    ├── test_engine*.py      — Tests engines (8 archivos)
    ├── test_hub*.py         — Tests HF Hub (5 archivos)
    ├── test_i18n*.py        — Tests i18n (4 archivos)
    └── test_*.py            — Tests unitarios y de integración
│
├── .github/                   — INFRAESTRUCTURA GITHUB
│   ├── workflows/
│   │   ├── ci.yml             — CI: lint + test + type-check (Python 3.10/3.11/3.12)
│   │   ├── pages.yml          — Deploy docs a GitHub Pages
│   │   ├── build-executables.yml — Build ejecutables multiplataforma
│   │   ├── lint.yml           — Linting con ruff
│   │   ├── test.yml           — Tests con pytest
│   │   ├── security.yml       — Auditoría de seguridad
│   │   └── license-check.yml  — Verificación de licencias
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml     — Template para reportes de bugs
│   │   └── feature_request.yml — Template para solicitudes de features
│   └── PULL_REQUEST_TEMPLATE.md — Template de PR con checklist de compliance

4. Diagrama de Arquitectura General

5. Módulo config — Configuración Central

Adicionalmente, SLOConfig define los Service Level Objectives del servidor: availability target, latencia P50/P95/P99.

Nuevos knobs de entorno (desde v0.1.0)

Regla de resolución en cada fila: nombre específico HFL → alias HFL → equivalente Ollama → valor por defecto. Así, un host que ya exporta variables Ollama funciona como reemplazo drop-in. Un valor inválido se registra una vez y se ignora — el arranque nunca falla por mala configuración del operador. Referencia completa: docs/env-vars.md.

6. Módulo cli — Interfaz de Línea de Comandos

Funciones Auxiliares del CLI

_format_size() convierte bytes a formato legible. _get_key() lee una tecla sin Enter (raw terminal). _extract_params_from_name() extrae parámetros del nombre (regex: "70b", "7b", "1.5b"). _estimate_model_size() estima tamaño en disco según parámetros y cuantización. _display_model_row() renderiza una fila de resultado de búsqueda. _get_params_value() extrae el valor numérico para filtrado.

Comandos nuevos (desde v0.1.0)

El fichero creció a ~2.350 líneas en src/hfl/cli/main.py. Se añadieron dos familias: comandos de paridad Ollama (drop-in) y los comandos V4 de descubrimiento/operación. Los imports perezosos mantienen un arranque barato; la mayoría de los comandos V4 ejecutan internamente una corrutina con asyncio.run().

El comando serve también ganó --tray/--gui (bandeja del sistema, ver la sección tray), --log-level, --json-logs y --ctx.

7. Módulo hub — Integración con HuggingFace

7. Descubrimiento, Recomendación, Smart Pull y Push del Hub (V4)

Más allá del pull básico, la capa Hub expone ahora el catálogo completo de HuggingFace (1,5M+ modelos con metadatos estructurados) como una superficie consultable y consciente del hardware. Cuatro endpoints de lectura/escritura se apoyan en módulos de planificación puros y sin red, de modo que las heurísticas son testeables sin acceso a internet.

Sondeo de hardware y presupuestos de VRAM

hfl/hub/hw_profile.py construye un HardwareProfile barato y solo de metadatos (sin trabajo de GPU). Presupuestos de memoria usados tanto por recommend como por smart_pull:

hfl/hub/quant_table.py convierte (params_b, quantization) en un FitEstimate conservador = (pesos + KV cache de contexto 4k + 1,0 GB de overhead) × 1,2 de seguridad. Los bits-por-peso están tabulados por cuant (q4_k_m→4,85, q8_0→8,5, mlx-4bit→4,5, …); los recuentos de capas y dimensiones ocultas del KV se agrupan por tamaño, con Qwen 3, Gemma 2 y Mixtral-8x7B (efectivo) añadidos para cerrar la brecha original solo-Llama.

Orden de candidatos en smart-pull

_candidate_repos() genera, de más específico a menos:

Las patas MLX solo aparecen cuando has_mlx es cierto. La escalera de cuants es ["mlx-8bit","mlx-4bit","q5_k_m","q4_k_m"] en Apple Silicon, si no ["q5_k_m","q4_k_m","q4_0","q3_k_m"]; los intentos rechazados se registran en fallback_chain y se muestran tal cual. Cuando nada cabe, build_smart_plan() lanza ValueError (mapeado a un 400 con una pista "prueba --max-vram-gb o un repo más pequeño").

# POST /api/pull/smart — Apple Silicon, 16 GB unificados
{"status": "planned", "target_repo_id": "mlx-community/Llama-3.1-8B-Instruct-4bit",
 "quantization": "mlx-4bit", "estimated_vram_gb": 6.3,
 "reason": "picked mlx-community/... @ mlx-4bit (6.3 GB / 11.2 GB budget)"}

Caché de descubrimiento y seguridad

DiscoveryCache (HFL_HOME/cache/discovery.json) indexa por la consulta serializada a JSON, TTL 300s, acotada a las 32 claves más recientes, con escrituras atómicas a fichero temporal y reseteo ante corrupción — existe para esquivar los 429 no autenticados del Hub en llamadas CLI encadenadas. En el lado del push, redact_secrets() elimina cualquier cosa que coincida con hf_[A-Za-z0-9]{20,} tanto de los logs como de los eventos de error visibles al cliente, y la subida se restringe a allow_patterns = exactamente los ficheros planificados — crítico porque un modelo respaldado por blob (FROM sha256:<digest>) tiene su local_dir apuntando al almacén compartido blobs/, así que un upload_folder sin restringir exfiltraría los bytes de todos los demás modelos.

8. Módulo models — Datos y Registro

ModelManifest (manifest.py)

Dataclass que almacena la metadata completa de cada modelo descargado. Es la unidad fundamental de información en el sistema.

ModelRegistry (registry.py)

Gestiona el inventario local. Persiste a ~/.hfl/models.json como array JSON. Operaciones: add() (evita duplicados), get() (busca por name, alias, o repo_id), set_alias(), list_all() (ordenado por fecha), remove().

ProvenanceLog (provenance.py)

Log inmutable de conversiones en ~/.hfl/provenance.json. Cada ConversionRecord documenta: origen (repo, formato, revisión), destino (formato, path, cuantización), herramienta usada (llama.cpp + versión), licencia original, y timestamps. Sirve para trazabilidad legal y auditoría de cumplimiento (R3).

8. Registro, Manifest, Procedencia y Capacidades (estado actual)

La capa de modelos se endureció y amplió notablemente. El registro en disco ganó seguridad ante concurrencia; el manifest absorbió campos derivados del Modelfile y legales; y un módulo dedicado computa ahora las capacidades estilo Ollama.

Detección de capacidades (compatible con Ollama)

Nuevo módulo hfl/models/capabilities.py. detect_capabilities() devuelve la lista que POST /api/show emite, que los clientes del SDK de Ollama (ollama-python, Open WebUI, LangChain) usan para habilitar tool-calling, visión, embeddings y razonamiento. La detección es coincidencia permisiva de subcadenas sobre name + repo_id + architecture:

El orden es determinista: completion/embedding primero, el resto alfabético.

Registro de procedencia

hfl/models/provenance.py registra la cadena origen→conversión→resultado (~/.hfl/provenance.json) para la salvaguarda de auditoría legal: repo/formato/revisión de origen, ruta destino, cuantización, herramienta + versión, licencia original y marca de tiempo de aceptación. log_conversion() es el punto de entrada de conveniencia, llamado desde el conversor GGUF tras una cuantización exitosa.

9. Módulo engine — Motores de Inferencia

Selector Automático (selector.py)

Lógica de decisión en select_engine(model_path, backend):

Todos los imports son lazy (_get_llama_cpp_engine(), etc.) para no requerir todas las dependencias instaladas.

Backend MLX — Apple Silicon (Fase 13)

mlx_engine.MLXEngine es una cuarta implementación de InferenceEngine que envuelve mlx-lm de Apple y accede a Metal directamente. El docstring del módulo afirma una ventaja de 3-10% en procesado de prompt y 15-25% en decode a fp16 frente a la ruta Metal de llama-cpp para arquitecturas de la familia Llama, más precisión mixta nativa q4/q5/q8 sin conversión a GGUF. La dependencia vive tras el extra [mlx].

mlx-lm no expone seed por llamada ni soporte de stop-strings, así que el engine cubre ambos huecos: _maybe_seed() siembra el RNG global de mlx (mx.random.seed) cuando cfg.seed >= 0 (paridad ENG-10/11 con vLLM/diffusers), y _stop_strings() + _earliest_stop() truncan la salida en el primer stop string del llamante. En generate_stream() la aplicación de stops es un filtro a nivel de carácter con buffer que retiene una cola (max_stop) que podría iniciar un marcador de stop para que la salida nunca lo sobrepase. Los conteos de tokens para el envelope de respuesta se recalculan con el tokenizer porque mlx-lm solo devuelve el texto de la completion.

Selección de backend — ruta MLX y override forzado

select_engine() en selector.py incorpora una rama para Apple Silicon y un override a nivel de operador que el flujo antiguo no refleja.

GGUF permanece en llama-cpp en todos los casos — MLX no ingiere GGUF. _create_engine("mlx") conecta la petición explícita --backend mlx.

Snapshots de KV-cache — arranque en caliente (snapshot.py, V4 F6)

La mayoría de servidores reprocesan el prompt de sistema / prefijo few-shot en cada conversación nueva. snapshot.py expone Llama.save_state() / load_state() de llama-cpp-python como función de servidor: un operador puede capturar todo el KV-cache (tokens procesados + tensores) y restaurarlo para TTFT cero sobre el prefijo cacheado, incluso entre reinicios. Respalda POST /api/snapshot/save, /load, GET /api/snapshot y DELETE /api/snapshot/{name}.

def save_snapshot(engine, *, name, model_name) -> SnapshotMeta: ...
def load_snapshot(engine, *, name, model_name) -> SnapshotMeta: ...

El estado es un pickle de save_state() más un sidecar <name>.meta.json (model, tokens, created_at, bytes, version, mac) bajo HFL_HOME/snapshots/. Propiedades de seguridad del módulo:

save_snapshot/load_snapshot resuelven save_state/load_state en el engine directamente o en su _model interno; los engines sin esa API lanzan (los snapshots de KV son exclusivos de llama-cpp-python).

Decodificación especulativa (llama_cpp.py, V4 F5)

El backend llama-cpp puede ejecutar un modelo borrador que propone tokens que el modelo objetivo verifica en una sola pasada. Se elige al cargar mediante el kwarg draft_model_path (proveniente de un Modelfile); GenerationConfig también lleva un campo draft_model. Dos modos comparten el kwarg:

_LlamaModelDraftAdapter adapta un Llama normal al protocolo LlamaDraftModel (un Llama desnudo devuelve un dict de completion, no un array de token-ids). Es deliberadamente incremental: _align_and_eval_suffix() halla el prefijo común más largo con los ids ya procesados y evalúa solo el sufijo, preservando el KV-cache del borrador entre pasos. Un reset ingenuo por llamada pagaría el prefill completo N veces y haría la especulación 2-3× más lenta; ante divergencia (petición nueva / predicciones rechazadas) resetea y reproduce. El Llama borrador se guarda en self._draft_model y se libera en unload() para no duplicar VRAM en una carga posterior.

LoRA hot-swap y multi-LoRA (lora.py, V4 F4)

lora.py aplica / elimina adaptadores LoRA sobre un modelo en ejecución sin recargar los pesos base, respaldando POST /api/lora/apply, /remove, GET /api/lora y /api/lora/{model}. La superficie pública:

def apply_lora(engine, *, lora_path, scale=1.0, name=None) -> AdapterInfo
def remove_lora(engine, adapter_id) -> bool
def list_loras(engine=None) -> list[AdapterInfo]

remove_lora desacopla del engine vivo primero y solo borra la entrada del registro si tiene éxito — si el engine rechaza el unset, la entrada sigue registrada para que el reintento del cliente funcione, en vez de dejar un adaptador fantasma mezclado en cada generación pero imposible de quitar. Al cargar, LlamaCppEngine.load() también acepta una lista lora_paths pero solo conecta el primero al único kwarg lora_path de llama-cpp, registrando que los extras se ignoran (el apilado se hace por la vía multi-LoRA post-carga).

Flash Attention — gating por arquitectura

El doc lista flash_attn como parámetro de carga; el backend ahora lo resuelve con una precedencia de tres niveles en LlamaCppEngine.load(), porque la ruta flash-attn de llama-cpp-python ha sido históricamente propensa a crashear en arquitecturas nuevas:

El valor resuelto se pasa al constructor de Llama junto al tope de contexto por arquitectura (_ARCHITECTURE_CTX_CAP, p.ej. Gemma 3/4 limitado a 8192 para no fijar memoria unificada en Apple Silicon) y la cuantización opcional del KV-cache (kv_cache_type → type_k/type_v q4_0/q8_0/f16).

Ciclo de vida del modelo en el engine — keep-alive y evicción

HFL no tiene un pin()/unpin() literal en el engine; la residencia de un modelo la gobiernan el ModelPool (model_pool.py) y los deadlines de keep-alive, así que el "pinning" es una propiedad emergente, no una llamada de API. El pool mantiene varios engines cargados y los desaloja por tres señales: LRU (capacidad), timeout de inactividad (default idle_timeout_seconds=3600) y presión de memoria (estimaciones). Un bucle en background (background_eviction_interval=60s) barre modelos ociosos vía start_background_eviction().

Otros engines del paquete

Más allá de los tres backends de texto, engine/ incluye engines de audio, difusión y embeddings que la sección original nunca mencionó. Se cargan de forma lazy tras sus propios extras.

El módulo base define la ABC paralela AudioEngine (TTSConfig / AudioResult), y select_tts_engine() en selector.py enruta automáticamente un modelo TTS a Bark o Coqui (sniffing por nombre/arquitectura en config.json, Bark como default de pipeline transformers).

10. Módulo core — Concurrencia, Dispatcher y Sesiones

El paquete hfl.core es la capa de infraestructura transversal añadida tras el congelado de la v0.1.0. Contiene el Container de inyección de dependencias, el trazado de peticiones, el sandboxing opcional del proceso, el puente eventos→métricas y la persistencia de sesiones de chat. Su acompañante más importante es el InferenceDispatcher — la primitiva de concurrencia acotada que serializa cada llamada de inferencia contra el modelo compartido no reentrante.

Dónde vive. La clase del dispatcher se define en hfl/engine/dispatcher.py, pero se cablea como singleton dentro del contenedor del core y siempre se obtiene mediante hfl.core.get_dispatcher(). Forma parte del relato de concurrencia del core.

10.1 InferenceDispatcher — un Bulkhead acotado

InferenceDispatcher (hfl/engine/dispatcher.py) es async-aware y se apoya en un asyncio.Semaphore cuya capacidad sigue exactamente a max_inflight. Todos los contadores mutan bajo un único _counter_lock para que las decisiones de la ruta rápida y la lenta observen una vista consistente.

La factoría build_default_dispatcher() lee estos valores de hfl.config; el _create_dispatcher() del contenedor lo envuelve en el singleton perezoso.

El ciclo de adquisición — ruta rápida, ruta lenta, rechazo

El gestor de contexto asíncrono slot() ejecuta un protocolo de cuatro fases. Bajo el counter lock decide entre la ruta rápida (capacidad ahora) y la lenta (hay que esperar); una cola de espera llena se rechaza antes de encolar, así el cliente recibe un 429 inmediato en vez de bloquearse.

async with self._counter_lock:
    if self._in_flight < self._max_inflight:
        self._in_flight += 1          # ruta rápida: reserva un slot
        fast_path = True
    else:
        if self._depth >= self._max_queued:
            self._rejected_full_total += 1
            raise QueueFullError(...)  # → HTTP 429 + Retry-After
        self._depth += 1            # ruta lenta: encola y espera
        fast_path = False

La fase 2 adquiere el semáforo fuera del counter lock (para que los llamantes que liberan nunca causen deadlock). Los de ruta lenta envuelven el acquire en asyncio.wait_for(..., timeout=acquire_timeout); un timeout decrementa depth, incrementa rejected_timeout_total y lanza QueueTimeoutError. La seguridad ante cancelación es explícita: una cancelación mientras se espera deshace depth; una cancelación tras reservar el slot de ruta rápida revierte in_flight; un slot retenido durante la ejecución siempre se libera en el finally de la fase 4 (decrementa in_flight, luego sem.release() — elegido para que un snapshot tomado a mitad de la liberación sobre-cuente la carga en lugar de infra-contarla).

snapshot() — la superficie de métricas

snapshot() devuelve un DispatcherSnapshot inmutable (seis enteros: max_inflight, max_queued, in_flight, depth, accepted_total, rejected_full_total, rejected_timeout_total). Es de solo lectura y barato, por lo que se exporta en todas las superficies:

Cómo lo consumen las rutas: run_dispatched() en api/helpers.py adquiere un slot, ejecuta la llamada síncrona al motor en un hilo (asyncio.to_thread) y aplica el timeout de generación. De forma crítica retiene el slot hasta que el hilo trabajador realmente termina — una llamada síncrona al motor no se puede cancelar, así que ante un 504/cancelación del cliente el slot se mantiene (_release_when_worker_exits) para impedir que una petición en cola arranque una segunda inferencia que corrompería el modelo a mitad de generación. Las rutas de streaming pre-adquieren con acquire_stream_slot(), que devuelve o bien un gestor de contexto ya abierto o una JSONResponse 429/503 lista.

10.2 exclusive() — la barrera de drenaje para trabajo admin

Protege tres operaciones contra el modelo compartido:

10.3 Refcount pin/unpin de motores — la guardia contra use-after-free en el hot-swap

exclusive() solo cubre las rutas que retienen un slot del dispatcher. El turno de chat por WebSocket (routes_ws.py) lee el motor directamente y no retiene un slot, así que un swap concurrente podría hacer unload() del modelo a mitad del stream — un use-after-free del modelo no reentrante. ServerState cierra ese hueco con un contador de referencias.

La lógica de swap en set_llm_engine() realiza un retirar-luego-asignar atómico: retira el motor viejo antes de asignar el nuevo, así un fallo de descarga deja el motor viejo en su sitio (los llamantes ven "el reemplazo falló", no un estado a medio actualizar). Dentro del drenaje exclusive() comprueba _engine_inuse: si el motor desplazado sigue fijado pasa a _engine_retired y la descarga se difiere al último unpin_engine; si no, se descarga de inmediato fuera del loop. El productor WS fija el motor durante toda la vida del hilo productor y lo libera en su finally (que puede sobrevivir a una cancelación del cliente, ya que la llamada al motor no se puede interrumpir).

10.4 Container — inyección de dependencias y singletons

core/container.py centraliza el estado global. Singleton[T] es un contenedor perezoso thread-safe (double-checked locking sobre una factoría, con reset() para tests). El dataclass Container tiene un Singleton por servicio compartido y expone accesores de conveniencia:

from hfl.core import get_config, get_registry, get_state, get_dispatcher

reset_container() reconstruye todo desde cero — el fixture estándar de tests para estado limpio.

10.5 Tracing, Sesiones, Sandbox, Observabilidad

11. Módulo converter — Conversión de Formatos

formats.py — Detección de Formatos

Enum ModelFormat: GGUF, SAFETENSORS, PYTORCH, UNKNOWN. La función detect_format(path) inspecciona extensiones (.gguf, .safetensors, .pt/.pth/.bin) tanto en archivos individuales como en directorios (rglob). find_model_file() localiza el archivo principal del modelo.

gguf_converter.py — Conversión a GGUF

Clase GGUFConverter con pipeline de dos pasos:

ensure_tools() auto-instala llama.cpp si no existe: git clone → cmake build → pip install requirements. check_model_convertibility() valida que el modelo sea convertible (rechaza LoRA adapters, modelos de imagen, modelos sin config.json).

11. Cobertura de arquitecturas, parser de Modelfile y renderizador Go-template (estado actual)

El cluster del conversor abarca detección de formato/tipo (formats.py), el pipeline GGUF (gguf_converter.py), un parser/renderizador bidireccional completo de Modelfile (modelfile_parser.py) y un motor Go-template mínimo (go_template.py).

30+ arquitecturas LLM + detección MLX

hfl/converter/formats.py reconoce 33 arquitecturas causal-LM en LLM_ARCHITECTURES (Llama, Mistral, Mixtral, Qwen2/Qwen2Moe, Gemma/Gemma2, Phi/Phi3, Falcon, Cohere/CommandR, DeepseekV2, InternLM/InternLM2, Yi, StarCoder2, CodeLlama, Olmo/Olmo2, Mamba, Jamba, Arctic, StableLm, OPT, Bloom, GPT2/NeoX/J, …), más otras 16 familias de arquitecturas (TTS, STT, embeddings, vision-QA, seq2seq, depth, …) usadas por detect_model_type() para clasificar cualquier config.json de HF. is_mlx_quantized_repo() marca repos empaquetados con MLX (mlx en el repo id, o un objeto quantization con group_size+bits en config.json) para enrutarlos al backend MLX en lugar del conversor de llama.cpp, que rechaza grafos empaquetados con MLX.

Pipeline de conversión GGUF

hfl/converter/gguf_converter.py ejecuta safetensors → convert_hf_to_gguf.py (F16) → llama-quantize → GGUF final. check_model_convertibility() rechaza de entrada adaptadores LoRA, modelos de difusión/imagen y configuraciones de audio/TTS. convert_with_cache() normaliza el token de cuant antes de construir la clave de bloqueo (para que q4_k_m y Q4_K_M no compitan por el mismo fichero de salida) y serializa conversiones duplicadas con un bloqueo por clave; _gguf_variant_path() evita deliberadamente with_suffix para que los puntos de versión en los nombres de repo (Qwen2.5-7B) no se trunquen en nombres de fichero colisionantes. El intermedio F16 es reanudable, y _check_conversion_environment() sondea el Python del host en busca de una combinación compatible de transformers/huggingface_hub antes de lanzar la conversión real.

Parser de Modelfile — escapes, guardas de INCLUDE, round-trip

hfl/converter/modelfile_parser.py cierra el bucle para POST /api/create: parse_modelfile() maneja FROM, PARAMETER, TEMPLATE, SYSTEM, ADAPTER, LICENSE, MESSAGE, REQUIRES, ENV, CAPABILITIES, DRAFT e INCLUDE; render_modelfile_document() serializa de vuelta con un invariante de round-trip testeado. Endurecimiento:

• Decodificación de escapes — _decode_quoted() interpreta \n \t \r \" \\ dentro de valores con comillas simples y triples; el codificador escapa las barras invertidas (y los """ incrustados) de forma simétrica para que una plantilla Jinja con un \n literal sobreviva un parse→render→parse sin cambios.
• Guarda de inyección de rutas en INCLUDE — _expand_includes() recorre el directorio base una vez hacia un dict allow-list; cada open() posterior consume una cadena indexada por diccionario, nunca entrada de usuario en bruto. _is_safe_include_rel() rechaza .., rutas absolutas, barras invertidas y NUL; se aplican detección de ciclos y un tope de profundidad 16.
• Matcher de INCLUDE escrito a mano (sin regex) para que el análisis de ReDoS polinómico de CodeQL no tenga nada que marcar.

Renderizador Go-template con guarda de recursión

hfl/converter/go_template.py implementa el subconjunto de text/template de Go que usan los Modelfiles reales — {{ .Field }}, rutas anidadas, {{ range }}, {{ if }}/{{ else }}/{{ end }}, literales de cadena, y recorte de espacios {{- -}}. render_go_template() es una capa de conveniencia, nunca una barrera: ante un GoTemplateError recae en el texto literal con un aviso, y captura RecursionError explícitamente para que un {{ if }}/{{ range }} profundamente anidado y malicioso no agote la pila de Python y aflore como un 500 no manejado.

12. Módulo api — Servidor REST

ServerState

Clase con engine (InferenceEngine activo), current_model (ModelManifest cargado) y api_key (str|None para autenticación). Instanciada como singleton global. El lifespan del servidor hace cleanup al cerrar.

Middleware Stack

Orden de ejecución Starlette (outer → inner): RequestLogger → APIKey → RateLimit (condicional) → Disclaimer → CORS. El orden de add_middleware() es inverso: CORS, Disclaimer, RateLimit, APIKey, RequestLogger. APIKey se ejecuta ANTES de RateLimit, de modo que las peticiones no autenticadas son rechazadas sin consumir tokens del rate limiter.

CORSMiddleware — Lista de orígenes permitidos configurable vía HFL_ORIGINS (por defecto solo localhost); ya no permite todos los orígenes de forma incondicional.

DisclaimerMiddleware — Añade header X-AI-Disclaimer a respuestas de endpoints de generación AI (R9).

RateLimitMiddleware — Limitación de tasa por IP, configurable vía env vars. Soporta rate limiting por modelo.

APIKeyMiddleware — Autenticación opcional via --api-key. Soporta Authorization: Bearer <key> y X-API-Key: <key>. Endpoints públicos (/health, /) exentos.

RequestLogger — Logging privacy-safe. NUNCA registra: bodies (prompts/outputs), headers auth, User-Agent. Solo: método, path, status, duración.

Exception Handlers

Manejo centralizado de excepciones via register_exception_handlers(app). Mapea toda la jerarquia HFLError a respuestas HTTP con codigos apropiados (400 para validacion, 429 para rate limit, 500 para errores internos).

OpenAPI Documentation

Todos los endpoints incluyen tags, summary y responses en sus decoradores para documentacion OpenAPI auto-generada. Tags: OpenAI, Ollama, TTS, Health, Metrics.

Structured Logging

Todo el logging usa format strings %-style (logger.info('Model loaded: %s', name)) en lugar de f-strings, evitando evaluacion innecesaria cuando el nivel de log esta deshabilitado.

Health & Metrics Endpoints

/health/deep?probe=true — Ejecuta un test de inferencia minimo para verificar que el modelo funciona correctamente. Si falla, reporta estado "degraded".

/health/sli — Service Level Indicators con metricas de disponibilidad y latencia.

/metrics — Metricas en formato Prometheus.

/metrics/json — Metricas en formato JSON.

Núcleo de Chat Compartido (chat_core.py)

Toda superficie de chat — OpenAI /v1/chat/completions, Ollama /api/chat y Anthropic /v1/messages — debe tomar la misma decisión una vez que el motor ha producido texto: ¿el modelo emitió una tool call y, de ser así, cuál es? Históricamente la ruta OpenAI quedó por detrás de la de Ollama y dejó caer silenciosamente el tool calling. Esa decisión vive ahora en un único lugar, de modo que las rutas solo pueden diferir en su traducción al formato de cable, nunca en esta lógica.

La forma canónica de tool call es {"function": {"name": str, "arguments": dict}}; cada ruta la mapea a su propio formato de cable. arguments es siempre un objeto parseado, nunca una cadena (regla C3). Cuando un turno es una tool call, content es "" (regla C4) y tool_calls es siempre una lista — vacía cuando no hay (regla C7).

def resolve_chat_output(raw_text, model_name, tools, engine_tool_calls=None, *, tools_disabled=False) -> ChatOutput:
    if tools_disabled:
        return ChatOutput(content=raw_text)
    if isinstance(engine_tool_calls, list) and engine_tool_calls:
        return ChatOutput(content="", tool_calls=engine_tool_calls)
    cleaned, parsed = parse_tool_calls(raw_text, model_name, tools)
    return ChatOutput(content="", tool_calls=parsed) if parsed else ChatOutput(content=cleaned)

Tool Calling (3 superficies)

El function/tool calling está implementado de forma uniforme en los tres dialectos de chat. Cada ruta mapea hacia el payload OpenAI-function del motor a la entrada, y mapea el canónico ChatOutput.tool_calls hacia su propio formato de cable a la salida.

Parsers de marcadores por familia (tool_parsers.py)

Cuando un backend no expone tool_calls estructuradas por sí mismo, HFL parsea los marcadores nativos de tool-call del texto generado. dispatch(text, model_name, tools) selecciona un parser por subcadena del nombre del modelo, lo ejecuta primero y solo recurre al fallback genérico de envoltorio JSON cuando hay tools declarados (de modo que un chat normal que contenga JSON nunca se malinterprete como tool call).

El streaming con tools declarados se bufferiza: cada dialecto acumula la generación completa y emite las tool_calls estructuradas en un único delta terminal, de modo que un marcador <tool_call> crudo nunca se filtra como token de contenido (API-7).

Bucle de agente nativo (agent_loop.py)

En /api/chat, optar con agent_loop=true conduce el ciclo de uso de tools en el servidor: llama al modelo, despacha las tool_calls emitidas (solo tools MCP — el modelo no debe alucinar nombres externos), añade resultados role=tool y re-llama hasta obtener una respuesta sin tool calls o alcanzar max_iterations (por defecto 6). Las tool calls de un mismo turno se disparan en paralelo vía asyncio.gather. run_agent_loop() devuelve el mensaje final más un tool_trace para replay/depuración.

Responses API (POST /v1/responses)

routes_openai_responses.py. El wrapper de más alto nivel de OpenAI (la ruta que golpea client.responses.create(...)) está implementado sobre la maquinaria existente de chat-completion — sin nuevo camino de motor. No es stateful: cada petición es autocontenida y el servidor no persiste una cadena de response_id.

La respuesta sin streaming la construye _render_response() como una lista output heterogénea y ordenada: primero resúmenes de reasoning, luego el message del assistant (bloques output_text), luego cualquier function_call — más un bloque usage con input_tokens/output_tokens/total_tokens. El streaming bufferiza los turnos con tools y solo emite function_call estructuradas en el evento final response.completed; ambos modos pasan por el dispatcher de inferencia (se retiene un slot durante todo el stream).

WebSocket /ws/chat (cancelable)

routes_ws.py. Los endpoints HTTP de streaming son de un solo disparo: la cancelación depende del cierre TCP y no devuelve ninguna señal accionable. El endpoint WebSocket añade una conexión persistente a través de múltiples turnos de chat, un frame cancel que interrumpe la generación en vuelo, y frames de servidor a nivel de token para que el cliente renderice UI sin parsear NDJSON ni SSE.

Gramática de frames (JSON, uno por mensaje WS)

El bucle de recepción lee frames de forma continua mientras un turno corre en una asyncio.Task de fondo (_drive_chat), de modo que un cancel puede llegar en pleno vuelo. El driver compite un asyncio.Event por turno contra cada token producido vía asyncio.wait(FIRST_COMPLETED) y sale limpiamente, dejando la conexión abierta para el siguiente prompt.

Gate previo al accept

Las actualizaciones WebSocket se saltan el APIKeyMiddleware y el CORSMiddleware HTTP, así que _check_ws_auth_and_origin() replica ambos en línea: API key vía ?api_key=, Authorization: Bearer o X-API-Key (comparación de tiempo constante), y una comprobación de allow-list de Origin (mismo origen estricto por defecto). Los rechazos hacen accept-then-close con código 1008 para que el navegador muestre la razón.

Envelopes de Error por Dialecto

La forma nativa (plana) de HFL {"error": str, "code": …, "category", "retryable", "details", "request_id"} no coincide con ningún proveedor real. errors.py:render_envelope(path, status_code, flat) la remodela según el prefijo de ruta para que los SDK reales de OpenAI/Anthropic (que ramifican según error.type) la parseen correctamente, manteniendo los campos de diagnóstico ricos de HFL como extensiones ignoradas por el SDK dentro del objeto de error.

Cada código de error lleva una política (category, retryable) de _ERROR_POLICY (p.ej. RATE_LIMIT_EXCEEDED→reintentable, VALIDATION_ERROR→no), de modo que la lógica de reintento / circuit-breaker del cliente decide sin parsear prosa. Los helpers de fábrica (service_unavailable, model_loading, queue_full, queue_timeout, …) aceptan todos un path opcional para el renderizado por dialecto.

Handler de validación (400)

exception_handlers.py registra tres handlers vía register_exception_handlers(app). El handler de RequestValidationError emite un 400 por dialecto en las superficies /v1/* (OpenAI/Anthropic reales devuelven 400, no el 422 por defecto de FastAPI {"detail":[…]}), aplanando el primer error a "loc: msg"; /api/* y todo lo demás conservan el 422 nativo. El handler de HFLError y un handler catch-all de Exception también pasan sus cuerpos por render_envelope, de modo que incluso un 500 no manejado llega a un SDK OpenAI/Anthropic como un objeto de error parseable.

Integración con el Dispatcher (spec §5.3)

Toda superficie de chat enruta su llamada al motor a través del dispatcher de inferencia compartido vía helpers.py, serializando las peticiones concurrentes contra el modelo no reentrante de llama.cpp / transformers (el uso concurrente corrompe la KV cache).

Métricas y Salud (actualizado)

routes_metrics.py expone GET /metrics (texto Prometheus vía get_metrics().export_prometheus()) y GET /metrics/json (JSON estructurado). El middleware RequestLogger (middleware.py) alimenta cada petición a Metrics.record_request(), acumulando contadores por-endpoint / por-status / por-método más histogramas de latencia de todo el tiempo (_bucket/_sum/_count para Prometheus).

Nuevos contadores desde v0.1.0

Los contadores de huérfanos existen porque una llamada síncrona al motor vía asyncio.to_thread no puede cancelarse — permiten a la planificación de capacidad ver con qué frecuencia un cancel/desconexión deja una inferencia corriendo hasta el final en segundo plano.

GET /healthz (orquestador, spec §5.5)

Además de las sondas /health* existentes, routes_health.py añade /healthz: devuelve 200 status=ok cuando hay un motor LLM cargado y listo, si no 503 status=degraded. El cuerpo lleva models_loaded, queue_depth / queue_in_flight en vivo del snapshot del dispatcher, y uptime_seconds — un solo scrape para orquestación.

13. Módulo i18n — Internacionalización

Funciones Principales

Archivos de Traducción

Cada idioma tiene un archivo JSON (~441 líneas, ~294 claves) en src/hfl/i18n/locales/:

en.json (inglés) y es.json (español). Las claves siguen la estructura module.action.message, por ejemplo: commands.pull.downloading, commands.search.no_results, errors.model_not_found.

Estado actual (v0.14.0)

Siguen siendo exactamente dos locales — en.json y es.json — pero cada uno ha crecido a 441 líneas (~294 claves hoja), ya que cada comando nuevo (discover, recommend, bench, snapshot, lora, …) registra sus cadenas commands.<name>.description / ayuda de opciones a través de t() en tiempo de import. La resolución de idioma es HFL_LANG → locale del sistema (LC_ALL/LC_MESSAGES/LANG) → en. Una clave ausente cae a inglés y, en su defecto, devuelve la clave literal, de modo que una cadena sin traducir se degrada con elegancia en vez de tumbar el CLI.

14. Módulo tray — Icono de bandeja del sistema

15. Módulo observability — Métricas, Firma y Auditoría

Aquí conviven dos preocupaciones distintas, en dos niveles de madurez distintos. Métricas (src/hfl/metrics.py) es la vía de telemetría en producción: respalda /metrics y la vista de SLI, y ahora emite histogramas Prometheus agregables además de contadores de saturación del dispatcher. El paquete src/hfl/observability/ — firma ed25519 de manifiestos, un audit log estructurado y tracing OpenTelemetry — está completamente implementado y cubierto por tests, pero dormant: ningún módulo bajo src/hfl/ importa todavía hfl.observability, así que estos helpers se distribuyen como fontanería opt-in con cero call sites en producción. Documentamos lo que hace el código y señalamos el hueco de cableado explícitamente.

Histogramas Prometheus

Metrics (un @dataclass thread-safe protegido por un único threading.Lock) mantiene dos familias de latencia como histogramas monotónicos de todo el histórico además de los buffers circulares acotados deque(maxlen=1000) que alimentan la vista de percentiles JSON local. Los deques encogen en silencio bajo carga (su ventana son las últimas 1000 muestras), así que la serie exportada es el array acumulativo de buckets — eso es lo que hace que histogram_quantile() y rate(..._count) sean correctos en cualquier ventana de scrape y entre réplicas.

Las fronteras de bucket (_LATENCY_BUCKETS_MS) son 13 cortes fijos en milisegundos de 5 a 60000, más un bucket de overflow +Inf. _bucket_index() halla la primera frontera >= valor; record_request() y record_generation() incrementan el bucket correspondiente y el _sum_ms acumulado. _append_histogram() renderiza el triple acumulativo _bucket{le=...} / _sum / _count.

def _bucket_index(value_ms: float) -> int:
    for i, boundary in enumerate(_LATENCY_BUCKETS_MS):
        if value_ms <= boundary:
            return i
    return len(_LATENCY_BUCKETS_MS)  # overflow +Inf

Se exportan dos series de histograma: hfl_request_latency_ms y hfl_generation_latency_ms, cada una con las líneas canónicas _bucket/_sum/_count. La vista JSON (export_json()) y get_sli() siguen calculando p50/p95/p99 localmente sobre el deque mediante _percentile() con interpolación lineal.

Métricas de saturación del dispatcher

En cada scrape, export_prometheus() obtiene un DispatcherSnapshot (de src/hfl/engine/dispatcher.py, un dataclass frozen de seis enteros) vía get_dispatcher().snapshot() y exporta las señales de load-shedding que antes no eran alertables. Leer el snapshot es barato, así que se hace inline bajo un try/except best-effort (la config puede no estar cargada en algunos tests).

Junto a ellas, el exporter publica diagnósticos de cancelación de streaming: hfl_ws_cancels_total / hfl_ws_cancel_orphans_total (frames de cancel WebSocket, y el subconjunto que dejó una llamada al engine corriendo en background con el slot del dispatcher aún ocupado) y el contador de paridad SSE/HTTP hfl_stream_cancel_orphans_total.

Firma ed25519 de manifiestos dormant

src/hfl/observability/signing.py implementa procedencia opt-in sobre los manifiestos de modelo. manifest_digest() talla un subconjunto estable del envelope (name, repo_id, file_hash, hash_algorithm, size_bytes, quantization, architecture, adapter_paths, parent_digest) — descartando deliberadamente metadata mutable como last_used para que un hfl show nunca invalide una firma — y le aplica SHA-256 a su JSON canónico. sign_manifest_envelope() adjunta un bloque {alg:"ed25519", key_id, digest, sig}; verify_manifest_envelope() lo verifica contra un keyring TrustRoot que el operador cura en ~/.hfl/trusted-publishers.json (key_id → clave pública base64url).

El backend criptográfico se elige en runtime: prueba pynacl primero, luego cryptography, lanzando SignatureUnavailableError si ninguno es importable; un bloque inválido/no autorizado lanza SignatureInvalidError (pensado para convertirse en un 400 en modo estricto). Los manifiestos sin firmar siguen siendo válidos — verify_manifest_envelope() simplemente devuelve False.

Audit log dormant

src/hfl/observability/audit.py escribe un objeto JSON por línea en HFL_AUDIT_LOG_PATH mediante un RotatingFileHandler (por defecto 100 MB × 5 backups, ajustable con HFL_AUDIT_LOG_MAX_BYTES / HFL_AUDIT_LOG_BACKUPS). Es opt-in: sin ruta configurada, audit_event() es un no-op de coste cero. El envelope de evento lleva ts (UTC, microsegundos, sufijo Z), event, actor (un prefijo SHA-256, nunca la API key cruda), resource, metadata y outcome. El catálogo es un frozenset AUDIT_EVENTS — model.create/delete/copy/pull/stop/unload/load, blob.upload, mcp.connect/disconnect, api_key.mint/revoke. El emisor nunca lanza; un nombre de evento desconocido registra un warning pero igualmente emite.

Tracing OpenTelemetry dormant

src/hfl/observability/tracing.py envuelve el SDK de OTEL tras un context manager trace_span(name, attributes=...) que se vuelve un no-op nullcontext() cuando el tracing está apagado — así los call sites nunca tienen que comprobar is_enabled(). configure_tracing() se activa con HFL_OTEL_ENABLED; cuando está activo construye un TracerProvider con un BatchSpanProcessor + exporter OTLP/HTTP (endpoint HFL_OTEL_EXPORTER_ENDPOINT, por defecto http://localhost:4318/v1/traces; nombre de servicio HFL_OTEL_SERVICE_NAME, por defecto hfl). El SDK viaja tras el extra [otel]; si falta, la configuración registra un warning y queda deshabilitada.

16. Módulos tools y mcp

La superficie agéntica. src/hfl/tools/ aporta las dos tools integradas — búsqueda web y fetch de URL — expuestas de forma compatible con Ollama en /api/web_search y /api/web_fetch (src/hfl/api/routes_web.py). src/hfl/mcp/ implementa ambas mitades del Model Context Protocol: HFL como host que se conecta a servidores MCP externos y mezcla sus tools en el chat, y HFL como servidor que publica sus propias tools a otros hosts. Ambos están cableados en producción; MCP viaja tras el extra opcional [mcp].

Tools integradas (src/hfl/tools/)

Los backends de búsqueda forman un pequeño registro tras una WebSearchBackend abstracta:

get_backend() resuelve el nombre (cayendo a DuckDuckGo con un warning ante valores desconocidos, así el servidor nunca da un 500 al arrancar). Los wrappers de redirect /l/?uddg= de DDG se desenvuelven a la URL destino real.

Endurecimiento SSRF / DNS-rebinding

web_fetch está endurecido en profundidad contra server-side request forgery. El flujo:

• Allowlist de esquema — solo http/https (_ALLOWED_SCHEMES).
• Resolución pre-flight — _resolve_and_validate() llama a socket.getaddrinfo() y rechaza la URL si cualquier dirección resuelta es privada, loopback, link-local, multicast, reserved o unspecified (_is_private_ip(); una dirección no parseable se trata como insegura). Esto bloquea el endpoint de cloud-metadata 169.254.169.254 y los servicios internos.
• Pineo de IP (cierra la ventana TOCTOU de DNS-rebinding) — la IP validada se pinea para la conexión real. _pinned_request() reescribe el host de la URL al literal de la IP verificada preservando la autoridad original en la cabecera Host y, para HTTPS, la extensión TLS sni_hostname — así httpx no puede re-resolver al conectar y un atacante con DNS autoritativo TTL-0 no puede responder público-aquí / privado-a-httpx. El userinfo (user:pass@) se preserva para que los fetch con Basic-auth sigan funcionando.
• Seguimiento manual de redirects — follow_redirects=False; hasta _MAX_REDIRECTS (3) saltos se siguen a mano, cada uno re-pasado por el guard completo de esquema + IP privada y re-pineado, así una URL pública no puede hacer 302 hacia una dirección interna/metadata.
• Presupuesto de bytes por streaming — el cuerpo se lee incrementalmente vía resp.aiter_bytes() con un tope duro max_bytes (5 MiB por defecto). Un get no-streaming bufferizaría toda la URL (controlada por el modelo) en RAM y podría hacer OOM al proceso; el streaming acota la memoria real, no solo la entrada del parser.

def _is_private_ip(ip_str: str) -> bool:
    try:
        ip = ipaddress.ip_address(ip_str)
    except ValueError:
        return True  # no parseable == inseguro
    return (ip.is_private or ip.is_loopback or ip.is_link_local
            or ip.is_multicast or ip.is_reserved or ip.is_unspecified)

La capa de ruta (routes_web.py) valida los cuerpos con Pydantic (query 1–2048 chars; max_results 1–10; url 1–2048 chars), mapea WebSearchError/WebFetchError a HTTP 400, y un crash a 500 con un mensaje que no filtra detalles.

Model Context Protocol (src/hfl/mcp/)

El SDK oficial mcp de Python es una dependencia opcional. Ambos módulos se importan incondicionalmente y degradan con gracia: un SDK ausente lanza MCPClientUnavailableError / MCPServerUnavailableError solo en el punto de uso, nunca al importar, así que las instalaciones sin el extra [mcp] siguen funcionando.

HFL como host — mcp/client.py

MCPClient (singleton vía get_client()) mantiene sesiones vivas a cada servidor configurado. connect(server_id, target) acepta dos transportes — stdio://<cmd> <args> (lanza un subproceso que habla JSON-RPC) y sse://<url> (HTTP + Server-Sent Events) — llama a session.initialize() + list_tools() y envuelve cada resultado como una MCPTool. Los nombres de tool se namespacean como server_id__tool (qualified_name) para evitar colisiones entre servidores, y to_ollama_tool() los convierte al esquema {type:"function", function:{...}} que ve el modelo. autoload_servers() conecta cada entrada del fichero JSON apuntado por HFL_MCP_AUTOLOAD; una entrada rota se registra pero nunca aborta hfl serve.

Integración en chat (src/hfl/api/routes_native.py): _merge_mcp_tools() pliega cada tool MCP conectada en el array tools de una petición /api/chat que no las declaró ya (best-effort — una lectura fallida se registra y se ignora). Cuando agent_loop=true, la ruta pasa mcp_client.call_tool como el mcp_caller a run_agent_loop(), que despacha las llamadas a tools y re-somete los resultados hasta una respuesta sin tools o max_iterations (6 por defecto).

HFL como servidor — mcp/server.py

HFLMCPServer publica un registro mínimo y seguro por defecto HFL_TOOLS: web_search, web_fetch, model_list y model_show. Las dos primeras delegan en hfl.tools; las dos últimas leen hfl.models.registry. --capabilities estrecha el conjunto publicado (_filter_tools()). build_server() cablea los handlers @server.list_tools() / @server.call_tool() del SDK; un ValueError del handler se convierte en una respuesta MCP IsError TextContent, cualquier otra excepción se registra y se expone como un error interno genérico. Se sirven dos transportes: serve_stdio() (para hosts por subproceso) y serve_sse(host, port) (una app Starlette bajo uvicorn, /sse + /messages/).

Superficie CLI — hfl mcp

El comando mcp en src/hfl/cli/main.py controla ambas mitades:

17. Jerarquía de Excepciones

Todas heredan de HFLError(message, details) con __str__ que combina ambos. Cada excepción incluye datos contextuales específicos (model_name, repo_id, required_gb, etc.) para diagnóstico detallado.

18. Flujo Completo: hfl pull

19. Flujo Completo: hfl run

20. Flujo Completo: hfl serve

21. Cumplimiento Legal y Auditoría

HFL implementa un sistema exhaustivo de cumplimiento legal documentado con referencias a auditoría (R1-R9):

Archivos Legales del Proyecto

22. Patrones de Diseño

Architecture Decision Records (ADRs)

Las decisiones arquitectónicas importantes están documentadas en docs/adr/ siguiendo el formato estándar ADR:

Patrones nuevos (añadidos desde v0.1.0)

23. Dependencias y Extras

Nuevos extras opcionales (desde v0.1.0)

La matriz de extras creció mucho más allá de los cuatro originales. Las deps nativas pesadas llevan ahora cotas superiores (tope en el siguiente major) por ser la mayor superficie de vulnerabilidades/rupturas. [all] = llama,transformers,vllm,convert,tts,coqui,audio,tray,mcp,mlx,stt,imagegen.

Subidas de pins: el core apunta ahora a transformers>=5.0,<6.0 + torch>=2.5,<3.0 (la línea 5.x / hub-1.x), huggingface-hub>=1.5,<2.0, fastapi~=0.135, starlette>=1.3.1 y python-multipart>=0.0.31 (ambos suelos fijados por correcciones de CVE). llama-cpp-python>=0.3.20 (soporte gemma4). [dev] añadió mypy>=1.10 y numpy>=1.24.

24. Testing

Categorías de Tests

Tests de Integración y Edge Cases

Tests Adicionales (v0.14.0)

Fixtures principales (conftest.py): tmp_hfl_home (directorio temporal), mock_hf_api (mock HfApi), sample_manifest (modelo ejemplo), populated_registry (registro pre-populado), mock_engine (engine de inferencia mockeado), test_client (FastAPI TestClient).

# Ejecutar tests con cobertura
pytest --cov=hfl --cov-report=html --cov-report=term-missing  # fail_under=75 (pyproject)

# Tests por categoría
pytest tests/test_api*.py -v          # Solo API
pytest tests/test_engine*.py -v       # Solo engines
pytest -k "not slow" -v               # Excluir tests lentos

25. Build y Distribución

Almacenamiento Local

~/.hfl/
├── models/               # Archivos de modelos descargados
│   └── org--model/       # Directorio por modelo (org--model format)
├── cache/                # Caché de HuggingFace Hub
├── tools/
│   └── llama.cpp/        # Herramientas compiladas para conversión
│       └── build/bin/    # Binarios: llama-quantize, etc.
├── models.json           # Registro de modelos (array de ModelManifest)
└── provenance.json       # Log inmutable de conversiones

26. CI/CD y GitHub

GitHub Actions Workflows

Templates de GitHub

Issue Templates: bug_report.yml (formulario estructurado con info de sistema, pasos para reproducir, logs) y feature_request.yml (problema, solución propuesta, componente afectado).

PR Template: Checklist que incluye verificación de los 5 Compliance Modules (licencia, provenance, disclaimer, privacidad, gating) como normas de uso responsable del proyecto.

Archivos de comunidad: CONTRIBUTING.md (guía de desarrollo, estilo de código, proceso de PR), CODE_OF_CONDUCT.md (Contributor Covenant v2.1), SECURITY.md (política de reporte de vulnerabilidades).

Workflows solo manuales (v0.14.0)

Cada uno de los 14 workflows bajo .github/workflows/ está ahora declarado on: workflow_dispatch — los disparadores automáticos push / pull_request / schedule / por tag se eliminaron deliberadamente. El propietario ejecuta cada pipeline a mano desde la pestaña Actions. No hay publicación automática: publish-pypi.yml tiene su disparador por tag eliminado y corre solo por dispatch manual (con un input testpypi), usando PyPI Trusted Publisher (OIDC, sin token almacenado) más una atestación Sigstore. build-executables.yml además conserva un disparador release: para subir artefactos.