Defensive publication: hybrid-rag-ranking-graceful-fallback (public prior art, 2026-06-25)

Author: gusitde

.gitignore

@@ -0,0 +1,29 @@
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.npm/
+.pnp.*
+.yarn/
+
+# Build / coverage
+dist/
+build/
+coverage/
+*.tsbuildinfo
+
+# Env / secrets (never commit)
+.env
+.env.*
+*.pem
+*.key
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+*.log

CITATION.cff

@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+message: "If you reference this defensive publication, please cite it as below."
+title: "Hybrid RAG Ranking with Graceful LLM Fallback"
+abstract: >-
+  A technical defensive publication describing a two-stage retrieval ranker in
+  which a deterministic, always-available lexical stage (TF-IDF-style scoring with
+  title and recency boosts) owns the critical path, and an optional language-model
+  re-ranking stage — bounded to a top-K subset and governed by a pre-call budget
+  and an explicit deadline — runs off the critical path and fails open to the
+  deterministic result on any timeout, error, malformed output, invalid permutation,
+  or budget breach, without surfacing that failure to the caller. Published as prior
+  art to keep the technique freely practiceable and unpatentable by others.
+type: report
+authors:
+  - family-names: "Assuncao"
+    given-names: "Gustavo"
+    affiliation: "Gus IT LLC (Florida, USA)"
+version: "1.0"
+date-released: "2026-06-25"
+license: AGPL-3.0-or-later
+keywords:
+  - defensive-publication
+  - prior-art
+  - retrieval-augmented-generation
+  - llm-reranking
+  - fail-open
+  - graceful-degradation

COMMERCIAL-LICENSE.md

@@ -0,0 +1,28 @@
+# Commercial License
+
+This software is **dual-licensed**. Choose ONE:
+
+## Option 1 — Open source (default): GNU AGPL-3.0-or-later
+Use, modify, and distribute under the GNU Affero General Public License, version 3
+or later (see [LICENSE](LICENSE)). Note the AGPL **network-use clause**: if you run a
+modified version to provide a service over a network, you must offer the complete
+corresponding source of your modified version to that service's users.
+
+## Option 2 — Commercial license (alternative)
+If you do not wish to comply with the AGPL — e.g. to embed this software in a
+proprietary or closed-source product or hosted service without disclosing your
+source — obtain a separate commercial license from the copyright holder.
+
+- **Licensor / copyright holder:** Gus IT LLC (Florida, USA)
+- **Contact:** gus@gusit.de
+
+A commercial license provides the same software under negotiated terms that remove
+the AGPL source-disclosure obligations.
+
+## Note on the technical disclosure
+The accompanying technical disclosure (`DEFENSIVE-PUBLICATION.md`) is published as
+public prior art; the **technique** is freely practiceable by anyone. This
+dual-license governs the use of **this source code and its derivatives**, not the
+underlying idea.
+
+Copyright (c) 2026 Gus IT LLC. All rights reserved except as expressly granted above.

DEFENSIVE-PUBLICATION.md

@@ -0,0 +1,10 @@
+Hybrid RAG Ranking with Graceful LLM Fallback
+Copyright (c) 2026 Gus IT LLC (Florida, USA)
+
+This software is dual-licensed under:
+  (1) the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see LICENSE; or
+  (2) a commercial license available from Gus IT LLC — see COMMERCIAL-LICENSE.md (contact gus@gusit.de).
+
+This repository accompanies a defensive technical publication released to establish
+public prior art. The disclosed technique is freely practiceable; the licenses above
+govern this source code and its derivatives.

LICENSE

