rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/hybrid_search.py

@@ -0,0 +1,65 @@
+"""Hybrid search (FR-C.3, FR-Q.1): server-side RRF fusion of the dense and sparse legs.
+
+Given a natural-language query, embed it once with the shared BGE-M3 embedder seam (T19) — dense and
+sparse over the same query text — and hand both query vectors to the store's server-side hybrid
+search (the T13 seam), which fuses the dense `vector.neighbors` leg and the sparse
+`vector.sparseNeighbors` leg by Reciprocal Rank Fusion in ArcadeDB (proven end to end at T14) into one
+ranked candidate list, honoring metadata filters. The fusion runs in the store, so there is no
+cross-store join and no client-side re-ranking here; this is the query-side entry point the compiler
+binds under FR-C.3. Reranking (the precision gate, FR-C.4/T22) consumes this list downstream.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.embedding import Embedder
+from rag_wright.contracts.chunk import MetadataValue
+from rag_wright.store.seam import Store
+
+DEFAULT_K = 10  # candidate-list depth; the eval and the reranker (T22) can override per call
+
+
+class Candidate(BaseModel):
+    """One fused retrieval candidate: enough to cite it (`chunk_id`) and filter by source."""
+
+    model_config = {"frozen": True}
+
+    chunk_id: str
+    source_doc_id: str
+
+
+class HybridSearchResult(BaseModel):
+    """The hybrid-search capability's output: the RRF-ranked candidate list for a query (FR-C.3)."""
+
+    model_config = {"frozen": True}
+
+    query: str
+    candidates: list[Candidate]  # RRF-ranked, best first
+
+
+def hybrid_search(
+    query: str,
+    *,
+    store: Store,
+    embedder: Embedder,
+    k: int = DEFAULT_K,
+    filters: Optional[dict[str, MetadataValue]] = None,
+) -> HybridSearchResult:
+    """Embed the query and return the RRF-fused, filter-honoring top-`k` candidate list.
+
+    The query is embedded once — dense and sparse over the same query text (a query has no
+    summary/full-text split, unlike a chunk) — through the injected `Embedder` seam, then fused
+    server-side by the store. The server's rank order is preserved; this capability does not re-rank.
+    """
+    dense_query = embedder.encode_dense(query)
+    sparse_query = embedder.encode_sparse(query)
+    rows = store.hybrid_search(dense_query, sparse_query, k=k, filters=filters)
+    candidates = [
+        Candidate(chunk_id=row["chunk_id"], source_doc_id=row["source_doc_id"]) for row in rows
+    ]
+    return HybridSearchResult(query=query, candidates=candidates)
+
+

rag_wright/capabilities/invoke.py

@@ -0,0 +1,31 @@
+"""EP-CORE-2 (ADR-0118): the capability implementation resolver -- the adapter-free heart of the ARD client.
+
+A capability's manifest carries an `impl_ref` ("module:attr") pointing to its invoke factory, a
+`(resources, inputs) -> result` callable (model factories ignore `resources`). `capability_impl(name)` reads the
+light index, pulls the `impl_ref`, and imports it LAZILY -- so there is NO central engine-owned adapter dict, and a
+developer registering a capability with an `impl_ref` makes it invocable with zero engine edits. ARD stays
+metadata-only (ADR-0003): the registry holds a string pointer, never a callable; this module does the import.
+
+Lives at the capabilities layer so BOTH the engine API invoker (`api/invoke.py`) and the ingestion pipeline's model
+dispatch (`spans/model_capabilities.py`) resolve the same way."""
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Callable
+
+
+def capability_impl(name: str) -> Callable[..., Any]:
+    """Resolve a capability name to its invoke factory via the manifest `impl_ref`. Raises `KeyError` if the name is
+    unknown to the ARD catalog, `NotImplementedError` if it declares no `impl_ref` (not invokable by name)."""
+    from rag_wright.capabilities.manifests import MANIFEST_SPECS
+
+    spec = MANIFEST_SPECS.get(name)
+    if spec is None:
+        raise KeyError(f"unknown capability {name!r} (not in the ARD catalog)")
+    ref = spec.impl_ref
+    if not ref:
+        raise NotImplementedError(f"capability {name!r} declares no impl_ref (not invokable by name)")
+    module_path, _, attr = ref.partition(":")
+    if not module_path or not attr:
+        raise ValueError(f"capability {name!r} has a malformed impl_ref {ref!r} (expected 'module:attr')")
+    return getattr(import_module(module_path), attr)

rag_wright/capabilities/jev_decision.py

@@ -0,0 +1,38 @@
+"""ADR-0119: a generic Jev typed-decision capability over the OpenRouter Decisions API.
+
+Jev (TypeSafe's "System-1" decision model) returns CALIBRATED typed answers -- a yes/no (`noul`), a `choice` from
+a set, or a `score` -- for a `state` + typed `questions`, with no generated text, in ~70-500 ms. This capability
+is DOMAIN-FREE mechanism: it just forwards a Decisions-API request and returns the typed answers. The compliance
+reference domain uses it for the operative-rule gate + claim_types/actor (ADR-0119, where it reaches the LLM's
+accuracy zero/few-shot, calibrated, at ~$0.00002/call); any domain can use it for routing / tagging / screening.
+
+It is I/O-bound (a network call), so it is an ASYNC `model` capability -- invoke via `api.ainvoke_model` (the sync
+`api.invoke_model` refuses an async impl). Laya (`laya` skill) is the open-weight / on-prem fallback.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+async def jev_decision(resources: Any, inputs: dict) -> dict:  # noqa: ARG001 - API model, store-independent
+    """Invoke a typed-decision model (Jev). `inputs`: `state` (the text/object to judge), `questions` (dict keyed
+    by question id, each `{type: "noul"|"choice"|"score", instructions, criteria}`), optional `model` (a
+    DecisionModelProfile key, default `jev-1.13`). The endpoint, served id, key env and timeout come from the
+    decision-model PROFILE (`models.profiles.decision_profile`, ADR-0119) -- not hardcoded here -- so swapping
+    Jev versions or pointing at an on-prem Laya decisions server is config. Returns the Decisions-API body
+    `{answers: {<id>: {type, noul|choice|score, ...}}, usage: {...}}`. Raises if the key env is unset or the API errors."""
+    import httpx
+
+    from rag_wright.models.profiles import decision_profile
+
+    prof = decision_profile(inputs.get("model"))
+    api_key = os.environ.get(prof.api_key_env)
+    if not api_key:
+        raise RuntimeError(f"jev_decision requires {prof.api_key_env}")
+    body = {"model": prof.served, "state": inputs["state"], "questions": inputs["questions"]}
+    timeout = float(os.environ.get("RAG_JEV_TIMEOUT_S", str(prof.timeout_s)))
+    async with httpx.AsyncClient() as client:
+        r = await client.post(prof.endpoint, headers={"Authorization": f"Bearer {api_key}"}, json=body, timeout=timeout)
+        r.raise_for_status()
+        return r.json()