ltcai 11.2.0 → 11.4.0

package/latticeai/core/embedding_providers/vision.py

@@ -0,0 +1,352 @@
+"""Images on the same contract as text — with two deliberate differences.
+
+**No fallback.** The hash embedder turns text into a real, if crude, cosine
+signal; hashing a file path says nothing about the picture, so an unavailable
+vision model is reported unavailable and the caller skips the embedding rather
+than storing a decoy.
+
+**A separate space by default.** A CLIP-family image vector is not comparable
+with a BGE text vector, so ``space == "image"`` means "index these apart and
+join them by late fusion". Only a genuinely shared-space model may declare
+``space == "shared"``, and only then can a text query be scored against image
+vectors.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence
+
+from .base import (
+    EmbeddingProvider,
+    EmbeddingUnavailable,
+    _l2_normalize,
+    _load_dotted,
+    _RemoteConfig,
+)
+
+#: CLIP ViT-B/32 width — the most common local image-embedding output.
+DEFAULT_VISION_DIM = 512
+#: Image vectors live in their own index and join text results by late fusion.
+VISION_SPACE_IMAGE = "image"
+#: A genuinely multimodal model (CLIP-style) can share the text space — opt-in.
+VISION_SPACE_SHARED = "shared"
+VISION_SPACES = (VISION_SPACE_IMAGE, VISION_SPACE_SHARED)
+VISION_PROVIDER_TYPES = ("mlx", "custom")
+VISION_TARGET_ENV = "LATTICEAI_VISION_EMBEDDING_TARGET"
+
+
+_KNOWN_VISION_DIMS = {
+    "clip-vit-base-patch32": 512,
+    "clip-vit-base-patch16": 512,
+    "clip-vit-large-patch14": 768,
+    "siglip-base-patch16-224": 768,
+    "siglip-large-patch16-384": 1024,
+}
+
+
+def _guess_vision_dim(model: str, default: int) -> int:
+    key = str(model or "").split("/")[-1].strip().lower()
+    key = key.split(":")[0]
+    return _KNOWN_VISION_DIMS.get(key, default)
+
+
+def _normalize_space(value: Any) -> str:
+    space = str(value or "").strip().lower()
+    return space if space in VISION_SPACES else VISION_SPACE_IMAGE
+
+
+class VisionEmbeddingProvider(EmbeddingProvider):
+    """Turns an image *file path* into a vector.
+
+    Subclasses implement :meth:`embed_images`; everything else — the single
+    ``embed_image``, L2 normalization, locking the index identity to the width
+    the model actually returned, and the refusal to embed text outside a shared
+    space — is shared here.
+    """
+
+    provider = "vision"
+    grade = "production"
+    #: ``"image"`` (own index, late fusion) or ``"shared"`` (same space as text)
+    space: str = VISION_SPACE_IMAGE
+
+    def __init__(self, cfg: _RemoteConfig):
+        self._cfg = cfg
+        self.dim = int(cfg.dim or DEFAULT_VISION_DIM)
+        self.space = _normalize_space(cfg.extra.get("space"))
+
+    # ── required ──────────────────────────────────────────────────────────
+    def embed_images(self, paths: Sequence[str]) -> List[List[float]]:
+        raise NotImplementedError
+
+    # ── derived (shared) ──────────────────────────────────────────────────
+    @property
+    def shares_text_space(self) -> bool:
+        """True when a text query may be scored against these vectors."""
+        return self.space == VISION_SPACE_SHARED
+
+    def embed_image(self, path: str) -> List[float]:
+        vectors = self.embed_images([path])
+        if not vectors:
+            raise EmbeddingUnavailable(f"{self.model_id} returned no vector for {path}")
+        return vectors[0]
+
+    def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
+        """Text side of a multimodal model — only in a shared space.
+
+        Scoring a BGE query vector against CLIP image vectors produces a number
+        with no meaning, so the image-space default refuses rather than
+        returning something a caller would rank on.
+        """
+        if not self.shares_text_space:
+            raise EmbeddingUnavailable(
+                f"{self.model_id} embeds images into a separate space; text "
+                "queries reach image nodes through late fusion, not this index"
+            )
+        return self._normalize_rows(self._embed_texts_raw(texts))
+
+    def _embed_texts_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        raise NotImplementedError
+
+    def _normalize_rows(self, rows: Iterable[Any]) -> List[List[float]]:
+        """L2-normalize, and lock the index identity to the real width."""
+        out: List[List[float]] = []
+        for row in rows:
+            vec = [float(x) for x in (row or [])]
+            if not vec:
+                raise EmbeddingUnavailable(f"{self.model_id} produced an empty vector")
+            self.dim = len(vec)
+            self.model_id = self._model_id_with_dim(self.dim)
+            out.append(_l2_normalize(vec))
+        return out
+
+    def metadata(self) -> Dict[str, Any]:
+        data = super().metadata()
+        data.update(
+            {
+                "modality": "image",
+                "space": self.space,
+                "shares_text_space": self.shares_text_space,
+            }
+        )
+        return data
+
+
+class MLXVisionEmbeddingProvider(VisionEmbeddingProvider):
+    """Local CLIP-family image embedder loaded through ``mlx_clip``.
+
+    Guarded import, opt-in, never a core dependency: the module must expose
+    ``load(model)`` returning an encoder with ``encode_image(paths)`` and —
+    for a shared space — ``encode_text(texts)``.
+    """
+
+    provider = "mlx-vision"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        if not cfg.dim:
+            self.dim = _guess_vision_dim(cfg.model, DEFAULT_VISION_DIM)
+        self.model_id = f"mlx-vision:{cfg.model}:{self.dim}"
+        self._encoder: Optional[Any] = None
+
+    def _load(self) -> Any:
+        if self._encoder is not None:
+            return self._encoder
+        try:  # optional dependency; only imported when this provider is used
+            import mlx_clip  # type: ignore
+
+            self._encoder = mlx_clip.load(self._cfg.model)
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"MLX vision model unavailable: {exc}") from exc
+        return self._encoder
+
+    def embed_images(self, paths: Sequence[str]) -> List[List[float]]:
+        encoder = self._load()
+        try:
+            rows = encoder.encode_image(list(paths))
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"MLX vision embedding failed: {exc}") from exc
+        return self._normalize_rows(rows)
+
+    def _embed_texts_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        encoder = self._load()
+        encode_text = getattr(encoder, "encode_text", None)
+        if not callable(encode_text):
+            raise EmbeddingUnavailable(
+                f"{self.model_id} has no text encoder, so it cannot back a shared space"
+            )
+        try:
+            return list(encode_text(list(texts)))
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"MLX vision text embedding failed: {exc}") from exc
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            self._load()
+            return {"status": "ok", "detail": f"MLX vision model {self._cfg.model} loaded"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
+class CustomVisionEmbeddingProvider(VisionEmbeddingProvider):
+    """A user-supplied ``module:callable`` that embeds image paths.
+
+    The callable receives ``List[str]`` (paths) and returns
+    ``List[List[float]]``. Configured via ``LATTICEAI_VISION_EMBEDDING_TARGET``.
+    """
+
+    provider = "custom-vision"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        self._target_ref = str(cfg.extra.get("target") or os.getenv(VISION_TARGET_ENV, ""))
+        self.model_id = f"custom-vision:{cfg.model or self._target_ref or 'callable'}:{self.dim}"
+        self._fn: Optional[Callable[..., Any]] = None
+
+    def _load(self) -> Callable[..., Any]:
+        if self._fn is not None:
+            return self._fn
+        self._fn = _load_dotted(self._target_ref, VISION_TARGET_ENV, "vision embedding")
+        return self._fn
+
+    def embed_images(self, paths: Sequence[str]) -> List[List[float]]:
+        fn = self._load()
+        try:
+            rows = list(fn(list(paths)))
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"custom vision embedding failed: {exc}") from exc
+        return self._normalize_rows(rows)
+
+    def _embed_texts_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        # A dotted image embedder is one callable over paths; a shared space
+        # would need a second, text-side entry point this contract has no slot
+        # for. Saying so beats scoring a query against the wrong function.
+        raise EmbeddingUnavailable(
+            f"{self.model_id} is an image-only callable and has no text encoder"
+        )
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            self._load()
+            return {"status": "ok", "detail": f"custom vision target {self._target_ref} loaded"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
+def build_vision_provider(
+    provider: str,
+    *,
+    model: str = "",
+    dim: int = 0,
+    space: str = VISION_SPACE_IMAGE,
+    timeout: float = 30.0,
+    extra: Optional[Dict[str, Any]] = None,
+) -> VisionEmbeddingProvider:
+    """Construct a vision provider by name. Never makes a network call."""
+    kind = str(provider or "").strip().lower()
+    cfg = _RemoteConfig(
+        model=model,
+        dim=int(dim or 0),
+        timeout=float(timeout or 30.0),
+        extra={"space": space, **(extra or {})},
+    )
+    if kind == "mlx":
+        return MLXVisionEmbeddingProvider(cfg)
+    if kind == "custom":
+        return CustomVisionEmbeddingProvider(cfg)
+    raise ValueError(
+        f"unknown vision embedding provider: {provider!r} (expected one of {VISION_PROVIDER_TYPES})"
+    )
+
+
+@dataclass
+class ResolvedVisionEmbedder:
+    """A vision provider, or an honest account of why there isn't one."""
+
+    provider: Optional[VisionEmbeddingProvider]
+    requested: str
+    health: Dict[str, Any]
+    detail: str = ""
+
+    @property
+    def available(self) -> bool:
+        return self.provider is not None
+
+    @property
+    def space(self) -> str:
+        return self.provider.space if self.provider is not None else VISION_SPACE_IMAGE
+
+    def as_port(self) -> Optional[Callable[[str], List[float]]]:
+        """The one-argument seam Brain Core injects (``None`` when absent).
+
+        ``lattice_brain`` must not import ``latticeai``, so the ingestion
+        pipeline never sees this class — only the callable it hands over.
+        """
+        if self.provider is None:
+            return None
+        return self.provider.embed_image
+
+    def as_dict(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "requested_provider": self.requested,
+            "available": self.available,
+            "health": self.health,
+            "detail": self.detail,
+        }
+        if self.provider is not None:
+            payload.update(self.provider.metadata())
+        return payload
+
+
+def resolve_vision_embedder(
+    provider: str = "",
+    *,
+    model: str = "",
+    dim: int = 0,
+    space: str = VISION_SPACE_IMAGE,
+    timeout: float = 30.0,
+    extra: Optional[Dict[str, Any]] = None,
+    probe: bool = True,
+) -> ResolvedVisionEmbedder:
+    """Build the requested vision provider, or report it unavailable.
+
+    Unlike :func:`resolve_embedder` there is no fallback: a hashed file path is
+    not a picture. An empty ``provider`` means the user never asked for image
+    embeddings, which is a configuration state rather than a failure.
+    """
+    requested = str(provider or "").strip().lower()
+    if not requested:
+        return ResolvedVisionEmbedder(
+            None,
+            "",
+            {"status": "unavailable", "detail": "no vision provider configured"},
+            "image embeddings are off; set a vision provider to enable them",
+        )
+    try:
+        prov = build_vision_provider(
+            requested, model=model, dim=dim, space=space, timeout=timeout, extra=extra
+        )
+    except Exception as exc:
+        return ResolvedVisionEmbedder(
+            None,
+            requested,
+            {"status": "unavailable", "detail": str(exc)},
+            f"could not construct vision provider {requested}",
+        )
+    if not probe:
+        return ResolvedVisionEmbedder(
+            prov, requested, {"status": "unknown", "detail": "not probed"}, ""
+        )
+    try:
+        health = prov.health()
+    except Exception as exc:  # a provider probe must never crash startup
+        health = {"status": "unavailable", "detail": str(exc)}
+    if health.get("status") != "ok":
+        return ResolvedVisionEmbedder(
+            None,
+            requested,
+            health,
+            f"{requested} vision model unavailable ({health.get('detail', '')})",
+        )
+    return ResolvedVisionEmbedder(prov, requested, health, "")

