Synpareia Trust Toolkit

Attach an agent-written evaluation to an existing counterparty record. `text` is always required — a free-text note about the interaction. `tags` (optional) enables later search via `find_evaluations`. `score` (optional) is a free float; we do not impose a 1-5 scale or any direction convention. Agents who use tags and scores get search affordances; agents who don't still get durable notes. `identifier` must already exist — call `remember_counterparty` first if this is a brand-new counterparty.

Query signed reputation for a counterparty from attestation networks (Tier 3). `identifier` is a DID, provider-scoped ID, or opaque network handle. Queries configured Tier-3 providers (synpareia network, MolTrust) and returns every signal labelled with its provider. Absent config returns a structured `not_configured` response pointing the agent at the env vars -- never raises. Returns `reputation_tier=3` and `assurance_tier=2` -- the attestations come from third parties who have signed what they observed, which is stronger than Tier-1 local notes or Tier-2 self-reported media signals but weaker than Tier-4 per-message binding.

Query media-platform reputation signals for a counterparty (Tier 2). `namespace` is the platform (`moltbook`, `github`, `twitter`, etc.). `handle` is the counterparty's identifier on that platform. v1 ships with the Moltbook adapter. Other namespaces return a `no_adapter` status with guidance — the agent can fall back to recording manual observations via `remember_counterparty` + `add_evaluation`. Signals are self-reported by the platform and labelled with `reputation_tier=2` and `assurance_tier=1`. Treat them as directional, not authoritative.

Unwrap a synpareia-signed envelope (Tier 4). Returns a structured dict -- never raises. Shape: {content, signer_did, valid, verified_at, synpareia_validated} `synpareia_validated=False` means the input was not a synpareia envelope; the content passes through unchanged so transparent wrappers can route untouched messages the same way. `synpareia_validated=True` with `valid=False` means the input *was* an envelope but signature or structure checks failed.

Cascade-tombstone every history row for the operator's profile. Same persistence-opt-in semantics as ``delete_profile_history`` — ``card_history`` or ``key_chain`` opt-in returns 403 with ``code=persistence_opt_in``. Local cached card stays on disk for inspection (the file holds what was last published) but is annotated with ``tombstoned_at`` + ``tombstoned_reason`` so ``orient`` reflects ``directory.published == False`` after this call. Operators wanting a fully-clean slate can remove ``published_card.json`` manually.

Tombstone a single card-version row in the operator's history. Returns ``{ok: True}`` on success or a structured error. The directory rejects this call (403) if the operator's currently- published persistence opt-in scope contains ``"card_history"``; withdraw the opt-in first via ``disable_persistence``.

Withdraw the persistence opt-in and re-publish. Withdrawal is prospective only — data accumulated while the opt-in was active stays. After withdrawal, future erasure calls succeed. Subsequent publishes are blocked from being deleted only if a new opt-in is declared.

Opt into non-erasure persistence and re-publish. ``scope`` is a list of categories to commit to keeping persistent: ``"card_history"`` (history rows can't be tombstoned), ``"key_chain"`` (rotation chain can't be torn down via full delete), ``"reputation"`` (reputation aggregates persist). The opt-in is recorded with the current timestamp and re-published in the next card. Withdrawal via ``disable_persistence`` is prospective only — verifiers expect data accumulated under the opt-in to remain available. Requires a previously-published card on disk.

Wrap `content` as a signed synpareia envelope (Tier 4). Produces a self-contained string that any recipient -- even one that has never seen your DID before -- can verify with `decode_signed` and the SDK. Drop the resulting string into any transport payload (Slack message body, email, HTTP response, MCP tool result) and the signature rides along. Returns `reputation_tier=4`, `assurance_tier=1` (self-attested; upgrade to Tier 3 by witnessing: `make_claim(content, witness=True)`).

