Labs · AI execution · local preview · 0.1.0-rc.3
AI Execute API
One job. One budget.
Bind an approved AI job budget, reserve maximum exposure before dispatch and recover the original provider job. This cost contract is separate from the payment obligation contract.
Install the preview clients.
Download the two SDK archives and checksums from the Execute preview. These are versioned direct downloads. The packages are not published to PyPI or npm.
python3 -m pip install --no-index --no-deps \
./haltseal_execute_sdk_preview-0.1.0rc3-py3-none-any.whl
npm install --ignore-scripts \
./haltseal-execute-sdk-preview-0.1.0-rc.3.tgzThe complete local evaluator is available by request. It supplies the running gateway, approval source, customer-bound keys and two separate local provider fixtures. Installing the SDK alone creates none of them.
The reference origin is http://127.0.0.1:8787, explicitly enabled for loopback evaluation. HTTPS is required elsewhere. Keep bearer keys and provider credentials on your backend.
Import the real approval
Read the signed approval input contract for the exact record schema and signature canonicalization.
The trusted order source signs customer identity, source order identity and cumulative approved budget. An admin key imports it with POST /v1/businesses. Customer-bound execution keys cannot create funding or choose another customer’s budget.
Use the returned business_id for every attempt of that business. New aliases, agent keys or providers do not add funding. The approval source must identify the real job; HALTSEAL cannot infer hidden duplication across unrelated order IDs.
Execute through the gateway.
This example assumes the local gateway is running, an approval has been imported and the evaluator has provided customer_key and business_id.
from haltseal_sdk import Client
client = Client("http://127.0.0.1:8787", customer_key,
allow_loopback_http=True)
execution = client.execute(
business_id=business_id,
attempt_key="render-1",
connection_id="lab",
action="lab.fixed_job.v1",
parameters={"prompt": "Synthetic square"},
max_cost_micro="12000000",
)
observed = client.recover(execution["id"])USD costs use integer micro-unit strings. 12000000 means a $12 maximum. The configured provider contract determines the enforceable ceiling; a client estimate does not establish it.
Keep the same business and attempt key after transport uncertainty. An identical gateway request retrieves its historical execution; changed economic content conflicts. The gateway owns durable dispatch intent and provider sending.
Current business API.
Protected routes use provisioned bearer keys. Tenant and customer come from the live key. Read the versioned OpenAPI JSON for exact schemas.
| Method and path | Purpose |
|---|---|
POST/v1/businesses | Admin imports an authenticated cumulative approval. |
GET/v1/businesses/{business_id} | Read the authorized business and its budget. |
POST/v1/businesses/{business_id}/aliases | Admin registers an unfunded, immutable locator. |
POST/v1/business-executions | Reserve capacity and dispatch the approved job. |
GET/v1/executions/lookup?scope_id=...&operation_key=... | Look up the original attempt using its business ID or registered alias. |
GET/v1/executions/{execution_id} | Read historical execution state. |
POST/v1/executions/{execution_id}/recover | Read-only original-job lookup and settlement. Body: {}. |
POST/v1/executions/{execution_id}/resume | Explicitly recheck a HELD or unexposed PREPARED execution. Body: {}. |
POST/v1/executions/{execution_id}/cancel | Cancel without refunding unresolved exposure. Body: {}. |
GET/v1/executions/{execution_id}/receipt | Read an unsigned historical digest. It grants no dispatch permission. |
GET/v1/scopes/{scope_id} | Read the canonical authorized balance, with aliases resolved. |
POST /v1/executions is unavailable in this preview. Use the authenticated business API above. Billing routes are a separate test contract. This preview offers no active checkout or subscription.
Keep UNKNOWN exposure reserved.
- Lost gateway reply: look up the same business ID and attempt key. If not visible, retain the identity and repeat only the identical gateway request. Do not call the provider directly.
- Lost provider job ID: recover the existing execution. The gateway performs exact read-only original-job lookup. An empty lookup keeps UNKNOWN; an ambiguous or mismatched result freezes release.
- Authoritative final cost: settle once and release only the unused portion of the reserved maximum.
- Held successor: explicitly resume it. Current approval and available capacity must pass again.
In the synthetic example, $20 is approved and an unknown $12 job leaves $8 available. A second $12 job is held. A verified final $4 cost makes $16 available. The second job stays held until explicit resume.
A separate approved job capped at $8 could fit while the original $12 exposure remains unknown. This is a budget rule, not the one-full-principal payment rule.
A timeout, restart, cancellation request, completed job or absent lookup is not final billing evidence. Recovery never sends a held successor automatically.
Transport success is not execution permission.
A business HOLD can be a successful HTTP response. Inspect the execution state rather than treating HTTP 200 as permission to dispatch elsewhere.
For a schema or key error, fix the contract or access scope. For timeout, connection failure or an unavailable dispatch response, preserve business and attempt identity and look up the original. Never switch providers as an automatic HTTP retry.
The SDKs use finite timeouts and do not automatically retry provider execution. Review exact response schemas and status codes in the OpenAPI contract.
Local preview. Provider qualification next.
The implemented cost, recovery and finality contract is a separate-process loopback fixture. The current preview supplies free client SDKs and a local evaluator by request. It supplies no native AI execution endpoint, paid hosted service or measured availability SLA.
Managed use requires a binding native-provider ceiling, original-job lookup, final billing evidence, qualified hosted operations, customer onboarding and agreed service terms. The exact provider contract determines which workflows can be supported. This is single-host local evaluation. Backup restoration, joint-history rollback, host migration and automatic history migration are not qualified. Preserve historical consumption and unresolved work through a separately reviewed cutover.