igel-qe-core 1.0.0

package/knowledge_base/deploy/firecrawl-docker.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Deploy self-hosted Firecrawl for KB web search (no API key required).
+set -euo pipefail
+
+INSTALL_DIR="${FIRECRAWL_INSTALL_DIR:-/opt/firecrawl}"
+PORT="${FIRECRAWL_PORT:-3002}"
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "ERROR: docker is not installed. Install Docker first, then re-run this script."
+  exit 1
+fi
+
+if ! docker compose version >/dev/null 2>&1; then
+  echo "ERROR: docker compose plugin is required."
+  exit 1
+fi
+
+if [ ! -d "$INSTALL_DIR/.git" ]; then
+  echo "Cloning Firecrawl into $INSTALL_DIR ..."
+  git clone --depth 1 https://github.com/mendableai/firecrawl.git "$INSTALL_DIR"
+else
+  echo "Updating Firecrawl in $INSTALL_DIR ..."
+  git -C "$INSTALL_DIR" pull --ff-only || true
+fi
+
+cd "$INSTALL_DIR"
+cat > .env << EOF
+PORT=${PORT}
+HOST=0.0.0.0
+USE_DB_AUTHENTICATION=false
+BULL_AUTH_KEY=igel-kb-local
+EOF
+
+echo "Building and starting Firecrawl on port ${PORT} ..."
+docker compose build
+docker compose up -d
+
+echo "Waiting for Firecrawl health ..."
+for i in $(seq 1 30); do
+  if curl -sf "http://127.0.0.1:${PORT}/" >/dev/null 2>&1; then
+    echo "Firecrawl is up at http://127.0.0.1:${PORT}"
+    echo "Set in knowledge_base/config/.env:"
+    echo "  FIRECRAWL_BASE_URL=http://127.0.0.1:${PORT}"
+    exit 0
+  fi
+  sleep 5
+done
+
+echo "WARN: Firecrawl may still be starting. Check: docker compose -C $INSTALL_DIR logs -f"
+exit 0

package/knowledge_base/deploy/igel-testgen.service

@@ -0,0 +1,26 @@
+# systemd service unit for the IGEL Test Case Generation API.
+#
+# Install:
+#   sudo cp igel-testgen.service /etc/systemd/system/
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable igel-testgen
+#   sudo systemctl start igel-testgen
+
+[Unit]
+Description=IGEL Test Case Generation API (RAG + KG)
+After=network.target postgresql.service
+Wants=postgresql.service
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/root/IGEL/IGEL_Automation_Claude/IGEL/innominds
+EnvironmentFile=-/root/IGEL/IGEL_Automation_Claude/IGEL/innominds/knowledge_base/config/.env
+ExecStartPre=/bin/bash -c 'until pg_isready -h ${DB_HOST:-localhost} -p ${DB_PORT:-5432}; do sleep 2; done'
+ExecStart=/bin/bash knowledge_base/deploy/run_server.sh
+Restart=always
+RestartSec=5
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target

