Repository navigation
v0.3.0
Breaking release: fresh install only. A database with the old migrations is refused (database predates the baseline; a fresh install is required), and the n8n tokens in PrivacyFence must be created again.
Added
- Two tiers: T0 (Markdown on
mainof a group's Forgejo repo, merged by a pull request that one of the group's approvers merges) and T3 (raw records withingest_record). Ids aredoc:<uuid>andrec:<uuid>; tier weights default toT0:1.0,T3:0.4. - Groups:
kh.yamllistspeople(Forgejo login to verified email) andgroups(members, approvers, optional repo). A person reads the groups that list their verified email; an n8n token carries group names as audiences. A change topeopleor a group needs akh serverestart. - Labels: defined in
kh.yaml, stored inkh.labels, checked on documents and records, and filterable insearch; the new toollist_labelslists them. kh setup plan|apply --config kh.yaml [--only STEP] [--prune] [--create-bucket]builds and checks the whole environment fromkh.yaml: Postgres roles, database, extension and tables, groups, labels, Forgejo teams, repos, branch protection and org webhook (read back after every write), the Ollama model and the S3 bucket.planexits 1 on drift and is meant to run on a schedule. New settingsKH_SETUP_PG_ADMIN_DSN_FILEandKH_SETUP_FORGEJO_ADMIN_TOKEN_FILE; the serving app never imports the setup code.kh lint FILE...checks frontmatter offline (id,title,review_by, optionallabels).- The tool
ingest_recordstores a raw record readable by a group the caller holds (body in S3 atrecords/<uuid>, 2000-character excerpt, repeat returns the existing id withexisted: true). It replacesingest_raw. - The tool
propose_docopens a pull request that proposes one document in a group's repo (checked path, text, labels and size; at mostKH_PROPOSE_MAX_OPENopen proposals). New settingsKH_PROPOSE_MAX_BYTESandKH_PROPOSE_MAX_OPEN. - The tools
search,get_docandlist_stalereturn the new shapes (min_tierT0orT3,labelsall-of,audience, 400-character snippets);searchwithmin_tier="T0"fails withonly T3 records match; repeat with min_tier T3 to see themwhen only records match. - The Forgejo push webhook queues a
git_pushjob only forrefs/heads/mainof a repo that belongs to a group; the job worker syncs the tree ofmain(a(path, blob_sha)diff of*.mdfiles) and embeds T3 records; failed jobs retry five times.kh checkandkh rebuild [--repo R]work on the new tables, andmainbeing rewritten raises the alertmain of <repo> was rewritten; run kh rebuild after review. - Releases: the GitHub release carries the wheel,
SHA256SUMSanddeploy/kh.example.yamlnext to the GHCR image, so an operator can install without Docker (pip install knowledge_hub-<v>-py3-none-any.whl, thenkh setup plan). Therelease.ymlchange reachesmainas a protected-change pull request. - CI: the
ciworkflow lints, runs the whole test suite on Python 3.12 and 3.13 against PostgreSQL 16 with pgvector, and builds the image on every pull request and every push tomain.
Changed
- Forgejo is the control for T0: the indexer reads
mainas Forgejo reports it, and branch protection (no direct push, merge whitelist the<group>-approveteam) decides what is approved. - One migration,
0001_baseline.sql, replaces the nine old ones: tablesgroups,labels,documents,records,chunksand the index tables, three roles, and one row-level rulekh.can_read(audience). A record insert needs the audience andcreated_by_sub = kh.caller_sub(). A label is checked by a trigger (SQLSTATEP0K05) and a label in use cannot be deleted (P0K06). - A caller's groups come from the verified email and
people; the audiences of aclaude_clientclaim are format-checked but grant nothing, andKH_DEV_IDENTITY.audiencesis ignored for aclaude_client. Ann8n_workflowkeeps the claim audiences that are configured groups. The PrivacyFence declaration keepsemail_for_visibility: true, and its Workspace-group mapping is no longer used for people. kh.yamlis rewritten:org,bot_login,indexer_login,forgejo_web_url,hub_url,people,groupsandlabelsreplacerepos,audiences,entitiesand the rest; unknown keys are refused. Seedeploy/kh.example.yaml.- Settings renamed or changed:
KH_FORGEJO_ORGis noworg:inkh.yaml,KH_MAX_RAW_BYTESisKH_MAX_RECORD_BYTES, theKH_TIER_WEIGHTSdefault isT0:1.0,T3:0.4, and an embedder'smay_embedtakes the audience name. kh dailyrecomputes stale flags and purges expired claim ids;kh requeue-embeddingsqueuesembed_recordjobs.- Deploy files: the compose example holds only the settings the hub still reads;
backup-kh.shdumps onlykh.recordsand its restore order ispg_restore,kh setup apply,kh rebuild,kh requeue-embeddings, S3 sync; the PrivacyFence declaration lists the six tools. - PrivacyFence: the changed tool gates void old approvals, so every n8n token is created again with group names as audiences and the gated tools
ingest_recordandpropose_docticked. - Docs: README, design, configuration and runbook are rewritten for two tiers;
docs/governance.mdis deleted. - PrivacyFence setup: the group-to-audience map in PrivacyFence's
admin_config.jsonstays for n8n tokens (people need none), and the administrators who create tokens must be members of the mapped groups through astaticmembership file or the defaultsnapshotsync. The declaration example and the runbook say how.
Removed
- T1 notes, T2 derived records, candidates, conflicts, promotion, domains, entities and Grist,
owners.ymland the governance gates, the trust walk, the requester record (kh/requested-by),allowed_emails, any-of audiences andraw_audience_map. - The tools
ingest_raw,write_derived,write_note,propose_change,propose_edit,get_entity,pr_status,list_my_proposalsand the other old tools; the agent write tools andkh.proposals. - The commands
kh validate,kh domain-owners,kh governance,kh recompute-visibilityandkh rebuild --rejudge. - The role
kh_provenance,kh.emailand the nine old migrations. - Settings
KH_FORGEJO_NOTES_TOKEN_FILE, everyKH_AGENT_*,KH_CI_STATUS_LOGINS,KH_PROMOTION_DAILY_LIMIT,KH_SUPERSEDED_WEIGHT,KH_DISPUTED_WEIGHTandKH_GRIST_*.