@aumos/agent-sim-bridge 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,118 @@
+/**
+ * HTTP client for the agent-sim-bridge sim-to-real transfer API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSimBridgeClient } from "@aumos/agent-sim-bridge";
+ *
+ * const client = createAgentSimBridgeClient({ baseUrl: "http://localhost:8094" });
+ *
+ * const sim = await client.createSimulation({
+ *   backend: "pybullet",
+ *   name: "manipulation-v1",
+ *   max_episode_steps: 500,
+ * });
+ *
+ * if (sim.ok) {
+ *   console.log("Simulation created:", sim.data.environment_id);
+ * }
+ * ```
+ */
+import type { ApiResult, DomainRandomization, GapEstimationRequest, GapEstimationResult, RandomizationRequest, RandomizationResult, SimResult, SimulationConfig, SimulationEnvironment, TransferConfig, TransferResult } from "./types.js";
+/** Configuration options for the AgentSimBridgeClient. */
+export interface AgentSimBridgeClientConfig {
+    /** Base URL of the agent-sim-bridge server (e.g. "http://localhost:8094"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-sim-bridge server. */
+export interface AgentSimBridgeClient {
+    /**
+     * Create and register a new simulation environment.
+     *
+     * @param config - Simulation configuration including backend and episode settings.
+     * @returns The created SimulationEnvironment descriptor.
+     */
+    createSimulation(config: SimulationConfig): Promise<ApiResult<SimulationEnvironment>>;
+    /**
+     * Transfer simulation values to real-world units using a calibration profile.
+     *
+     * @param options - Transfer configuration and simulation values to transform.
+     * @returns A TransferResult with transformed real-world values.
+     */
+    transferToReality(options: {
+        config: TransferConfig;
+        sim_values: readonly number[];
+    }): Promise<ApiResult<TransferResult>>;
+    /**
+     * Estimate the sim-to-real distribution gap across multiple dimensions.
+     *
+     * @param request - Gap estimation request with dimensions and metric selection.
+     * @returns A GapEstimationResult with per-dimension gaps and overall score.
+     */
+    estimateGap(request: GapEstimationRequest): Promise<ApiResult<GapEstimationResult>>;
+    /**
+     * Get the results for a completed simulation episode.
+     *
+     * @param options - Environment ID and optional run ID filter.
+     * @returns Array of SimResult records ordered by completion time descending.
+     */
+    getSimResults(options: {
+        environment_id: string;
+        run_id?: string;
+        limit?: number;
+    }): Promise<ApiResult<readonly SimResult[]>>;
+    /**
+     * Configure and apply domain randomization to a simulation environment.
+     *
+     * @param request - Randomization request with environment ID and parameter specs.
+     * @returns A RandomizationResult with the sampled parameter values.
+     */
+    configureRandomization(request: RandomizationRequest): Promise<ApiResult<RandomizationResult>>;
+    /**
+     * List all registered simulation environments.
+     *
+     * @param options - Optional filter parameters.
+     * @returns Array of SimulationEnvironment descriptors.
+     */
+    listSimulations(options?: {
+        backend?: string;
+        limit?: number;
+    }): Promise<ApiResult<readonly SimulationEnvironment[]>>;
+    /**
+     * Get the transfer configuration (calibration profile) for an environment.
+     *
+     * @param environmentId - The simulation environment identifier.
+     * @returns The TransferConfig describing the linear sim-to-real transform.
+     */
+    getTransferConfig(environmentId: string): Promise<ApiResult<TransferConfig>>;
+    /**
+     * Update the transfer configuration for a simulation environment.
+     *
+     * @param environmentId - The simulation environment identifier.
+     * @param config - The new TransferConfig to apply.
+     * @returns The updated TransferConfig.
+     */
+    updateTransferConfig(environmentId: string, config: TransferConfig): Promise<ApiResult<TransferConfig>>;
+    /**
+     * List the randomization configurations for a simulation environment.
+     *
+     * @param environmentId - The simulation environment identifier.
+     * @returns Array of DomainRandomization specifications.
+     */
+    listRandomizations(environmentId: string): Promise<ApiResult<readonly DomainRandomization[]>>;
+}
+/**
+ * Create a typed HTTP client for the agent-sim-bridge server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSimBridgeClient instance.
+ */
+export declare function createAgentSimBridgeClient(config: AgentSimBridgeClientConfig): AgentSimBridgeClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AAMpB,0DAA0D;AAC1D,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CACd,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,MAAM,EAAE,cAAc,CAAC;QACvB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;KAC/B,GAAG,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,WAAW,CACT,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,sBAAsB,CACpB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,qBAAqB,EAAE,CAAC,CAAC,CAAC;IAEzD;;;;;OAKG;IACH,iBAAiB,CACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAEtC;;;;;;OAMG;IACH,oBAAoB,CAClB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,kBAAkB,CAChB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC,CAAC;CACvD;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CAwItB"}

package/dist/client.js

@@ -0,0 +1,142 @@
+/**
+ * HTTP client for the agent-sim-bridge sim-to-real transfer API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSimBridgeClient } from "@aumos/agent-sim-bridge";
+ *
+ * const client = createAgentSimBridgeClient({ baseUrl: "http://localhost:8094" });
+ *
+ * const sim = await client.createSimulation({
+ *   backend: "pybullet",
+ *   name: "manipulation-v1",
+ *   max_episode_steps: 500,
+ * });
+ *
+ * if (sim.ok) {
+ *   console.log("Simulation created:", sim.data.environment_id);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-sim-bridge server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSimBridgeClient instance.
+ */
+export function createAgentSimBridgeClient(config) {
+    const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async createSimulation(simConfig) {
+            return fetchJson(`${baseUrl}/sim-bridge/simulations`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(simConfig),
+            }, timeoutMs);
+        },
+        async transferToReality(options) {
+            return fetchJson(`${baseUrl}/sim-bridge/transfer/sim-to-real`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(options),
+            }, timeoutMs);
+        },
+        async estimateGap(request) {
+            return fetchJson(`${baseUrl}/sim-bridge/gap/estimate`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getSimResults(options) {
+            const params = new URLSearchParams();
+            params.set("environment_id", options.environment_id);
+            if (options.run_id !== undefined) {
+                params.set("run_id", options.run_id);
+            }
+            if (options.limit !== undefined) {
+                params.set("limit", String(options.limit));
+            }
+            return fetchJson(`${baseUrl}/sim-bridge/simulations/results?${params.toString()}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async configureRandomization(request) {
+            return fetchJson(`${baseUrl}/sim-bridge/randomization/apply`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async listSimulations(options) {
+            const params = new URLSearchParams();
+            if (options?.backend !== undefined) {
+                params.set("backend", options.backend);
+            }
+            if (options?.limit !== undefined) {
+                params.set("limit", String(options.limit));
+            }
+            const query = params.toString();
+            return fetchJson(`${baseUrl}/sim-bridge/simulations${query ? `?${query}` : ""}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getTransferConfig(environmentId) {
+            return fetchJson(`${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/transfer-config`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async updateTransferConfig(environmentId, transferConfig) {
+            return fetchJson(`${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/transfer-config`, {
+                method: "PUT",
+                headers: baseHeaders,
+                body: JSON.stringify(transferConfig),
+            }, timeoutMs);
+        },
+        async listRandomizations(environmentId) {
+            return fetchJson(`${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/randomizations`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-sim-bridge
+ *
+ * TypeScript client for the AumOS agent-sim-bridge sim-to-real transfer layer.
+ * Provides HTTP client, simulation environment management, domain randomization,
+ * gap estimation, and reality adapter type definitions.
+ */
+export type { AgentSimBridgeClient, AgentSimBridgeClientConfig } from "./client.js";
+export { createAgentSimBridgeClient } from "./client.js";
+export type { ApiError, ApiResult, DistributionType, DomainRandomization, EnvironmentInfo, GapDimension, GapEstimation, GapEstimationRequest, GapEstimationResult, GapMetric, RandomizationRequest, RandomizationResult, SimResult, SimulationConfig, SimulationEnvironment, SpaceSpec, TransferConfig, TransferResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGzD,YAAY,EACV,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACT,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-sim-bridge
+ *
+ * TypeScript client for the AumOS agent-sim-bridge sim-to-real transfer layer.
+ * Provides HTTP client, simulation environment management, domain randomization,
+ * gap estimation, and reality adapter type definitions.
+ */
+export { createAgentSimBridgeClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * TypeScript interfaces for the agent-sim-bridge sim-to-real transfer layer.
+ *
+ * Mirrors the Python dataclasses and Pydantic models defined in:
+ *   agent_sim_bridge.environment.base          (SpaceSpec, EnvironmentInfo)
+ *   agent_sim_bridge.environment.sim_env       (SimulationEnvironment)
+ *   agent_sim_bridge.transfer.bridge           (CalibrationProfile)
+ *   agent_sim_bridge.transfer.domain_randomization (DistributionType, RandomizationConfig)
+ *   agent_sim_bridge.gap.estimator             (GapMetric, GapDimension, DimensionGap)
+ *   agent_sim_bridge.staging.results           (SimResult)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+/**
+ * Describes a continuous box space (observation or action).
+ * Maps to SpaceSpec Pydantic model in Python.
+ */
+export interface SpaceSpec {
+    /**
+     * Dimensionality tuple (e.g. [3] for a 3-vector, [84, 84, 3] for an image).
+     * Represented as an array in TypeScript.
+     */
+    readonly shape: readonly number[];
+    /** Per-dimension lower bounds. null means negative infinity. */
+    readonly low: readonly number[] | null;
+    /** Per-dimension upper bounds. null means positive infinity. */
+    readonly high: readonly number[] | null;
+    /** Numpy dtype string, e.g. "float32". */
+    readonly dtype: string;
+}
+/** Metadata describing an environment instance. */
+export interface EnvironmentInfo {
+    /** Human-readable identifier. */
+    readonly name: string;
+    /** Semantic version string. */
+    readonly version: string;
+    /** True for simulation environments, false for real-world. */
+    readonly is_simulation: boolean;
+    /** Maximum allowed steps per episode before truncation. */
+    readonly max_episode_steps: number;
+    /** Arbitrary key/value metadata. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/**
+ * Describes a simulation environment configuration.
+ * Corresponds to the SimulationEnvironment class in Python.
+ */
+export interface SimulationEnvironment {
+    /** Unique identifier for this simulation environment. */
+    readonly environment_id: string;
+    /** Metadata about this environment instance. */
+    readonly info: EnvironmentInfo;
+    /** Description of the observation (state) space. */
+    readonly state_space: SpaceSpec;
+    /** Description of the action space. */
+    readonly action_space: SpaceSpec;
+    /** Whether trajectory recording is enabled. */
+    readonly record_trajectories: boolean;
+    /** ISO-8601 UTC timestamp when this environment was created. */
+    readonly created_at: string;
+}
+/** Configuration for creating a simulation environment. */
+export interface SimulationConfig {
+    /** The backend to use (e.g. "pybullet", "gazebo", "generic"). */
+    readonly backend: string;
+    /** Human-readable name for this environment instance. */
+    readonly name?: string;
+    /** Episode truncation limit. */
+    readonly max_episode_steps?: number;
+    /** Whether to enable trajectory recording. */
+    readonly record_trajectories?: boolean;
+    /** Backend-specific configuration parameters. */
+    readonly backend_config?: Readonly<Record<string, unknown>>;
+}
+/** The result of a simulation episode or step. */
+export interface SimResult {
+    /** Unique identifier for this simulation run. */
+    readonly run_id: string;
+    /** The environment that produced this result. */
+    readonly environment_id: string;
+    /** Total number of steps completed in this episode. */
+    readonly total_steps: number;
+    /** Cumulative reward over the episode. */
+    readonly total_reward: number;
+    /** Whether the episode ended due to a terminal state. */
+    readonly terminated: boolean;
+    /** Whether the episode ended due to truncation. */
+    readonly truncated: boolean;
+    /** ISO-8601 UTC timestamp when the episode ended. */
+    readonly completed_at: string;
+    /** Arbitrary diagnostic information. */
+    readonly info: Readonly<Record<string, unknown>>;
+}
+/**
+ * Encodes a linear sim-to-real calibration transform.
+ * Maps to CalibrationProfile dataclass in Python.
+ *
+ * Each dimension i transforms as: real[i] = sim[i] * scale_factors[i] + offsets[i]
+ */
+export interface TransferConfig {
+    /** Per-dimension multiplicative scale factors. */
+    readonly scale_factors: readonly number[];
+    /** Per-dimension additive offsets (applied after scaling). */
+    readonly offsets: readonly number[];
+    /** Optional name of the noise model to apply after transformation. */
+    readonly noise_model: string | null;
+    /** Optional human-readable labels for each dimension. */
+    readonly dimension_names: readonly string[];
+    /** Arbitrary annotations (e.g. calibration date, sensor serial numbers). */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Result of a sim-to-real transfer operation. */
+export interface TransferResult {
+    /** The configuration used for the transfer. */
+    readonly config: TransferConfig;
+    /** Input values (simulation units). */
+    readonly sim_values: readonly number[];
+    /** Output values (real-world units). */
+    readonly real_values: readonly number[];
+    /** ISO-8601 UTC timestamp of the transfer. */
+    readonly transferred_at: string;
+}
+/**
+ * Supported sampling distributions for domain randomization.
+ * Maps to DistributionType enum in Python.
+ */
+export type DistributionType = "uniform" | "gaussian" | "log_uniform" | "constant";
+/**
+ * Specification for randomizing one environment parameter.
+ * Maps to RandomizationConfig dataclass in Python.
+ */
+export interface DomainRandomization {
+    /**
+     * Dot-path name of the parameter to randomize.
+     * e.g. "physics.gravity" or "sensor.noise_std".
+     */
+    readonly parameter_name: string;
+    /** Sampling distribution to use. */
+    readonly distribution: DistributionType;
+    /** Lower bound (or mean for GAUSSIAN, or constant value for CONSTANT). */
+    readonly low: number;
+    /** Upper bound (or std dev for GAUSSIAN). */
+    readonly high: number;
+    /** Optional hard minimum applied after sampling. */
+    readonly clip_low: number | null;
+    /** Optional hard maximum applied after sampling. */
+    readonly clip_high: number | null;
+    /** Arbitrary annotations. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/** Configuration for applying a set of domain randomizations. */
+export interface RandomizationRequest {
+    /** The environment identifier to apply randomizations to. */
+    readonly environment_id: string;
+    /** The randomization specifications to apply. */
+    readonly randomizations: readonly DomainRandomization[];
+    /** Optional RNG seed for reproducibility. */
+    readonly seed?: number;
+}
+/** Result of applying domain randomizations to an environment. */
+export interface RandomizationResult {
+    /** The environment that was randomized. */
+    readonly environment_id: string;
+    /** The sampled parameter values (parameter_name -> sampled_value). */
+    readonly sampled_parameters: Readonly<Record<string, number>>;
+    /** ISO-8601 UTC timestamp of when randomization was applied. */
+    readonly applied_at: string;
+}
+/**
+ * Statistical distance metric for comparing distributions.
+ * Maps to GapMetric enum in Python.
+ */
+export type GapMetric = "KL_DIVERGENCE" | "WASSERSTEIN" | "MMD" | "JENSEN_SHANNON";
+/**
+ * A named pair of sim and real distributions for one observable dimension.
+ * Maps to GapDimension frozen dataclass in Python.
+ */
+export interface GapDimension {
+    /** Human-readable label (e.g. "joint_velocity_0"). */
+    readonly name: string;
+    /** Empirical distribution collected in simulation. */
+    readonly sim_distribution: readonly number[];
+    /** Empirical distribution collected on the real system. */
+    readonly real_distribution: readonly number[];
+}
+/**
+ * The gap value for one metric applied to one dimension.
+ * Maps to DimensionGap frozen dataclass in Python.
+ */
+export interface GapEstimation {
+    /** The name of the GapDimension this result belongs to. */
+    readonly dimension_name: string;
+    /** The GapMetric used to compute the value. */
+    readonly metric: GapMetric;
+    /** The computed distance value. */
+    readonly value: number;
+    /** Qualitative severity: "low", "medium", or "high". */
+    readonly interpretation: string;
+}
+/** Request for estimating the sim-to-real gap across dimensions. */
+export interface GapEstimationRequest {
+    /** Dimensions to analyse. */
+    readonly dimensions: readonly GapDimension[];
+    /** Metrics to compute (defaults to all four if omitted). */
+    readonly metrics?: readonly GapMetric[];
+}
+/** Full result of a sim-to-real gap estimation run. */
+export interface GapEstimationResult {
+    /** Per-dimension gap results, indexed by dimension name. */
+    readonly dimension_gaps: Readonly<Record<string, readonly GapEstimation[]>>;
+    /** Weighted average gap score in [0, 1]. */
+    readonly overall_gap_score: number;
+    /** ISO-8601 UTC timestamp when the estimation was computed. */
+    readonly estimated_at: string;
+}
+/** Standard error payload returned by the agent-sim-bridge API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * TypeScript interfaces for the agent-sim-bridge sim-to-real transfer layer.
+ *
+ * Mirrors the Python dataclasses and Pydantic models defined in:
+ *   agent_sim_bridge.environment.base          (SpaceSpec, EnvironmentInfo)
+ *   agent_sim_bridge.environment.sim_env       (SimulationEnvironment)
+ *   agent_sim_bridge.transfer.bridge           (CalibrationProfile)
+ *   agent_sim_bridge.transfer.domain_randomization (DistributionType, RandomizationConfig)
+ *   agent_sim_bridge.gap.estimator             (GapMetric, GapDimension, DimensionGap)
+ *   agent_sim_bridge.staging.results           (SimResult)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aumos/agent-sim-bridge",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-sim-bridge sim-to-real transfer layer — simulation environments, domain randomization, gap estimation, and reality adapters",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-sim-bridge",
+    "simulation",
+    "sim-to-real",
+    "domain-randomization",
+    "gap-estimation",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-sim-bridge"
+  }
+}

package/src/client.ts

@@ -0,0 +1,358 @@
+/**
+ * HTTP client for the agent-sim-bridge sim-to-real transfer API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSimBridgeClient } from "@aumos/agent-sim-bridge";
+ *
+ * const client = createAgentSimBridgeClient({ baseUrl: "http://localhost:8094" });
+ *
+ * const sim = await client.createSimulation({
+ *   backend: "pybullet",
+ *   name: "manipulation-v1",
+ *   max_episode_steps: 500,
+ * });
+ *
+ * if (sim.ok) {
+ *   console.log("Simulation created:", sim.data.environment_id);
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  DomainRandomization,
+  GapEstimationRequest,
+  GapEstimationResult,
+  RandomizationRequest,
+  RandomizationResult,
+  SimResult,
+  SimulationConfig,
+  SimulationEnvironment,
+  TransferConfig,
+  TransferResult,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentSimBridgeClient. */
+export interface AgentSimBridgeClientConfig {
+  /** Base URL of the agent-sim-bridge server (e.g. "http://localhost:8094"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-sim-bridge server. */
+export interface AgentSimBridgeClient {
+  /**
+   * Create and register a new simulation environment.
+   *
+   * @param config - Simulation configuration including backend and episode settings.
+   * @returns The created SimulationEnvironment descriptor.
+   */
+  createSimulation(
+    config: SimulationConfig,
+  ): Promise<ApiResult<SimulationEnvironment>>;
+
+  /**
+   * Transfer simulation values to real-world units using a calibration profile.
+   *
+   * @param options - Transfer configuration and simulation values to transform.
+   * @returns A TransferResult with transformed real-world values.
+   */
+  transferToReality(options: {
+    config: TransferConfig;
+    sim_values: readonly number[];
+  }): Promise<ApiResult<TransferResult>>;
+
+  /**
+   * Estimate the sim-to-real distribution gap across multiple dimensions.
+   *
+   * @param request - Gap estimation request with dimensions and metric selection.
+   * @returns A GapEstimationResult with per-dimension gaps and overall score.
+   */
+  estimateGap(
+    request: GapEstimationRequest,
+  ): Promise<ApiResult<GapEstimationResult>>;
+
+  /**
+   * Get the results for a completed simulation episode.
+   *
+   * @param options - Environment ID and optional run ID filter.
+   * @returns Array of SimResult records ordered by completion time descending.
+   */
+  getSimResults(options: {
+    environment_id: string;
+    run_id?: string;
+    limit?: number;
+  }): Promise<ApiResult<readonly SimResult[]>>;
+
+  /**
+   * Configure and apply domain randomization to a simulation environment.
+   *
+   * @param request - Randomization request with environment ID and parameter specs.
+   * @returns A RandomizationResult with the sampled parameter values.
+   */
+  configureRandomization(
+    request: RandomizationRequest,
+  ): Promise<ApiResult<RandomizationResult>>;
+
+  /**
+   * List all registered simulation environments.
+   *
+   * @param options - Optional filter parameters.
+   * @returns Array of SimulationEnvironment descriptors.
+   */
+  listSimulations(options?: {
+    backend?: string;
+    limit?: number;
+  }): Promise<ApiResult<readonly SimulationEnvironment[]>>;
+
+  /**
+   * Get the transfer configuration (calibration profile) for an environment.
+   *
+   * @param environmentId - The simulation environment identifier.
+   * @returns The TransferConfig describing the linear sim-to-real transform.
+   */
+  getTransferConfig(
+    environmentId: string,
+  ): Promise<ApiResult<TransferConfig>>;
+
+  /**
+   * Update the transfer configuration for a simulation environment.
+   *
+   * @param environmentId - The simulation environment identifier.
+   * @param config - The new TransferConfig to apply.
+   * @returns The updated TransferConfig.
+   */
+  updateTransferConfig(
+    environmentId: string,
+    config: TransferConfig,
+  ): Promise<ApiResult<TransferConfig>>;
+
+  /**
+   * List the randomization configurations for a simulation environment.
+   *
+   * @param environmentId - The simulation environment identifier.
+   * @returns Array of DomainRandomization specifications.
+   */
+  listRandomizations(
+    environmentId: string,
+  ): Promise<ApiResult<readonly DomainRandomization[]>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-sim-bridge server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSimBridgeClient instance.
+ */
+export function createAgentSimBridgeClient(
+  config: AgentSimBridgeClientConfig,
+): AgentSimBridgeClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async createSimulation(
+      simConfig: SimulationConfig,
+    ): Promise<ApiResult<SimulationEnvironment>> {
+      return fetchJson<SimulationEnvironment>(
+        `${baseUrl}/sim-bridge/simulations`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(simConfig),
+        },
+        timeoutMs,
+      );
+    },
+
+    async transferToReality(options: {
+      config: TransferConfig;
+      sim_values: readonly number[];
+    }): Promise<ApiResult<TransferResult>> {
+      return fetchJson<TransferResult>(
+        `${baseUrl}/sim-bridge/transfer/sim-to-real`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(options),
+        },
+        timeoutMs,
+      );
+    },
+
+    async estimateGap(
+      request: GapEstimationRequest,
+    ): Promise<ApiResult<GapEstimationResult>> {
+      return fetchJson<GapEstimationResult>(
+        `${baseUrl}/sim-bridge/gap/estimate`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getSimResults(options: {
+      environment_id: string;
+      run_id?: string;
+      limit?: number;
+    }): Promise<ApiResult<readonly SimResult[]>> {
+      const params = new URLSearchParams();
+      params.set("environment_id", options.environment_id);
+      if (options.run_id !== undefined) {
+        params.set("run_id", options.run_id);
+      }
+      if (options.limit !== undefined) {
+        params.set("limit", String(options.limit));
+      }
+      return fetchJson<readonly SimResult[]>(
+        `${baseUrl}/sim-bridge/simulations/results?${params.toString()}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async configureRandomization(
+      request: RandomizationRequest,
+    ): Promise<ApiResult<RandomizationResult>> {
+      return fetchJson<RandomizationResult>(
+        `${baseUrl}/sim-bridge/randomization/apply`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async listSimulations(options?: {
+      backend?: string;
+      limit?: number;
+    }): Promise<ApiResult<readonly SimulationEnvironment[]>> {
+      const params = new URLSearchParams();
+      if (options?.backend !== undefined) {
+        params.set("backend", options.backend);
+      }
+      if (options?.limit !== undefined) {
+        params.set("limit", String(options.limit));
+      }
+      const query = params.toString();
+      return fetchJson<readonly SimulationEnvironment[]>(
+        `${baseUrl}/sim-bridge/simulations${query ? `?${query}` : ""}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getTransferConfig(
+      environmentId: string,
+    ): Promise<ApiResult<TransferConfig>> {
+      return fetchJson<TransferConfig>(
+        `${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/transfer-config`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async updateTransferConfig(
+      environmentId: string,
+      transferConfig: TransferConfig,
+    ): Promise<ApiResult<TransferConfig>> {
+      return fetchJson<TransferConfig>(
+        `${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/transfer-config`,
+        {
+          method: "PUT",
+          headers: baseHeaders,
+          body: JSON.stringify(transferConfig),
+        },
+        timeoutMs,
+      );
+    },
+
+    async listRandomizations(
+      environmentId: string,
+    ): Promise<ApiResult<readonly DomainRandomization[]>> {
+      return fetchJson<readonly DomainRandomization[]>(
+        `${baseUrl}/sim-bridge/simulations/${encodeURIComponent(environmentId)}/randomizations`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @aumos/agent-sim-bridge
+ *
+ * TypeScript client for the AumOS agent-sim-bridge sim-to-real transfer layer.
+ * Provides HTTP client, simulation environment management, domain randomization,
+ * gap estimation, and reality adapter type definitions.
+ */
+
+// Client and configuration
+export type { AgentSimBridgeClient, AgentSimBridgeClientConfig } from "./client.js";
+export { createAgentSimBridgeClient } from "./client.js";
+
+// Core types
+export type {
+  ApiError,
+  ApiResult,
+  DistributionType,
+  DomainRandomization,
+  EnvironmentInfo,
+  GapDimension,
+  GapEstimation,
+  GapEstimationRequest,
+  GapEstimationResult,
+  GapMetric,
+  RandomizationRequest,
+  RandomizationResult,
+  SimResult,
+  SimulationConfig,
+  SimulationEnvironment,
+  SpaceSpec,
+  TransferConfig,
+  TransferResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,274 @@
+/**
+ * TypeScript interfaces for the agent-sim-bridge sim-to-real transfer layer.
+ *
+ * Mirrors the Python dataclasses and Pydantic models defined in:
+ *   agent_sim_bridge.environment.base          (SpaceSpec, EnvironmentInfo)
+ *   agent_sim_bridge.environment.sim_env       (SimulationEnvironment)
+ *   agent_sim_bridge.transfer.bridge           (CalibrationProfile)
+ *   agent_sim_bridge.transfer.domain_randomization (DistributionType, RandomizationConfig)
+ *   agent_sim_bridge.gap.estimator             (GapMetric, GapDimension, DimensionGap)
+ *   agent_sim_bridge.staging.results           (SimResult)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+
+// ---------------------------------------------------------------------------
+// Space and environment types
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a continuous box space (observation or action).
+ * Maps to SpaceSpec Pydantic model in Python.
+ */
+export interface SpaceSpec {
+  /**
+   * Dimensionality tuple (e.g. [3] for a 3-vector, [84, 84, 3] for an image).
+   * Represented as an array in TypeScript.
+   */
+  readonly shape: readonly number[];
+  /** Per-dimension lower bounds. null means negative infinity. */
+  readonly low: readonly number[] | null;
+  /** Per-dimension upper bounds. null means positive infinity. */
+  readonly high: readonly number[] | null;
+  /** Numpy dtype string, e.g. "float32". */
+  readonly dtype: string;
+}
+
+/** Metadata describing an environment instance. */
+export interface EnvironmentInfo {
+  /** Human-readable identifier. */
+  readonly name: string;
+  /** Semantic version string. */
+  readonly version: string;
+  /** True for simulation environments, false for real-world. */
+  readonly is_simulation: boolean;
+  /** Maximum allowed steps per episode before truncation. */
+  readonly max_episode_steps: number;
+  /** Arbitrary key/value metadata. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Simulation environment
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a simulation environment configuration.
+ * Corresponds to the SimulationEnvironment class in Python.
+ */
+export interface SimulationEnvironment {
+  /** Unique identifier for this simulation environment. */
+  readonly environment_id: string;
+  /** Metadata about this environment instance. */
+  readonly info: EnvironmentInfo;
+  /** Description of the observation (state) space. */
+  readonly state_space: SpaceSpec;
+  /** Description of the action space. */
+  readonly action_space: SpaceSpec;
+  /** Whether trajectory recording is enabled. */
+  readonly record_trajectories: boolean;
+  /** ISO-8601 UTC timestamp when this environment was created. */
+  readonly created_at: string;
+}
+
+/** Configuration for creating a simulation environment. */
+export interface SimulationConfig {
+  /** The backend to use (e.g. "pybullet", "gazebo", "generic"). */
+  readonly backend: string;
+  /** Human-readable name for this environment instance. */
+  readonly name?: string;
+  /** Episode truncation limit. */
+  readonly max_episode_steps?: number;
+  /** Whether to enable trajectory recording. */
+  readonly record_trajectories?: boolean;
+  /** Backend-specific configuration parameters. */
+  readonly backend_config?: Readonly<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Sim result
+// ---------------------------------------------------------------------------
+
+/** The result of a simulation episode or step. */
+export interface SimResult {
+  /** Unique identifier for this simulation run. */
+  readonly run_id: string;
+  /** The environment that produced this result. */
+  readonly environment_id: string;
+  /** Total number of steps completed in this episode. */
+  readonly total_steps: number;
+  /** Cumulative reward over the episode. */
+  readonly total_reward: number;
+  /** Whether the episode ended due to a terminal state. */
+  readonly terminated: boolean;
+  /** Whether the episode ended due to truncation. */
+  readonly truncated: boolean;
+  /** ISO-8601 UTC timestamp when the episode ended. */
+  readonly completed_at: string;
+  /** Arbitrary diagnostic information. */
+  readonly info: Readonly<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Transfer / calibration types
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes a linear sim-to-real calibration transform.
+ * Maps to CalibrationProfile dataclass in Python.
+ *
+ * Each dimension i transforms as: real[i] = sim[i] * scale_factors[i] + offsets[i]
+ */
+export interface TransferConfig {
+  /** Per-dimension multiplicative scale factors. */
+  readonly scale_factors: readonly number[];
+  /** Per-dimension additive offsets (applied after scaling). */
+  readonly offsets: readonly number[];
+  /** Optional name of the noise model to apply after transformation. */
+  readonly noise_model: string | null;
+  /** Optional human-readable labels for each dimension. */
+  readonly dimension_names: readonly string[];
+  /** Arbitrary annotations (e.g. calibration date, sensor serial numbers). */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+/** Result of a sim-to-real transfer operation. */
+export interface TransferResult {
+  /** The configuration used for the transfer. */
+  readonly config: TransferConfig;
+  /** Input values (simulation units). */
+  readonly sim_values: readonly number[];
+  /** Output values (real-world units). */
+  readonly real_values: readonly number[];
+  /** ISO-8601 UTC timestamp of the transfer. */
+  readonly transferred_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Domain randomization types
+// ---------------------------------------------------------------------------
+
+/**
+ * Supported sampling distributions for domain randomization.
+ * Maps to DistributionType enum in Python.
+ */
+export type DistributionType = "uniform" | "gaussian" | "log_uniform" | "constant";
+
+/**
+ * Specification for randomizing one environment parameter.
+ * Maps to RandomizationConfig dataclass in Python.
+ */
+export interface DomainRandomization {
+  /**
+   * Dot-path name of the parameter to randomize.
+   * e.g. "physics.gravity" or "sensor.noise_std".
+   */
+  readonly parameter_name: string;
+  /** Sampling distribution to use. */
+  readonly distribution: DistributionType;
+  /** Lower bound (or mean for GAUSSIAN, or constant value for CONSTANT). */
+  readonly low: number;
+  /** Upper bound (or std dev for GAUSSIAN). */
+  readonly high: number;
+  /** Optional hard minimum applied after sampling. */
+  readonly clip_low: number | null;
+  /** Optional hard maximum applied after sampling. */
+  readonly clip_high: number | null;
+  /** Arbitrary annotations. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+/** Configuration for applying a set of domain randomizations. */
+export interface RandomizationRequest {
+  /** The environment identifier to apply randomizations to. */
+  readonly environment_id: string;
+  /** The randomization specifications to apply. */
+  readonly randomizations: readonly DomainRandomization[];
+  /** Optional RNG seed for reproducibility. */
+  readonly seed?: number;
+}
+
+/** Result of applying domain randomizations to an environment. */
+export interface RandomizationResult {
+  /** The environment that was randomized. */
+  readonly environment_id: string;
+  /** The sampled parameter values (parameter_name -> sampled_value). */
+  readonly sampled_parameters: Readonly<Record<string, number>>;
+  /** ISO-8601 UTC timestamp of when randomization was applied. */
+  readonly applied_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Gap estimation types
+// ---------------------------------------------------------------------------
+
+/**
+ * Statistical distance metric for comparing distributions.
+ * Maps to GapMetric enum in Python.
+ */
+export type GapMetric =
+  | "KL_DIVERGENCE"
+  | "WASSERSTEIN"
+  | "MMD"
+  | "JENSEN_SHANNON";
+
+/**
+ * A named pair of sim and real distributions for one observable dimension.
+ * Maps to GapDimension frozen dataclass in Python.
+ */
+export interface GapDimension {
+  /** Human-readable label (e.g. "joint_velocity_0"). */
+  readonly name: string;
+  /** Empirical distribution collected in simulation. */
+  readonly sim_distribution: readonly number[];
+  /** Empirical distribution collected on the real system. */
+  readonly real_distribution: readonly number[];
+}
+
+/**
+ * The gap value for one metric applied to one dimension.
+ * Maps to DimensionGap frozen dataclass in Python.
+ */
+export interface GapEstimation {
+  /** The name of the GapDimension this result belongs to. */
+  readonly dimension_name: string;
+  /** The GapMetric used to compute the value. */
+  readonly metric: GapMetric;
+  /** The computed distance value. */
+  readonly value: number;
+  /** Qualitative severity: "low", "medium", or "high". */
+  readonly interpretation: string;
+}
+
+/** Request for estimating the sim-to-real gap across dimensions. */
+export interface GapEstimationRequest {
+  /** Dimensions to analyse. */
+  readonly dimensions: readonly GapDimension[];
+  /** Metrics to compute (defaults to all four if omitted). */
+  readonly metrics?: readonly GapMetric[];
+}
+
+/** Full result of a sim-to-real gap estimation run. */
+export interface GapEstimationResult {
+  /** Per-dimension gap results, indexed by dimension name. */
+  readonly dimension_gaps: Readonly<Record<string, readonly GapEstimation[]>>;
+  /** Weighted average gap score in [0, 1]. */
+  readonly overall_gap_score: number;
+  /** ISO-8601 UTC timestamp when the estimation was computed. */
+  readonly estimated_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-sim-bridge API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}