@adaas/a-frame 0.0.23 → 0.1.2

package/tests/A-Frame.browser.test.ts

@@ -1,94 +1,204 @@
-import { A_Component, A_Concept, A_Container, A_Error } from "@adaas/a-concept";
+/**
+ * A-Frame Browser Bundle Tests
+ *
+ * Validates the pre-built bundle flow:
+ *   1. Build an in-memory A_FrameBundle with synthetic (but valid) vectors.
+ *   2. Seed A_FrameBrowserStorageBlobs from the bundle (no server needed).
+ *   3. Load the concept — definitions are hydrated from the plain record store.
+ *   4. Run a cosine-similarity search against the hydrated index.
+ *
+ * No network calls, no encryption key, no server required.
+ */
+import { A_Component, A_Concept, A_Container, A_Context, A_Error } from "@adaas/a-concept";
 import { A_Frame } from "@adaas/a-frame/core";
-import { config } from 'dotenv';
 import { A_FrameIndex } from "@adaas/a-frame/index";
-import { A_FrameBrowserChannel } from "@adaas/a-frame/channel";
 import { A_FrameVector } from "@adaas/a-frame/vector";
-
-config();
-
-describe('A-Frame Browser Tests', () => {
-    @A_Frame.Define({
-        description: 'Handles HTTP requests and response formatting for the REST API layer. Use this for routing, middleware, request validation, and sending responses.',
-    })
-    class ComponentA extends A_Component {
+import { A_FrameBrowserStorageBlobs } from '../src/lib/A-FrameStorage/browser/A-FrameBrowserStorageBlobs.context';
+import type { A_FrameBundle } from "@adaas/a-frame/bundle";
+import { A_FRAME_BUNDLE_VERSION } from "@adaas/a-frame/bundle";
+import { A_FrameTargetType } from '../src/lib/A-Frame/A-Frame.types';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Generate a normalised random unit vector of a given dimension. */
+function makeVector(dims: number, seed: number): number[] {
+    const v = Array.from({ length: dims }, (_, i) => Math.sin(seed * 13.7 + i * 0.37));
+    const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+    return v.map(x => x / norm);
+}
+
+/** Build a synthetic A_FrameBundle with the supplied definition descriptors. */
+function makeSyntheticBundle(
+    defs: Array<{ aseid: string; name: string; description: string; namespace: string; hash: string; seed: number }>,
+    dims = 64,
+): A_FrameBundle {
+    const records: A_FrameBundle['records'] = {};
+
+    for (const d of defs) {
+        const rec = {
+            aseid: d.aseid,
+            name: d.name,
+            hash: d.hash,
+            type: A_FrameTargetType.COMPONENT,
+            description: d.description,
+            namespace: d.namespace,
+            embedding: makeVector(dims, d.seed),
+            date: new Date().toISOString(),
+            model: 'adaas-antares-v1',
+            credentialId: 'test-cred',
+            aFrameVersion: '0.1.1',
+            aFrameServerVersion: '1.0.0',
+        };
+        (records[d.namespace] ??= []).push(rec);
     }
 
-    @A_Frame.Define({
-        description: 'Manages database connections and performs CRUD operations on persistent storage. Use this for querying, inserting, updating, and deleting records.',
-    })
-    class ComponentB extends A_Component {
+    return {
+        bundleVersion: A_FRAME_BUNDLE_VERSION,
+        aFrameVersion: '0.1.1',
+        serverVersion: '1.0.0',
+        builtAt: new Date().toISOString(),
+        records,
+        namespaceRecords: [],
+    };
+}
+
+// ─── Component definitions ────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'Handles HTTP requests and response formatting for the REST API layer. Use this for routing, middleware, request validation, and sending responses.',
+})
+class ComponentA extends A_Component { }
+
+@A_Frame.Define({
+    description: 'Manages database connections and performs CRUD operations on persistent storage. Use this for querying, inserting, updating, and deleting records.',
+})
+class ComponentB extends A_Component { }
+
+@A_Frame.Define({
+    description: 'Orchestrates business logic and coordinates between the HTTP layer and the database layer. Use this for processing rules, validation, and transformations.',
+})
+class ComponentC extends A_Component { }
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame Browser Bundle Tests', () => {
+
+    let bundle: A_FrameBundle;
+
+    beforeAll(() => {
+        // Definitions are registered in A_FrameIndex.instance at class-decoration
+        // time (when @A_Frame.Define runs). Use the singleton directly — no DI
+        // resolution needed; no concept.load() required.
+        const defs = A_FrameIndex.instance.listDefinitions();
+
+        // Build bundle records using the real hash so the hash-check inside
+        // loadDefinitionFromBlobs() succeeds and fromJSON() is actually called.
+        const bundleDefs = defs.map((def, i) => ({
+            aseid: def.aseid.toString(),
+            name: def.name,
+            description: def.description ?? '',
+            namespace: def.namespace.id,
+            hash: def.hash,
+            seed: i + 1,
+        }));
+
+        bundle = makeSyntheticBundle(bundleDefs);
+    });
 
-    }
+    it('Bundle is seeded correctly into BrowserStorageBlobs', () => {
+        // Seed and verify plain store is populated
+        const blobs = A_FrameBrowserStorageBlobs.fromBundle(bundle);
 
-    @A_Frame.Define({
-        description: 'Orchestrates business logic and coordinates between the HTTP layer and the database layer. Use this for processing rules, validation, and transformations.',
-    })
-    class ComponentC extends A_Component {
+        expect(blobs.hasBundleData).toBe(true);
 
-    }
+        const nsKeys = Array.from(blobs.plainStore.keys());
+        expect(nsKeys.length).toBeGreaterThan(0);
 
-    it('Standard basic test', async () => {
+        for (const [ns, recs] of blobs.plainStore) {
+            for (const r of recs) {
+                expect(r.embedding).toBeInstanceOf(Float32Array);
+                expect((r.embedding as Float32Array).length).toBe(64);
+            }
+        }
+    });
+
+    it('Definitions are hydrated from bundle on concept.load()', async () => {
         try {
+            // Seed blobs before creating the concept
+            A_FrameBrowserStorageBlobs.fromBundle(bundle);
+
             const concept = new A_Concept({
-                name: 'Test Concept',
-                components: [A_Frame, A_FrameBrowserChannel],
+                name: 'BundleTest',
+                components: [A_Frame],
                 containers: [
                     new A_Container({
-                        name: 'Container A',
-                        components: [ComponentA, ComponentB, ComponentC]
-                    })
-                ]
-            })
+                        name: 'Container',
+                        components: [ComponentA, ComponentB, ComponentC],
+                    }),
+                ],
+            });
 
             await concept.load();
-        } catch (error) {
-            if (error instanceof A_Error) {
-                console.error("A_Error occurred:", error.toJSON());
-            } else {
-                console.error("Unexpected error occurred:", error);
+
+            const index = concept.scope.resolve(A_FrameIndex)!;
+            const definitions = index.listDefinitions();
+
+            console.log(`\n  [bundle] ${definitions.length} definition(s) indexed`);
+            for (const def of definitions) {
+                console.log(`    • ${def.name}: isEmbed=${def.isEmbed}  dims=${def.vector?.dimensions ?? 'NONE'}`);
+            }
+
+            expect(definitions.length).toBe(3);
+            for (const def of definitions) {
+                expect(def.isEmbed).toBe(true);
+                expect(def.vector).toBeDefined();
+                expect(def.vector!.dimensions).toBe(64);
             }
+        } catch (error) {
+            if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
             throw error;
         }
     });
 
