release: v0.5.0 - Widget production-ready & instructor configuration

.env.example

@@ -25,6 +25,11 @@
 # Example: VEKTRA_LLM_API_BASE=http://localhost:8000/v1
 # VEKTRA_LLM_API_BASE=
 
+# Extra JSON body forwarded to litellm. Useful for vLLM thinking models
+# (Qwen3.5, DeepSeek-R1) to disable thinking mode.
+# Example: VEKTRA_LLM_EXTRA_BODY={"chat_template_kwargs": {"enable_thinking": false}}
+# VEKTRA_LLM_EXTRA_BODY=
+
 # Or set provider-specific keys directly:
 # OPENAI_API_KEY=sk-...
 # ANTHROPIC_API_KEY=sk-ant-...
@@ -83,6 +88,12 @@
 # VEKTRA_CONTEXT_CHUNK_RATIO=0.6
 # VEKTRA_PROMPT_TEMPLATES_DIR=
 
+# Default RAG grounding policy. Per-namespace override via
+# PATCH /api/v1/admin/namespaces/{id}/config.
+#   strict  - answer from retrieved context + history only
+#   hybrid  - fall back to model knowledge when confident
+# VEKTRA_PROMPT_GROUNDING_MODE=strict
+
 # Query rewriting (AdvancedQueryPipeline)
 # VEKTRA_QUERY_REWRITE_ENABLED=true
 # VEKTRA_QUERY_REWRITE_MODEL=
@@ -141,6 +152,14 @@
 # VEKTRA_AUDIT_RETENTION_DAYS=90
 # VEKTRA_EVAL_MODE=false
 
+# Persist QueryTrace rows for every query (DEBT-011). When unset, defaults
+# to true if vektra-analytics is configured, false otherwise.
+# VEKTRA_ANALYTICS_STORE_TRACES=
+
+# Log original and rewritten query text at debug level. Development only;
+# query text is otherwise redacted from logs.
+# VEKTRA_DEBUG_LOG_QUERIES=false
+
 # --------------------------------------------------------------------------
 # Security
 # --------------------------------------------------------------------------
@@ -174,3 +193,10 @@
 # Set to false when an external LMS (e.g. Moodle) manages enrollment.
 # When false, namespace is derived from JWT (namespace claim or course_id fallback).
 # VEKTRA_LEARN_REQUIRE_ENROLLMENT=true
+
+# Default visibility of the source-citations section in the chatbot widget
+# (FEAT-014). Resolution chain: data-show-sources attr (client) >
+# namespaces.config.show_sources (per-course) > this env var > hardcoded true.
+# The API always returns the full sources list; this flag only instructs the
+# widget whether to render them.
+# VEKTRA_LEARN_SHOW_SOURCES=true

.gemini/styleguide.md

@@ -1,4 +1,4 @@
-# Vektra coding conventions for Gemini Code Assist
+# Vektra RAG coding conventions for Gemini Code Assist
 
 ## General
 

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,5 +1,5 @@
 name: Bug report
-description: Report a bug in Vektra
+description: Report a bug in Vektra RAG
 labels: ["bug"]
 body:
   - type: markdown

.s2s/CONTEXT.md

@@ -140,7 +140,7 @@ See [architecture.md](architecture.md) for complete architecture documentation.
 - ChunkingStrategy: pluggable chunking. FixedSizeChunking (Phase 1), DualStrategyChunking with semantic splitting (Phase 2)
 - QueryPipeline: RAG pipeline abstraction returning QueryResponse + QueryTrace. Phase 2: AdvancedQueryPipeline with query rewriting (ARCH-061), reranking, hybrid search (implemented)
 - SafeguardHook: pre/post query safeguards (3 trust boundary points) with content modification support (ARCH-049)
-- EventEmitter: internal event hooks. NoOpEventEmitter (Phase 1), LogEventEmitter (Phase 2)
+- EventEmitter: internal event hooks. NoOpEventEmitter (Phase 1), WebhookEventEmitter (Phase 2: HMAC-SHA256 signed HTTP POST)
 
 **Key decisions** (64 total, 25 ADRs):
 - [ADR-0003](decisions/ADR-0003-modular-monolith-phase1.md): Modular monolith for Phase 1

.s2s/architecture.md