package/latticeai/core/file_generation/__init__.py

@@ -0,0 +1,115 @@
+"""Model-agnostic file content generation pipeline.
+
+Small local models (gemma/qwen/llama 7B class) asked to "generate an HTML
+file" commonly wrap the payload in chat noise: leading commentary ("Sure!
+Here is your page:"), Markdown fences, ``<think>`` reasoning blocks,
+trailing explanations, or an incomplete document. The previous direct-write
+path saved that reply nearly verbatim, so weak models produced broken files.
+
+This package makes the file-creation flow robust regardless of which LLM is
+loaded, by treating the model as an untrusted content source:
+
+1. Prompt   — extension-aware instructions anchored with the exact first
+   line the reply must start with (small models follow examples, not rules).
+   → :mod:`.prompting`
+2. Extract  — strip reasoning blocks and conversational framing, pick the
+   best fenced block, slice known document boundaries. → :mod:`.extraction`
+3. Validate — per-extension structural checks (HTML document shape, JSON
+   parses, CSS has rule blocks, refusal/chat detection). → :mod:`.validation`
+4. Retry    — one corrective attempt that tells the model what was wrong.
+   → :mod:`.orchestration`
+5. Repair   — deterministic scaffolds guarantee the user still gets a valid
+   file even when the model never produces usable output. → :mod:`.repair`
+
+Alongside the five steps: :mod:`.sanitize` is the single write-side door every
+entry point runs untrusted content through, :mod:`.inference` guesses a
+filename or a whole project manifest when the user named neither, and
+:mod:`.bundles` checks that a multi-file project's links hold together.
+
+The pipeline is pure (no I/O, no FastAPI); the chat layer injects an async
+``generate(context) -> str`` callable.
+
+Split into these submodules in v11.3.0 with no behaviour change. Every name
+the single module exposed still resolves from ``latticeai.core.file_generation``.
+
+Stubbing note: a name rebound *here* changes only this module's binding — the
+submodule that calls it holds its own. A test standing in for one of the
+regex/helper seams patches the submodule that reads it (for example
+``latticeai.core.file_generation.inference._PKG_NAME_RE``).
+"""
+
+from __future__ import annotations
+
+# The single module bound this for its own use, which made it part of the
+# surface callers could reach. Re-exported in the redundant-alias form so it
+# reads as deliberate rather than as a leftover import.
+from latticeai.core.quiet import quiet as quiet
+
+from .bundles import _EXTERNAL_REF_PREFIXES as _EXTERNAL_REF_PREFIXES
+from .bundles import _HTML_LOCAL_REF_RE as _HTML_LOCAL_REF_RE
+from .bundles import _local_bundle_refs as _local_bundle_refs
+from .bundles import repair_bundle_references as repair_bundle_references
+from .bundles import validate_project_bundle as validate_project_bundle
+from .extraction import _CHAT_LINE_RE as _CHAT_LINE_RE
+from .extraction import _EXT_FENCE_LANGS as _EXT_FENCE_LANGS
+from .extraction import _FENCE_RE as _FENCE_RE
+from .extraction import _THINK_BLOCK_RE as _THINK_BLOCK_RE
+from .extraction import _THINK_OPEN_RE as _THINK_OPEN_RE
+from .extraction import _ext as _ext
+from .extraction import _slice_html_document as _slice_html_document
+from .extraction import _slice_json_document as _slice_json_document
+from .extraction import _strip_chat_lines as _strip_chat_lines
+from .extraction import extract_file_content as extract_file_content
+from .inference import _CREATE_VERB_RE as _CREATE_VERB_RE
+from .inference import _CSS_HINT_RE as _CSS_HINT_RE
+from .inference import _EXPLICIT_FILENAME_RE as _EXPLICIT_FILENAME_RE
+from .inference import _HTML_HINT_RE as _HTML_HINT_RE
+from .inference import _JS_HINT_RE as _JS_HINT_RE
+from .inference import _PACKAGE_HINT_RE as _PACKAGE_HINT_RE
+from .inference import _PKG_NAME_RE as _PKG_NAME_RE
+from .inference import _PROJECT_NAME_RE as _PROJECT_NAME_RE
+from .inference import _PYTHON_HINT_RE as _PYTHON_HINT_RE
+from .inference import _REACT_HINT_RE as _REACT_HINT_RE
+from .inference import _TYPE_KEYWORDS as _TYPE_KEYWORDS
+from .inference import _VITE_HINT_RE as _VITE_HINT_RE
+from .inference import _python_package_manifest as _python_package_manifest
+from .inference import _react_manifest as _react_manifest
+from .inference import infer_file_target as infer_file_target
+from .inference import infer_project_manifest as infer_project_manifest
+from .orchestration import _salvage_score as _salvage_score
+from .orchestration import generate_file_content as generate_file_content
+from .prompting import _BUNDLE_HTML_MODULE_RULE as _BUNDLE_HTML_MODULE_RULE
+from .prompting import _BUNDLE_HTML_RULE as _BUNDLE_HTML_RULE
+from .prompting import _FIRST_LINE_HINTS as _FIRST_LINE_HINTS
+from .prompting import _TYPE_RULES as _TYPE_RULES
+from .prompting import _bundle_html_rule as _bundle_html_rule
+from .prompting import build_file_generation_context as build_file_generation_context
+from .repair import _repair_html as _repair_html
+from .repair import repair_file_content as repair_file_content
+from .sanitize import PREVIEWABLE_EXTENSIONS as PREVIEWABLE_EXTENSIONS
+from .sanitize import sanitize_write_content as sanitize_write_content
+from .validation import _BRACED_CODE_EXTENSIONS as _BRACED_CODE_EXTENSIONS
+from .validation import _COMMENTARY_RE as _COMMENTARY_RE
+from .validation import _COMPONENT_EXTENSIONS as _COMPONENT_EXTENSIONS
+from .validation import _REFUSAL_RE as _REFUSAL_RE
+from .validation import _check_balanced_delimiters as _check_balanced_delimiters
+from .validation import _check_component_blocks as _check_component_blocks
+from .validation import _looks_like_commentary as _looks_like_commentary
+from .validation import _strip_code_literals as _strip_code_literals
+from .validation import looks_like_refusal as looks_like_refusal
+from .validation import validate_file_content as validate_file_content
+
+__all__ = [
+    "PREVIEWABLE_EXTENSIONS",
+    "build_file_generation_context",
+    "extract_file_content",
+    "generate_file_content",
+    "infer_file_target",
+    "infer_project_manifest",
+    "looks_like_refusal",
+    "repair_bundle_references",
+    "repair_file_content",
+    "sanitize_write_content",
+    "validate_file_content",
+    "validate_project_bundle",
+]