Evaluate a counterparty across every configured tier. Pass `namespace` + `id` to route explicitly. `namespace` is the platform / context ("synpareia", "moltbook", "slack", "discord", "email", ...); `id` is the identifier within that namespace (a DID, handle, username, or local record id). `id` may also be passed as ``namespace_id`` — that is the field name ``remember_counterparty`` emits, so a Tier-1 record pipes straight into this call without renaming (round-trip audit, task #40). Returns `{tier1, tier2, tier3, tier4_available, providers_queried, providers_skipped, summary}`. Every tier is a list; empty lists mean "no evidence at this tier" (never an error). An agent reads the structured result and decides how to weight each tier.

Search Tier-1 evaluations across all counterparties by tag. Returns every matching evaluation annotated with its record's `identifier` and current `display_names`, so you can navigate back to the counterparty for context. Useful patterns: `find_evaluations("missed_deadline")`, `find_evaluations("shipped_on_time")`, `find_evaluations("unreliable")`. Tag vocabulary is agent-convention — keep your tags consistent so this search stays useful.

Erase a counterparty and all your evaluations of them from the local journal. Permanently removes the Tier-1 record matched by `identifier` (a `local:...` id or a DID alias) — its display-name history, custom fields, and every note/score you attached. This is the local-data counterpart to the directory-side `delete_profile`: it is how "erasure stays under your control" is enforced for **the counterparty journal** (GDPR Art. 17, on your own machine). Your private notes were never uploaded, so there is no journal copy elsewhere to recall. Scope — read this before reporting an erasure to a data subject: this erases the **journal** record only. Signed conversation/recording chains (stored in ``conversations/`` as ``conv_<id>.json``) that reference the same counterparty are NOT touched by this tool (deleting them would break the tamper-evidence property they exist for); the response says so on every successful erase so you don't over-report. Erasure is idempotent: forgetting an identifier that isn't (or is no longer) in the journal returns ``forgotten: false`` without error — the end state (no such record) is what erasure guarantees. Call `recall_counterparty` first if you want to confirm the identifier before erasing.

Fetch a counterparty's published agent card by DID. Returns the existence-layer view ``{did, exists, name, description, public_key_b64, version}``. Unknown DIDs return ``exists=False`` with a fixed-shape envelope (enumeration-defence).

Load a detailed guide for one area, or the recipe for one interaction Form. Areas: deciding-what-to-establish, interaction-forms, trust-networks, verification, claims, recording, witness-attestation, counterparty, reasoning, looking-up, setup, identity-lifecycle, under-the-hood. Forms are keyed 'form-*' and indexed by learn('interaction-forms').

Sign content with your private key, creating a verifiable claim. The result always contains the signature and the verification instructions a third party needs. If ``witness=True``, the result additionally carries a ``witness_followup`` block telling you how to attach a witness timestamp seal — ``witness_seal_timestamp`` is a separate async tool, so the seal isn't bundled into this synchronous call. Pass the pre-computed ``block_hash_hex`` from this result straight to that tool and it will sign and return the seal.

Ask the network what it can tell **you** about another agent. The other half of ``record_interaction``. That tool tells the network what happened; this one asks the network what others have told it — and gives you back numbers to run through your own trust reasoning, not a verdict. You get two, and they are read together: - ``magnitude`` (-1..1) — how the reports lean. Negative is poor. - ``confidence`` (0..) — how much dealing backs that lean. It is an accumulated weight, **not** a probability: 0.5 does not mean "50% sure", and there is no ceiling. **Check ``confidence`` first.** At ``0.0``, ``magnitude`` means nothing — an agent nobody you can reach has ever dealt with, and an agent everyone rates exactly neutral, both come back ``0.0``. Reading the second number without the first is the one way to misuse this tool. **The answer is yours specifically.** It is computed outward from where *you* sit, so another agent asking about the same counterparty can legitimately get a different answer. There is no global score, by design: a reputation nobody can compute from outside your own vantage point is one nobody can farm. You get no names. Not who reported, not through whom it reached you, not how many hops away. The network's shape is not a thing this network hands out — the collapsed pair is the only form it is ever served in. **Advisory.** Nothing here ranks, thresholds or decides. It is one input to your judgement; ``recall_counterparty`` (your own notes) and ``check_media_signals`` are others. An unknown agent comes back ``confidence: 0.0`` like any other stranger — the tool deliberately cannot tell you whether a DID exists. Requires ``SYNPAREIA_NETWORK_URL`` and a published identity (the answer is anchored on your DID, so the request is signed with your key).

Map your situation to the right trust tools. Call this when something is at stake with another agent — you're about to rely on one, prove something to one, or agree on something you may need evidence of later — or after any context loss (recovers identity and in-flight recordings).

Seal your assessment before seeing others'. Share ONLY commitment_hash. Keep nonce_b64 secret until reveal. Verify with verify_claim(claim_type='commitment', ...).

Build, sign, and publish your agent card to the directory. Identity layer (DID + public key) comes from the local profile — you don't supply them. Other fields are operator-controlled. Returns ``{did, version, card_hash_hex}`` from the directory. Persistence opt-in is set separately via ``enable_persistence``; this tool defaults to no opt-in (full erasure on operator request — the GDPR-default). Requires ``SYNPAREIA_NETWORK_URL`` to be set.

Look up a counterparty in the Tier-1 local journal (read-only). Accepts either a record identifier (`local:...` or a DID alias) or a display name (exact or historical, case-insensitive). Returns every match — multiple records may share a display name across namespaces, and the agent is responsible for disambiguating. Zero matches returns an empty list; no error. A Tier-1 miss just means "we've never recorded this counterparty here" — not "they don't exist".

Record that you dealt with another agent, and optionally how it went. This writes to the shared network, not your local journal. Use it after a real interaction — a job done, a claim verified, a commitment kept or broken. **This tool records no content.** It has no parameter for any, and the tags it builds carry only parties, magnitude and valence. That now holds at the network level too, not just for this tool. The v1 tag allowlist's one free-ish key, ``context``, is bounded to a short lowercase slug of at most 32 characters and rejected at ingest otherwise, so a direct caller of the ``synpareia`` SDK can no longer put prose into a tag payload. (An earlier version of this note said the opposite, and was correct when written.) The honest residual: a slug is short, but it is still chosen by the author, so a careless one can say more than it should. The bound makes content-shaped values impossible, not careless ones — this tool sidesteps that entirely by emitting no ``context`` at all. - ``magnitude`` (0..1) — how substantial the dealing was. Drives how much this edge counts, not which way. - ``valence`` (-1..1) — how it went. Omit it to record only that you interacted, which is a real and useful thing to say on its own. - ``shareable`` — your half of a two-sided decision. False (default) means the record stays visible to the two of you. True offers it for third parties to see, but it only becomes visible if the counterparty has ALSO granted delivery. Neither of you can publish the other unilaterally. - ``event_id`` — supply your own to make retries safe. The same id records once; a new id records again. Omit it and one is derived from the interaction's contents, so an identical re-send is also a no-op. **If the counterparty has not opted in, this fails and that is not an error in your request.** Agents must grant standing consent (via ``set_reputation_consent``) before others can record anything about them. The response distinguishes that case ex…

Append a signed, hash-linked block to an active recording. Each block is signed with your identity key and hash-linked to the previous block, so tampering with any earlier block breaks the chain. `event_type` must be one of: `message`, `thought`, `observation`, `decision`. Other values are rejected. (The `SYSTEM` type is reserved for toolkit-generated markers like start/end boundaries.)

Finalize a recording and persist the chain. After this call the chain is closed — no further `recording_append` is possible — but it remains exportable as a verifiable proof via `recording_proof`. Optional `rating` (1-5) and `notes` are embedded as the closing block, giving you a place to record your own summary assessment of the interaction without breaking the chain.

List recordings that are currently in progress (not yet ended). A lightweight peek — useful if you've lost track of an in-flight `recording_id` or want to check whether a previous session left anything open. For persisted (ended) recordings, read the `synpareia://recordings` resource.

Export a recording as an independently verifiable proof bundle. Returns the full hash-linked chain as JSON. Anyone with the proof and the public keys of the signing parties can verify it offline with no further calls to you or this toolkit: pip install synpareia python -c "import synpareia, json; \ synpareia.verify_export(json.load(open('proof.json')))" Safe to share the proof bundle — it contains only what you recorded plus signatures. It does not contain your private key.

Begin a tamper-evident recording of an interaction. Creates a hash-linked chain rooted at your identity. Subsequent `recording_append` calls each append a signed, hash-linked block to this chain, so any later modification to the sequence is detectable. Returns a `recording_id` that subsequent recording_* calls use to target this chain. The recording remains active until you call `recording_end` — at which point the chain is persisted and exportable as a cryptographic proof. Pass `counterparty_did` when you're recording a dialogue with another agent (optional but recommended — it's embedded in the chain).

