UQA Showcase

Overview

These eleven showcase examples demonstrate UQA's most distinctive capabilities. Each example is self-contained and runs with inline data — no external datasets or downloads required.

Knowledge Discovery Engine

examples/showcase/knowledge_discovery.py · Papers 1–3

UQA's core thesis is that posting lists serve as the universal abstraction across all paradigms. This example builds a citation network of 15 landmark ML papers and progressively combines SQL, full-text search, vector similarity, and graph queries — culminating in a single SQL statement that fuses all four.

Single-Paradigm Queries

Each paradigm operates independently through the same posting list algebra:

-- Paradigm 1: SQL (relational filtering and aggregation)
SELECT field, COUNT(*) AS papers, ROUND(AVG(citations), 0) AS avg_cit
FROM papers
GROUP BY field ORDER BY avg_cit DESC;

-- Paradigm 2: Full-Text Search (Bayesian BM25 calibrated P(relevant))
SELECT title, _score FROM papers
WHERE bayesian_match(title, 'attention')
ORDER BY _score DESC;

-- Paradigm 3: Vector Search (cosine similarity nearest neighbors)
SELECT title, field, _score FROM papers
WHERE knn_match(embedding, $1, 5)
ORDER BY _score DESC;

-- Paradigm 4: Graph (PageRank on citation network)
SELECT title, _score FROM pagerank()
ORDER BY _score DESC LIMIT 5;

Multi-Signal Fusion

Because every paradigm produces a posting list, they compose freely through fuse_log_odds — combining signals in calibrated probability space:

-- Two signals: text + vector
SELECT title, _score FROM papers
WHERE fuse_log_odds(
    bayesian_match(title, 'attention'),
    knn_match(embedding, $1, 10)
) ORDER BY _score DESC LIMIT 5;

-- Three signals: text + vector + graph centrality
SELECT title, field, _score FROM papers
WHERE fuse_log_odds(
    bayesian_match(title, 'attention'),
    knn_match(embedding, $1, 10),
    pagerank()
) ORDER BY _score DESC LIMIT 5;

Four-Paradigm Unification

A single SQL statement that combines all four paradigms: Bayesian BM25 (FTS), cosine KNN (vector), PageRank (graph), and a relational filter — all composed through the posting list algebra.

SELECT title, year, field, _score FROM papers
WHERE fuse_log_odds(
    bayesian_match(title, 'attention'),  -- FTS: calibrated P(relevant)
    knn_match(embedding, $1, 10),        -- Vector: semantic similarity
    pagerank()                           -- Graph: citation influence
) AND year >= 2019                       -- SQL: relational filter
ORDER BY _score DESC LIMIT 5;

Cypher Integration

For complex graph patterns beyond what traverse() provides, openCypher queries run inside SQL FROM clauses:

-- Two-hop citation chains: which papers cite papers that cite the Transformer?
SELECT * FROM cypher('citations', $$
    MATCH (a)-[:cites]->(b)-[:cites]->(c)
    RETURN a.title AS paper, b.title AS via, c.title AS root
$$) AS (paper agtype, via agtype, root agtype);

Sample output (truncated):

paper                           | via                             | root
--------------------------------+---------------------------------+----------------------------------
BERT                            | attention is all you need       | neural machine translation by...
LLaMA                           | flash attention fast...         | attention is all you need
InstructGPT                     | GPT-3                           | attention is all you need
DPR                             | BERT                            | attention is all you need

Query Plan

EXPLAIN reveals how the four paradigms merge into a unified operator tree:

FilterOp(field='year')
  LogOddsFusion(alpha=0.5, signals=3)
    ScoreOp(scorer=BayesianBM25Scorer, terms=['attent'], field='title')
      TermOp(term='attention', field='title')
    _CalibratedKNNOperator
    PageRankOperator
  (estimated cost: 166.5)

Each paradigm contributes a posting list to the operator tree. LogOddsFusion combines them in calibrated probability space. The FilterOp intersects the result via Boolean algebra.

Calibration Matters

examples/showcase/calibration_matters.py · Paper 3