package/latticeai/core/file_generation/bundles.py

@@ -0,0 +1,76 @@
+"""Bundle-level checks: does this set of files hold together?
+
+A multi-file project is only as valid as its links. These helpers find the
+local references an HTML document makes, repoint the ones a weak model got
+almost right, and report every file that is invalid or dangling.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Tuple
+
+from .extraction import _ext
+from .validation import validate_file_content
+
+_HTML_LOCAL_REF_RE = re.compile(
+    r"(?:href|src)\s*=\s*[\"']([^\"'#?]+)[\"']", re.IGNORECASE
+)
+_EXTERNAL_REF_PREFIXES = ("http://", "https://", "//", "data:", "mailto:", "tel:", "javascript:")
+
+
+def _local_bundle_refs(html: str) -> List[str]:
+    """File references inside an HTML document that must exist in the bundle."""
+    refs: List[str] = []
+    for ref in _HTML_LOCAL_REF_RE.findall(html or ""):
+        candidate = ref.strip()
+        if not candidate or candidate.startswith(_EXTERNAL_REF_PREFIXES):
+            continue
+        if "." not in candidate.rsplit("/", 1)[-1]:
+            continue  # anchors / routes, not files
+        refs.append(candidate)
+    return refs
+
+
+def repair_bundle_references(files: Dict[str, str]) -> Tuple[Dict[str, str], List[str]]:
+    """Deterministically point dangling HTML refs at real bundle files.
+
+    A weak model asked for ``style.css`` sometimes links ``styles.css``. When
+    a referenced file is missing but the bundle contains exactly one file of
+    the same extension, the reference is rewritten. Returns ``(files, fixes)``.
+    """
+    names = {p.rsplit("/", 1)[-1] for p in files}
+    fixes: List[str] = []
+    repaired = dict(files)
+    for path, content in files.items():
+        if _ext(path) not in (".html", ".htm"):
+            continue
+        updated = content
+        for ref in _local_bundle_refs(content):
+            base = ref.rsplit("/", 1)[-1]
+            if base in names:
+                continue
+            same_ext = [n for n in names if _ext(n) == _ext(base)]
+            if len(same_ext) == 1:
+                updated = updated.replace(ref, same_ext[0])
+                fixes.append(f"{path}: '{ref}' -> '{same_ext[0]}'")
+        if updated != content:
+            repaired[path] = updated
+    return repaired, fixes
+
+
+def validate_project_bundle(files: Dict[str, str]) -> Dict[str, Any]:
+    """Bundle-level verification: every file valid, every HTML ref resolvable."""
+    issues: List[str] = []
+    per_file: Dict[str, Dict[str, Any]] = {}
+    names = {p.rsplit("/", 1)[-1] for p in files}
+    for path, content in files.items():
+        ok, reason = validate_file_content(content, path)
+        per_file[path] = {"valid": ok, "reason": reason}
+        if not ok:
+            issues.append(f"{path}: {reason}")
+        if _ext(path) in (".html", ".htm"):
+            for ref in _local_bundle_refs(content):
+                if ref.rsplit("/", 1)[-1] not in names:
+                    issues.append(f"{path}: references missing file '{ref}'")
+    return {"ok": not issues, "issues": issues, "files": per_file}