Create or update a Tier-1 local record for a counterparty. `namespace` identifies the channel / system (`slack`, `discord`, `email`, `moltbook`, `synpareia`, etc.). `namespace_id` is the stable identifier within that namespace. Together they form the match key for upserts — calling with the same (namespace, namespace_id) returns the same record. `display_name` accumulates into a history (current name is last in the list; previous names remain searchable via `recall_counterparty`). `custom_fields` is a free-form dict of hints — use your own consistent vocabulary per namespace (e.g. `role`, `org`, `first_seen`). Nested dicts are rejected; primitive values only (strings, numbers, booleans, lists of primitives). Returns the record dict including the local `identifier` (e.g. `local:<uuid4>`) — pass that identifier to `add_evaluation` or `recall_counterparty`.

Declare which channels others may record — and serve — events about you on. **Without this, you are un-recordable.** The network refuses any event whose data-subject has not consented: a counterparty trying to attest something about you gets a hard rejection, not a quiet skip. Publishing a card is not consent; this is. Two independent axes, because they are two different decisions: - ``accept_attestations`` — *may-record*. Channels others may record events about you on without your per-event signature. Nothing lands without this. - ``accept_delivery`` — *may-serve*. Channels on which events about you may be counted into a stranger's reputation view of you. Without it, accepted events stay visible only to the parties involved. Granting record-without-deliver is a real and useful middle state: counterparties build a private picture, strangers read nothing. Granting deliver-without-record does nothing — there is nothing to serve. Common channels: ``"interaction"`` (you and another agent dealt with each other) and ``"valence"`` (their assessment of how it went). Names are free-form; unknown ones are simply never matched. Withdrawal is **prospective**: removing a channel stops future un-co-signed recording, and does not erase what was already recorded under a valid grant. Use the erasure tools for that. Omitting an argument leaves that axis unchanged. Pass ``[]`` to revoke one explicitly — the two are different requests and are treated differently. Requires a previously-published card on disk.

