Repository navigation
Releases
Releases · tkcs-lab/knowledge-hub
v0.3.1
Changed
searchnow searches T0 and T3 by default (min_tierdefaults toT3);min_tier="T0"still searches documents only and fails withonly T3 records match; repeat with min_tier T3 to see themwhen only records match. The tool description says there are exactly two tiers.
Fixed
ingest_recordrefuses a NUL character in any text argument withargument <name> is invalidbefore storing anything; before, a NUL late in the body was stored and its embedding job failed on every attempt.- The
embed_recordjob removes NUL characters from a stored body before chunking, so records stored before this fix can be indexed withkh requeue-embeddings. kh requeue-embeddingsno longer skips a record whose job was leftrunningby a stopped worker.
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_*.
v0.2.0
Added
- Governance config:
reference_audiencesper entity kind (default forcus: contracts and mgmt),governance.owner_teamsinkh.yaml, and theowners.ymlmodel withCODEOWNERSrendering. kh governance renderwrites the frontmatter JSON Schema,owners.yml,CODEOWNERS, the pull request template and thekhForgejo workflow for a canonical repository.- Forgejo client: compare files, branch head lookup, team and membership reads, and
post_statusguarded to thekh/validateandkh/domain-ownerscontexts. kh validate --repo R --base B --head Hchecks the markdown files a pull request changes in a canonical repository, prints onepath: reasonline per problem, exits 0, 1 or 2 and posts thekh/validatecommit status. Ids are checked only across the repos the token can read (unreadable ones are skipped), no Grist table is read for a kind the repo may not cite, and errors never name another repository.kh governance render --runner-labelsets the runner label of the rendered workflow, so each audience can have its own runner (defaultkh-validate:host).kh domain-owners --repo R --pr Nchecks that the teams named inowners.yml(and, for awiden-audience/<audience>label, the audience's owner teams) have approved the current head of a pull request, prints one line per missing approval and posts thekh/domain-ownerscommit status.self_merge_teamsinkh.yaml: a merged pull request is also trusted when its author, a member of a team that owns every touched path inowners.yml, merged it themselves. Such documents carry the new stampowner_merge.stamp(reviewed,owner_merge,anchoror empty) insearchandget_docresults, next toapproved_by;stampis a forbidden frontmatter key.- Merge verdicts are stored in
kh.merge_verdictsand reused by every sync and rebuild;kh rebuild --rejudgejudges every merge afresh. bot_loginsinkh.yaml(default[kh-hub-bot], which is always included): bots never self-merge and their approvals never count.kh domain-ownerspasses a pull request whose author may self-merge as owner.
Changed
kh domain-ownersprints the approval or self-merge that applied when it passes.- An audience list in
entities.<kind>.audiencesorraw_audience_mapnow means any one of the audiences may read the rows; derived records, candidates and conflicts still need every source. Check multi-audience lists before upgrading (migration 0007). generated_byandderived_fromare forbidden frontmatter keys, like the other keys the server writes.- The indexer skips paths with a dot-prefixed segment, so
.forgejo/pull_request_template.mdraises no alert. - The PrivacyFence declaration example sets
email_for_visibility: true.
v0.1.1
Changed
- Entity kinds are configurable in
kh.yaml: each kind names its Grist table, its audiences and an optional label, so the hub is no longer limited to products, components, versions and customers. The old list form keeps working.
v0.1.0
Added
- Deployment examples: the release image from GHCR, Ollama with its limits and a one-off model pull, a PrivacyFence upstream declaration, and the install order for a fresh host.
- MCP tools for agents to search, read, list and follow records, plus write tools for raw ingest and derived notes.
- Indexer that builds the database from the canonical Git repositories on every Forgejo webhook push.
khcommands for serving, migrating, rebuilding, checking, recomputing visibility and requeueing embeddings.- Row-level security that enforces audience visibility, so a caller never sees or detects records outside their audience.
- Container image published to GHCR for linux/arm64.