lastlight 0.1.0__py3-none-any.whl

lastlight/__init__.py

@@ -0,0 +1,14 @@
+"""LastLight: offline intelligence under extreme constraints."""
+
+from .api import LastLight
+from .types import QueryResult, RetrievalMetadata, SourceResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LastLight",
+    "QueryResult",
+    "RetrievalMetadata",
+    "SourceResult",
+    "__version__",
+]

lastlight/adaptive.py

@@ -0,0 +1,3 @@
+"""Backward-compatible imports for :mod:`lastlight.retrieval.adaptive`."""
+
+from .retrieval.adaptive import *  # noqa: F401,F403

lastlight/api.py

@@ -0,0 +1,119 @@
+"""Stable library-facing facade for the LastLight runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from .application.factory import ApplicationFactory
+from .safety.triage import first_acceptable_result
+from .shared.domain import SearchResult
+from .types import QueryResult, RetrievalMetadata, SourceResult
+
+KnowledgeSource = Path | str
+KnowledgeSources = KnowledgeSource | Sequence[KnowledgeSource] | None
+
+
+class LastLight:
+    """Small public facade over the offline LastLight application runtime.
+
+    Ecosystem clients should prefer this facade instead of importing internal
+    factories or package-specific implementation modules.
+    """
+
+    def __init__(
+        self,
+        knowledge: KnowledgeSources = None,
+        *,
+        strategy: str = "lexical",
+        language: str | None = None,
+        mode: str = "balanced",
+        energy_budget_mwh: float | None = None,
+        memory_budget_mb: int | None = None,
+    ) -> None:
+        self.strategy = strategy
+        self.mode = mode
+        self._app = ApplicationFactory.create(
+            knowledge_dir=knowledge,
+            strategy=strategy,
+            language=language,
+            mode=mode,
+            energy_budget_mwh=energy_budget_mwh,
+            memory_budget_mb=memory_budget_mb,
+        )
+
+    @classmethod
+    def from_packs(
+        cls,
+        packs: Sequence[KnowledgeSource],
+        **kwargs: object,
+    ) -> "LastLight":
+        """Create an engine from one or more local directory/ZIP packs."""
+
+        return cls(knowledge=packs, **kwargs)
+
+    def search(self, text: str, *, top_k: int = 3) -> list[SearchResult]:
+        """Return ranked retrieval results for advanced callers."""
+
+        return self._app.search(text, top_k=top_k)
+
+    def query(self, text: str, *, top_k: int = 3) -> QueryResult:
+        """Return a stable, structured result suitable for UIs and integrations."""
+
+        results = self._app.search(text, top_k=top_k)
+        accepted = first_acceptable_result(results)
+        metadata = self._metadata(top_k)
+        return QueryResult(
+            query=text,
+            accepted=accepted is not None,
+            confidence=accepted.confidence if accepted else None,
+            passage=accepted.passage if accepted else None,
+            sources=tuple(self._source_result(result) for result in results),
+            retrieval=metadata,
+        )
+
+    def answer(self, text: str, *, top_k: int = 3) -> str:
+        """Return the existing human-readable, safety-aware answer."""
+
+        return self._app.answer(text, top_k=top_k)
+
+    def plan(self, text: str, *, top_k: int = 3) -> RetrievalMetadata:
+        """Run retrieval and expose the selected retrieval-policy metadata."""
+
+        self._app.search(text, top_k=top_k)
+        return self._metadata(top_k)
+
+    def retrieval_metadata(self) -> dict[str, object] | None:
+        """Compatibility hook for first-party adapters; prefer :meth:`plan`."""
+
+        return self._app.retrieval_metadata()
+
+    def _metadata(self, top_k: int) -> RetrievalMetadata:
+        raw = self._app.retrieval_metadata() or {
+            "strategy": self.strategy,
+            "mode": "fixed",
+            "effective_top_k": top_k,
+        }
+        return RetrievalMetadata(
+            strategy=str(raw.get("strategy", self.strategy)),
+            mode=str(raw.get("mode", "fixed")),
+            effective_top_k=int(raw.get("effective_top_k", top_k)),
+            risk=str(raw["risk"]) if raw.get("risk") is not None else None,
+            reason=str(raw["reason"]) if raw.get("reason") is not None else None,
+        )
+
+    @staticmethod
+    def _source_result(result: SearchResult) -> SourceResult:
+        document = result.document
+        return SourceResult(
+            title=document.title,
+            path=document.path,
+            pack_name=document.pack_name,
+            pack_version=document.pack_version,
+            language=document.language,
+            tags=document.tags,
+            score=result.score,
+            confidence=result.confidence,
+            passage=result.passage,
+            matched_terms=result.matched_terms,
+        )

lastlight/app.py

@@ -0,0 +1,2 @@
+"""Backward-compatible imports for :mod:`lastlight.application.app`."""
+from .application.app import *  # noqa: F401,F403

lastlight/application/__init__.py

@@ -0,0 +1 @@
+"""Application services, sessions, language routing and construction."""

lastlight/application/adaptive.py

@@ -0,0 +1,2 @@
+"""Internal bridge to adaptive retrieval."""
+from ..retrieval.adaptive import *  # noqa: F401,F403

lastlight/application/app.py

@@ -0,0 +1,49 @@
+"""Application service layer."""
+
+from __future__ import annotations
+
+from .domain import SearchQuery, SearchResult
+from .interfaces import KnowledgeRepository, RetrievalStrategy
+from .language import resolve_retrieval_language
+from .safety import safe_answer
+from .triage import append_follow_up_questions, first_acceptable_result
+
+
+class LastLightApp:
+    def __init__(
+        self,
+        repository: KnowledgeRepository,
+        retrieval: RetrievalStrategy,
+        language: str | None = None,
+    ) -> None:
+        self.repository = repository
+        self.retrieval = retrieval
+        self.language = language.casefold() if language else None
+
+    def search(self, text: str, top_k: int = 3) -> list[SearchResult]:
+        documents = self.repository.list_documents()
+        effective_language = resolve_retrieval_language(
+            text,
+            documents,
+            explicit_language=self.language,
+        )
+        if effective_language:
+            documents = [
+                document
+                for document in documents
+                if document.language.casefold() == effective_language
+            ]
+        return self.retrieval.search(SearchQuery(text=text, top_k=top_k), documents)
+
+    def answer(self, text: str, top_k: int = 3) -> str:
+        results = self.search(text, top_k=top_k)
+        return append_follow_up_questions(
+            safe_answer(results), first_acceptable_result(results)
+        )
+
+    def retrieval_metadata(self) -> dict[str, object] | None:
+        getter = getattr(self.retrieval, "decision_metadata", None)
+        if not callable(getter):
+            return None
+        metadata = getter()
+        return metadata if isinstance(metadata, dict) else None

lastlight/application/domain.py

@@ -0,0 +1,2 @@
+"""Internal bridge to shared domain models."""
+from ..shared.domain import *  # noqa: F401,F403

lastlight/application/factory.py

@@ -0,0 +1,37 @@
+"""Application factory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from .adaptive import AdaptiveRetrievalConfig, AdaptiveRetrievalStrategy
+from .app import LastLightApp
+from .knowledge_sources import build_knowledge_repository
+from .retrieval import BM25RetrievalStrategy, LexicalRetrievalStrategy
+
+
+class ApplicationFactory:
+    @staticmethod
+    def create(
+        knowledge_dir: Path | str | Sequence[Path | str] | None = None,
+        strategy: str = "lexical",
+        language: str | None = None,
+        mode: str = "balanced",
+        energy_budget_mwh: float | None = None,
+        memory_budget_mb: int | None = None,
+    ) -> LastLightApp:
+        repository = build_knowledge_repository(knowledge_dir)
+        if strategy == "bm25":
+            retrieval = BM25RetrievalStrategy()
+        elif strategy == "adaptive":
+            retrieval = AdaptiveRetrievalStrategy(
+                AdaptiveRetrievalConfig(
+                    mode=mode,
+                    energy_budget_mwh=energy_budget_mwh,
+                    memory_budget_mb=memory_budget_mb,
+                )
+            )
+        else:
+            retrieval = LexicalRetrievalStrategy()
+        return LastLightApp(repository=repository, retrieval=retrieval, language=language)