BM25 scores are unbounded $[0, +\infty)$, while cosine similarity is bounded $[-1, 1]$. Naive combination (adding raw scores) lets BM25 dominate the ranking regardless of the vector signal. Bayesian BM25 solves this by calibrating both signals into $P(\text{relevant})$ in $[0, 1]$.

The Scale Problem

Raw scores from the same 10 papers, query "attention transformer":

Problem: BM25 scores range 0.7–0.9, cosine ranges -0.1–1.0. Naive addition: BM25 dominates. A non-relevant paper like "language models few-shot" ranks 5th (cosine = 0.98 but BM25 = 0.0), while the relevant "vision transformer" drops to 7th (BM25 = 0.87 but cosine = 0.01). This is Theorem 1.2.2 (Paper 3): Signal Dominance in Naive Combination.

Fusion Strategy Comparison

Four strategies on the same data:

-- Bayesian log-odds fusion (principled)
SELECT title, _score FROM papers
WHERE fuse_log_odds(
    bayesian_match(title, 'attention transformer'),
    knn_match(embedding, $1, 10)
) ORDER BY _score DESC;

-- Probabilistic AND: P(A) * P(B) -- strict intersection
WHERE fuse_prob_and(...);

-- Probabilistic OR: 1 - (1-P(A))*(1-P(B)) -- broad recall
WHERE fuse_prob_or(...);

Calibration Metrics

The example computes ECE (Expected Calibration Error) and Brier score with ground-truth relevance labels, and generates reliability diagrams showing predicted vs actual relevance rates per probability bin:

from uqa.scoring.calibration import CalibrationMetrics

ece = CalibrationMetrics.ece(predictions, labels, n_bins=5)
brier = CalibrationMetrics.brier(predictions, labels)
diagram = CalibrationMetrics.reliability_diagram(predictions, labels, n_bins=5)

# Parameter learning from relevance judgments
learned = engine.learn_scoring_params("papers", "title", "attention", labels)

# Online incremental updates
engine.update_scoring_params("papers", "title", score=0.85, label=1)

A perfectly calibrated model has avg_predicted == avg_actual in every bin. learn_scoring_params optimizes the sigmoid parameters $(\alpha, \beta)$ from labeled data, and update_scoring_params adjusts them incrementally as new feedback arrives.

From Bayes to Neurons

examples/showcase/bayesian_neural.py · Paper 4

Paper 4 proves that when you combine multiple calibrated probability signals through Bayesian inference, the end-to-end computation is a feedforward neural network. This example traces the computation step by step.

Layer-by-Layer Derivation

Input Layer: Raw Scores

Two scoring signals with incompatible scales: BM25 in $[0, +\infty)$, cosine in $[-1, 1]$.

Layer 1: Sigmoid Calibration

Bayesian BM25 applies $P_i = \sigma(\alpha_i s_i - \beta_i)$. This sigmoid is not a design choice — it follows necessarily from the Bernoulli exponential family structure of binary relevance. The natural parameter of $\text{Bernoulli}(p)$ is $\text{logit}(p)$, and the inverse link function is the sigmoid (Paper 4, Theorem 6.3.1).

-- Raw BM25 score (unbounded)
SELECT title, _score FROM papers
WHERE text_match(title, 'attention');

-- Calibrated probability (sigmoid-transformed)
SELECT title, _score FROM papers
WHERE bayesian_match(title, 'attention');

Hidden Layer: Logit Transform

Each calibrated probability is transformed to log-odds space: $\ell_i = \log(P_i / (1 - P_i))$. Log-odds space is where Bayesian updates are naturally linear — this is the hidden layer's nonlinear activation function.

Output Layer: Aggregation + Sigmoid

Log-odds are aggregated linearly with confidence scaling (the $\sqrt{n}$ law):

-- This SQL statement IS a neural network
SELECT title, _score FROM papers
WHERE fuse_log_odds(
    bayesian_match(title, 'attention'),
    knn_match(embedding, $1, 10)
) ORDER BY _score DESC;