-    it('Should Allow to do search in index', async () => {
+    it('Index search returns results after bundle hydration', async () => {
         try {
+            A_FrameBrowserStorageBlobs.fromBundle(bundle);
+
             const concept = new A_Concept({
-                name: 'Test Concept',
-                components: [A_Frame, A_FrameBrowserChannel],
+                name: 'BundleSearchTest',
+                components: [A_Frame],
                 containers: [
                     new A_Container({
-                        name: 'Container A',
-                        components: [ComponentA, ComponentB, ComponentC]
-                    })
-                ]
-            })
+                        name: 'Container',
+                        components: [ComponentA, ComponentB, ComponentC],
+                    }),
+                ],
+            });
 
             await concept.load();
 
             const index = concept.scope.resolve(A_FrameIndex)!;
-            const channel = concept.scope.resolve(A_FrameBrowserChannel)!;
-
-            const query = "I need to apply some business rules and validate data before saving";
-
-            const result = await channel.embed(query);
 
-            const vector = new A_FrameVector(result.response!.data[0].embedding);
+            // Use ComponentA's own vector as query — it should rank first
+            const compA = index.listDefinitions().find(d => d.name === ComponentA.name)!;
+            expect(compA).toBeDefined();
 
-            const indexResult = index.search(vector, {
-                topK: 1,
-            });
+            const queryVector = new A_FrameVector(compA.vector!.values.slice());
+            const results = index.search(queryVector, { topK: 3 });
 