package/knowledge_base/deploy/install_reranker.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Install free/open-source local reranker (BAAI/bge-reranker-v2-m3 via sentence-transformers).
+set -euo pipefail
+
+PYTHON="${KB_PYTHON:-python3.8}"
+if ! command -v "$PYTHON" >/dev/null 2>&1; then
+  PYTHON=python3
+fi
+
+echo "Using Python: $($PYTHON --version 2>&1)"
+
+# Bootstrap user pip if system pip is broken (OpenSSL/pyOpenSSL conflicts on older Ubuntu).
+if ! "$PYTHON" -m pip --version >/dev/null 2>&1; then
+  echo "Bootstrapping pip..."
+  curl -sS "https://bootstrap.pypa.io/pip/$($PYTHON -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')/get-pip.py" \
+    -o /tmp/get-pip-kb.py
+  "$PYTHON" /tmp/get-pip-kb.py --user
+fi
+
+PIP="$($PYTHON -m pip --version >/dev/null 2>&1 && echo "$PYTHON -m pip" || echo "$HOME/.local/bin/pip$($PYTHON -c 'import sys; print(sys.version_info.minor)')")"
+# shellcheck disable=SC2086
+$PIP install --upgrade \
+  'jinja2>=3.1.2,<3.2' \
+  'MarkupSafe>=2.1.0,<3' \
+  'tokenizers>=0.20,<0.21' \
+  'transformers>=4.41.0,<4.47' \
+  'sentence-transformers>=3.2.0,<3.3' \
+  'torch>=2.0,<2.5'
+
+# Remove stale metadata that makes transformers think tokenizers 0.21 is installed.
+SITE=$("$PYTHON" -c "import site; print(site.getsitepackages()[0])")
+rm -rf "${SITE}/tokenizers-0.21.0.dist-info" 2>/dev/null || true
+
+echo "Verifying CPU OSS reranker (MiniLM — fast on CPU)..."
+"$PYTHON" << 'PYEOF'
+import markupsafe
+if not hasattr(markupsafe, "soft_unicode"):
+    markupsafe.soft_unicode = getattr(markupsafe, "soft_str", str)
+from time import perf_counter
+from sentence_transformers import CrossEncoder
+model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2", max_length=256, device="cpu")
+pairs = [
+    ("UMS SSO login", "Section: SSO\nPassage: Configure Entra ID SSO in UMS"),
+    ("UMS SSO login", "Section: Battery\nPassage: Power management settings"),
+] * 8
+t0 = perf_counter()
+scores = model.predict(pairs, show_progress_bar=False, batch_size=8)
+elapsed = perf_counter() - t0
+print(f"OK — MiniLM reranked {len(pairs)} pairs in {elapsed:.2f}s, top score={float(max(scores)):.4f}")
+PYEOF
+
+echo "Done. Set RERANKER_BACKEND=local in config/.env (default)."
+
+echo "Installing free web search (DuckDuckGo ddgs)..."
+# shellcheck disable=SC2086
+$PIP install 'duckduckgo-search>=6.0.0,<7.0.0' 2>/dev/null || $PIP install 'ddgs>=6.0.0'
+
+echo "Installing Firecrawl SDK + Playwright (web search + JS page extraction)..."
+# crawl4ai requires Python 3.9+ (numpy>=1.26); on 3.8 we use Playwright directly.
+# shellcheck disable=SC2086
+$PIP install 'firecrawl-py>=1.0.0' 'playwright>=1.40.0,<1.49.0'
+if "$PYTHON" -c 'import sys; exit(0 if sys.version_info >= (3, 9) else 1)'; then
+  $PIP install 'crawl4ai>=0.4.0,<0.5.0' || true
+fi
+
+echo "Setting up Playwright browser (Chromium)..."
+"$PYTHON" -m playwright install chromium 2>/dev/null || true
+if command -v crawl4ai-setup >/dev/null 2>&1; then
+  crawl4ai-setup || true
+fi
+
+echo "Verifying DuckDuckGo search..."
+"$PYTHON" << 'PYEOF'
+try:
+    from duckduckgo_search import DDGS
+except ImportError:
+    from ddgs import DDGS
+with DDGS() as ddgs:
+    rows = list(ddgs.text("IGEL OS SSO", max_results=2) or [])
+echo "Verifying Crawl4AI import..."
+"$PYTHON" << 'PYEOF'
+try:
+    from crawl4ai import AsyncWebCrawler
+    print("OK — crawl4ai import")
+except Exception as e:
+    print(f"WARN — crawl4ai: {e}")
+try:
+    import firecrawl
+    print("OK — firecrawl-py import")
+except Exception as e:
+    print(f"WARN — firecrawl-py: {e}")
+PYEOF

package/knowledge_base/deploy/requirements.txt

