@adaas/a-frame 0.1.1 → 0.1.2

package/src/lib/A-FrameDynamicStructure/A-FrameComponentMapper.component.ts

@@ -0,0 +1,320 @@
+import { A_Caller, A_Component, A_Container, A_Context, A_Entity, A_Feature, A_Fragment, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_FrameChannel } from "../A-FrameChannel/A-FrameChannel.component";
+import { A_FrameFeatures } from "../A-FrameChannel/A-FrameChannel.constants";
+import { A_FrameChannelRequest } from "../A-FrameChannel/A-FrameChannelRequest.context";
+import { A_FrameIndex } from "../A-FrameIndex/A-FrameIndex.context";
+import { A_FrameInheritanceFilter } from "../A-FrameIndex/A-FrameIndex.types";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import { A_FrameDynamicStructure } from "./A-FrameDynamicStructure.entity";
+import { A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
+import { A_FrameDynamicStructureError } from "./A-FrameDynamicStructure.error";
+import {
+    A_FrameComponentMapEntry,
+    A_FrameDynamicStructureDefinition,
+    A_FrameDynamicStructureDefinitionEntity,
+    A_FrameStructureSelectRequest,
+    A_FrameStructureSelectResolution,
+    A_FrameStructureSelectResponse,
+} from "./A-FrameDynamicStructure.types";
+import { A_FrameComponentMapIndex } from "./A-FrameComponentMapIndex.context";
+
+
+/**
+ * Stateless component that implements the `Map` feature for
+ * `A_FrameDynamicStructure`.
+ *
+ * Receives all necessary context via `@A_Inject` — it stores no state of its
+ * own.  Injects the calling structure (via `A_Caller`), the local definition
+ * index (`A_FrameIndex`), the map-result accumulator (`A_FrameComponentMapIndex`),
+ * and the HTTP channel (`A_FrameChannel`) needed for refinement retry calls.
+ *
+ * Algorithm:
+ *  1. Read `structure.definition` (raw, with server embeddings).
+ *  2. For every element run cosine-similarity search against `A_FrameIndex`.
+ *  3. For remaining unmatched elements (up to `structure.maxRetries`): ask the
+ *     server to refine their descriptions, then re-match the new definition.
+ *  4. Mark still-unmatched elements with a `matchError`.
+ *  5. Call `structure.hydrateFromMap(mapIndex.toResult(workingDef))`.
+ */
+export class A_FrameComponentMapper extends A_Component {
+
+    @A_Feature.Extend({
+        name: A_FrameDynamicStructureFeatures.Map,
+        scope: [A_FrameDynamicStructure],
+    })
+    async mapStructure(
+        @A_Inject(A_Caller) structure: A_FrameDynamicStructure,
+        @A_Inject(A_FrameComponentMapIndex) mapIndex: A_FrameComponentMapIndex,
+        @A_Inject(A_FrameIndex) frameIndex: A_FrameIndex,
+        @A_Inject(A_FrameChannel) channel: A_FrameChannel,
+    ): Promise<void> {
+
+        const def = structure.definition;
+        if (!def) return;
+
+        // ── helpers ──────────────────────────────────────────────────────────
+
+        const tryMatch = (
+            el: A_FrameDynamicStructureDefinitionEntity,
+            minScore: number,
+            inherit?: A_FrameInheritanceFilter | A_FrameInheritanceFilter[],
+        ): Pick<A_FrameComponentMapEntry, 'matchedClass' | 'matchScore'> => {
+            if (!el.embedding?.length) {
+                return { matchedClass: null, matchScore: 0 };
+            }
+            const results = frameIndex.search(new A_FrameVector(el.embedding), { topK: 1, inherit });
+            const top = results[0];
+            if (top && top.score >= minScore) {
+                return { matchedClass: top.record.name, matchScore: top.score };
+            }
+            return { matchedClass: null, matchScore: top?.score ?? 0 };
+        };
+
+        const allElements = (d: A_FrameDynamicStructureDefinition): A_FrameDynamicStructureDefinitionEntity[] => [
+            ...d.containers,
+            ...d.containers.flatMap(c => [
+                ...(c.components ?? []),
+                ...(c.fragments  ?? []),
+                ...(c.entities   ?? []),
+            ]),
+            ...d.components,
+            ...d.fragments,
+            ...d.entities,
+        ];
+
+        const stripEmbeddings = (d: A_FrameDynamicStructureDefinition): A_FrameDynamicStructureDefinition => {
+            const strip = (el: A_FrameDynamicStructureDefinitionEntity): A_FrameDynamicStructureDefinitionEntity => {
+                const { embedding, ...rest } = el as any;
+                return rest as A_FrameDynamicStructureDefinitionEntity;
+            };
+            return {
+                containers: d.containers.map(c => ({
+                    ...strip(c),
+                    components: (c.components ?? []).map(strip),
+                    fragments:  (c.fragments  ?? []).map(strip),
+                    entities:   (c.entities   ?? []).map(strip),
+                })),
+                components: d.components.map(strip),
+                fragments:  d.fragments.map(strip),
+                entities:   d.entities.map(strip),
+            };
+        };
+
+        /**
+         * Infer the appropriate inheritance filter for an element by checking which
+         * slot it occupies inside the definition (container / component / fragment / entity).
+         */
+        const inferInherit = (
+            el: A_FrameDynamicStructureDefinitionEntity,
+            d: A_FrameDynamicStructureDefinition,
+        ): A_FrameInheritanceFilter | undefined => {
+            if (d.containers.some(c => c.prompt === el.prompt)) return { class: A_Container };
+            if (d.components.some(c => c.prompt === el.prompt)) return { class: A_Component };
+            if (d.fragments.some(c => c.prompt === el.prompt))  return { class: A_Fragment };
+            if (d.entities.some(c => c.prompt === el.prompt))   return { class: A_Entity };
+            for (const ct of d.containers) {
+                if ((ct.components ?? []).some(c => c.prompt === el.prompt)) return { class: A_Component };
+                if ((ct.fragments  ?? []).some(c => c.prompt === el.prompt)) return { class: A_Fragment };
+                if ((ct.entities   ?? []).some(c => c.prompt === el.prompt)) return { class: A_Entity };
+            }
+            return undefined;
+        };
+
+        /**
+         * Mutate workingDef in-place: update the element identified by `oldPrompt`
+         * with a new prompt, role, and embedding from a server suggestion.
+         * This lets the next iteration's `allElements()` find the updated embedding.
+         */
+        const updateElementEmbedding = (
+            d: A_FrameDynamicStructureDefinition,
+            oldPrompt: string,
+            newPrompt: string,
+            newEmbedding: number[],
+            newRole?: string,
+        ): void => {
+            const update = (el: A_FrameDynamicStructureDefinitionEntity & { role?: string }): void => {
+                if (el.prompt === oldPrompt) {
+                    el.prompt = newPrompt;
+                    el.embedding = newEmbedding;
+                    if (newRole !== undefined) el.role = newRole;
+                }
+            };
+            d.containers.forEach(update);
+            d.containers.forEach(ct => {
+                (ct.components ?? []).forEach(update);
+                (ct.fragments  ?? []).forEach(update);
+                (ct.entities   ?? []).forEach(update);
+            });
+            d.components.forEach(update);
+            d.fragments.forEach(update);
+            d.entities.forEach(update);
+        };
+
+        /**
+         * Match all elements in the definition, restricting each group's candidate
+         * pool to the appropriate base class via inheritance filters:
+         *   containers → A_Container
+         *   components → A_Component
+         *   fragments  → A_Fragment
+         *   entities   → A_Entity
+         */
+        const matchAll = (d: A_FrameDynamicStructureDefinition): void => {
+            mapIndex.clear();
+            const score = structure.minScore;
+
+            // Top-level containers
+            for (const ct of d.containers) {
+                mapIndex.set({
+                    prompt: ct.prompt,
+                    role:   ct.role,
+                    class:  ct.class,
+                    ...tryMatch(ct, score, { class: A_Container }),
+                });
+                // Nested: components, fragments, entities within each container
+                for (const el of (ct.components ?? []))
+                    mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Component }) });
+                for (const el of (ct.fragments ?? []))
+                    mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Fragment }) });
+                for (const el of (ct.entities ?? []))
+                    mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Entity }) });
+            }
+
+            // Top-level cross-cutting elements
+            for (const el of d.components)
+                mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Component }) });
+            for (const el of d.fragments)
+                mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Fragment }) });
+            for (const el of d.entities)
+                mapIndex.set({ prompt: el.prompt, role: el.role, class: el.class, ...tryMatch(el, score, { class: A_Entity }) });
+        };
+
+        // ── initial matching pass ─────────────────────────────────────────────
+
+        const workingDef = def;
+        matchAll(workingDef);
+
+        // ── select / suggest retry loop ───────────────────────────────────────
+        //
+        // For each retry: collect unmatched elements, pull `candidateCount` top
+        // candidates per element from the local index (no minScore filter so we
+        // always have *something* to show the AI), then call /api/v1/structure/select.
+        //
+        // The server returns one resolution per element:
+        //   select  → directly set matchedClass (no re-embed needed)
+        //   suggest → the response includes a fresh embedding; re-run tryMatch
+        //   none    → skip the element (will become a matchError below)
+
+        for (let retry = 0; retry < structure.maxRetries; retry++) {
+            const unmatchedEls = allElements(workingDef).filter(
+                el => el.embedding?.length && mapIndex.get(el.prompt)?.matchedClass === null,
+            );
+            if (unmatchedEls.length === 0) break;
+
+            // Build select payload — top-K candidates per element, no minScore.
+            const k = structure.candidateCount;
+            const selectElements = unmatchedEls.map(el => {
+                // Determine appropriate inheritance filter for this element's role.
+                // We look up the existing map entry to know which slot it lives in.
+                const entry = mapIndex.get(el.prompt);
+                // Use unconstrained search to get candidates (already tried constrained above).
+                const candidateResults = frameIndex.search(
+                    new A_FrameVector(el.embedding!),
+                    { topK: k },
+                );
+                return {
+                    prompt:     el.prompt,
+                    role:       el.role,
+                    candidates: candidateResults.map(r => ({
+                        name:        r.record.name,
+                        description: r.record.description,
+                    })),
+                };
+            });
+
+            // Call /api/v1/structure/select
+            const selectReq = new A_FrameChannelRequest<A_FrameStructureSelectResponse>(
+                'POST',
+                '/api/v1/structure/select',
+                {
+                    originalPrompt: structure.prompt,
+                    elements:       selectElements,
+                    model:          structure.modelName,
+                } satisfies A_FrameStructureSelectRequest,
+            );
+
+            const selectScope = new A_Scope({
+                name: `A_FrameComponentMapper.mapStructure:select${retry}`,
+                fragments: [selectReq],
+            }).inherit(A_Context.scope(channel));
+
+            await channel.call(A_FrameFeatures.Request, selectScope);
+            selectScope.destroy();
+
+            if (!selectReq.response) break;
+
+            // Apply resolutions
+            let anyUpdate = false;
+            for (const resolution of selectReq.response.resolutions) {
+                const existing = mapIndex.get(resolution.elementPrompt);
+                if (!existing) continue;
+
+                if (resolution.type === 'select' && resolution.selectedClass) {
+                    // Direct selection — no re-embed required.
+                    mapIndex.set({ ...existing, matchedClass: resolution.selectedClass, matchScore: 1 });
+                    anyUpdate = true;
+
+                } else if (resolution.type === 'suggest' && resolution.suggestion) {
+                    // Server suggested a re-description, optionally with a fresh embedding.
+                    const { prompt: newPrompt, role: newRole, embedding: newEmbedding } = resolution.suggestion;
+
+                    if (newEmbedding?.length) {
+                        // Re-search locally with the new embedding.
+                        const el = unmatchedEls.find(e => e.prompt === resolution.elementPrompt);
+                        const inherit = el ? inferInherit(el, workingDef) : undefined;
+                        const results = frameIndex.search(
+                            new A_FrameVector(newEmbedding),
+                            { topK: 1, inherit },
+                        );
+                        const top = results[0];
+                        if (top && top.score >= structure.minScore) {
+                            mapIndex.set({ ...existing, matchedClass: top.record.name, matchScore: top.score });
+                            anyUpdate = true;
+                        } else {
+                            // Still unmatched, but update the prompt so next retry uses the new description.
+                            mapIndex.set({ ...existing, prompt: newPrompt, role: newRole });
+                            // Also update the working element so allElements() finds the new embedding.
+                            updateElementEmbedding(workingDef, resolution.elementPrompt, newPrompt, newEmbedding, newRole);
+                            anyUpdate = true;
+                        }
+                    } else {
+                        // No embedding returned — just update description for next round.
+                        mapIndex.set({ ...existing, prompt: newPrompt, role: newRole });
+                        anyUpdate = true;
+                    }
+                }
+                // type === 'none': leave as-is, will become matchError below.
+            }
+
+            if (!anyUpdate) break;
+        }
+
+        // ── finalize: mark remaining unmatched with an error ──────────────────
+
+        for (const el of allElements(workingDef)) {
+            const entry = mapIndex.get(el.prompt);
+            if (entry && entry.matchedClass === null && el.embedding?.length) {
+                mapIndex.set({
+                    ...entry,
+                    matchError: {
+                        title: A_FrameDynamicStructureError.ComponentNotFound,
+                        description: `Unable to match "${el.prompt}" to any registered implementation after ${structure.maxRetries} retries.`,
+                    },
+                });
+            }
+        }
+
+        // ── hydrate the structure with the map result ─────────────────────────
+
+        structure.hydrateFromMap(mapIndex.toResult(workingDef));
+    }
+}

package/src/lib/A-FrameDynamicStructure/A-FrameDynamicStructure.constants.ts

@@ -3,8 +3,9 @@
 
 export const A_FrameDynamicStructureFeatures = {
     Load: '_A_FRAME_DYNAMIC_STRUCTURE_LOAD',
-    Update: '_A_FRAME_DYNAMIC_STRUCTURE_UPDATE',
+    Patch: '_A_FRAME_DYNAMIC_STRUCTURE_PATCH',
     Generate: '_A_FRAME_DYNAMIC_STRUCTURE_GENERATE',
+    Map: '_A_FRAME_DYNAMIC_STRUCTURE_MAP',
 } as const;