lastlight/application/interfaces.py

@@ -0,0 +1,2 @@
+"""Internal bridge to shared protocols."""
+from ..shared.interfaces import *  # noqa: F401,F403

lastlight/application/knowledge_sources.py

@@ -0,0 +1,2 @@
+"""Internal bridge to knowledge source construction."""
+from ..knowledge.knowledge_sources import *  # noqa: F401,F403

lastlight/application/language.py

@@ -0,0 +1,76 @@
+"""Deterministic language routing for offline retrieval."""
+
+from __future__ import annotations
+
+import re
+
+from .domain import KnowledgeDocument
+
+_WORD_RE = re.compile(r"[^\W\d_]+", re.UNICODE)
+
+_SPANISH_TERMS = {
+    "agua", "ayuda", "bateria", "batería", "beber", "calor", "comida",
+    "como", "cómo", "donde", "dónde", "emergencia", "fuego", "frio", "frío",
+    "herida", "hervir", "inundacion", "inundación", "necesito", "primeros",
+    "refugio", "sangre", "segura", "seguro", "terremoto", "sin", "con",
+    "para", "que", "qué", "una", "uno", "unos", "unas", "el", "la", "los", "las",
+}
+
+_ENGLISH_TERMS = {
+    "water", "help", "battery", "drink", "heat", "food", "how", "where",
+    "emergency", "fire", "cold", "wound", "boil", "flood", "need", "first",
+    "aid", "shelter", "blood", "safe", "earthquake", "without", "with", "for",
+    "what", "the", "a", "an",
+}
+
+_SPANISH_CHARS = set("áéíóúüñ¿¡")
+
+
+def corpus_languages(documents: list[KnowledgeDocument]) -> tuple[str, ...]:
+    """Return known document languages in deterministic order."""
+    languages = {
+        document.language.casefold()
+        for document in documents
+        if document.language and document.language.casefold() not in {"unknown", "und"}
+    }
+    return tuple(sorted(languages))
+
+
+def infer_query_language(text: str, available: tuple[str, ...]) -> str | None:
+    """Infer Spanish or English only when the query provides useful evidence."""
+    normalized = text.strip().casefold()
+    if not normalized:
+        return None
+
+    words = _WORD_RE.findall(normalized)
+    spanish_score = sum(word in _SPANISH_TERMS for word in words)
+    english_score = sum(word in _ENGLISH_TERMS for word in words)
+
+    if any(char in _SPANISH_CHARS for char in normalized):
+        spanish_score += 2
+
+    if "es" in available and spanish_score > english_score and spanish_score > 0:
+        return "es"
+    if "en" in available and english_score > spanish_score and english_score > 0:
+        return "en"
+    return None
+
+
+def resolve_retrieval_language(
+    text: str,
+    documents: list[KnowledgeDocument],
+    explicit_language: str | None = None,
+) -> str | None:
+    """Resolve the language used to filter documents for one retrieval call.
+
+    Explicit CLI/API configuration always wins. Otherwise a monolingual corpus
+    adopts its only language automatically. Multilingual corpora use conservative
+    ES/EN query detection and leave ambiguous queries unfiltered.
+    """
+    if explicit_language:
+        return explicit_language.casefold()
+
+    available = corpus_languages(documents)
+    if len(available) == 1:
+        return available[0]
+    return infer_query_language(text, available)

