@adaas/a-frame 0.0.22 → 0.0.23

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

@@ -0,0 +1,8 @@
+
+
+export const A_FrameDefinitionFeatures = {
+    Load: '_A_FRAME_DEFINITION_LOAD',
+    Save: '_A_FRAME_DEFINITION_SAVE',
+    Embed: '_A_FRAME_DEFINITION_EMBED',
+    Destroy: '_A_FRAME_DEFINITION_DESTROY',
+} as const;

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

@@ -0,0 +1,290 @@
+import { A_Dependency, A_Entity, A_FormatterHelper, A_Scope } from "@adaas/a-concept";
+import {
+    A_FrameDefinition_EmbeddingMeta,
+    A_FrameDefinition_Init,
+    A_FrameDefinition_Serialized,
+} from "./A-FrameDefinition.types";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import { A_FrameNamespace } from "../A-FrameNamespace";
+import { A_FrameHashHelper } from "@adaas/a-frame/helpers/Hash.helper";
+import { A_FrameDefinitionFeatures } from "./A-FrameDefinition.constants";
+import { A_FrameTargetType } from "../A-Frame/A-Frame.types";
+
+export class A_FrameDefinition extends A_Entity<A_FrameDefinition_Init, A_FrameDefinition_Serialized> {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    protected _name!: string;
+    protected _type!: A_FrameTargetType;
+    protected _source!: string;
+    protected _dependency!: string;
+    protected _description?: string;
+    protected _namespace!: A_FrameNamespace;
+    protected _metadata?: Record<string, any>;
+    protected _vector?: A_FrameVector;
+
+
+    /**
+     * Common properties for all definition types (component, entity, container, fragment, method
+     */
+    protected _hash!: string;
+    protected _date?: string;
+    protected _model!: string;
+    protected _credentialId!: string;
+    protected _aFrameVersion!: string;
+    protected _aFrameServerVersion!: string;
+
+    //-----------------------------------------------------------------------------------------------------
+    //---------------------------------------- Primary properties -----------------------------------------
+    //-----------------------------------------------------------------------------------------------------
+    /**
+     * Definition Identifier from ASEID unique name 
+     */
+    get id(): string {
+        return this.aseid.id;
+    }
+    /**
+     * The type of the definition target (component, entity, container, fragment, or method)
+     */
+    get type(): A_FrameTargetType {
+        return this._type;
+    }
+    /**
+     * The name of the defined feature (e.g. "MyComponent", "myMethod", etc.)
+     */
+    get name(): string {
+        return this._name;
+    }
+    /**
+     * Description that explains the purpose of the defined feature, its inputs/outputs, or any other relevant information.
+     */
+    get description(): string | undefined {
+        return this._description;
+    }
+
+    get dependency(): A_Dependency {
+        return new A_Dependency(this._dependency);
+    }
+    /**
+     * The original source code string that implements the defined feature. This is the main content that gets embedded and indexed for search.
+     */
+    get source(): string {
+        return this._source;
+    }
+    /**
+     * The vector embedding representing the definition's source and metadata. This is populated after embedding and is used for similarity search in the index.
+     */
+    get vector(): A_FrameVector | undefined {
+        return this._vector;
+    }
+    /**
+     * Namespace to which this definition belongs. Used for scoping search and organizing definitions. If not specified, defaults to the global namespace.
+     */
+    get namespace(): A_FrameNamespace {
+        return this._namespace;
+    }
+    /**
+     * Additional metadata about the definition, stored as key-value pairs. This can include any relevant information that doesn't fit into the other properties but may be useful for search or organization.
+     */
+    get metadata(): Record<string, any> {
+        return this._metadata || {};
+    }
+    //-----------------------------------------------------------------------------------------------------
+    //----------------------------------- Common State properties -----------------------------------------
+    //-----------------------------------------------------------------------------------------------------
+    /**
+     * A unique hash string computed from the definition's name, source, description, and metadata. This is used to identify identical definitions and avoid duplicates in the index.
+     */
+    get hash(): string {
+        return this._hash;
+    }
+    /**
+     * The timestamp (in milliseconds since epoch) when the definition was embedded. This is used for tracking the freshness of the embedding and can be useful for re-embedding stale definitions.
+     */
+    get date(): string | undefined {
+        return this._date;
+    }
+    /**
+     * The name of the embedding model used to produce the vector. This is important for understanding the characteristics of the embedding and for debugging purposes.
+     */
+    get model(): string {
+        return this._model;
+    }
+    /**
+     * ID of the server credential (API key) used during embedding. This is useful for auditing and debugging embedding operations, especially when multiple credentials are in use.
+     */
+    get credentialId(): string | undefined {
+        return this._credentialId;
+    }
+    /**
+     * Version of @adaas/a-frame that produced this record. This helps track compatibility and understand which version of the library was used to create the definition.
+     */
+    get aFrameVersion(): string | undefined {
+        return this._aFrameVersion;
+    }
+    /**
+     * Version of a-frame-server that produced the vector. This is useful for debugging embedding issues and ensuring compatibility between the library and the embed server.
+     */
+    get aFrameServerVersion(): string | undefined {
+        return this._aFrameServerVersion;
+    }
+    //-----------------------------------------------------------------------------------------------------
+    //--------------------------------------- Computed properties -----------------------------------------
+    //-----------------------------------------------------------------------------------------------------
+    get isEmbed(): boolean {
+        return this._vector !== undefined;
+    }
+    /**
+     * Saves the definition to storage. The actual implementation of saving is handled by the A_FrameDefinitionFeatures.Save feature, which can be implemented by the environment (e.g. browser, Node.js) to persist the definition in a database, file system, or other storage mechanism.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    save(scope?: A_Scope): Promise<void> | void {
+        return this.call(A_FrameDefinitionFeatures.Save, scope);
+    }
+    /**
+     * Deletes the definition from storage. The actual implementation of deletion is handled by the A_FrameDefinitionFeatures.Destroy feature, which can be implemented by the environment to remove the definition from the database, file system, or other storage mechanism.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    destroy(scope?: A_Scope): Promise<void> | void {
+        return this.call(A_FrameDefinitionFeatures.Destroy, scope);
+    }
+    /**
+     * Loads the definition from storage. The actual implementation of loading is handled by the A_FrameDefinitionFeatures.Load feature, which can be implemented by the environment to retrieve the definition from the database, file system, or other storage mechanism and populate the entity's properties accordingly.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    load(scope?: A_Scope): Promise<void> | void {
+        return this.call(A_FrameDefinitionFeatures.Load, scope);
+    }
+    /**
+     * Updates the definition's properties. This can be used to modify the source code, description, metadata, or namespace of the definition. After updating, you may want to call `embed()` again to refresh the embedding based on the new content.
+     * 
+     * @param updates 
+     */
+    update(updates: Partial<Pick<A_FrameDefinition, 'source' | 'description' | 'metadata' | 'namespace'>>): void {
+        if (updates.source) this._source = updates.source;
+        if (updates.description !== undefined) this._description = updates.description;
+        if (updates.metadata !== undefined) this._metadata = updates.metadata;
+        if (updates.namespace !== undefined) this._namespace = updates.namespace;
+    }
+    /**
+     * Generates the embedding for the definition's source and metadata. 
+     * 
+     * @param scope 
+     * @returns 
+     */
+    embed(scope?: A_Scope): Promise<void> | void {
+        return this.call(A_FrameDefinitionFeatures.Embed, scope);
+    }
+
+
+    fromNew(newEntity: A_FrameDefinition_Init): void {
+        this._type = newEntity.type;
+
+        this.aseid = this.generateASEID({
+            id: A_FormatterHelper.toKebabCase(newEntity.dependency + '-' + newEntity.name),
+            scope: 'a-frame',
+        });
+
+        this._name = newEntity.name;
+
+        const hashSource = this._name + '//'
+            + (newEntity.description || '') + '//'
+            + (newEntity.metadata ? JSON.stringify(newEntity.metadata) : '') + '//'
+            + newEntity.source + '//'
+            + 'Namespace: ' + newEntity.namespace.id;
+
+        this._hash = A_FrameHashHelper.fnv1a(hashSource);
+
+        this._source = newEntity.source;
+        this._description = newEntity.description;
+        this._namespace = newEntity.namespace;
+        this._metadata = newEntity.metadata;
+        this._dependency = newEntity.dependency;
+    }
+
+    fromJSON(serialized: A_FrameDefinition_Serialized): void {
+        this._name = serialized.name;
+        this._hash = serialized.hash;
+        this._source = serialized.source || '';
+        this._description = serialized.description;
+        this._metadata = serialized.metadata;
+        this._vector = serialized.embedding ? new A_FrameVector(serialized.embedding) : undefined;
+        this._date = serialized.date;
+        this._model = serialized.model;
+        this._credentialId = serialized.credentialId;
+        this._aFrameVersion = serialized.aFrameVersion;
+        this._aFrameServerVersion = serialized.aFrameServerVersion;
+    }
+
+    toJSON(): A_FrameDefinition_Serialized {
+        return {
+            ...super.toJSON(),
+            hash: this._hash,
+            name: this._name,
+            source: this._source,
+            description: this._description,
+            metadata: this._metadata,
+            namespace: this._namespace.aseid.toString(),
+            embedding: this._vector?.values,
+            date: this._date ?? new Date().toISOString(),
+            model: this._model,
+            credentialId: this._credentialId,
+            aFrameVersion: this._aFrameVersion,
+            aFrameServerVersion: this._aFrameServerVersion,
+        };
+    }
+
+
+    // ─── Embedding hydration ──────────────────────────────────────────────────
+
+    /** Populate the vector from a pre-existing storage record */
+    // hydrateFromRecord(record: A_FrameDefinition_Record): void {
+    //     if (record.hash !== this._hash) {
+    //         throw new Error(
+    //             `A_FrameDefinition.hydrateFromRecord: hash mismatch for "${this._name}" ` +
+    //             `(expected ${this._hash}, got ${record.hash})`
+    //         );
+    //     }
+    //     this._vector = new A_FrameVector(record.embedding);
+    //     this._embeddedAt = record.embeddedAt;
+    //     this._model = record.model;
+    //     this._credentialId = record.credentialId;
+    //     this._aFrameVersion = record.aFrameVersion;
+    //     this._aFrameServerVersion = record.aFrameServerVersion;
+    // }
+
+    /** Populate the vector from a freshly-fetched embedding */
+    hydrateFromEmbedding(embedding: Float32Array, meta?: A_FrameDefinition_EmbeddingMeta): void {
+        this._vector = new A_FrameVector(embedding);
+        this._date = new Date().toISOString();
+        if (meta) {
+            this._model = meta.model;
+            this._credentialId = meta.credentialId ?? undefined;
+            this._aFrameVersion = meta.aFrameVersion;
+            this._aFrameServerVersion = meta.aFrameServerVersion;
+        }
+    }
+
+    // ─── Embedding input ──────────────────────────────────────────────────────
+
+    /**
+     * Build the text string sent to the embedding model.
+     * Concatenates name + description + source so the resulting
+     * vector captures both intent and implementation.
+     */
+    toString(): string {
+        const parts: string[] = [];
+        parts.push(`// ${this._name}`);
+        if (this._description) parts.push(`// ${this._description}`);
+        parts.push(this._source);
+        return parts.join('\n');
+    }
+}

