Agent frameworks

Python SDK

The Python SDK in vincs calls the Vinc HTTP API. Use it directly, or add the LangGraph or Microsoft Agent Framework adapter from the same package.

Install and connect

Requires Python 3.11 or later. This package also installs the vinc account command. See CLI installation for terminal use and the local runtime requirements.

This page describes vincs 0.1.5, which carries vinc-client 0.1.12. A feature that came after vincs 0.1.2 names the release it came with. The separate vinc-client package has the same methods under from vinc_client import VincClient.

pip install vincs

from vinc import VincClient

vinc = VincClient()                       # reads VINC_API_KEY
team = VincClient(space="<team id>")      # a team's graph instead of your personal one

Use it as a context manager, or call close() when you are done. AsyncVincClient has the same methods, awaited, and closes with aclose().

Read-only and write keys

With a read-only key, every write method raises VincAuthError with code read_only_key before anything is sent. A dry_run preview of a delete or merge counts as a write, because the server ranks it with the change it previews. vinc.read_only tells you whether the client holds a read-only key.

Context for one model call

block = vinc.get_context("Why are our colour tokens stored as OKLCH?")
if block:
    system_prompt += "\n\n" + block

get_context returns a text block ready to append to a system prompt, or None when nothing matched. The block is fenced and marked as reference data, because text in the graph can be written by anyone with access to it. It cites node ids the model can quote back.

If Vinc is unreachable or the daily limit is used up, it logs a warning and returns None, so your model call goes ahead. A key or space problem raises.

Reading

Every method also takes space= to use another space for that one call. brief and search take mode (general, current or historical), as_of and known_at to scope the answer in time; historical=True is the older way to include expired evidence.

Writing, on purpose

Nothing in the package writes because a conversation happened. Write with a vinc_sk_ key, after a person approved the result.

writer = VincClient(api_key=os.environ["VINC_WRITE_KEY"])
writer.record_episode(
    "Fixed contrast on the dark secondary button",
    summary="text-secondary now passes 4.5:1 on the dark surface.",
    about=["decision:tokens-are-oklch"],
)

record_episode reads every about id first, so a typo raises VincNotFound instead of creating an empty node. It also takes date, domain, tags and episode_id, and from vincs 0.1.4 create_only and operation_id, as write_package does.

ingest(nodes, edges) writes any nodes and links, merged by id. Properties you send replace the stored ones whole: read first and send the merged result, or, from vincs 0.1.3, put the node's expected_rev and a props_patch (a JSON Merge Patch) on it. If someone wrote in between, the whole write is refused. If part of the write was skipped or warned about, it raises VincPartialWrite; e.result holds what was stored and the warnings.

When the hub is briefly down

The hosted hub can stop answering for a moment, for example while a new version is deployed. From vincs 0.1.4 the client retries those cases, so they read as a slower call rather than an error.

• Retried: HTTP 502, 503 and 504, a dropped connection and a timeout. Anything else, including 401, 404, 409, 429 and 500, raises at once.
• Reads and previews (dry_run=True) are retried. A write is retried only when it carries an operation_id, because without one the server could apply it twice.
• The client waits as long as Retry-After says when the hub sends it, and otherwise waits longer after each try, up to 8 seconds. Once the next try would start more than retry_for seconds (90 by default) after the first, it stops and raises the last error. retry_for=0 turns retries off.
• get_context and prefetch never retry: they run inside a model call, so an outage makes them skip the context or stop at once. For your own code inside a model call, without_retries() returns the same client with retries off.

Retry a write

A write whose response was lost may or may not have landed. Give each logical write a fresh lowercase UUID as operation_id, and reuse it only to retry that write. ingest takes it from vincs 0.1.3; record_episode, write_package and the delete and merge calls from vincs 0.1.4.

import uuid
from vinc import VincUnavailable

op = str(uuid.uuid4())                                 # one id per logical write
try:
    writer.record_episode("Release checklist approved", about=["decision:release-plan"],
                          episode_id="episode:release-checklist-approved", operation_id=op)
except VincUnavailable:
    receipt = writer.operation_status(op)             # decide from the receipt, then retry with the same op

• An identical retry with the same operation_id returns the stored result without applying again. Changed arguments under the same id conflict.
• operation_status(operation_id) reads the receipt. accepted and unknown do not prove the write did not happen; committed means the graph transaction committed. A replayed result is a historical summary, so read the targets for their current state.
• Receipts belong to the owner, are kept until the owner's account is deleted, and are capped at 5,000 per owner. A read-only key can read them.
• create_only=True refuses ids that already exist, before any change. Without it, writes keep merging by id. A write with an operation_id is retried while the hub is briefly down; a write without one never is.

