LangChain Audit Implementation - Code Quality Improvements

Summary

Implementation of findings from the LangChain audit report (03-LANGCHAIN-AUDIT-REPORT-01-01-2026.md). This PR addresses technical debt items and quick wins identified in the audit.

Changes Made

Task 1: Replace console.log with Logger ✅

File: backend/src/services/llm/adaptive-llm-factory.ts

• Added createLogger import and created service-level logger
• Replaced console.log → serviceLogger.debug() for structured output skip message
• Replaced console.warn → serviceLogger.warn() for withStructuredOutput failure
• Replaced debug console.log → serviceLogger.debug() for extraction chain creation

Task 2: Cache KG_DEBUG Environment Variable ✅

File: backend/src/services/llm/structured-output-parser.ts

• Added module-level constant: const KG_DEBUG_ENABLED = process.env.KG_DEBUG === 'true';
• Updated constructor to use cached value instead of reading env var on each instantiation

Task 3: Centralize Ollama URL Resolution ✅

New File: backend/src/config/ollama.config.ts

Created centralized utility with:

• getOllamaBaseUrl(tenantBaseUrl?) - Returns URL with fallback chain: tenant → env → default
• isOllamaConfigured(tenantBaseUrl?) - Checks if Ollama is explicitly configured
• OLLAMA_DEFAULT_URL - Exported constant (http://localhost:11434)

Updated Files (15+ files):

| Category | Files |
|----------|-------|
| Services | adaptive-llm-factory.ts, tenant-settings.service.ts |
| Workers | worker-init.ts |
| RAG Workflows | semantic-retrieval/workflow.ts, generate-response-node.ts, analyze-intent-node.ts, detect-filters-node.ts, call-llm-node.ts, extract-query-entities-node-llm.ts, generate-embedding-node.ts, semantic-search-node-vector.ts |
| Ingestion Workflows | calculate-embeddings-node-llm.ts, embed-chunks-node-llm.ts, enrich-relationships-node.ts |
| API Routes | embeddings.routes.ts, system-parameters.routes.ts |

Task 4: Content-Type-Aware Text Splitters ✅

File: backend/src/workflows/ingestion/document-chunking/nodes/chunk-content-node.ts

• Added getSeparatorsForFileType() helper function with smart separators for:
• Markdown: Headers first (\n## , \n### , \n#### )
• Code files: Class/function boundaries (\n\nclass , \n\nfunction , \n\ndef )
• HTML/XML: Tag boundaries (</div>, </p>, </section>)
• CSV/TSV: Row/field separators (\n, ,, \t)
• Default: Paragraph/sentence boundaries
• Added separators_strategy field to chunkerConfig for observability

Skipped

• TD-04 (Cohere direct fetch): Marked as acceptable in audit - uses direct fetch for Cohere reranking with proper error handling

---

Testing Checklist

Build Verification

• [ ] Run npm run build in backend directory - should compile without new errors
• Note: Pre-existing errors in semantic-cache.service.ts, memgraph.service.ts, output-filter.ts are unrelated to these changes

Unit Tests

• [ ] Run existing test suite: npm test
• [ ] Verify no regressions in LLM-related tests

Functional Testing

Ollama URL Centralization

• [ ] Verify Ollama connections work with default URL (no env var set)
• [ ] Verify OLLAMA_BASE_URL env var is respected when set
• [ ] Verify tenant-specific base URLs override env var
• [ ] Test embedding generation with Ollama
• [ ] Test LLM calls with Ollama provider

Logging Verification

• [ ] Verify adaptive-llm-factory logs appear correctly in log output
• [ ] Verify no console.log or console.warn output from LLM factory
• [ ] Check KG_DEBUG=true still enables debug output in structured-output-parser

Content-Type-Aware Chunking

• [ ] Test chunking a Markdown file - verify headers are preserved as chunk boundaries
• [ ] Test chunking a code file (.ts/.py) - verify function/class boundaries respected
• [ ] Test chunking an HTML file - verify tag boundaries respected
• [ ] Test chunking a plain text/PDF - verify default separators work
• [ ] Verify separators_strategy appears in processing_status chunkerConfig

Integration Testing

• [ ] Upload and process a document end-to-end
• [ ] Verify RAG query works with Ollama provider
• [ ] Verify knowledge graph extraction works with updated LLM factory

---

Files Modified

New Files

• backend/src/config/ollama.config.ts

Modified Files

• backend/src/services/llm/adaptive-llm-factory.ts
• backend/src/services/llm/structured-output-parser.ts
• backend/src/services/tenant/tenant-settings.service.ts
• backend/src/workers/shared/worker-init.ts
• backend/src/workflows/rag/semantic-retrieval/workflow.ts
• backend/src/workflows/rag/rag-response/nodes/generate-response-node.ts
• backend/src/workflows/rag/query-router/nodes/analyze-intent-node.ts
• backend/src/workflows/rag/query-router/nodes/detect-filters-node.ts
• backend/src/workflows/rag/llm-interaction/nodes/call-llm-node.ts
• backend/src/workflows/rag/graph-retrieval/nodes/extract-query-entities-node-llm.ts
• backend/src/workflows/rag/hybrid-retrieval/nodes/generate-embedding-node.ts
• backend/src/workflows/rag/graph-retrieval/nodes/semantic-search-node-vector.ts
• backend/src/workflows/ingestion/knowledge-graph-builder/nodes/calculate-embeddings-node-llm.ts
• backend/src/workflows/ingestion/generate-embeddings/nodes/embed-chunks-node-llm.ts
• backend/src/workflows/ingestion/knowledge-graph-builder/nodes/enrich-relationships-node.ts
• backend/src/workflows/ingestion/document-chunking/nodes/chunk-content-node.ts
• backend/src/api/routes/admin/embeddings.routes.ts
• backend/src/api/routes/admin/system-parameters.routes.ts

---

Related

• Audit Report: docs/Generated/audit reports/03-LANGCHAIN-AUDIT-REPORT-01-01-2026.md
• Branch: staging