package/src/lib/A-FrameDefinition/A-FrameDefinition.types.ts

@@ -0,0 +1,109 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept"
+import { A_FrameNamespace } from "../A-FrameNamespace";
+import { A_FrameTargetType } from "../A-Frame/A-Frame.types";
+import { A_FrameDefinition } from "./A-FrameDefinition.entity";
+
+
+
+
+
+// ─── Entity init / serialized ─────────────────────────────────────────────────
+
+export type A_FrameDefinition_Init = {
+    /**
+     * Name of the Component/Fragment/Entity or method, provided automatically by the decorator.
+     */
+    name: string,
+    /**
+     * Information where this Definition relates to Container/Component/Fragment/Entity
+     */
+    dependency: string,
+    /**
+     * The Description that explains the purpose and functionality of the defined feature. This should provide enough context for someone to understand what the feature does and when to use it, without needing to read the source code.
+     */
+    description?: string,
+    /**
+     * An optional metadata object that can contain any additional information about the defined feature. This can include things like parameter types for methods, expected props for components, or any other relevant details that don't fit into the description or source fields.
+     */
+    namespace: A_FrameNamespace,
+    /**
+     * The source code or implementation details of the defined feature. For a component, this would be the component's code; for a method, it would be the method's implementation, etc.
+     */
+    source: string,
+    /**
+     * The type of the defined feature, indicating whether it's a component, entity, container, fragment, or method. This is used for categorization and search filtering in the index.
+     */
+    type: A_FrameTargetType,
+    /**
+     * Optional metadata object that can contain any additional information about the defined feature. This can include things like parameter types for methods, expected props for components, or any other relevant details that don't fit into the description or source fields.
+     */
+    metadata?: Record<string, any>,
+}
+
+export type A_FrameDefinition_Serialized = {
+    /**
+     * Name of the Component/Fragment/Entity or method, provided automatically by the decorator.
+     */
+    name: string
+    /**
+     * Information where this Definition relates to Container/Component/Fragment/Entity
+     */
+    description?: string
+    /**
+     * Namespace ID or name that this definition belongs to. This is used for grouping related definitions together in the index and can be used as a filter during search.
+     */
+    source?: string
+    /**
+     * A state indicating the last status of embeddings applied
+     */
+    hash: string
+    /**
+     * Type of the definition (component, entity, container, fragment or method)
+     */
+    type: A_FrameTargetType,
+    /**
+     * Optional metadata object that can contain any additional information about the defined feature. This can include things like parameter types for methods, expected props for components, or any other relevant details that don't fit into the description or source fields.
+     */
+    metadata?: Record<string, unknown>
+    /**
+     * Namespace ID or name that this definition belongs to. This is used for grouping related definitions together in the index and can be used as a filter during search.
+     */
+    namespace: string
+    /**
+     * An Float32Array representing the embedding vector for this definition, if it has been generated and stored. This can be used for similarity search and retrieval in the index.
+     */
+    embedding?: Float32Array
+    /**
+     * ISO timestamp string of when the embedding was generated. This can be used for cache invalidation or tracking when the data was last updated.
+     */
+    date: string
+    /** 
+     * Name of the model used in the request 
+     */
+    model: string
+    /** 
+     * ID of the server credential (API key) used during embedding 
+     */
+    credentialId: string
+    /** 
+     * Version of @adaas/a-frame that produced this record 
+     */
+    aFrameVersion: string
+    /** 
+     * Version of adaas-a-frame-mcp (embed-server) that produced the vector 
+     */
+    aFrameServerVersion: string
+
+} & A_TYPES__Entity_Serialized
+
+
+
+export type A_FrameDefinition_EmbeddingMeta = {
+    model: string,
+    dimensions: number,
+    inputCount: number,
+    date: string,
+    credentialId: string,
+    aFrameVersion: string,
+    aFrameServerVersion: string
+}

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

