@adaas/a-frame 0.0.21 → 0.0.23

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

@@ -0,0 +1,123 @@
+import { A_Component } from "@adaas/a-concept";
+import {
+    A_FrameLogEntry,
+    A_FrameLogLevelType,
+    A_FrameLoggerConfig,
+    A_FrameProgressBar,
+    IA_FrameLogger,
+} from "./A-FrameLogger.types";
+import {
+    A_FRAME_LOG_LEVEL_PRIORITY,
+    A_FRAME_LOG_DEFAULTS,
+} from "./A-FrameLogger.constants";
+
+
+/**
+ * Abstract base for `A_FrameLogger` — environment-agnostic state and behaviour.
+ *
+ * Concrete subclasses (`A-FrameLogger.component.env-node` and
+ * `A-FrameLogger.component.env-browser`) implement `write()` and `progress()`
+ * since each runtime renders to a different surface (TTY vs DevTools console).
+ */
+export abstract class A_FrameLoggerBase extends A_Component implements IA_FrameLogger {
+
+    protected level: A_FrameLogLevelType;
+    protected prefix: string;
+    protected counters: Map<string, number> = new Map();
+    protected startTime: number = Date.now();
+
+    constructor(config: A_FrameLoggerConfig = {}) {
+        super();
+        this.level = config.level ?? 'debug';
+        this.prefix = config.prefix ?? '';
+    }
+
+    // ─── Subclass hooks ──────────────────────────────────────────────────────
+
+    /** Render a fully-built log entry to the runtime-specific output. */
+    protected abstract write(entry: A_FrameLogEntry): void;
+
+    /** Create a runtime-specific progress bar. */
+    abstract progress(label: string, total: number): A_FrameProgressBar;
+
+    // ─── Configuration ───────────────────────────────────────────────────────
+
+    setLevel(level: A_FrameLogLevelType): void {
+        this.level = level;
+    }
+
+    /** Returns true when the entry passes the current level filter. */
+    protected shouldEmit(level: A_FrameLogLevelType): boolean {
+        return A_FRAME_LOG_LEVEL_PRIORITY[level] >= A_FRAME_LOG_LEVEL_PRIORITY[this.level];
+    }
+
+    // ─── Level methods (shared) ──────────────────────────────────────────────
+
+    private emit(level: A_FrameLogLevelType, message: string, metadata?: Record<string, unknown>): void {
+        if (!this.shouldEmit(level)) return;
+        this.write({
+            level,
+            message: this.prefix ? `${this.prefix} ${message}` : message,
+            timestamp: Date.now(),
+            metadata,
+        });
+    }
+
+    debug(msg: string, meta?: Record<string, unknown>): void { this.emit('debug', msg, meta); }
+    info(msg: string, meta?: Record<string, unknown>): void { this.emit('info', msg, meta); }
+    success(msg: string, meta?: Record<string, unknown>): void { this.emit('success', msg, meta); }
+    warn(msg: string, meta?: Record<string, unknown>): void { this.emit('warn', msg, meta); }
+    error(msg: string, meta?: Record<string, unknown>): void { this.emit('error', msg, meta); }
+
+    /** Default implementation that subclasses may override for nicer headings. */
+    section(title: string): void {
+        this.info(`── ${title} ──`);
+    }
+
+    divider(): void {
+        this.info('────────────────────────────────────────────────────────');
+    }
+
+    // ─── Counters / timing ───────────────────────────────────────────────────
+
+    increment(key: string, by = 1): void {
+        this.counters.set(key, (this.counters.get(key) ?? 0) + by);
+    }
+
+    set(key: string, value: number): void {
+        this.counters.set(key, value);
+    }
+
+    get(key: string): number {
+        return this.counters.get(key) ?? 0;
+    }
+
+    resetTimer(): void {
+        this.startTime = Date.now();
+        this.counters.clear();
+    }
+
+    elapsed(): string {
+        const ms = Date.now() - this.startTime;
+        if (ms < 1000) return `${ms}ms`;
+        const s = ms / 1000;
+        if (s < 60) return `${s.toFixed(2)}s`;
+        const m = Math.floor(s / 60);
+        return `${m}m ${(s - m * 60).toFixed(1)}s`;
+    }
+
+    /**
+     * Print a left-aligned table of all counters plus elapsed time.
+     * Concrete subclasses can override for richer rendering.
+     */
+    summary(title: string = A_FRAME_LOG_DEFAULTS.summaryTitle): void {
+        this.section(title);
+        const keys = [...this.counters.keys()];
+        const pad = keys.reduce((m, k) => Math.max(m, k.length), 'elapsed'.length);
+        for (const key of keys) {
+            this.info(`  ${key.padEnd(pad)}  ${this.counters.get(key)}`);
+        }
+        this.info(`  ${'elapsed'.padEnd(pad)}  ${this.elapsed()}`);
+        this.divider();
+    }
+}

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