-            console.log("Search results:", indexResult);
+            console.log('\n  [search]');
+            results.forEach((r, i) =>
+                console.log(`    [${i + 1}] ${r.record.name}  score=${r.score.toFixed(4)}`),
+            );
 
+            expect(results.length).toBeGreaterThan(0);
+            // The top result must be ComponentA itself (cosine = 1.0)
+            expect(results[0].record.name).toBe(ComponentA.name);
+            expect(results[0].score).toBeCloseTo(1.0, 5);
         } catch (error) {
-            if (error instanceof A_Error) {
-                console.error("A_Error occurred:", error.toJSON());
-            } else {
-                console.error("Unexpected error occurred:", error);
-            }
+            if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
             throw error;
         }
     });
 });
+

package/tests/A-FrameDynamicContent.browser.test.ts

@@ -0,0 +1,74 @@
+import { A_Concept, A_Container, A_Error } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+import { A_FrameDynamicContent } from "@adaas/a-frame/dynamic-content";
+import { config } from 'dotenv';
+
+config();
+
+describe('A-Frame DynamicContent Browser Tests', () => {
+
+    it('Dynamic article generation and editing (browser channel)', async () => {
+        try {
+            const container = new A_Container({
+                name: 'Container A',
+                components: []
+            });
+
+            const concept = new A_Concept({
+                name: 'Test Concept',
+                components: [A_Frame, ],
+                containers: [container]
+            });
+
+            await concept.load();
+
+            const article = new A_FrameDynamicContent({
+                prompt: "Write a concise article about software architecture. Cover: what it is, key principles (separation of concerns, modularity, scalability), and common patterns (layered, microservices, event-driven). Keep each section brief — 2-3 sentences.",
+            });
+
+            container.scope.register(article);
+
+            // ── Step 1: Generate ───────────────────────────────────────────────
+            await article.generate();
+
+            console.log("=== Generated article ===");
+            console.log(article.text);
+
+            expect(article.segments.length).toBeGreaterThan(0);
+            expect(article.text.length).toBeGreaterThan(0);
+
+            const generatedText = article.text;
+
+            // ── Step 2: Add examples ───────────────────────────────────────────
+            await article.patch("Add a concrete real-world example for each architectural pattern mentioned (layered, microservices, event-driven). Insert each example directly after the section it illustrates.");
+
+            console.log("\n=== After adding examples ===");
+            console.log(article.text);
+
+            expect(article.text.length).toBeGreaterThan(generatedText.length);
+            expect(article.segments.length).toBeGreaterThanOrEqual(article.segments.length);
+
+            // ── Step 3: Modify a segment ───────────────────────────────────────
+            const textBeforeModify = article.text;
+
+            await article.patch("Rewrite the paragraph about key principles to also mention the DRY (Don't Repeat Yourself) principle. Keep the paragraph roughly the same length.");
+
+            console.log("\n=== After modifying key principles paragraph ===");
+            console.log(article.text);
+
+            const modified = article.text !== textBeforeModify;
+            console.log(`\n=== Modification verified: ${modified ? 'YES — content changed' : 'NO — unchanged (unexpected)'} ===`);
+            expect(modified).toBe(true);
+            expect(article.text.toLowerCase()).toContain('dry');
+
+        } catch (error) {
+            if (error instanceof A_Error) {
+                console.error("A_Error occurred:", error.toJSON());
+            } else {
+                console.error("Unexpected error occurred:", error);
+            }
+            throw error;
+        }
+
+    }, 60 * 60 * 1000);
+});