@@ -0,0 +1,3 @@
+export * from './A-FrameDefinition.entity';
+export * from './A-FrameDefinition.constants';
+export * from './A-FrameDefinition.types';

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

@@ -0,0 +1,13 @@
+import { A_Entity } from "@adaas/a-concept";
+import { A_FrameDynamicFeature_Init, A_FrameDynamicFeature_Serialized } from "./A-FrameDynamicFeature.types";
+
+
+
+export class A_FrameDynamicFeature extends A_Entity<A_FrameDynamicFeature_Init, A_FrameDynamicFeature_Serialized> {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+
+}

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

@@ -0,0 +1,10 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept"
+
+
+export type A_FrameDynamicFeature_Init = {
+
+}
+
+export type A_FrameDynamicFeature_Serialized = {
+
+} & A_TYPES__Entity_Serialized

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

@@ -0,0 +1,2 @@
+export * from './A-FrameDynamicFeature.entity';
+export * from './A-FrameDynamicFeature.types';

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

@@ -0,0 +1,38 @@
+import { A_Entity } from "@adaas/a-concept";
+import { A_FrameDynamicPatch_Init, A_FrameDynamicPatch_Serialized } from "./A-FrameDynamicPatch.types";
+
+
+export class A_FrameDynamicPatch extends A_Entity<A_FrameDynamicPatch_Init, A_FrameDynamicPatch_Serialized> {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    version!: number;
+    timestamp!: number;
+    reason!: string;
+    encoded!: string;      // base64-encoded snapshot of components at this version
+    delta!: number;        // component count change vs. previous patch
+
+
+
+    fromNew(options: A_FrameDynamicPatch_Init) {
+        this.version = options.version;
+        this.timestamp = options.timestamp;
+        this.reason = options.reason;
+        this.encoded = options.encoded;
+        this.delta = options.delta;
+    }
+
+
+    toJSON(): A_FrameDynamicPatch_Serialized {
+        return {
+            ...super.toJSON(),
+            version: this.version,
+            timestamp: this.timestamp,
+            reason: this.reason,
+            encoded: this.encoded,
+            delta: this.delta,
+        }
+    }
+}

