lorebase-keeper 0.2.3__py3-none-any.whl

lorebase_keeper/reading/requests.py

@@ -0,0 +1,107 @@
+"""Request bodies of the read API."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from lorebase_core.query import Predicate, Query
+
+AT = (
+    "Revision id or tag to read at (time travel): key-ordered listings read the tree, other "
+    "reads a snapshot of the Revision."
+)
+
+
+class _Body(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class QueryRequest(Query):
+    """A DSL query (design 8.2) and where to read it."""
+
+    branch: str | None = Field(default=None, description="Default: the Domain's default branch.")
+    at: str | None = Field(default=None, description=AT)
+
+
+class RecordAddress(_Body):
+    kind: str = Field(min_length=1)
+    key: str = Field(min_length=1)
+
+
+class TraverseStep(_Body):
+    relation: str = Field(min_length=1, description="Forward or inverse Relation api name.")
+    where: Predicate | None = Field(default=None, description="Filter on the Records reached.")
+    limit: int | None = Field(default=None, ge=1, description="Records reached by this step.")
+
+
+class TraverseRequest(_Body):
+    """Follow a path of Relations from one Record (design 8.3)."""
+
+    branch: str | None = None
+    at: str | None = Field(default=None, description=AT)
+    start: RecordAddress
+    path: list[TraverseStep] = Field(min_length=1)
+
+
+class NeighborhoodRequest(_Body):
+    """Breadth-first expansion from seed Records, bounded by depth and caps (design 8.3)."""
+
+    branch: str | None = None
+    at: str | None = Field(default=None, description=AT)
+    seeds: list[RecordAddress] = Field(min_length=1)
+    depth: int = Field(default=1, ge=1)
+    relations: list[str] | None = Field(
+        default=None,
+        description="Relation api names to follow; a forward name follows Links forward, an "
+        "inverse name backward. Default: every Relation in both directions.",
+    )
+    max_nodes: int | None = Field(default=None, ge=1)
+    max_edges: int | None = Field(default=None, ge=1)
+    values: bool = Field(
+        default=True,
+        description="false: nodes are Record headers (kind, key, title) and edges Link "
+        "endpoints (relation, from, to), without values; for callers that need the structure "
+        "only.",
+    )
+
+
+SearchMode = Literal["lexical", "semantic", "hybrid"]
+
+
+class SearchTuning(_Body):
+    """Ranking knobs of one search in place of the `search` settings (to compare parameter
+    sets). Unset knobs keep their configured value; `candidates` and `typo_candidates` may only
+    be lowered and `trigram_threshold` only raised."""
+
+    lexical_weight: float | None = Field(default=None, ge=0, le=100)
+    semantic_weight: float | None = Field(default=None, ge=0, le=100)
+    rrf_k: int | None = Field(default=None, ge=1, le=10_000)
+    trigram_threshold: float | None = Field(default=None, ge=0.1, le=1)
+    trigram_weight: float | None = Field(default=None, ge=0, le=100)
+    typo_candidates: int | None = Field(default=None, ge=0)
+    candidates: int | None = Field(default=None, ge=1)
+
+
+class SearchRequest(_Body):
+    """Full-text, vector or hybrid search (design 8.4). Vectors come from the caller."""
+
+    branch: str | None = None
+    at: str | None = Field(default=None, description=AT)
+    q: str | None = Field(default=None, min_length=1, description="Text query (web search syntax).")
+    kinds: list[str] | None = Field(default=None, description="Kind api names; default: all.")
+    where: Predicate | None = Field(
+        default=None, description="DSL filter; needs exactly one Kind in `kinds`."
+    )
+    mode: SearchMode | None = Field(
+        default=None,
+        description="Default: hybrid with both `q` and `query_vector`, otherwise the one given.",
+    )
+    query_vector: list[float] | None = Field(
+        default=None, description="Query embedding of the configured model and dimension."
+    )
+    limit: int | None = Field(default=None, ge=1)
+    tuning: SearchTuning | None = Field(
+        default=None, description="Ranking knobs in place of the `search` settings."
+    )

lorebase_keeper/reading/runtime.py

@@ -0,0 +1,145 @@
+"""Per-application state of the read path and the read transaction dependency.
+
+Reads run in a read-only transaction with the `read.statement_timeout_ms` statement timeout.
+The Domain is added to the row-level security scope when the read point is resolved
+(`reading.points`), so every query of a request stays inside its Domain.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import OrderedDict
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+from sqlalchemy import func, select, text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from lorebase_core.model import Schema
+from lorebase_keeper.errors import UNAVAILABLE, ProblemError
+from lorebase_keeper.ratelimit.bucket import InMemoryRateStore
+from lorebase_keeper.reading.caching import ResponseCache, build_cache
+from lorebase_keeper.reading.settings import (
+    ReadSettings,
+    SearchSettings,
+    read_settings,
+    search_settings,
+)
+from lorebase_keeper.settings import SensitivitySettings, keeper_settings
+from lorebase_platform.settings import Settings
+from lorebase_store.runtime import StoreRuntime
+from lorebase_store.settings import StoreSettings
+from lorebase_store.vault import VaultKeys
+
+_STATE_KEY = "read_runtime"
+
+
+class SchemaCache:
+    """Thread-safe LRU of compiled schemas keyed by `(domain_id, schema partition hash)`."""
+
+    def __init__(self, max_entries: int) -> None:
+        self._max = max_entries
+        self._entries: OrderedDict[tuple[str, bytes], Schema] = OrderedDict()
+        self._lock = Lock()
+
+    def get(self, domain_id: str, schema_hash: bytes) -> Schema | None:
+        key = (domain_id, schema_hash)
+        with self._lock:
+            found = self._entries.get(key)
+            if found is not None:
+                self._entries.move_to_end(key)
+            return found
+
+    def put(self, domain_id: str, schema_hash: bytes, schema: Schema) -> None:
+        with self._lock:
+            self._entries[(domain_id, schema_hash)] = schema
+            self._entries.move_to_end((domain_id, schema_hash))
+            while len(self._entries) > self._max:
+                self._entries.popitem(last=False)
+
+
+SNAPSHOT_RATE_BUCKETS = 10_000
+"""Principals whose snapshot build buckets are kept (the least recently used are dropped)."""
+
+
+@dataclass
+class ReadRuntime:
+    """Settings, sessions and caches shared by the reads of one application."""
+
+    sessions: async_sessionmaker[AsyncSession]
+    read: ReadSettings
+    search: SearchSettings
+    store: StoreRuntime
+    cache: ResponseCache | None = None
+    sensitivity: SensitivitySettings = field(default_factory=SensitivitySettings)
+    schemas: SchemaCache = field(init=False)
+    snapshot_builds: asyncio.Semaphore = field(init=False)
+    """Snapshot builds running in this process (`read.time_travel`)."""
+    snapshot_rates: InMemoryRateStore = field(init=False)
+    """Snapshot builds started per principal in this process."""
+
+    def __post_init__(self) -> None:
+        self.schemas = SchemaCache(self.read.schema_cache_entries)
+        self.snapshot_builds = asyncio.Semaphore(
+            self.read.time_travel.snapshot_max_concurrent_builds
+        )
+        self.snapshot_rates = InMemoryRateStore(SNAPSHOT_RATE_BUCKETS)
+
+    @property
+    def store_settings(self) -> StoreSettings:
+        return self.store.settings
+
+    @property
+    def vault(self) -> VaultKeys | None:
+        """Keys of the personal data vault; None when it is not configured."""
+        return self.store.vault
+
+    @classmethod
+    def build(cls, settings: Settings, sessions: async_sessionmaker[AsyncSession]) -> ReadRuntime:
+        reads = keeper_settings(settings).reads
+        return cls(
+            sessions=sessions,
+            read=read_settings(settings),
+            search=search_settings(settings),
+            store=StoreRuntime.from_loaded(settings),
+            cache=build_cache(reads.cache),
+            sensitivity=reads.sensitivity,
+        )
+
+
+def get_read_runtime(request: Request) -> ReadRuntime:
+    """The read runtime of the application, built on first use; 503 without a database."""
+    state = request.app.state
+    runtime = getattr(state, _STATE_KEY, None)
+    if runtime is not None:
+        return cast(ReadRuntime, runtime)
+    database = getattr(state, "database", None)
+    if database is None:
+        raise ProblemError(UNAVAILABLE, "Reads need a configured database.")
+    runtime = ReadRuntime.build(cast(Settings, state.settings), database.sessions)
+    setattr(state, _STATE_KEY, runtime)
+    return runtime
+
+
+ReadRuntimeDep = Annotated[ReadRuntime, Depends(get_read_runtime)]
+
+
+async def begin_read(session: AsyncSession, runtime: ReadRuntime) -> None:
+    """Make the session's (new) transaction read-only with the read statement timeout."""
+    await session.execute(text("SET TRANSACTION READ ONLY"))
+    await session.execute(
+        select(func.set_config("statement_timeout", str(runtime.read.statement_timeout_ms), True))
+    )
+
+
+async def read_session(runtime: ReadRuntimeDep) -> AsyncIterator[AsyncSession]:
+    """A session in a read-only transaction, closed after the response."""
+    async with runtime.sessions() as session, session.begin():
+        await begin_read(session, runtime)
+        yield session
+
+
+ReadSessionDep = Annotated[AsyncSession, Depends(read_session)]