evalvault 1.74.0__py3-none-any.whl → 1.76.0__py3-none-any.whl

evalvault/adapters/outbound/domain_memory/postgres_domain_memory_schema.sql

@@ -0,0 +1,177 @@
+-- EvalVault Domain Memory Schema (PostgreSQL)
+-- Based on "Memory in the Age of AI Agents: A Survey" framework
+-- Forms: Flat (Phase 1), Planar/Hierarchical (Phase 2-3)
+-- Functions: Factual, Experiential, Working layers
+-- Dynamics: Formation, Evolution, Retrieval strategies
+
+-- =========================================================================
+-- Factual Layer - 검증된 도메인 사실 (SPO 트리플)
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS factual_facts (
+    fact_id TEXT PRIMARY KEY,
+    subject TEXT NOT NULL,           -- 엔티티 이름
+    predicate TEXT NOT NULL,         -- 관계 타입
+    object TEXT NOT NULL,            -- 대상 엔티티
+    language TEXT DEFAULT 'ko',      -- 언어 코드 (ko, en)
+    domain TEXT DEFAULT 'default',   -- 도메인 (insurance, legal, medical)
+    fact_type TEXT DEFAULT 'verified', -- verified, inferred, contradictory
+    verification_score REAL DEFAULT 1.0, -- 0.0-1.0
+    verification_count INTEGER DEFAULT 1,
+    source_document_ids TEXT,        -- JSON array of document IDs
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    last_verified TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    abstraction_level INTEGER DEFAULT 0
+);
+
+-- 검색 최적화를 위한 인덱스
+CREATE INDEX IF NOT EXISTS idx_facts_domain_lang ON factual_facts(domain, language);
+CREATE INDEX IF NOT EXISTS idx_facts_subject ON factual_facts(subject);
+CREATE INDEX IF NOT EXISTS idx_facts_predicate ON factual_facts(predicate);
+CREATE INDEX IF NOT EXISTS idx_facts_object ON factual_facts(object);
+CREATE INDEX IF NOT EXISTS idx_facts_triple ON factual_facts(subject, predicate, object);
+CREATE INDEX IF NOT EXISTS idx_facts_verification_score ON factual_facts(verification_score DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_last_verified ON factual_facts(last_verified DESC);
+
+-- GIN indexes for text search (ILIKE-based)
+CREATE INDEX IF NOT EXISTS idx_facts_subject_gin ON factual_facts USING GIN (to_tsvector('english', subject));
+CREATE INDEX IF NOT EXISTS idx_facts_predicate_gin ON factual_facts USING GIN (to_tsvector('english', predicate));
+CREATE INDEX IF NOT EXISTS idx_facts_object_gin ON factual_facts USING GIN (to_tsvector('english', object));
+
+-- =========================================================================
+-- Experiential Layer - 평가에서 학습된 패턴
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS learning_memories (
+    learning_id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,            -- 원본 평가 run ID
+    domain TEXT DEFAULT 'default',
+    language TEXT DEFAULT 'ko',
+    entity_type_reliability TEXT,    -- JSON: {entity_type: reliability_score}
+    relation_type_reliability TEXT,  -- JSON: {relation_type: reliability_score}
+    failed_patterns TEXT,            -- JSON array of failed patterns
+    successful_patterns TEXT,        -- JSON array of successful patterns
+    faithfulness_by_entity_type TEXT, -- JSON: {entity_type: faithfulness_score}
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_learnings_domain_lang ON learning_memories(domain, language);
+CREATE INDEX IF NOT EXISTS idx_learnings_run_id ON learning_memories(run_id);
+CREATE INDEX IF NOT EXISTS idx_learnings_timestamp ON learning_memories(timestamp DESC);
+
+-- =========================================================================
+-- Behavior Layer - Metacognitive Reuse (재사용 가능한 행동)
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS behavior_entries (
+    behavior_id TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    trigger_pattern TEXT,            -- 트리거 조건 (regex 또는 키워드)
+    action_sequence TEXT,            -- JSON array of action steps
+    success_rate REAL DEFAULT 0.0,   -- 역사적 성공률
+    token_savings INTEGER DEFAULT 0, -- 절감되는 토큰 수
+    applicable_languages TEXT DEFAULT '["ko", "en"]', -- JSON array
+    domain TEXT DEFAULT 'default',
+    last_used TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    use_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_behaviors_domain ON behavior_entries(domain);
+CREATE INDEX IF NOT EXISTS idx_behaviors_success_rate ON behavior_entries(success_rate DESC);
+CREATE INDEX IF NOT EXISTS idx_behaviors_use_count ON behavior_entries(use_count DESC);
+CREATE INDEX IF NOT EXISTS idx_behaviors_last_used ON behavior_entries(last_used DESC);
+
+-- GIN indexes for behavior search
+CREATE INDEX IF NOT EXISTS idx_behaviors_description_gin ON behavior_entries USING GIN (to_tsvector('english', description));
+CREATE INDEX IF NOT EXISTS idx_behaviors_trigger_gin ON behavior_entries USING GIN (to_tsvector('english', trigger_pattern));
+
+-- =========================================================================
+-- Working Layer - 현재 세션의 활성 컨텍스트
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS memory_contexts (
+    session_id TEXT PRIMARY KEY,
+    domain TEXT DEFAULT 'default',
+    language TEXT DEFAULT 'ko',
+    active_entities TEXT,            -- JSON array of entity names
+    entity_type_distribution TEXT,   -- JSON: {entity_type: count}
+    current_quality_metrics TEXT,    -- JSON: {metric_name: value}
+    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_contexts_domain ON memory_contexts(domain);
+CREATE INDEX IF NOT EXISTS idx_contexts_updated_at ON memory_contexts(updated_at DESC);
+
+-- =========================================================================
+-- Fact Sources - 사실과 문서 간의 관계 (Phase 2)
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS fact_sources (
+    id SERIAL PRIMARY KEY,
+    fact_id TEXT NOT NULL,
+    document_id TEXT NOT NULL,
+    extraction_confidence REAL DEFAULT 1.0,
+    extracted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (fact_id) REFERENCES factual_facts(fact_id) ON DELETE CASCADE,
+    UNIQUE(fact_id, document_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_fact_sources_fact_id ON fact_sources(fact_id);
+CREATE INDEX IF NOT EXISTS idx_fact_sources_document_id ON fact_sources(document_id);
+
+-- =========================================================================
+-- Memory Evolution Log - 메모리 변화 추적 (Phase 2)
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS memory_evolution_log (
+    id SERIAL PRIMARY KEY,
+    operation TEXT NOT NULL,         -- consolidate, update, forget, decay
+    target_type TEXT NOT NULL,       -- fact, learning, behavior
+    target_id TEXT NOT NULL,
+    details TEXT,                    -- JSON: operation-specific details
+    performed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_evolution_log_operation ON memory_evolution_log(operation);
+CREATE INDEX IF NOT EXISTS idx_evolution_log_target ON memory_evolution_log(target_type, target_id);
+CREATE INDEX IF NOT EXISTS idx_evolution_log_performed_at ON memory_evolution_log(performed_at DESC);
+
+-- =========================================================================
+-- Phase 5: Planar Form - KG Integration
+-- =========================================================================
+
+-- KG Entity binding table for explicit KG links
+CREATE TABLE IF NOT EXISTS fact_kg_bindings (
+    id SERIAL PRIMARY KEY,
+    fact_id TEXT NOT NULL,
+    kg_entity_id TEXT NOT NULL,          -- KG 엔티티 이름/ID
+    kg_relation_type TEXT,               -- KG 관계 타입
+    binding_confidence REAL DEFAULT 1.0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (fact_id) REFERENCES factual_facts(fact_id) ON DELETE CASCADE,
+    UNIQUE(fact_id, kg_entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_kg_bindings_fact_id ON fact_kg_bindings(fact_id);
+CREATE INDEX IF NOT EXISTS idx_kg_bindings_kg_entity ON fact_kg_bindings(kg_entity_id);
+CREATE INDEX IF NOT EXISTS idx_kg_bindings_relation_type ON fact_kg_bindings(kg_relation_type);
+
+-- =========================================================================
+-- Phase 5: Hierarchical Form - Summary Layers
+-- =========================================================================
+
+-- Fact hierarchy table for parent-child relationships
+CREATE TABLE IF NOT EXISTS fact_hierarchy (
+    id SERIAL PRIMARY KEY,
+    parent_fact_id TEXT NOT NULL,
+    child_fact_id TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (parent_fact_id) REFERENCES factual_facts(fact_id) ON DELETE CASCADE,
+    FOREIGN KEY (child_fact_id) REFERENCES factual_facts(fact_id) ON DELETE CASCADE,
+    UNIQUE(parent_fact_id, child_fact_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hierarchy_parent ON fact_hierarchy(parent_fact_id);
+CREATE INDEX IF NOT EXISTS idx_hierarchy_child ON fact_hierarchy(child_fact_id);

evalvault/adapters/outbound/llm/factory.py

@@ -97,7 +97,7 @@ def _resolve_faithfulness_fallback_config(
 
 def _default_faithfulness_fallback_model(provider: str) -> str | None:
     if provider == "ollama":
-        return "gpt-oss-safeguard:20b"
+        return "qwen3:8b"
     if provider == "vllm":
         return "gpt-oss-120b"
     return None

evalvault/adapters/outbound/llm/vllm_adapter.py

@@ -64,6 +64,29 @@ class VLLMAdapter(BaseLLMAdapter):
         """Get the embedding model name being used."""
         return self._embedding_model_name
 
+    def embed_sync(
+        self,
+        *,
+        texts: list[str],
+        model: str | None = None,
+        dimension: int | None = None,
+    ) -> list[list[float]]:
+        """Synchronous embedding call using OpenAI-compatible API."""
+        embed_base_url = self._settings.vllm_embedding_base_url or self._settings.vllm_base_url
+        client = OpenAI(
+            base_url=embed_base_url,
+            api_key=self._settings.vllm_api_key or "local",
+            timeout=self._settings.vllm_timeout,
+        )
+        payload: dict[str, Any] = {
+            "model": model or self._embedding_model_name,
+            "input": texts,
+        }
+        if dimension is not None:
+            payload["dimensions"] = dimension
+        response = client.embeddings.create(**payload)
+        return [item.embedding for item in response.data]
+
     async def agenerate_text(
         self,
         prompt: str,

evalvault/adapters/outbound/nlp/korean/dense_retriever.py

@@ -141,8 +141,8 @@ class KoreanDenseRetriever:
         },
     }
 
-    # 기본 모델: dragonkue/BGE-m3-ko (AutoRAG 벤치마크 1위)
-    DEFAULT_MODEL = "dragonkue/BGE-m3-ko"
+    # 기본 모델: BAAI/bge-m3 (멀티링거시 기본)
+    DEFAULT_MODEL = "BAAI/bge-m3"
 
     def __init__(
         self,
@@ -175,7 +175,7 @@ class KoreanDenseRetriever:
             device: 디바이스 (auto, cpu, cuda, mps)
             batch_size: 인코딩 배치 크기
                 - 0 이하로 설정하면 간단한 휴리스틱으로 자동 결정
-            ollama_adapter: Ollama LLM 어댑터 (Qwen3-Embedding 사용 시 필수)
+        ollama_adapter: OpenAI 호환 임베딩 어댑터 (Ollama/vLLM)
             matryoshka_dim: Matryoshka 차원 (Qwen3-Embedding 전용)
                 - None: 모델 권장 차원 사용
                 - 256: 개발용 (속도 우선)
@@ -237,12 +237,12 @@ class KoreanDenseRetriever:
         self._query_cache_size = max(query_cache_size, 0)
         self._search_cache_size = max(search_cache_size, 0)
 
-        # Validate Ollama adapter for Ollama models
+        # Validate embedding adapter for OpenAI-compatible embedding models
         model_info = self.SUPPORTED_MODELS.get(self._model_name)
         if model_info and model_info.get("type") == "ollama" and not self._ollama_adapter:
             raise ValueError(
-                f"ollama_adapter is required for Ollama model '{self._model_name}'. "
-                "Create one with: OllamaAdapter(settings)"
+                f"embedding adapter is required for model '{self._model_name}'. "
+                "Create one with: OllamaAdapter(settings) or VLLMAdapter(settings)"
             )
 
         # Auto-select matryoshka dimension if not specified
@@ -362,7 +362,10 @@ class KoreanDenseRetriever:
             return
 
         model_info = self.SUPPORTED_MODELS.get(self._model_name)
-        model_type = model_info["type"] if model_info else "sentence-transformers"
+        if model_info is None and self._ollama_adapter is not None:
+            model_type = "ollama"
+        else:
+            model_type = model_info["type"] if model_info else "sentence-transformers"
 
         # Ollama models use adapter directly - no model loading needed
         if model_type == "ollama":

evalvault/adapters/outbound/nlp/korean/toolkit.py

@@ -76,10 +76,21 @@ class KoreanNLPToolkit(KoreanNLPToolkitPort):
 
         embedding_func = None
         try:
-            dense_retriever = KoreanDenseRetriever(
-                profile=embedding_profile,
-                ollama_adapter=ollama_adapter,
-            )
+            if embedding_profile == "vllm":
+                from evalvault.adapters.outbound.llm.vllm_adapter import VLLMAdapter
+                from evalvault.config.settings import Settings
+
+                settings = Settings()
+                adapter = ollama_adapter or VLLMAdapter(settings)
+                dense_retriever = KoreanDenseRetriever(
+                    model_name=settings.vllm_embedding_model,
+                    ollama_adapter=adapter,
+                )
+            else:
+                dense_retriever = KoreanDenseRetriever(
+                    profile=embedding_profile,
+                    ollama_adapter=ollama_adapter,
+                )
             embedding_func = dense_retriever.get_embedding_func()
             if verbose:
                 logger.info(

evalvault/adapters/outbound/phoenix/sync_service.py

@@ -104,6 +104,22 @@ class PhoenixSyncService:
                 dataset_description=description,
             )
         except Exception as exc:  # pragma: no cover - HTTP/serialization errors
+            message = str(exc)
+            if "already exists" in message:
+                existing = self._find_dataset_by_name(dataset_name)
+                if existing:
+                    dataset_obj = self._client.datasets.get_dataset(dataset=existing["id"])
+                    dataset_url = self._client.experiments.get_dataset_experiments_url(
+                        dataset_obj.id
+                    )
+                    return PhoenixDatasetInfo(
+                        dataset_id=dataset_obj.id,
+                        dataset_name=dataset_obj.name,
+                        dataset_version_id=dataset_obj.version_id,
+                        url=dataset_url,
+                        description=description,
+                        example_count=getattr(dataset_obj, "examples", None),
+                    )
             raise PhoenixSyncError(f"Dataset upload failed: {exc}") from exc
 
         dataset_url = self._client.experiments.get_dataset_experiments_url(phoenix_dataset.id)
@@ -173,6 +189,74 @@ class PhoenixSyncService:
             )
         return examples
 
+    def _find_dataset_by_name(self, dataset_name: str) -> dict[str, Any] | None:
+        try:
+            datasets = self._client.datasets.list()
+        except Exception:
+            return None
+        for entry in datasets:
+            if entry.get("name") == dataset_name:
+                return entry
+        return None
+
+    def sync_prompts(
+        self,
+        *,
+        prompt_entries: list[dict[str, Any]],
+        model_name: str,
+        model_provider: str,
+        prompt_set_name: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Create prompt versions in Phoenix Prompt Management."""
+
+        if not prompt_entries:
+            return []
+
+        try:
+            from phoenix.client.resources.prompts import PromptVersion
+        except Exception as exc:  # pragma: no cover - optional dependency
+            raise PhoenixSyncError("Phoenix prompt client unavailable") from exc
+
+        synced: list[dict[str, Any]] = []
+        for index, entry in enumerate(prompt_entries, start=1):
+            name = entry.get("name") or entry.get("role") or f"prompt_{index}"
+            content = entry.get("content") or entry.get("content_preview") or ""
+            if not content:
+                continue
+            prompt_version = PromptVersion(
+                [{"role": "system", "content": content}],
+                model_name=model_name,
+                model_provider=model_provider,
+                template_format="NONE",
+            )
+            prompt_metadata = {
+                "kind": entry.get("kind"),
+                "role": entry.get("role"),
+                "checksum": entry.get("checksum"),
+                "status": entry.get("status"),
+                "source": entry.get("source") or entry.get("path"),
+                "order": index,
+            }
+            if prompt_set_name:
+                prompt_metadata["prompt_set"] = prompt_set_name
+            try:
+                version = self._client.prompts.create(
+                    version=prompt_version,
+                    name=name,
+                    prompt_description=entry.get("notes"),
+                    prompt_metadata=_as_serializable(prompt_metadata),
+                )
+                synced.append(
+                    {
+                        **entry,
+                        "phoenix_prompt_version_id": getattr(version, "id", None),
+                    }
+                )
+            except Exception as exc:  # pragma: no cover - HTTP errors
+                raise PhoenixSyncError(f"Prompt sync failed: {exc}") from exc
+
+        return synced
+
     def _build_input_payload(self, test_case: TestCase) -> dict[str, Any]:
         return {
             "question": test_case.question,
@@ -258,6 +342,21 @@ def build_experiment_metadata(
         "total_test_cases": run.total_test_cases,
         "metrics": metrics,
     }
+    if run.results:
+        latencies = [r.latency_ms for r in run.results if r.latency_ms]
+        tokens = [r.tokens_used for r in run.results if r.tokens_used]
+        costs = [r.cost_usd for r in run.results if r.cost_usd is not None]
+        if latencies:
+            payload["avg_latency_ms"] = round(sum(latencies) / len(latencies), 2)
+        if tokens:
+            payload["avg_tokens"] = round(sum(tokens) / len(tokens), 2)
+        if costs:
+            payload["avg_cost_usd"] = round(sum(costs) / len(costs), 6)
+    if run.total_tokens:
+        payload["total_tokens"] = run.total_tokens
+    if run.total_cost_usd is not None:
+        payload["total_cost_usd"] = run.total_cost_usd
+    payload["error_rate"] = round(1 - run.pass_rate, 4)
     if reliability_snapshot:
         payload["reliability_snapshot"] = reliability_snapshot
     if dataset.metadata:

evalvault/adapters/outbound/retriever/pgvector_store.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import psycopg
+from psycopg.rows import dict_row
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PgvectorResult:
+    doc_id: int
+    content: str
+    score: float
+
+
+class PgvectorStore:
+    def __init__(
+        self,
+        conn_string: str,
+        *,
+        distance: str = "cosine",
+        index_type: str = "hnsw",
+        index_lists: int = 100,
+        hnsw_m: int = 16,
+        hnsw_ef_construction: int = 64,
+    ) -> None:
+        self._conn_string = conn_string
+        self._distance = distance
+        self._index_type = index_type
+        self._index_lists = index_lists
+        self._hnsw_m = hnsw_m
+        self._hnsw_ef_construction = hnsw_ef_construction
+
+    def _vector_ops(self) -> str:
+        if self._distance == "ip":
+            return "vector_ip_ops"
+        if self._distance == "l2":
+            return "vector_l2_ops"
+        return "vector_cosine_ops"
+
+    def _connect(self) -> psycopg.Connection:
+        conn = psycopg.connect(self._conn_string, row_factory=dict_row)
+        try:
+            from pgvector.psycopg import register_vector
+
+            register_vector(conn)
+        except Exception as exc:  # pragma: no cover - runtime dependency
+            logger.warning("Failed to register pgvector type: %s", exc)
+        return conn
+
+    def ensure_schema(self, *, dimension: int) -> None:
+        sql = f"""
+        CREATE EXTENSION IF NOT EXISTS vector;
+
+        CREATE TABLE IF NOT EXISTS rag_documents (
+            id BIGSERIAL PRIMARY KEY,
+            source TEXT NOT NULL,
+            source_hash TEXT NOT NULL,
+            doc_id INTEGER NOT NULL,
+            content TEXT NOT NULL,
+            embedding VECTOR({dimension}),
+            metadata JSONB,
+            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_rag_documents_source ON rag_documents(source);
+        CREATE INDEX IF NOT EXISTS idx_rag_documents_doc_id ON rag_documents(doc_id);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_rag_documents_source_doc_id
+            ON rag_documents(source, doc_id);
+        """
+        with self._connect() as conn:
+            conn.execute(sql)
+            if self._index_type != "none":
+                opclass = self._vector_ops()
+                if self._index_type == "ivfflat":
+                    index_sql = (
+                        "CREATE INDEX IF NOT EXISTS idx_rag_documents_embedding "
+                        f"ON rag_documents USING ivfflat (embedding {opclass}) "
+                        f"WITH (lists = {self._index_lists});"
+                    )
+                    try:
+                        conn.execute(index_sql)
+                    except Exception as exc:  # pragma: no cover - runtime dependency
+                        logger.warning("Failed to create ivfflat index: %s", exc)
+                elif self._index_type == "hnsw":
+                    index_sql = (
+                        "CREATE INDEX IF NOT EXISTS idx_rag_documents_embedding "
+                        f"ON rag_documents USING hnsw (embedding {opclass}) "
+                        f"WITH (m = {self._hnsw_m}, ef_construction = {self._hnsw_ef_construction});"
+                    )
+                    try:
+                        conn.execute(index_sql)
+                    except Exception as exc:  # pragma: no cover - runtime dependency
+                        logger.warning("Failed to create hnsw index: %s", exc)
+            conn.commit()
+
+    def get_source_state(self, *, source: str) -> tuple[str | None, int]:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT source_hash, COUNT(*) AS total
+                FROM rag_documents
+                WHERE source = %s
+                GROUP BY source_hash
+                ORDER BY total DESC
+                LIMIT 1
+                """,
+                (source,),
+            ).fetchone()
+        if not row:
+            return None, 0
+        return row["source_hash"], int(row["total"])
+
+    def replace_documents(
+        self,
+        *,
+        source: str,
+        source_hash: str,
+        documents: Iterable[str],
+        embeddings: Iterable[list[float]],
+    ) -> None:
+        rows = list(zip(documents, embeddings, strict=True))
+        with self._connect() as conn:
+            conn.execute("DELETE FROM rag_documents WHERE source = %s", (source,))
+            with conn.cursor() as cursor:
+                cursor.executemany(
+                    """
+                    INSERT INTO rag_documents (source, source_hash, doc_id, content, embedding)
+                    VALUES (%s, %s, %s, %s, %s)
+                    """,
+                    [
+                        (source, source_hash, index, content, embedding)
+                        for index, (content, embedding) in enumerate(rows)
+                    ],
+                )
+            conn.commit()
+
+    def search(
+        self, *, source: str, query_embedding: list[float], top_k: int
+    ) -> list[PgvectorResult]:
+        if self._distance == "ip":
+            operator = "<#>"
+        elif self._distance == "l2":
+            operator = "<->"
+        else:
+            operator = "<=>"
+
+        sql = (
+            f"SELECT doc_id, content, embedding {operator} %s::vector AS score "
+            f"FROM rag_documents WHERE source = %s ORDER BY embedding {operator} %s::vector LIMIT %s"
+        )
+
+        with self._connect() as conn:
+            rows = conn.execute(sql, (query_embedding, source, query_embedding, top_k)).fetchall()
+
+        return [
+            PgvectorResult(
+                doc_id=int(row["doc_id"]), content=row["content"], score=float(row["score"])
+            )
+            for row in rows
+        ]

evalvault/adapters/outbound/storage/base_sql.py

@@ -247,7 +247,7 @@ class SQLQueries:
         return "SELECT run_id FROM evaluation_runs WHERE 1=1"
 
     def list_runs_ordering(self) -> str:
-        return f" ORDER BY started_at DESC LIMIT {self.placeholder}"
+        return f" ORDER BY started_at DESC LIMIT {self.placeholder} OFFSET {self.placeholder}"
 
     def upsert_regression_baseline(self) -> str:
         raise NotImplementedError("Override in subclass")
@@ -394,6 +394,7 @@ class BaseSQLStorageAdapter(ABC):
     def list_runs(
         self,
         limit: int = 100,
+        offset: int = 0,
         dataset_name: str | None = None,
         model_name: str | None = None,
     ) -> list[EvaluationRun]:
@@ -410,7 +411,7 @@ class BaseSQLStorageAdapter(ABC):
                 params.append(model_name)
 
             query += self.queries.list_runs_ordering()
-            params.append(limit)
+            params.extend([limit, offset])
 
             cursor = self._execute(conn, query, params)
             run_ids = [row["run_id"] for row in cursor.fetchall()]

evalvault/adapters/outbound/storage/factory.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from evalvault.adapters.outbound.storage.postgres_adapter import PostgreSQLStorageAdapter
+from evalvault.adapters.outbound.storage.sqlite_adapter import SQLiteStorageAdapter
+from evalvault.config.settings import Settings
+from evalvault.ports.outbound.storage_port import StoragePort
+
+logger = logging.getLogger(__name__)
+
+
+def build_storage_adapter(
+    *,
+    settings: Settings | None = None,
+    db_path: Path | None = None,
+    fallback_to_sqlite: bool = True,
+) -> StoragePort:
+    resolved_settings = settings or Settings()
+
+    if db_path is not None:
+        return SQLiteStorageAdapter(db_path=db_path)
+
+    backend = getattr(resolved_settings, "db_backend", "postgres")
+    if backend == "sqlite":
+        resolved_db_path = resolved_settings.evalvault_db_path
+        if resolved_db_path is None:
+            raise RuntimeError("SQLite backend selected but evalvault_db_path is not set.")
+        return SQLiteStorageAdapter(db_path=resolved_db_path)
+
+    conn_string = resolved_settings.postgres_connection_string
+    if not conn_string:
+        host = resolved_settings.postgres_host or "localhost"
+        port = resolved_settings.postgres_port
+        database = resolved_settings.postgres_database
+        user = resolved_settings.postgres_user or "postgres"
+        password = resolved_settings.postgres_password or ""
+        conn_string = f"host={host} port={port} dbname={database} user={user} password={password}"
+
+    try:
+        return PostgreSQLStorageAdapter(connection_string=conn_string)
+    except Exception as exc:
+        if not fallback_to_sqlite:
+            raise
+        logger.warning("PostgreSQL adapter failed (%s). Falling back to SQLite.", exc)
+        resolved_db_path = resolved_settings.evalvault_db_path
+        if resolved_db_path is None:
+            raise
+        return SQLiteStorageAdapter(db_path=resolved_db_path)
+
+
+__all__ = ["build_storage_adapter"]

evalvault/adapters/outbound/storage/postgres_schema.sql

@@ -1,6 +1,8 @@
 -- EvalVault PostgreSQL Database Schema
 -- Stores evaluation runs, test case results, and metric scores
 
+CREATE EXTENSION IF NOT EXISTS vector;
+
 -- Main evaluation runs table
 CREATE TABLE IF NOT EXISTS evaluation_runs (
     run_id UUID PRIMARY KEY,