@dexcost/sdk 0.2.0

package/dist/core/gpu-runtime.js

@@ -0,0 +1,131 @@
+/**
+ * Active GPU runtime resolver — Phase 2 Task 3.
+ *
+ * Sibling of `compute-runtime.ts`. Coexists without modification —
+ * compute-runtime answers "which compute billing model" and gpu-runtime
+ * answers "which GPU billing model (if any)".
+ *
+ * Cascade priority (capture spec §5.5):
+ *
+ * 1. Serverless GPU env vars (MODAL_TASK_ID / RUNPOD_POD_ID /
+ *    REPLICATE_MODEL) — win immediately when NVML is available.
+ * 2. IaaS GPU via cloud_detect — provider AWS/GCP/Azure AND instanceType
+ *    matches a GPU-family regex AND NVML reports ≥1 device. Classifies as
+ *    AWS_EC2_GPU / GCP_GCE_BUNDLED / GCP_GCE_N1_ATTACHED (Decision #9) /
+ *    AZURE_VM_GPU / AZURE_VM_VGPU (Decision #10).
+ * 3. Reserved-GPU providers — Lambda Labs / CoreWeave from cloud_detect
+ *    AND NVML reports ≥1 device.
+ * 4. NONE when NVML unavailable, 0 devices, or unmatched runtime.
+ *
+ * **String values match Python EXACTLY** — cross-SDK event portability.
+ *
+ * **TS deviation**: takes an `Options` object with hook functions. This
+ * lets tests inject deterministic stubs without monkeypatching module-
+ * level imports (ESM bindings are immutable). The default options use the
+ * production nvml-reader + cloud-detect modules.
+ *
+ * Mirrors python/src/dexcost/gpu_runtime.py.
+ */
+import { getCloudEnv as defaultGetCloudEnv } from "../cloud-detect.js";
+import { getDeviceCount as defaultGetDeviceCount, nvmlAvailable as defaultNvmlAvailable, } from "./nvml-reader.js";
+/** GPU runtime kind discriminator. String values pinned to Python. */
+export const GpuRuntimeKind = {
+    Modal: "modal",
+    RunPod: "runpod",
+    Replicate: "replicate",
+    LambdaLabs: "lambda_labs",
+    CoreWeave: "coreweave",
+    AwsEc2Gpu: "aws_ec2_gpu",
+    GcpGceBundled: "gcp_gce_bundled",
+    GcpGceN1Attached: "gcp_gce_n1_attached",
+    AzureVmGpu: "azure_vm_gpu",
+    AzureVmVgpu: "azure_vm_vgpu",
+    None: "none",
+};
+// ─── GPU instance-family matchers ───────────────────────────────────────────
+// AWS GPU EC2 families: g4/g4dn/g5/g5g/g6/g6e/p3/p4d/p4de/p5/p5e/p5en
+const AWS_GPU_FAMILY_RE = /^(g4|g4dn|g5|g5g|g6|g6e|p3|p4d|p4de|p5|p5e|p5en)\./i;
+// GCP A2/A3/A4 (bundled GPU) + G2 (L4-bundled)
+const GCP_BUNDLED_GPU_FAMILY_RE = /^(a2|a3|a4|g2)-/i;
+// GCP N1 — attached-accelerator path (Decision #9 — accelerator type not
+// exposed by metadata; rely on NVML fallback).
+const GCP_N1_FAMILY_RE = /^n1-/i;
+// Azure ND/NC series — bundled GPU instances.
+const AZURE_GPU_FAMILY_RE = /^Standard_(ND|NC)/i;
+// Azure NVadsA10 v5 — fractional vGPU (Decision #10). More specific; matched first.
+const AZURE_VGPU_FAMILY_RE = /^Standard_NV\d+ads_A10_v5/i;
+function isAwsGpuInstance(it) {
+    return !!it && AWS_GPU_FAMILY_RE.test(it);
+}
+function isGcpBundledGpuInstance(it) {
+    return !!it && GCP_BUNDLED_GPU_FAMILY_RE.test(it);
+}
+function isGcpN1Instance(it) {
+    return !!it && GCP_N1_FAMILY_RE.test(it);
+}
+function isAzureVgpuInstance(it) {
+    return !!it && AZURE_VGPU_FAMILY_RE.test(it);
+}
+function isAzureGpuInstance(it) {
+    return !!it && AZURE_GPU_FAMILY_RE.test(it);
+}
+// ─── Resolver ───────────────────────────────────────────────────────────────
+function _isNode() {
+    return typeof process !== "undefined" && !!process.versions?.node;
+}
+/**
+ * Return the active GPU runtime, or NONE when there's no GPU.
+ *
+ * The cascade short-circuits on the FIRST positive match. If NVML can't
+ * initialize or reports 0 devices, returns NONE regardless of env-var
+ * signals — a Modal task on a CPU-only Modal function emits no GPU events.
+ */
+export function resolveGpuRuntime(options) {
+    const nvmlAvailable = options?.nvmlAvailable ?? defaultNvmlAvailable;
+    const getDeviceCount = options?.getDeviceCount ?? defaultGetDeviceCount;
+    const getCloudEnv = options?.getCloudEnv ?? defaultGetCloudEnv;
+    // Browser → no GPU.
+    if (!_isNode())
+        return GpuRuntimeKind.None;
+    // NVML must be available AND see ≥1 device for any GPU event emission.
+    if (!nvmlAvailable())
+        return GpuRuntimeKind.None;
+    const count = getDeviceCount() ?? 0;
+    if (count <= 0)
+        return GpuRuntimeKind.None;
+    // 1. Serverless GPU env vars — fastest path, decisive when set.
+    const env = process.env;
+    if (env.MODAL_TASK_ID || env.MODAL_IMAGE_ID)
+        return GpuRuntimeKind.Modal;
+    if (env.RUNPOD_POD_ID || env.RUNPOD_POD_HOSTNAME)
+        return GpuRuntimeKind.RunPod;
+    if (env.REPLICATE_MODEL || env.REPLICATE_PREDICTION_ID) {
+        return GpuRuntimeKind.Replicate;
+    }
+    // 2/3. Cloud-detect IaaS / reserved-GPU.
+    const cloud = getCloudEnv();
+    const provider = cloud.provider;
+    const it = cloud.instanceType ?? null;
+    if (provider === "lambda_labs")
+        return GpuRuntimeKind.LambdaLabs;
+    if (provider === "coreweave")
+        return GpuRuntimeKind.CoreWeave;
+    if (provider === "aws") {
+        if (isAwsGpuInstance(it))
+            return GpuRuntimeKind.AwsEc2Gpu;
+    }
+    if (provider === "gcp") {
+        if (isGcpBundledGpuInstance(it))
+            return GpuRuntimeKind.GcpGceBundled;
+        if (isGcpN1Instance(it))
+            return GpuRuntimeKind.GcpGceN1Attached;
+    }
+    if (provider === "azure") {
+        if (isAzureVgpuInstance(it))
+            return GpuRuntimeKind.AzureVmVgpu;
+        if (isAzureGpuInstance(it))
+            return GpuRuntimeKind.AzureVmGpu;
+    }
+    return GpuRuntimeKind.None;
+}
+//# sourceMappingURL=gpu-runtime.js.map

