mirror of
https://github.com/vectorize-io/hindsight.git
synced 2026-09-14 19:31:49 +08:00
Nicolò Boschi
4d22a882f5
* docs(knowledge-pages): document Knowledge Pages and Mental Models Knowledge Pages shipped in #2455 with no documentation at all — no architecture page, no API page, no mention in the sidebar. Mental models had an API page but nothing explaining what they are or why they are fast. Add both, as top-level entries under Architecture and API. - Architecture: how pages are mental models with a simplified, document-shaped configuration; the folder hierarchy; the `hindsight fs` filesystem projection; page-level search; and why a projected view over reconciled memory is not the same thing as a folder of raw files. - Architecture: mental models as standing answers built in the background, so an application reads the current version instead of paying for synthesis on the request path. - API: the full knowledge-base endpoint surface, the page defaults and what each one buys, staleness gating, what a refresh reads, and how delta mode edits a structured document instead of regenerating prose. The mental-model trigger table gains the seven settings it was missing. - FAQ: mental model vs knowledge page. Also corrects the neighbouring answer, which described mental models as built automatically during retain — that is observations. The API examples use the maintained clients like every other API page, so this adds the knowledge-base surface to the Python and TypeScript wrappers (kept at parity, with request-mapping tests on both sides) and runnable Python/Node/Go examples. * feat(cli): manage knowledge pages from the CLI The knowledge base was reachable from every client except the CLI, where the eight endpoints were listed as deliberate coverage skips ("managed in the control plane UI"). That left `hindsight fs` able to mirror pages read-only but nothing able to create, edit, search, or delete them — and it meant the API docs could not show a CLI tab alongside Python/Node/Go. Adds `hindsight knowledge-base` with tree, create-folder, create-page, get-page, search, update, delete, and export, removing the skips so cli-coverage-check enforces the surface from here on. `create-page` sends no trigger unless --mode or --fact-types is passed, so the server's page defaults stand; when either is given the whole trigger has to be restated, because a supplied trigger replaces the defaults rather than merging with them. Also adds the CLI tab to the Knowledge Pages API page and a Knowledge Base section to the CLI reference.
83 lines
2.9 KiB
Bash
83 lines
2.9 KiB
Bash
#!/bin/bash
|
|
# Knowledge Pages API examples for Hindsight CLI
|
|
# Run: bash examples/api/knowledge-pages.sh
|
|
|
|
set -e
|
|
|
|
HINDSIGHT_URL="${HINDSIGHT_API_URL:-http://localhost:8888}"
|
|
BANK_ID="knowledge-pages-demo-bank-cli"
|
|
|
|
# =============================================================================
|
|
# Setup (not shown in docs)
|
|
# =============================================================================
|
|
hindsight bank create "$BANK_ID" --name "Knowledge Pages Demo"
|
|
hindsight memory retain "$BANK_ID" "The API is deployed to Kubernetes with a rolling update"
|
|
hindsight memory retain "$BANK_ID" "Deploys run from the main branch after CI passes"
|
|
hindsight memory retain "$BANK_ID" "A failed deploy is rolled back by redeploying the previous tag"
|
|
sleep 2
|
|
|
|
# =============================================================================
|
|
# Doc Examples
|
|
# =============================================================================
|
|
|
|
# [docs:create-folder]
|
|
# Create a folder (omit --parent-id to create it at the root)
|
|
hindsight knowledge-base create-folder "$BANK_ID" "Operations"
|
|
# [/docs:create-folder]
|
|
|
|
FOLDER_ID=$(hindsight knowledge-base tree "$BANK_ID" -o json | jq -r '.roots[0].id')
|
|
|
|
# [docs:create-page]
|
|
# Create a page — content is generated in the background
|
|
hindsight knowledge-base create-page "$BANK_ID" \
|
|
"Deploying the API" \
|
|
"How is the API deployed?" \
|
|
--parent-id "$FOLDER_ID" \
|
|
--tags ops,type:runbook
|
|
# [/docs:create-page]
|
|
|
|
# Wait for the page's first build
|
|
sleep 20
|
|
|
|
# [docs:get-tree]
|
|
# Show the folder/page tree (no page bodies)
|
|
hindsight knowledge-base tree "$BANK_ID"
|
|
# [/docs:get-tree]
|
|
|
|
PAGE_ID=$(hindsight knowledge-base tree "$BANK_ID" -o json | jq -r '.roots[0].children[0].id')
|
|
|
|
# [docs:get-page]
|
|
# Read a page as a markdown document
|
|
hindsight knowledge-base get-page "$BANK_ID" "$PAGE_ID"
|
|
# [/docs:get-page]
|
|
|
|
# [docs:search-pages]
|
|
# Hybrid search (full-text + vector) over whole pages
|
|
hindsight knowledge-base search "$BANK_ID" "how do we deploy" --limit 5
|
|
# [/docs:search-pages]
|
|
|
|
# [docs:update-node]
|
|
# Rename a node, move it, and/or update a page's options.
|
|
# Changing --source-query rebuilds the page against the new question.
|
|
hindsight knowledge-base update "$BANK_ID" "$PAGE_ID" \
|
|
--name "Deploying the API (v2)" \
|
|
--tags ops,type:runbook,reviewed
|
|
# [/docs:update-node]
|
|
|
|
# [docs:export]
|
|
# Export the knowledge base as a portable markdown bundle
|
|
hindsight knowledge-base export "$BANK_ID"
|
|
# [/docs:export]
|
|
|
|
# [docs:delete-node]
|
|
# Delete a folder or page — deleting a folder removes its whole subtree
|
|
hindsight knowledge-base delete "$BANK_ID" "$FOLDER_ID" -y
|
|
# [/docs:delete-node]
|
|
|
|
# =============================================================================
|
|
# Cleanup (not shown in docs)
|
|
# =============================================================================
|
|
curl -s -X DELETE "${HINDSIGHT_URL}/v1/default/banks/${BANK_ID}" > /dev/null
|
|
|
|
echo "knowledge-pages.sh: All examples passed"
|