@aithos/sdk 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/src/compute.d.ts

@@ -1,16 +1,31 @@
-import { type BrowserIdentity } from "@aithos/protocol-client";
+import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
 export interface ComputeMessage {
     readonly role: "user" | "assistant";
     readonly content: string;
 }
 export interface InvokeBedrockArgs {
-    /** Mandate ID granting this app the right to spend the user's wallet. */
-    readonly mandateId: string;
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The SDK uses the owner's own DID
+     *   as a sentinel "self" mandate id — the proxy skips all
+     *   mandate-related checks (scope, allowed_models, caps) when the
+     *   envelope is owner-signed, so the value is informational only.
+     * - **Delegate sessions**: required. Must reference the imported
+     *   mandate bundle the SDK signs with (the proxy enforces
+     *   `compute.invoke` scope and any `allowed_models` filter).
+     */
+    readonly mandateId?: string;
     /**
      * Model id. Today the proxy accepts the canonical Aithos identifiers:
-     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`.
+     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6`.
      * The proxy maps these to Bedrock cross-region inference profiles.
+     *
+     * NOTE: `claude-opus-4-7` is also provisioned on the Bedrock account
+     * but commercial access is gated behind an AWS Sales unlock (as of
+     * May 2026) — InvokeModel returns AccessDeniedException pointing to
+     * AWS Sales. Stick with `claude-opus-4-6` until the unlock lands.
      */
     readonly model: string;
     /** Conversation messages (user / assistant turns). */
@@ -44,16 +59,263 @@ export interface InvokeBedrockResult {
     /** Audit log id for traceability. */
     readonly auditId: string;
 }
+/**
+ * Stable cross-provider image model ids supported by the Aithos compute
+ * proxy. New models can be added on the server side without an SDK
+ * release — but tagging the namespaced literal here gives consumers
+ * autocomplete + type-checking.
+ *
+ * The `image:` prefix is part of the wire contract: the server uses it
+ * to disambiguate text and image dispatch when a mandate's
+ * `allowed_models` mixes both.
+ */
+export type ImageModelId = "image:flux-schnell" | "image:flux-dev" | "image:flux-pro-1.1" | "image:flux-pro-1.1-ultra" | "image:imagen-3" | "image:imagen-4" | "image:nano-banana";
+/** Aspect ratios accepted by `invokeImage`. */
+export type ImageAspectRatio = "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "21:9";
+export interface InvokeImageArgs {
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The SDK uses the owner's own DID
+     *   as a sentinel "self" mandate id — the proxy skips all
+     *   mandate-related checks when the envelope is owner-signed.
+     * - **Delegate sessions**: required. Must reference the imported
+     *   mandate bundle the SDK signs with.
+     */
+    readonly mandateId?: string;
+    /**
+     * Image model id. Defaults to `"image:flux-pro-1.1"` on the SDK side
+     * if omitted — the server allowlist is the source of truth for which
+     * ones actually work.
+     */
+    readonly model?: ImageModelId;
+    /** What to draw. */
+    readonly prompt: string;
+    /** Optional comma-separated list of things to avoid (e.g. "blurry, watermark"). */
+    readonly negativePrompt?: string;
+    /** Default 1:1. */
+    readonly aspectRatio?: ImageAspectRatio;
+    /** Deterministic seed (re-rolls). Omit for random. */
+    readonly seed?: number;
+    /** Number of images to generate. Default 1, max 4. */
+    readonly numberOfImages?: number;
+    /** Idempotency key for retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Abort signal to cancel the request (network + provider call). */
+    readonly signal?: AbortSignal;
+}
+export interface InvokeImageImage {
+    /** Base64-encoded image bytes (raw, no data: URI prefix). */
+    readonly base64: string;
+    /** "image/png" | "image/jpeg". */
+    readonly contentType: string;
+    readonly width: number;
+    readonly height: number;
+}
+export interface InvokeImageResult {
+    readonly images: readonly InvokeImageImage[];
+    /** Seed actually used by the provider (echoed back even when caller didn't set one). */
+    readonly seed: number;
+    /** Microcredits debited from the wallet (exact — no reconcile path for images). */
+    readonly creditsCharged: number;
+    /** Wallet balance after debit. */
+    readonly walletBalance: number;
+    /** Audit log id for traceability. */
+    readonly auditId: string;
+}
+export interface InvokeBedrockVisionArgs {
+    readonly mandateId?: string;
+    /**
+     * Model id. Sonnet 4.6 is the default — it's vision-capable and
+     * returns reliable structured JSON when prompted.
+     */
+    readonly model?: string;
+    /** Source image — Blob (recommended) or raw base64. */
+    readonly image: Blob | {
+        readonly base64: string;
+        readonly contentType: string;
+    };
+    /** Text prompt accompanying the image. */
+    readonly prompt: string;
+    /** Optional system prompt. */
+    readonly system?: string;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface InvokeBedrockVisionResult {
+    readonly content: string;
+    readonly stopReason: StopReason;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+}
+export interface InvokeSegmentationArgs {
+    /** Mandate id (optional for owner sessions — see InvokeImageArgs). */
+    readonly mandateId?: string;
+    /** Source image. Blob (recommended) or raw base64. */
+    readonly image: Blob | {
+        readonly base64: string;
+        readonly contentType: string;
+    };
+    /**
+     * Text phrase describing what to segment. Florence-2 is robust with
+     * natural-language descriptions: "the torso of the robot", "the
+     * dog's head", "the chest of the character".
+     */
+    readonly textInput: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface SegmentPolygon {
+    readonly points: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+    }>;
+}
+export interface InvokeSegmentationResult {
+    /** All polygons Florence-2 returned (typically 1, sometimes a few when the prompt matches multiple regions). */
+    readonly polygons: readonly SegmentPolygon[];
+    /** Bbox of the first polygon for callers that only need a coarse target. */
+    readonly bbox: {
+        readonly left: number;
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+    } | null;
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+}
+/**
+ * Models accepted by `invokeUrlFetch`. These are the Anthropic-API-direct
+ * model aliases — the proxy resolves them to the canonical API model id
+ * (`claude-haiku-4-5-20251001`, etc.) at dispatch time.
+ *
+ * Bedrock's compute_invoke supports the same names but routes through
+ * Bedrock; url_fetch routes through `api.anthropic.com` directly because
+ * the `web_fetch` server-side tool isn't exposed via Bedrock.
+ */
+export type UrlFetchModelId = "claude-haiku-4-5" | "claude-sonnet-4-6" | "claude-opus-4-6";
+export interface InvokeUrlFetchArgs {
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The owner's own DID is used as a
+     *   sentinel "self" mandate id; the proxy skips all mandate checks
+     *   for owner-signed envelopes.
+     * - **Delegate sessions**: required. Must reference an imported
+     *   mandate bundle that carries the `compute.url_fetch` scope (NOT
+     *   the same scope as `compute.invoke` — see the protocol spec).
+     */
+    readonly mandateId?: string;
+    /**
+     * Anthropic model alias. Default `"claude-haiku-4-5"` — fastest and
+     * cheapest model that supports `web_fetch`. Bump to Sonnet 4.6 for
+     * deeper reasoning over the fetched content; Opus 4.6 for the
+     * heaviest analyses (priced accordingly via reconcile). Opus 4.7 is
+     * provisioned but commercially gated — see the docstring on
+     * InvokeBedrockArgs.model for the unlock path.
+     */
+    readonly model?: UrlFetchModelId;
+    /**
+     * User prompt — should normally contain the URL(s) the caller wants
+     * the model to fetch and analyze. Example:
+     *   "Voici l'URL https://tata.com — résume le service, identifie
+     *    le style du site et la couleur primaire. Renvoie en JSON."
+     */
+    readonly prompt: string;
+    /** Optional system prompt (Anthropic-style separate field). */
+    readonly system?: string;
+    /** Cap on output tokens. Default 2048. */
+    readonly maxTokens?: number;
+    /** Sampling temperature. Default model-dependent. */
+    readonly temperature?: number;
+    /**
+     * Maximum number of `web_fetch` invocations the model is allowed to
+     * make in this call. Default 5; range [1, 10].
+     */
+    readonly maxFetches?: number;
+    /**
+     * Maximum tokens of fetched content Anthropic will inject per fetch.
+     * Default 100_000; range [1000, 200_000]. Pages larger than this
+     * are truncated server-side.
+     */
+    readonly maxContentTokens?: number;
+    /**
+     * When `true` (default), the response carries citation spans tying
+     * generated text back to fetched documents — useful for displaying
+     * "selon X, …" footnotes in the UI without post-processing.
+     */
+    readonly citations?: boolean;
+    /**
+     * Optional domain allowlist — if set, the model can only fetch from
+     * these domains. Mutually exclusive with `blockedDomains`.
+     */
+    readonly allowedDomains?: readonly string[];
+    /**
+     * Optional domain blocklist. Mutually exclusive with `allowedDomains`.
+     */
+    readonly blockedDomains?: readonly string[];
+    /** Idempotency key for retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Single citation projection — flattened from Anthropic's wire shape so
+ * consumers can render `{cited_text}` next to `{url}` without parsing
+ * vendor-specific block types.
+ */
+export interface UrlFetchCitation {
+    readonly url: string;
+    readonly citedText: string;
+    readonly documentTitle?: string;
+    readonly startCharIndex?: number;
+    readonly endCharIndex?: number;
+}
+/** Per-fetch metadata in the order the model performed the fetches. */
+export interface UrlFetchMetadata {
+    readonly url: string;
+    readonly retrievedAt?: string;
+    readonly title?: string;
+}
+export interface InvokeUrlFetchResult {
+    /** Final assistant text — typically a JSON string when the prompt asked for structure. */
+    readonly content: string;
+    /** Citation spans (empty when `citations: false` or no fetches succeeded). */
+    readonly citations: readonly UrlFetchCitation[];
+    /** Per-URL fetch metadata. */
+    readonly urlsFetched: readonly UrlFetchMetadata[];
+    readonly stopReason: "end_turn" | "max_tokens" | "tool_use" | "stop_sequence" | "pause_turn" | "refusal";
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly webFetchInvocations: number;
+    };
+    /** Microcredits charged after reconcile (already net of any refund). */
+    readonly creditsCharged: number;
+    /** Wallet balance after the debit + reconcile. */
+    readonly walletBalance: number;
+    /** Audit log id for traceability. */
+    readonly auditId: string;
+}
 export interface ComputeNamespaceDeps {
-    readonly identity: BrowserIdentity;
+    readonly auth: AithosAuth;
     readonly appDid: string;
     readonly endpoints: AithosSdkEndpoints;
     readonly fetch: typeof fetch;
 }
 /**
  * `sdk.compute` namespace. Constructed once by the {@link AithosSDK}
- * constructor; all calls share the SDK's identity, app DID, and endpoint
- * configuration.
+ * constructor; reads the active owner from the supplied
+ * {@link AithosAuth} on every call so signing material follows the
+ * latest sign-in/sign-out state.
  */
 export declare class ComputeNamespace {
     #private;
@@ -62,10 +324,109 @@ export declare class ComputeNamespace {
      * Invoke a Bedrock model through the compute proxy. See
      * {@link InvokeBedrockArgs} and {@link InvokeBedrockResult}.
      *
+     * Two signer paths are supported:
+     *
+     *   - **Owner**: when the caller is signed in as an owner, the
+     *     envelope is signed with the owner's `#public` sphere key and
+     *     no mandate is attached (the proxy resolves the mandate
+     *     server-side from `params.mandate_id`).
+     *   - **Delegate**: when the caller is delegate-only (mandate
+     *     imported via `auth.importMandate`), the envelope is signed
+     *     with the delegate's bound keypair and the full SignedMandate
+     *     is attached so the proxy can verify both signature and
+     *     authorisation in one pass. The mandate must carry the
+     *     `compute.invoke` scope and the proxy enforces its constraints
+     *     (caps, allowed models, …) at server-side.
+     *
+     * Owner takes precedence: if a session has BOTH an owner and a
+     * matching delegate session, we use the owner key (more flexible —
+     * the mandate is dereferenced via `mandate_id` and there's no
+     * lifetime cliff if the delegate seed has been wiped).
+     *
      * @throws {AithosSDKError} on protocol errors. The `code` field is one of
-     *   `network`, `http`, `empty`, or any code returned by the proxy
-     *   (`quota_exceeded`, `mandate_revoked`, `insufficient_credits`, …).
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`, `http`,
+     *   `empty`, or any code returned by the proxy (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
+    /**
+     * Multimodal Bedrock invoke — image + text → text response.
+     * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).
+     *
+     * Use when you need a VLM to reason about an image: locating
+     * features, structured extraction, semantic Q&A. Prompt the model
+     * to return JSON if you need structured output (the API itself is
+     * unstructured).
+     */
+    invokeBedrockVision(args: InvokeBedrockVisionArgs): Promise<InvokeBedrockVisionResult>;
+    /**
+     * Generate one or more images through the Aithos compute proxy
+     * (currently powered by fal.ai FLUX models). Spec mirror of
+     * {@link invokeBedrock}: same envelope, same wallet path, same
+     * mandate-scope gate (`compute.invoke` + `allowed_models`). The
+     * separation at the JSON-RPC method level (`aithos.compute_invoke_image`
+     * vs `aithos.compute_invoke`) commits each envelope to a specific
+     * modality so a stolen text-invoke envelope cannot be replayed
+     * against the image endpoint.
+     *
+     * Default model: `"image:flux-pro-1.1"`. Default aspect ratio: 1:1.
+     * Default count: 1 image.
+     *
+     * Pricing is per image and deterministic (no token-based reconcile):
+     *   - flux-schnell:        3 000 mc + fee per image
+     *   - flux-dev:           25 000 mc + fee per image
+     *   - flux-pro-1.1:       40 000 mc + fee per image
+     *   - flux-pro-1.1-ultra: 60 000 mc + fee per image
+     */
+    invokeImage(args: InvokeImageArgs): Promise<InvokeImageResult>;
+    /**
+     * Run text-prompted segmentation (Florence-2 referring-expression)
+     * on a source image. Returns one or more polygons hugging the
+     * region matching the text prompt.
+     *
+     * Use cases: locate the chest/torso area of a generated mascot
+     * for logo compositing, find the face zone for a thumbnail crop,
+     * extract a product from a marketing shot — anything that needs
+     * a precise mask + bbox from natural-language description.
+     *
+     * Pricing: flat 5 000 mc per call (~$0.005 — Florence-2 is cheap).
+     */
+    invokeSegmentation(args: InvokeSegmentationArgs): Promise<InvokeSegmentationResult>;
+    /**
+     * Fetch one or more URLs and have Claude analyze the content. Routes
+     * through `api.anthropic.com` with the `web_fetch` server-side tool —
+     * NOT through Bedrock — because Bedrock does not expose Anthropic's
+     * server-side tools (web_fetch, web_search, etc.). The proxy hides
+     * this multi-backend detail from the SDK consumer; the wallet,
+     * envelope, and mandate-scope contracts are unchanged.
+     *
+     * Typical use:
+     * ```ts
+     * const r = await sdk.compute.invokeUrlFetch({
+     *   prompt: "Voici l'URL https://tata.com — résume le service, " +
+     *           "identifie le style et la couleur primaire. JSON.",
+     * });
+     * console.log(r.content);
+     * for (const c of r.citations) console.log(c.url, "→", c.citedText);
+     * ```
+     *
+     * Mandate scope: requires `compute.url_fetch` (distinct from
+     * `compute.invoke` — see {@link InvokeUrlFetchArgs.mandateId}).
+     *
+     * Pricing: same Claude 4.x rates as Bedrock (Anthropic's direct API
+     * and Bedrock list prices are identical). Default Haiku 4.5 ≈
+     * $0.001/1k input + $0.005/1k output. The proxy pre-debits a
+     * conservative upper bound (`maxFetches × maxContentTokens × input
+     * rate + maxTokens × output rate`) and reconciles down to the actual
+     * usage Anthropic reports — so the wallet is always charged the
+     * exact post-call cost.
+     *
+     * @throws {AithosSDKError} on protocol errors. Notable codes:
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`,
+     *   `http`, `empty`, plus proxy codes `-32042` (mandate scope
+     *   missing), `-32070`/`-32071` (wallet), `-32074` (fetch blocked
+     *   by robots.txt / domain filter), `-32050` (rate limit).
+     */
+    invokeUrlFetch(args: InvokeUrlFetchArgs): Promise<InvokeUrlFetchResult>;
 }
 //# sourceMappingURL=compute.d.ts.map