acquaint.tools#
The single source of truth for every surface: plain functions, flat arguments in, JSON-ready dicts out.
The CLI is cw over TOOLS; the MCP server exposes the same functions (by
acquaint.tools:<name> reference); the shipped skills describe these verbs. Nothing
in this module knows about any of those surfaces.
Every tool takes data_dir (default: $ACQUAINT_DATA_DIR, else data_dir in
~/.config/acquaint/config.toml, else ~/.local/share/acquaint). Every result carries
ok and a one-line summary; long human-readable content is in text.
Tools never act on a guess. A name, alias, handle or email counts only when exactly one
entity has it exactly; a partial match is returned as a suggestion. rename and
forget need the exact id. Library callers with their own store use the core
functions (acquaint.lookup.find_entity(), acquaint.brief.compose_brief(), …)
with a Store.
Module Attributes
Every tool, in the order surfaces list them. |
|
What each tool changes, for surfaces that must decide what to expose or confirm. |
Functions
|
Everything to know before writing to someone: card, writing style, reach, project norms, recent observations, gaps. |
|
Scan prose that names people before publishing it: conflations (one person written as two), ambiguous names, unknown names. |
|
The digests of an entity's conversations (notes on what each said, kept in |
|
Add a dated batch to a digest: a |
|
Record that a conversation has been processed through |
|
Create the digest of one conversation ( |
|
Record a sweep of a channel ( |
|
Who may be told what, before writing to a set of readers (ids or channel identities, plus an optional correspond |
|
Remove an entity's folder and leave a salted tombstone. |
|
Check records: every preference, view and rule sourced; tiers, labels and seals set by the operator; nothing POLICY.md forbids; files parse; entry files within budget. |
|
Create a person, project, org or group from its template (a readable slug id; |
|
Ordered channels for reaching someone in a context. |
|
Is the record due for a refresh from its corpora? Per corpus ( |
|
Append a dated observation ( |
|
Change an entity's id ( |
|
Map a channel handle ( |
|
Everything the store says about one person's disclosure standing, with sources and dates, to confirm when a collaboration ends, when someone changes role, or before a tier changes: tier entries, links, the default tiers and clearances reached through links, seals on records and on fact lines, and the rules that name them. |
|
The deterministic half of deslop: machine-writing tells in a draft, at the recipient's tolerance and against their blocklist. |
|
Make the data root a checkout of a PRIVATE GitHub repository (created private through |
|
Pull the store from its private remote, rebasing local work on top. |
|
Commit, rebase onto the remote and push the store, after re-checking the remote, the guard and the visibility. |
|
Whether the store is synced, to which repository, uncommitted changes, ahead/behind, the guard, and live visibility. |
|
Before filing a meeting's todos as GitHub issues: is the project unambiguous, is every participant (comma-separated) registered and linked to it, and does it declare a meta repository that is private now? Returns the repository, each person's GitHub login, and a fix for every problem. |
|
Look up one person, project, org or group by exact id, name, alias, handle or email. |
Exceptions
An expected failure with a message meant for the person or agent that asked. |
- exception acquaint.tools.AcquaintError[source]#
Bases:
ExceptionAn expected failure with a message meant for the person or agent that asked.
- acquaint.tools.SIDE_EFFECTS = {'brief': 'read', 'check': 'read', 'digest': 'read', 'digest_append': 'rewrite', 'digest_mark': 'rewrite', 'digest_new': 'create', 'digest_sweep': 'rewrite', 'disclosure': 'read', 'forget': 'destructive', 'lint': 'read', 'new': 'create', 'reach': 'read', 'refresh_due': 'read', 'remember': 'append', 'rename': 'rewrite', 'resolve': 'read', 'review': 'read', 'style_lint': 'read', 'sync_init': 'external', 'sync_pull': 'rewrite', 'sync_push': 'external', 'sync_status': 'external-read', 'todo_preflight': 'external-read', 'who': 'read'}#
What each tool changes, for surfaces that must decide what to expose or confirm.
readchanges nothing and stays local;appendadds to a log;createadds a record;rewritechanges existing records;destructiveremoves data;external-readqueries a remote service;externalacts on one.
- acquaint.tools.TOOLS = [<function who>, <function resolve>, <function check>, <function reach>, <function brief>, <function remember>, <function lint>, <function new>, <function rename>, <function forget>, <function sync_init>, <function sync_push>, <function sync_pull>, <function sync_status>, <function style_lint>, <function disclosure>, <function review>, <function todo_preflight>, <function digest>, <function digest_new>, <function digest_append>, <function digest_mark>, <function digest_sweep>, <function refresh_due>]#
Every tool, in the order surfaces list them.
- acquaint.tools.brief(person, *, purpose=None, project=None, ref=None, audience=None, data_dir=None)[source]#
Everything to know before writing to someone: card, writing style, reach, project norms, recent observations, gaps. With
ref(the conversation the message goes to; correspond is asked who can read it, and an unknown audience is public) oraudience(an audience record as JSON), it opens with the ceiling, the records not to identify, how many lines were withheld, and what they were already told.- Return type:
- acquaint.tools.check(text, *, data_dir=None)[source]#
Scan prose that names people before publishing it: conflations (one person written as two), ambiguous names, unknown names.
- Return type:
- acquaint.tools.digest(entity, ref=None, *, data_dir=None)[source]#
The digests of an entity’s conversations (notes on what each said, kept in
digests/) and their watermarks: how far each was processed, per scope (content,style). Withref(a correspond reference, e.g.whatsapp:ada-lovelace), that one digest andsince, the time to hand tocorrespond read <ref> --sincefor what is new. Reads only.- Return type:
- acquaint.tools.digest_append(entity, ref, *, heading, rows, through=None, scope='content', force=False, data_dir=None)[source]#
Add a dated batch to a digest: a
### <heading>block (e.g. the date range) at the end of each section named inrows.rowsis JSON{"Takeaways": ["line [at: <ISO time>]"]}, orsection | line | anchorrows (one per line), or@<path>to read either from a file. Lines under Takeaways, Themes, Index and Open threads need an[at: …]or[source: …]anchor, else nothing is written. Withthrough(ISO time of the last message processed), the watermark moves in the same call.- Return type:
- acquaint.tools.digest_mark(entity, ref, *, through=None, checked=None, scope='content', force=False, data_dir=None)[source]#
Record that a conversation has been processed through
through(the ISO time of the last message processed), forscope(contentorstyle), and/or that it was last read atchecked(ISO time; a quiet channel has no new message, sothroughcannot say it was looked at). Moving either back needsforce.- Return type:
- acquaint.tools.digest_new(entity, ref, *, archive='correspond', data_dir=None)[source]#
Create the digest of one conversation (
ref, a correspond reference) for an entity, from the template: Orientation, Takeaways, Themes, Index, Open threads, and an empty watermark.archivenames where the messages themselves live (never this store).- Return type:
- acquaint.tools.digest_sweep(entity, channel, *, checked, refs=None, archive='correspond', force=False, data_dir=None)[source]#
Record a sweep of a channel (
slack,whatsapp, …): stampchecked(ISO time with an offset, when the sweep read them) on the digests it read, quiet ones included. Withrefs(conversation references<channel>:..., one per item or comma-separated) exactly those are stamped, each created first if it has none; without, every digest of the channel is. A digest checked later keeps that later time (seekept_later).digestthen reportsswept: the oldestcheckedper channel.- Return type:
- acquaint.tools.disclosure(people, *, projects=None, audience=None, today=None, data_dir=None)[source]#
Who may be told what, before writing to a set of readers (ids or channel identities, plus an optional correspond
audiencerecord as JSON): the tier and clearance in force for each, the least clearance, which records each is cleared for, the seals, the vocabulary a gate must scan for, what each was already told, and the gaps.projectslimits the records to those plus people. Reads only.- Return type:
- acquaint.tools.forget(entity, *, confirm=False, data_dir=None)[source]#
Remove an entity’s folder and leave a salted tombstone. Needs the exact id; without
confirm, only reports what would be removed.- Return type:
- acquaint.tools.lint(entity=None, *, data_dir=None)[source]#
Check records: every preference, view and rule sourced; tiers, labels and seals set by the operator; nothing POLICY.md forbids; files parse; entry files within budget.
- Return type:
- acquaint.tools.new(kind, name, *, qualifier=None, description=None, force=False, data_dir=None)[source]#
Create a person, project, org or group from its template (a readable slug id;
qualifierseparates two of the same name).- Return type:
- acquaint.tools.reach(person, *, purpose=None, urgency=None, project=None, message_type=None, topic=None, data_dir=None)[source]#
Ordered channels for reaching someone in a context. Only active addresses; returns them, sends nothing.
outcomeisreachable,no_address(a rule matched, but neither states an address nor finds a usable one recorded for its channels) orno_channel. Each channel’saddress_kindisstated,identity(the person’s handle, which a conversation-addressed channel does not take) orNone.- Return type:
- acquaint.tools.refresh_due(entity, *, today=None, data_dir=None)[source]#
Is the record due for a refresh from its corpora? Per corpus (
refresh.tomlbesidesources.md): the watermark insources.md, how many items are newer, the threshold; plus the age of the last refresh againstmax_age_days(default 7).outcomeisdue(exit 0),not_due(exit 1: nothing fired and everything was checked) orunchecked(exit 4: nothing fired, but a corpus, the config or the record could not be read; seeunchecked). The result has the same keys whatever the outcome; a script should readoutcomefrom--jsonrather than rely on the exit code alone. Reads only; never refreshes.- Return type:
- acquaint.tools.remember(entity, text, *, source=None, kind='observation', disclosed=None, reactivate=False, data_dir=None)[source]#
Append a dated observation (
observation,interaction,identity,preference,view,rule) to an entity’s log, with its source. Aninteractionmay list the records the message identified (disclosed: exact ids, never the text). An identity equal to an inactive one (stale,retracted, …) is refused, naming that entry and the command with which the operator can make it active again.- Return type:
- acquaint.tools.rename(entity, to, *, data_dir=None)[source]#
Change an entity’s id (
tois a slug) or name and id (tois a name), rewriting links to it. Needs the exact id.- Return type:
- acquaint.tools.resolve(handle, *, data_dir=None)[source]#
Map a channel handle (
github:octocat,email:ada@example.org) to the entity it belongs to, with the evidence.okis true only when an active identity on the named platform belongs to exactly one entity. A handle without a platform (@octocat), a match by name only, an inactive identity, or several owners all returnok: falsewith what was found.- Return type:
- acquaint.tools.review(person, *, today=None, data_dir=None)[source]#
Everything the store says about one person’s disclosure standing, with sources and dates, to confirm when a collaboration ends, when someone changes role, or before a tier changes: tier entries, links, the default tiers and clearances reached through links, seals on records and on fact lines, and the rules that name them. Not ok when an affiliation has ended while a permissive tier is still in force. Reads only.
- Return type:
- acquaint.tools.style_lint(text, *, recipient=None, tolerance=None, data_dir=None)[source]#
The deterministic half of deslop: machine-writing tells in a draft, at the recipient’s tolerance and against their blocklist.
- Return type:
- acquaint.tools.sync_init(*, repo, remote_url=None, existing_only=False, dry_run=False, data_dir=None)[source]#
Make the data root a checkout of a PRIVATE GitHub repository (created private through
ghunlessexisting_only), with a pre-push guard.- Return type:
- acquaint.tools.sync_pull(*, dry_run=False, data_dir=None)[source]#
Pull the store from its private remote, rebasing local work on top.
- Return type:
- acquaint.tools.sync_push(ids=None, *, message=None, all=False, allow_markers=None, dry_run=False, data_dir=None)[source]#
Commit, rebase onto the remote and push the store, after re-checking the remote, the guard and the visibility. With
ids(records, e.g.person:ada-lovelace), commit only those records and leave other uncommitted records alone; without, commit everything, but amessagemust then name every record it commits unlessall. A file holding conflict markers is refused unless its path (relative to the store, e.g.people/ada-lovelace/PROFILE.md) is inallow_markers(list every path after one flag, and put record ids before it): for a record that quotes a conflict block on purpose.- Return type:
- acquaint.tools.sync_status(*, check_visibility=True, data_dir=None)[source]#
Whether the store is synced, to which repository, uncommitted changes, ahead/behind, the guard, and live visibility.
- Return type:
- acquaint.tools.todo_preflight(project, people, *, data_dir=None)[source]#
Before filing a meeting’s todos as GitHub issues: is the project unambiguous, is every participant (comma-separated) registered and linked to it, and does it declare a meta repository that is private now? Returns the repository, each person’s GitHub login, and a fix for every problem.
- Return type:
- acquaint.tools.who(name, *, field=None, brief=False, data_dir=None)[source]#
Look up one person, project, org or group by exact id, name, alias, handle or email.
Costs scale with what you ask:
fieldreturns one value (aka,email,github,label,tier, any frontmatter key, or a dotted fact name such asname.full: only a currentclearfact is readable here, a stricter one is refused),briefthe identity block, and the default the whole entry file. It never guesses: no exact match, or several, returns the candidates andok: false.- Return type: