@adaas/a-frame 0.1.1 → 0.1.2

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

@@ -0,0 +1,88 @@
+import { A_Concept, A_Container, A_Error } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { config } from 'dotenv';
+import { A_FrameCompletion } from '@adaas/a-frame/completion';
+import { A_FRAME_MODELS } from '@adaas/a-frame/models';
+
+config();
+
+jest.setTimeout(60_000);
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function buildConcept() {
+    const container = new A_Container({
+        name: 'Completion Test Container',
+        components: [],
+    });
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+    return { concept, container };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame Completion Tests', () => {
+
+    describe('Integration — text generation', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('produces text and an embedding vector', async () => {
+            try {
+                const completion = new A_FrameCompletion({
+                    prompt: 'Write one sentence explaining what an embedding vector is.',
+                });
+                expect(completion.options?.model).toBe(A_FRAME_MODELS.RIGEL);
+
+                container.scope.register(completion);
+                await completion.generate();
+
+                expect(completion.isGenerated).toBe(true);
+                expect(typeof completion.text).toBe('string');
+                expect(completion.text!.length).toBeGreaterThan(0);
+                expect(completion.vector).toBeDefined();
+                expect(completion.vector!.values.length).toBeGreaterThan(0);
+                expect(typeof completion.model).toBe('string');
+                expect(completion.model!.length).toBeGreaterThan(0);
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+        it('different prompts produce different vectors', async () => {
+            try {
+                const c1 = new A_FrameCompletion({
+                    prompt: 'Write one sentence explaining what an embedding vector is.',
+                });
+                const c2 = new A_FrameCompletion({
+                    prompt: 'Describe the lifecycle of a butterfly in one sentence.',
+                });
+                container.scope.register(c1);
+                container.scope.register(c2);
+                await c1.generate();
+                await c2.generate();
+
+                expect(c1.vector).toBeDefined();
+                expect(c2.vector).toBeDefined();
+                expect(c2.vector!.isEqualTo(c1.vector!)).toBe(false);
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+});

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

@@ -0,0 +1,261 @@
+import { A_Component, A_Concept, A_Container, A_Error } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame/core";
+import { A_FrameIndex } from "@adaas/a-frame/index";
+import { A_FrameDynamicContent } from "@adaas/a-frame/dynamic-content";
+import { A_FrameCompletion } from "@adaas/a-frame/completion";
+import { config } from 'dotenv';
+
+config();
+
+jest.setTimeout(5 * 60 * 1000);
+
+// ─── UI Component Definitions ─────────────────────────────────────────────────
+// These represent the available components in an article renderer.
+// @A_Frame.Define() stores a semantic description in the index so that
+// any content segment can be matched to the right component via vector search.
+
+@A_Frame.Define({
+    description: 'Renders the main title or headline of an article. Use for the primary H1 heading at the top of the page.',
+})
+class TitleComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a section heading (H2/H3). Use for sub-headings that introduce a new topic or group of content within the article.',
+})
+class SectionHeadingComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a block of descriptive text or a paragraph. Use for general narrative content, explanations, introductions, or conclusions.',
+})
+class TextParagraphComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a clickable hyperlink. Use when content references an external resource, source, or URL.',
+})
+class LinkComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders an interactive button element. Use for calls-to-action such as "Learn More", "View Details", or "Compare".',
+})
+class ButtonComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a bar chart that compares numerical values across categories. Use for comparing statistics, counts, or measurements between multiple items (e.g. average weight by breed).',
+})
+class BarChartComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a pie chart showing proportional data or percentage breakdowns. Use when the content describes how a total is distributed across categories (e.g. popularity share by breed).',
+})
+class PieChartComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a data table with rows and columns. Use for structured tabular data such as side-by-side breed comparisons, trait lists, or statistical tables.',
+})
+class DataTableComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders an image or photo with an optional caption. Use when the content references a visual, illustration, or photo of a dog breed.',
+})
+class ImageComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a highlighted fact or key statistic in a prominent callout box. Use for single notable numbers or fun facts (e.g. "The Labrador has ranked #1 in popularity for 30 years").',
+})
+class StatCalloutComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a bullet-point or numbered list. Use when the content enumerates traits, characteristics, or steps (e.g. "Top 5 most popular breeds: ...").',
+})
+class ListComponent extends A_Component {}
+
+@A_Frame.Define({
+    description: 'Renders a breed profile card showing key attributes such as origin, size, temperament, and lifespan in a compact summary format.',
+})
+class BreedProfileCardComponent extends A_Component {}
+
+
+// ─── Bridge prompt ─────────────────────────────────────────────────────────────
+
+const BRIDGE_SYSTEM = [
+    'You are a UI layout assistant. Given a piece of article content, your only job is to',
+    'describe which single UI component from a standard article renderer would best',
+    'visualise that content. Be specific: mention the visual form (chart, card, table, heading,',
+    'paragraph, list, etc.) and what data it would show. Keep the answer to 1-2 sentences.',
+].join(' ');
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type SegmentMapping = {
+    segmentIndex: number;
+    segmentSnippet: string;
+    bridgeDescription: string;
+    componentName: string;
+    score: number;
+};
+
+// ─── Pipeline helper ──────────────────────────────────────────────────────────
+
+async function buildMappings(): Promise<{
+    index: A_FrameIndex;
+    article: A_FrameDynamicContent;
+    mappings: SegmentMapping[];
+}> {
+    const container = new A_Container({
+        name: 'Article Container',
+        components: [
+            TitleComponent,
+            SectionHeadingComponent,
+            TextParagraphComponent,
+            LinkComponent,
+            ButtonComponent,
+            BarChartComponent,
+            PieChartComponent,
+            DataTableComponent,
+            ImageComponent,
+            StatCalloutComponent,
+            ListComponent,
+            BreedProfileCardComponent,
+        ],
+    });
+
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+
+    await concept.load();
+
+    const index = concept.scope.resolve(A_FrameIndex)!;
+
+    // Embed all component definitions explicitly (A_FRAME_SYNC is disabled in jest.setup.ts)
+    const definitions = index.listDefinitions();
+    await Promise.all(definitions.map(def => def.embed()));
+
+    console.log(`\n=== Index loaded: ${index.indexSize} component definitions ===\n`);
+
+    // Generate a short article — keep the prompt concise so that even a
+    const article = new A_FrameDynamicContent({
+        prompt: [
+            'Write a short article about web development. Include:',
+            '- A title',
+            '- An introduction paragraph',
+            '- A section listing 3 popular frontend frameworks with brief descriptions',
+            '- A comparison table of those frameworks',
+            '- A conclusion paragraph',
+        ].join('\n'),
+    });
+
+    container.scope.register(article);
+    await article.generate();
+
+    console.log(`=== Article generated: ${article.segments.length} segments ===\n`);
+
+    // Map each segment to a component via bridge completion
+    const mappings: SegmentMapping[] = [];
+
+    for (let i = 0; i < article.segments.length; i++) {
+        const segment = article.segments[i];
+        const contentSnippet = segment.content.slice(0, 500);
+
+        const bridge = new A_FrameCompletion({
+            prompt: `Content segment:\n"""\n${contentSnippet}\n"""\n\nDescribe which UI component should render this content.`,
+            options: {
+                system: BRIDGE_SYSTEM,
+                max_tokens: 80,
+            },
+        });
+
+        container.scope.register(bridge);
+
+        let searchVector = segment.vector;
+
+        try {
+            await bridge.generate();
+            searchVector = bridge.vector ?? searchVector;
+        } catch (bridgeErr) {
+            console.warn(
+                `[${i}] Bridge completion failed, using segment embedding as fallback:`,
+                bridgeErr instanceof Error ? bridgeErr.message : String(bridgeErr),
+            );
+        }
+
+        if (!searchVector) {
+            console.warn(`[${i}] No embedding available — skipping`);
+            continue;
+        }
+
+        const results = index.search(searchVector, { topK: 1 });
+        const best = results[0];
+
+        const mapping: SegmentMapping = {
+            segmentIndex: i,
+            segmentSnippet: segment.content.slice(0, 80).replace(/\n/g, ' '),
+            bridgeDescription: (bridge.text ?? '(segment embedding fallback)').slice(0, 120).replace(/\n/g, ' '),
+            componentName: best?.record.name ?? '(no match)',
+            score: best?.score ?? 0,
+        };
+
+        mappings.push(mapping);
+
+        console.log(
+            `[${String(i).padStart(2)}] ${mapping.componentName.padEnd(28)} score=${mapping.score.toFixed(3)}\n` +
+            `     content  : ${mapping.segmentSnippet}\n` +
+            `     bridge   : ${mapping.bridgeDescription}\n`,
+        );
+    }
+
+    return { index, article, mappings };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame Content Mapping Tests', () => {
+
+    // ── Integration: content-to-component pipeline ────────────────────────
+
+    describe('Integration — content-to-component pipeline', () => {
+
+        let index: A_FrameIndex;
+        let article: A_FrameDynamicContent;
+        let mappings: SegmentMapping[];
+
+        beforeAll(async () => {
+            try {
+                ({ index, article, mappings } = await buildMappings());
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+        it('index contains all component definitions', () => {
+            expect(index.indexSize).toBeGreaterThan(0);
+        });
+
+        it('article generates at least one segment', () => {
+            expect(article.segments.length).toBeGreaterThan(0);
+        });
+
+        it('every segment is mapped to a named component', () => {
+            expect(mappings.length).toBeGreaterThan(0);
+            for (const m of mappings) {
+                expect(m.componentName).toBeTruthy();
+            }
+        });
+
+        it('multiple distinct component types are used across the article', () => {
+            const distinctComponents = new Set(mappings.map(m => m.componentName));
+            console.log('\n=== Component usage summary ===');
+            for (const name of distinctComponents) {
+                const count = mappings.filter(m => m.componentName === name).length;
+                console.log(`  ${name}: ${count}`);
+            }
+            expect(distinctComponents.size).toBeGreaterThan(1);
+        });
+
+    });
+
+});

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

@@ -0,0 +1,154 @@
+/**
+ * A-FrameDefinition.integration.test.ts — integration test for the A_FrameDefinition
+ * embedding round-trip.
+ *
+ * Connects to a running adaas-a-frame-mcp server (env vars required).
+ *
+ * Required env vars:
+ *   A_FRAME_SERVER_URL  — e.g. http://localhost:3000
+ *   A_FRAME_VERSION     — semver of the client library, e.g. 0.1.1
+ */
+
+import { config } from 'dotenv';
+import { A_Concept, A_Container } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { A_FrameDefinition } from '@adaas/a-frame/definition';
+import { A_FrameNamespace } from '@adaas/a-frame/namespace';
+import { A_FrameTargetType } from '@adaas/a-frame/core';
+import { A_FRAME_MODELS } from '@adaas/a-frame/models';
+
+config();
+
+jest.setTimeout(60_000);
+
+// ─── sample component source to embed ────────────────────────────────────────
+
+const SAMPLE_SOURCE = `
+import { A_Component, A_Feature, A_Inject } from '@adaas/a-concept';
+import { AuthService } from './AuthService';
+import { UserRepository } from './UserRepository';
+
+export class UserController extends A_Component {
+
+    @A_Feature.Extend({ name: 'getUser', scope: 'user-read' })
+    async getUser(
+        @A_Inject(AuthService) auth: AuthService,
+        @A_Inject(UserRepository) repo: UserRepository,
+    ) {
+        await auth.verify();
+        return repo.findById(1);
+    }
+
+    @A_Feature.Extend({ name: 'createUser', scope: 'user-write' })
+    async createUser(
+        @A_Inject(UserRepository) repo: UserRepository,
+    ) {
+        return repo.create({ name: 'test' });
+    }
+
+    lookup(id: number): string {
+        return \`user:\${id}\`;
+    }
+}
+`.trim();
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function makeDefinition(ns: A_FrameNamespace) {
+    return new A_FrameDefinition({
+        name: 'UserController',
+        dependency: 'UserController',
+        description: 'Handles user CRUD operations',
+        source: SAMPLE_SOURCE,
+        type: A_FrameTargetType.COMPONENT,
+        namespace: ns,
+    });
+}
+
+async function setup() {
+    const ns = new A_FrameNamespace({ name: 'test' });
+    const def = makeDefinition(ns);
+    const container = new A_Container({ name: 'test-container', components: [] });
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+    container.scope.register(ns);
+    container.scope.register(def);
+    await concept.load();
+    return def;
+}
+
+// ─── tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame Definition Tests', () => {
+
+    // A single embed() call is shared across all assertions via beforeAll.
+    // This avoids 6 independent network round-trips while still exercising
+    // the full embedding pipeline exactly once per test run.
+
+    describe('Integration — embed() round-trip', () => {
+
+        let definition: A_FrameDefinition;
+
+        beforeAll(async () => {
+            definition = await setup();
+            await definition.embed();
+        });
+
+        it('populates vector after embed()', () => {
+            expect(definition.vector).toBeDefined();
+            expect(definition.vector!.values.length).toBeGreaterThan(0);
+            expect(typeof definition.model).toBe('string');
+            expect(definition.model.length).toBeGreaterThan(0);
+        });
+
+        it('populates aFrameMeta with extracted className', () => {
+            expect(definition.aFrameMeta).toBeDefined();
+            expect(definition.aFrameMeta!.className).toBe('UserController');
+        });
+
+        it('aFrameMeta.methods includes expected public methods', () => {
+            const methods = definition.aFrameMeta!.methods;
+            expect(methods).toContain('getUser');
+            expect(methods).toContain('createUser');
+            expect(methods).toContain('lookup');
+        });
+
+        it('aFrameMeta.injectDeps includes @A_Inject dependencies', () => {
+            const deps = definition.aFrameMeta!.injectDeps;
+            expect(deps).toContain('AuthService');
+            expect(deps).toContain('UserRepository');
+        });
+
+        it('aFrameMeta.features includes @A_Feature.Extend names', () => {
+            const features = definition.aFrameMeta!.features;
+            expect(features).toContain('getUser');
+            expect(features).toContain('createUser');
+        });
+
+        it('preserves aFrameMeta through toJSON / fromJSON round-trip', () => {
+            const serialized = definition.toJSON();
+            expect(serialized.aFrameMeta).toBeDefined();
+            expect(serialized.aFrameMeta!.className).toBe('UserController');
+
+            const ns = new A_FrameNamespace({ name: 'test' });
+            const restored = new A_FrameDefinition({
+                name: 'UserController',
+                dependency: 'UserController',
+                source: '',
+                type: A_FrameTargetType.COMPONENT,
+                namespace: ns,
+            });
+            restored.fromJSON(serialized);
+
+            expect(restored.aFrameMeta).toBeDefined();
+            expect(restored.aFrameMeta!.methods).toEqual(definition.aFrameMeta!.methods);
+            expect(restored.aFrameMeta!.injectDeps).toEqual(definition.aFrameMeta!.injectDeps);
+            expect(restored.aFrameMeta!.features).toEqual(definition.aFrameMeta!.features);
+        });
+
+    });
+
+});

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

@@ -0,0 +1,126 @@
+import { A_Concept, A_Container, A_Error } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { config } from 'dotenv';
+import { A_FrameDynamicContent } from '@adaas/a-frame/dynamic-content';
+import { A_FRAME_MODELS } from '@adaas/a-frame/models';
+
+config();
+
+jest.setTimeout(60 * 60 * 1000);
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function buildConcept() {
+    const container = new A_Container({ name: 'DynamicContent Test Container', components: [] });
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+    return { concept, container };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame DynamicContent Tests', () => {
+
+    describe('Integration — generate and patch', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('generates content and applies sequential patches', async () => {
+            try {
+                const newContent = 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(newContent);
+                await newContent.generate();
+
+                console.log('=== Generated article ===');
+                console.log(newContent.text);
+
+                await newContent.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(newContent.text);
+
+                await newContent.patch("Remove all the example sentences that were added (the ones describing real-world examples for each pattern).");
+
+                console.log('\n=== After removing examples ===');
+                console.log(newContent.text);
+
+                const textBeforeModify = newContent.text;
+
+                await newContent.patch("Rewrite the paragraph about key principles to also mention the DRY (Don't Repeat Yourself) principle. Keep the paragraph roughly the same length.");
+
+                const textAfterModify = newContent.text;
+
+                console.log('\n=== After modifying key principles paragraph ===');
+                console.log(newContent.text);
+
+                expect(textAfterModify).not.toBe(textBeforeModify);
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+    describe('Integration — semantic comparison', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('related topics score higher than unrelated topics', async () => {
+            try {
+                const cats1 = new A_FrameDynamicContent({
+                    prompt: 'Write a short article about cats: their behaviour, habits, and why people love them as pets.',
+                });
+                const cats2 = new A_FrameDynamicContent({
+                    prompt: 'Write a short article about kittens: how they grow, play, and become adult cats.',
+                });
+                const cars = new A_FrameDynamicContent({
+                    prompt: 'Write a short article about racing cars: engine specifications, speed records, and Formula 1.',
+                });
+
+                container.scope.register(cats1);
+                container.scope.register(cats2);
+                container.scope.register(cars);
+
+                await cats1.generate();
+                await cats2.generate();
+                await cars.generate();
+
+                const relatedScore = cats1.compareTo(cats2);
+                const unrelatedScore = cats1.compareTo(cars);
+
+                console.log(`Related score  (cats vs kittens): ${relatedScore.toFixed(4)}`);
+                console.log(`Unrelated score (cats vs cars):    ${unrelatedScore.toFixed(4)}`);
+
+                expect(relatedScore).toBeGreaterThanOrEqual(0);
+                expect(relatedScore).toBeLessThanOrEqual(1);
+                expect(unrelatedScore).toBeGreaterThanOrEqual(0);
+                expect(unrelatedScore).toBeLessThanOrEqual(1);
+                expect(relatedScore).toBeGreaterThan(unrelatedScore);
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+});