@@ -429,7 +429,7 @@ See [section 8.4](#84-deployment) for Docker Compose specification and resource
 - **ARCH-035 - EmbeddingProvider Protocol**: Dedicated Protocol for embedding generation. Separates embed_documents() from embed_query() for asymmetric models. Single shared instance between ingest and core. Configurable provider and model via env vars.
 - **ARCH-036 - QueryPipeline Protocol**: Abstraction of RAG query pipeline. execute() returns (QueryResponse, QueryTrace). Phase 1: SimpleQueryPipeline (embed -> search -> relevance_filter -> build_prompt -> LLM, with graceful degradation). relevance_filter applies minimum score threshold and overlap deduplication (ARCH-056). build_prompt calculates token budget from model context window (ARCH-055), renders composable Jinja2 templates (ARCH-054). Phase 2: AdvancedQueryPipeline adds query_rewrite (ARCH-061), query_classify, rerank, confidence scoring steps. Selectable via VEKTRA_QUERY_PIPELINE.
 - **ARCH-037 - ChunkingStrategy Protocol**: Abstraction of text chunking. Receives DocumentChunk stream, returns chunked stream. Phase 1: FixedSizeChunking. Selectable via VEKTRA_CHUNKING_STRATEGY.
-- **ARCH-038 - EventEmitter interface**: Internal event hooks with NoOp default. Emission points at document lifecycle, query completion, safeguard triggers, API key operations. Phase 2 (implemented): LogEventEmitter. WebhookEventEmitter with HMAC-SHA256 deferred to Phase 3.
+- **ARCH-038 - EventEmitter interface**: Internal event hooks with NoOp default. Emission points at document lifecycle, query completion, safeguard triggers, API key operations. Phase 2 (implemented): WebhookEventEmitter (HMAC-SHA256 signed HTTP POST, activated via `VEKTRA_WEBHOOK_URL`). LogEventEmitter (structlog-based) was scoped during planning but never implemented; the webhook path subsumed the use case.
 - **ARCH-039 - ProviderRegistry pattern**: Unified registry for all Protocol implementations. Dict-based in Phase 1, extensible to entry_points plugin discovery in Phase 2. Consistent VEKTRA_* env var configuration pattern.
 - **ARCH-040 - Forward-compatible data model**: Phase 1 schema includes fields for Phase 2 features: response_id and citation_id for feedback loops, document version and supersedes_id for versioning, deleted_at and deletion_reason for soft delete, index_version for zero-downtime reindex. All fields nullable/defaulted, no behavioral change in Phase 1.
 - **ARCH-041 - Audit/analytics separation**: QueryTrace (per-step timing, chunk refs, model info) emitted separately from audit log. QueryTrace does not contain query text or response content (REQ-051 compliance). Phase 1: structlog emission. Phase 2 (implemented): dedicated query_traces table with reporting API (vektra-analytics).
@@ -704,7 +704,7 @@ class EventEmitter(Protocol):
     async def emit(event_type: str, payload: dict) -> None
 ```
 
-Phase 1: NoOpEventEmitter. Emission points: document.indexed, document.failed, query.completed, safeguard.triggered, apikey.created, apikey.revoked. Phase 2 (implemented): LogEventEmitter (structlog-based event logging). WebhookEventEmitter with HMAC-SHA256 deferred to Phase 3.
+Phase 1: NoOpEventEmitter. Emission points: document.indexed, document.failed, query.completed, safeguard.triggered, apikey.created, apikey.revoked. Phase 2 (implemented): WebhookEventEmitter — HMAC-SHA256 signed HTTP POST with configurable URL, secret, and timeout (`VEKTRA_WEBHOOK_URL`, `VEKTRA_WEBHOOK_SECRET`, `VEKTRA_WEBHOOK_TIMEOUT`). LogEventEmitter was originally scoped for Phase 2 but never built; structlog already emits the same events at module boundaries, so the webhook path was prioritized instead.
 
 ### 8.3.1 Extended types
 
@@ -1989,7 +1989,7 @@ Quality scenarios (QS-xx) define measurable targets. Validation scenarios ([vali
 | TD-05 | No OAuth/OIDC | API keys sufficient for Phase 1 | Add for vektra-learn in Phase 2 |
 | TD-06 | Confidence scoring undefined | Algorithm needs research spike, confidence_tier field exists in QueryResponse | OQ-014, Phase 2 spike, field ready (ARCH-040) |
 | TD-07 | Dense-only vector search | Hybrid search Protocol ready (SearchMode enum), implementation deferred | REQ-050, swap PgvectorProvider or add QdrantVectorStoreProvider in Phase 2 (ARCH-051) |
-| TD-08 | NoOp event emission | EventEmitter hooks in place, no handler | REQ-061, swap to WebhookEventEmitter in Phase 2 |
+| TD-08 | NoOp event emission | EventEmitter hooks in place, no handler | REQ-061, WebhookEventEmitter implemented in Phase 2 |
 | TD-09 | Passthrough safeguards | SafeguardHook hooks in place, no enforcement | REQ-044, swap to Presidio-based in Phase 2 |
 | TD-10 | No sparse embeddings | SparseEmbeddingProvider Protocol defined, not registered | ARCH-053, register FastEmbedBM25Provider or SPLADEProvider in Phase 2 |
 
@@ -2133,7 +2133,7 @@ Quality scenarios (QS-xx) define measurable targets. Validation scenarios ([vali
 | REQ-058 Content type detection | ARCH-042 Magic bytes | Reliable dispatch, mismatch warnings |
 | REQ-059 LLM graceful degradation | ARCH-043 Graceful degradation, ARCH-056 Retrieval quality | Fallback model, context-only response, no-relevant-context path |
 | REQ-060 QueryTrace | ARCH-041 Audit/analytics separation | Per-step RAG tracing, GDPR-safe |
-| REQ-061 EventEmitter | ARCH-038 EventEmitter interface | NoOp Phase 1, LogEventEmitter Phase 2 |
+| REQ-061 EventEmitter | ARCH-038 EventEmitter interface | NoOp Phase 1, WebhookEventEmitter Phase 2 |
 | REQ-062 ProviderRegistry | ARCH-039 ProviderRegistry pattern | Unified provider configuration |
 | REQ-063 Metadata filtering | ARCH-044 Chunk metadata filtering | JSONB + GIN index, SearchFilters in search() |
 | REQ-064 Zero-downtime reindex | ARCH-045 Index version | Atomic version switch, no downtime |
@@ -2218,4 +2218,4 @@ Quality scenarios (QS-xx) define measurable targets. Validation scenarios ([vali
 *Version 1.9 - Quality scenarios: Section 10 expanded from 12 to 18 QS entries, quality tree restructured, 6 architecture-derived scenarios added (ARCH-043 degradation, ARCH-057 startup, ARCH-039 extensibility, ARCH-040 evolvability, NFR-008 retention, NFR-010 progress), validation scenario cross-reference (10.4)*
 *Version 1.9.1 - Conversational query rewriting: ARCH-061 (pre-retrieval query rewriting in AdvancedQueryPipeline), ADR-0023, rewrite.j2 template added to ARCH-054, ARCH-036 Phase 2 updated. Multilingual embedding note added to ADR-0013.*
 *Version 1.10 - OQ-018/OQ-019 resolution: ARCH-062 (admin UI server-side rendering, ADR-0024), ARCH-063 (learn chatbot widget, ADR-0025), ARCH-064 (Phase 2 hardware target 8GB/4CPU). Glossary: HTMX added. Deferred table: 3 entries added.*
-*Version 2.0 - Phase 2 delivery annotations: all Phase 2 features marked as implemented (v0.2.0). Component table expanded with vektra-analytics and vektra-learn. Protocol implementations updated: QdrantVectorStoreProvider, UnstructuredExtractor, DualStrategyChunking, AdvancedQueryPipeline, FastEmbedBM25Provider, LogEventEmitter. WebhookEventEmitter deferred to Phase 3.*
+*Version 2.0 - Phase 2 delivery annotations: all Phase 2 features marked as implemented (v0.2.0). Component table expanded with vektra-analytics and vektra-learn. Protocol implementations updated: QdrantVectorStoreProvider, UnstructuredExtractor, DualStrategyChunking, AdvancedQueryPipeline, FastEmbedBM25Provider, WebhookEventEmitter. LogEventEmitter was originally scoped for Phase 2 but never built; the webhook path subsumed the use case.*