kb_model
Read-onlyIdempotent
Convert requirement prose into structured claims, analyze ambiguity and grounding, and generate strict-lane write sets or predicate plans for KB application.
Instructions
Turn requirement prose into checkable structure without writing the KB. Use it for one requirement's prose; to plan a whole change request use kb_compile_intent. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Optional requirement ID used for deterministic draft relationship guidance. | |
| mode | Yes | analyze (advisor receipt), requirement (strict claim write set) or predicates (ontology predicate plan). | |
| text | Yes | Required prose requirement text to model. Example: 'Customer data must be retained for 7 years.' | |
| type | No | Entity type context for analysis. Requirement, domain-fact, and supporting prose all receive a proposition ledger; only requirements receive deterministic modeling suggestions. | |
| logic | No | Optional typed kibi.logic.v1 IR. Kibi validates and canonicalizes it into a rule fact; raw Prolog is rejected. | |
| title | No | Optional requirement title for draft apply plans. | |
| value | No | Optional extracted semantic claim value: a string, number or boolean, or a list of strings for a set claim. Example: ['requireAuth'] with operator includes. | |
| source | No | Optional primary source path or provenance root used for stable IDs and text refs. Example: '.kb/requirements/customer-retention.md'. | |
| status | No | Optional requirement status for draft suggestions. | |
| clauses | No | Optional complete list of atomic requirement clauses supplied by the caller. Each clause must be a verbatim fragment of text (whitespace may differ); a clause that does not occur in text fails the call with VALIDATION_FAILED naming it. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review. | |
| claimKey | No | Optional advisor-issued claim key for the exact proposition represented by logic. | |
| minScore | No | Minimum candidate score. Higher values make ontology-gap fallback more likely. Default: 0.35. | |
| operator | No | Optional extracted semantic claim operator. Use gt/lt for strict bounds ('greater than zero' is gt 0, not gte 0). A set claim takes a list value with eq (exactly these), includes (at least these), subset_of (only these) or excludes (none of these); matches takes a regular expression string. Example: 'eq'. | |
| schemaId | No | Optional exact reviewed predicate schema ID. When supplied, Kibi selects that schema instead of lexical rank order and fails closed if it is unavailable. | |
| claimText | No | Optional exact proposition text represented by logic; defaults to text. | |
| confidence | No | Confidence score for the extracted claim. >= 0.70 yields strict-lane output; lower confidence yields observation-only review output. | |
| provenance | No | Optional extracted text reference. Falls back to source when omitted. Example: '.kb/requirements/customer-retention.md#L1'. | |
| subjectKey | No | Optional extracted semantic claim subjectKey. Example: 'Customer.Data'. | |
| propertyKey | No | Optional extracted semantic claim propertyKey. Example: 'Retention Years'. | |
| sourceFiles | No | Optional related source files. The first value is used as the source fallback when source is omitted. | |
| subjectHint | No | Optional canonical subject key to use as the first predicate argument. Example: 'editor.annotation'. | |
| polarityHint | No | Optional reviewed polarity override for claims whose surface negation does not express predicate denial. Use only after reviewing the selected schema and full claim scope. | |
| maxCandidates | No | Maximum ranked predicate candidates to return. Default: 5. | |
| requirementId | No | Optional requirement ID. The strict write set updates this requirement instead of minting a REQ-AUTO id, and a typed logic rule attaches its requires_rule relationship to it. | |
| workspaceRoot | No | Optional absolute path of the workspace this call is about when it differs from the one the server started in, for example the git worktree you are working in. The server answers from that workspace's knowledge base when it is a worktree of the same repository or lies under the client's MCP roots; otherwise it answers from its own workspace and adds a workspace_mismatch diagnostic. Host hooks fill this in automatically where available. | |
| interpretations | No | Optional host-LLM typed kibi.logic.v1 interpretations. Kibi validates and canonicalizes them; raw Prolog is not accepted. | |
| argumentBindings | No | Optional exact predicate argument values keyed by a candidate schema's argument_names. Required before applying a candidate whose binding_status is incomplete; Kibi never substitutes guessed values for unbound arguments. | |
| existingLogicClaims | No | Existing requirement logic_claims values. The returned requirement update merges the new atomic claim key into this manifest instead of replacing prior claims. | |
| includeExistingSchemas | No | Whether to include existing KB fact_kind=predicate_schema facts alongside Kibi's built-in predicate catalog. Default: true. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| error | No | ||
| status | Yes | ||
| effects | Yes | ||
| operation | Yes | ||
| diagnostics | Yes | ||
| nextActions | Yes | ||
| kibiProtocol | Yes | ||
| resultVersion | Yes |