Knowledge Layer (v0.3 foundation)

Knowledge Layer (v0.3 foundation) Purpose The knowledge layer retrieves relevant site content for prompt augmentation (RAG). It follows the Clean Architecture contracts in 02-system-architecture-prompt.md while reusing the existing embeddings stack through a…

v5 README.md Download markdown Updated July 18, 2026

Knowledge Layer (v0.3 foundation)#

Purpose#

The knowledge layer retrieves relevant site content for prompt augmentation (RAG). It follows the Clean Architecture contracts in 02-system-architecture-prompt.md while reusing the existing embeddings stack through a legacy adapter.

Current Scope#

  • Domain contract: KnowledgeRetrieverInterface
  • Value object: KnowledgeChunk with optional source URL for citations
  • Application use case: RetrieveKnowledgeContext
  • Public widget grounding: PublicKnowledgeGroundingPolicy (sources-only when RAG enabled)
  • Legacy adapter: LegacyRagKnowledgeRetriever -> RagService
  • Used by legacy ChatService for public widget + agent SendChatMessage for admin (both return sources)
  • Indexed content types: posts, pages, extra public CPT (rag_indexable_post_types / teddy_indexable_post_types), WooCommerce products, PDF/CSV media uploads
  • Large catalogs: cursor option teddy_rag_ingest_cursor batches 25 items per cron tick; phases include uploads; filters teddy_indexable_products, teddy_indexable_posts, teddy_indexable_upload_mimes
  • Enrichment: KnowledgeContentEnricher (ACF + Elementor) + UploadDocumentExtractor (PDF/CSV)
  • Admin: Settings knowledge panel + REST GET/POST /knowledge/status|reindex|ingest; Settings UI upload for PDF/CSV
  • SEO domain tools: seo.meta.generate, seo.article.write, seo.article.audit

Feature Flag#

  • Setting key: enable_rag
  • Default: false

When RAG is first enabled, a background reindex is scheduled (~15s). Admins can also click Rebuild knowledge index now on Settings.

Main Classes#

  • src/Domain/Knowledge/KnowledgeChunk.php
  • src/Domain/Knowledge/KnowledgeRetrieverInterface.php
  • src/Application/Knowledge/KnowledgePromptComposer.php
  • src/Application/Knowledge/PublicKnowledgeGroundingPolicy.php
  • src/Application/UseCase/RetrieveKnowledgeContext.php
  • src/Infrastructure/Knowledge/LegacyRagKnowledgeRetriever.php
  • src/Services/RagService.php (search() + augment())
  • src/REST/KnowledgeController.php

Verification#

  • Unit tests: tests/Unit/KnowledgePromptComposerTest.php, tests/Unit/PublicKnowledgeGroundingPolicyTest.php, tests/Unit/MarkdownToHtmlTest.php
  • Integration: tests/Integration/RagServiceCursorTest.php (1000-product cursor simulation)
  • E2E: tests/e2e-rag.php, tests/e2e-rag-scale.php
  • Playwright admin smoke: TEDDY_E2E_PASS=*** npm run test:e2e:playwright (optional TEDDY_E2E_USER, default vinhnx)
  • Static analysis: composer phpstan