-- pg_infer extension installation SQL (version 1.0.0)
--
-- This file captures the complete DDL that CREATE EXTENSION pg_infer executes.
-- It is generated from the extension_sql! macros in the Rust source code and
-- serves as a reference for packaging, auditing, and manual deployment.
--
-- NOTE: In normal usage, pgrx generates and manages extension SQL automatically.
-- This file is provided for:
--   1. Packaging (e.g., .deb/.rpm that install without cargo-pgrx)
--   2. Auditing (review what DDL the extension creates)
--   3. Migration planning (diff between versions)
--
-- Do NOT load this file directly with \i — use CREATE EXTENSION pg_infer.

\echo Use "CREATE EXTENSION pg_infer" to load this file. \quit

-- ==========================================================================
-- Schema & Model Registry (bootstrap_schema)
-- ==========================================================================

CREATE SCHEMA IF NOT EXISTS infer;

-- Model registry.  One row per registered model; the row points at
-- either a local vindex directory (backend = 'local') or a remote
-- larql-server endpoint (backend = 'remote').
CREATE TABLE IF NOT EXISTS infer.models (
    model_name    TEXT PRIMARY KEY,
    vindex_path   TEXT NOT NULL,
    source        TEXT NOT NULL,
    extract_level TEXT NOT NULL DEFAULT 'browse',
    num_layers    INT,
    hidden_size   INT,
    vocab_size    INT,
    backend       TEXT NOT NULL DEFAULT 'local',
    server_url    TEXT,
    registered_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- ==========================================================================
-- SQL Functions (generated by pgrx from #[pg_extern] declarations)
-- ==========================================================================

-- The following functions are created by pgrx during CREATE EXTENSION.
-- They are documented here for reference but not re-declared (pgrx handles it).
--
-- Query functions:
--   walk(prompt text, top int DEFAULT 20, model text DEFAULT NULL)
--       RETURNS TABLE(layer int, feature int, gate_score float8, concept text, also text)
--
--   describe(entity text, threshold float8 DEFAULT NULL, model text DEFAULT NULL)
--       RETURNS TABLE(relation text, target text, gate_score float8, layer int)
--
--   infer(prompt text, top int DEFAULT 5, model text DEFAULT NULL)
--       RETURNS TABLE(token text, probability float8, rank int)
--
--   similar_to(a text, b text, model text DEFAULT NULL) RETURNS float8
--
--   similar_to_many(candidates text[], query text, model text DEFAULT NULL)
--       RETURNS TABLE(candidate text, score float8)
--
--   implies(subject text, object text, model text DEFAULT NULL) RETURNS bool
--
--   describe_layers(entity text, model text DEFAULT NULL, threshold float8 DEFAULT NULL)
--       RETURNS TABLE(layer int, feature int, target text, gate_score float8, also text)
--
--   nearest_to(entity text, layer int, top int DEFAULT 10, model text DEFAULT NULL)
--       RETURNS TABLE(layer int, feature int, gate_score float8, concept text, also text)
--
-- Explain/introspection:
--   infer_explain_walk(prompt text, top int DEFAULT 20, model text DEFAULT NULL)
--       RETURNS TABLE(layer int, band text, feature int, gate_score float8, token text, also text)
--
--   infer_show_layers(model text DEFAULT NULL)
--       RETURNS TABLE(layer int, band text, num_features int)
--
--   infer_show_features(layer int, filter text DEFAULT NULL,
--                       min_score float8 DEFAULT 0.0, lim int DEFAULT 50,
--                       model text DEFAULT NULL)
--       RETURNS TABLE(feature int, token text, score float8, also text)
--
--   infer_show_relations(model text DEFAULT NULL)
--       RETURNS TABLE(relation text, count int, max_score float8, layers text, examples text)
--
--   infer_diff(a text, b text, top int DEFAULT 10, model text DEFAULT NULL)
--       RETURNS TABLE(layer int, feature int, token text, score_a float8, score_b float8, delta float8)
--
-- Model management:
--   infer_create_model(model_name text, source text, extract_level text DEFAULT 'browse')
--       RETURNS text
--
--   infer_create_model_remote(model_name text, server_url text) RETURNS text
--
--   infer_create_model_grid(model_name text, model_id text DEFAULT NULL,
--                           poll_secs int DEFAULT 30)
--       RETURNS text
--
--   infer_create_models_remote(model_names text[], server_url text) RETURNS text
--
--   infer_drop_model(model_name text) RETURNS text
--
--   infer_models()
--       RETURNS TABLE(model_name text, source text, extract_level text,
--                     num_layers int, hidden_size int, vocab_size int,
--                     backend text, server_url text, registered_at timestamptz)
--
--   infer_detect_server() RETURNS text
--
-- Cache/stats:
--   infer_stats(model text DEFAULT NULL)
--       RETURNS TABLE(stat_name text, stat_value text)
--
--   infer_warmup(model_name text, layers integer[] DEFAULT NULL) RETURNS text
--       Prefetches layer pages + loads inference weights on a remote
--       server. NULL layers = every layer the server owns.
--       BREAKING (was: entities text[]) -- larql-server's /v1/warmup has
--       no per-entity activation cache; it ignored the entities body and
--       the reported counts were always zero.
--
--   infer_server_stats(model_name text)
--       RETURNS TABLE(stat_name text, stat_value text)
--
-- Operator support:
--   infer_distance(a text, b text) RETURNS float8
--   infer_similarity(a text, b text) RETURNS float8
--   infer_implies_op(left text, right text) RETURNS bool

-- ==========================================================================
-- Operators (infer_access_method)
-- ==========================================================================

-- Distance operator (lower = more similar).  Used with ORDER BY + LIMIT.
CREATE OPERATOR <~> (
    LEFTARG  = text,
    RIGHTARG = text,
    FUNCTION = infer_distance,
    COMMUTATOR = <~>
);

-- Similarity score operator (higher = more similar).
-- Used with WHERE filters: WHERE col <~ 'query' > 15.0
CREATE OPERATOR <~ (
    LEFTARG  = text,
    RIGHTARG = text,
    FUNCTION = infer_similarity,
    COMMUTATOR = <~
);

-- Semantic implication operator.
-- Usage: SELECT 'Paris' @> 'France';
CREATE OPERATOR @> (
    LEFTARG  = text,
    RIGHTARG = text,
    FUNCTION = infer_implies_op
);

-- Apply high cost to prevent the planner from using these in nested loops.
-- Without this, PG assumes COST=1 and will happily call them millions of times.
ALTER FUNCTION infer_distance(text, text) COST 10000;
ALTER FUNCTION infer_similarity(text, text) COST 10000;
ALTER FUNCTION similar_to(text, text, text) COST 10000;

-- ==========================================================================
-- Access Method (infer_access_method)
-- ==========================================================================

-- Register the AM handler function.
CREATE FUNCTION infer_am_handler(internal) RETURNS index_am_handler
    LANGUAGE c AS 'MODULE_PATHNAME', 'infer_am_handler_wrapper';

-- Create the access method.
CREATE ACCESS METHOD infer TYPE INDEX HANDLER infer_am_handler;

-- Operator family for semantic distance ordering.
CREATE OPERATOR FAMILY infer_ops USING infer;

-- Default operator class for text columns.
CREATE OPERATOR CLASS infer_text_ops DEFAULT FOR TYPE text
    USING infer FAMILY infer_ops AS
        OPERATOR 1 <~> (text, text) FOR ORDER BY float_ops;

-- ==========================================================================
-- Embedding Semantics
-- ==========================================================================
--
-- walk() uses last-token embedding by default (configurable via
-- infer.walk_embed_mode GUC: 'last' or 'average'). This simulates the
-- next-token prediction context — the model's internal representation
-- of what comes next after the prompt.
--
-- describe() and similar_to() use mean-pooling over all token embeddings
-- (without special tokens). This produces a stable entity identity vector
-- that matches regardless of how the entity is phrased or contextualized.
--
-- For single-token entities (e.g., "Paris"), all functions use the same
-- direct embedding lookup, so results are consistent across walk/describe.
--
-- describe_layers() follows the same embedding strategy as describe() but
-- returns all per-layer activations without deduplication.

-- ==========================================================================
-- GUC Parameters (registered in _PG_init, documented here for reference)
-- ==========================================================================
--
-- infer.default_model     TEXT    (default: '')      — model name for single-model deployments
-- infer.data_directory    TEXT    (default: 'infer') — base directory for vindex files
-- infer.max_memory        INT     (default: 8192)    — max RSS in MB before LRU eviction
-- infer.auto_download     BOOL   (default: true)     — auto-download from HuggingFace Hub
-- infer.gate_threshold    REAL   (default: 0.0)      — minimum gate activation to report
-- infer.grid_url          TEXT    (default: '')      — grid discovery endpoint URL
-- infer.grid_poll_interval INT   (default: 30)       — seconds between grid route refreshes
-- infer.log_level         TEXT    (default: 'info')  — tracing filter level
-- infer.describe_top_k    INT    (default: 50)       — max edges from describe()
-- infer.gate_cache_max_layers INT (default: 4)       — max decoded gate layers in LRU