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.

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:

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 for interpretation and the Compute Impact Reports API for exact fields.

SDK methods

The assembled TypeScript SDK exports LithiComputeClient from the package root. Its selected methods have these source signatures:

import { LithiComputeClient } from "@lithi-ai/compute-sdk";

new LithiComputeClient(options: ClientOptions)
client.pricing(): Promise<PublicPricingProjection>
client.createQuote(body: QuoteRequest, key?: string): Promise<QuoteResponse>
client.createJob(body: JobRequest, key?: string): Promise<JobProjection>
client.getJob(id: string): Promise<JobProjection>
client.getJobResult(id: string): Promise<ResultProjection>
client.createBatch(body: BatchRequest, key?: string): Promise<BatchProjection>
client.getBatch(id: string): Promise<BatchProjection>
client.listBatchResults(id: string, limit?: number, cursor?: string): Promise<Page<ResultProjection>>
client.prepareArtifact(body: ArtifactPrepareRequest, key?: string): Promise<ArtifactPrepareProjection>
client.completeArtifact(body: ArtifactCompleteRequest, key?: string): Promise<ArtifactProjection>
client.getReceipt(id: string): Promise<Receipt>

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 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 and the SDK parity guide 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.

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.

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.

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.

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.

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.

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.

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.

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.

export async function wrapBlockKeys(recipientPublicKey: Uint8Array, deks: readonly Uint8Array[], aad: PQHPKELeaseAAD, options: XWingWrapOptions): Promise<XWingWrappedBlockKeys>;

• 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.

export function bindApproval(quote: QuoteLike, decision: ApprovalDecision, nowMs: number): Readonly<ApprovedWork>;

• 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.

export function bindTransferPermission(decision: TransferDecision, nowMs: number, options: TransferLineageOptions = {}): Readonly<TransferPermission>;

• 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.

export async function submitApprovedJob(port: ComputeClientPort, approvedWork: ApprovedWork, jobRequest: JobRequestBody, options: Readonly<{
    now_ms: number;
    checkpoint: SubmissionCheckpoint;
}>): Promise<SubmitOutcome>;

• 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.

export async function resumeSubmission(port: ComputeClientPort, approvedWork: ApprovedWork, intent: SubmissionIntent, options: Readonly<{
    now_ms: number;
}>): Promise<SubmitOutcome>;

• 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.

export async function checkResultDescriptor(port: Pick<ComputeClientPort, 'getJobResult'>, jobId: string, options: DescriptorCheckOptions = {}): Promise<DescriptorCheck>;

• 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.

export async function deliverResult(request: DeliverResultRequest): Promise<DeliveryOutcome>;

• 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.

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.

export async function runPlan(plan: RunPlan, handlers: WorkflowHandlers, state: RunState, checkpoint: RunCheckpoint): Promise<RunState>;

• 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.

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.

export function discover(root: string, files: ReadonlyMap<string, string>, 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.

export function planSetup(detected: readonly DetectedClient[], desired: readonly DesiredChange[], files: ReadonlyMap<string, string>): 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.

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.

export async function assessUsage(input: UsageAssessmentInput): Promise<UsageAssessmentResult>;

• 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.

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.

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.

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:

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.