> ## Documentation Index > > Fetch the complete documentation index at: https://lithi.ai/llms.txt > > Use this file to discover all available pages before exploring further. # Compute Kit API and tool reference Choose an interface by where the work happens. Remote Work tools request or read Compute work. Language SDK methods validate and send the wire contract. Kit helpers prepare data, compose bounded work and deliver results locally. Agent skills explain the process. A method in one group does not become a tool in another group. The Kit is a harness around an existing agent: it supports permitted preparation, an approved connection, quote and approval handling, submission and result handling. The agent keeps its own model, context, planning, edits, builds, tests and final decision. A compatible agent needs a supported MCP or API transport and approved account access. | Interface | Kind | Boundary | | --- | --- | --- | | `lithi.quote` | Remote Work tool | Requests a quote for a declared scope; a quote is a price, not permission. | | `lithi.run` | Remote Work tool | Requests authorized execution for an approved scope. | | `lithi.batch` | Remote Work tool | Requests execution-equivalent work for a declared batch. | | `lithi.status` | Remote Work tool | Reads current job state. | | `lithi.result` | Remote Work tool | Reads accepted result metadata; it does not by itself read or verify artifact bytes. | | `LithiComputeClient` | TypeScript SDK | Validates wire requests and responses, then uses the supplied transport. | | `@lithi/kit-core`, `@lithi/kit-data`, `@lithi/kit-workflows`, `@lithi/kit-setup` | TypeScript local modules | Prepare, seal, compose, resume, deliver or inspect locally; they do not silently dispatch work. | | Python adapters and result bundle helpers | Python SDK helpers | Validate supported records and read result bundles with caller-supplied I/O and key custody. | | Agent skills | Instructions | Explain decisions and recovery; they grant no access or authority. | ## Remote Work tools Use the five `lithi.*` tools through the connected agent host. Their live schemas and account authority are the source of truth for a request. Keep these boundaries in the call sequence: ```text title="Remote Work tools" kind="data" lithi.quote ↓ Approval bound to that quote ↓ lithi.run or lithi.batch ↓ lithi.status ↓ lithi.result ``` The quote, approval and transfer decisions are separate. An uncertain submission is reconciled with its original identity before a retry; do not invent a new request identity to bypass an ambiguous response. ## Monthly reporting is separate An authorized monthly report is read through its reporting API with `reporting:read` permission or from an approved report file. It is not a sixth Work tool. The report can expose distinct `accepted_work_macs`, `physical_activity_macs` and `provider_accounts` populations with availability labels. Those populations are not additive, and a provider-account count does not establish a people count. Use the [Compute impact report](/docs/compute/impact-report) for interpretation and the [Compute Impact Reports API](/docs/compute/reference/impact-reports) for exact fields. ## SDK methods The assembled TypeScript SDK exports `LithiComputeClient` from the package root. Its selected methods have these source signatures: ```ts title="SDK methods example" kind="code" import { LithiComputeClient } from "@lithi-ai/compute-sdk"; new LithiComputeClient(options: ClientOptions) client.pricing(): Promise client.createQuote(body: QuoteRequest, key?: string): Promise client.createJob(body: JobRequest, key?: string): Promise client.getJob(id: string): Promise client.getJobResult(id: string): Promise client.createBatch(body: BatchRequest, key?: string): Promise client.getBatch(id: string): Promise client.listBatchResults(id: string, limit?: number, cursor?: string): Promise> client.prepareArtifact(body: ArtifactPrepareRequest, key?: string): Promise client.completeArtifact(body: ArtifactCompleteRequest, key?: string): Promise client.getReceipt(id: string): Promise ``` `pricing()` implements the compatibility wire contract; it is not the current customer tariff. The legacy per-service projection returns a typed unavailable outcome with a next action. Read [current informational token rates](/pricing) for planning (`GET https://lithi.ai/api/public/compute/pricing` for structured rates) and the signed quote for the exact approved work. A supported SDK method or historical DTO does not make old page, minute, build or test-unit prices current. These methods validate exact request fields, identity bindings and response projections. Invalid inputs or responses produce the SDK's typed error outcomes. Transport ambiguity remains ambiguous and is reconciled using the same idempotency key; it is not treated as a confirmed second submission. The package exports the TypeScript client source as part of the approved supplied artifact. Its package name does not imply public registry installation. The other SDK families are different surfaces. Python supplies selected adapters, result-bundle and impact helpers. Go, Swift and .NET primarily supply wire clients. Check the [language client guides](/docs/compute/clients) and the [SDK parity guide](/docs/compute/clients) before assuming a local helper exists in another language. The customer export includes Go SDK source even when a separate client guide is withheld; JVM guidance is not a JVM SDK package. ## Kit helpers These local helpers compose preparation, submission, results, workflows and setup. Choose the group from the action you need; the full signature and refusal below each helper is the contract. ### Prepare and protect input ### `prepareRecords` Exported local helper. Import from `@lithi/kit-data`. ```ts title="prepareRecords signature example" kind="code" export function prepareRecords(rawInput: unknown): PreparationResult; ``` - **Input:** one object containing schema, records, field policy, alias scope, detectors and secret scanners - **Output:** PreparationResult: decision, safe summary, protected local evidence and an eligible derivative - **Effect:** local inspection, transformation and re-scan; no transfer - **Refusal:** blocked or review_required cannot produce a sealing commitment; invalid API input throws a typed error - **Example:** `examples/privacy/run-lifecycle.ts` ### `preparedBinding` Exported local helper. Import from `@lithi/kit-data`. ```ts title="preparedBinding signature example" kind="code" export function preparedBinding(result: PreparationResult): string; ``` - **Input:** the genuine PreparationResult from prepareRecords - **Output:** the eligible preparation commitment - **Effect:** local check only - **Refusal:** PREPARATION_NOT_ELIGIBLE for blocked or review_required; UNKNOWN_PREPARATION for an unrecognized result - **Example:** `examples/typescript/src/full-journey.ts` ### `createAliasScope` Exported local helper. Import from `@lithi/kit-data`. ```ts title="createAliasScope signature example" kind="code" export function createAliasScope(params: unknown): AliasScope; ``` - **Input:** tenant, purpose, dataset_scope, map_version and caller-supplied keyMaterial; optional tokenHexLength - **Output:** an opaque AliasScope handle - **Effect:** derives and holds local scoped key material; no network or persistent store - **Refusal:** rejects short production key material or token length; caller must supply a secure random key - **Example:** `examples/privacy/run-lifecycle.ts` ### `aliasFor` Exported local helper. Import from `@lithi/kit-data`. ```ts title="aliasFor signature example" kind="code" export function aliasFor(scope: AliasScope, entityType: string, canonicalEntityId: string): string; ``` - **Input:** AliasScope, entityType and canonicalEntityId - **Output:** a stable alias within the selected scope - **Effect:** local keyed derivation and collision tracking - **Refusal:** invalid identity or a collision refuses instead of merging entities - **Example:** `examples/privacy/run-lifecycle.ts` ### `restoreOutputs` Exported local helper. Import from `@lithi/kit-data`. ```ts title="restoreOutputs signature example" kind="code" export function restoreOutputs(rawRequest: unknown): readonly RestorationItemResult[]; ``` - **Input:** one restoration request with accepted-result identity, matching map and allowed fields - **Output:** per-item RestorationItemResult outcomes - **Effect:** local authorized identity restoration - **Refusal:** invalid requests refuse; unauthorized or mismatched item restoration stays visible in the outcomes - **Example:** `examples/privacy/run-lifecycle.ts` ### `splitUnits` Exported local helper. Import from `@lithi/kit-core`. ```ts title="splitUnits signature example" kind="code" export function splitUnits(units: readonly SplitUnit[], options: SplitOptions): SplitUnitsResult; ``` - **Input:** SplitUnit array and SplitOptions including the matching measurer and limits - **Output:** SplitUnitsResult with pieces and refusals - **Effect:** local deterministic splitting; no Mac or execution placement - **Refusal:** indivisible oversize input produces SPLIT_PLAN_REQUIRED; the suggested plan is not applied - **Example:** `examples/typescript/src/full-journey.ts` ### `sealBlocks` Exported local helper. Import from `@lithi/kit-core`. ```ts title="sealBlocks signature example" kind="code" export function sealBlocks(units: readonly SealUnit[], options: SealOptions): SealResult; ``` - **Input:** prepared measured SealUnit array and SealOptions with profile, envelope and preparation bindings - **Output:** SealResult: encrypted blocks, a content-free manifest and a separate local key holder, or a refusal - **Effect:** local AES-256-GCM encryption; no upload or key release - **Refusal:** invalid bindings, oversized groups and incompatible measurement refuse - **Example:** `examples/typescript/src/full-journey.ts` ### `sealUnitsFromSplitPieces` Exported local helper. Import from `@lithi/kit-core`. ```ts title="sealUnitsFromSplitPieces signature example" kind="code" export function sealUnitsFromSplitPieces(pieces: readonly SplitPiece[], options: SplitPieceSealOptions): SealUnit[]; ``` - **Input:** SplitPiece array and SplitPieceSealOptions - **Output:** SealUnit array ready for sealBlocks - **Effect:** local shape conversion only; this function does not encrypt - **Refusal:** invalid pieces or binding options refuse - **Example:** `packages/core/src/compile/seal.ts` ### `wrapBlockKeys` Exported local helper. Import from `@lithi-ai/compute-sdk`. ```ts title="wrapBlockKeys signature example" kind="code" export async function wrapBlockKeys(recipientPublicKey: Uint8Array, deks: readonly Uint8Array[], aad: PQHPKELeaseAAD, options: XWingWrapOptions): Promise; ``` - **Input:** leased recipient public key, assigned block DEKs, canonical lease AAD and required shard identity/global block ordinals - **Output:** one HPKE-wrapped shard key and authenticated AES-GCM-wrapped block keys - **Effect:** local cryptographic wrapping only; does not choose a recipient, grant access or release keys - **Refusal:** invalid scope, missing pinned HPKE libraries, expiry or malformed keys refuse; ordinal sets must be strictly increasing within the manifest bounds - **Example:** `sdk/typescript/src/xwingBlockKeys.ts` ### Bind and submit approved work ### `bindApproval` Exported local helper. Import from `@lithi/kit-core`. ```ts title="bindApproval signature example" kind="code" export function bindApproval(quote: QuoteLike, decision: ApprovalDecision, nowMs: number): Readonly; ``` - **Input:** the quote, ApprovalDecision and current time - **Output:** ApprovedWork bound to that exact quote and decision - **Effect:** records the supplied approval locally; server admission remains separate - **Refusal:** changed scope, expired quote or incompatible ceiling refuse - **Example:** `examples/typescript/src/real-sdk-journey.ts` ### `bindTransferPermission` Exported local helper. Import from `@lithi/kit-core`. ```ts title="bindTransferPermission signature example" kind="code" export function bindTransferPermission(decision: TransferDecision, nowMs: number, options: TransferLineageOptions = {}): Readonly; ``` - **Input:** TransferDecision, current time and optional lineage options - **Output:** a bound TransferPermission - **Effect:** records transfer permission locally; does not transfer bytes or approve spending - **Refusal:** invalid or mismatched transfer identity and lineage refuse - **Example:** `examples/typescript/src/real-sdk-journey.ts` ### `submitApprovedJob` Exported local helper. Import from `@lithi/kit-core`. ```ts title="submitApprovedJob signature example" kind="code" export async function submitApprovedJob(port: ComputeClientPort, approvedWork: ApprovedWork, jobRequest: JobRequestBody, options: Readonly<{ now_ms: number; checkpoint: SubmissionCheckpoint; }>): Promise; ``` - **Input:** ComputeClientPort, ApprovedWork, JobRequestBody and options with now_ms and checkpoint - **Output:** SubmitOutcome - **Effect:** writes intent through the caller checkpoint, then dispatches through the supplied port - **Refusal:** approval/request mismatch refuses; an uncertain dispatch remains an unknown outcome for reconciliation - **Example:** `examples/typescript/src/real-sdk-journey.ts` ### `resumeSubmission` Exported local helper. Import from `@lithi/kit-core`. ```ts title="resumeSubmission signature example" kind="code" export async function resumeSubmission(port: ComputeClientPort, approvedWork: ApprovedWork, intent: SubmissionIntent, options: Readonly<{ now_ms: number; }>): Promise; ``` - **Input:** ComputeClientPort, ApprovedWork, original SubmissionIntent and now_ms options - **Output:** reconciled SubmitOutcome - **Effect:** reads/reconciles through the supplied port and replays only the permitted original intent - **Refusal:** changed identity, approval or request bindings refuse; never rotates the idempotency key - **Example:** `examples/typescript/src/real-sdk-journey.ts` ### Verify and deliver results ### `checkResultDescriptor` Exported local helper. Import from `@lithi/kit-core`. ```ts title="checkResultDescriptor signature example" kind="code" export async function checkResultDescriptor(port: Pick, jobId: string, options: DescriptorCheckOptions = {}): Promise; ``` - **Input:** a getJobResult port, jobId and optional recorded descriptor - **Output:** DescriptorCheck at most descriptor_matched - **Effect:** reads metadata through the supplied port, which may make a network call; reads no artifact bytes - **Refusal:** foreign, changed, malformed or undelivered result metadata refuses - **Example:** `examples/typescript/src/full-journey.ts` ### `deliverResult` Exported local helper. Import from `@lithi/kit-core`. ```ts title="deliverResult signature example" kind="code" export async function deliverResult(request: DeliverResultRequest): Promise; ``` - **Input:** one DeliverResultRequest with result port, job identity, recipient, channel, validator, destination and any required decryptor - **Output:** DeliveryOutcome with named stage reports - **Effect:** retrieves and processes bytes using caller adapters, then commits to the supplied destination - **Refusal:** failed integrity, decryption, schema, coverage or destination checks prevent a successful commit - **Example:** `examples/delivery/deliver-to-directory.mjs` ### Coordinate workflows ### `planRun` Exported local helper. Import from `@lithi/kit-workflows`. ```ts title="planRun signature example" kind="code" export function planRun(workflow: WorkflowDefinition, request: PlanRequest): RunPlan; ``` - **Input:** WorkflowDefinition and PlanRequest - **Output:** deterministic RunPlan - **Effect:** local planning only - **Refusal:** invalid definitions or stage dependencies refuse - **Example:** `examples/typescript/src/full-journey.ts` ### `runPlan` Exported local helper. Import from `@lithi/kit-workflows`. ```ts title="runPlan signature example" kind="code" export async function runPlan(plan: RunPlan, handlers: WorkflowHandlers, state: RunState, checkpoint: RunCheckpoint): Promise; ``` - **Input:** RunPlan, WorkflowHandlers, RunState and RunCheckpoint - **Output:** updated RunState - **Effect:** runs declared caller handlers and checkpoints; handlers own any I/O effects - **Refusal:** changed plans, invalid state and failed required stages remain explicit - **Example:** `examples/typescript/src/full-journey.ts` ### `resumeRun` Exported local helper. Import from `@lithi/kit-workflows`. ```ts title="resumeRun signature example" kind="code" export function resumeRun(plan: RunPlan, state: RunState): readonly StageDefinition[]; ``` - **Input:** the original RunPlan and persisted RunState - **Output:** the StageDefinition array eligible to resume - **Effect:** local state validation and selection; does not execute stages - **Refusal:** changed plan or inconsistent persisted state refuses - **Example:** `packages/workflows/src/resume.ts` ### Inspect usage and setup ### `discover` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="discover signature example" kind="code" export function discover(root: string, files: ReadonlyMap, clientIds: readonly string[] = REGISTERED_CLIENT_IDS): readonly DetectedClient[]; ``` - **Input:** the documented discovery input with an injected file projection - **Output:** host discovery results - **Effect:** inspects supplied local metadata; no process launch or configuration write - **Refusal:** unsupported or unobserved host capabilities remain explicit - **Example:** `examples/typescript/src/full-journey.ts` ### `planSetup` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="planSetup signature example" kind="code" export function planSetup(detected: readonly DetectedClient[], desired: readonly DesiredChange[], files: ReadonlyMap): SetupPlan; ``` - **Input:** documented setup input and requested configuration - **Output:** a deterministic configuration plan - **Effect:** local preview; no installation - **Refusal:** unsupported host or scope is reported without applying a change - **Example:** `packages/setup/src/plan-setup.ts` ### `doctor` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="doctor signature example" kind="code" export function doctor(input: DoctorInput): readonly DiagnosticFinding[]; ``` - **Input:** DoctorInput with the supplied setup projection - **Output:** diagnostic findings - **Effect:** local checks over supplied evidence; does not apply changes - **Refusal:** missing or unavailable evidence remains a finding, never an invented pass - **Example:** `examples/typescript/src/full-journey.ts` ### `assessUsage` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="assessUsage signature example" kind="code" export async function assessUsage(input: UsageAssessmentInput): Promise; ``` - **Input:** UsageAssessmentInput with a registered host, authorized reading mode, task, overage state and current time - **Output:** UsageAssessmentResult with a bucketed summary, recommendation and agent-safe context - **Effect:** uses the selected local reading adapter and optional summary sinks; no paid Compute work or account changes - **Refusal:** unknown hosts refuse; failed or unrecognized readings remain UNKNOWN rather than LOW; raw account figures stay local - **Example:** `packages/setup/src/__tests__/usage.test.ts` ### `summarizeUsage` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="summarizeUsage signature example" kind="code" export function summarizeUsage(snapshot: AgentUsageSnapshot, now: Date): UsagePressureSummary; ``` - **Input:** an AgentUsageSnapshot minted by normalizeUsageSnapshot and the current time - **Output:** a branded UsagePressureSummary with pressure, binding window, reset bucket and reason codes - **Effect:** local arithmetic only; no network calls, work submission or raw-usage disclosure - **Refusal:** unsealed snapshots refuse; missing readings remain UNKNOWN; early-window pace remains unresolved - **Example:** `packages/setup/src/__tests__/usage.test.ts` ### `recommendUsageFit` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="recommendUsageFit signature example" kind="code" export function recommendUsageFit(input: UsageFitInput): UsageFitRecommendation; ``` - **Input:** UsageFitInput containing the branded summary, actual host/pool, task fit, urgency and overage state - **Output:** CONTINUE, WAIT_FOR_RESET, ASSESS_LITHI, COST_FIT_ONLY or INSUFFICIENT_USAGE_DATA with reasons - **Effect:** local policy evaluation only; paid_activity is NONE and human approval remains required - **Refusal:** unbranded summaries refuse; unsupported work, mismatched pools or unresolved evidence cannot prove allowance preservation - **Example:** `packages/setup/src/__tests__/usage.test.ts` ### `evaluateEconomics` Exported local helper. Import from `@lithi/kit-setup`. ```ts title="evaluateEconomics signature example" kind="code" export function evaluateEconomics(input: EconomicsInput): EconomicsEvaluation; ``` - **Input:** EconomicsInput with billing shape, task, usage summary when applicable, current quote, measured baseline, retained work, overhead and like-for-like gates - **Output:** EconomicsEvaluation separating usage value, cost comparability, cost position and next steps - **Effect:** local comparison only; no quote request, reservation, transfer or paid submission; agent output uses bands rather than raw account figures - **Refusal:** unusable quote, baseline, overhead, data fit or timing stays unresolved; zero baseline cannot produce a percentage saving - **Example:** `packages/setup/src/__tests__/economics.test.ts` `evaluateEconomics` composes usage fit and cost fit into the closed contract `lithi.kit.economics-evaluation.v1`. It evaluates the billing shape, task fit, current usage summary, current quote, measured baseline, retained frontier work, preparation/verification/delivery overhead and `like_for_like` gates. It never exposes an amount, percentage, rate or timestamp in its result; `raw_figures_disclosed` is the literal `false`, `paid_activity` is `NONE` and `requires_human_approval` is `true`. The nested usage result, when present, keeps the exact usage outcomes `CONTINUE`, `WAIT_FOR_RESET`, `ASSESS_LITHI`, `COST_FIT_ONLY` and `INSUFFICIENT_USAGE_DATA`; those values describe the current allowance decision and are separate from the composed economics outcome. Cost comparability is evaluated in this order: an unexpired quote, a measured and fresh baseline, matching `like_for_like` fields (`same_task`, `same_volume`, `same_output`, `same_quality_threshold`, `same_verification`, `same_timing` and `same_data_handling`), bound cache and tool fees, a bound model where required, and explicit retained-frontier, preparation, verification and delivery evidence. The corresponding mismatch codes are `NOT_SAME_TASK`, `NOT_SAME_VOLUME`, `NOT_SAME_OUTPUT`, `NOT_SAME_QUALITY_THRESHOLD`, `NOT_SAME_VERIFICATION`, `NOT_SAME_TIMING` and `NOT_SAME_DATA_HANDLING`. Missing, stale or unconvertible evidence leaves the result unresolved. The result uses these exact comparability values: `COMPARABLE`, `NOT_COMPARABLE`, `INSUFFICIENT_BASELINE`, `ZERO_BASELINE` or `QUOTE_REQUIRED`. It returns `QUOTE_REQUIRED` for no active or expired quote, `INSUFFICIENT_BASELINE` for no measured or stale baseline, and `NOT_COMPARABLE` for a mismatch, unbound fees or model, an unaccounted retained frontier/preparation/verification/delivery component, or an unconvertible unit. A zero baseline cannot produce a percentage saving. When the comparison is `COMPARABLE`, `position` is `LITHI_LOWER`, `LITHI_HIGHER` or `SIMILAR`, and `difference_band` is `within_5_percent`, `5_to_25_percent`, `25_to_50_percent` or `over_50_percent`. Otherwise `position` and `difference_band` remain `null` unless the zero-baseline contract supplies the documented higher-or-similar position. The composed `outcome` then follows the billing shape. An unsuitable task always yields `KEEP_CURRENT_AGENT`. An included allowance can yield `KEEP_CURRENT_AGENT`, `WAIT_FOR_RESET`, `OFFLOAD_OPPORTUNITY_IDENTIFIED` or `INSUFFICIENT_USAGE_DATA`. A metered shape can yield `LITHI_LOWER_COST`, `SIMILAR_COST`, `LITHI_HIGHER_COST`, `NOT_COMPARABLE`, `INSUFFICIENT_BASELINE` or `QUOTE_REQUIRED`. When the cost comparability is `ZERO_BASELINE`, the composed outcome is `LITHI_HIGHER_COST` and the position is `LITHI_HIGHER` or `SIMILAR`. An unknown billing shape yields `INSUFFICIENT_BASELINE`. The evaluator may add `DIRECT_COST_COMPARISON_REQUIRED` for metered shapes and `QUOTA_PRESERVATION_MEASURED` only for a fresh, completed, matching-pool measurement. Its exact composed outcome set is `KEEP_CURRENT_AGENT`, `WAIT_FOR_RESET`, `OFFLOAD_OPPORTUNITY_IDENTIFIED`, `LITHI_LOWER_COST`, `SIMILAR_COST`, `LITHI_HIGHER_COST`, `NOT_COMPARABLE`, `INSUFFICIENT_BASELINE`, `QUOTE_REQUIRED` or `INSUFFICIENT_USAGE_DATA`. Its full `EconomicsEvaluation` also returns `schema_version`, `host_id`, `billing_shape`, optional `usage`, `cost`, `claims`, `reason_codes`, `next_steps`, `lithi_recommended`, `requires_human_approval`, `paid_activity` and `raw_figures_disclosed`. `lithi_recommended` never removes the human approval requirement. ## Result levels and Python helpers The Core delivery report names these levels in order: ```text title="Result levels and Python helpers" kind="data" descriptor_matched transfer_authorised bytes_verified decryption_authenticated schema_validated coverage_reconciled destination_committed quality_evaluated (outside the Kit) ``` `not_applicable` means a delivery profile has no such step; it does not mean a required check was skipped. Python's selected result helpers follow the same distinctions: `verify_result_bundle` checks the descriptor contract, `read_artifact_rows` checks transferred parts and decoding, and `LocalDirectoryDestination` commits verified files without overwriting conflicts. Python receives caller-supplied fetch, decrypt and destination facilities; it does not expose the complete TypeScript privacy and workflow modules. For the reader-facing workflow, continue with the [Kit agent guide](/docs/compute/kit/agent-guide).