package/dist/core/gpu-runtime.js.map

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

package/dist/core/heuristics.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Retry Heuristic Engine for the dexcost TypeScript SDK.
+ *
+ * Analyses a sliding window of recent events per task and auto-detects
+ * probable retries by identifying LLM calls that follow a failed call
+ * (transient error) to the same model within the configured time window.
+ */
+import type { CostEvent } from "./models.js";
+/** Error types that indicate a transient failure likely to be retried. */
+export declare const TRANSIENT_ERRORS: Set<string>;
+/**
+ * Base likelihood (0–1) that each transient error type leads to a retry.
+ * Used as the starting multiplier before time-decay is applied.
+ */
+export declare const ERROR_LIKELIHOODS: Record<string, number>;
+/** Result returned by `RetryHeuristicEngine.check()`. */
+export interface HeuristicMatch {
+    /** Whether the event is likely a retry. */
+    isRetry: boolean;
+    /** Confidence score from 0.0 to 1.0. */
+    confidence: number;
+    /** Event ID of the failed predecessor, if matched. */
+    matchedEventId: string | undefined;
+    /** "heuristic" when a match is found, "" otherwise. */
+    reason: string;
+}
+/**
+ * Sliding-window heuristic engine that detects probable retry events.
+ *
+ * Call `record(event)` for every event you process.
+ * Call `check(event)` *before* recording to determine whether the
+ * incoming event looks like a retry of a recently failed call.
+ */
+export declare class RetryHeuristicEngine {
+    private readonly _windowSeconds;
+    private readonly _threshold;
+    /** Map from taskId → ordered list of recorded events. */
+    private readonly _windows;
+    /**
+     * @param windowSeconds - How far back (in seconds) to look for a matching
+     *   failed predecessor. Defaults to 30.
+     * @param threshold - Minimum confidence score required to flag an event as
+     *   a retry. Defaults to 0.8.
+     */
+    constructor(windowSeconds?: number, threshold?: number);
+    /** The configured sliding-window size in seconds. */
+    get windowSeconds(): number;
+    /** The minimum confidence threshold for flagging a retry. */
+    get threshold(): number;
+    /**
+     * Record an event into the sliding window for its task.
+     *
+     * Events older than `windowSeconds` relative to the new event are pruned
+     * before appending.
+     */
+    record(event: CostEvent): void;
+    /**
+     * Check whether an incoming event looks like a retry.
+     *
+     * Walks the recorded events for the same task backwards (most-recent
+     * first) looking for an `llm_call` event with the same model that ended
+     * with a transient error within the time window.
+     *
+     * Does NOT modify the window — call `record()` separately.
+     */
+    check(event: CostEvent): HeuristicMatch;
+    private _getOrCreate;
+    /**
+     * Remove events from the front of the list that are older than
+     * `windowSeconds` relative to `referenceTime`.
+     */
+    private _prune;
+}
+//# sourceMappingURL=heuristics.d.ts.map

