@siduri-x/observation 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { VisionOrgan } from '@siduri-x/core';
+export interface ObservationReading {
+    entity: string;
+    value: string;
+    confidence: number;
+    sourceCrop?: string;
+    ocrText?: string;
+    competingInterpretations?: string[];
+}
+export interface Observation {
+    observationId: string;
+    evidenceId: string;
+    sourceName: string;
+    providerId: string;
+    readings: ObservationReading[];
+    confidence: number;
+    createdAt: string;
+    expiresAt: string;
+    frameDigest: string;
+}
+export interface ObservationResult {
+    observation?: Observation;
+    duplicate: boolean;
+    reason?: 'empty_frame' | 'duplicate_frame' | 'invalid_reading' | 'provider_failure';
+}
+export interface ObservationOrgan {
+    ingest(frame: Uint8Array, sourceName: string, providerId?: string): Promise<ObservationResult>;
+    current(now?: Date): Observation[];
+    clearExpired(now?: Date): number;
+}
+export declare function digestFrame(frame: Uint8Array): string;
+export declare class FixtureObservationOrgan implements ObservationOrgan {
+    private readonly vision;
+    private readonly ttlMs;
+    private readonly maxFrames;
+    private readonly maxFrameBytes;
+    private readonly observations;
+    private readonly digests;
+    constructor(vision: VisionOrgan, ttlMs?: number, maxFrames?: number, maxFrameBytes?: number);
+    ingest(frame: Uint8Array, sourceName: string, providerId?: string): Promise<ObservationResult>;
+    current(now?: Date): Observation[];
+    clearExpired(now?: Date): number;
+}

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixtureObservationOrgan = void 0;
+exports.digestFrame = digestFrame;
+const node_crypto_1 = require("node:crypto");
+function digestFrame(frame) {
+    // Cryptographically robust SHA-256 content identity digest
+    return (0, node_crypto_1.createHash)('sha256').update(frame).digest('hex');
+}
+function frameDataUrl(frame) {
+    return `data:image/png;base64,${Buffer.from(frame).toString('base64')}`;
+}
+function id(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+}
+function clampConfidence(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, Math.min(1, value))
+        : 0;
+}
+function parseReadings(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    const raw = Array.isArray(parsed) ? parsed : (parsed && typeof parsed === 'object' && Array.isArray(parsed.readings) ? parsed.readings : undefined);
+    if (!raw)
+        return undefined;
+    const readings = raw.filter((item) => item && typeof item.entity === 'string' && typeof item.value === 'string')
+        .map((item) => ({
+        entity: item.entity.slice(0, 96),
+        value: item.value.slice(0, 512),
+        confidence: clampConfidence(item.confidence),
+        sourceCrop: typeof item.source_crop === 'string' ? item.source_crop : undefined,
+        ocrText: typeof item.ocr_text === 'string' ? item.ocr_text.slice(0, 512) : undefined,
+        competingInterpretations: Array.isArray(item.competing_interpretations)
+            ? item.competing_interpretations.filter((v) => typeof v === 'string').slice(0, 4)
+            : undefined,
+    }));
+    return readings.length === raw.length ? readings : undefined;
+}
+class FixtureObservationOrgan {
+    vision;
+    ttlMs;
+    maxFrames;
+    maxFrameBytes;
+    observations = [];
+    digests = new Set();
+    constructor(vision, ttlMs = 30_000, maxFrames = 8, maxFrameBytes = 10 * 1024 * 1024) {
+        this.vision = vision;
+        this.ttlMs = ttlMs;
+        this.maxFrames = maxFrames;
+        this.maxFrameBytes = maxFrameBytes;
+        if (ttlMs <= 0 || maxFrames <= 0)
+            throw new Error('observation limits must be positive');
+    }
+    async ingest(frame, sourceName, providerId = 'vision') {
+        if (!frame.length)
+            return { duplicate: false, reason: 'empty_frame' };
+        if (frame.byteLength > this.maxFrameBytes) {
+            throw new Error(`Observation frame exceeds maximum allowed size of ${this.maxFrameBytes} bytes (received ${frame.byteLength})`);
+        }
+        this.clearExpired();
+        const frameDigest = digestFrame(frame);
+        if (this.digests.has(frameDigest))
+            return { duplicate: true, reason: 'duplicate_frame' };
+        let readings;
+        try {
+            // The frame is converted only for the provider call and is never stored.
+            const imageUrl = frameDataUrl(frame);
+            readings = parseReadings(await this.vision.analyze(imageUrl, 'Return only visible readings as JSON with entity, value, and confidence.'));
+        }
+        catch {
+            return { duplicate: false, reason: 'provider_failure' };
+        }
+        if (!readings)
+            return { duplicate: false, reason: 'invalid_reading' };
+        const now = Date.now();
+        const observation = {
+            observationId: id('obs'),
+            evidenceId: id('evidence'),
+            sourceName: sourceName.slice(0, 96),
+            providerId: providerId.slice(0, 96),
+            readings,
+            confidence: readings.length ? readings.reduce((sum, item) => sum + item.confidence, 0) / readings.length : 0,
+            createdAt: new Date(now).toISOString(),
+            expiresAt: new Date(now + this.ttlMs).toISOString(),
+            frameDigest,
+        };
+        this.observations.push(observation);
+        this.digests.add(frameDigest);
+        while (this.observations.length > this.maxFrames) {
+            const removed = this.observations.shift();
+            if (removed)
+                this.digests.delete(removed.frameDigest);
+        }
+        return { observation, duplicate: false };
+    }
+    current(now = new Date()) {
+        this.clearExpired(now);
+        return this.observations.map((item) => ({ ...item, readings: item.readings.map((reading) => ({ ...reading })) }));
+    }
+    clearExpired(now = new Date()) {
+        const before = this.observations.length;
+        const current = now.getTime();
+        const retained = this.observations.filter((item) => new Date(item.expiresAt).getTime() > current);
+        this.observations.splice(0, this.observations.length, ...retained);
+        this.digests.clear();
+        for (const item of retained)
+            this.digests.add(item.frameDigest);
+        return before - retained.length;
+    }
+}
+exports.FixtureObservationOrgan = FixtureObservationOrgan;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+describe('FixtureObservationOrgan', () => {
+    test('creates bounded evidence without retaining the raw frame', async () => {
+        const vision = { analyze: jest.fn().mockResolvedValue(JSON.stringify({ readings: [
+                    { entity: 'scene', value: 'combat', confidence: 0.9 },
+                ] })) };
+        const organ = new index_1.FixtureObservationOrgan(vision, 1000, 2);
+        const frame = new Uint8Array([1, 2, 3]);
+        const result = await organ.ingest(frame, 'fixture-genshin', 'fixture-vision');
+        expect(result.observation).toMatchObject({ sourceName: 'fixture-genshin', providerId: 'fixture-vision', confidence: 0.9 });
+        expect(result.observation?.evidenceId).toMatch(/^evidence_/);
+        expect(JSON.stringify(result.observation)).not.toContain('1,2,3');
+        expect(vision.analyze).toHaveBeenCalledWith(expect.stringContaining('data:image/png;base64'), expect.any(String));
+    });
+    test('suppresses duplicate frames and expires observations', async () => {
+        const vision = { analyze: jest.fn().mockResolvedValue('[{"entity":"scene","value":"idle","confidence":1}]') };
+        const organ = new index_1.FixtureObservationOrgan(vision, 1000, 2);
+        const frame = new Uint8Array([7, 8, 9]);
+        const first = await organ.ingest(frame, 'fixture');
+        const duplicate = await organ.ingest(frame, 'fixture');
+        expect(first.observation).toBeDefined();
+        expect(duplicate).toMatchObject({ duplicate: true, reason: 'duplicate_frame' });
+        expect(organ.clearExpired(new Date(Date.now() + 2000))).toBe(1);
+        expect(organ.current(new Date(Date.now() + 2000))).toEqual([]);
+    });
+    test('generates deterministic and distinct SHA-256 digests for distinct frames', () => {
+        const frame1 = new Uint8Array([1, 2, 3, 4]);
+        const frame2 = new Uint8Array([1, 2, 3, 5]);
+        const digest1a = (0, index_1.digestFrame)(frame1);
+        const digest1b = (0, index_1.digestFrame)(frame1);
+        const digest2 = (0, index_1.digestFrame)(frame2);
+        expect(digest1a).toBe(digest1b);
+        expect(digest1a).not.toBe(digest2);
+        expect(digest1a).toMatch(/^[a-f0-9]{64}$/);
+    });
+    test('rejects oversized observation frames exceeding configured maximum bytes', async () => {
+        const vision = { analyze: jest.fn().mockResolvedValue('[]') };
+        const organ = new index_1.FixtureObservationOrgan(vision, 1000, 2, 100); // 100 bytes max
+        const oversizedFrame = new Uint8Array(200);
+        await expect(organ.ingest(oversizedFrame, 'test')).rejects.toThrow(/exceeds maximum allowed size/);
+    });
+    test('rejects malformed provider readings', async () => {
+        const organ = new index_1.FixtureObservationOrgan({ analyze: jest.fn().mockResolvedValue('not json') });
+        await expect(organ.ingest(new Uint8Array([1]), 'fixture')).resolves.toMatchObject({ reason: 'invalid_reading' });
+    });
+});

package/organ-manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "@siduri-x/observation",
+  "organType": "observation",
+  "version": "1.0.0",
+  "displayName": "Observation (Grounded Observation Ingestion)",
+  "description": "Cryptographically hashed video/image observation ingest and duplicate detection",
+  "entrypoint": "./dist/index.js",
+  "factory": "FixtureObservationOrgan",
+  "configKey": "observation",
+  "configSchema": {
+    "type": "object",
+    "properties": {}
+  },
+  "environment": [],
+  "services": [],
+  "database": null,
+  "healthCheck": null
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@siduri-x/observation",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --config jest.config.json"
+  },
+  "dependencies": {
+    "@siduri-x/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.3.3"
+  },
+  "description": "Observation organ for evidence extraction, frame deduplication, and OCR readings",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vxnuslabs/siduri-y",
+    "directory": "packages/organs/observation"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "organ-manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./organ-manifest.json": "./organ-manifest.json"
+  }
+}