@@ -0,0 +1,106 @@
+# Hybrid RAG Ranking with Graceful LLM Fallback
+
+> A two-stage retrieval ranker in which a deterministic, always-available lexical
+> stage owns the critical path and an optional language-model re-ranking stage —
+> bounded to a top-K subset and governed by a budget — runs off the critical path
+> and **fails open** to the deterministic result on any timeout, error, or budget
+> breach, without surfacing that failure to the caller.
+
+---
+
+**⚖️ DEFENSIVE PUBLICATION / PRIOR ART**
+
+This repository is a **Technical Defensive Publication**. It is published to
+establish a dated, citable record of prior art so that the technique described
+herein remains free for anyone to practice and **cannot be patented by others**.
+
+| Field | Value |
+|-------|-------|
+| Publisher / Copyright holder | **Gus IT LLC** (Florida, USA) |
+| Author | **Gustavo Assuncao, PhD** |
+| Publication date | **2026-06-25** |
+| Version | **1.0** |
+| Document type | Technical Defensive Publication (public prior art) |
+| Classification | Public |
+| License | AGPL-3.0-or-later (copyleft; commercial license available) |
+| Deposit channel | To be assigned (IP.com / Zenodo / arXiv) — establishes a public, dated, citable prior-art record |
+
+![status](https://img.shields.io/badge/status-published-success)
+![type](https://img.shields.io/badge/type-defensive--publication-blue)
+![license](https://img.shields.io/badge/license-AGPL--3.0-green)
+![prior-art](https://img.shields.io/badge/prior--art-established_2026--06--25-informational)
+
+---
+
+## Abstract
+
+Retrieval-augmented generation (RAG) pipelines increasingly insert a
+language-model (LLM) re-ranking stage between candidate retrieval and answer
+synthesis, because LLM re-rankers materially improve ordering quality. But LLM
+re-rankers are slow, expensive, rate-limited, and occasionally unavailable. The
+naive integration — call the retriever, then *await* the LLM re-ranker, then
+return — promotes the slow, failure-prone stage onto the **critical path**: the
+end-to-end latency, availability, and cost of retrieval all become hostage to the
+LLM provider. A single provider timeout or a tripped spend cap turns a sub-100 ms
+retrieval into a multi-second failure.
+
+This publication describes a hybrid ranking architecture that inverts the
+dependency. A deterministic lexical stage (TF-IDF-style scoring with title and
+recency boosts) is the **critical path** and *always* returns a fully-ordered
+result within a tight latency budget. The LLM re-ranking stage is structurally a
+**non-critical-path enhancement**: it is invoked only on a bounded top-K subset of
+the already-ordered deterministic output, it is governed by a per-call budget and
+time bound, and — the central novelty — on **any** failure (bridge unavailability,
+timeout, malformed output, or budget breach) the system **fails open**, returning
+the deterministic ranking unchanged and *without surfacing the failure to the
+caller*. The contract guarantees a valid, ordered result on every call; the LLM
+can only ever *improve* the ordering, never degrade availability or latency.
+
+The disclosure provides the architecture, the fail-open state machine, the
+top-K/budget cost-bounding mechanics, a data model, a clean-room reference
+implementation, a worked example, security and failure-mode analysis, framework
+mappings, an evaluation methodology, and an enumerated set of inventive claims
+(one independent plus fourteen dependent).
+
+## Why this is published
+
+We believe two-stage retrieval that *fails open from an LLM re-ranker to a
+deterministic ranker* is a robustness pattern that should remain **freely
+practiceable by everyone** — RAG infrastructure authors, search teams, and agent
+builders alike. Rather than seek a patent on the fail-open guarantee, Gus IT LLC
+publishes it defensively. By placing a complete, enabling, dated technical
+description in the public domain under AGPL-3.0-or-later, we create prior art that bars a
+later party from patenting the same technique and asserting it against
+practitioners. The reference implementation is original, clean-room, and
+dependency-light so that anyone can read it, run it, and adopt the pattern.
+
+## Table of Contents
+
+- **[DEFENSIVE-PUBLICATION.md](DEFENSIVE-PUBLICATION.md)** — the full technical
+  whitepaper (architecture, mechanics, data model, claims, evaluation, appendices).
+- **[docs/PRIOR-ART.md](docs/PRIOR-ART.md)** — prior-art landscape and delta table.
+- **[docs/FIGURES.md](docs/FIGURES.md)** — all figures with captions.
+- **[docs/OPEN-SOURCE-APP.md](docs/OPEN-SOURCE-APP.md)** — planned open-source
+  reference app and deployment sketch.
+- **[src/](src/)** — clean-room illustrative reference implementation
+  ([src/README.md](src/README.md)).
+- **[LICENSE](LICENSE)** — AGPL-3.0-or-later.
+- **[NOTICE](NOTICE)** — attribution and defensive-publication statement.
+- **[CITATION.cff](CITATION.cff)** — citation metadata.
+
+## Planned open-source app
+
+This repository is intended to seed a small open-source reference application: a
+self-contained hybrid RAG ranking service that demonstrates the fail-open pattern
+end-to-end, with a pluggable re-ranker adapter and a generic Kubernetes/AKS
+deployment sketch. See **[docs/OPEN-SOURCE-APP.md](docs/OPEN-SOURCE-APP.md)**.
+
+## License & Citation
+
+Licensed under the **GNU Affero General Public License v3.0** — see [LICENSE](LICENSE). The AGPL-3.0-or-later
+express patent grant is intentional for a prior-art release.
+
+To cite this publication, see [CITATION.cff](CITATION.cff). Short form:
+
+> Assuncao, Gustavo (2026). *Hybrid RAG Ranking with Graceful LLM Fallback.*
+> Technical Defensive Publication, v1.0, Gus IT LLC. Published 2026-06-25.

NOTICE

@@ -0,0 +1,124 @@
+# Figures
+
+All figures from [`../DEFENSIVE-PUBLICATION.md`](../DEFENSIVE-PUBLICATION.md),
+collected with captions. They render natively on GitHub via Mermaid.
+
+---
+
+## Figure 1 — System architecture
+
+The base ranker is the only path the caller strictly depends on; everything to the
+right of the gate is best-effort.
+
+```mermaid
+graph TD
+    Q[Query q + candidate set D] --> B[Deterministic Base Ranker<br/>TF-IDF + title/recency boosts]
+    B --> OB[(Ordered base result O_B)]
+    OB --> GATE{Overlay gate:<br/>enabled? &nbsp; budget OK? &nbsp; size > min?}
+    GATE -- no --> RET[Return O_B]
+    GATE -- yes --> TOPK[Select top-K subset D_K]
+    TOPK --> M[LLM Re-ranker M<br/>listwise index ordering]
+    M -- success + valid permutation --> MERGE[Merge: O_M over D_K,<br/>O_B tail preserved]
+    M -- error / timeout / budget / malformed --> FALLBACK[Fail open]
+    MERGE --> RET2[Return merged result]
+    FALLBACK --> RET3[Return O_B silently]
+    RET --> CALLER([Caller])
+    RET2 --> CALLER
+    RET3 --> CALLER
+    M -. failure telemetry .-> METRICS[/Metrics: rerank_attempts,<br/>rerank_fallbacks, reasons/]
+```
+
+---
+
+## Figure 2 — Fail-open state machine
+
+Every edge that is not a clean success funnels to `ReturnBase`, and `ReturnBase`
+never throws.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Base
+    Base --> Gate: O_B ready
+    Gate --> ReturnBase: disabled / too few docs / over budget
+    Gate --> AttemptRerank: enabled & within budget
+    AttemptRerank --> Validate: adapter returned within deadline
+    AttemptRerank --> FailOpen: error / timeout / 429 / empty
+    Validate --> Merge: O_M is a valid permutation of D_K
+    Validate --> FailOpen: malformed / not a permutation
+    Merge --> ReturnMerged
+    FailOpen --> ReturnBase: record reason, do NOT throw
+    ReturnBase --> [*]
+    ReturnMerged --> [*]
+```
+
+---
+
+## Figure 3 — Logical data model
+
+`RERANK_EVENT` is telemetry-only; it never affects the returned `SCORED_DOC` list
+beyond setting `reranked` flags.
+
+```mermaid
+erDiagram
+    QUERY ||--o{ SCORED_DOC : ranks
+    DOCUMENT ||--|| SCORED_DOC : becomes
+    RANK_INVOCATION ||--o{ SCORED_DOC : produces
+    RANK_INVOCATION ||--o| RERANK_EVENT : may_emit
+
+    DOCUMENT {
+        string id
+        string title
+        string content
+        timestamp updated_at
+    }
+    SCORED_DOC {
+        int index "original position in D"
+        float base_score "[0,1] from B"
+        int final_rank "position in returned order"
+        bool reranked "true if in top-K and merge applied"
+    }
+    RANK_INVOCATION {
+        string query
+        int candidate_count "|D|"
+        int top_k "K used"
+        string path "base | merged"
+        int latency_ms
+    }
+    RERANK_EVENT {
+        string outcome "success | fallback"
+        string reason "timeout|error|429|budget|malformed|invalid_perm|empty"
+        int tokens_estimated
+        int deadline_ms
+    }
+```
+
+---
+
+## Figure 4 — Worked-example sequence
+
+Shows both the success merge and the fail-open branch returning `O_B` silently.
+
+```mermaid
+sequenceDiagram
+    participant C as Caller
+    participant R as HybridRanker.rank
+    participant B as BaseRanker
+    participant G as OverlayGate
+    participant M as LLM Adapter
+    C->>R: rank(q, D, opts, adapter)
+    R->>B: baseRank(q, D)
+    B-->>R: O_B = [d3,d7,d1,d9,d5,...]
+    R->>G: gate(enabled, |D|, budget)
+    G-->>R: attempt (within budget)
+    R->>M: rerank(q, topK=[d3,d7,d1,d9,d5], deadline=1500ms)
+    alt success within deadline
+        M-->>R: order [2,0,1,4,3]
+        R->>R: validate permutation ✓
+        R->>R: merge → [d1,d3,d7,d5,d9] ++ tail
+        R-->>C: merged result (path=merged)
+    else timeout / error / 429 / malformed
+        M--xR: failure
+        R->>R: record fallback reason
+        R-->>C: O_B unchanged (path=base), no throw
+    end
+```