[Feat]: knowledge-base agent (PDF/PNG/URL → markdown → RAG → graphRAG)

.env.example

@@ -209,4 +209,31 @@ LLM_KEY_ENCRYPTION_KEY=
 # (case-insensitive), their role_id is set to 'admin'. Idempotent — leave
 # set forever; only the FIRST signup with this email is promoted. To add
 # a second admin later, use the admin UI role management tab.
-INITIAL_ADMIN_EMAIL=
+INITIAL_ADMIN_EMAIL=
+
+# KB retrieval knobs (issue #13 v3). All server-only — backend tool
+# surface and mention resolver read these via lib/kb/env.ts. Defaults
+# reflect the community survey in `.claude/13-kb-v3.md`:
+#   LangChain EnsembleRetriever / LlamaIndex QueryFusionRetriever /
+#   Haystack DocumentJoiner — per-leg 50, fused 5–10; Mastra = 3;
+#   Mastra + Vercel AI SDK RAG chunks = 512–1024 tokens.
+#   KB_MENTION_TOPK_DEFAULT — chunks per single @-mention. 5.
+#   KB_MENTION_TOPK_MAX     — per-mention upper bound when user overrides. 20.
+#   KB_MENTION_TOKEN_BUDGET — total token cap across multi-mention turns.
+#                             Per-mention topK is rebudgeted as
+#                             ceil(BUDGET / (CHUNK_MAX_CHARS/4 * mentions)).
+#                             8192.
+#   KB_HYBRID_TOPK_DEFAULT  — fused topK for the search_kb tool. 8.
+#   KB_HYBRID_TOPK_MAX      — fused topK upper bound for the tool. 20.
+#   KB_CHUNK_MAX_CHARS      — per-chunk truncation before stuffing into
+#                             the LLM prompt; ~512 tokens at 4 chars/token.
+#                             2000.
+#   KB_RERANK_MIN_SCORE     — minimum rerank relevance score threshold for filtering.
+#                             Chunks below this score are filtered out. 0.4.
+KB_MENTION_TOPK_DEFAULT=5
+KB_MENTION_TOPK_MAX=20
+KB_MENTION_TOKEN_BUDGET=8192
+KB_HYBRID_TOPK_DEFAULT=8
+KB_HYBRID_TOPK_MAX=20
+KB_CHUNK_MAX_CHARS=2000
+KB_RERANK_MIN_SCORE=0.4

.github/workflows/CI.yml

@@ -74,7 +74,13 @@ jobs:
     # to bring the schema up — the build-time DB can be empty otherwise.
     services:
       postgres:
-        image: postgres:16-alpine
+        # pgvector/pgvector:pg16 (Debian-based, FROM postgres:16) ships
+        # the vector extension pre-installed — required by migration
+        # 0005_*.sql (CREATE EXTENSION vector). Stock postgres:16-alpine
+        # does not bundle it. Wire-format (POSTGRES_*, PGDATA, init
+        # scripts) is unchanged from upstream so all 6 build/test steps
+        # keep working without further edits.
+        image: pgvector/pgvector:pg16
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
@@ -109,7 +115,13 @@ jobs:
     timeout-minutes: 10
     services:
       postgres:
-        image: postgres:16-alpine
+        # pgvector/pgvector:pg16 (Debian-based, FROM postgres:16) ships
+        # the vector extension pre-installed — required by migration
+        # 0005_*.sql (CREATE EXTENSION vector). Stock postgres:16-alpine
+        # does not bundle it. Wire-format (POSTGRES_*, PGDATA, init
+        # scripts) is unchanged from upstream so all 6 build/test steps
+        # keep working without further edits.
+        image: pgvector/pgvector:pg16
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres

.gitignore

@@ -31,6 +31,9 @@ yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
 
+# v1 KB JSON store — temporary local storage, replaced by DB tables in v2
+/.kb-store/
+
 # env files (can opt-in for committing if needed)
 .env*
 !.env.test

CLAUDE.md

@@ -4,23 +4,24 @@ Guidance for Claude Code in this repo. Features, layout, env vars, tech stack 
 
 ## Docs index
 
