Topics, the categories of a house

A topic is how an owner sorts what comes in: "Bridge renovation", "Money", "Travel". In a house a topic is an individual under an aspect named Thema (German for topic). Its description, in a slot named Umschreibung (German for paraphrase), is the whole material by which anyone decides what belongs to it. A document belongs to a topic through an edge of the form About, which carries one sentence of reasoning.

A fresh house has neither the aspect nor the form. Check with overview (aspects) and list_forms (a form titled About). If they are missing, coin them once.

Coin the vocabulary, with these exact words

Use the modeller door. An aspect is its description: the same words are the same aspect in every house, and other words are a different aspect that merely shares the name. Assigning topics from the list of open work (assign_topics, see the-list-of-open-work) looks for exactly this aspect and this form, and list_work hands out both definitions as well. So copy them as they stand, including the German slot name.

Call define_aspect with this YAML:

Name: Thema

Description: >
  A Thema is a lasting concern of the person this memory belongs to: one of the worlds he
  lives in, and one that a find can belong to.


  Conventions of this aspect:

  - The Umschreibung slot carries the whole judgement material: what belongs here and what
  does not, in the owner's own words. Sharpening it is a new fassung, never an overwrite —
  and it is the intended way to steer assignment, in place of any rule in code.

  - Names are labels, never keys. Topics may overlap, and a find belongs to as many as fit.

  - Topics are coined by the owner alone. No agent invents one: a find that fits none stays
  unassigned, and that is a signal about the topic list, not about the find.

  - Assignment is an About edge from the content to the topic, carrying one sentence of
  reasoning. It is asserted generously and without conjecture — too many is one retract,
  too few is invisible.

  - What stands here is content, not vocabulary: a Thema is an individual of this corpus,
  never a concept of the model. The concept DAG describes the system; a Thema describes a
  life.

Properties:
- Name: Umschreibung
  Kind: Versioned
  Description: >
    What belongs to this topic and what does not, in the owner's own words. This text is
    the whole material an assigning agent judges by; sharpening it is a new fassung, and
    it makes every stamped document fall due again.

Call define_form with the title About and this YAML:

Description: >
  An About states that the content (From) belongs to a topic (To): the assignment of a find
  to one of the owner's lasting concerns. It carries the one sentence that explains the
  assignment. The edge is an ordinary assertion — retract takes it back, and taking it back
  is the intended correction when an assignment misses.

Properties:
- Code: Reason
  Type: Storable
  Description: >
    One sentence naming what in the content makes it belong to this topic. It is shown to
    the owner as the explanation of the assignment; a reason that only repeats the topic's
    name explains nothing.

Both calls are idempotent: the answer says is_new: false when the definition already stands. Keep the concept ID of the aspect and the ID of the form from the answers.

Add a topic

Topics are the owner's. Ask your human which topics there are and what belongs to each; do not invent them from the documents. The author door is enough from here on.

create_individual {"aspect_id": "<Thema concept ID>", "name": "Money"}
set_property {"thing_id": "<topic ID>", "path": ["Umschreibung"],
              "value": "Budgets, quotes, prices and invoices of any kind: what something costs.",
              "context_id": "<Thema concept ID>", "versioned": true}

create_individual never searches: calling it twice makes two topics of the same name. List the existing ones first with list_collection on the collection that overview reports for the aspect. To sharpen a description, call set_property again with the new text; the old one stays readable through get_history.

Assign, read, correct

assert_formed_link {"form_id": "<About ID>", "from_id": "<document ID>", "to_id": "<topic ID>",
                    "values": {"Reason": "Quarterly budget note with the cost of the bearings."}}
get_links {"id": "<topic ID>", "direction": "in", "form_id": "<About ID>"}
get_links {"id": "<document ID>", "direction": "out", "form_id": "<About ID>"}
retract {"link_id": "<link ID from get_links>"}

The first call assigns, the second lists everything that belongs to a topic, the third the topics of one document, the fourth takes an assignment back. Asserting the same assignment again changes nothing. For assigning many documents with the prompt of the house, use recipe-assign-topics.

Go deeper