ltcai 11.7.0 → 12.0.0

package/latticeai/api/worker_compute.py

@@ -3,8 +3,14 @@
 Plan §설계 결정 2 (revised) hands **every write** to Rust — platform state and
 the knowledge graph both. What is left for Python is the part Rust cannot do
 without shipping a model runtime and half of PyPI: turning text into vectors,
-turning a document into text, turning a spec into document bytes, turning audio
-into a transcript, and turning a picture into facts about it.
+turning a document into text, turning a spec into document bytes, and turning
+audio into a transcript.
+
+A ninth seam, ``POST /worker/multimodal/describe``, was here until v11.8.0. It
+wrapped :func:`lattice_brain.multimodal.extract_image_facts` for a native image
+ingest that was never built, so nothing in the tree ever called it — not
+``lattice-ingest``, not the gateway. The Brain Core functions behind it are
+untouched; what went is the door nobody opened.
 
 ``worker_seams.py`` holds the *state* seams (``/worker/chat/record-turn``,
 ``/worker/graph/mutate``) that Wave 2 codes against and Wave 2.5 §W3 retires.
@@ -13,7 +19,7 @@ here opens a database, writes a file, or reaches a store. Each handler is a
 function of its request body, so a caller can retry it, cache it, or run two of
 them at once without asking who else is writing.
 
-The five seams, and what each was extracted from:
+The nine seams, and what each was extracted from:
 
 ``POST /worker/embed``
     ``EmbeddingProvider.embed_batch`` on the *resolved* provider — the same
@@ -30,22 +36,15 @@ The five seams, and what each was extracted from:
 
 ``POST /worker/render/{docx,xlsx,pptx,pdf}``
     The *building* half of ``tools.documents.create_*`` — same libraries, same
-    layout decisions, same filename sanitising — with ``save(path)`` replaced by
-    ``save(BytesIO)``. Rust places the file; this seam never learns where.
+    layout decisions — with ``save(path)`` replaced by ``save(BytesIO)``. Rust
+    places the file, sanitises the name and resolves the target; this seam
+    never learns where and answers with bytes only.
 
 ``POST /worker/asr``
     ``VoiceCaptureService._transcribe``'s contract without the ingest: the same
     injected transcriber port, the same container whitelist and size ceiling,
     and the same refusal to call an empty transcript "text".
 
-``POST /worker/multimodal/describe``
-    :func:`lattice_brain.multimodal.extract_image_facts` plus
-    :func:`~lattice_brain.multimodal.image_quality_score` — exactly what
-    ``IngestionRoutingMixin._ingest_image`` computes before it writes a node.
-    The describe step *is* separable here because Brain Core already split it:
-    observing an image and writing it are two functions, and only the first one
-    is compute.
-
 ``POST /worker/extract``
     :func:`~lattice_brain.graph._kg_common.extraction._extract_concepts` (LLM-first),
     :func:`~lattice_brain.graph._kg_common.extraction._extract_triples` and
@@ -54,6 +53,12 @@ The five seams, and what each was extracted from:
     consume, already classified. Rust writes the Concept/Task/Decision subgraph;
     this seam never opens a store.
 
+``POST /worker/vector/query``
+    Approximate nearest-neighbour over the ``.hnsw`` sidecar next to the
+    brain database. The one compute seam that *reads* the store (row count
+    + embeddings, never a write) so it can refresh the sidecar and say
+    ``index: "none"`` when there is nothing to serve.
+
 Gating is the seam gate the rest of the worker uses — ``LATTICEAI_AGENT_TOOL_SEAM``
 read per request through :func:`latticeai.api.agent_worker_seam._seam_open`,
 then ``require_user`` and the ``agent_seam`` rate bucket. Off ⇒ 404. Mounted
@@ -67,8 +72,10 @@ import asyncio
 import base64
 import binascii
 import contextlib
+import importlib.util
 import io
 import logging
+import sys
 import tempfile
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple
@@ -85,7 +92,7 @@ from latticeai.services.voice_capture import (
     SUPPORTED_AUDIO_EXTENSIONS,
 )
 from latticeai.tools import _CJK_FONT_CANDIDATES, ToolError