package/src/lib/A-FrameDynamicPatch/A-FrameDynamicPatch.types.ts

@@ -0,0 +1,20 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+
+
+
+export type A_FrameDynamicPatch_Init = {
+    version: number;
+    timestamp: number;
+    reason: string;
+    encoded: string;      // base64-encoded snapshot of components at this version
+    delta: number;        // component count change vs. previous patch
+}
+
+
+export type A_FrameDynamicPatch_Serialized = {
+    version: number;
+    timestamp: number;
+    reason: string;
+    encoded: string;      // base64-encoded snapshot of components at this version
+    delta: number;        // component count change vs. previous patch
+} & A_TYPES__Entity_Serialized

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

@@ -0,0 +1,9 @@
+
+
+
+export const A_FrameDynamicSessionFeatures = {
+    Init: '_A_FRAME_DYNAMIC_SESSION_INIT',
+    Question: '_A_FRAME_DYNAMIC_SESSION_QUESTION',
+    Answer: '_A_FRAME_DYNAMIC_SESSION_ANSWER',
+    Destroy: '_A_FRAME_DYNAMIC_SESSION_DESTROY',
+} as const;

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

@@ -0,0 +1,91 @@
+import { A_Context, A_Entity, A_Scope } from "@adaas/a-concept"
+import { A_FrameDynamicSession_Init, A_FrameDynamicSession_Serialized } from "./A-FrameDynamicSession.types";
+import { A_FrameDynamicSessionFeatures } from "./A-FrameDynamicSession.constants";
+
+
+export class A_FrameDynamicSession extends A_Entity<A_FrameDynamicSession_Init, A_FrameDynamicSession_Serialized> {
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    /**
+     * 
+     */
+    protected _scope!: A_Scope
+
+    protected _turnsCount!: number;
+    protected _currentTurn!: number;
+    protected _initDate!: string;
+
+    /**
+     * 
+     */
+    get scope(): A_Scope {
+
+        if (!this._scope) {
+            this._scope = A_Context.allocate(this, new A_Scope({ name: `${this.aseid.id}-scope` }));
+        }
+
+        return this._scope;
+    }
+
+    get currentTurn(): number {
+        return this._currentTurn;
+    }
+
+    get initDate(): Date {
+        return new Date(this._initDate);
+    }
+
+
+    static onQuestion() {
+        return;
+    }
+
+    static onAnswer() {
+        return;
+    }
+
+
+    fromNew(newEntity: A_FrameDynamicSession_Init): void {
+        this._turnsCount = newEntity.turnsCount || 5;
+        this._currentTurn = 0;
+        this._initDate = new Date().toISOString();
+
+    }
+
+    fromJSON(serialized: A_FrameDynamicSession_Serialized): void {
+        this._turnsCount = serialized.turnsCount;
+        this._currentTurn = serialized.currentTurn;
+        this._initDate = serialized.initDate;
+    }
+
+
+    async init() {
+        await this.call(A_FrameDynamicSessionFeatures.Init)
+    }
+
+    async destroy(scope?: A_Scope): Promise<void> {
+        await this.call(A_FrameDynamicSessionFeatures.Destroy, scope);
+    }
+
+
+    async question() {
+        this._currentTurn++;
+        await this.call(A_FrameDynamicSessionFeatures.Question);
+    }
+
+    async answer() {
+        await this.call(A_FrameDynamicSessionFeatures.Answer);
+    }
+
+
+    toJSON(): A_FrameDynamicSession_Serialized {
+        return {
+            ...super.toJSON(),
+            turnsCount: this._turnsCount,
+            currentTurn: this._currentTurn,
+            initDate: this._initDate,
+        }
+    }
+}

package/src/lib/A-FrameDynamicSession/A-FrameDynamicSession.types.ts

@@ -0,0 +1,18 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+
+
+
+export type A_FrameDynamicSession_Init = {
+
+    turnsCount: number;
+
+}
+
+
+export type A_FrameDynamicSession_Serialized = {
+
+    turnsCount: number;
+    currentTurn: number;
+    initDate: string;
+
+} & A_TYPES__Entity_Serialized

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

@@ -0,0 +1,13 @@
+
+
+
+export const A_FrameDynamicStructureFeatures = {
+    Load: '_A_FRAME_DYNAMIC_STRUCTURE_LOAD',
+    Update: '_A_FRAME_DYNAMIC_STRUCTURE_UPDATE',
+    Generate: '_A_FRAME_DYNAMIC_STRUCTURE_GENERATE',
+} as const;
+
+
+export const A_FrameDynamicStructureEvents = {
+    Updated: '_A_FRAME_DYNAMIC_STRUCTURE_UPDATED',
+} as const;