When both signals share the same sigmoid calibration (homogeneous case), $\text{logit}(\sigma(x)) = x$ (identity), and the network collapses to logistic regression. When calibrations differ (heterogeneous — the practical case of BM25 + cosine), the logit is a genuine nonlinearity, yielding a true two-layer network (Paper 4, Theorem 5.2.1).

Gating Functions: The Probabilistic Hierarchy

Paper 4 derives three activation functions from three probabilistic questions applied to the same evidence:

The MAP-to-Bayes duality in classical statistics manifests as the ReLU-to-Swish transition in neural activations.

-- Standard fusion (no gating)
WHERE fuse_log_odds(text_match(...), traverse_match(...));

-- ReLU gating: zeroes out negative log-odds (non-evidence)
WHERE fuse_log_odds(text_match(...), traverse_match(...), 'relu');

-- Swish gating: smooth gating, weak signals leak through
WHERE fuse_log_odds(text_match(...), traverse_match(...), 'swish');

-- Attention: context-dependent weights (Logarithmic Opinion Pooling)
WHERE fuse_attention(bayesian_match(...), bayesian_match(...));

-- Depth: multi-layer network via iterated marginalization
WHERE staged_retrieval(
    text_match(title, 'attention'), 6,         -- Layer 1: broad recall
    bayesian_match(abstract, 'attention'), 4,  -- Layer 2: re-rank
    knn_match(embedding, $1, 3), 2             -- Layer 3: final fusion
);

Full Architecture

The complete correspondence between Bayesian inference and neural computation:

+---------------------------------------------------------------+
| INPUT LAYER           raw scores from each paradigm           |
|   text_match(s1)      knn_match(s2)      pagerank(s3)         |
+---------------------------------------------------------------+
                                 |
+---------------------------------------------------------------+
| CALIBRATION           sigmoid: P_i = sigma(a_i*s_i - b_i)     |
|   (Bernoulli exponential family => sigmoid is inevitable)     |
+---------------------------------------------------------------+
                                 |
+---------------------------------------------------------------+
| HIDDEN LAYER          logit: l_i = log(P_i / (1-P_i))         |
|   Optional gating:                                            |
|     none  -> l_i              (standard)                      |
|     ReLU  -> max(0, l_i)      (MAP estimator, sparse prior)   |
|     Swish -> l_i*sigma(l_i)   (Bayes posterior mean)          |
+---------------------------------------------------------------+
                                 |
+---------------------------------------------------------------+
| AGGREGATION           sum(l_i) / n^alpha                      |
|   Uniform:    fuse_log_odds    (equal weights)                |
|   Attention:  fuse_attention   (context-dependent weights)    |
|   Depth:      staged_retrieval (iterated marginalization)     |
+---------------------------------------------------------------+
                                 |
+---------------------------------------------------------------+
| OUTPUT LAYER          sigmoid: P_fused = sigma(aggregated)    |
|   The final P(relevant | all evidence)                        |
+---------------------------------------------------------------+

Deep Fusion: Neural Networks as SQL

Paper 4 (applied) · 4 showcase examples

Paper 4 proved that Bayesian multi-signal fusion IS a neural network. deep_fusion() takes this further — implementing complete deep learning pipelines (ResNet, GNN, CNN, and full classification heads) as composable SQL layer functions over graph-structured data.

ResNet: Hierarchical Signal Layers

deep_fusion_resnet.py

Each layer() adds its fused logits to the running accumulator via a residual connection — mathematically identical to ResNet skip connections: $x^{(k)} = g(x^{(k-1)} + F(x^{(k-1)}))$.

-- Three-layer hierarchy: text -> vector -> graph centrality
SELECT title, _score FROM papers
WHERE deep_fusion(
    layer(bayesian_match(title, 'attention')),      -- Layer 0: text prior
    layer(knn_match(embedding, $1, 10)),            -- Layer 1: vector refinement
    layer(pagerank('papers')),                      -- Layer 2: centrality boost
    gating => 'relu'
) ORDER BY _score DESC;

GNN: Graph Propagation Layers