@@ -0,0 +1,68 @@
+# Knowledge Base Ingestion Pipeline - Additional Dependencies
+# Install with: pip install -r requirements_kb.txt
+
+# PostgreSQL + pgvector
+psycopg2-binary==2.9.9
+pgvector==0.3.6
+
+# Database migrations
+alembic==1.13.1
+
+# Azure OpenAI
+openai==1.57.4
+
+# Document Parsing
+pdfplumber==0.11.4
+pymupdf>=1.24.0
+python-docx==1.1.2
+mammoth==1.8.0
+pandas>=2.0.0,<2.1.0; python_version < "3.9"
+pandas>=2.2.0; python_version >= "3.9"
+openpyxl==3.1.5
+
+# Token counting
+tiktoken>=0.5.0
+
+# Config / Utils
+pydantic>=2.7.0
+eval_type_backport>=0.2.0; python_version < "3.10"
+python-dotenv==1.0.1
+tenacity==9.0.0
+rich==13.9.4
+
+# OSS local reranker (CrossEncoder — free, runs on CPU/GPU)
+# Default model: BAAI/bge-reranker-v2-m3 (multilingual, best open-source for IGEL DE/EN)
+# Install: bash knowledge_base/deploy/install_reranker.sh
+jinja2>=3.1.2,<3.2
+MarkupSafe>=2.1.0,<3
+tokenizers>=0.20,<0.21
+transformers>=4.41.0,<4.47
+sentence-transformers>=3.2.0,<3.3
+torch>=2.0,<2.5; python_version < "3.9"
+
+# Optional hosted reranker (not required for OSS setup)
+# cohere>=5.0.0
+
+# Web retrieval (confidence-gated — Firecrawl search + Crawl4AI fetch)
+httpx>=0.27.0
+beautifulsoup4>=4.12.0
+lxml>=5.0.0
+duckduckgo-search>=6.0.0,<7.0.0; python_version < "3.9"
+firecrawl-py>=1.0.0
+playwright>=1.40.0,<1.49.0
+crawl4ai>=0.4.0,<0.5.0; python_version >= "3.9"
+
+# REST API server (always-running service)
+fastapi>=0.111.0
+uvicorn[standard]>=0.30.0
+redis>=5.0.0
+# Phase 3: Neo4j graph DB (optional — enable with KG_SHADOW_MODE=true)
+neo4j>=5.15.0
+
+# Phase 4-6: Optional OSS packages (PostgreSQL fallbacks exist if not installed)
+# cognee
+# graphiti-core
+
+# Phase 5: Agent orchestration (sequential fallback if not installed)
+langgraph>=0.0.8; python_version < "3.9"
+langgraph>=0.2.0; python_version >= "3.9"

package/knowledge_base/deploy/run_server.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Start the IGEL Test Generation API server.
+# Run this directly or use the systemd service (igel-testgen.service).
+#
+# Default: binds to 0.0.0.0:8000 so any machine on the network can call the API.
+# Override with environment variables: TESTGEN_HOST, TESTGEN_PORT
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+cd "$PROJECT_DIR"
+
+# Prefer Python 3.8+ (Pydantic v2 / FastAPI stack)
+PYTHON="${TESTGEN_PYTHON:-python3.8}"
+if ! command -v "$PYTHON" >/dev/null 2>&1; then
+  PYTHON=python3
+fi
+
+HOST="${TESTGEN_HOST:-0.0.0.0}"
+PORT="${TESTGEN_PORT:-8000}"
+WORKERS="${TESTGEN_WORKERS:-1}"
+
+echo "Starting IGEL Test Generation API on ${HOST}:${PORT} (workers=${WORKERS})"
+echo "  Project dir: $PROJECT_DIR"
+echo "  Python:      $($PYTHON --version 2>&1)"
+echo "  Swagger UI:  http://${HOST}:${PORT}/docs"
+echo ""
+
+exec "$PYTHON" -m uvicorn knowledge_base.api.server:app \
+    --host "$HOST" \
+    --port "$PORT" \
+    --workers "$WORKERS" \
+    --log-level info

package/knowledge_base/docs/TEST_GENERATION_GUIDE.md