-| Topic                                           | File                    |
-| ----------------------------------------------- | ----------------------- |
-| Features, quick-start, layout, env vars, deps   | `README.md`             |
-| Marketing landing page sections + assets        | `docs/LANDING.md`       |
-| Every HTTP endpoint under `app/api/`            | `docs/APIS.md`          |
-| Memory + thread-summarize design                | `docs/MEMORY.md`        |
-| Observability panel design + retention          | `docs/OBSERVABILITY.md` |
-| LangGraph tool inventory + frontend card wiring | `docs/TOOLS.md`         |
-| Interrupt-driven tool flow contract             | `docs/INTERRUPT.md`     |
-| Attachments backing (R2 + presign) design       | `docs/ATTACHMENTS.md`   |
-| Auth setup, OAuth, troubleshooting              | `docs/AUTH.md`          |
-| DB schema, ownership, indexes                   | `docs/DB.md`            |
-| Provider registry (round-robin + withFallbacks) | `docs/PROVIDERS.md`     |
-| Credit / LLM-call quota system                  | `docs/CREDIT.md`        |
-| Admin UI + endpoints for providers/users/roles  | `docs/ADMIN.md`         |
-| Production deploys (Docker, env, Caddy)         | `docs/DEPLOY.md`        |
-| CI/CD, Docker, deploys                          | `docs/CI.md`            |
+| Topic                                            | File                     |
+| ------------------------------------------------ | ------------------------ |
+| Features, quick-start, layout, env vars, deps    | `README.md`              |
+| Marketing landing page sections + assets         | `docs/LANDING.md`        |
+| Every HTTP endpoint under `app/api/`             | `docs/APIS.md`           |
+| Memory + thread-summarize design                 | `docs/MEMORY.md`         |
+| Knowledge base, ingestion, hybrid search, Rerank | `docs/KNOWLEDGE_BASE.md` |
+| Observability panel design + retention           | `docs/OBSERVABILITY.md`  |
+| LangGraph tool inventory + frontend card wiring  | `docs/TOOLS.md`          |
+| Interrupt-driven tool flow contract              | `docs/INTERRUPT.md`      |
+| Attachments backing (R2 + presign) design        | `docs/ATTACHMENTS.md`    |
+| Auth setup, OAuth, troubleshooting               | `docs/AUTH.md`           |
+| DB schema, ownership, indexes                    | `docs/DB.md`             |
+| Provider registry (round-robin + withFallbacks)  | `docs/PROVIDERS.md`      |
+| Credit / LLM-call quota system                   | `docs/CREDIT.md`         |
+| Admin UI + endpoints for providers/users/roles   | `docs/ADMIN.md`          |
+| Production deploys (Docker, env, Caddy)          | `docs/DEPLOY.md`         |
+| CI/CD, Docker, deploys                           | `docs/CI.md`             |
 
 API changes update `docs/APIS.md` in the same commit (rule 1). Tool changes update `docs/TOOLS.md` (rule 10).
 
@@ -75,7 +76,7 @@ Non-negotiable. Every change.
 
 ## Things to know before editing
 