-from latticeai.tools.documents import _body_to_str, _safe_filename, read_document
+from latticeai.tools.documents import _body_to_str, read_document
 
 logger = logging.getLogger(__name__)
 
@@ -107,15 +114,11 @@ EXTRACT_LIMITS: Dict[str, int] = {"message": 12, "document": 15}
 #: write-side module would tie this compute seam to a module W1 is replacing.
 PASSAGE_MAX_CHARS = 50_000
 
-#: Render kind → the suffix ``_safe_filename`` enforces. Same table as
-#: ``documents._DOCUMENT_TOOL_TARGETS``, minus the output directory: where the
-#: file lands is Rust's decision now, so this seam does not carry it.
-RENDER_SUFFIXES: Dict[str, str] = {
-    "docx": ".docx",
-    "xlsx": ".xlsx",
-    "pptx": ".pptx",
-    "pdf": ".pdf",
-}
+#: Upper bound on ``texts`` for one ``POST /worker/embed``. Ingest already
+#: batches; a caller that dumps a whole vault into one request is a bug, not
+#: a use case. 256 sits in the 128–256 band G-RAG-A recommended. Additive:
+#: the request/response shape is unchanged.
+EMBED_MAX_BATCH = 256
 
 #: The CJK-capable fonts ``create_pdf`` looks for, as a module attribute so a
 #: test can point the probe at a font that exists (and at one that does not)
@@ -163,9 +166,40 @@ WORKER_COMPUTE_MESSAGES: Dict[str, Dict[str, str]] = {
         "ko": "'{kind}' 은(는) 추출 종류가 아닙니다. {allowed} 중 하나여야 합니다.",
         "en": "'{kind}' is not an extraction kind. Use one of {allowed}.",
     },
+    "worker_compute.embed_batch_too_large": {
+        "ko": "임베딩 배치가 {count}개입니다. 한 번에 {limit}개까지입니다.",
+        "en": "The embed batch has {count} texts; the limit is {limit}.",
+    },
+    "worker_compute.vector_query_invalid": {
+        "ko": "벡터 질의는 embedding_model, embedding_dim, vector 가 필요합니다.",
+        "en": "A vector query needs embedding_model, embedding_dim, and vector.",
+    },
 }
 
 
+def pointer_tools_available() -> bool:
+    """Whether this interpreter can import ``pyautogui``.
+
+    Cheap and side-effect free: ``find_spec`` does not load the module, so a
+    headless worker without a display is not punished for answering the
+    question. The platform computer-use status route reads this through
+    ``GET /worker/sysinfo`` rather than guessing from its own process.
+    """
+    return importlib.util.find_spec("pyautogui") is not None
+
+
+def sysinfo_payload_extras() -> Dict[str, Any]:
+    """Additive fields for ``GET /worker/sysinfo``.
+
+    Existing GPU keys stay owned by ``worker_seams.probe_gpu_memory``. This
+    dict is merged in; it must never reuse those names.
+    """
+    return {
+        "capabilities": {"pointer_tools": pointer_tools_available()},
+        "python_version": "{}.{}.{}".format(*sys.version_info[:3]),
+    }
+
+
 def register_worker_compute_messages() -> None:
     """Publish this module's messages into the one shared catalog."""
     for key, entry in WORKER_COMPUTE_MESSAGES.items():
@@ -415,16 +449,6 @@ class AsrRequest(BaseModel):
     filename: Optional[str] = None
 
 
-class DescribeRequest(BaseModel):
-    """One picture, with the two observation switches ``extract_image_facts`` takes."""
-
-    content_b64: str
-    mime: Optional[str] = None
-    filename: Optional[str] = None
-    ocr: bool = True
-    thumbnail: bool = True
-
-
 class ExtractRequest(BaseModel):
     """The text one ingest door would hand ``_extract_concepts``."""
 
@@ -432,6 +456,16 @@ class ExtractRequest(BaseModel):
     kind: str = "message"
 
 
