feat: KnowledgeBase extension v0.1.6 — inline PDF viewer in browse tab

KnowledgeBase extension for EspoCRM: UI on top of the shira-hermes KB of
Israeli National Insurance law, regulations, and circulars.

Three modes:
- חיפוש — Hybrid (pgvector + tsvector) + Voyage rerank-2.5, returns ranked
  chunks with heading_path and citations.
- שאל את שירה — Full agent loop; Shira picks up search_insurance_kb as
  needed and returns a summary with citations.
- עיון — Browse all active sources. Click a source:
  - PDF source (ספר הליקויים, ספר המבחנים, circulars): renders the
    original PDF inline via an iframe proxied through the
    KnowledgeBasePdf EntryPoint, so the layout/columns/tables are
    preserved and Ctrl+F works natively.
  - TXT source (חוק הביטוח הלאומי scraped from Wikisource): falls back
    to the hierarchical chunk list with RTL styling.

Architecture:
- Controller: KnowledgeBase.php — thin proxy to shira-hermes /kb/*.
- Service: KnowledgeBaseService.php — shared curl plumbing; derives the
  shira-hermes base URL from the SmartAssistant integration record so
  there is no second admin config.
- EntryPoint: KnowledgeBasePdf.php — streams the PDF inline, wraps the
  body in a php://temp stream for setBody, applies a locked-down CSP.
- JS: views/kb/index.js branches on source.original_path; modes wired
  through the SmartAssistant fa_IR i18n convention.

Auth model:
- Browser → EspoCRM: session cookie / X-Api-Key (EspoCRM's existing auth).
- EspoCRM → shira-hermes: X-Api-Key from the SmartAssistant integration
  (never exposed to the browser).
- Portal users are blocked at both the Controller and the EntryPoint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,2 @@
+*.zip
+.DS_Store

build.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -euo pipefail
+
+VERSION=$(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")
+MODULE=$(python3 -c "import json; m=json.load(open('manifest.json')); print(m.get('module', m['name']))")
+ZIPNAME="${MODULE}-${VERSION}.zip"
+
+echo "Building $ZIPNAME..."
+rm -f "$ZIPNAME"
+zip -r "$ZIPNAME" manifest.json files/ scripts/ \
+  -x "*.DS_Store" "*__MACOSX*" "*.zip" 2>/dev/null || \
+zip -r "$ZIPNAME" manifest.json files/ \
+  -x "*.DS_Store" "*__MACOSX*" "*.zip"
+
+echo "✓ Built: $ZIPNAME ($(du -h "$ZIPNAME" | cut -f1))"

files/client/custom/modules/knowledge-base/res/templates/kb/index.tpl

@@ -0,0 +1,59 @@
+<div class="kb-page" dir="rtl">
+    <div class="page-header">
+        <h3>בסיס ידע — ביטוח לאומי</h3>
+    </div>
+
+    <ul class="nav nav-tabs" style="margin-bottom:12px;">
+        <li class="{{#ifEqual mode 'search'}}active{{/ifEqual}}">
+            <a href="#" role="button" data-action="switchMode" data-mode="search">חיפוש</a>
+        </li>
+        <li class="{{#ifEqual mode 'ask'}}active{{/ifEqual}}">
+            <a href="#" role="button" data-action="switchMode" data-mode="ask">שאל את שירה</a>
+        </li>
+        <li class="{{#ifEqual mode 'browse'}}active{{/ifEqual}}">
+            <a href="#" role="button" data-action="switchMode" data-mode="browse">עיון</a>
+        </li>
+    </ul>
+
+    {{#ifEqual mode 'search'}}
+    <div class="kb-search-box" style="margin-bottom:12px;">
+        <div class="form-inline" style="display:flex;gap:8px;flex-wrap:wrap;">
+            <input type="text" class="form-control" data-name="query"
+                   placeholder="מונחי חיפוש…"
+                   style="flex:1 1 320px;min-width:280px;" />
+            <select class="form-control" data-name="kind" style="flex:0 0 auto;">
+                <option value="any">כל הסוגים</option>
+                <option value="law">חוק</option>
+                <option value="regulation">תקנות</option>
+                <option value="circular">חוזרים</option>
+            </select>
+            <button type="button" class="btn btn-primary" data-action="submit">חפש</button>
+        </div>
+        <div class="small text-muted" style="margin-top:6px;">
+            חיפוש Hybrid: וקטורי + מילולי + rerank. מחזיר עד 8 קטעים רלוונטיים.
+        </div>
+    </div>
+    {{/ifEqual}}
+
+    {{#ifEqual mode 'ask'}}
+    <div class="kb-search-box" style="margin-bottom:12px;">
+        <div class="form-inline" style="display:flex;gap:8px;flex-wrap:wrap;">
+            <input type="text" class="form-control" data-name="query"
+                   placeholder="שאלה בשפה חופשית…"
+                   style="flex:1 1 320px;min-width:280px;" />
+            <button type="button" class="btn btn-primary" data-action="submit">שאל את שירה</button>
+        </div>
+        <div class="small text-muted" style="margin-top:6px;">
+            שירה תחפש בבסיס הידע ותחזיר תשובה מסוכמת עם ציטוטים.
+        </div>
+    </div>
+    {{/ifEqual}}
+
+    {{#ifEqual mode 'browse'}}
+    <div class="kb-sources panel panel-default" style="padding:12px;">
+        <div class="text-muted">טוען מקורות…</div>
+    </div>
+    {{/ifEqual}}
+
+    <div class="kb-results" style="margin-top:12px;"></div>
+</div>

files/client/custom/modules/knowledge-base/src/controllers/kb.js

@@ -0,0 +1,12 @@
+define('modules/knowledge-base/controllers/kb', ['controller'], function (Dep) {
+
+    return Dep.extend({
+
+        // Default action when the user clicks the "Knowledge Base" navbar tab.
+        actionIndex: function () {
+            this.main('modules/knowledge-base/views/kb/index', {});
+        },
+
+    });
+
+});

files/client/custom/modules/knowledge-base/src/views/dashlets/kb-search.js

@@ -0,0 +1,69 @@
+define('modules/knowledge-base/views/dashlets/kb-search', ['views/dashlets/abstract/base'], function (Dep) {
+
+    return Dep.extend({
+
+        name: 'KbSearch',
+
+        templateContent: `
+            <div dir="rtl" style="padding:8px;">
+                <div style="display:flex;gap:6px;">
+                    <input type="text" class="form-control input-sm" data-name="query"
+                           placeholder="חפש בבסיס הידע…" style="flex:1;" />
+                    <button type="button" class="btn btn-primary btn-sm" data-action="submit">חפש</button>
+                </div>
+                <div class="kb-dashlet-results" style="margin-top:8px;max-height:300px;overflow-y:auto;"></div>
+                <div style="margin-top:6px;">
+                    <a href="#KnowledgeBase" class="small">פתח בבסיס הידע המלא →</a>
+                </div>
+            </div>
+        `,
+
+        events: {
+            'click [data-action="submit"]': function () {
+                this.runSearch();
+            },
+            'keypress input[data-name="query"]': function (e) {
+                if (e.which === 13) this.runSearch();
+            },
+        },
+
+        runSearch: function () {
+            const query = (this.$el.find('input[data-name="query"]').val() || '').trim();
+            if (!query) return;
+            const $r = this.$el.find('.kb-dashlet-results');
+            $r.html('<div class="text-muted small">מחפש…</div>');
+            Espo.Ajax.postRequest('KnowledgeBase/action/search', {
+                query: query,
+                kind: 'any',
+                topK: 5,
+            }).then(res => this.renderHits(res.hits || []))
+              .catch(err => {
+                  $r.html('<div class="alert alert-danger small">' + ((err && err.statusText) || 'Error') + '</div>');
+              });
+        },
+
+        renderHits: function (hits) {
+            const $r = this.$el.find('.kb-dashlet-results');
+            if (!hits.length) {
+                $r.html('<div class="text-muted small">לא נמצאו תוצאות.</div>');
+                return;
+            }
+            const esc = s => String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+            const kindHe = {law: 'חוק', regulation: 'תקנה', circular: 'חוזר'};
+            const rows = hits.map(h => {
+                const kind = kindHe[h.kind] || h.kind;
+                const ident = h.identifier ? ' ' + esc(h.identifier) : '';
+                const ref = h.section_ref || h.heading_path || '';
+                const preview = esc((h.content || '').slice(0, 200)) + ((h.content || '').length > 200 ? '…' : '');
+                return `<div style="margin-bottom:8px;padding:6px;border-bottom:1px solid #eee;">
+                    <div class="small"><strong>[${kind}${ident}]</strong> ${esc(h.title || '')}
+                      ${ref ? '<span class="text-muted"> — ' + esc(ref) + '</span>' : ''}</div>
+                    <div class="small text-muted" style="white-space:pre-wrap;margin-top:3px;">${preview}</div>
+                  </div>`;
+            }).join('');
+            $r.html(rows);
+        },
+
+    });
+
+});

files/client/custom/modules/knowledge-base/src/views/kb/index.js

@@ -0,0 +1,289 @@
+define('modules/knowledge-base/views/kb/index', ['view'], function (Dep) {
+
+    return Dep.extend({
+
+        template: 'knowledge-base:kb/index',
+
+        // Active mode: 'search' (default) | 'ask' | 'browse'
+        mode: 'search',
+        kind: 'any',
+
+        data: function () {
+            return {
+                mode: this.mode,
+                kind: this.kind,
+            };
+        },
+
+        events: {
+            'click [data-action="switchMode"]': function (e) {
+                e.preventDefault();
+                const target = $(e.currentTarget).data('mode');
+                if (target === this.mode) return;
+                this.mode = target;
+                this.reRender();
+            },
+            'click [data-action="submit"]': function (e) {
+                if (e && e.preventDefault) e.preventDefault();
+                this.runQuery();
+            },
+            'keypress input[data-name="query"]': function (e) {
+                if (e.which === 13) {
+                    e.preventDefault();
+                    this.runQuery();
+                }
+            },
+            'change select[data-name="kind"]': function (e) {
+                this.kind = $(e.currentTarget).val();
+            },
+            'click [data-action="viewSource"]': function (e) {
+                e.preventDefault();
+                const id = parseInt($(e.currentTarget).data('id'), 10);
+                if (id) this.openSource(id);
+            },
+        },
+
+        setup: function () {
+            // setTitle is only available on main.js; on a plain `view` we set
+            // document.title directly and let EspoCRM's navbar pick up the
+            // scopeName translation.
+            const label = this.translate('KnowledgeBase', 'scopeNames');
+            if (label && label !== 'KnowledgeBase') {
+                document.title = label;
+            }
+        },
+
+        afterRender: function () {
+            // Load the source list up front so the browse tab is instant when
+            // the user clicks it.
+            if (!this._sourcesPromise) {
+                this._sourcesPromise = Espo.Ajax.getRequest('KnowledgeBase/action/sources')
+                    .then(res => {
+                        this._sources = res.sources || [];
+                        this.renderSourcesList();
+                    })
+                    .catch(err => {
+                        console.error('KB: failed to load sources', err);
+                    });
+            } else if (this._sources) {
+                this.renderSourcesList();
+            }
+            // Focus the input on every render so users can start typing right away.
+            const $input = this.$el.find('input[data-name="query"]');
+            if ($input.length) $input.trigger('focus');
+        },
+
+        runQuery: function () {
+            const query = (this.$el.find('input[data-name="query"]').val() || '').trim();
+            if (!query) return;
+            const kind = this.$el.find('select[data-name="kind"]').val() || 'any';
+            this.kind = kind;
+
+            if (this.mode === 'search') {
+                this.runSearch(query, kind);
+            } else if (this.mode === 'ask') {
+                this.runAsk(query);
+            }
+        },
+
+        runSearch: function (query, kind) {
+            this.setLoading(true);
+            Espo.Ajax.postRequest('KnowledgeBase/action/search', {
+                query: query,
+                kind: kind,
+                topK: 8,
+            }).then(res => {
+                this.setLoading(false);
+                this.renderSearchResults(res.hits || []);
+            }).catch(err => {
+                this.setLoading(false);
+                this.showError(err);
+            });
+        },
+
+        runAsk: function (message) {
+            this.setLoading(true);
+            Espo.Ajax.postRequest('KnowledgeBase/action/ask', {
+                message: message,
+            }).then(res => {
+                this.setLoading(false);
+                this.renderAskAnswer(res.text || '');
+            }).catch(err => {
+                this.setLoading(false);
+                this.showError(err);
+            });
+        },
+
+        renderSearchResults: function (hits) {
+            const $results = this.$el.find('.kb-results');
+            if (!hits.length) {
+                $results.html('<div class="text-muted">לא נמצאו תוצאות.</div>');
+                return;
+            }
+            const kindHe = {law: 'חוק', regulation: 'תקנה', circular: 'חוזר'};
+            const rows = hits.map(h => {
+                const kind = kindHe[h.kind] || h.kind;
+                const ident = h.identifier ? ' ' + this.escape(h.identifier) : '';
+                const path = h.heading_path || h.section_ref || '';
+                const pub = h.published_at ? ' · פורסם ' + h.published_at : '';
+                // Content is rendered inside a white-space:pre-wrap block —
+                // no need to convert \n to <br>; that would double-break.
+                const content = this.escape(h.content || '');
+                const srcLink = h.source_url
+                    ? `<a href="${this.escape(h.source_url)}" target="_blank" rel="noopener">מקור</a>`
+                    : '';
+                const bodyStyle =
+                    'direction:rtl;unicode-bidi:plaintext;white-space:pre-wrap;' +
+                    'font-family:"Segoe UI",Arial,sans-serif;line-height:1.7;text-align:right;';
+                return `
+                    <div class="kb-hit panel panel-default" style="margin-bottom:10px;">
+                      <div class="panel-heading" style="direction:rtl;text-align:right;">
+                        <strong>[${kind}${ident}]</strong> ${this.escape(h.title || '')}
+                        ${path ? ' — <span class="text-muted">' + this.escape(path) + '</span>' : ''}
+                        <span class="text-muted small">${pub}</span>
+                      </div>
+                      <div class="panel-body" style="${bodyStyle}">${content}</div>
+                      ${srcLink ? '<div class="panel-footer small">' + srcLink + '</div>' : ''}
+                    </div>`;
+            }).join('');
+            $results.html(rows);
+        },
+
+        renderAskAnswer: function (text) {
+            const $results = this.$el.find('.kb-results');
+            // Shira replies in markdown; render through EspoCRM's markdown
+            // helper when available, otherwise fall back to escaped text.
+            let html;
+            try {
+                const helper = this.getHelper && this.getHelper();
+                if (helper && typeof helper.transformMarkdownText === 'function') {
+                    html = helper.transformMarkdownText(text || '');
+                    if (html && html.toString) html = html.toString();
+                }
+            } catch (e) { /* fall through */ }
+            if (!html) {
+                html = '<div style="white-space:pre-wrap;">' + this.escape(text || '') + '</div>';
+            }
+            $results.html('<div class="kb-answer panel panel-info"><div class="panel-body">' + html + '</div></div>');
+        },
+
+        renderSourcesList: function () {
+            const $list = this.$el.find('.kb-sources');
+            if (!$list.length) return;
+            if (!this._sources || !this._sources.length) {
+                $list.html('<div class="text-muted">אין מקורות.</div>');
+                return;
+            }
+            const kindHe = {law: 'חוק', regulation: 'תקנות', circular: 'חוזרים'};
+            const grouped = {law: [], regulation: [], circular: []};
+            this._sources.forEach(s => {
+                if (grouped[s.kind]) grouped[s.kind].push(s);
+            });
+            const sections = Object.keys(grouped).filter(k => grouped[k].length).map(k => {
+                const items = grouped[k].map(s => {
+                    const ident = s.identifier ? ' · ' + this.escape(s.identifier) : '';
+                    const pub = s.published_at ? ' · ' + s.published_at : '';
+                    return `<li>
+                        <a href="#" role="button" data-action="viewSource" data-id="${s.id}">
+                          ${this.escape(s.title)}
+                        </a>
+                        <span class="text-muted small">${ident}${pub} · ${s.chunk_count} קטעים</span>
+                      </li>`;
+                }).join('');
+                return `<h4>${kindHe[k]}</h4><ul>${items}</ul>`;
+            }).join('');
+            $list.html(sections);
+        },
+
+        openSource: function (sourceId) {
+            const $results = this.$el.find('.kb-results');
+            $results.html('<div class="text-muted">טוען מסמך…</div>');
+            Espo.Ajax.getRequest('KnowledgeBase/action/chunks', {sourceId: sourceId})
+                .then(res => {
+                    const src = res.source || {};
+                    const chunks = res.chunks || [];
+                    const ident = src.identifier ? ' · ' + this.escape(src.identifier) : '';
+                    const pub = src.published_at ? ' · פורסם ' + src.published_at : '';
+                    const head = `
+                        <div class="panel panel-default">
+                          <div class="panel-heading">
+                            <h3 style="margin:0;">${this.escape(src.title || '')}</h3>
+                            <small class="text-muted">${ident}${pub}</small>
+                          </div>
+                        </div>`;
+
+                    // If the source is a PDF (original_path ends in .pdf),
+                    // render it inline via the EntryPoint proxy. Ctrl+F works
+                    // inside the iframe via the browser's native PDF viewer,
+                    // which also gives zoom, print, and download controls.
+                    const originalPath = (src.original_path || '').toLowerCase();
+                    if (originalPath.endsWith('.pdf')) {
+                        const pdfUrl = '?entryPoint=KnowledgeBasePdf&sourceId=' + encodeURIComponent(sourceId);
+                        const chunksCount = chunks.length;
+                        const iframe = `
+                            <iframe
+                                src="${pdfUrl}"
+                                style="width:100%;height:80vh;border:1px solid #ddd;background:#fafafa;"
+                                title="${this.escape(src.title || '')}"></iframe>
+                            <div class="small text-muted" style="margin-top:6px;direction:rtl;text-align:right;">
+                                מוצג ה-PDF המקורי. החיפוש בעמוד &quot;חיפוש&quot; ו-&quot;שאל את שירה&quot; עובד על ${chunksCount} קטעי הטקסט שחולצו מהמסמך הזה.
+                            </div>`;
+                        $results.html(head + iframe);
+                        return;
+                    }
+                    // Hebrew content with mixed LTR (numbers, Latin, ־) renders
+                    // correctly only when we force RTL direction and tell the
+                    // bidi algorithm to isolate each paragraph. Plain white-space:
+                    // pre-wrap alone preserves line breaks but leaves the bidi
+                    // resolution up to the browser, which produces jumbled
+                    // glyphs on PDF-extracted Hebrew + Latin runs.
+                    const contentStyle =
+                        'direction:rtl;' +
+                        'unicode-bidi:plaintext;' +
+                        'white-space:pre-wrap;' +
+                        'font-family:"Segoe UI",Arial,sans-serif;' +
+                        'line-height:1.7;' +
+                        'text-align:right;';
+                    const body = chunks.map(c => {
+                        const heading = c.heading_path || c.section_ref || '';
+                        return `<div class="kb-chunk" style="margin-bottom:14px;padding:10px;border:1px solid #eee;border-radius:4px;">
+                            ${heading ? '<div class="text-muted" style="font-size:0.85em;margin-bottom:6px;direction:rtl;text-align:right;">' + this.escape(heading) + '</div>' : ''}
+                            <div style="${contentStyle}">${this.escape(c.content)}</div>
+                          </div>`;
+                    }).join('');
+                    $results.html(head + body);
+                })
+                .catch(err => this.showError(err));
+        },
+
+        setLoading: function (loading) {
+            const $btn = this.$el.find('[data-action="submit"]');
+            if (loading) {
+                $btn.prop('disabled', true).text(this.translate('Loading', 'labels'));
+                this.$el.find('.kb-results').html('<div class="text-muted">מחפש…</div>');
+            } else {
+                $btn.prop('disabled', false).text(this.getSubmitLabel());
+            }
+        },
+
+        getSubmitLabel: function () {
+            if (this.mode === 'ask') return 'שאל את שירה';
+            return 'חפש';
+        },
+
+        showError: function (err) {
+            const msg = (err && err.responseText) || (err && err.message) || 'Unknown error';
+            this.$el.find('.kb-results').html(
+                '<div class="alert alert-danger">' + this.escape(msg.slice(0, 400)) + '</div>'
+            );
+        },
+
+        escape: function (str) {
+            return String(str || '')
+                .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+                .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+        },
+
+    });
+
+});