deep_fusion_gnn.py

propagate() layers spread scores through graph edges — one round of GNN message passing with a logit-space residual. Stacking layers enables multi-hop reasoning.

-- 2-hop message passing through citations
SELECT title, _score FROM papers
WHERE deep_fusion(
    layer(bayesian_match(title, 'attention')),      -- seed scores
    propagate('cites', 'mean'),                     -- 1-hop spread
    propagate('cites', 'mean'),                     -- 2-hop spread
    layer(knn_match(embedding, $1, 10)),            -- vector refinement
    gating => 'relu'
) ORDER BY _score DESC;

CNN: Spatial Convolution

deep_fusion_cnn.py

convolve() performs weighted multi-hop BFS aggregation over graph neighborhoods. On a 4-connected grid, hop 0 = self, hop 1 = 3x3, hop 2 = 5x5 receptive field. Weights are estimated from spatial autocorrelation (MLE, no backpropagation).

-- Stacked convolutions with MLE-estimated weights
SELECT id, _score FROM patches
WHERE deep_fusion(
    layer(knn_match(embedding, $1, 16)),
    convolve('spatial', ARRAY[0.6, 0.4]),          -- 3x3 equivalent
    convolve('spatial', ARRAY[0.6, 0.4]),          -- 5x5 effective field
    gating => 'relu'
) ORDER BY _score DESC;

Full Neural Network Pipeline

deep_fusion_nn.py

The complete deep learning pipeline — from spatial feature extraction through classification — expressed as a single SQL statement:

-- Complete CNN: conv -> pool -> flatten -> dense -> softmax
SELECT id, _score FROM patches
WHERE deep_fusion(
    layer(knn_match(embedding, $1, 16)),                -- 16 nodes
    convolve('spatial', ARRAY[0.6, 0.4]),               -- spatial features
    pool('spatial', 'max', 2),                          -- downsample
    batch_norm(),                                       -- normalize
    dropout(0.3),                                       -- regularize
    flatten(),                                          -- spatial -> 1D
    dense(ARRAY[...], ARRAY[...],
          output_channels => 4, input_channels => 8),   -- project to classes
    softmax(),                                          -- probabilities
    gating => 'relu'
) ORDER BY _score DESC;

The EXPLAIN plan reads like a network architecture diagram:

DeepFusion(layers=8, alpha=0.5, gating='relu')
  Layer 0 (signals=1):
    _CalibratedKNNOperator
  Layer 1 (convolve='spatial', hops=1, weights=[0.6, 0.4]):
  Layer 2 (pool='spatial', method='max', size=2):
  Layer 3 (batch_norm, eps=1e-05):
  Layer 4 (dropout, p=0.3):
  Layer 5 (flatten):
  Layer 6 (dense=8->4):
  Layer 7 (softmax):

Deep Learning: Analytical Training

Paper 4 (training) · 4 showcase examples

Paper 4 proves neural networks emerge from Bayesian inference. deep_learn() takes this to its logical conclusion — training CNN classifiers without backpropagation. Multi-channel convolution kernels serve as Bayesian prior with configurable initialization (Kaiming, orthogonal, Gabor, k-means); ridge regression computes the posterior. global_pool() provides channel-preserving spatial reduction as an alternative to flatten(). Product of Experts (PoE) local learning trains independent expert heads at each stage, combined via logit averaging with shrinkage correction.

MNIST Architecture (28×28 Grayscale)

