@adaas/a-frame 0.0.23 → 0.1.2

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

@@ -1,187 +1,299 @@
-import { A_CommonHelper, A_Context, A_Entity, A_Scope, A_TYPES__A_DependencyInjectable } from "@adaas/a-concept";
-import { A_FrameDynamicStructure_Init, A_FrameDynamicStructure_Serialized, A_FrameDynamicStructureEventNames, A_FrameDynamicStructureListener, A_FrameDynamicStructureResolvedComponent } from "./A-FrameDynamicStructure.types";
+import { A_CommonHelper, A_Context, A_Entity, A_Scope } from "@adaas/a-concept";
+import {
+    A_FrameDynamicStructure_Init,
+    A_FrameDynamicStructure_Serialized,
+    A_FrameDynamicStructureDefinition,
+    A_FrameComponentMapResult,
+} from "./A-FrameDynamicStructure.types";
 import { A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
-import { A_FrameDynamicPatch } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.entity";
+import { A_FrameDynamicStructureOperation } from "./A-FrameDynamicStructureOperation.context";
 import { A_FrameDynamicStructureError } from "./A-FrameDynamicStructure.error";
-
+import { A_FrameDynamicPatch } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.entity";
+import { A_FRAME_MODELS } from "../A-FrameModels/A-FrameModels.constants";
+import { A_FrameComponentMapIndex } from "./A-FrameComponentMapIndex.context";
 
 
 export class A_FrameDynamicStructure extends A_Entity<A_FrameDynamicStructure_Init, A_FrameDynamicStructure_Serialized> {
-    
+
     static get concept(): string {
         return 'a-frame';
     }
 
-    // ── Identity ────────────────────────────────────────────────────────────────
+    // ── Identity ─────────────────────────────────────────────────────────────
     prompt!: string;
     createdAt!: number;
 
-    // ── Config ──────────────────────────────────────────────────────────────────
+    // ── Config ───────────────────────────────────────────────────────────────
     private model!: string;
-    private context!: string;
-    private metaHint!: string;
-    private includeBases!: string[];
-    private excludeBases!: string[];
-    private enabledComponents!: string[];
-    // ── State ───────────────────────────────────────────────────────────────────
-    private _components!: A_FrameDynamicStructureResolvedComponent[]
-    private _history!: A_FrameDynamicPatch[]
-    private _version = 0;
-
-    private listeners!: Map<string, Set<A_FrameDynamicStructureListener>>;
+    private _context!: string;
+    private _metaHint!: string;
+    private _includeBases!: string[];
+    private _excludeBases!: string[];
+    private _enabledComponents!: string[];
+    private _minScore!: number;
+    private _maxRetries!: number;
+    private _candidateCount!: number;
+
+    // ── State ─────────────────────────────────────────────────────────────────
+    private _definition!: A_FrameDynamicStructureDefinition | null;
+    private _mapResult!: A_FrameComponentMapResult | null;
+    private _history!: A_FrameDynamicPatch[];
+    private _version!: number;
 
     fromNew(options: A_FrameDynamicStructure_Init) {
-        this.createdAt = Date.now();
+        super.fromNew(options);
 
-        this._components = [];
+        this.createdAt = Date.now();
+        this.prompt = options.prompt;
+        this.model = options.options?.model || A_FRAME_MODELS.PULSAR;
+        this._context = options.options?.context ?? '';
+        this._metaHint = options.options?.metaHint ?? '';
+        this._includeBases = (options.options?.includeBases || [])
+            .map(b => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+        this._excludeBases = (options.options?.excludeBases || [])
+            .map(b => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+        this._enabledComponents = (options.options?.enabledComponents || [])
+            .map(b => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+
+        this._minScore   = options.options?.minScore   ?? 0.7;
+        this._maxRetries = options.options?.maxRetries ?? 3;
+        this._candidateCount = options.options?.candidateCount ?? 5;
+
+        this._definition = null;
+        this._mapResult  = null;
         this._history = [];
         this._version = 0;
+    }
 
-        this.listeners = new Map();
+    // ── Accessors ─────────────────────────────────────────────────────────────
 
-        this.prompt = options.prompt;
-        this.model = options.model;
-        this.context = options.context ?? 'generic';
-        this.metaHint = options.metaHint ?? '';
-        this.includeBases = (options.includeBases || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
-        this.excludeBases = (options.excludeBases || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
-        this.enabledComponents = (options.enabledComponents || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
-    }
+    /** The AI model name used for generation / patching. */
+    get modelName(): string { return this.model; }
 
-    // ── Public read-only accessors ───────────────────────────────────────────────
+    /** Context hint forwarded to the AI for scoping architecture style. */
+    get contextHint(): string { return this._context; }
 
-    /** The current resolved component list (output of the last generate or patch). */
-    get components(): ReadonlyArray<A_FrameDynamicStructureResolvedComponent> {
-        return this._components;
-    }
+    /** Meta/prop hint forwarded to the AI for component selection. */
+    get metaHintValue(): string { return this._metaHint; }
 
-    /** Immutable patch history. */
-    get history(): ReadonlyArray<A_FrameDynamicPatch> {
-        return this._history;
-    }
+    /** Base-class allowlist (string names). */
+    get includedBases(): string[] { return this._includeBases; }
 
-    /** Current schema version (increments with each patch). */
-    get version(): number {
-        return this._version;
-    }
+    /** Base-class denylist (string names). */
+    get excludedBases(): string[] { return this._excludeBases; }
+
+    /** Explicit component allowlist (string names). */
+    get enabledComponentsList(): string[] { return this._enabledComponents; }
+
+    /** Minimum cosine-similarity score (0–1) required for a component match. */
+    get minScore(): number { return this._minScore; }
 
+    /** Max server refinement retries per unmatched element. */
+    get maxRetries(): number { return this._maxRetries; }
 
-    // ── Main pipeline ────────────────────────────────────────────────────────────
+    /** Number of top candidates to send to the AI on each retry. */
+    get candidateCount(): number { return this._candidateCount; }
+
+    /** Current architecture definition as a raw object, or null before first generate(). */
+    get definition(): A_FrameDynamicStructureDefinition | null { return this._definition; }
 
     /**
-     * Run the full generation pipeline:
-     *   content generation → structure mapping → encode → patch
-     *
-     * @returns The resolved component list.
+     * Current architecture definition serialised to a formatted JSON string,
+     * with server embeddings stripped for readability.
+     * Returns an empty-definition JSON before generate() is called.
      */
-    async generate(): Promise<void> {
-        // const context = new A_FrameDynamicStructureOperation();
+    get structure(): string {
+        if (!this._definition) {
+            return JSON.stringify({ containers: [], components: [], fragments: [], entities: [] }, null, 2);
+        }
+        return JSON.stringify(this._stripEmbeddings(this._definition), null, 2);
+    }
 
-        // const executionScope = new A_Scope({
-        //     name: 'a-frame-dynamic-structure-generate',
-        //     fragments: [context],
-        // })
-        //     .inherit(A_Context.scope(this));
+    /** Component-mapping result produced by map(), or null before map() is called. */
+    get mapResult(): A_FrameComponentMapResult | null { return this._mapResult; }
 
-        // try {
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch> { return this._history; }
 
-        //     await this.call(A_FrameDynamicStructureFeatures.Generate, executionScope);
+    /** Current definition version (increments with each patch). */
+    get version(): number { return this._version; }
 
-        //     executionScope.destroy();
+    // ── Main pipeline ─────────────────────────────────────────────────────────
 
-        //     return context;
+    /**
+     * Generate the architecture definition from the entity's prompt.
+     * Calls the server's /api/v1/structure/generate endpoint via the A_FrameChannel feature.
+     */
+    async generate(): Promise<void> {
+        const operation = new A_FrameDynamicStructureOperation();
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-structure-generate',
+            fragments: [operation],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicStructureFeatures.Generate, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicStructureError({
+                title: A_FrameDynamicStructureError.GenerationFailed,
+                description: `Failed to generate structure: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
 
-        // } catch (err) {
-        //     executionScope.destroy();
-        //     throw new A_FrameDynamicStructureError({
-        //         title: A_FrameDynamicStructureError.GenerationFailed,
-        //         description: `Failed to generate structure: ${err instanceof Error ? err.message : String(err)}`,
-        //     });
-        // }
+    /**
+     * Apply a natural-language patch instruction to the current definition.
+     * Calls the server's /api/v1/structure/patch endpoint via the A_FrameChannel feature.
+     */
+    async patch(instruction: string): Promise<void> {
+        const operation = new A_FrameDynamicStructureOperation({ instruction });
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-structure-patch',
+            fragments: [operation],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicStructureFeatures.Patch, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicStructureError({
+                title: A_FrameDynamicStructureError.GenerationFailed,
+                description: `Failed to patch structure: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
     }
 
+    /**
+     * Match every element in the current definition against the local A_FrameIndex.
+     * Retries unmatched elements via server-side refinement patches.
+     *
+     * Results are stored separately from the raw definition and are available
+     * via `mapResult` after this call completes.
+     */
+    async map(): Promise<void> {
+        const mapIndex = new A_FrameComponentMapIndex();
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-structure-map',
+            fragments: [mapIndex],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicStructureFeatures.Map, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicStructureError({
+                title: A_FrameDynamicStructureError.GenerationFailed,
+                description: `Failed to map structure: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
 
-    async patch(prompt: string): Promise<void> {
-        this._version++;
+    // ── Hydration ─────────────────────────────────────────────────────────────
 
+    /**
+     * Populate the definition from a server generate response.
+     * Creates the first history entry.
+     */
+    hydrateFromGeneration(
+        definition: A_FrameDynamicStructureDefinition,
+        meta: { model: string; serverVersion: string },
+    ): void {
+        this._definition = definition;
+        this._mapResult  = null;
+        this._history.push(new A_FrameDynamicPatch({
+            version:   this._version,
+            timestamp: Date.now(),
+            reason:    `Generated for: "${this.prompt}"`,
+            encoded:   Buffer.from(JSON.stringify(this._stripEmbeddings(definition))).toString('base64'),
+            delta:     this._countElements(definition),
+        }));
     }
 
     /**
-     * Restore the component list to a specific version from history.
-     * Creates a new patch entry so the revert itself is tracked.
+     * Replace the current definition with a patched version from the server.
+     * Increments the version and records a history entry.
      */
-    revertTo(version: number): this {
-        // this._currentVersion = version;
+    hydrateFromPatch(
+        definition: A_FrameDynamicStructureDefinition,
+        patchSummary: string,
+        meta: { model: string; serverVersion: string },
+    ): void {
+        const prevCount = this._definition ? this._countElements(this._definition) : 0;
+        this._definition = definition;
+        this._mapResult  = null;   // previous map result is now stale
+        this._version++;
+
+        this._history.push(new A_FrameDynamicPatch({
+            version:   this._version,
+            timestamp: Date.now(),
+            reason:    patchSummary,
+            encoded:   Buffer.from(JSON.stringify(this._stripEmbeddings(definition))).toString('base64'),
+            delta:     this._countElements(definition) - prevCount,
+        }));
+    }
 
-        return this;
+    /**
+     * Store the component-mapping result produced by `A_FrameComponentMapper`.
+     * Called by the mapper after it finishes matching all elements.
+     */
+    hydrateFromMap(result: A_FrameComponentMapResult): void {
+        this._mapResult = result;
     }
 
-    // ── Serialisation ─────────────────────────────────────────────────────────────
-
-    // /**
-    //  * Encode the complete DynamicStructure state to an opaque base64 string.
-    //  * Suitable for storage, transport, or embedding in another system.
-    //  */
-    // serialize(): string {
-    //     const payload: SerializedDynamicStructure = {
-    //         id: this.id,
-    //         version: this._version,
-    //         prompt: this.prompt,
-    //         components: [...this._components],
-    //         history: this._history.map(({ version, timestamp, reason }) => ({
-    //             version,
-    //             timestamp,
-    //             reason,
-    //         })),
-    //     };
-    //     return encode(payload);
-    // }
-
-    // /**
-    //  * Decode a serialised string back to its raw payload.
-    //  * Note: this is a static factory that returns the data only —
-    //  * it does not reconstruct a live DynamicStructure instance.
-    //  *
-    //  * To reconstruct a live instance, create a new DynamicStructure and
-    //  * call .patch() with the decoded components.
-    //  */
-    // static deserialize(encoded: string): SerializedDynamicStructure {
-    //     return decode<SerializedDynamicStructure>(encoded);
-    // }
+    // ── Serialisation ─────────────────────────────────────────────────────────
 
     toJSON(): A_FrameDynamicStructure_Serialized {
+        const elementCount = this._definition ? this._countElements(this._definition) : 0;
         return {
             ...super.toJSON(),
             name: this.prompt,
-            description: `DynamicStructure with ${this._components.length} components and ${this._history.length} patches`,
+            description: `DynamicStructure with ${elementCount} elements and ${this._history.length} patches`,
             metadata: {
-                model: this.model,
-                context: this.context,
-                metaHint: this.metaHint,
-                includeBases: this.includeBases,
-                excludeBases: this.excludeBases,
-                enabledComponents: this.enabledComponents,
-                createdAt: this.createdAt,
+                model:             this.model,
+                context:           this._context,
+                metaHint:          this._metaHint,
+                includeBases:      this._includeBases,
+                excludeBases:      this._excludeBases,
+                enabledComponents: this._enabledComponents,
+                candidateCount:    this._candidateCount,
+                createdAt:         this.createdAt,
             },
-            history: this._history.map(item => item.toJSON()),
-        }
+            history: this._history.map(p => p.toJSON()),
+        };
     }
 
-    // ── Internals ──────────────────────────────────────────────────────────────
-    subscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void {
-        if (!this.listeners.has(feature)) {
-            this.listeners.set(feature, new Set());
-        }
-        this.listeners.get(feature)!.add(listener);
-    }
+    // ── Private helpers ───────────────────────────────────────────────────────
 
-    unsubscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void {
-        this.listeners.get(feature)?.delete(listener);
+    private _countElements(def: A_FrameDynamicStructureDefinition): number {
+        return (def.containers?.length ?? 0)
+             + (def.components?.length ?? 0)
+             + (def.fragments?.length  ?? 0)
+             + (def.entities?.length   ?? 0);
     }
 
-
-    emit(stage: A_FrameDynamicStructureEventNames, context: any): void {
-        this.listeners.get(stage)?.forEach(listener => listener(context));
+    /** Return a copy of the definition with all `embedding` arrays removed. */
+    private _stripEmbeddings(def: A_FrameDynamicStructureDefinition): A_FrameDynamicStructureDefinition {
+        const strip = (el: any): any => {
+            const { embedding, ...rest } = el;
+            return rest;
+        };
+        return {
+            containers: def.containers.map(c => ({
+                ...strip(c),
+                components: (c.components ?? []).map(strip),
+                fragments:  (c.fragments  ?? []).map(strip),
+                entities:   (c.entities   ?? []).map(strip),
+            })),
+            components: def.components.map(strip),
+            fragments:  def.fragments.map(strip),
+            entities:   def.entities.map(strip),
+        };
     }
-
-}
+}