package/tests/integration/A-Frame.integration.test.ts

@@ -0,0 +1,272 @@
+import { A_Component, A_Concept, A_Container, A_Context, A_Entity, A_Error, A_Fragment, A_Scope } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+import { config } from 'dotenv';
+import { A_FrameIndex } from "@adaas/a-frame/index";
+import { A_FrameChannel } from "@adaas/a-frame/channel";
+import { A_FrameSegment } from "@adaas/a-frame/segment";
+import { A_FrameVector } from "@adaas/a-frame/vector";
+import { A_FRAME_MODELS } from "@adaas/a-frame/models";
+
+config();
+
+// Embedding 10 components via Ollama takes ~30 s on the very first run.
+// Subsequent runs are fast: definitions are loaded from the local .aframe
+// storage cache and re-embedding is skipped automatically.
+// The storage layer compares hash + server version on load; if either changes
+// (e.g. description edited or server upgraded) only the affected definitions
+// are re-embedded — no manual cache purge needed.
+jest.setTimeout(180_000);
+
+// ---------------------------------------------------------------------------
+// Component definitions — each covers a clearly distinct domain so that
+// cosine-similarity search should unambiguously rank the correct one first.
+// ---------------------------------------------------------------------------
+
+@A_Frame.Define({
+    description: 'Handles HTTP requests and response formatting for the REST API layer. Use this for routing, middleware, request validation, and sending HTTP responses.',
+})
+class ComponentA extends A_Component { }         // HTTP / REST routing
+
+@A_Frame.Define({
+    description: 'Manages database connections and performs CRUD operations on persistent storage. Use this for querying, inserting, updating, and deleting records in a relational or NoSQL database.',
+})
+class ComponentB extends A_Component { }         // Database / persistence
+
+@A_Frame.Define({
+    description: 'Orchestrates business logic and coordinates between the HTTP layer and the database layer. Use this for applying processing rules, data validation, and domain-level transformations.',
+})
+class ComponentC extends A_Component { }         // Business logic
+
+@A_Frame.Define({
+    description: 'Handles user authentication, session management, and JWT token verification. Use this for login, logout, password hashing, token issuance, and access-control checks.',
+})
+class ComponentD extends A_Component { }         // Auth / JWT
+
+@A_Frame.Define({
+    description: 'Sends transactional and marketing emails, push notifications, and SMS messages to users. Use this whenever you need to notify a user via any messaging channel.',
+})
+class ComponentE extends A_Component { }         // Notifications / Email
+
+@A_Frame.Define({
+    description: 'Manages file uploads, downloads, and cloud blob storage operations. Use this for persisting binary assets, generating pre-signed URLs, and streaming files to/from object storage.',
+})
+class ComponentF extends A_Component { }         // File / blob storage
+
+@A_Frame.Define({
+    description: 'Provides in-memory and Redis-based caching to reduce latency for expensive computations. Use this to store, retrieve, and invalidate cached data with configurable TTL.',
+})
+class ComponentG extends A_Component { }         // Cache / Redis
+
+@A_Frame.Define({
+    description: 'Schedules and executes background jobs, recurring cron tasks, and deferred work. Use this to offload long-running processing from the request cycle.',
+})
+class ComponentH extends A_Component { }         // Background jobs / scheduling
+
+@A_Frame.Define({
+    description: 'Records structured audit logs, application traces, and observability events. Use this to persist user-action history, system events, and debug traces to a log store.',
+})
+class ComponentI extends A_Component { }         // Logging / audit
+
+@A_Frame.Define({
+    description: 'Processes payments, manages billing plans, and integrates with payment gateways such as Stripe or PayPal. Use this to charge customers, issue refunds, and handle subscription lifecycles.',
+})
+class ComponentJ extends A_Component { }         // Payments / billing
+
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function buildConcept() {
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [
+            new A_Container({
+                name: 'Container A',
+                components: [
+                    ComponentA, ComponentB, ComponentC,
+                    ComponentD, ComponentE, ComponentF,
+                    ComponentG, ComponentH, ComponentI, ComponentJ,
+                ],
+            }),
+        ],
+    });
+    await concept.load();
+    return concept;
+}
+
+async function searchTop1(
+    scope: A_Scope,
+    index: A_FrameIndex,
+    query: string,
+) {
+    // Wrap the query in an A_FrameSegment with task:'query' so nomic-embed-text
+    // uses its "search_query:" prefix — matching the "search_document:" prefix
+    // applied when the definitions were embedded.
+    const segment = new A_FrameSegment({ content: query, options: { task: 'query' } });
+    await segment.embed(scope);
+
+    if (!segment.vector || segment.vector.dimensions === 0) {
+        throw new Error(`Segment embedding is empty for query: "${query}".`);
+    }
+    // Query segments default to Antares model, task forced to 'query'
+    expect(segment.options?.model).toBe(A_FRAME_MODELS.ANTARES);
+    expect(segment.options?.task).toBe('query');
+    console.log(`\n  [embed] model="${segment['_model'] ?? 'unknown'}" dims=${segment.vector.dimensions} task=query`);
+
+    const results = index.search(segment.vector, { topK: 3 });
+
+    console.log(`  Query: "${query}"`);
+    results.forEach((r, i) =>
+        console.log(`    [${i + 1}] ${r.record.name}  (score: ${r.score.toFixed(4)})  — ${r.record.description?.slice(0, 60)}...`),
+    );
+
+    return results;
+}
+
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('A-Frame Tests', () => {
+
+    // The suite needs A_FRAME_SYNC enabled so that missing or stale
+    // definitions are embedded and saved on the first run.
+    // The storage layer's hash + server-version check handles all staleness
+    // automatically — no manual cache wipe is ever needed.
+    beforeAll(() => {
+        process.env.A_FRAME_SYNC = 'true';
+    });
+
+    afterAll(() => {
+        // Restore the default (jest.setup.ts value) so other test files
+        // are not affected when the suite runs in watch mode.
+        process.env.A_FRAME_SYNC = 'false';
+    });
+
+    it('Standard basic test — concept loads without errors', async () => {
+        try {
+            const concept = await buildConcept();
+
+            // Verify every definition was embedded (non-zero vector)
+            const index = concept.scope.resolve(A_FrameIndex)!;
+            const definitions = index.listDefinitions();
+
+            console.log(`\n  [index] ${definitions.length} definition(s) loaded`);
+            for (const def of definitions) {
+                console.log(`    • ${def.name}: vector dims=${def.vector?.dimensions ?? 'MISSING'} model="${def.model ?? 'N/A'}"`);
+                expect(def.vector).toBeDefined();
+                expect(def.vector!.dimensions).toBeGreaterThan(0);
+                // After embedding the server returns the physical model name
+                expect(typeof def.model).toBe('string');
+                expect(def.model.length).toBeGreaterThan(0);
+                // The logical model requested at definition-creation time should be Antares
+                expect(def.requestedModel).toBe(A_FRAME_MODELS.ANTARES);
+            }
+        } catch (error) {
+            if (error instanceof A_Error) console.error("A_Error:", error.toJSON());
+            else console.error("Unexpected error:", error);
+            throw error;
+        }
+    });
+
+    it('Should allow to do search in index', async () => {
+        try {
+            const concept = await buildConcept();
+            const index = concept.scope.resolve(A_FrameIndex)!;
+
+            const results = await searchTop1(
+                concept.scope, index,
+                "I need to apply some business rules and validate data before saving",
+            );
+
+            expect(results.length).toBeGreaterThan(0);
+            expect(results[0].record.name).toBe('ComponentC');
+        } catch (error) {
+            if (error instanceof A_Error) console.error("A_Error:", error.toJSON());
+            else console.error("Unexpected error:", error);
+            throw error;
+        }
+    });
+
+    // -----------------------------------------------------------------------
+    // Parametrised search-accuracy cases
+    // -----------------------------------------------------------------------
+
+    const searchCases: Array<{ query: string; expectedComponent: string }> = [
+        {
+            query: "Route an incoming HTTP POST request and send a JSON response",
+            expectedComponent: 'ComponentA',
+        },
+        {
+            query: "Insert a new record into the database and query existing ones",
+            expectedComponent: 'ComponentB',
+        },
+        {
+            query: "Apply domain validation rules and orchestrate the processing pipeline",
+            expectedComponent: 'ComponentC',
+        },
+        {
+            query: "Verify a JWT token and check whether the user is authorised to access this resource",
+            expectedComponent: 'ComponentD',
+        },
+        {
+            query: "Send a welcome email and a push notification to a newly registered user",
+            expectedComponent: 'ComponentE',
+        },
+        {
+            query: "Upload an image to cloud object storage and generate a pre-signed download URL",
+            expectedComponent: 'ComponentF',
+        },
+        {
+            query: "Reduce latency by serving hot data from an in-memory Redis cache with TTL-based eviction",
+            expectedComponent: 'ComponentG',
+        },
+        {
+            query: "Schedule a background task to process a report asynchronously after midnight",
+            expectedComponent: 'ComponentH',
+        },
+        {
+            query: "Record an audit trail entry whenever a user modifies sensitive data",
+            expectedComponent: 'ComponentI',
+        },
+        {
+            query: "Charge a customer's credit card and handle a payment failure with a refund",
+            expectedComponent: 'ComponentJ',
+        },
+    ];
+
+    describe('Search accuracy — each query should return the correct component as the top result', () => {
+
+        // jest.setup.ts calls A_Context.reset() BEFORE EACH test, which wipes
+        // the root scope.  We rebuild the concept in beforeEach so the index
+        // and channel are re-registered.  Subsequent buildConcept() calls are
+        // fast because A_FrameNodeStorage loads definitions from the .aframe
+        // cache files on disk and skips the embedding API call entirely.
+        let index: A_FrameIndex;
+        let scope: A_Scope;
+
+        beforeEach(async () => {
+            const concept = await buildConcept();
+            index = concept.scope.resolve(A_FrameIndex)!;
+            scope = concept.scope;
+        });
+
+        test.each(searchCases)(
+            '$query → $expectedComponent',
+            async ({ query, expectedComponent }) => {
+                const results = await searchTop1(scope, index, query);
+
+                expect(results.length).toBeGreaterThan(0);
+
+                const topResult = results[0];
+                expect(topResult.record.name).toBe(expectedComponent);
+
+                // Sanity-check: top score should be meaningfully higher than 0
+                expect(topResult.score).toBeGreaterThan(0.1);
+            },
+        );
+    });
+});