graph TD
    Input["Input
28 × 28 × 1 — 784-D embedding"]

    subgraph S1["Stage 1"]
        direction LR
        Conv1["Conv2d — 32ch, 3 × 3 Kaiming"] --> ReLU1["ReLU"] --> Pool1["MaxPool2d 2 × 2
→ 14 × 14 × 32"]
    end

    subgraph S2["Stage 2"]
        direction LR
        Conv2["Conv2d — 64ch, 3 × 3 Kaiming"] --> ReLU2["ReLU"] --> Pool2["MaxPool2d 2 × 2
→ 7 × 7 × 64"]
    end

    subgraph Classifier["Classifier"]
        direction LR
        Flat["Flatten
3136-D"] --> Dense["Dense(10) — Ridge Regression
W = (X'X + λI)⁻¹X'Y"] --> Softmax["Softmax
10 classes"]
    end

    Input --> S1 --> S2 --> Classifier
  

Tiny ImageNet Architecture (64×64 RGB)

graph TD
    Input["Input
64 × 64 × 3 — 12288-D embedding"]

    subgraph S1["Stage 1"]
        direction LR
        Conv1["Conv2d — 64ch, 3 × 3 Kaiming"] --> ReLU1["ReLU"] --> Pool1["MaxPool2d 2 × 2
→ 32 × 32 × 64"]
    end

    subgraph S2["Stage 2"]
        direction LR
        Conv2["Conv2d — 128ch, 3 × 3 Kaiming"] --> ReLU2["ReLU"] --> Pool2["MaxPool2d 2 × 2
→ 16 × 16 × 128"]
    end

    subgraph S3["Stage 3"]
        direction LR
        Conv3["Conv2d — 256ch, 3 × 3 Kaiming"] --> ReLU3["ReLU"] --> Pool3["MaxPool2d 2 × 2
→ 8 × 8 × 256"]
    end

    subgraph Classifier["Classifier"]
        direction LR
        Flat["Flatten
16384-D"] --> Dense["Dense(50) — Ridge Regression
W = (X'X + λI)⁻¹X'Y"] --> Softmax["Softmax
50 classes"]
    end

    Input --> S1 --> S2 --> S3 --> Classifier
  

Product of Experts (PoE) Training Pipeline

graph TD
    Data["Training Data
embeddings + labels"] --> Stage1
    Data --> Stage2
    Data --> Stage3
    Data --> Final

    subgraph Stage1["Stage 1: Conv + Pool"]
        C1["Conv2d
(Kaiming prior)"] --> P1["MaxPool2d"]
        P1 --> E1["Expert Head 1
Ridge Regression"]
    end

    subgraph Stage2["Stage 2: Conv + Pool"]
        C2["Conv2d
(Kaiming prior)"] --> P2["MaxPool2d"]
        P2 --> E2["Expert Head 2
Ridge Regression"]
    end

    subgraph Stage3["Stage 3: Conv + Pool"]
        C3["Conv2d
(Kaiming prior)"] --> P3["MaxPool2d"]
        P3 --> E3["Expert Head 3
Ridge Regression"]
    end

    subgraph Final["Final Head"]
        FH["Ridge Regression
on last features"]
    end

    E1 --> PoE["PoE Combination
avg(logits) + α · log(n)"]
    E2 --> PoE
    E3 --> PoE
    FH --> PoE
    PoE --> Pred["Prediction
argmax(softmax(logits))"]
  

MNIST: Handwritten Digit Classification

deep_learn_mnist.py

Full MNIST pipeline: 60,000 training images, 10,000 test images, 28×28 grayscale. Architecture: conv(32ch) → pool(2) → conv(64ch) → pool(2) → flatten → dense(10) → softmax. Achieves 97.89% test accuracy.

-- Step 1: Build spatial grid graph
SELECT * FROM build_grid_graph('mnist_train', 28, 28, 'spatial');

-- Step 2: Train (analytical, no backpropagation)
SELECT deep_learn(
    'mnist_cnn', label, embedding, 'spatial',
    convolve(n_channels => 32),
    pool('max', 2),
    convolve(n_channels => 64),
    pool('max', 2),
    flatten(),
    dense(output_channels => 10),
    softmax(),
    gating => 'relu', lambda => 1.0
) FROM mnist_train;

-- Step 3: Inference via deep_predict()
SELECT id, deep_predict('mnist_cnn', embedding) AS pred
FROM mnist_test;

-- Step 3 (alt): Inference via deep_fusion(model())
SELECT id, _score, class_probs FROM grid_28x28
WHERE deep_fusion(
    model('mnist_cnn', $1),
    gating => 'relu'
) ORDER BY _score DESC;

Tiny ImageNet: RGB Image Classification

deep_learn_tiny_imagenet.py

50-class subset of Tiny ImageNet: 500 train/class (+flip augmentation), 50 val/class, 64×64 RGB. Architecture: conv(64ch) → pool(2) → conv(128ch) → pool(2) → conv(256ch) → pool(2) → flatten → dense(50) → softmax. 3-stage conv+pool: 64 → 32 → 16 → 8 spatial dims, final features 256 × 8 × 8 = 16,384.

-- RGB input: 3 * 64 * 64 = 12288 dimensions per image
SELECT deep_learn(
    'tiny_cnn', label, embedding, 'spatial',
    convolve(n_channels => 64),
    pool('max', 2),
    convolve(n_channels => 128),
    pool('max', 2),
    convolve(n_channels => 256),
    pool('max', 2),
    flatten(),
    dense(output_channels => 50),
    softmax(),
    gating => 'relu', lambda => 500.0
) FROM tiny_train;

Experimental Results

Random baseline for 50 classes: 2%. All results without backpropagation.

Global Pooling & Kernel Initialization

v0.22.0 · Advanced layer options for deep_learn()

Global pooling (global_pool()) provides channel-preserving spatial reduction as an alternative to flatten(). Instead of flattening all spatial positions into a single long vector ($C \times H \times W$), global pooling computes per-channel statistics, reducing spatial dimensions to 1×1 while retaining channel information.

Architecture with Global Pooling

graph TD
    Input["Input
28 × 28 × 1 — 784-D"]

    subgraph S1["Stage 1"]
        direction LR
        Conv1["Conv2d — 32ch
Orthogonal Init"] --> ReLU1["ReLU"] --> Pool1["MaxPool2d 2 × 2
→ 14 × 14 × 32"]
    end

    subgraph GP["Global Pooling"]
        direction LR
        GPL["global_pool('avg_max')
avg: 32-D + max: 32-D = 64-D"]
    end

    subgraph Classifier["Classifier"]
        direction LR
        Dense["Dense(10) — Ridge Regression"] --> Softmax["Softmax
10 classes"]
    end

    Input --> S1 --> GP --> Classifier
  

Dimensionality comparison (32 channels, 14×14 feature map after pooling):

Kernel initialization controls the conv layer's Bayesian prior. Four modes replace or supplement the default random initialization:

SQL: Global Pooling + Orthogonal Init

— Orthogonal kernels + global avg_max pooling
SELECT deep_learn(
    'ortho_gpool', label, embedding, 'spatial',
    convolve(n_channels => 32, init => 'orthogonal'),
    pool('max', 2),
    global_pool('avg_max'),
    dense(output_channels => 10),
    softmax(),
    gating => 'relu', lambda => 1.0
) FROM mnist_train;

— Gabor filter bank + global avg pooling
SELECT deep_learn(
    'gabor_gpool', label, embedding, 'spatial',
    convolve(n_channels => 48, init => 'gabor'),
    pool('max', 2),
    global_pool('avg'),
    dense(output_channels => 10),
    softmax(),
    gating => 'relu', lambda => 1.0
) FROM mnist_train;

— K-means data-dependent kernels
SELECT deep_learn(
    'kmeans_model', label, embedding, 'spatial',
    convolve(n_channels => 64, init => 'kmeans'),
    pool('max', 2),
    flatten(),
    dense(output_channels => 10),
    softmax(),
    gating => 'relu', lambda => 1.0
) FROM mnist_train;

Source Files

python examples/showcase/knowledge_discovery.py
python examples/showcase/calibration_matters.py
python examples/showcase/bayesian_neural.py
python examples/showcase/deep_fusion_resnet.py
python examples/showcase/deep_fusion_gnn.py
python examples/showcase/deep_fusion_cnn.py
python examples/showcase/deep_fusion_nn.py
python examples/showcase/deep_learn_mnist.py
python examples/showcase/deep_learn_tiny_imagenet.py
python examples/showcase/deep_learn_attention.py
python examples/showcase/deep_learn_mnist_pruning.py