Savvy

Binds a locally generated toolchain key to this conversation's Savant session so the plugin's scripts can call the Savant web-app API as you. Returns no secret. Run `savant.py session pair` first: it generates the key on this machine and prints its pairingHash; pass that hash here. Returns apiBaseUrl (base URL for API calls) and tabId (the 'X-SAVANT-TAB' header value for this conversation's current workspace). Binding the same hash again renews its validity window, so call this right before a sequence of API requests and again if an API call returns 401.

Describe the Savant entity types available through search and fetch — what each type is and how the types relate to each other. Call once for orientation before exploring.

Fetch the full detail of one Savant entity by id — either a savant:// URI returned by search (e.g. savant://workflow/abc123) or the {type}/{id} shorthand (e.g. workflow/abc123). A savant://sample/{id} fetch returns a dataset's sample rows: samples are collected under a 1000-row cap, so the rows you count in the response say what you are holding — fewer than the cap means the whole dataset, exactly 1000 means a preview of a larger dataset whose total is not known. A capped sample must never be used to answer a how-many or count question about the dataset: say the preview cannot settle it, and offer to build a workflow, which runs against the complete dataset. Binary (document) columns come back summarised, never inlined: each cell carries the file name, format, size and page count with `contentOmitted: true`, not the bytes. To work with a document's content, run a flow with an extraction step over the dataset; re-fetching the sample will not return the bytes. The fetched record is the only source for an entity's attributes: a dataset's created date, owner and originating system are stated from it, never inferred from a name, a date in a filename, or surrounding context, and an attribute not yet read is reported as unread, not filled in.

Resolve which workspace owns a Savant entity that is NOT in your current workspace, so you can switch there and read it. Pass an id in the same form search returns and fetch accepts — a savant:// URI (e.g. savant://workflow/abc123) or the {type}/{id} shorthand (e.g. workflow/abc123). Returns the owning namespace plus its organization and workspace; pass the namespace to switch-workspace, then fetch the entity in scope. For entities already in your current workspace, use search/fetch instead.

Search Savant entities (workflows, folders, sources, connections, ...) in the current workspace scope. Empty query lists everything in each type's default ordering. Every word of the query must appear in an entity's name, description or connector, in any order; spaces, underscores and hyphens are ignored, so 'sales order' also finds 'SalesOrders.csv' and 'SALES_ORDER'. There is no fuzzy matching or stemming: a misspelled word matches nothing. Type words like 'connection' or 'sources' are NOT wildcards and match nothing; to list a type, use an empty query with types. Returns one page of ranked results with savant:// URIs that can be passed to fetch. Optional per-type filters narrow within a type — see the filters parameter. Results are PAGED: keep passing the returned cursor while one comes back to read a type to the end. For "how many" questions set includeTotals=true — the first page then reports the exact total per type in ONE call, so never page through results just to count them, and never estimate a count from a page. A total is exact only when includeTotals returned it or you read to the last page; any other number is a floor ("at least N") and is never described as counted. A dataset hit carries its system, rows and columns only: its created date and owner come from fetch, never from its name or a date in a filename.

Switches this session to a different workspace or organization. Pass the target namespace (shown on workspace/organization search results and fetch payloads, on whereami for the current scope, or from locate for an entity in another workspace) — or the savant://workspace/{id} URI straight from a search hit. Subsequent calls (search, fetch, whereami, get-api-credentials) operate in the new workspace. The switch persists for the session's life; a full re-authorization resets to the bootstrap namespace. You can only switch to workspaces/organizations you have access to.

Returns the caller's current workspace scope for this conversation — namespace, organization, and workspace, with the caller's role at each level. Present the organization and workspace by name (the namespace is fine to mention); never surface or refer to internal session or tab identifiers, or those concepts. The active workspace can change via switch-workspace and is independent per conversation; this reflects the current one. If the result carries a note, relay it to the user verbatim: it means they currently have access to no workspace at all.

Returns the authenticated caller's identity: the email address they are signed in with. This is the caller's stable identity — the same across all their conversations; use whereami for the current workspace, which is per-conversation. Derived entirely from the access token.