quantum-ai-sdk 0.4.0 → 0.6.0

package/dist/vision.d.ts

@@ -0,0 +1,130 @@
+import type { QuantumClient } from "./client.js";
+/** Domain context for relevance analysis. */
+export interface VisionContext {
+    /** Installation type (e.g. "solar", "heat_pump", "ev_charger"). */
+    installationType?: string;
+    /** Phase (e.g. "pre_install", "installation", "post_install"). */
+    phase?: string;
+    /** Expected items for relevance checking. */
+    expectedItems?: string[];
+}
+/** Request body for vision analysis endpoints. */
+export interface VisionRequest {
+    /** Base64-encoded image (with or without data: prefix). */
+    imageBase64?: string;
+    /** Image URL (fetched by the model provider). */
+    imageUrl?: string;
+    /** Model to use. Default: gemini-2.5-flash. */
+    model?: string;
+    /** Analysis profile: "combined" (default), "scene", "objects", "ocr", "quality". */
+    profile?: string;
+    /** Domain context for relevance checking. */
+    context?: VisionContext;
+}
+/** A detected object with bounding box. */
+export interface DetectedObject {
+    /** Object label. */
+    label: string;
+    /** Detection confidence (0.0 - 1.0). */
+    confidence: number;
+    /** Bounding box: [y_min, x_min, y_max, x_max] normalised to 0-1000. */
+    boundingBox: [number, number, number, number];
+}
+/** Image quality assessment. */
+export interface QualityAssessment {
+    /** Overall rating: "good", "acceptable", "poor". */
+    overall: string;
+    /** Quality score (0.0 - 1.0). */
+    score: number;
+    /** Blur level: "none", "slight", "significant". */
+    blur: string;
+    /** Lighting: "well_lit", "dim", "dark". */
+    darkness: string;
+    /** Resolution: "high", "adequate", "low". */
+    resolution: string;
+    /** Exposure: "correct", "over", "under". */
+    exposure: string;
+    /** Specific issues found. */
+    issues: string[];
+}
+/** Relevance check against expected content. */
+export interface RelevanceCheck {
+    /** Whether the image is relevant to the context. */
+    relevant: boolean;
+    /** Relevance score (0.0 - 1.0). */
+    score: number;
+    /** Items expected based on context. */
+    expectedItems: string[];
+    /** Items actually found in the image. */
+    foundItems: string[];
+    /** Expected but not found. */
+    missingItems: string[];
+    /** Found but not expected. */
+    unexpectedItems: string[];
+    /** Additional notes. */
+    notes?: string;
+}
+/** A detected text region in the image. */
+export interface TextOverlay {
+    /** Extracted text content. */
+    text: string;
+    /** Bounding box: [y_min, x_min, y_max, x_max] normalised to 0-1000. */
+    boundingBox?: [number, number, number, number];
+    /** Overlay type: "gps", "timestamp", "address", "label", "other". */
+    type?: string;
+}
+/** OCR / text extraction result. */
+export interface OcrResult {
+    /** All extracted text concatenated. */
+    text?: string;
+    /** Extracted metadata (GPS, timestamp, address, etc.). */
+    metadata: Record<string, string>;
+    /** Individual text overlays with positions. */
+    overlays: TextOverlay[];
+}
+/** Full vision analysis response. */
+export interface VisionResponse {
+    /** Scene description. */
+    caption?: string;
+    /** Suggested tags (lowercase_snake_case). */
+    tags: string[];
+    /** Detected objects with bounding boxes. */
+    objects: DetectedObject[];
+    /** Image quality assessment. */
+    quality?: QualityAssessment;
+    /** Relevance check against context. */
+    relevance?: RelevanceCheck;
+    /** Extracted text and overlay metadata. */
+    ocr?: OcrResult;
+    /** Model used. */
+    model: string;
+    /** Cost in ticks. */
+    costTicks: number;
+    /** Request identifier. */
+    requestId: string;
+}
+/**
+ * Full combined vision analysis (scene + objects + quality + OCR + relevance).
+ * @internal
+ */
+export declare function visionAnalyze(client: QuantumClient, req: VisionRequest): Promise<VisionResponse>;
+/**
+ * Object detection with bounding boxes.
+ * @internal
+ */
+export declare function visionDetect(client: QuantumClient, req: VisionRequest): Promise<VisionResponse>;
+/**
+ * Scene description and tags.
+ * @internal
+ */
+export declare function visionDescribe(client: QuantumClient, req: VisionRequest): Promise<VisionResponse>;
+/**
+ * Text extraction and overlay metadata (OCR).
+ * @internal
+ */
+export declare function visionOcr(client: QuantumClient, req: VisionRequest): Promise<VisionResponse>;
+/**
+ * Image quality assessment.
+ * @internal
+ */
+export declare function visionQuality(client: QuantumClient, req: VisionRequest): Promise<VisionResponse>;