@@ -0,0 +1,174 @@
+# IGEL test case generation — operator guide
+
+This document is for anyone running the RAG-powered test generator in `knowledge_base/`. The CLI (`python -m knowledge_base.cli.generate`) **always retrieves context from PostgreSQL** (vector + full-text hybrid search + knowledge graph) before calling the LLM. Outputs are only as accurate as the **ingested documentation** in the KB.
+
+## How it works (short)
+
+1. Your **topic** string is embedded and searched against `kb_chunks` / related tables.
+2. Top passages are merged via **Reciprocal Rank Fusion** (vector + FTS), optionally **reranked** by a cross-encoder.
+3. The **Knowledge Graph** is queried for registry keys, TC Setup paths, and feature entities linked to the retrieved chunks — these supply the *exact strings* the LLM uses in test steps.
+4. Text chunks + KG entities + image context are fused under a token budget.
+5. That context is sent to the model with strict instructions: **ground steps in the KB**, no vague expected results, no invented URLs or product paths.
+6. Artifacts are written under `tests/Generated/` (by default): Markdown spec, Python pytest file, and an appended **KB retrieval traceability** section listing chunk IDs for audit.
+
+Use `--debug` to print full retrieval diagnostics (scores, inclusion reasons, KG nodes).
+
+## Faithful modes (manual TC → pytest)
+
+The generator **classifies** every request:
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Transform** | Pasted manual TC has 3+ structured steps (CSV / JIRA export) | **Preserve** step count and intent; map to Markdown + pytest; light KB retrieval for supplementary paths/keys only. |
+| **Expand** | Pasted TC is partial (few steps or incomplete expected results) | **Keep** existing steps verbatim; use RAG/KG to **fill gaps** only. |
+| **Synthesize** | Topic-only (no structured paste) | Full RAG + KG (same as legacy behavior). |
+
+- **CLI**: pass `--source-tc-file path/to/export.csv` (optional `--detail-level concise|detailed|auto`).
+- **API**: `POST /generate` with optional `source_tc` (string) and `detail_level`, or `POST /convert` with required `source_tc` for dedicated manual-TC conversion.
+
+Step-fidelity checks run after generation; warnings are returned when counts or preservation rules may be violated.
+
+## Prerequisites
+
+- PostgreSQL reachable with the KB populated (`knowledge_base/.env`, see `config.py` / `db/client.py`).
+- Documents ingested (`python -m knowledge_base.ingestion.ingest` — this **also populates the Knowledge Graph automatically**).
+- Azure OpenAI credentials configured for the LLM and embeddings.
+
+## Ingestion (single command — RAG + KG in sync)
+
+```bash
+python -m knowledge_base.ingestion.ingest               # Ingest all new docs + build KG
+python -m knowledge_base.ingestion.ingest --file x.pdf  # Single file (KG extracted for that doc)
+python -m knowledge_base.ingestion.ingest --reset       # Full re-ingest from scratch
+python -m knowledge_base.ingestion.ingest --stats       # Show document, chunk, KG, and image counts
+python -m knowledge_base.ingestion.ingest --skip-kg     # Text + embeddings only (rare; skips KG)
+```
+
+**No separate KG step is needed.** Each ingested document automatically has its registry keys (`app.*`), TC Setup paths, and feature nodes extracted into `knowledge_graph_nodes` / `knowledge_graph_edges`. The `--stats` output shows `kg_nodes`, `kg_edges`, and `kg_orphan_parents` (parents with no KG entity — ideally 0 or low).
+
+If you ever need a backfill (e.g. after upgrading the KG extractor logic), you can still run the standalone extractor:
+
+```bash
+python -m knowledge_base.ingestion.kg_extractor
+```
+
+## Always-running API service (recommended)
+
+The server runs on **192.168.204.65:8000** and responds to any user query — no commands to run per test case.
+
+### Starting the service
+
+```bash
+# Option 1: systemd (starts on boot, restarts on crash)
+sudo cp knowledge_base/igel-testgen.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable igel-testgen
+sudo systemctl start igel-testgen
+
+# Option 2: directly
+cd /root/IGEL/IGEL_Automation_Claude/IGEL/innominds
+./knowledge_base/run_server.sh
+```
+
+### API endpoints
+
+| Method | Path | What it does |
+|--------|------|------|
+| `POST` | `/query` | Ask any test-case question — returns detailed executable steps |
+| `POST` | `/generate` | Full generation from `topic` and/or pasted `source_tc` (auto-routed) |
+| `POST` | `/convert` | Convert pasted manual TC (`source_tc` required) — transform/expand pipeline |
+| `GET` | `/health` | Check DB, KB, KG readiness |
+| `GET` | `/stats` | Document/chunk/KG counts |
+
+Swagger docs at **http://192.168.204.65:8000/docs**
+
+### Example: ask for test steps
+
+```bash
+curl -X POST http://192.168.204.65:8000/query \
+  -H "Content-Type: application/json" \
+  -d '{"question": "How to test Entra ID SSO login on IGEL OS 12", "top_k": 10}'
+```
+
+Response includes `answer` (full detailed steps), `kb_sources` (chunk IDs for traceability), and `kg_entities_used`.
+
+### Example: generate full test case
+
+```bash
+curl -X POST http://192.168.204.65:8000/generate \
+  -H "Content-Type: application/json" \
+  -d '{"topic": "RDP session connection validation", "output_format": "both"}'
+```
+
+### Example: faithful conversion (pasted manual TC)
+
+Use `POST /convert` with a JSON body where `source_tc` is the full pasted export (CSV or JIRA table). For large pastes, build the JSON in code or use HTTPie/`curl --data-binary @body.json`. Optional: same payload on `POST /generate` with `"source_tc": "..."` plus a short `"topic"` label.
+
+Response includes `markdown_content`, `python_content`, `traceability_table`, and metadata.
+
+## CLI generation (alternative, for scripting)
+
+From the `innominds` package root (where `knowledge_base` is importable):
+
+```bash
+python -m knowledge_base.cli.generate "Entra ID SSO login validation" --format both
+python -m knowledge_base.cli.generate "UMS profile assignment" --product UMS --top-k 10
+python -m knowledge_base.cli.generate "Chromium policies QCAPPS-429" --source-tc-file path/to/jira_export.csv --detail-level detailed
+python -m knowledge_base.cli.generate --interactive
+```
+
+- **`--product`**: narrows search (UMS, IGEL OS, COSMOS, etc.); if nothing matches, retrieval retries without the filter.
+- **`--top-k`**: more chunks retrieved before budgeting; use when the topic is broad.
+- **`--source-tc-file`**: pasted official manual steps — enables **transform** or **expand** instead of topic-only synthesis.
+- **`--detail-level`**: `concise`, `detailed`, or `auto` (classifier default).
+- **`--debug`**: JSON dump of retrieval traces after generation.
+
+## What you should ask (topic phrasing)
+
+The topic is the **search query**. Be specific so retrieval pulls the right manuals:
+
+- Good: `"Entra ID SSO login validation on IGEL OS 12"` / `"UMS assign profile and verify device reboot"`.
+- Weak: `"SSO"` (too vague — retrieval may miss the right procedures).
+
+The model is instructed to return a **full JIRA-style test** even if your topic is short. **Detail still depends on what the KB returns.** If the database does not contain a path, command, or URL, the generator must not invent it.
+
+## How the Knowledge Graph improves test steps
+
+The KG supplies **structured entities** that link across documents:
+
+| KG node type | Example | How it ends up in test steps |
+|---|---|---|
+| `registry_key` | `app.igel.sessions.rdp0.host` | Exact `get`/`set` commands in SSH steps |
+| `ui_path` | `TC Setup > Sessions > RDP > Session Name` | Exact UMS navigation in TC Setup sections |
+| `feature` | "RDP Global Settings" | Cross-section relationship (links multiple chunks) |
+
+Without KG, the model only sees the 8-10 retrieved passages. With KG, it also sees **every registry key and UI path related to those passages**, even if they come from different documents. This means:
+- Steps use **real** `app.*` keys, not paraphrased descriptions.
+- TC Setup paths are **copied verbatim** from the graph, not guessed.
+- Related features from other documents surface as additional context.
+
+## Executable, non-vague steps (policy)
+
+Prompts enforce:
+
+- **Concrete actions**: exact TC Setup paths, CLI with full syntax, file paths, policy names, UI strings — copied from KB passages + KG entities where present.
+- **Concrete expected results**: observable checks (log lines, labels, command output), not standalone "Pass" or "works as expected."
+- **URLs**: only those present in retrieved docs (or standard patterns documented there). Tenant hosts belong in `ums_cred` / `api_config` in generated Python, not hardcoded guesses.
+- **Python**: pytest code is generated with the **same KB excerpt** in the prompt, so `--format py` is still DB-grounded.
+
+## Generated Python tests and configuration
+
+Generated tests use shared creds and helpers (`ums_cred`, `device_cred`, `api_config`). Ensure `testdata/` and config match your environment so generated steps are **runnable**, not just syntactically valid.
+
+## Traceability
+
+Each run prints **KB_REF** lines (file, section, chunk UUIDs). Generated Markdown ends with a traceability table. Use that to open the same passages in PostgreSQL or re-ingest logs when a step looks wrong.
+
+## If output is shallow or generic
+
+1. Check `--stats`: ensure `kg_nodes > 0` and `kg_orphan_parents` is low.
+2. Improve ingestion (more complete source docs).
+3. Increase `--top-k` or refine `--product` / topic wording.
+4. Run with `--debug` and confirm chunks are relevant (`included` / ranks).
+
+The LLM cannot replace missing documentation; it only structures what retrieval provides.

