Hub: proposal review hints vs Enrich (LLM)

Two optional features use a chat-capable model for proposals only (not the same subsystem as Meaning search embeddings). Neither is a merge gate; humans still approve or discard.

Embeddings vs chat (operators)

Hosted bridge index/search uses EMBEDDING_PROVIDER / EMBEDDING_MODEL (see hub/bridge/README.md); voyage is supported the same way as openai with VOYAGE_API_KEY.

Chat provider selection (completeChat)

Resolved in this order (first match wins):

1. KNOWTATION_CHAT_PROVIDER=deepinfra + DEEPINFRA_API_KEY → DeepInfra (OpenAI-compatible). Falls back to OpenAI then Anthropic if their keys are set and DeepInfra returns an error.
2. KNOWTATION_CHAT_PROVIDER=openai → OpenAI only (no fallback). Requires OPENAI_API_KEY.
3. KNOWTATION_CHAT_PROVIDER=anthropic → Anthropic only (no fallback). Requires ANTHROPIC_API_KEY.
4. Implicit DeepInfra: DEEPINFRA_API_KEY set and neither OPENAI_API_KEY nor ANTHROPIC_API_KEY set → DeepInfra. (Backward compatible — never preempts an existing OpenAI/Anthropic deployment.)
5. KNOWTATION_CHAT_PREFER_ANTHROPIC=1 with both OpenAI and Anthropic keys → Anthropic first, OpenAI fallback.
6. Default: OpenAI → Anthropic → Ollama.

DeepInfra notes (hosted Hub cost lane):

• One OpenAI-compatible API key (DEEPINFRA_API_KEY) covers chat (Qwen 2.5, Llama 3.x, Mistral), embeddings, image generation, and TTS — the same key works for OpenClaw orchestration.
• Default chat model is Qwen/Qwen2.5-72B-Instruct; override with DEEPINFRA_CHAT_MODEL. For the cheap review hints path, set DEEPINFRA_CHAT_MODEL=meta-llama/Meta-Llama-3.1-8B-Instruct (or pass config.llm.deepinfra_chat_model per-call).
• Enrich JSON validation: before flipping production, run the saved Enrich prompts through validateAndNormalizeEnrichResult against your chosen DeepInfra model and confirm 10/10 of your known-good samples still parse. Smaller models may need a stricter system prompt.
• Netlify production: set DEEPINFRA_API_KEY and KNOWTATION_CHAT_PROVIDER=deepinfra in the gateway site's deploy env (not just .env locally). Keep OPENAI_API_KEY as fallback if you want automatic recovery on DeepInfra outages.

Review hints (plain text for reviewers)

What it does: After a proposal is created, an async job asks the model for 2–6 short lines of informal reminders (risks, unclear scope, things to verify). The model is instructed not to say pass/fail/approve. Output is stored as plain text on the proposal and shown in the Hub proposal detail panel (Activity → open a proposal) under a Review hints block when review_hints is non-empty.

Implementation: lib/hub-proposal-review-hints-job.mjs → completeChat() (lib/llm-complete.mjs).

Self-hosted (Node Hub):

1. Set KNOWTATION_HUB_PROPOSAL_REVIEW_HINTS=1 in the environment where npm run hub runs.
2. Configure chat the same way as other LLM features: OpenAI (OPENAI_API_KEY, optional OPENAI_CHAT_MODEL), Anthropic (ANTHROPIC_API_KEY, optional ANTHROPIC_CHAT_MODEL), and/or Ollama (OLLAMA_URL, OLLAMA_CHAT_MODEL). Optional KNOWTATION_CHAT_PREFER_ANTHROPIC=1 when both OpenAI and Anthropic keys exist. See lib/llm-complete.mjs and config/local.yaml / env used by the Hub process. (Meaning search still follows embedding.* / EMBEDDING_PROVIDER, not these chat keys.)
3. Creating a proposal via POST /api/v1/proposals on that Hub triggers setImmediate(() => runProposalReviewHintsJob(...)) in hub/server.mjs. Hints are written to data/hub_proposals.json (local file store).
4. Refresh the proposal in the UI after a few seconds; hints are not a modal—they appear inline in the drawer when present.

Hosted (gateway + canister):

• The canister stores hints when POST /api/v1/proposals/:proposal_id/review-hints is called with JSON body {"review_hints":"...","review_hints_model":"..."} (see hub/icp/src/hub/main.mo).
• The gateway runs an async job after a successful POST /api/v1/proposals: when KNOWTATION_HUB_PROPOSAL_REVIEW_HINTS=1 on the gateway process, it calls maybeScheduleHostedProposalReviewHints (hub/gateway/proposal-review-hints-async.mjs), which fetches the new proposal, runs completeChat() (lib/llm-complete.mjs) with the same Ollama/OpenAI env as self-hosted, then POSTs hints to the canister. Hints appear in the Hub drawer after a short delay (refresh if needed).
• Deploy requirement: The Netlify (or other) function that runs the gateway must have a reachable chat backend (typically OpenAI in production; localhost Ollama is not reachable from Netlify). If the env flag is on but the model call fails, hints simply stay empty—check gateway logs.

JSON / import shaping: Review hints are not JSON schema for notes or imports. They do not pre-fill frontmatter or tags.

Enrich (summary + suggested labels)

What it does: On demand, POST /api/v1/proposals/:id/enrich asks the model for JSON: {"summary":"...","suggested_labels":["tag",...]}. The Hub stores assistant_notes, assistant_model, and suggested labels on the proposal record. The UI shows an Enrich (AI) button on proposed items when the feature is enabled (web/hub/hub.js).

Roadmap — richer metadata: We plan to extend Enrich so the model also recommends vault-aligned frontmatter (e.g. project, title, causal_chain_id, entity, episode_id, follows, and other fields from SPEC.md §2), not only summary and tags. That work is specified in PROPOSAL-ENRICH-EXTENSION-PLAN.md (storage, validation, Hub UI, canister/gateway parity). Until that ships, Enrich remains summary + suggested_labels only.

Self-hosted: Set KNOWTATION_HUB_PROPOSAL_ENRICH=1 on the Node Hub; same Ollama/OpenAI chat config as above. Route is implemented in hub/server.mjs.

Hosted: The gateway implements POST /api/v1/proposals/:id/enrich when KNOWTATION_HUB_PROPOSAL_ENRICH=1: it runs completeChat() (lib/llm-complete.mjs) and POSTs assistant_notes, assistant_model, and suggested_labels_json (JSON array string) to the canister at the same path. The canister stores fields on the proposal; deploy the hub canister from this repo so stable storage includes enrich columns (V4 migration). Chat env on the gateway: typically OpenAI or Anthropic on Netlify (localhost Ollama is not reachable from serverless).

Privacy (operators)

Proposal body (and path/intent) are sent to the configured chat API when hints or Enrich run. That content leaves your deployment to the provider unless you use local Ollama on self-hosted with no cloud API keys. There is no way to get cloud-model quality with zero data egress to the vendor; disabling KNOWTATION_HUB_PROPOSAL_* env flags avoids LLM calls entirely.

Settings rows (Backup tab)

Related (not Enrich v1)

New note / import assistants that pre-fill Markdown for arbitrary captures are a separate product path from proposal Enrich. Enrich stays proposal-scoped; the extended Enrich plan still targets the proposal review surface and approved-note metadata alignment — see PROPOSAL-ENRICH-EXTENSION-PLAN.md.