package/dist/vision.js

@@ -0,0 +1,124 @@
+// ── Wire format (snake_case JSON) ────────────────────────────────
+/** @internal Convert camelCase request to snake_case wire format. */
+function toWire(req) {
+    const out = {};
+    if (req.imageBase64 !== undefined)
+        out.image_base64 = req.imageBase64;
+    if (req.imageUrl !== undefined)
+        out.image_url = req.imageUrl;
+    if (req.model !== undefined)
+        out.model = req.model;
+    if (req.profile !== undefined)
+        out.profile = req.profile;
+    if (req.context) {
+        const ctx = {};
+        if (req.context.installationType !== undefined)
+            ctx.installation_type = req.context.installationType;
+        if (req.context.phase !== undefined)
+            ctx.phase = req.context.phase;
+        if (req.context.expectedItems !== undefined)
+            ctx.expected_items = req.context.expectedItems;
+        out.context = ctx;
+    }
+    return out;
+}
+/** @internal Convert snake_case wire response to camelCase. */
+function fromWire(raw) {
+    const objects = (raw.objects ?? []).map((o) => ({
+        label: o.label ?? "",
+        confidence: o.confidence ?? 0,
+        boundingBox: o.bounding_box ?? [0, 0, 0, 0],
+    }));
+    let quality;
+    if (raw.quality) {
+        const q = raw.quality;
+        quality = {
+            overall: q.overall ?? "",
+            score: q.score ?? 0,
+            blur: q.blur ?? "",
+            darkness: q.darkness ?? "",
+            resolution: q.resolution ?? "",
+            exposure: q.exposure ?? "",
+            issues: q.issues ?? [],
+        };
+    }
+    let relevance;
+    if (raw.relevance) {
+        const r = raw.relevance;
+        relevance = {
+            relevant: r.relevant ?? false,
+            score: r.score ?? 0,
+            expectedItems: r.expected_items ?? [],
+            foundItems: r.found_items ?? [],
+            missingItems: r.missing_items ?? [],
+            unexpectedItems: r.unexpected_items ?? [],
+            notes: r.notes,
+        };
+    }
+    let ocr;
+    if (raw.ocr) {
+        const o = raw.ocr;
+        const overlays = (o.overlays ?? []).map((ov) => ({
+            text: ov.text ?? "",
+            boundingBox: ov.bounding_box,
+            type: ov.type,
+        }));
+        ocr = {
+            text: o.text,
+            metadata: o.metadata ?? {},
+            overlays,
+        };
+    }
+    return {
+        caption: raw.caption,
+        tags: raw.tags ?? [],
+        objects,
+        quality,
+        relevance,
+        ocr,
+        model: raw.model ?? "",
+        costTicks: raw.cost_ticks ?? 0,
+        requestId: raw.request_id ?? "",
+    };
+}
+// ── Client methods ───────────────────────────────────────────────
+/**
+ * Full combined vision analysis (scene + objects + quality + OCR + relevance).
+ * @internal
+ */
+export async function visionAnalyze(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/vision/analyze", toWire(req));
+    return fromWire(data);
+}
+/**
+ * Object detection with bounding boxes.
+ * @internal
+ */
+export async function visionDetect(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/vision/detect", toWire(req));
+    return fromWire(data);
+}
+/**
+ * Scene description and tags.
+ * @internal
+ */
+export async function visionDescribe(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/vision/describe", toWire(req));
+    return fromWire(data);
+}
+/**
+ * Text extraction and overlay metadata (OCR).
+ * @internal
+ */
+export async function visionOcr(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/vision/ocr", toWire(req));
+    return fromWire(data);
+}
+/**
+ * Image quality assessment.
+ * @internal
+ */
+export async function visionQuality(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/vision/quality", toWire(req));
+    return fromWire(data);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantum-ai-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Cosmic Duck SDK — 100+ AI endpoints across 10 providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",