Delete and merge with a preview

delete, delete_edge, merge_nodes and doc_delete cannot be undone, so call each twice. With dry_run=True nothing changes and you get the complete preview with a preview_digest. Show it to a person, then apply with that digest. These calls come with vincs 0.1.4.

preview = writer.merge_nodes("concept:colour-tokens", "concept:color-tokens", dry_run=True)
# show the preview to a person, then apply exactly what they saw
writer.merge_nodes("concept:colour-tokens", "concept:color-tokens",
                   preview_digest=preview["preview_digest"], operation_id=str(uuid.uuid4()))

If the affected state changed after the preview, the apply call is refused instead of acting on something nobody saw. A preview that would be too large, or that touches a target the key cannot reach, is refused as well. Both calls need a write key; an operation_id on the apply call makes it safe to retry.

Roles and their evidence

role(role_id) reads a role's stored contract as it is now. prefetch(role_id, task) builds the block a model should see before it answers: the whole contract, the full text of each document the role says to read first, and Vinc's material on the task, with node ids the model can cite.

role = vinc.role("concept:agent-reviewer-judgement")             # id, props and the roles it works with
block = vinc.prefetch(
    "concept:agent-reviewer-judgement", "Review the proposed change.",
    max_chars=120000,
)

Prefetch reads the complete role contract and each required document by its declared document id on every call, without a cache. Each document must have complete text and a verified content hash; missing, partial or unverified documents raise prefetch_spec_unresolved before optional task lookup. Authentication and service errors propagate. The combined max_chars budget defaults to 24,000 characters. Large roles need a larger budget, such as the 120,000-character budget in this example. prefetch_budget_exceeded stops the read instead of truncating the contract or required documents. Your code picks the role and its budget. Helpers use max_chars for this same budget.

role() also returns the contract's rev and hash. To keep an agent on the contract you reviewed, pass that hash as pin to role, prefetch or prefetch_with_contract. When the role has changed, the call raises VincRoleChanged before any document is read, with the current id, rev and hash in details. Moving the pin to the new hash is your decision. The pin covers the role contract, not the text of the documents it lists. Over REST this is expected_hash on GET /v1/roles/{id}, which answers 409 role_changed. It comes with vincs 0.1.5.

pin = vinc.role("concept:agent-reviewer-judgement")["hash"]       # after you reviewed it
block = vinc.prefetch(
    "concept:agent-reviewer-judgement", "Review the proposed change.",
    max_chars=120000, pin=pin,
)

Role mode or context mode

In the framework adapters, role mode calls prefetch and context mode calls get_context.

The SDK keeps nothing between calls; the framework adapters decide how often to call. prefetch_with_contract and RoleToolPolicy come with vincs 0.1.4.

Hand a result to another agent

Write one package Record with the question, the conclusion and each claim's evidence, and give the next agent its id. Passing only citation ids loses the conclusion.

handoff = writer.write_package(                        # vinc_sk_ key
    "When does the dashboard become stale?", "Keep the 36 hour threshold.",
    claims=[{"claim": "Stale after 36 hours.", "evidence_ids": ["decision:threshold"]}],
    produced_by="agent:analyst", run_id="analysis-1", space="personal",
)
block = vinc.get_package_context(handoff["package_id"], space=handoff["space"])   # next agent

The space must be named, and the evidence must already exist in it. Each read checks every evidence id again with the reader's key, so deleted or unreadable evidence is marked as not citable. Source text is never copied into the package. Use a new package id for each handoff.

Check an answer against a role

OutputGate checks a final answer against the role's gates, never_checks and person_only, outside the model. evaluate returns pass, block or interrupt; require_pass raises OutputGateStopped on the last two.

from vinc import OutputGate

gate = OutputGate(role["props"])
result = gate.evaluate(final_answer)
print(result.verdict)                                  # pass, block or interrupt

A claim that something ran needs a ToolProof built from a real tool call your host saw in this run; never build one from the model's output. A prose-only contract or an unknown check blocks. A pass releases the answer and nothing more: it does not run, permit or undo a tool. RoleOutput, prepare_person_only and resolve_person_only turn a person-only request into an approval bound to that exact draft; the framework packages wire them into their own approval steps.

Validate a review

parse_review checks a reviewer's JSON against ReviewOutput: a verdict of ACCEPT or RETURN, findings with citations, and person-only requests. RETURN needs findings and ACCEPT needs none; malformed JSON or extra fields raise. A valid shape does not prove the citations exist or that anyone approved.

Errors

Other public names

Everything below is importable from vinc, or from vinc_client in the separate package.