package/knowledge_base/embeddings/azure_embedder.py

@@ -0,0 +1,99 @@
+"""
+Azure OpenAI Embeddings — text-embedding-3-large (3072 dims)
+
+Features:
+  - Batched embedding (32 texts per API call)
+  - Exponential backoff retry on rate-limit / transient errors
+  - Returns embeddings as list[list[float]] aligned to input order
+"""
+from __future__ import annotations
+import time
+import logging
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+from openai import AzureOpenAI, RateLimitError, APIConnectionError, APITimeoutError
+from knowledge_base.config import cfg
+
+logger = logging.getLogger(__name__)
+
+_client: AzureOpenAI | None = None
+
+
+def _get_client() -> AzureOpenAI:
+    global _client
+    if _client is None:
+        _client = AzureOpenAI(
+            api_key=cfg.AZURE_API_KEY,
+            azure_endpoint=cfg.AZURE_ENDPOINT,
+            api_version=cfg.AZURE_EMBEDDINGS_API_VERSION,
+        )
+    return _client
+
+
+@retry(
+    retry=retry_if_exception_type((RateLimitError, APIConnectionError, APITimeoutError)),
+    wait=wait_exponential(multiplier=1, min=2, max=30),
+    stop=stop_after_attempt(cfg.MAX_RETRIES),
+    reraise=True,
+)
+def _embed_batch(texts: list[str]) -> list[list[float]]:
+    """Embed a single batch (max 32 texts) with retry on transient errors."""
+    client = _get_client()
+    response = client.embeddings.create(
+        model=cfg.AZURE_EMBEDDING_DEPLOYMENT,
+        input=texts,
+        dimensions=cfg.EMBEDDING_DIM,
+    )
+    # Response items are ordered by index
+    sorted_data = sorted(response.data, key=lambda x: x.index)
+    return [item.embedding for item in sorted_data]
+
+
+def embed_texts(texts: list[str], batch_size: int = 32) -> list[list[float]]:
+    """
+    Embed a list of texts in batches.
+    Returns list of embeddings in the same order as input texts.
+    Empty or whitespace-only texts get a zero vector.
+    """
+    results: list[list[float] | None] = [None] * len(texts)
+    zero_vector = [0.0] * cfg.EMBEDDING_DIM
+
+    # Separate non-empty texts with their original indices
+    to_embed: list[tuple[int, str]] = [
+        (i, t.strip()) for i, t in enumerate(texts) if t.strip()
+    ]
+
+    for batch_start in range(0, len(to_embed), batch_size):
+        batch = to_embed[batch_start:batch_start + batch_size]
+        indices = [item[0] for item in batch]
+        batch_texts = [item[1] for item in batch]
+
+        try:
+            embeddings = _embed_batch(batch_texts)
+            for idx, emb in zip(indices, embeddings):
+                results[idx] = emb
+            logger.debug("Embedded batch %d–%d", batch_start, batch_start + len(batch))
+        except Exception as e:
+            logger.error("Embedding batch %d–%d failed: %s", batch_start, batch_start + len(batch), e)
+            # Fill failed batch with zero vectors rather than crashing ingestion
+            for idx in indices:
+                results[idx] = zero_vector
+
+        # Small pause between batches to stay within rate limits
+        if batch_start + batch_size < len(to_embed):
+            time.sleep(0.3)
+
+    # Fill empty/whitespace texts with zero vectors
+    return [r if r is not None else zero_vector for r in results]
+
+
+def embed_single(text: str) -> list[float]:
+    """Embed a single text — convenience wrapper for query-time use."""
+    if not text.strip():
+        return [0.0] * cfg.EMBEDDING_DIM
+    return embed_texts([text])[0]
+
+
+def format_for_pgvector(embedding: list[float]) -> str:
+    """Format embedding as PostgreSQL vector literal string."""
+    return "[" + ",".join(f"{v:.8f}" for v in embedding) + "]"

package/knowledge_base/eval/__init__.py

@@ -0,0 +1,33 @@
+"""
+IGEL Knowledge Base Evaluation Framework
+=========================================
+Provides 5-dimensional scoring for test case generation quality:
+- Retrieval confidence
+- Domain confidence
+- Structural completeness
+- Script executability
+- Publish confidence
+"""
+from __future__ import annotations
+
+from knowledge_base.eval.scorers import (
+    RetrievalScorer,
+    DomainScorer,
+    StructuralScorer,
+    ExecutabilityScorer,
+    PublishScorer,
+    EvaluationResult,
+)
+from knowledge_base.eval.harness import EvaluationHarness
+from knowledge_base.eval.baseline import BaselineManager
+
+__all__ = [
+    "RetrievalScorer",
+    "DomainScorer",
+    "StructuralScorer",
+    "ExecutabilityScorer",
+    "PublishScorer",
+    "EvaluationResult",
+    "EvaluationHarness",
+    "BaselineManager",
+]