lastlight/application/retrieval.py

@@ -0,0 +1,2 @@
+"""Internal bridge to retrieval strategies."""
+from ..retrieval.strategies import *  # noqa: F401,F403

lastlight/application/safety.py

@@ -0,0 +1,2 @@
+"""Internal bridge to safety response formatting."""
+from ..safety.safety import *  # noqa: F401,F403

lastlight/application/session.py

@@ -0,0 +1,120 @@
+"""Tiny session memory for follow-up questions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .app import LastLightApp
+from .domain import SearchResult
+from .safety import LOW_CONFIDENCE_RESPONSE, safe_answer
+from .triage import append_follow_up_questions, first_acceptable_result
+
+FOLLOW_UP_PREFIXES = (
+    "and ",
+    "also ",
+    "what about",
+    "what if",
+    "what should",
+    "how about",
+    "then ",
+    "next ",
+    "can i",
+    "should i",
+)
+
+SHORT_FOLLOW_UP_TERMS = {
+    "again",
+    "after",
+    "before",
+    "inside",
+    "indoors",
+    "night",
+    "now",
+    "outside",
+    "then",
+    "there",
+    "this",
+    "that",
+    "with",
+    "without",
+}
+
+
+@dataclass
+class SessionMemory:
+    query: str = ""
+    title: str = ""
+    tags: tuple[str, ...] = ()
+    matched_terms: tuple[str, ...] = ()
+
+    @property
+    def has_context(self) -> bool:
+        return bool(self.query or self.title or self.tags or self.matched_terms)
+
+    def context_text(self) -> str:
+        return " ".join(
+            value
+            for value in (
+                self.query,
+                self.title,
+                " ".join(self.tags),
+                " ".join(self.matched_terms),
+            )
+            if value
+        )
+
+
+class LastLightSession:
+    def __init__(self, app: LastLightApp) -> None:
+        self.app = app
+        self.memory = SessionMemory()
+
+    def clear(self) -> None:
+        self.memory = SessionMemory()
+
+    def search(self, query: str, top_k: int = 3) -> list[SearchResult]:
+        search_text = self._contextual_query(query)
+        results = self.app.search(search_text, top_k=top_k)
+        self._remember(query, results)
+        return results
+
+    def answer(self, query: str) -> str:
+        results = self.search(query, top_k=3)
+        return append_follow_up_questions(
+            safe_answer(results), first_acceptable_result(results)
+        )
+
+    def answer_passage(self, query: str) -> str:
+        results = self.search(query, top_k=3)
+        result = first_acceptable_result(results)
+        if result is not None:
+            return result.passage
+        return LOW_CONFIDENCE_RESPONSE
+
+    def _contextual_query(self, query: str) -> str:
+        if not self.memory.has_context or not _looks_like_follow_up(query):
+            return query
+        return f"{self.memory.context_text()} {query}"
+
+    def _remember(self, query: str, results: list[SearchResult]) -> None:
+        for result in results:
+            if result.confidence in {"HIGH", "MEDIUM"}:
+                self.memory = SessionMemory(
+                    query=query,
+                    title=result.document.title,
+                    tags=result.document.tags,
+                    matched_terms=result.matched_terms,
+                )
+                return
+
+
+def _looks_like_follow_up(query: str) -> bool:
+    normalized = query.strip().casefold()
+    if not normalized:
+        return False
+    if normalized.startswith(FOLLOW_UP_PREFIXES):
+        return True
+    words = normalized.replace("?", "").split()
+    return len(words) <= 4 and (
+        normalized.endswith("?") or bool(SHORT_FOLLOW_UP_TERMS.intersection(words))
+    )

lastlight/application/triage.py

@@ -0,0 +1,2 @@
+"""Internal bridge to deterministic triage."""
+from ..safety.triage import *  # noqa: F401,F403

lastlight/chunking.py

@@ -0,0 +1,3 @@
+"""Backward-compatible imports for :mod:`lastlight.retrieval.chunking`."""
+
+from .retrieval.chunking import *  # noqa: F401,F403

lastlight/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command-line interface and command handlers.
+
+The package re-exports the historical ``lastlight.cli`` module surface so tests,
+embedders and monkeypatch-based integrations keep working after the source tree
+was split into subpackages.
+"""
+
+from .cli import *  # noqa: F401,F403

lastlight/cli/app.py

@@ -0,0 +1,2 @@
+"""Internal bridge to the application service."""
+from ..application.app import *  # noqa: F401,F403