@adaas/a-frame 0.1.1 → 0.1.2

package/src/lib/A-FrameDynamicContent/A-FrameDynamicContentIndex.context.ts

@@ -0,0 +1,288 @@
+import { A_Fragment } from "@adaas/a-concept";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import { A_FrameContentPatchOperation } from "./A-FrameDynamicContent.types";
+import { A_FrameSegment } from "../A-FrameSegment";
+
+
+export interface A_FrameDynamicContentIndex_SearchResult {
+    segment: A_FrameSegment;
+    score: number;
+}
+
+
+export class A_FrameDynamicContentIndex extends A_Fragment {
+
+    /** Maximum segments forwarded to the server in a single patch request. */
+    static readonly PATCH_PIECE_LIMIT = 5;
+
+    /** Ordered list of segment IDs — defines the canonical reading order. */
+    private _order: string[] = [];
+
+    /** O(1) lookup by id. */
+    private _map: Map<string, A_FrameSegment> = new Map();
+
+    // ── Accessors ─────────────────────────────────────────────────────────────
+
+    get count(): number {
+        return this._order.length;
+    }
+
+    get size(): number {
+        return this._order.length;
+    }
+
+    // ── Basic mutation ────────────────────────────────────────────────────────
+
+    /** Append one or more segments to the end. */
+    add(...segments: A_FrameSegment[]): void {
+        segments.forEach(seg => {
+            this._map.set(seg.id as string, seg);
+            if (!this._order.includes(seg.id as string)) {
+                this._order.push(seg.id as string);
+            }
+        });
+    }
+
+    /** Replace the content of an existing segment in-place (position unchanged). */
+    update(segment: A_FrameSegment): void {
+        this._map.set(segment.id, segment);
+        if (!this._order.includes(segment.id)) {
+            this._order.push(segment.id);
+        }
+    }
+
+    /** Remove a segment by id. */
+    remove(id: string): void {
+        this._map.delete(id);
+        const idx = this._order.indexOf(id);
+        if (idx !== -1) this._order.splice(idx, 1);
+    }
+
+    /** Remove all segments. */
+    clear(): void {
+        this._map.clear();
+        this._order = [];
+    }
+
+    // ── Positional insertion ──────────────────────────────────────────────────
+
+    /** Insert `segment` immediately before the segment with `targetId`. */
+    insertBefore(targetId: string, segment: A_FrameSegment): void {
+        this._map.set(segment.id, segment);
+        const targetIdx = this._order.indexOf(targetId);
+        if (targetIdx === -1) {
+            this._order.push(segment.id);
+        } else {
+            this._order.splice(targetIdx, 0, segment.id);
+        }
+    }
+
+    /** Insert `segment` immediately after the segment with `targetId`. */
+    insertAfter(targetId: string, segment: A_FrameSegment): void {
+        this._map.set(segment.id, segment);
+        const targetIdx = this._order.indexOf(targetId);
+        if (targetIdx === -1) {
+            this._order.push(segment.id);
+        } else {
+            this._order.splice(targetIdx + 1, 0, segment.id);
+        }
+    }
+
+    /** Swap the content of `targetId` with `segment`, keeping the same position. */
+    replace(targetId: string, segment: A_FrameSegment): void {
+        const pos = this._order.indexOf(targetId);
+        if (pos === -1) return;
+        this._map.delete(targetId);
+        this._map.set(segment.id, segment);
+        this._order[pos] = segment.id;
+    }
+
+    // ── Position management ────────────────────────────────────────────────────
+
+    /** Move the segment with `id` to absolute zero-based `newPosition`. */
+    moveTo(id: string, newPosition: number): void {
+        const from = this._order.indexOf(id);
+        if (from === -1) return;
+        this._order.splice(from, 1);
+        const clipped = Math.max(0, Math.min(newPosition, this._order.length));
+        this._order.splice(clipped, 0, id);
+    }
+
+    /** Move `id` to directly before `targetId`. */
+    moveBefore(id: string, targetId: string): void {
+        const from = this._order.indexOf(id);
+        if (from === -1) return;
+        this._order.splice(from, 1);
+        const to = this._order.indexOf(targetId);
+        this._order.splice(to === -1 ? 0 : to, 0, id);
+    }
+
+    /** Move `id` to directly after `targetId`. */
+    moveAfter(id: string, targetId: string): void {
+        const from = this._order.indexOf(id);
+        if (from === -1) return;
+        this._order.splice(from, 1);
+        const to = this._order.indexOf(targetId);
+        this._order.splice(to === -1 ? this._order.length : to + 1, 0, id);
+    }
+
+    // ── Patch operation dispatch ──────────────────────────────────────────────
+
+    /**
+     * Apply a single `A_FrameContentPatchOperation` to the index.
+     * For `add` and `replace` the caller must supply the resolved `segment`.
+     * For `remove` only the `op` is needed.
+     */
+    applyOperation(op: A_FrameContentPatchOperation, segment?: A_FrameSegment): void {
+        switch (op.action) {
+            case 'remove': {
+                if (op.targetId) this.remove(op.targetId);
+                break;
+            }
+            case 'replace': {
+                if (op.targetId && segment) this.replace(op.targetId, segment);
+                break;
+            }
+            case 'add': {
+                if (!segment) break;
+                if (!op.targetId || op.position === 'append') {
+                    this.add(segment);
+                } else if (op.position === 'before') {
+                    this.insertBefore(op.targetId, segment);
+                } else {
+                    // 'after' is the default
+                    this.insertAfter(op.targetId, segment);
+                }
+                break;
+            }
+        }
+    }
+
+    // ── Lookup ────────────────────────────────────────────────────────────────
+
+    get(id: string): A_FrameSegment | undefined {
+        return this._map.get(id);
+    }
+
+    /** Returns all segments in their current canonical order. */
+    list(): A_FrameSegment[] {
+        return this._order
+            .map(id => this._map.get(id))
+            .filter((s): s is A_FrameSegment => s !== undefined);
+    }
+
+    // ── Search ────────────────────────────────────────────────────────────────
+
+    /**
+     * Computes the centroid (element-wise mean) of all embedded segments.
+     * Returns `null` when no segments have been embedded yet.
+     * The centroid represents the overall semantic "centre of gravity" of this
+     * content block and is used by `A_FrameDynamicContent.compareTo()` to
+     * measure similarity between two content instances.
+     */
+    centroid(): A_FrameVector | null {
+        const embedded = this.list().filter(s => s.isEmbed && s.vector);
+        if (embedded.length === 0) return null;
+
+        const dim = embedded[0].vector!.length;
+        const sum = new Float32Array(dim);
+
+        for (const seg of embedded) {
+            const vals = seg.vector!.values;
+            for (let i = 0; i < dim; i++) sum[i] += vals[i];
+        }
+        for (let i = 0; i < dim; i++) sum[i] /= embedded.length;
+
+        return new A_FrameVector(sum);
+    }
+
+    /**
+     * Rank all embedded segments by cosine similarity to the query vector.
+     */
+    search(
+        vector: A_FrameVector,
+        topK: number = A_FrameDynamicContentIndex.PATCH_PIECE_LIMIT,
+    ): A_FrameDynamicContentIndex_SearchResult[] {
+        const queryVec = vector.normalize();
+
+        return this.list()
+            .filter(s => s.isEmbed && s.vector)
+            .map(s => ({
+                segment: s,
+                score: queryVec.dot(s.vector!.normalize()),
+            }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+
+    /**
+     * Rank segments by how many instruction keywords appear in their content.
+     * Words shorter than 4 characters are ignored.
+     */
+    searchByKeywords(
+        instruction: string,
+        topK: number = A_FrameDynamicContentIndex.PATCH_PIECE_LIMIT,
+    ): A_FrameDynamicContentIndex_SearchResult[] {
+        const keywords = instruction
+            .toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 3);
+
+        if (keywords.length === 0) return [];
+
+        return this.list()
+            .map(segment => {
+                const lower = segment.content.toLowerCase();
+                const score = keywords.reduce(
+                    (acc, kw) => acc + (lower.includes(kw) ? 1 : 0),
+                    0,
+                );
+                return { segment, score };
+            })
+            .filter(s => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+
+    /**
+     * Select at most `limit` segments most relevant to a patch instruction.
+     *
+     * Priority:
+     *   1. Vector search  — when `vector` is provided and segments carry embeddings.
+     *   2. Keyword search — fallback when embeddings are absent or vector is null.
+     *   3. Identity       — first N segments when neither search finds candidates.
+     */
+    selectForPatch(
+        vector: A_FrameVector | null,
+        instruction: string,
+        limit: number = A_FrameDynamicContentIndex.PATCH_PIECE_LIMIT,
+    ): A_FrameSegment[] {
+        const all = this.list();
+        if (all.length <= limit) return all;
+
+        // 1. Vector search
+        if (vector) {
+            const hasEmbedded = all.some(s => s.isEmbed);
+            if (hasEmbedded) {
+                const results = this.search(vector, limit);
+                if (results.length > 0) return results.map(r => r.segment);
+            }
+        }
+
+        // 2. Keyword fallback
+        const kwResults = this.searchByKeywords(instruction, limit);
+        if (kwResults.length > 0) return kwResults.map(r => r.segment);
+
+        // 3. Identity
+        return all.slice(0, limit);
+    }
+
+    // ── Similarity helpers ────────────────────────────────────────────────────
+
+    cosineSimilarity(a: A_FrameVector, b?: A_FrameVector): number {
+        if (!b) return 0;
+        const dot = a.dot(b);
+        const mag = a.magnitude() * b.magnitude();
+        return mag === 0 ? 0 : dot / mag;
+    }
+}

package/src/lib/A-FrameDynamicContent/A-FrameDynamicContentOperation.context.ts

@@ -0,0 +1,26 @@
+import { A_Fragment } from "@adaas/a-concept";
+
+
+export class A_FrameDynamicContentOperation<
+    _InputParams = any,
+> extends A_Fragment {
+
+    protected _meta: Map<string, any> = new Map();
+
+    constructor(params: _InputParams = {} as _InputParams) {
+        super({ name: 'a-frame-dynamic-content-operation-context' });
+        this._meta.set('params', params);
+    }
+
+    get params(): _InputParams {
+        return this._meta.get('params');
+    }
+
+    get(key: string) {
+        return this._meta.get(key);
+    }
+
+    set(key: string, value: any) {
+        this._meta.set(key, value);
+    }
+}

package/src/lib/A-FrameDynamicContent/index.ts

@@ -0,0 +1,5 @@
+export * from './A-FrameDynamicContent.constants';
+export * from './A-FrameDynamicContent.entity';
+export * from './A-FrameDynamicContent.types';
+export * from './A-FrameDynamicContent.error';
+export * from './A-FrameDynamicContentOperation.context';

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

@@ -0,0 +1,6 @@
+
+export const A_FrameDynamicFeatureFeatures = {
+    Generate: '_A_FRAME_DYNAMIC_FEATURE_GENERATE',
+    Patch:    '_A_FRAME_DYNAMIC_FEATURE_PATCH',
+    Map:      '_A_FRAME_DYNAMIC_FEATURE_MAP',
+} as const;

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

@@ -1,6 +1,16 @@
-import { A_Entity } from "@adaas/a-concept";
-import { A_FrameDynamicFeature_Init, A_FrameDynamicFeature_Serialized } from "./A-FrameDynamicFeature.types";
-
+import { A_CommonHelper, A_Context, A_Entity, A_Scope } from "@adaas/a-concept";
+import {
+    A_FrameDynamicFeature_Init,
+    A_FrameDynamicFeature_Serialized,
+    A_FrameDynamicFeatureDefinition,
+    A_FrameDynamicFeatureMapResult,
+} from "./A-FrameDynamicFeature.types";
+import { A_FrameDynamicFeatureFeatures } from "./A-FrameDynamicFeature.constants";
+import { A_FrameDynamicFeatureOperation } from "./A-FrameDynamicFeatureOperation.context";
+import { A_FrameDynamicFeatureError } from "./A-FrameDynamicFeature.error";
+import { A_FrameDynamicPatch } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.entity";
+import { A_FRAME_MODELS } from "../A-FrameModels/A-FrameModels.constants";
+import { A_FrameMethodMapIndex } from "./A-FrameMethodMapIndex.context";
 
 
 export class A_FrameDynamicFeature extends A_Entity<A_FrameDynamicFeature_Init, A_FrameDynamicFeature_Serialized> {
@@ -9,5 +19,244 @@ export class A_FrameDynamicFeature extends A_Entity<A_FrameDynamicFeature_Init,
         return 'a-frame';
     }
 
+    // ── Identity ────────────────────────────────────────────────────────────────
+    prompt!: string;
+    createdAt!: number;
+
+    // ── Config ───────────────────────────────────────────────────────────────
+    private _model!: string;
+    private _context!: string;
+    private _includeBases!: string[];
+    private _excludeBases!: string[];
+    private _enabledComponents!: string[];
+    private _minScore!: number;
+    private _maxRetries!: number;
+
+    // ── State ───────────────────────────────────────────────────────────────────
+    private _definition!: A_FrameDynamicFeatureDefinition | null;
+    private _mapResult!: A_FrameDynamicFeatureMapResult | null;
+    private _history!: A_FrameDynamicPatch[];
+    private _version!: number;
+
+    fromNew(options: A_FrameDynamicFeature_Init) {
+        super.fromNew(options);
+
+        this.createdAt = Date.now();
+        this.prompt    = options.prompt;
+        this._model    = options.options?.model ?? A_FRAME_MODELS.PULSAR;
+        this._context  = options.options?.context ?? '';
+        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._definition = null;
+        this._mapResult  = null;
+        this._history    = [];
+        this._version    = 0;
+    }
+
+    // ── Accessors ───────────────────────────────────────────────────────────────
+
+    get modelName():            string   { return this._model; }
+    get contextHint():          string   { return this._context; }
+    get includedBases():        string[] { return this._includeBases; }
+    get excludedBases():        string[] { return this._excludeBases; }
+    get enabledComponentsList():string[] { return this._enabledComponents; }
+    get minScore():             number   { return this._minScore; }
+    get maxRetries():           number   { return this._maxRetries; }
+
+    /** Current workflow definition, or `null` before first `generate()`. */
+    get definition(): A_FrameDynamicFeatureDefinition | null { return this._definition; }
+
+    /**
+     * Serialised workflow definition (no embedding arrays) — safe to
+     * log or persist.  Returns an empty shell before `generate()` is called.
+     */
+    get workflow(): string {
+        if (!this._definition) {
+            return JSON.stringify({ title: '', description: '', steps: [], components: [], fragments: [], entities: [] }, null, 2);
+        }
+        return JSON.stringify(this._stripEmbeddings(this._definition), null, 2);
+    }
+
+    /** Component-mapping result produced by `map()`, or `null` before that call. */
+    get mapResult(): A_FrameDynamicFeatureMapResult | null { return this._mapResult; }
+
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch> { return this._history; }
+
+    /** Version counter — increments with each `patch()` call. */
+    get version(): number { return this._version; }
+
+    // ── Main pipeline ───────────────────────────────────────────────────────────────
+
+    /**
+     * Generate the workflow definition from the entity's prompt.
+     *
+     * Calls the server's `/api/v1/feature/generate` endpoint.  The server
+     * returns an ordered list of steps (with embeddings), a list of supporting
+     * components/fragments/entities, and a human-readable title + description
+     * of the workflow.
+     *
+     * After this call succeeds, invoke `map()` to match each element to a
+     * registered class/method in the local A_FrameIndex.
+     */
+    async generate(): Promise<void> {
+        const operation = new A_FrameDynamicFeatureOperation();
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-feature-generate',
+            fragments: [operation],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicFeatureFeatures.Generate, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicFeatureError({
+                title: A_FrameDynamicFeatureError.GenerationFailed,
+                description: `Failed to generate feature workflow: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    /**
+     * Apply a natural-language patch instruction to refine the current workflow.
+     *
+     * Calls the server's `/api/v1/feature/patch` endpoint.  Increments the
+     * version and records a history entry.  A previous `map()` result is
+     * invalidated — call `map()` again after patching.
+     */
+    async patch(instruction: string): Promise<void> {
+        const operation = new A_FrameDynamicFeatureOperation({ instruction });
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-feature-patch',
+            fragments: [operation],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicFeatureFeatures.Patch, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicFeatureError({
+                title: A_FrameDynamicFeatureError.PatchFailed,
+                description: `Failed to patch feature workflow: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    /**
+     * Match every step and supporting element in the current workflow definition
+     * against the local A_FrameIndex.
+     *
+     * Steps are matched to registered *methods* (via embedded method-level
+     * definitions indexed with `@A_Frame.Define`).  Supporting components,
+     * fragments, and entities are matched to registered classes.
+     *
+     * Unmatched steps are retried via server-side refinement patches (up to
+     * `maxRetries` times) before being marked with a `matchError`.
+     *
+     * Results are stored in `mapResult` after this call completes.
+     */
+    async map(): Promise<void> {
+        const mapIndex = new A_FrameMethodMapIndex();
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-feature-map',
+            fragments: [mapIndex],
+        }).inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameDynamicFeatureFeatures.Map, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicFeatureError({
+                title: A_FrameDynamicFeatureError.MappingFailed,
+                description: `Failed to map feature workflow: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    // ── Hydration ───────────────────────────────────────────────────────────────
+
+    hydrateFromGeneration(
+        definition: A_FrameDynamicFeatureDefinition,
+        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:     definition.steps.length,
+        }));
+    }
+
+    hydrateFromPatch(
+        definition: A_FrameDynamicFeatureDefinition,
+        patchSummary: string,
+        meta: { model: string; serverVersion: string },
+    ): void {
+        const prevSteps = this._definition?.steps.length ?? 0;
+        this._definition = definition;
+        this._mapResult  = null;
+        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:     definition.steps.length - prevSteps,
+        }));
+    }
+
+    hydrateFromMap(result: A_FrameDynamicFeatureMapResult): void {
+        this._mapResult = result;
+    }
+
+    // ── Serialisation ──────────────────────────────────────────────────────────────
+
+    toJSON(): A_FrameDynamicFeature_Serialized {
+        return {
+            ...super.toJSON(),
+            name: this.prompt,
+            description: `DynamicFeature with ${this._definition?.steps.length ?? 0} steps and ${this._history.length} patches`,
+            metadata: {
+                model:             this._model,
+                context:           this._context,
+                includeBases:      this._includeBases,
+                excludeBases:      this._excludeBases,
+                enabledComponents: this._enabledComponents,
+                createdAt:         this.createdAt,
+            },
+            history: this._history.map(p => p.toJSON()),
+        };
+    }
 
-}
+    // ── Private helpers ──────────────────────────────────────────────────────────────
+
+    private _stripEmbeddings(def: A_FrameDynamicFeatureDefinition): A_FrameDynamicFeatureDefinition {
+        const strip = (el: any): any => {
+            const { embedding, ...rest } = el;
+            return rest;
+        };
+        return {
+            ...def,
+            steps:      def.steps.map(strip),
+            components: def.components.map(strip),
+            fragments:  def.fragments.map(strip),
+            entities:   def.entities.map(strip),
+        };
+    }
+}

package/src/lib/A-FrameDynamicFeature/A-FrameDynamicFeature.error.ts

@@ -0,0 +1,11 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_FrameDynamicFeatureError extends A_Error {
+
+    static readonly GenerationFailed  = 'GenerationFailed';
+    static readonly PatchFailed       = 'PatchFailed';
+    static readonly MappingFailed     = 'MappingFailed';
+    static readonly MethodNotFound    = 'MethodNotFound';
+    static readonly InvalidOperation  = 'InvalidOperation';
+}