@@ -0,0 +1,66 @@
+import { A_FrameLogLevelType } from "./A-FrameLogger.types";
+
+
+export const A_FrameLogLevel = {
+    Debug: 'debug',
+    Info: 'info',
+    Success: 'success',
+    Warn: 'warn',
+    Error: 'error',
+} as const satisfies Record<string, A_FrameLogLevelType>;
+
+
+/** Numeric priority used for level filtering. Higher = more severe. */
+export const A_FRAME_LOG_LEVEL_PRIORITY: Record<A_FrameLogLevelType, number> = {
+    debug: 10,
+    info: 20,
+    success: 20,
+    warn: 30,
+    error: 40,
+};
+
+
+/** Glyphs used as the leading symbol for each log level. */
+export const A_FrameLogIcon: Record<A_FrameLogLevelType, string> = {
+    debug: '·',
+    info: 'ℹ',
+    success: '✔',
+    warn: '⚠',
+    error: '✖',
+};
+
+
+/** ANSI escape sequences. Used by the Node implementation only. */
+export const A_FRAME_ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    gray: '\x1b[90m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+} as const;
+
+
+/**
+ * Browser console CSS — used with `console.log('%c...', style)` for coloured
+ * output in DevTools. Mirrors the ANSI palette by intent.
+ */
+export const A_FRAME_BROWSER_CSS: Record<A_FrameLogLevelType, string> = {
+    debug: 'color: #888;',
+    info: 'color: #06b;',
+    success: 'color: #2a7; font-weight: bold;',
+    warn: 'color: #c80;',
+    error: 'color: #c33; font-weight: bold;',
+};
+
+
+/** Defaults applied when building a logger without explicit options. */
+export const A_FRAME_LOG_DEFAULTS = {
+    progressBarWidth: 24,
+    summaryTitle: 'Summary',
+    /** Update progress at most this often (ms) for non-TTY/browser output. */
+    progressThrottleMs: 250,
+} as const;

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