-- Graph id `agent` is in `langgraph.json`, `LANGGRAPH_ASSISTANT_ID` (`.env.example`, surfaced to client via `window.__CONFIG__` — see rule #12), and `unstable_createLangGraphStream({ assistantId })`. Keep aligned.
+- Graph id `agent` is in `langgraph.json`, `LANGGRAPH_ASSISTANT_ID` (`.env.example`, surfaced to client via `window.__CONFIG__` — see rule #12), and `unstable_createLangGraphStream({ assistantId })`. Keep aligned. The `kbAgent` assistant id (KB ingestion, `langgraph.json` + `lib/kb/ingest.ts:fireIngestionRun` dispatch) follows the same sync rule — there is no env-driven alias for it, but renaming it requires updating `langgraph.json` AND `fireIngestionRun` together.
 - `app/api/[..._path]/route.ts` proxy uses `runtime = "nodejs"` (was edge) — `withAuth` needs Node `net` for Postgres session reads.
 - `components.json` declares a `@assistant-ui` registry at `https://r.assistant-ui.com/{name}.json` for `shadcn`-style component adds.
 - `feat/*` branches: `git fetch origin main` and merge if main moved before committing — see [[feature-branch-tracks-main]].

README.md

@@ -16,6 +16,7 @@ A self-hostable chat app (this repo: `langgraph-app`) that streams tokens from a
 - **Crypto sub-agent**: price, NFT holdings (5-chain gallery via Alchemy Portfolio), and a simulated swap flow against an auto-funded Mock Coin balance.
 - **Observability panel**: every LLM / Tool / Chain / Node span is captured by a `BaseCallbackHandler` and persisted to a `observability_spans` Postgres table. Each assistant message shows an icon button that opens a per-turn waterfall — duration, token usage, nested parent/child spans. The list endpoint is server-transformed (panel never carries the raw collector payload); per-row click lazy-loads the full span via a dedicated detail endpoint. See [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md).
 - **Chat attachments**: assistant-ui's `AttachmentAdapter` plus a presigned PUT to Cloudflare R2 — the browser uploads bytes directly to R2, nothing traverses Next.js. Lazy-register on missing env (mirrors DENO / ALCHEMY). See [docs/ATTACHMENTS.md](docs/ATTACHMENTS.md) for the key convention, messageId-deferred decision, and Content-Disposition XSS guard.
+- **Knowledge Base & Hybrid Search**: PDF ingestion, page screenshot rendering, text chunking, and pgvector-backed three-leg RRF (Keyword, Vector, Tag) hybrid search combined with semantic Reranking (Cohere/Jina), `@` mention resolution (with automatic fallback to full markdown when chunks are not ready), dynamic budget scaling, and iterative search. See [docs/KNOWLEDGE_BASE.md](docs/KNOWLEDGE_BASE.md).
 - **Per-LLM-call credit quota**: every successful call is metered against a UTC-aligned rolling-window cap read from `role.creditLimit` / `role.windowHours`. Enforcement lives at the `/api/[..._path]` proxy — when the cap is hit, the proxy synthesizes a `show_credit_card` SSE stream and the chat UI renders the credit-limit-reached card inline. The call log backs a per-user history (Settings → Credits) and an admin-managed rate config. See [docs/CREDIT.md](docs/CREDIT.md).
 - **Admin console**: a single `/admin` page with three tabs — Providers (registry + encrypted API keys + per-model rates), Roles (credit caps + window length), Users (role assignment, ban with immediate session revoke, delete). The first admin is bootstrapped via `INITIAL_ADMIN_EMAIL`. See [docs/ADMIN.md](docs/ADMIN.md).
 
@@ -310,6 +311,7 @@ Test database stays isolated from dev — never put production-like data in `lan
 - [`docs/APIS.md`](docs/APIS.md) — HTTP endpoint reference. Update whenever a route under `app/api/` changes.
 - [`docs/LANDING.md`](docs/LANDING.md) — marketing landing at `/`: per-section file map, asset inventory, motion keyframes, route-group naming rule, frontend test layout.
 - [`docs/MEMORY.md`](docs/MEMORY.md) — memory + thread-summarize design: dual-graph topology, `<memory>` + `<threads>` recall, `save_memory` RFC 6902 patches, store-anchored trigger window math, Memory tab UI, security stance.
+- [`docs/KNOWLEDGE_BASE.md`](docs/KNOWLEDGE_BASE.md) — knowledge base design: ingestion pipeline, three-leg RRF hybrid search (Keyword, Vector, Tag), semantic Reranking and score filtering, `@` mention resolution (Meta vs Full Markdown mode), mention budgeting, and iterative search.
 - [`docs/OBSERVABILITY.md`](docs/OBSERVABILITY.md) — observability panel design: callback handler wiring, `observability_spans` schema, server-side transform + aggregate, lazy-loaded row detail, security/redaction, retention config, and curl examples.
 - [`docs/TOOLS.md`](docs/TOOLS.md) — LangGraph tool inventory and frontend card wiring. Update whenever a tool or card is added/removed/rerouted.
 - [`docs/INTERRUPT.md`](docs/INTERRUPT.md) — interrupt-driven tool flows (ask_location, connect_wallet, place_crypto_order, get_order_status) — the two runtime paths the cards can take.

app/admin/admin-tabs.tsx

@@ -10,6 +10,7 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Badge } from "@/components/ui/badge";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Checkbox } from "@/components/ui/checkbox";
 import { Separator } from "@/components/ui/separator";
 import { Switch } from "@/components/ui/switch";
 import {
@@ -32,11 +33,16 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/comp
 import { toast } from "sonner";
 
 type PublicProviderApiKey = { name: string };
+type ModelKind = "chat" | "ocr" | "embed" | "extract" | "rerank";
 type PublicModel = {
   name: string;
   enabled: boolean;
   inputPer1k: number;
   outputPer1k: number;
+  // ponytail: server-side default ["chat"] means an older row may not
+  // carry the field at all. Fall back to chat at render time so the
+  // table shows a value for every model, regardless of seed-vs-new.
+  kind?: ModelKind[];
 };
 type PublicProviderRow = {
   id: string;
@@ -56,6 +62,12 @@ type RoleRow = {
   createdAt: string;
   updatedAt: string;
 };
+
+// ponytail: module-scope constant so add-mode `initialKind ?? ["chat"]`
+// keeps the same array reference across renders — `useEffect` dep
+// comparison uses Object.is, and a fresh literal each render would loop
+// forever (Next dev StrictMode catches it as "Maximum update depth").
+const DEFAULT_KIND: ModelKind[] = ["chat"];
 // ponytail: server-side join shape — user + role name inlined so the
 // table can render "Admin" / "User" labels without a second round-trip.
 // `roleName` is null when the FK points at a missing role (defensive —
@@ -360,8 +372,9 @@ function ModelsSection({ providerId, models }: { providerId: string; models: Pub
         <table className="w-full text-sm">
           <thead className="bg-muted/50 text-muted-foreground text-xs">
             <tr>
-              <th className="px-3 py-2 text-left font-medium">Name</th>
-              <th className="px-3 py-2 text-left font-medium">Enabled</th>
+              <th className="w-[220px] px-3 py-2 text-left font-medium">Name</th>
+              <th className="px-3 py-2 text-left font-medium">Status</th>
+              <th className="px-3 py-2 text-left font-medium">Kind</th>
               <th className="px-3 py-2 text-right font-medium">Input / 1k</th>
               <th className="px-3 py-2 text-right font-medium">Output / 1k</th>
               <th className="px-3 py-2 text-right font-medium" />
@@ -370,19 +383,28 @@ function ModelsSection({ providerId, models }: { providerId: string; models: Pub
           <tbody>
             {models.length === 0 ? (
               <tr>
-                <td colSpan={5} className="text-muted-foreground px-3 py-3 text-center text-xs">
+                <td colSpan={6} className="text-muted-foreground px-3 py-3 text-center text-xs">
                   No models configured.
                 </td>
               </tr>
             ) : (
               models.map((m) => (
                 <tr key={m.name} className="border-t">
-                  <td className="px-3 py-2 font-mono text-xs">{m.name}</td>
+                  <td className="w-[220px] px-3 py-2 font-mono text-xs">{m.name}</td>
                   <td className="px-3 py-2">
                     <Badge variant={m.enabled ? "success" : "muted"}>
                       {m.enabled ? "Enabled" : "Disabled"}
                     </Badge>
                   </td>
+                  <td className="px-3 py-2">
+                    <div className="flex flex-wrap gap-1">
+                      {(m.kind ?? ["chat"]).map((k) => (
+                        <Badge key={k} variant="secondary">
+                          {k.charAt(0).toUpperCase() + k.slice(1)}
+                        </Badge>
+                      ))}
+                    </div>
+                  </td>
                   <td className="px-3 py-2 text-right font-mono text-xs">{m.inputPer1k}</td>
                   <td className="px-3 py-2 text-right font-mono text-xs">{m.outputPer1k}</td>
                   <td className="px-3 py-2 text-right">
@@ -511,19 +533,35 @@ function ModelDialog(
   const initialEnabled = isEdit ? props.model.enabled : true;
   const initialIn = isEdit ? String(props.model.inputPer1k) : "0.001";
   const initialOut = isEdit ? String(props.model.outputPer1k) : "0.002";
+  // ponytail: backend defaults kind to ["chat"] on POST when omitted,
+  // so the add-mode local seed mirrors the server contract and we don't
+  // need to send `kind` in the body. Edit-mode seeds from existing row.
+  const initialKind: ModelKind[] = isEdit ? (props.model.kind ?? DEFAULT_KIND) : DEFAULT_KIND;
 
   const [name, setName] = useState(initialName);
   const [enabled, setEnabled] = useState(initialEnabled);
   const [inputPer1k, setInputPer1k] = useState(initialIn);
   const [outputPer1k, setOutputPer1k] = useState(initialOut);
+  const [kind, setKind] = useState<ModelKind[]>(initialKind);
   const [saving, start] = useTransition();
 
   useEffect(() => {
     setName(initialName);
     setEnabled(initialEnabled);
     setInputPer1k(initialIn);
     setOutputPer1k(initialOut);
-  }, [initialName, initialEnabled, initialIn, initialOut]);
+    setKind(initialKind);
+  }, [initialName, initialEnabled, initialIn, initialOut, initialKind]);
+
+  const toggleKind = (k: ModelKind, checked: boolean) => {
+    setKind((prev) => {
+      const next = checked ? Array.from(new Set([...prev, k])) : prev.filter((x) => x !== k);
+      // ponytail: at least one kind must stay selected — unchecking the
+      // last box is a no-op so the user can never save a model with
+      // kind = [] (which the API rejects with 400 anyway).
+      return next.length === 0 ? prev : next;
+    });
+  };
 
   const save = () => {
     if (!name.trim()) {
@@ -541,8 +579,8 @@ function ModelDialog(
       : `/api/admin/providers/${encodeURIComponent(props.providerId)}/models`;
     const method = isEdit ? "PATCH" : "POST";
     const body = isEdit
-      ? { name: name.trim(), enabled, inputPer1k: inp, outputPer1k: out }
-      : { name: name.trim(), enabled, inputPer1k: inp, outputPer1k: out };
+      ? { name: name.trim(), enabled, inputPer1k: inp, outputPer1k: out, kind }
+      : { name: name.trim(), enabled, inputPer1k: inp, outputPer1k: out, kind };
     start(async () => {
       const r = await jsonFetch(path, { method, body: JSON.stringify(body) });
       if (!r.ok) {
@@ -580,15 +618,6 @@ function ModelDialog(
             className="font-mono"
           />
         </label>
-        <label className="flex items-center justify-between gap-3">
-          <span className="text-sm font-medium">Enabled</span>
-          <Switch
-            checked={enabled}
-            onCheckedChange={setEnabled}
-            disabled={saving || props.pending}
-            aria-label="Model enabled"
-          />
-        </label>
         <label className="flex flex-col gap-1.5">
           <span className="text-sm font-medium">Input / 1k</span>
           <Input
@@ -611,6 +640,39 @@ function ModelDialog(
             disabled={saving || props.pending}
           />
         </label>
+        <label className="flex items-center justify-between gap-3">
+          <span className="text-sm font-medium">Enabled</span>
+          <Switch
+            checked={enabled}
+            onCheckedChange={setEnabled}
+            disabled={saving || props.pending}
+            aria-label="Model enabled"
+          />
+        </label>
+        <div className="flex flex-col gap-1.5">
+          <span className="text-sm font-medium">Kind</span>
+          <div className="flex flex-wrap gap-3">
+            {(["chat", "ocr", "embed", "extract", "rerank"] as const).map((k) => (
+              <label key={k} className="flex items-center gap-2 text-sm">
+                <Checkbox
+                  checked={kind.includes(k)}
+                  onCheckedChange={(c) => toggleKind(k, c === true)}
+                  disabled={saving || props.pending}
+                  aria-label={`kind ${k}`}
+                />
+                {/* ponytail: title-case label for the dialog checkbox; the
+                    wire-format enum stays lowercase (matches the JSONB value
+                    and the registry's `m.kind ?? ["chat"]` contract). */}
+                <span>{k === "ocr" ? "OCR" : k.charAt(0).toUpperCase() + k.slice(1)}</span>
+              </label>
+            ))}
+          </div>
+          <p className="text-muted-foreground text-xs">
+            At least one kind is required — chat for general inference, ocr for PDF vision, embed
+            for KB chunk vectors, extract for structured-output triples from chunks, rerank for
+            secondary retrieval reranking.
+          </p>
+        </div>
       </div>
     </FormDialog>
   );