+class VectorQueryRequest(BaseModel):
+    """Approximate neighbours from the HNSW sidecar. ``k`` is capped at 200."""
+
+    workspace: Optional[str] = None
+    embedding_model: str
+    embedding_dim: int
+    vector: List[float] = Field(default_factory=list)
+    k: int = 10
+
+
 def build_extract_reply(text: str, kind: str) -> Dict[str, Any]:
     """The structures ``ingest_message`` / ``ingest_document`` / ``ingest_source`` consume.
 
@@ -484,18 +518,17 @@ def create_worker_compute_router(
     *,
     embedder: Any,
     transcriber: Optional[Callable[[str], str]] = None,
-    multimodal_ports: Any = None,
     require_user: Callable[[Request], Any],
     enforce_rate_limit: Callable[[str, str], None],
+    db_path: Any = None,
 ) -> APIRouter:
     """The nine compute seams, wired to what this worker actually resolved.
 
     ``embedder`` is the :class:`~latticeai.core.embedding_providers.text.ResolvedEmbedder`
     ``phase_brain`` built (``None`` ⇒ 503, because a worker with no embedder is
-    a configuration rather than a crash). ``transcriber`` and
-    ``multimodal_ports`` are the same injected ports the voice and ingestion
-    paths hold; absent, the relevant seam reports the absence instead of
-    inventing a transcript or a caption.
+    a configuration rather than a crash). ``transcriber`` is the injected port
+    the voice path holds; absent, ``/worker/asr`` reports the absence instead of
+    inventing a transcript.
     """
     router = APIRouter()
 
@@ -522,11 +555,18 @@ def create_worker_compute_router(
     async def _render(
         kind: str,
         builder: Callable[[], bytes],
-        filename: str,
         language: str,
         **extra: Any,
     ) -> Dict[str, Any]:
-        """Build one document off the event loop and hand back its bytes."""
+        """Build one document off the event loop and hand back its bytes.
+
+        The reply is the bytes and what they cost, and nothing about *where*
+        they go: ``lattice-agent``'s ``documents::document_output_target`` runs
+        its own ``safe_filename`` and ``Workspace::resolve`` over the request's
+        ``filename`` **before** it calls here, and writes to the target it
+        resolved. A second sanitisation on this side produced a name no caller
+        ever read — two spellings of one rule, one of them invisible.
+        """
         try:
             payload = await asyncio.to_thread(builder)
         except ToolError as exc:
@@ -541,7 +581,6 @@ def create_worker_compute_router(
                 500, "worker_compute.render_failed", language, kind=kind, reason=str(exc)
             ) from exc
         return {
-            "filename": _safe_filename(filename, RENDER_SUFFIXES[kind]),
             "content_b64": base64.b64encode(payload).decode("ascii"),
             "bytes": len(payload),
             **extra,
@@ -572,15 +611,37 @@ def create_worker_compute_router(
             )
         provider = embedder.provider
         texts = list(req.texts)
+        if len(texts) > EMBED_MAX_BATCH:
+            raise http_error(
+                422,
+                "worker_compute.embed_batch_too_large",
+                language,
+                count=str(len(texts)),
+                limit=str(EMBED_MAX_BATCH),
+            )
         if kind == "passage":
             texts = [text[:PASSAGE_MAX_CHARS] for text in texts]
-        vectors = await asyncio.to_thread(provider.embed_batch, texts)
+        # `embed_batch_for` rather than `embed_batch`: an asymmetric model (the
+        # E5 family) needs to know whether this text is the question or the
+        # answer, and `kind` is exactly that. Symmetric providers ignore it.
+        # Resolved by name because the embedder arrives injected: a stand-in
+        # that predates the role-aware method still embeds, it just cannot be
+        # told which role it is embedding for.
+        role_aware = getattr(provider, "embed_batch_for", None)
+        vectors = (
+            await asyncio.to_thread(role_aware, texts, kind)
+            if callable(role_aware)
+            else await asyncio.to_thread(provider.embed_batch, texts)
+        )
         return {
             "vectors": vectors,
             "dim": provider.dim,
             "provider": embedder.active,
             "model_id": provider.model_id,
             "kind": kind,
+            # Additive (v12.0.0): `fallback` means these vectors are feature
+            # hashes, not meaning. A caller that stores them can say so.
+            "grade": getattr(provider, "grade", "fallback"),
         }
 
     @router.post("/worker/parse")
@@ -616,7 +677,6 @@ def create_worker_compute_router(
         return await _render(
             "docx",
             lambda: build_docx_bytes(req.title, req.body),
-            req.filename,
             resolve_language(request),
         )
 
@@ -628,7 +688,6 @@ def create_worker_compute_router(
         return await _render(
             "xlsx",
             lambda: build_xlsx_bytes(req.rows, req.sheet_name),
-            req.filename,
             resolve_language(request),
             rows=len(req.rows),
         )
@@ -641,7 +700,6 @@ def create_worker_compute_router(
         return await _render(
             "pptx",
             lambda: build_pptx_bytes(req.title, req.slides),
-            req.filename,
             resolve_language(request),
             slides=len(req.slides) + 1,
         )
@@ -654,7 +712,6 @@ def create_worker_compute_router(
         return await _render(
             "pdf",
             lambda: build_pdf_bytes(req.title, req.body),
-            req.filename,
             resolve_language(request),
         )
 
@@ -731,64 +788,6 @@ def create_worker_compute_router(
             "detail": "",
         }
 
-    @router.post("/worker/multimodal/describe")
-    async def worker_multimodal_describe(req: DescribeRequest, request: Request):
-        """Everything ``_ingest_image`` knows before it writes a node.
-
-        ``metadata`` is ``ImageFacts.as_metadata()`` — the exact dict
-        ``write_image_memory`` merges onto the node — and ``index_text`` is the
-        exact text it chunks. ``embedding`` is present only when a vision model
-        produced one, which is the one property an image vector must have.
-        """
-        _require_seam(request)
-        _admit(request)
-        language = resolve_language(request)
-        data = _decode(req.content_b64, language)
-        suffix = _suffix_for(req.filename, req.mime, ".png")
-
-        from lattice_brain.ingestion import _quality_level
-        from lattice_brain.multimodal import (
-            MODALITY_IMAGE,
-            MultimodalPorts,
-            extract_image_facts,
-            image_quality_score,
-        )
-
-        ports = multimodal_ports or MultimodalPorts()
-        with _temp_payload(data, suffix) as tmp_path:
-            facts = await asyncio.to_thread(
-                lambda: extract_image_facts(
-                    tmp_path, ports=ports, ocr=req.ocr, thumbnail=req.thumbnail
-                )
-            )
-        quality = image_quality_score(facts)
-        return {
-            "modality": MODALITY_IMAGE,
-            "readable": facts.readable,
-            "error": facts.error,
-            "width": facts.width,
-            "height": facts.height,
-            "format": facts.image_format,
-            "mode": facts.mode,
-            "ocr_status": facts.ocr_status,
-            "ocr_text": facts.ocr_text,
-            "ocr_detail": facts.ocr_detail,
-            "caption_status": facts.caption_status,
-            "caption": facts.caption,
-            "embedding_status": facts.embedding_status,
-            "embedding": facts.embedding,
-            "embedding_detail": facts.embedding_detail,
-            "thumbnail": facts.thumbnail,
-            "index_text": facts.index_text(),
-            "metadata": facts.as_metadata(),
-            "quality": {
-                "score": quality["score"],
-                "level": _quality_level(quality["score"]),
-                "reasons": quality["reasons"],
-            },
-            "ports": ports.describe(),
-        }
-
     @router.post("/worker/extract")
     async def worker_extract(req: ExtractRequest, request: Request):
         """Concepts, triples and Task/Decision items for this text.