@@ -0,0 +1,67 @@
+/**
+ * Public API surface for A_FrameLogger — shared between node and browser.
+ */
+
+
+export type A_FrameLogLevelType = 'debug' | 'info' | 'success' | 'warn' | 'error';
+
+
+export interface A_FrameLogEntry {
+    level: A_FrameLogLevelType;
+    message: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+
+
+/**
+ * Handle returned by `logger.progress()`. Calling code drives the bar by
+ * `tick()`-ing once per processed item, then `succeed()` or `fail()` at the end.
+ */
+export interface A_FrameProgressBar {
+    /** Advance by one and optionally update the trailing label */
+    tick(label?: string): void;
+    /** Mark the bar complete (even if not all items ticked) */
+    succeed(label?: string): void;
+    /** Mark the bar failed at current position */
+    fail(label?: string): void;
+    /** Set the absolute current value (for non-monotonic progress) */
+    update(current: number, label?: string): void;
+}
+
+
+/**
+ * Constructor / runtime configuration. All fields optional — sensible defaults
+ * are applied so `new A_FrameLogger()` always works.
+ */
+export interface A_FrameLoggerConfig {
+    /** Minimum level to emit. Levels below are silently dropped. Default: 'debug'. */
+    level?: A_FrameLogLevelType;
+    /** Override TTY detection (Node only). Default: auto-detect via process.stdout.isTTY. */
+    color?: boolean;
+    /** Optional prefix prepended to every line, e.g. "[a-frame]" */
+    prefix?: string;
+}
+
+
+export interface IA_FrameLogger {
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    success(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+
+    section(title: string): void;
+    divider(): void;
+
+    progress(label: string, total: number): A_FrameProgressBar;
+
+    increment(key: string, by?: number): void;
+    set(key: string, value: number): void;
+    get(key: string): number;
+
+    resetTimer(): void;
+    elapsed(): string;
+
+    summary(title?: string): void;
+}

package/src/lib/A-FrameLogger/index.browser.ts

@@ -0,0 +1,4 @@
+export { A_FrameLogger } from './A-FrameLogger.component.env-browser';
+export { A_FrameLoggerBase } from './A-FrameLogger.component';
+export * from './A-FrameLogger.constants';
+export * from './A-FrameLogger.types';

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

@@ -0,0 +1,4 @@
+export { A_FrameLogger } from './A-FrameLogger.component.env-node';
+export { A_FrameLoggerBase } from './A-FrameLogger.component';
+export * from './A-FrameLogger.constants';
+export * from './A-FrameLogger.types';

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

@@ -0,0 +1,12 @@
+import { A_FrameNamespace } from "./A-FrameNamespace.entity";
+
+
+export const A_FRAME_DEFAULT_NAMESPACE_KEY = 'default';
+
+
+export const A_FrameNamespaceFeatures = {
+    Load: '_A_FRAME_NAMESPACE_LOAD',
+    Save: '_A_FRAME_NAMESPACE_SAVE',
+    Embed: '_A_FRAME_NAMESPACE_EMBED',
+    Destroy: '_A_FRAME_NAMESPACE_DESTROY',
+} as const;

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

@@ -0,0 +1,211 @@
+import { A_Context, A_Entity, A_FormatterHelper, A_Scope } from "@adaas/a-concept";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import {
+    A_FrameNamespace_Init,
+    A_FrameNamespace_Serialized,
+    A_FrameNamespace_Record,
+    A_FrameNamespace_EmbeddingMeta,
+} from "./A-FrameNamespace.types";
+import { A_FrameHashHelper } from "@adaas/a-frame/helpers/Hash.helper";
+import { A_FrameNamespaceFeatures } from "./A-FrameNamespace.constants";
+
+
+export class A_FrameNamespace extends A_Entity<A_FrameNamespace_Init, A_FrameNamespace_Serialized> {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    protected _name!: string;
+    protected _hash!: string;
+    protected _description?: string;
+    protected _metadata?: Record<string, any>;
+    protected _vector?: A_FrameVector;
+    protected _embeddedAt?: number;
+    // ─── Provenance ───────────────────────────────────────────────────────────
+    protected _embeddingModel?: string;
+    protected _credentialId?: string;
+    protected _aFrameVersion?: string;
+    protected _aFrameServerVersion?: string;
+
+
+    // ─── Getters ──────────────────────────────────────────────────────────────
+
+    get id(): string {
+        return this.aseid.id;
+    }
+
+    get name(): string {
+        return this._name;
+    }
+
+    get hash(): string {
+        return this._hash;
+    }
+
+    get description(): string | undefined {
+        return this._description;
+    }
+
+    get metadata(): Record<string, any> {
+        return this._metadata || {};
+    }
+
+    get vector(): A_FrameVector | undefined {
+        return this._vector;
+    }
+
+    get embedding(): Float32Array | null {
+        return this._vector?.values ?? null;
+    }
+
+    //-----------------------------------------------------------------------------------------------------
+    //--------------------------------------- Computed properties -----------------------------------------
+    //-----------------------------------------------------------------------------------------------------
+    get aFrameServerVersion(): string | undefined {
+        return this._aFrameServerVersion;
+    }
+
+    get aFrameVersion(): string | undefined {
+        return this._aFrameVersion;
+    }
+
+    get isEmbed(): boolean {
+        return this._vector !== undefined;
+    }
+    /**
+      * Saves Namespace to storage. The actual implementation of saving is handled by the A_FrameNamespaceFeatures.Save feature, which can be implemented by the environment to persist the definition to a database, file system, or other storage mechanism.
+      * 
+      * @param scope 
+      * @returns 
+      */
+    save(scope?: A_Scope): Promise<void> | void {
+        console.log(`Saving namespace "${this._name}"...`);
+        return this.call(A_FrameNamespaceFeatures.Save, scope);
+    }
+    /**
+     * Deletes the namespace from storage. The actual implementation of deletion is handled by the A_FrameNamespaceFeatures.Destroy feature, which can be implemented by the environment to remove the namespace from the database, file system, or other storage mechanism.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    destroy(scope?: A_Scope): Promise<void> | void {
+        return this.call(A_FrameNamespaceFeatures.Destroy, scope);
+    }
+    /**
+     * Loads the namespace from storage. The actual implementation of loading is handled by the A_FrameNamespaceFeatures.Load feature, which can be implemented by the environment to retrieve the namespace from the database, file system, or other storage mechanism and populate the entity's properties accordingly.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    async load(scope?: A_Scope): Promise<void> {
+        return this.call(A_FrameNamespaceFeatures.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_FrameNamespace, 'name' | 'description' | 'metadata'>>): void {
+        if (updates.name) this._name = updates.name;
+        if (updates.description !== undefined) this._description = updates.description;
+        if (updates.metadata !== undefined) this._metadata = updates.metadata;
+    }
+    /**
+     * Generates an embedding vector for the namespace using the A_FrameNamespaceFeatures.Embed feature. This typically involves sending the namespace's content (name + description) to an embedding model and storing the resulting vector in the entity. Once embedded, the namespace can be searched using its vector representation.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    embed(scope?: A_Scope): Promise<void> | void {
+        console.log(`Embedding namespace "${this._name}"...`);
+        return this.call(A_FrameNamespaceFeatures.Embed, scope);
+    }
+
+    // ─── A_Entity lifecycle ───────────────────────────────────────────────────
+
+    fromNew(init: A_FrameNamespace_Init): void {
+
+        this.aseid = this.generateASEID({
+            id: A_FormatterHelper.toKebabCase(init.name),
+            scope: 'a-frame',
+        });
+
+        this._name = init.name;
+
+        const hashSource = this._name
+            + (init.description || '')
+            + (init.metadata ? JSON.stringify(init.metadata) : '');
+
+        this._hash = A_FrameHashHelper.fnv1a(hashSource);
+        this._description = init.description;
+        this._metadata = init.metadata;
+    }
+
+    fromJSON(serialized: A_FrameNamespace_Serialized): void {
+        this._name = serialized.name;
+        this._hash = serialized.hash;
+        this._description = serialized.description;
+        this._metadata = serialized.metadata;
+        this._vector = serialized.embedding ? new A_FrameVector(serialized.embedding) : undefined;
+        this._embeddedAt = serialized.embeddedAt;
+        this._embeddingModel = serialized.embeddingModel;
+        this._credentialId = serialized.credentialId;
+        this._aFrameVersion = serialized.aFrameVersion;
+        this._aFrameServerVersion = serialized.aFrameServerVersion;
+    }
+
+
+
+    toJSON(): A_FrameNamespace_Serialized {
+        return {
+            ...super.toJSON(),
+            hash: this._hash,
+            name: this._name,
+            description: this._description,
+            metadata: this._metadata,
+            embedding: this._vector?.values,
+            embeddedAt: this._embeddedAt ?? Date.now(),
+            embeddingModel: this._embeddingModel,
+            credentialId: this._credentialId,
+            aFrameVersion: this._aFrameVersion,
+            aFrameServerVersion: this._aFrameServerVersion,
+        };
+    }
+
+
+    // ─── Embedding hydration ──────────────────────────────────────────────────
+
+    hydrateFromRecord(record: A_FrameNamespace_Record): void {
+        if (record.hash !== this._hash) {
+            throw new Error(
+                `A_FrameNamespace.hydrateFromRecord: hash mismatch for "${this._name}" ` +
+                `(expected ${this._hash}, got ${record.hash})`
+            );
+        }
+        this._vector = new A_FrameVector(record.embedding);
+        this._embeddedAt = record.embeddedAt;
+    }
+
+    hydrateFromEmbedding(embedding: Float32Array, meta?: A_FrameNamespace_EmbeddingMeta): void {
+        this._vector = new A_FrameVector(embedding);
+        this._embeddedAt = Date.now();
+        if (meta) {
+            this._embeddingModel = meta.model;
+            this._credentialId = meta.credentialId ?? undefined;
+            this._aFrameVersion = meta.aFrameVersion;
+            this._aFrameServerVersion = meta.aFrameServerVersion;
+        }
+    }
+
+    /**
+     * Build the text string sent to the embedding model.
+     * Uses name + description so the vector captures semantic intent.
+     */
+    toString(): string {
+        const parts: string[] = [`// namespace: ${this._name}`];
+        if (this._description) parts.push(`// ${this._description}`);
+        return parts.join('\n');
+    }
+}
+

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

@@ -0,0 +1,72 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+
+
+// ─── Entity lifecycle types ───────────────────────────────────────────────────
+
+export type A_FrameNamespace_Init = {
+    /** Unique identifier / slug for the namespace (e.g. "math", "finance/options") */
+    name: string;
+    description?: string;
+    metadata?: Record<string, any>;
+}
+
+export type A_FrameNamespace_Serialized = {
+    hash: string;
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    embedding?: Float32Array;
+    embeddedAt: number;
+    // ─── Provenance ───────────────────────────────────────────────────────────
+    embeddingModel?: string;
+    credentialId?: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+} & A_TYPES__Entity_Serialized
+
+
+// ─── Stored record (written to __namespaces.bin) ─────────────────────────────
+
+export type A_FrameNamespace_Record = {
+    /** SHA-256 hex of the namespace name — acts as stable identity key */
+    hash: string;
+    /** Namespace name / slug */
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    embedding: Float32Array;
+    embeddedAt: number;
+    // ─── Provenance metadata ──────────────────────────────────────────────────
+    /** Name of the embedding model used to produce the vector */
+    embeddingModel?: 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 that produced the vector */
+    aFrameServerVersion?: string;
+}
+
+
+// ─── Embedding hydration metadata ────────────────────────────────────────────
+
+export type A_FrameNamespace_EmbeddingMeta = {
+    model?: string;
+    date: string;
+    dimensions: number;
+    inputCount: number;
+    credentialId?: string | null;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+}
+
+
+// ─── Search result ────────────────────────────────────────────────────────────
+
+export type A_FrameNamespace_SearchResult = {
+    name: string;
+    score: number;
+    hash: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}

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

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