mcp-agentic-pipelines 1.0.1

package/vendors/precis/backend/agents/veri_score.py

@@ -0,0 +1,341 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+import asyncio
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Set
+
+from backend.core.stemming import PrecisStemmer
+from backend.core.tracing import TraceEventType
+
+
+# ── Known stopwords (NLTK minus content-bearing words + Precis custom) ─
+_CONTENT_WORDS_TO_KEEP: Set[str] = {
+    "other", "more", "most", "some", "such", "only", "own", "same",
+    "very", "just", "both", "few", "each", "every", "any", "all",
+    "no", "not", "nor",
+}
+
+def _load_veri_stopwords() -> Set[str]:
+    """NLTK English stopwords minus content-bearing words."""
+    try:
+        from nltk.corpus import stopwords
+        return set(stopwords.words("english")) - _CONTENT_WORDS_TO_KEEP
+    except (ImportError, LookupError, OSError):
+        pass
+    return {
+        "i", "me", "my", "we", "our", "you", "your", "he", "him", "his",
+        "she", "her", "it", "its", "they", "them", "their", "this", "that",
+        "these", "those", "am", "is", "are", "was", "were", "be", "been",
+        "being", "have", "has", "had", "do", "does", "did", "a", "an", "the",
+        "and", "but", "if", "or", "because", "as", "of", "at", "by", "for",
+        "with", "about", "between", "into", "through", "during", "before",
+        "after", "to", "from", "in", "on", "off", "over", "under",
+        "can", "will", "should", "now",
+    }
+
+_STOPWORDS: Set[str] = _load_veri_stopwords() | {
+    # Precis-specific query-structure words
+    "summarize", "summary", "summarise", "explain", "describe",
+    "list", "identify", "compare", "contrast", "discuss", "analyze",
+    "key", "finding", "findings", "detail", "details", "overview",
+    "section", "chapter", "paragraph", "figure", "table", "page",
+    "get", "make", "made", "see", "show", "shown", "find", "found",
+}
+
+
+@dataclass
+class VeriScoreReport:
+    relevancy_score: float = 0.0
+    trustworthiness_score: float = 0.0
+    exhaustivity_score: float = 0.0
+    hallucination_rate: float = 0.0
+    citation_coverage: float = 0.0
+    per_chunk_scores: List[Dict[str, Any]] = field(default_factory=list)
+    flagged_issues: List[str] = field(default_factory=list)
+    evaluation_timestamp: str = ""
+
+
+class VeriScoreEvaluator:
+    """Self-evaluation engine. Scores every Precis output on 5 quality dimensions.
+
+    All scoring methods use Porter-stemmed tokens for consistency with the
+    retrieval layer (NestedHashIndex).  Stopwords are filtered before scoring.
+    """
+
+    def __init__(self) -> None:
+        self.min_relevancy = 0.6
+        self.min_trustworthiness = 0.5
+        self._stemmer = PrecisStemmer()
+
+    # ── Public API ───────────────────────────────────────────────────
+
+    async def evaluate(self, query: str, retrieved_chunks: List[Dict[str, Any]],
+                       generated_response: str, citations: List[Dict[str, Any]],
+                       trace=None) -> VeriScoreReport:
+        """Run all five quality checks **in parallel** and return a VeriScoreReport.
+
+        The five dimensions are fully independent — same inputs, no shared mutable
+        state — so we compute them concurrently via asyncio.gather.
+        """
+        # Launch all five dimension checks + per-chunk scoring concurrently.
+        # Each is a sync CPU method offloaded to a thread so the event loop
+        # stays free for other work (LLM calls, WebSocket streaming, etc.).
+        (rel, trust, exh, hall,
+         sentence_count, per_chunk) = await asyncio.gather(
+            asyncio.to_thread(self._compute_relevancy, query, retrieved_chunks),
+            asyncio.to_thread(self._compute_trustworthiness, retrieved_chunks),
+            asyncio.to_thread(self._compute_exhaustivity, query, retrieved_chunks),
+            asyncio.to_thread(self._compute_hallucination_rate, generated_response, retrieved_chunks),
+            asyncio.to_thread(self._count_sentences, generated_response),
+            asyncio.to_thread(self._score_per_chunk, query, retrieved_chunks),
+        )
+
+        cit_cov = min(len(citations) / max(1, sentence_count), 1.0)
+
+        # Flagged issues depend on the computed scores — run after gather
+        flagged = self._collect_flagged_issues(rel, trust, exh, hall, cit_cov, per_chunk)
+
+        report = VeriScoreReport(
+            relevancy_score=rel,
+            trustworthiness_score=trust,
+            exhaustivity_score=exh,
+            hallucination_rate=hall,
+            citation_coverage=cit_cov,
+            per_chunk_scores=per_chunk,
+            flagged_issues=flagged,
+            evaluation_timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+        if trace:
+            trace.event(
+                TraceEventType.EVALUATION_COMPLETED,
+                agent_name="VeriScore",
+                message=f"R:{rel:.2f} T:{trust:.2f} H:{hall:.2f}",
+                data={
+                    "relevancy": rel,
+                    "trust": trust,
+                    "hallucination": hall,
+                    "exhaustivity": exh,
+                    "citation_coverage": cit_cov,
+                },
+            )
+        return report
+
+    # ── Dimension 1: Relevancy ───────────────────────────────────────
+
+    def _compute_relevancy(self, query: str, chunks: List[Dict]) -> float:
+        """Average Jaccard similarity between stemmed query tokens and each chunk.
+
+        Uses the same PrecisStemmer as the retrieval layer so that "running"
+        and "runs" are recognised as the same concept.
+        """
+        if not chunks:
+            return 0.0
+        query_stems = self._stem_set(query)
+        if not query_stems:
+            return 0.0
+        scores: List[float] = []
+        for c in chunks:
+            chunk_stems = self._stem_set(c.get("text", ""))
+            if not chunk_stems:
+                scores.append(0.0)
+                continue
+            inter = len(query_stems & chunk_stems)
+            union = len(query_stems | chunk_stems)
+            scores.append(inter / union if union else 0.0)
+        return sum(scores) / len(scores)
+
+    # ── Dimension 2: Trustworthiness ─────────────────────────────────
+
+    def _compute_trustworthiness(self, chunks: List[Dict]) -> float:
+        """Score source reliability from chunk metadata.
+
+        Returns 0.0 when there are no chunks (no evidence = no trust),
+        rather than a misleading default of 0.5.
+        """
+        if not chunks:
+            return 0.0  # ← was 0.5 — no evidence means no trust
+        scores: List[float] = []
+        for c in chunks:
+            score = 0.5  # Neutral base
+            text = c.get("text", "")
+            if len(text) > 100:
+                score += 0.2
+            elif len(text) > 30:
+                score += 0.1
+            # Has a source document = verifiable
+            if c.get("source"):
+                score += 0.15
+            # Match quality
+            mt = c.get("match_type", "")
+            if mt == "exact":
+                score += 0.15
+            elif mt == "subset":
+                score += 0.10
+            elif mt == "semantic":
+                score += 0.05  # semantic matches are fuzzier → lower bonus
+            # Structural signals (preserved from MultiToken)
+            if c.get("is_title") or c.get("is_header"):
+                score += 0.10
+            if c.get("token_type") == "contextual":
+                score += 0.05
+            scores.append(min(score, 1.0))
+        return sum(scores) / len(scores)
+
+    # ── Dimension 3: Exhaustivity ────────────────────────────────────
+
+    def _compute_exhaustivity(self, query: str, chunks: List[Dict]) -> float:
+        """Fraction of stemmed query tokens that appear in at least one chunk.
+
+        Uses set intersection (word-boundary) rather than naive substring
+        matching to avoid false positives (e.g. "in" matching "interesting").
+        """
+        if not chunks:
+            return 0.0
+        query_stems = self._stem_set(query)
+        if not query_stems:
+            return 1.0  # Query had only stopwords → fully covered
+        # Build the union of all stemmed tokens across all chunks
+        all_stems: Set[str] = set()
+        for c in chunks:
+            all_stems |= self._stem_set(c.get("text", ""))
+        covered = len(query_stems & all_stems)
+        return covered / len(query_stems)
+
+    # ── Dimension 4: Hallucination Rate ──────────────────────────────
+
+    def _compute_hallucination_rate(self, response: str, chunks: List[Dict]) -> float:
+        """Proportion of response sentences whose *content words* are not
+        attested in any retrieved source chunk.
+
+        Uses nltk-style sentence splitting (robust against abbreviations,
+        decimal numbers, and bullet lists) and Porter-stemmed token matching
+        for consistency with the retrieval layer.
+
+        Returns 0.0 when:
+          - Response is empty
+          - No source evidence is available (can't assess)
+          - Response has no substantive sentences (< 20 chars)
+        """
+        if not response.strip():
+            return 0.0
+
+        # Build evidence: union of all stemmed tokens from source chunks ONLY.
+        # IMPORTANT: do NOT include the synthesis/generated text here —
+        # otherwise you're comparing the response against itself.
+        evidence_stems: Set[str] = set()
+        for c in chunks:
+            evidence_stems |= self._stem_set(c.get("text", ""))
+
+        if not evidence_stems:
+            return 0.0  # No evidence → can't assess
+
+        # Split into sentences (handles ., ?, !, abbreviations, decimals)
+        sentences = self._split_sentences(response)
+        substantive = [s for s in sentences if len(s.strip()) > 20]
+        if not substantive:
+            return 0.0
+
+        unsupported = 0
+        for sent in substantive:
+            sent_stems = self._stem_set(sent)
+            # Filter to content words only (len > 4 to avoid noise)
+            content_words = {s for s in sent_stems if len(s) > 4}
+            if not content_words:
+                continue  # Skip sentences with only short/stop words
+            # A sentence is "supported" if at least ONE content word
+            # appears in the evidence
+            if not (content_words & evidence_stems):
+                unsupported += 1
+
+        return unsupported / len(substantive) if substantive else 0.0
+
+    # ── Helpers ──────────────────────────────────────────────────────
+
+    def _stem_set(self, text: str) -> Set[str]:
+        """Stem every word in *text*, filtering stopwords and empty results.
+
+        Returns a set of stemmed tokens for fast intersection / union ops.
+        """
+        if not text or not text.strip():
+            return set()
+        words = text.lower().split()
+        stems = self._stemmer.stem_tokens(words)
+        return {s for s in stems if s and s not in _STOPWORDS}
+
+    @staticmethod
+    def _split_sentences(text: str) -> List[str]:
+        """Split *text* into sentences, robust against abbreviations and decimals.
+
+        Falls back to simple split if nltk is unavailable.
+        """
+        try:
+            from nltk.tokenize import sent_tokenize
+            return sent_tokenize(text)
+        except (ImportError, LookupError):
+            pass
+        # Fallback: split on sentence-ending punctuation followed by space + capital
+        return [s.strip() for s in re.split(r'(?<=[.!?])\s+(?=[A-Z])', text) if s.strip()]
+
+    @staticmethod
+    def _count_sentences(text: str) -> int:
+        """Count sentences in *text*. Used for citation-coverage denominator."""
+        try:
+            from nltk.tokenize import sent_tokenize
+            return len(sent_tokenize(text))
+        except (ImportError, LookupError):
+            pass
+        return max(1, len(re.findall(r'[.!?]\s', text)) + 1)
+
+    def _score_per_chunk(self, query: str, chunks: List[Dict]) -> List[Dict[str, Any]]:
+        """Score each chunk individually and return a list of per-chunk reports."""
+        query_stems = self._stem_set(query)
+        per_chunk: List[Dict[str, Any]] = []
+        for c in chunks:
+            text = c.get("text", "")
+            chunk_stems = self._stem_set(text)
+            inter = len(query_stems & chunk_stems)
+            union = len(query_stems | chunk_stems)
+            jaccard = inter / union if union else 0.0
+            per_chunk.append({
+                "text_preview": text[:120],
+                "source": c.get("source", ""),
+                "page": c.get("page", 1),
+                "match_type": c.get("match_type", ""),
+                "jaccard": round(jaccard, 3),
+                "char_length": len(text),
+            })
+        return per_chunk
+
+    def _collect_flagged_issues(
+        self,
+        rel: float, trust: float, exh: float, hall: float,
+        cit_cov: float, per_chunk: List[Dict],
+    ) -> List[str]:
+        """Aggregate issues across all quality dimensions into a human-readable list."""
+        issues: List[str] = []
+        if rel < self.min_relevancy:
+            issues.append(f"Low relevancy ({rel:.2f} < {self.min_relevancy}) — "
+                          "query terms not well covered by retrieved chunks")
+        if trust < self.min_trustworthiness:
+            issues.append(f"Low trustworthiness ({trust:.2f} < {self.min_trustworthiness}) — "
+                          "sources may be unreliable or too short")
+        if exh < 0.5:
+            issues.append(f"Low exhaustivity ({exh:.2f}) — "
+                          "many query terms not found in any chunk")
+        if hall > 0.3:
+            issues.append(f"High hallucination rate ({hall:.0%} > 30%) — "
+                          f"many response claims are not supported by source evidence")
+        if hall > 0.1:
+            issues.append(f"Elevated hallucination rate ({hall:.0%}) — review recommended")
+        if cit_cov < 0.2:
+            issues.append(f"Low citation coverage ({cit_cov:.0%}) — "
+                          "few sources cited relative to response length")
+        # Per-chunk issues
+        zero_jaccard = [c for c in per_chunk if c.get("jaccard", 0) == 0.0]
+        if zero_jaccard and len(zero_jaccard) == len(per_chunk):
+            issues.append("All chunks have zero Jaccard overlap with query — "
+                          "retrieval may have returned irrelevant content")
+        return issues

package/vendors/precis/backend/agents/work_order_extractor.py

@@ -0,0 +1,205 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+
+Extracts structured fields from semi-structured work orders without OCR training,
+without ML models, without vector databases. Uses regex patterns + stemming for
+field label detection and value extraction.
+
+Common aviation work order fields:
+  Tail Number, Work Order #, Date, Aircraft Model, Part Number, Serial Number,
+  Mechanic ID, Station, Work Performed, Hours, AD/SB Compliance, Inspector Stamp
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+
+@dataclass
+class ExtractedField:
+    field_name: str          # e.g., "tail_number"
+    raw_label: str           # e.g., "Tail #:", "REG:", "A/C REG NO"
+    value: str               # e.g., "N737AG"
+    confidence: float        # 0.0 - 1.0
+    page: int
+    line_number: int
+    context: str = ""        # surrounding text for verification
+
+
+@dataclass
+class WorkOrder:
+    """Structured work order record extracted from a document."""
+    source_file: str
+    tail_number: Optional[str] = None
+    work_order_number: Optional[str] = None
+    date: Optional[str] = None
+    aircraft_model: Optional[str] = None
+    part_numbers: List[str] = field(default_factory=list)
+    part_descriptions: List[str] = field(default_factory=list)
+    serial_numbers: List[str] = field(default_factory=list)
+    mechanic_id: Optional[str] = None
+    station: Optional[str] = None
+    work_performed: Optional[str] = None
+    hours_worked: Optional[str] = None
+    ad_sb_references: List[str] = field(default_factory=list)
+    inspector_stamp: Optional[str] = None
+    extracted_fields: List[ExtractedField] = field(default_factory=list)
+    raw_text_snippet: str = ""
+
+
+class WorkOrderExtractor:
+    """Extracts structured aviation work order fields using token-pattern matching."""
+
+    # Field label patterns — key is the canonical field name, value is list of regex patterns
+    FIELD_PATTERNS: Dict[str, List[str]] = {
+        "tail_number": [
+            r"(?:tail|a/?c|aircraft|registration|reg|n-?number)[\s#:.-]*([\s]*[nN]\d{1,6}[a-zA-Z]{0,2})",
+            r"(?:tail|a/?c|aircraft|registration|reg)[\s#:.-]*([\s]*\d{1,6}[a-zA-Z]{0,2})",
+            r"\b([nN]\d{1,6}[a-zA-Z]{0,2})\b",
+        ],
+        "work_order_number": [
+            r"(?:wo|w/?o|work\s*order|job\s*card|task\s*order)[\s#:.-]*([\s]*[a-zA-Z0-9]{4,20})",
+            r"\b(?:WO|W/O)\s*[:#.-]*\s*([a-zA-Z0-9]{4,20})",
+        ],
+        "date": [
+            r"(?:date|dated|performed|completed)[\s:.-]*([\s]*\d{1,2}[/-]\d{1,2}[/-]\d{2,4})",
+            r"(?:date|dated)[\s:.-]*([\s]*\d{4}-\d{2}-\d{2})",
+            r"(?:date|dated)[\s:.-]*([\s]*(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2},?\s*\d{4})",
+        ],
+        "aircraft_model": [
+            r"(?:model|a/?c\s*type|aircraft\s*type)[\s:.-]*([\s]*(?:B|b)(?:7[3-9]\d|7[3-9]\d[-\s]*[a-zA-Z0-9]{0,6}))",
+            r"(?:model|a/?c\s*type|aircraft\s*type)[\s:.-]*([\s]*(?:A|a)(?:3[12]\d|3[12]\d[-\s]*[a-zA-Z0-9]{0,4}))",
+            r"(?:model|a/?c\s*type|aircraft\s*type)[\s:.-]*([\s]*[a-zA-Z]{1,4}[-\s]*\d{2,4}[a-zA-Z0-9]{0,4})",
+        ],
+        "part_number": [
+            r"(?:p/?n|part\s*(?:no|number|#)|p/n)[\s:.-]*([\s]*[a-zA-Z0-9]{3,30})",
+            r"\b([a-zA-Z]{2,6}\d{3,10}[a-zA-Z]{0,4})\b",
+            r"\b([a-zA-Z]{1,3}\d{5,12})\b",
+        ],
+        "serial_number": [
+            r"(?:s/?n|s/n|serial\s*(?:no|number|#))[\s:.-]*([\s]*[a-zA-Z0-9]{3,30})",
+            r"\b(?:SN|S/N)\s*[:#.-]*\s*([a-zA-Z0-9]{3,30})",
+        ],
+        "mechanic_id": [
+            r"(?:mechanic|tech|technician|a&p|a/?p|inspector|performed\s*by)[\s:.-]*([\s]*[a-zA-Z0-9]{2,20})",
+            r"(?:mechanic|tech)[\s:.-]*\#?\s*([a-zA-Z]{1,3}\d{2,8})",
+        ],
+        "station": [
+            r"(?:station|location|facility|base|gate)[\s:.-]*([\s]*[a-zA-Z]{3,6})",
+            r"\b(?:ATL|DFW|ORD|LAX|JFK|MIA|SEA|SFO|DEN|IAH|MCO|BOS|EWR|PHX|MSP|DTW|CLT|LAS|HNL)\b",
+        ],
+        "hours_worked": [
+            r"(?:hours|man[-\s]*hours|labor\s*hrs|labor\s*hours)[\s:.-]*([\s]*\d+\.?\d*)",
+            r"(?:total\s*hrs|total\s*hours)[\s:.-]*([\s]*\d+\.?\d*)",
+        ],
+        "ad_sb_reference": [
+            r"\b(AD\s*\d{4}[-\s]*\d{2}[-\s]*\d{2,4})\b",
+            r"\b(SB\s*[a-zA-Z0-9]{2,6}[-\s]*\d{2,5})\b",
+            r"(?:airworthiness\s*directive|a\.?d\.?|service\s*bulletin|s\.?b\.?)[\s:.-]*([a-zA-Z0-9]{4,20})",
+        ],
+        "inspector_stamp": [
+            r"(?:inspector|inspected\s*by|stamp|signed\s*by|approved\s*by)[\s:.-]*([\s]*[a-zA-Z\s]{3,30})",
+            r"(?:RII|R\.?I\.?I\.?|buy\s*back)[\s:.-]*([\s]*[a-zA-Z]{2,20})",
+        ],
+        "work_performed": [
+            r"(?:work\s*performed|description|task|action\s*taken|corrective\s*action)[\s:.-]*([\s]*[a-zA-Z0-9\s,;()]{20,500})",
+        ],
+    }
+
+    def __init__(self) -> None:
+        self._compiled_patterns: Dict[str, List[re.Pattern]] = {}
+        for field_name, patterns in self.FIELD_PATTERNS.items():
+            self._compiled_patterns[field_name] = [re.compile(p, re.IGNORECASE) for p in patterns]
+
+    def extract(self, text: str, source_file: str = "unknown") -> WorkOrder:
+        """Extract all known fields from work order text. Returns structured WorkOrder."""
+        wo = WorkOrder(source_file=source_file)
+        lines = text.split("\n")
+
+        for line_num, line in enumerate(lines):
+            for field_name, patterns in self._compiled_patterns.items():
+                for pattern in patterns:
+                    match = pattern.search(line)
+                    if match:
+                        value = match.group(1).strip() if match.groups() else match.group(0).strip()
+                        # Skip if value is too short or looks like a false positive
+                        if len(value) < 2:
+                            continue
+                        if field_name == "tail_number" and not self._looks_like_tail(value):
+                            continue
+                        if field_name == "part_number" and len(value) < 4:
+                            continue
+
+                        field = ExtractedField(
+                            field_name=field_name,
+                            raw_label=match.group(0)[:50],
+                            value=value,
+                            confidence=self._confidence(field_name, value),
+                            page=1,
+                            line_number=line_num,
+                            context=self._get_context(lines, line_num),
+                        )
+                        wo.extracted_fields.append(field)
+
+                        # Populate the structured fields
+                        self._assign_field(wo, field_name, value)
+
+        # Capture raw text for the "work performed" field if not explicitly extracted
+        if not wo.work_performed:
+            # Take the longest paragraph as potential work description
+            paragraphs = [p.strip() for p in text.split("\n\n") if len(p.strip()) > 50]
+            if paragraphs:
+                wo.work_performed = max(paragraphs, key=len)[:500]
+
+        return wo
+
+    def _looks_like_tail(self, value: str) -> bool:
+        """Check if a value looks like an N-number."""
+        # N-number: N followed by 1-5 digits, optionally 1-2 letters
+        return bool(re.match(r'^[nN]\d{1,5}[a-zA-Z]{0,2}$', value.strip()))
+
+    def _confidence(self, field_name: str, value: str) -> float:
+        """Heuristic confidence score based on value quality."""
+        base = 0.7
+        if len(value) > 20:
+            base -= 0.2  # Too long, might be grabbing extra text
+        if len(value) < 3:
+            base -= 0.3
+        if field_name == "tail_number" and self._looks_like_tail(value):
+            base = 0.95  # High confidence for valid N-numbers
+        if field_name == "date" and re.search(r'\d{1,2}[/-]\d{1,2}[/-]\d{2,4}', value):
+            base = 0.90
+        return min(max(base, 0.3), 1.0)
+
+    def _get_context(self, lines: List[str], line_num: int, window: int = 1) -> str:
+        """Get surrounding lines for context."""
+        start = max(0, line_num - window)
+        end = min(len(lines), line_num + window + 1)
+        return " | ".join(lines[start:end])
+
+    def _assign_field(self, wo: WorkOrder, field_name: str, value: str) -> None:
+        """Assign extracted value to the structured WorkOrder."""
+        if field_name == "tail_number" and not wo.tail_number:
+            wo.tail_number = value
+        elif field_name == "work_order_number" and not wo.work_order_number:
+            wo.work_order_number = value
+        elif field_name == "date" and not wo.date:
+            wo.date = value
+        elif field_name == "aircraft_model" and not wo.aircraft_model:
+            wo.aircraft_model = value
+        elif field_name == "part_number" and value not in wo.part_numbers:
+            wo.part_numbers.append(value)
+        elif field_name == "serial_number" and value not in wo.serial_numbers:
+            wo.serial_numbers.append(value)
+        elif field_name == "mechanic_id" and not wo.mechanic_id:
+            wo.mechanic_id = value
+        elif field_name == "station" and not wo.station:
+            wo.station = value
+        elif field_name == "work_performed" and not wo.work_performed:
+            wo.work_performed = value[:500]
+        elif field_name == "hours_worked" and not wo.hours_worked:
+            wo.hours_worked = value
+        elif field_name == "ad_sb_reference" and value not in wo.ad_sb_references:
+            wo.ad_sb_references.append(value)
+        elif field_name == "inspector_stamp" and not wo.inspector_stamp:
+            wo.inspector_stamp = value

package/vendors/precis/backend/api/__init__.py

@@ -0,0 +1,3 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================

package/vendors/precis/backend/api/routes/__init__.py

@@ -0,0 +1,3 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================

package/vendors/precis/backend/config.py

@@ -0,0 +1,88 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================
+# Centralized configuration loaded from environment variables and .env file.
+# All settings are typed and validated by Pydantic at startup.
+#
+# Usage:
+#   from backend.config import settings
+#   api_key = settings.OPENAI_API_KEY  # Auto-loaded from .env
+#
+# Related:
+#   .env.example  — Template with all available settings
+#   docker-compose.yml — Passes env vars to containers
+# =============================================================================
+
+from typing import Optional, List
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """
+    Precis application settings.
+
+    All fields are automatically loaded from environment variables
+    or the .env file. Pydantic validates types at startup — if a required
+    field is missing or has the wrong type, the app fails fast with a clear error.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",  # Ignore unknown env vars (don't crash)
+    )
+
+    # --- Application ---
+    APP_NAME: str = "Precis"
+    APP_VERSION: str = "1.0.0"
+    ENVIRONMENT: str = "development"  # development | staging | production
+    LOG_LEVEL: str = "INFO"           # DEBUG | INFO | WARNING | ERROR
+
+    # --- Database ---
+    DATABASE_URL: str = "sqlite:///data/app.db"
+
+    # --- Redis (Optional) ---
+    REDIS_URL: Optional[str] = None
+
+    # --- External LLM Providers ---
+    OPENAI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+    GOOGLE_API_KEY: Optional[str] = None
+    DEEPSEEK_API_KEY: Optional[str] = None
+
+    # --- Local LLM (Ollama) ---
+    OLLAMA_BASE_URL: str = "http://localhost:11434"
+    OLLAMA_DEFAULT_MODEL: str = "llama3"
+
+    # --- Default LLM Provider ---
+    DEFAULT_LLM_PROVIDER: str = "deepseek"  # deepseek | openai | anthropic | google | ollama
+
+    # --- RBF Predictor Hyperparameters ---
+    # See: backend/agents/radial_interpol.py for usage
+    # See: Alt_DNN.pdf Theorem 2.1 for mathematical foundation
+    RBF_TAU: float = 500.0    # Sharpness — higher τ → more exact interpolation at training points
+    RBF_GAMMA: float = 1.0    # Kernel width — controls influence radius of each training node
+
+    # --- NoGAN Synthesizer Defaults ---
+    # See: backend/agents/dist_free_synth.py for usage
+    NOGAN_DEFAULT_BINS: int = 50
+    NOGAN_MODE: str = "random_counts"  # random_counts | fixed_counts
+
+    # --- Anomaly Detection Thresholds ---
+    # See: backend/agents/stat_anomaly.py for usage
+    ANOMALY_MULTI_ENTITY_THRESHOLD: int = 50
+    ANOMALY_SPIKE_SIGMA: float = 3.0
+
+    # --- Evaluation Thresholds ---
+    # See: backend/agents/veri_score.py for usage
+    EVAL_MIN_RELEVANCY: float = 0.6
+    EVAL_MIN_TRUSTWORTHINESS: float = 0.5
+
+    # --- Security ---
+    CORS_ORIGINS: str = "http://localhost:3000"
+    MAX_UPLOAD_SIZE_MB: int = 50
+
+
+# Global settings instance — import this everywhere
+settings = Settings()

package/vendors/precis/backend/core/__init__.py

@@ -0,0 +1,13 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================
+# backend/core/ — Low-level utilities used across all agents.
+# These are pure functions with no external dependencies (other than NLTK/NumPy).
+#
+# Modules:
+#   stemming.py   — NLTK-based stemmer for multi-token normalization
+#   multitoken.py — MultiToken extraction from parsed documents
+#   hashing.py    — Nested hash utilities for O(1) lookup
+#   pmi.py        — Pointwise Mutual Information for relevancy scoring
+#   metrics.py    — GenAI evaluation metrics (relevancy, trust, exhaustivity)
+# =============================================================================