@@ -812,22 +811,42 @@ def create_worker_compute_router(
             )
         return await asyncio.to_thread(build_extract_reply, req.text, kind)
 
+    @router.post("/worker/vector/query")
+    async def worker_vector_query(req: VectorQueryRequest, request: Request):
+        """Top-k ids from the HNSW sidecar, or ``index: "none"`` honestly."""
+        _require_seam(request)
+        _admit(request)
+        language = resolve_language(request)
+        if not req.embedding_model or req.embedding_dim <= 0 or not req.vector:
+            raise http_error(422, "worker_compute.vector_query_invalid", language)
+        from latticeai.core.vector_index import query_sidecar
+
+        return await asyncio.to_thread(
+            query_sidecar,
+            workspace=req.workspace,
+            embedding_model=req.embedding_model,
+            embedding_dim=req.embedding_dim,
+            vector=req.vector,
+            k=req.k,
+            db_path=db_path,
+        )
+
     return router
 
 
 __all__ = [
     "CJK_FONT_CANDIDATES",
     "EMBED_KINDS",
+    "EMBED_MAX_BATCH",
     "EXTRACT_KINDS",
     "EXTRACT_LIMITS",
     "PASSAGE_MAX_CHARS",
-    "RENDER_SUFFIXES",
     "WORKER_COMPUTE_MESSAGES",
     "AsrRequest",
-    "DescribeRequest",
     "EmbedRequest",
     "ExtractRequest",
     "ParseRequest",
+    "VectorQueryRequest",
     "RenderDocxRequest",
     "RenderPdfRequest",
     "RenderPptxRequest",
@@ -838,5 +857,7 @@ __all__ = [
     "build_pptx_bytes",
     "build_xlsx_bytes",
     "create_worker_compute_router",
+    "pointer_tools_available",
     "register_worker_compute_messages",
+    "sysinfo_payload_extras",
 ]

package/latticeai/api/worker_seams.py

@@ -85,21 +85,36 @@ def probe_gpu_memory() -> Dict[str, Any]:
         total = _total_memory_bytes()
     except Exception as exc:  # noqa: BLE001 — an absent GPU is not a failure
         quiet("MLX unified-memory probe")
-        return {
+        payload = {
             "mlx_available": False,
             "gpu_mem_gb": 0.0,
             "gpu_mem_pct": 0.0,
             "total_bytes": 0,
             "detail": str(exc),
         }
+        payload.update(_sysinfo_extras())
+        return payload
     used = active + cached
-    return {
+    payload = {
         "mlx_available": True,
         "gpu_mem_gb": round(used / (1024 ** 3), 2),
         "gpu_mem_pct": round(used / total * 100, 1) if total else 0.0,
         "total_bytes": total,
         "detail": None,
     }
+    payload.update(_sysinfo_extras())
+    return payload
+
+
+def _sysinfo_extras() -> Dict[str, Any]:
+    """Additive capability / interpreter facts. Fail closed to empty extras."""
+    try:
+        from latticeai.api.worker_compute import sysinfo_payload_extras
+
+        extras = sysinfo_payload_extras()
+    except Exception:  # noqa: BLE001 — a missing extra must not hide the GPU reading
+        return {}
+    return extras if isinstance(extras, dict) else {}
 
 
 # ── request bodies ──────────────────────────────────────────────────────────

package/latticeai/core/embedding_providers/__init__.py

@@ -68,6 +68,14 @@ from __future__ import annotations
 from lattice_brain.embeddings import DEFAULT_EMBEDDING_DIM as DEFAULT_EMBEDDING_DIM
 from lattice_brain.embeddings import LocalEmbeddingModel as LocalEmbeddingModel
 
+from .autodetect import AUTO_PROVIDER as AUTO_PROVIDER
+from .autodetect import AUTODETECT_ENV as AUTODETECT_ENV
+from .autodetect import LOCAL_MLX_MODELS as LOCAL_MLX_MODELS
+from .autodetect import Detection as Detection
+from .autodetect import detect_embedder as detect_embedder
+from .autodetect import detect_local_mlx as detect_local_mlx
+from .autodetect import detect_ollama as detect_ollama
+from .autodetect import resolve_auto_provider as resolve_auto_provider
 from .base import _KNOWN_DIMS as _KNOWN_DIMS
 from .base import EmbeddingProvider as EmbeddingProvider
 from .base import EmbeddingUnavailable as EmbeddingUnavailable
@@ -113,6 +121,14 @@ from .vision import build_vision_provider as build_vision_provider
 from .vision import resolve_vision_embedder as resolve_vision_embedder
 
 __all__ = [
+    "AUTODETECT_ENV",
+    "AUTO_PROVIDER",
+    "LOCAL_MLX_MODELS",
+    "Detection",
+    "detect_embedder",
+    "detect_local_mlx",
+    "detect_ollama",
+    "resolve_auto_provider",
     "DEFAULT_CAPTION_PROMPT",
     "DEFAULT_VISION_DIM",
     "VISION_CAPTION_TARGET_ENV",