@adaas/a-frame 0.0.21 → 0.0.23

package/src/lib/A-FrameChannel/A-FrameChannel.component.ts

@@ -0,0 +1,273 @@
+import { A_Caller, A_Component, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import { IA_Frame_Channel, A_Frame_EmbedResponse, A_Frame_GenerateResponse, A_Frame_CredentialResponse } from "./A-FrameChannel.types";
+import { A_FrameEnv } from "../A-FrameEnv/A-FrameEnv.fragment.env-node";
+import { A_FrameFeatures } from "./A-FrameChannel.constants";
+import { A_FrameChannelRequest } from "./A-FrameChannelRequest.context";
+import { A_FrameChannelError } from "./A-FrameChannel.error";
+import { A_FrameDefinition } from "../A-FrameDefinition";
+import { A_FrameDefinitionFeatures } from "../A-FrameDefinition/A-FrameDefinition.constants";
+import { A_FrameNamespaceFeatures } from "../A-FrameNamespace/A-FrameNamespace.constants";
+import { A_FrameNamespace } from "../A-FrameNamespace";
+import { A_FrameDynamicStructure } from "../A-FrameDynamicStructure/A-FrameDynamicStructure.entity";
+import { A_FrameDynamicSession } from "../A-FrameDynamicSession/A-FrameDynamicSession.entity";
+import { A_FrameDynamicStructureOperation } from "../A-FrameDynamicStructure/A-FrameDynamicStructureOperation.context";
+import { A_FrameChannelSocket } from "./A-FrameChannelSocket.entity";
+
+/**
+ * A_FrameChannel — Node.js environment
+ *
+ * HTTP client for the embed-server API.
+ * Configuration is resolved from process.env via A_FrameEnv injected at
+ * feature execution time — no state is stored on the component itself.
+ *
+ * Uses the global fetch (available in Node 18+; no extra dependency needed).
+ */
+export class A_FrameChannel extends A_Component implements IA_Frame_Channel {
+
+    async generate(prompt: string): Promise<A_FrameChannelRequest<A_Frame_GenerateResponse>> {
+        const request = new A_FrameChannelRequest<A_Frame_GenerateResponse>('POST', '/api/completions', { prompt, max_tokens: 512 });
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.generate',
+            fragments: [request],
+        })
+            .inherit(A_Context.scope(this));
+
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope);
+            executionScope.destroy();
+
+            return request;
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameChannelError({
+                title: A_FrameChannelError.RequestFailed,
+                description: `Failed to generate completion: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    async embed(input: string | string[]): Promise<A_FrameChannelRequest<A_Frame_EmbedResponse>> {
+        const request = new A_FrameChannelRequest<A_Frame_EmbedResponse>('POST', '/api/embeddings', { input });
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.embed',
+            fragments: [request],
+        })
+            .inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope);
+            executionScope.destroy();
+
+            return request;
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameChannelError({
+                title: A_FrameChannelError.RequestFailed,
+                description: `Failed to embed input: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    async getCredentials(): Promise<A_FrameChannelRequest<A_Frame_CredentialResponse>> {
+        const request = new A_FrameChannelRequest<A_Frame_CredentialResponse>('GET', '/api/credentials/me');
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.getCredentials',
+            fragments: [request],
+        })
+            .inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope);
+            executionScope.destroy();
+
+            return request;
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameChannelError({
+                title: A_FrameChannelError.RequestFailed,
+                description: `Failed to get credentials: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    async ping(): Promise<A_FrameChannelRequest<boolean>> {
+        const request = new A_FrameChannelRequest<boolean>('GET', '/health');
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.ping',
+            fragments: [request],
+        })
+            .inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope);
+            executionScope.destroy();
+
+            return request;
+
+        } catch {
+            executionScope.destroy();
+
+            return request;
+        }
+    }
+
+
+
+    // ─── Feature implementation ───────────────────────────────────────────────
+    @A_Feature.Extend({
+        name: A_FrameDefinitionFeatures.Embed,
+        scope: [A_FrameDefinition],
+    })
+    async embedDefinition(
+        @A_Inject(A_Caller) definition: A_FrameDefinition,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+    ) {
+        const request = new A_FrameChannelRequest<A_Frame_EmbedResponse>('POST', '/api/v1/definition/embed', {
+            definition: definition.toJSON(),
+        });
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.embedDefinition',
+            fragments: [request]
+        })
+            .inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope) as A_Frame_EmbedResponse;
+            executionScope.destroy();
+
+            const response = request.response!;
+            if (!response.data || !response.data[0] || !response.data[0].embedding) {
+                throw new A_FrameChannelError({
+                    title: A_FrameChannelError.InvalidRequest,
+                    description: `Invalid embedding response for definition "${definition.name}"`,
+                });
+            }
+
+            const vector = new Float32Array(response.data[0].embedding);
+
+            definition.hydrateFromEmbedding(vector, {
+                model: response.model,
+                dimensions: response.meta.dimensions,
+                inputCount: response.meta.input_count,
+                aFrameServerVersion: response.meta.server_version!,
+                aFrameVersion: env.A_FRAME_VERSION!,
+                credentialId: response.meta.credential_id!,
+                date: response.date,
+            });
+        } catch (err) {
+            throw new A_FrameChannelError({
+                title: A_FrameChannelError.RequestFailed,
+                description: `Failed to embed definition "${definition.name}": ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+
+    }
+
+
+
+    @A_Feature.Extend({
+        name: A_FrameNamespaceFeatures.Embed,
+        scope: [A_FrameNamespace],
+    })
+    async embedNamespace(
+        @A_Inject(A_Caller) namespace: A_FrameNamespace,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+    ) {
+
+        const request = new A_FrameChannelRequest<A_Frame_EmbedResponse>('POST', '/api/v1/namespace/embed', {
+            namespace: namespace.toJSON(),
+        });
+
+        const executionScope = new A_Scope({
+            name: 'A_FrameChannel.embedNamespace',
+            fragments: [request]
+        })
+            .inherit(A_Context.scope(this));
+
+
+        try {
+            await this.call(A_FrameFeatures.Request, executionScope) as A_Frame_EmbedResponse;
+            executionScope.destroy();
+
+            const response = request.response!;
+            if (!response.data || !response.data[0] || !response.data[0].embedding) {
+                throw new A_FrameChannelError({
+                    title: A_FrameChannelError.InvalidRequest,
+                    description: `Invalid embedding response for namespace "${namespace.name}"`,
+                });
+            }
+
+            const vector = new Float32Array(response.data[0].embedding);
+
+            namespace.hydrateFromEmbedding(vector, {
+                model: response.model,
+                dimensions: response.meta.dimensions,
+                inputCount: response.meta.input_count,
+                aFrameServerVersion: response.meta.server_version!,
+                aFrameVersion: env.A_FRAME_VERSION!,
+                credentialId: response.meta.credential_id!,
+                date: response.date,
+            });
+        } catch (err) {
+            throw new A_FrameChannelError({
+                title: A_FrameChannelError.RequestFailed,
+                description: `Failed to embed namespace "${namespace.name}": ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+
+    }
+
+
+
+
+
+
+    async generateDynamicStructure(
+        @A_Inject(A_Caller) structure: A_FrameDynamicStructure,
+        @A_Inject(A_FrameDynamicSession) session: A_FrameDynamicSession,
+        @A_Inject(A_FrameDynamicStructureOperation) operation: A_FrameDynamicStructureOperation,
+    ) {
+
+    }
+
+
+    // /**
+    //  * Open a bidirectional WebSocket connection to the server.
+    //  *
+    //  * The method resolves once the connection is closed (server close frame or
+    //  * transport end).  While it is pending, call `socket.send(event)` to push
+    //  * frames to the server.  Incoming frames are dispatched automatically to
+    //  * any `@A_FrameChannelSocket.onEvent()` handlers registered on `socket`.
+    //  *
+    //  * @param socket - Pre-configured socket entity (optionally a subclass with
+    //  *                 event handlers pre-registered via `@onEvent` decorators).
+    //  */
+    // async connect(socket: A_FrameChannelSocket): Promise<void> {
+    //     const executionScope = new A_Scope({
+    //         name: 'A_FrameChannel.connect',
+    //         entities: [socket],
+    //     }).inherit(A_Context.scope(this));
+
+    //     try {
+    //         await this.call(A_FrameFeatures.Socket, executionScope);
+    //         executionScope.destroy();
+    //     } catch (err) {
+    //         executionScope.destroy();
+    //         throw new A_FrameChannelError({
+    //             title: A_FrameChannelError.RequestFailed,
+    //             description: `WebSocket connection to ${socket.path} failed: ${err instanceof Error ? err.message : String(err)}`,
+    //         });
+    //     }
+    // }
+
+}
+
+
+
+

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

@@ -0,0 +1,39 @@
+
+
+export const A_FrameFeatures = {
+    Request: '_A_FRAME_REQUEST',
+    Socket:  '_A_FRAME_SOCKET',
+} as const;
+
+
+
+export const A_FrameChannelStreamStatuses = {
+    Open: 'open',
+    Closed: 'closed',
+} as const;
+
+
+export const A_FrameChannelStreamFeatures = {
+    open: '_A_FRAME_CHANNEL_STREAM_OPEN',
+    send: '_A_FRAME_CHANNEL_STREAM_SEND',
+    onEvent: '_A_FRAME_CHANNEL_STREAM_ON_EVENT',
+    onError: '_A_FRAME_CHANNEL_STREAM_ON_ERROR',
+    onComplete: '_A_FRAME_CHANNEL_STREAM_ON_COMPLETE',
+    onClose: '_A_FRAME_CHANNEL_STREAM_ON_CLOSE',
+} as const;
+
+
+// ─── WebSocket socket entity constants ───────────────────────────────────────
+
+export const A_FrameChannelSocketStatuses = {
+    Connecting: 'connecting',
+    Open: 'open',
+    Closed: 'closed',
+} as const;
+
+export const A_FrameChannelSocketFeatures = {
+    onEvent:  '_A_FRAME_CHANNEL_SOCKET_ON_EVENT',
+    onError:  '_A_FRAME_CHANNEL_SOCKET_ON_ERROR',
+    onOpen:   '_A_FRAME_CHANNEL_SOCKET_ON_OPEN',
+    onClose:  '_A_FRAME_CHANNEL_SOCKET_ON_CLOSE',
+} as const;

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

@@ -0,0 +1,10 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+
+export class A_FrameChannelError extends A_Error{
+    static readonly InvalidRequest = 'InvalidRequest';
+    static readonly Timeout = 'Timeout';
+    static readonly RequestFailed = 'RequestFailed';
+}
+ 

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

@@ -0,0 +1,143 @@
+import { A_TYPES__Entity_Serialized, A_TYPES__Error_Serialized } from "@adaas/a-concept";
+import { A_FrameChannelRequest } from "./A-FrameChannelRequest.context";
+import {
+    A_FrameChannelStreamStatuses,
+    A_FrameChannelStreamFeatures,
+    A_FrameChannelSocketStatuses,
+    A_FrameChannelSocketFeatures,
+} from "./A-FrameChannel.constants";
+
+export interface A_Frame_EmbedResponse {
+    data: Array<{ embedding: number[]; index: number }>;
+    model: string;
+    /**
+     * Execution backend reported by the server ("local" | "remote" | …) 
+     */
+    backend?: string;
+    /**
+     * ISO timestamp of when the embedding was generated, as reported by the server. Useful for cache validation and staleness checks.
+     */
+    date: string;
+    meta: {
+        dimensions: number;
+        input_count: number;
+        /** Embed-server (a-frame-mcp) package version */
+        server_version: string;
+        /** ID of the credential (API key) used for this request */
+        credential_id: string | null;
+    };
+}
+
+
+export interface A_Frame_GenerateResponse {
+    data: { text: string };
+    model: string;
+    /**
+     * Execution backend reported by the server ("local" | "remote" | …) 
+     */
+    backend?: string;
+    /**
+     * ISO timestamp of when the embedding was generated, as reported by the server. Useful for cache validation and staleness checks.
+     */
+    date: string;
+    meta: {
+        /** Embed-server (a-frame-mcp) package version */
+        server_version: string;
+        /** ID of the credential (API key) used for this request */
+        credential_id: string | null;
+    };
+}
+
+export interface A_Frame_CredentialResponse {
+    /** Unique identifier for the credential */
+    id: string;
+    /** Name of the credential */
+    name: string;
+    /** Optional description of the credential */
+    description: string | null;
+    /** The encryption key in base64 format */
+    encryption_key: string;
+    /** Encryption algorithm used (e.g., "AES-256-GCM") */
+    algorithm: string;
+    /** Encoding format of the encryption key (e.g., "base64") */
+    key_encoding: string;
+    /** Usage instructions for the encryption key */
+    usage_note: string;
+    /** Version of the a-frame-mcp server */
+    server_version: string;
+}
+
+
+// ─── Channel interface ────────────────────────────────────────────────────────
+
+export interface IA_Frame_Channel {
+
+    generate(prompt: string): Promise<A_FrameChannelRequest<A_Frame_GenerateResponse>>;
+
+    /** Embed one or more raw text strings and return the server response */
+    embed(inputs: string | string[]): Promise<A_FrameChannelRequest<A_Frame_EmbedResponse>>;
+
+    /** Fetch credential details (incl. encryption key) for the authenticated API key */
+    getCredentials(): Promise<A_FrameChannelRequest<A_Frame_CredentialResponse>>;
+
+    /** Returns true if the embed server is reachable */
+    ping(): Promise<A_FrameChannelRequest<boolean>>;
+}
+
+
+// ==================================================================================
+// A_Frame ChannelStream entity types
+// ==================================================================================
+export type A_FrameChannelStreamStatusNames = typeof A_FrameChannelStreamStatuses[keyof typeof A_FrameChannelStreamStatuses];
+
+export type A_FrameChannelStreamFeatureNames = typeof A_FrameChannelStreamFeatures[keyof typeof A_FrameChannelStreamFeatures];
+
+export type A_FrameChannelStream_Init<
+    T extends Record<string, any> = Record<string, any>
+> = {
+    method: string;
+    path: string;
+    body?: T;
+}
+
+export type A_FrameChannelStream_Serialized<
+    T extends Record<string, any> = Record<string, any>
+> = {
+
+    method: string;
+    path: string;
+    body?: T;
+
+    initDate: string;
+    status: A_FrameChannelStreamStatusNames;
+    error?: A_TYPES__Error_Serialized;
+
+} & A_TYPES__Entity_Serialized
+
+
+// ==================================================================================
+// A_Frame ChannelSocket entity types
+// ==================================================================================
+export type A_FrameChannelSocketStatusNames = typeof A_FrameChannelSocketStatuses[keyof typeof A_FrameChannelSocketStatuses];
+
+export type A_FrameChannelSocketFeatureNames = typeof A_FrameChannelSocketFeatures[keyof typeof A_FrameChannelSocketFeatures];
+
+export type A_FrameChannelSocket_Init<
+    T extends Record<string, any> = Record<string, any>
+> = {
+    method: string;
+    path: string;
+    /** Optional JSON body sent as the X-A-Frame-Init header during the upgrade request. */
+    body?: T;
+}
+
+export type A_FrameChannelSocket_Serialized<
+    T extends Record<string, any> = Record<string, any>
+> = {
+    method: string;
+    path: string;
+    body?: T;
+    initDate: string;
+    status: A_FrameChannelSocketStatusNames;
+    error?: A_TYPES__Error_Serialized;
+} & A_TYPES__Entity_Serialized

package/src/lib/A-FrameChannel/A-FrameChannelEvent.context.ts

@@ -0,0 +1,28 @@
+import { A_Error, A_Fragment } from "@adaas/a-concept";
+
+
+export class A_FrameChannelEvent<
+    T extends Record<string, any> = any,
+> extends A_Fragment {
+
+    protected _data?: T;
+    protected _eventName!: string;
+
+    constructor(
+        name: string,
+        data?: T
+    ) {
+        super({ name: 'a-frame-channel-event-' + name });
+        this._data = data as T;
+        this._eventName = name;
+    }
+
+    get name(): string {
+        return this._eventName;
+    }
+
+    get data(): T | undefined {
+        return this._data;
+    }
+
+}

package/src/lib/A-FrameChannel/A-FrameChannelRequest.context.ts

@@ -0,0 +1,36 @@
+import { A_Error, A_Fragment } from "@adaas/a-concept";
+
+
+export class A_FrameChannelRequest<
+    _Response = any
+> extends A_Fragment {
+
+    protected _response?: _Response;
+
+    protected _error?: A_Error;
+
+
+    constructor(
+        public method: string,
+        public path: string,
+        public body?: unknown
+    ) {
+        super({ name: 'a-frame-channel-request' });
+    }
+
+    complete(response: _Response): void {
+        this._response = response;
+    }
+
+    fail(error: A_Error): void {
+        this._error = error;
+    }
+
+    get response(): _Response | undefined {
+        return this._response;
+    }
+
+    get error(): A_Error | undefined {
+        return this._error;
+    }
+}