package/dist/core/heuristics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../src/core/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,aAM3B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMpD,CAAC;AAMF,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAcD;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE;;;;;OAKG;gBACS,aAAa,GAAE,MAAW,EAAE,SAAS,GAAE,MAAY;IAW/D,qDAAqD;IACrD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,6DAA6D;IAC7D,IAAI,SAAS,IAAI,MAAM,CAEtB;IAMD;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAa9B;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc;IAoEvC,OAAO,CAAC,YAAY;IASpB;;;OAGG;IACH,OAAO,CAAC,MAAM;CAWf"}

package/dist/core/heuristics.js

@@ -0,0 +1,182 @@
+/**
+ * Retry Heuristic Engine for the dexcost TypeScript SDK.
+ *
+ * Analyses a sliding window of recent events per task and auto-detects
+ * probable retries by identifying LLM calls that follow a failed call
+ * (transient error) to the same model within the configured time window.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Error types that indicate a transient failure likely to be retried. */
+export const TRANSIENT_ERRORS = new Set([
+    "rate_limit",
+    "timeout",
+    "5xx",
+    "server_error",
+    "connection_error",
+]);
+/**
+ * Base likelihood (0–1) that each transient error type leads to a retry.
+ * Used as the starting multiplier before time-decay is applied.
+ */
+export const ERROR_LIKELIHOODS = {
+    rate_limit: 1.0,
+    timeout: 0.9,
+    "5xx": 0.85,
+    server_error: 0.85,
+    connection_error: 0.8,
+};
+// ---------------------------------------------------------------------------
+// Engine
+// ---------------------------------------------------------------------------
+/** Canonical no-match result. */
+const NO_MATCH = {
+    isRetry: false,
+    confidence: 0,
+    matchedEventId: undefined,
+    reason: "",
+};
+/**
+ * Sliding-window heuristic engine that detects probable retry events.
+ *
+ * Call `record(event)` for every event you process.
+ * Call `check(event)` *before* recording to determine whether the
+ * incoming event looks like a retry of a recently failed call.
+ */
+export class RetryHeuristicEngine {
+    _windowSeconds;
+    _threshold;
+    /** Map from taskId → ordered list of recorded events. */
+    _windows = new Map();
+    /**
+     * @param windowSeconds - How far back (in seconds) to look for a matching
+     *   failed predecessor. Defaults to 30.
+     * @param threshold - Minimum confidence score required to flag an event as
+     *   a retry. Defaults to 0.8.
+     */
+    constructor(windowSeconds = 30, threshold = 0.8) {
+        if (windowSeconds <= 0) {
+            throw new Error(`windowSeconds must be positive, got ${windowSeconds}`);
+        }
+        if (threshold <= 0 || threshold > 1) {
+            throw new Error(`threshold must be in (0, 1], got ${threshold}`);
+        }
+        this._windowSeconds = windowSeconds;
+        this._threshold = threshold;
+    }
+    /** The configured sliding-window size in seconds. */
+    get windowSeconds() {
+        return this._windowSeconds;
+    }
+    /** The minimum confidence threshold for flagging a retry. */
+    get threshold() {
+        return this._threshold;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Record an event into the sliding window for its task.
+     *
+     * Events older than `windowSeconds` relative to the new event are pruned
+     * before appending.
+     */
+    record(event) {
+        const list = this._getOrCreate(event.taskId);
+        this._prune(list, event.occurredAt);
+        if (list.length === 0) {
+            this._windows.delete(event.taskId);
+            // Re-create the entry for the incoming event
+            const fresh = [event];
+            this._windows.set(event.taskId, fresh);
+        }
+        else {
+            list.push(event);
+        }
+    }
+    /**
+     * Check whether an incoming event looks like a retry.
+     *
+     * Walks the recorded events for the same task backwards (most-recent
+     * first) looking for an `llm_call` event with the same model that ended
+     * with a transient error within the time window.
+     *
+     * Does NOT modify the window — call `record()` separately.
+     */
+    check(event) {
+        const list = this._windows.get(event.taskId);
+        if (!list || list.length === 0) {
+            return NO_MATCH;
+        }
+        const eventMs = event.occurredAt.getTime();
+        // Walk backwards through the window list (most-recent first)
+        for (let i = list.length - 1; i >= 0; i--) {
+            const candidate = list[i];
+            // Skip self (same eventId)
+            if (candidate.eventId === event.eventId) {
+                continue;
+            }
+            // Only consider llm_call events
+            if (candidate.eventType !== "llm_call") {
+                continue;
+            }
+            // Only consider the same model
+            if (candidate.model !== event.model) {
+                continue;
+            }
+            // We found an llm_call for the same model — inspect its outcome
+            const errorType = candidate.details["error_type"];
+            if (typeof errorType !== "string" || !TRANSIENT_ERRORS.has(errorType)) {
+                // Same model succeeded (or had a non-transient error) — not a retry chain
+                return NO_MATCH;
+            }
+            // Transient error found — compute time gap
+            const candidateMs = candidate.occurredAt.getTime();
+            const gapSeconds = (eventMs - candidateMs) / 1000;
+            if (gapSeconds < 0 || gapSeconds > this._windowSeconds) {
+                return NO_MATCH;
+            }
+            const baseLikelihood = ERROR_LIKELIHOODS[errorType] ?? 0.8;
+            const confidence = baseLikelihood * Math.max(0, 1 - gapSeconds / this._windowSeconds);
+            if (confidence >= this._threshold) {
+                return {
+                    isRetry: true,
+                    confidence,
+                    matchedEventId: candidate.eventId,
+                    reason: "heuristic",
+                };
+            }
+            // Confidence too low — still not a confirmed retry
+            return NO_MATCH;
+        }
+        // No matching candidate found
+        return NO_MATCH;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    _getOrCreate(taskId) {
+        let list = this._windows.get(taskId);
+        if (!list) {
+            list = [];
+            this._windows.set(taskId, list);
+        }
+        return list;
+    }
+    /**
+     * Remove events from the front of the list that are older than
+     * `windowSeconds` relative to `referenceTime`.
+     */
+    _prune(list, referenceTime) {
+        const cutoffMs = referenceTime.getTime() - this._windowSeconds * 1000;
+        let i = 0;
+        while (i < list.length && list[i].occurredAt.getTime() < cutoffMs) {
+            i++;
+        }
+        if (i > 0) {
+            list.splice(0, i);
+        }
+    }
+}
+//# sourceMappingURL=heuristics.js.map

package/dist/core/heuristics.js.map

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

package/dist/core/models.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Core data models for dexcost TypeScript SDK.
+ *
+ * These interfaces match the Dexcost Standard Event Schema v1
+ * and mirror the Python SDK's Task and Event dataclasses.
+ */
+/** Lifecycle status of a tracked task. */
+export type TaskStatus = "pending" | "success" | "failed";
+/** Discriminator for cost-generating events. */
+export type EventType = "llm_call" | "external_cost" | "compute_cost" | "retry_marker" | "network" | "gpu_cost" | "gpu_utilization_signal";
+/** How trustworthy the reported costUsd value is. */
+export type CostConfidence = "exact" | "computed" | "estimated" | "unknown";
+/** Where the costUsd figure was derived from. */
+/**
+ * Sprint 3 Theme F / §4.1.3 (P3): canonical 8-value set aligned
+ * across all 4 SDKs. Adding new values requires a coordinated wire-
+ * contract change — bump schema_version.
+ */
+export type PricingSource = "litellm" | "tokencost" | "provider_response" | "manual" | "custom" | "rate_registry" | "service_catalog" | "unknown";
+/**
+ * A tracked business task (e.g., "resolve support ticket").
+ *
+ * All downstream events roll up into the aggregated cost and token fields.
+ * `metadata` is an open record for caller-defined context.
+ */
+export interface Task {
+    taskId: string;
+    taskType: string;
+    status: TaskStatus;
+    startedAt: Date;
+    endedAt?: Date;
+    metadata: Record<string, unknown>;
+    customerId?: string;
+    projectId?: string;
+    parentTaskId?: string;
+    experimentId?: string;
+    variant?: string;
+    llmCostUsd: number;
+    externalCostUsd: number;
+    computeCostUsd: number;
+    /**
+     * v2 cloud-egress cost in USD, computed at task finalize from the
+     * accountant's canonical external_bytes_out scalar. Distinct from
+     * externalCostUsd (vendor API charges) — see Decision #7.
+     */
+    networkCostUsd: number;
+    /**
+     * v2 GPU cost in USD, computed at task finalize from the GpuAccountant's
+     * NVML diff (per-PID SM-time) + cgroup-walk PID filter. Distinct from
+     * computeCostUsd (CPU/memory rollup) — GPU billing is a separate dimension.
+     * Mirrors the Python SDK's Task.gpu_cost_usd field.
+     */
+    gpuCostUsd: number;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCachedTokens: number;
+    retryCount: number;
+    retryCostUsd: number;
+    failureCount: number;
+    networkBytesIn: number;
+    networkBytesOut: number;
+    networkCallCount: number;
+    /**
+     * Per-host network breakdown, shape `{ hosts: Array<...> }`. Capped at 20
+     * entries plus an `_other` overflow bucket during finalize.
+     */
+    networkByHost: Record<string, unknown>;
+    schemaVersion: string;
+    /**
+     * In-memory only. The per-task ComputeAccountant (cgroup start/end
+     * snapshots + runtime context). Never serialized — the buffer's
+     * upsertTask() writes named columns only, so this field cannot leak to
+     * SQLite or the wire payload. Compatible with the Python SDK's
+     * Task._compute pattern.
+     *
+     * Typed as unknown to avoid a circular import from core/compute-
+     * accountant.ts (which imports from cgroup-reader / compute-runtime).
+     */
+    _compute?: unknown;
+    /**
+     * In-memory only. The per-task GpuAccountant (NVML start snapshot +
+     * cgroup PID scope + per-device handles). Never serialized — same
+     * contract as _compute. Mirrors Python's Task._gpu.
+     */
+    _gpu?: unknown;
+}
+/**
+ * A single cost event (LLM call, external API, compute, retry).
+ *
+ * Matches the Dexcost Standard Event Schema v1.  LLM-specific fields are
+ * undefined for non-LLM event types.
+ */
+export interface CostEvent {
+    eventId: string;
+    taskId: string;
+    eventType: EventType;
+    occurredAt: Date;
+    costUsd: number;
+    costConfidence: CostConfidence;
+    pricingSource?: PricingSource;
+    pricingVersion?: string;
+    provider?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedTokens?: number;
+    latencyMs?: number;
+    serviceName?: string;
+    isRetry: boolean;
+    retryReason?: string;
+    retryOf?: string;
+    details: Record<string, unknown>;
+    schemaVersion: string;
+}
+/** Create a default Task with required fields. */
+export declare function createTask(overrides: Partial<Task> & {
+    taskId: string;
+}): Task;
+/** Create a default CostEvent with required fields. */
+export declare function createCostEvent(overrides: Partial<CostEvent> & {
+    eventId: string;
+    taskId: string;
+}): CostEvent;
+/**
+ * Serialise a Task to a JSON-safe dictionary matching the Standard Event Schema v1.
+ * Costs are serialised as strings to preserve precision.
+ */
+export declare function taskToDict(task: Task): Record<string, unknown>;
+/**
+ * Serialise a CostEvent to a JSON-safe dictionary matching the Standard Event Schema v1.
+ * Costs are serialised as strings to preserve precision.
+ */
+export declare function eventToDict(event: CostEvent): Record<string, unknown>;
+/**
+ * Deserialise a Task from a JSON-safe dictionary (inverse of `taskToDict`).
+ *
+ * Mirrors the Python SDK's `Task.from_dict`. Throws an Error when required
+ * fields are missing or malformed.
+ */
+export declare function taskFromDict(data: Record<string, unknown>): Task;
+/**
+ * Deserialise a CostEvent from a JSON-safe dictionary (inverse of `eventToDict`).
+ *
+ * Mirrors the Python SDK's `Event.from_dict`. Throws an Error when required
+ * fields are missing or malformed.
+ */
+export declare function eventFromDict(data: Record<string, unknown>): CostEvent;
+//# sourceMappingURL=models.d.ts.map

package/dist/core/models.d.ts.map

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