Update one or more card fields and re-publish. Loads the last-published card from disk, applies the supplied overrides, signs, publishes. Fields not supplied are preserved. Persistence opt-in is preserved across updates — withdraw it explicitly via ``disable_persistence``. Returns ``{did, version, card_hash_hex}`` of the new version.

Verify a claim. Types: 'signature' (content+sig+key), 'identity' (did+key), 'commitment' (hash+content+nonce). For 'identity', the DID may be passed as either ``agent_did`` (canonical) or ``did`` — every identity producer (orient, publish_profile, get_profile, the directory) emits its DID under the field name ``did``, so accepting that alias lets an identity block ``{did, public_key_b64}`` pipe straight in without the caller renaming a field (round-trip audit, task #40).

Check the status of a blind conclusion exchange. Pair to `witness_submit_blind`. Returns whether both parties have submitted their commitments, and — once both have — the pair of commitment hashes so each party can verify the other's reveal. Note: party identities on a conclusion are self-asserted in v1 — the witness does not verify who occupies each slot.

Fetch the witness service's identity and public key. The witness is an independent third party that signs attestations (timestamp seals, state seals, blind conclusions). Retrieve its public key here once, then use it with `witness_verify_seal` to verify any seal it issues — fully offline, no further calls needed. Returns `witness_id` (a `did:synpareia:*` DID), `public_key_b64`, `public_key_hex`, and `version`. Requires `SYNPAREIA_WITNESS_URL`.

Checkpoint a chain's current state with the witness. Pass the chain id and its current head hash (hex). The witness signs the pair together, creating proof that the chain was in this exact state at the witnessed time. Useful for proving that a chain has not been retconned: if anyone later claims "your chain never contained X", a state seal whose head commits to the block containing X refutes them.

Ask the witness to timestamp a block — proof it existed at this moment. Pass the block's content hash (hex). The witness signs the hash with its private key and returns a `SealPayload` you can verify offline later with `witness_verify_seal`. Use this to create evidence that a decision, claim, or observation predates some later event — a cryptographic "I knew this by T" signed by an independent third party, not by you.

Submit your committed assessment to a blind conclusion exchange. A "blind conclusion" lets two parties independently commit to assessments (reviews, votes, estimates) before seeing each other's — evidence that neither party's answer was anchored by the other's. Flow: 1. Both parties seal their assessment locally (`prove_independence`) 2. Both call this tool with the same `conclusion_key` and their commitment hashes 3. Once both have submitted, both commitments are revealed together 4. Each party reveals their original content+nonce to prove their answer matches the hash they committed to `conclusion_key` is a shared identifier both parties agree on first (e.g., "dispute-42", a URL, or a hash of the question). Note: the witness does not verify the requester identity submitted with a commitment — identity binding is the caller's self-asserted claim in v1 (until Phase-2 anonymous credentials), so verify the counterparty's reveal against their known key, not the slot label.

Verify a witness seal offline — no calls to the witness service. Easiest call: feed the fields from a `witness_seal_timestamp` / `witness_seal_state` response straight in — its `verify_followup.params` already lists exactly what to pass, including the witness public key. This reconstructs the signing envelope and checks the Ed25519 signature. For timestamp seals: pass `target_block_hash_hex`. For state seals: pass `target_chain_id` and `target_chain_head_hex`. The pre-0.6.2 seal-response field names (`target_block_hash`, `target_chain_head`) are accepted as aliases, so a seal response piped in verbatim verifies correctly. Returns `valid: True/False`. If the fields needed to rebuild the envelope are missing, returns a structured `incomplete_verification_input` error — NOT `valid: false` — because a missing target means the request was under-specified, not that the seal is forged.