Aribito: A Library That Points Before It Speaks

Question

In my first Aribito article, I described a small local CLI experiment: three attributed perspectives on one request, followed by a human choice or a decision to hold. The choice is recorded; it does not execute the suggestion.

That raised another design question for me. If an AI team is going to help someone choose a next step, how should it find relevant project material without treating every search result as an instruction?

I am exploring a library index for that purpose. It is a proposal, not a feature of the current Aribito demo. The idea is to keep original documents where they belong and give the assistant a small card describing each document: an ID, kind, title, subjects, short summary, reference, and what is known about its freshness and verification. In the example below, the invented cards contain no source text.

A card is a lead, not an answer

Suppose someone asks, “Where is the guide for the prototype?” A matching card can say that a demo guide may be relevant. It cannot establish that the guide is current, that its contents are correct, or that the assistant may quote, send, or act on it. Those are separate checks.

Retrieval systems can quietly blur finding a document, reading it, trusting it, and doing what it says. The card's own summary deserves caution too: it could be mistaken, stale, or contain an instruction someone placed there. Even a top hit marked unverified is still unverified.

Here is a runnable illustration, using invented public project notes. It reads no files, calls no model, and has no connection to Aribito's current CLI. The demo: references deliberately resolve nowhere.

"""Illustrative, self-contained index example for this article.

Uses fabricated metadata. It does not read source files or connect to Aribito.
"""

from dataclasses import asdict, dataclass
from typing import Literal


SourceKind = Literal["project_note", "demo_guide", "role_outline"]
Freshness = Literal["current", "stale", "unknown"]
Verification = Literal["checked", "unverified"]


@dataclass(frozen=True)
class IndexEntry:
    entry_id: str
    source_kind: SourceKind
    canonical_ref: str  # Opaque demo reference, never a local file path.
    title: str
    logical_day: int | None
    subjects: tuple[str, ...]
    summary: str
    sensitivity: Literal["public", "restricted"]
    freshness: Freshness
    verification_status: Verification
    content_included: Literal[False] = False


def find_candidates(entries: tuple[IndexEntry, ...], term: str) -> tuple[IndexEntry, ...]:
    """Find metadata matches; a match is not evidence or permission."""
    needle = term.strip().casefold()
    if not needle:
        return ()
    return tuple(
        entry
        for entry in entries
        if entry.sensitivity == "public"
        and needle in " ".join((entry.title, *entry.subjects, entry.summary)).casefold()
    )


if __name__ == "__main__":
    # All three records are invented; these references resolve nowhere.
    fixture = (
        IndexEntry("demo-note-1", "project_note", "demo:note:1",
                   "Prototype project note", 12, ("prototype",),
                   "A sample project note exists.", "public", "unknown", "unverified"),
        IndexEntry("demo-guide-1", "demo_guide", "demo:guide:1",
                   "Prototype demo guide", 12, ("prototype",),
                   "A sample demonstration guide exists.", "public", "unknown", "unverified"),
        IndexEntry("demo-role-1", "role_outline", "demo:role:1",
                   "Public role outline", None, ("roles",),
                   "A sample public role outline exists.", "public", "unknown", "unverified"),
    )
    for candidate in find_candidates(fixture, "prototype"):
        print(asdict(candidate))

Run it with python aribito_library_index_example.py. The two printed records are candidates for “prototype.” Both still say freshness='unknown' and verification_status='unverified'. The toy function excludes records without a public label; that condition alone is not an access-control policy for real sources.

What I would test next

The code demonstrates only metadata lookup. It searches the summary as text, but never treats that text as a command or verifies it. Before a real assistant used an index, I would want to test whether it keeps these questions separate:

1. Did the lookup find a candidate document?
2. Was the original document actually read, and when?
3. Is the specific claim supported by that document?
4. Is the requested use of the information authorized?

A possible later handoff would pass a candidate reference to a separately bounded reader. That reader would need to report whether it actually opened the source and which claim it supports; permission to reveal or act on the result would be checked separately. This handoff has not been built or tested. The type hint Literal[False] does not enforce the field at runtime, and a summary could itself expose source content. A real index would need validation and review before exposing cards.

For me, the promising part of a library is modest: it can help an AI team say, “Here is where we might look, and here is what we still do not know.” That seems like a better starting point than letting a search hit speak with the authority of the original source.

What metadata would you want to see before trusting an assistant's suggested source?

---

Direction and publication decision: Masato Kato. Structure, prose, and illustrative code: Codex editorial assistance. The example contains invented metadata and is not a live model transcript or a claim about deployed Aribito behavior.