files/custom/Espo/Modules/KnowledgeBase/Controllers/KnowledgeBase.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Espo\Modules\KnowledgeBase\Controllers;
+
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\Forbidden;
+use Espo\Core\InjectableFactory;
+use Espo\Core\Acl;
+use Espo\Modules\KnowledgeBase\Services\KnowledgeBaseService;
+use Espo\Entities\User;
+
+/**
+ * Thin proxy controller. The EspoCRM UI talks to these actions; each
+ * action forwards to shira-hermes (/kb/*) with the shared API key held
+ * server-side. The browser never sees the shira-hermes key.
+ */
+class KnowledgeBase
+{
+    private InjectableFactory $injectableFactory;
+    private Acl $acl;
+    private User $user;
+
+    public function __construct(InjectableFactory $injectableFactory, Acl $acl, User $user)
+    {
+        $this->injectableFactory = $injectableFactory;
+        $this->acl = $acl;
+        $this->user = $user;
+    }
+
+    private function getService(): KnowledgeBaseService
+    {
+        return $this->injectableFactory->create(KnowledgeBaseService::class);
+    }
+
+    private function checkAccess(): void
+    {
+        // Anyone with a portal-less account (regular users) can read the KB.
+        if ($this->user->isPortal()) {
+            throw new Forbidden('Portal users have no KB access.');
+        }
+    }
+
+    public function postActionSearch(Request $request, Response $response): array
+    {
+        $this->checkAccess();
+        $data = $request->getParsedBody();
+
+        if (empty($data->query)) {
+            throw new BadRequest('query is required.');
+        }
+
+        return $this->getService()->search(
+            trim($data->query),
+            $data->kind ?? 'any',
+            (int) ($data->top_k ?? $data->topK ?? 8)
+        );
+    }
+
+    public function getActionSources(Request $request, Response $response): array
+    {
+        $this->checkAccess();
+        return $this->getService()->listSources();
+    }
+
+    public function getActionChunks(Request $request, Response $response): array
+    {
+        $this->checkAccess();
+        $sourceId = $request->getQueryParam('sourceId');
+
+        if (!$sourceId || !is_numeric($sourceId)) {
+            throw new BadRequest('sourceId (numeric) is required.');
+        }
+
+        return $this->getService()->sourceChunks((int) $sourceId);
+    }
+
+    public function postActionAsk(Request $request, Response $response): array
+    {
+        $this->checkAccess();
+        $data = $request->getParsedBody();
+
+        if (empty($data->message)) {
+            throw new BadRequest('message is required.');
+        }
+
+        return $this->getService()->ask(
+            trim($data->message),
+            $data->conversationId ?? null,
+            $data->conversationHistory ?? []
+        );
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/EntryPoints/KnowledgeBasePdf.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace Espo\Modules\KnowledgeBase\EntryPoints;
+
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\EntryPoint\EntryPoint;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\Error;
+use Espo\Core\Exceptions\Forbidden;
+use Espo\Core\Exceptions\NotFound;
+use Espo\Core\InjectableFactory;
+use Espo\Entities\User;
+use Espo\Modules\KnowledgeBase\Services\KnowledgeBaseService;
+
+/**
+ * Streams the original PDF of a KB source to an iframe in the browse tab.
+ * Access: `?entryPoint=KnowledgeBasePdf&sourceId=<id>`.
+ *
+ * We intentionally do NOT reuse EspoCRM's Attachment ACL model — KB sources
+ * are not Entities. The gate is the same rule as the Controller: no portal
+ * users. Anyone with a regular user account in the CRM can read the KB.
+ */
+class KnowledgeBasePdf implements EntryPoint
+{
+    public function __construct(
+        private InjectableFactory $injectableFactory,
+        private User $user,
+    ) {}
+
+    public function run(Request $request, Response $response): void
+    {
+        if ($this->user->isPortal()) {
+            throw new Forbidden('Portal users have no KB access.');
+        }
+
+        $sourceId = $request->getQueryParam('sourceId');
+        if (!$sourceId || !is_numeric($sourceId)) {
+            throw new BadRequest('sourceId (numeric) is required.');
+        }
+
+        $service = $this->injectableFactory->create(KnowledgeBaseService::class);
+
+        try {
+            $pdf = $service->getPdfBinary((int) $sourceId);
+        } catch (NotFound | Forbidden | BadRequest $e) {
+            throw $e;
+        } catch (\Throwable $e) {
+            throw new Error('Failed to fetch PDF: ' . $e->getMessage());
+        }
+
+        $body = (string) ($pdf['body'] ?? '');
+        $contentType = (string) ($pdf['contentType'] ?? 'application/pdf');
+        $filename = (string) ($pdf['filename'] ?? ('source-' . $sourceId . '.pdf'));
+
+        if ($body === '') {
+            throw new Error('Empty PDF body');
+        }
+
+        // Disposition: inline so the browser renders rather than downloads.
+        // Quote-escape the ASCII fallback; add RFC 5987 encoded UTF-8 for the
+        // real Hebrew filename.
+        $asciiFallback = 'source-' . (int) $sourceId . '.pdf';
+        $utf8Encoded = rawurlencode($filename);
+        $disposition = sprintf(
+            'inline; filename="%s"; filename*=UTF-8\'\'%s',
+            $asciiFallback,
+            $utf8Encoded,
+        );
+
+        // setBody() expects a PSR StreamInterface, not a raw string. Wrap
+        // the binary in an in-memory php://temp stream so the ResponseWrapper
+        // can stream it to the client without buffering twice.
+        $stream = fopen('php://temp', 'w+b');
+        fwrite($stream, $body);
+        rewind($stream);
+        $psrStream = \GuzzleHttp\Psr7\Utils::streamFor($stream);
+
+        $response
+            ->setHeader('Content-Type', $contentType)
+            ->setHeader('Content-Disposition', $disposition)
+            ->setHeader('Content-Length', (string) strlen($body))
+            ->setHeader('X-Content-Type-Options', 'nosniff')
+            ->setHeader('Cache-Control', 'private, max-age=300')
+            // Downloading via the attachment entry point uses a locked-down
+            // CSP; we do the same here to keep inline viewing safe.
+            ->setHeader('Content-Security-Policy', "default-src 'self'")
+            ->setBody($psrStream);
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/en_US/Global.json

@@ -0,0 +1,8 @@
+{
+    "scopeNames": {
+        "KnowledgeBase": "Knowledge Base"
+    },
+    "scopeNamesPlural": {
+        "KnowledgeBase": "Knowledge Base"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/en_US/KnowledgeBase.json

@@ -0,0 +1,13 @@
+{
+    "labels": {
+        "Knowledge Base": "Knowledge Base",
+        "Search": "Search",
+        "Ask Shira": "Ask Shira",
+        "Browse": "Browse",
+        "Loading": "Loading…",
+        "No results": "No results"
+    },
+    "dashlets": {
+        "KbSearch": "KB Search"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/fa_IR/Global.json

@@ -0,0 +1,8 @@
+{
+    "scopeNames": {
+        "KnowledgeBase": "בסיס ידע"
+    },
+    "scopeNamesPlural": {
+        "KnowledgeBase": "בסיס ידע"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/fa_IR/KnowledgeBase.json

@@ -0,0 +1,13 @@
+{
+    "labels": {
+        "Knowledge Base": "בסיס ידע",
+        "Search": "חיפוש",
+        "Ask Shira": "שאל את שירה",
+        "Browse": "עיון",
+        "Loading": "טוען…",
+        "No results": "לא נמצאו תוצאות"
+    },
+    "dashlets": {
+        "KbSearch": "חיפוש בבסיס ידע"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/he_IL/Global.json

@@ -0,0 +1,8 @@
+{
+    "scopeNames": {
+        "KnowledgeBase": "בסיס ידע"
+    },
+    "scopeNamesPlural": {
+        "KnowledgeBase": "בסיס ידע"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/i18n/he_IL/KnowledgeBase.json

@@ -0,0 +1,13 @@
+{
+    "labels": {
+        "Knowledge Base": "בסיס ידע",
+        "Search": "חיפוש",
+        "Ask Shira": "שאל את שירה",
+        "Browse": "עיון",
+        "Loading": "טוען…",
+        "No results": "לא נמצאו תוצאות"
+    },
+    "dashlets": {
+        "KbSearch": "חיפוש בבסיס ידע"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/metadata/app/dashlets.json

@@ -0,0 +1,6 @@
+{
+    "KbSearch": {
+        "view": "modules/knowledge-base/views/dashlets/kb-search",
+        "aclScope": "KnowledgeBase"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/metadata/app/entryPoints.json

@@ -0,0 +1,5 @@
+{
+    "KnowledgeBasePdf": {
+        "className": "Espo\\Modules\\KnowledgeBase\\EntryPoints\\KnowledgeBasePdf"
+    }
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/metadata/clientDefs/KnowledgeBase.json

@@ -0,0 +1,4 @@
+{
+    "controller": "modules/knowledge-base/controllers/kb",
+    "iconClass": "fas fa-book"
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/metadata/scopes/KnowledgeBase.json

@@ -0,0 +1,4 @@
+{
+    "tab": true,
+    "module": "KnowledgeBase"
+}

files/custom/Espo/Modules/KnowledgeBase/Resources/routes.json

@@ -0,0 +1,34 @@
+[
+    {
+        "route": "/KnowledgeBase/action/search",
+        "method": "post",
+        "params": {
+            "controller": "KnowledgeBase",
+            "action": "search"
+        }
+    },
+    {
+        "route": "/KnowledgeBase/action/sources",
+        "method": "get",
+        "params": {
+            "controller": "KnowledgeBase",
+            "action": "sources"
+        }
+    },
+    {
+        "route": "/KnowledgeBase/action/chunks",
+        "method": "get",
+        "params": {
+            "controller": "KnowledgeBase",
+            "action": "chunks"
+        }
+    },
+    {
+        "route": "/KnowledgeBase/action/ask",
+        "method": "post",
+        "params": {
+            "controller": "KnowledgeBase",
+            "action": "ask"
+        }
+    }
+]

files/custom/Espo/Modules/KnowledgeBase/Services/KnowledgeBaseService.php

@@ -0,0 +1,251 @@
+<?php
+
+namespace Espo\Modules\KnowledgeBase\Services;
+
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\Error;
+use Espo\Core\Exceptions\NotFound;
+use Espo\Core\Utils\Config;
+use Espo\Core\Utils\Log;
+use Espo\ORM\EntityManager;
+
+/**
+ * Thin HTTP client over shira-hermes `/kb/*` endpoints. Reuses the
+ * SmartAssistant integration record for connection details: the same
+ * shira-hermes instance hosts both the chat webhook and the KB API, so
+ * deriving the KB base URL from SmartAssistant's webhookUrl keeps
+ * everything in one place and avoids a second admin form.
+ */
+class KnowledgeBaseService
+{
+    private EntityManager $entityManager;
+    private Config $config;
+    private Log $log;
+
+    public function __construct(EntityManager $entityManager, Config $config, Log $log)
+    {
+        $this->entityManager = $entityManager;
+        $this->config = $config;
+        $this->log = $log;
+    }
+
+    public function search(string $query, string $kind, int $topK): array
+    {
+        $topK = max(1, min(15, $topK));
+        if (!in_array($kind, ['any', 'law', 'regulation', 'circular'], true)) {
+            $kind = 'any';
+        }
+
+        return $this->post('/kb/search', [
+            'query' => $query,
+            'kind' => $kind,
+            'top_k' => $topK,
+        ]);
+    }
+
+    public function listSources(): array
+    {
+        return $this->get('/kb/sources');
+    }
+
+    public function sourceChunks(int $sourceId): array
+    {
+        return $this->get('/kb/source/' . $sourceId . '/chunks');
+    }
+
+    public function ask(string $message, ?string $conversationId, array $history): array
+    {
+        return $this->post('/kb/ask', [
+            'message' => $message,
+            'conversation_id' => $conversationId,
+            'conversation_history' => $history,
+        ]);
+    }
+
+    /**
+     * Fetch the original PDF bytes of a source from shira-hermes.
+     *
+     * @return array{body:string, contentType:string, filename:string}
+     * @throws NotFound when the source doesn't exist in the KB
+     * @throws BadRequest when the source has no PDF (stored as plain text)
+     * @throws Error on transport or upstream 5xx errors
+     */
+    public function getPdfBinary(int $sourceId): array
+    {
+        $resp = $this->requestBinary('GET', '/kb/source/' . $sourceId . '/pdf');
+
+        $status = $resp['status'];
+        if ($status === 404) {
+            throw new NotFound('KB source not found.');
+        }
+        if ($status === 409) {
+            throw new BadRequest('This source has no PDF original.');
+        }
+        if ($status < 200 || $status >= 300) {
+            $this->log->error("KnowledgeBase: PDF HTTP {$status}");
+            throw new Error("Knowledge Base returned HTTP {$status}");
+        }
+
+        // Parse the UTF-8 filename from Content-Disposition if present, fall
+        // back to a generic name. The EntryPoint will re-emit the same shape.
+        $filename = 'source-' . $sourceId . '.pdf';
+        if (preg_match("/filename\\*=UTF-8''([^;\\s]+)/i", $resp['disposition'] ?? '', $m)) {
+            $filename = rawurldecode($m[1]);
+        }
+
+        return [
+            'body' => $resp['body'],
+            'contentType' => $resp['contentType'] ?: 'application/pdf',
+            'filename' => $filename,
+        ];
+    }
+
+    // ---- HTTP helpers ----------------------------------------------------
+
+    private function getBaseUrl(): string
+    {
+        $integration = $this->entityManager->getEntityById('Integration', 'SmartAssistant');
+        if (!$integration || !$integration->get('enabled')) {
+            throw new Error('SmartAssistant integration is not enabled; cannot reach shira-hermes KB.');
+        }
+        $data = $integration->get('data') ?? (object) [];
+        $webhookUrl = $data->webhookUrl ?? null;
+        if (!$webhookUrl) {
+            throw new Error('SmartAssistant webhook URL is not configured.');
+        }
+        // The webhook URL typically looks like: https://shira.dev.marcus-law.co.il/api/smart-assistant/chat
+        // We want the origin only — strip any path and trailing slash.
+        $parts = parse_url($webhookUrl);
+        if (!$parts || empty($parts['scheme']) || empty($parts['host'])) {
+            throw new Error('Webhook URL is not parseable.');
+        }
+        $origin = $parts['scheme'] . '://' . $parts['host'];
+        if (!empty($parts['port'])) {
+            $origin .= ':' . $parts['port'];
+        }
+        return $origin;
+    }
+
+    private function getApiKey(): ?string
+    {
+        $integration = $this->entityManager->getEntityById('Integration', 'SmartAssistant');
+        if (!$integration || !$integration->get('enabled')) {
+            return null;
+        }
+        $data = $integration->get('data') ?? (object) [];
+        return $data->apiKey ?? null;
+    }
+
+    private function get(string $path): array
+    {
+        return $this->request('GET', $path, null);
+    }
+
+    private function post(string $path, array $payload): array
+    {
+        return $this->request('POST', $path, $payload);
+    }
+
+    /**
+     * Variant of request() for binary responses (PDFs). No json_decode; splits
+     * the response into headers + body so callers can see Content-Type and
+     * Content-Disposition.
+     *
+     * @return array{body:string, contentType:string, disposition:string, status:int}
+     */
+    private function requestBinary(string $method, string $path): array
+    {
+        $url = $this->getBaseUrl() . $path;
+        $apiKey = $this->getApiKey();
+
+        $headers = ['Accept: application/pdf,*/*'];
+        if ($apiKey) {
+            $headers[] = 'X-Api-Key: ' . $apiKey;
+        }
+
+        $ch = curl_init($url);
+        curl_setopt_array($ch, [
+            CURLOPT_CUSTOMREQUEST => $method,
+            CURLOPT_HTTPHEADER => $headers,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_HEADER => true,
+            CURLOPT_TIMEOUT => 180,
+            CURLOPT_CONNECTTIMEOUT => 10,
+        ]);
+
+        $raw = curl_exec($ch);
+        $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $headerSize = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
+        $error = curl_error($ch);
+        curl_close($ch);
+
+        if ($error) {
+            $this->log->error("KnowledgeBase: HTTP error calling {$url}: {$error}");
+            throw new Error("Failed to reach Knowledge Base: {$error}");
+        }
+
+        $rawHeaders = substr($raw, 0, $headerSize) ?: '';
+        $body = substr($raw, $headerSize) ?: '';
+
+        $contentType = '';
+        $disposition = '';
+        foreach (explode("\r\n", $rawHeaders) as $line) {
+            if (stripos($line, 'Content-Type:') === 0) {
+                $contentType = trim(substr($line, strlen('Content-Type:')));
+            } elseif (stripos($line, 'Content-Disposition:') === 0) {
+                $disposition = trim(substr($line, strlen('Content-Disposition:')));
+            }
+        }
+
+        return [
+            'body' => $body,
+            'contentType' => $contentType,
+            'disposition' => $disposition,
+            'status' => $httpCode,
+        ];
+    }
+
+    private function request(string $method, string $path, ?array $payload): array
+    {
+        $url = $this->getBaseUrl() . $path;
+        $apiKey = $this->getApiKey();
+
+        $headers = ['Accept: application/json'];
+        if ($apiKey) {
+            $headers[] = 'X-Api-Key: ' . $apiKey;
+        }
+
+        $ch = curl_init($url);
+        $opts = [
+            CURLOPT_CUSTOMREQUEST => $method,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_TIMEOUT => 180,
+            CURLOPT_CONNECTTIMEOUT => 10,
+        ];
+        if ($payload !== null) {
+            $headers[] = 'Content-Type: application/json';
+            $opts[CURLOPT_POSTFIELDS] = json_encode($payload);
+        }
+        $opts[CURLOPT_HTTPHEADER] = $headers;
+        curl_setopt_array($ch, $opts);
+
+        $body = curl_exec($ch);
+        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $error = curl_error($ch);
+        curl_close($ch);
+
+        if ($error) {
+            $this->log->error("KnowledgeBase: HTTP error calling {$url}: {$error}");
+            throw new Error("Failed to reach Knowledge Base: {$error}");
+        }
+        if ($httpCode < 200 || $httpCode >= 300) {
+            $this->log->error("KnowledgeBase: HTTP {$httpCode} from {$url}: {$body}");
+            throw new Error("Knowledge Base returned HTTP {$httpCode}");
+        }
+        $decoded = json_decode($body, true);
+        if (!is_array($decoded)) {
+            throw new Error('Invalid JSON from Knowledge Base.');
+        }
+        return $decoded;
+    }
+}

manifest.json

@@ -0,0 +1,14 @@
+{
+    "name": "KnowledgeBase",
+    "module": "KnowledgeBase",
+    "version": "0.1.6",
+    "acceptableVersions": [
+        ">=8.0.0"
+    ],
+    "php": [
+        ">=8.1"
+    ],
+    "releaseDate": "2026-04-24",
+    "author": "klear",
+    "description": "Knowledge Base — Israeli National Insurance law, regulations, and circulars. Hybrid search + ask-shira, powered by shira-hermes KB."
+}