@adaas/a-frame 0.1.1 → 0.1.2

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

@@ -3,6 +3,27 @@ import { A_FrameNamespace } from "../A-FrameNamespace";
 import { A_FrameTargetType } from "../A-Frame/A-Frame.types";
 import { A_FrameDefinition } from "./A-FrameDefinition.entity";
 
+// ─── Server-generated metadata ───────────────────────────────────────────────
+
+/**
+ * Metadata statically extracted server-side from a definition's source code.
+ * Returned by POST /api/v1/definition/embed and stored on the entity so it
+ * can be persisted alongside the embedding vector.
+ */
+export interface DefinitionExtractedMeta {
+    /** Class name found in source (e.g. "PaymentProcessor") */
+    className?: string;
+    /** Public method names (excludes constructor and `_private` conventions) */
+    methods: string[];
+    /** Class names injected via @A_Inject(ClassName) decorators */
+    injectDeps: string[];
+    /** Feature names from @A_Feature.Extend({ name: '...' }) decorators */
+    features: string[];
+    /** Number of embedding chunks the source was split into */
+    chunkCount: number;
+}
+
+
 
 
 
@@ -38,6 +59,12 @@ export type A_FrameDefinition_Init = {
      * 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>,
+    /**
+     * Optional embedding model override (e.g. `A_FRAME_MODELS.ANTARES`). When omitted the
+     * server defaults to the Antares model.  Pass a named model ID to request a specific
+     * backend without hard-coding the physical model name.
+     */
+    model?: string,
 }
 
 export type A_FrameDefinition_Serialized = {
@@ -93,6 +120,10 @@ export type A_FrameDefinition_Serialized = {
      * Version of adaas-a-frame-mcp (embed-server) that produced the vector 
      */
     aFrameServerVersion: string
+    /**
+     * Structural metadata extracted server-side from the definition's source (methods, deps, features).
+     */
+    aFrameMeta?: DefinitionExtractedMeta
 
 } & A_TYPES__Entity_Serialized
 
@@ -105,5 +136,7 @@ export type A_FrameDefinition_EmbeddingMeta = {
     date: string,
     credentialId: string,
     aFrameVersion: string,
-    aFrameServerVersion: string
+    aFrameServerVersion: string,
+    /** Structural metadata extracted server-side from the source code */
+    aFrameMeta?: DefinitionExtractedMeta,
 }

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

@@ -0,0 +1,5 @@
+
+export const A_FrameDynamicContentFeatures = {
+    Generate: '_A_FRAME_DYNAMIC_CONTENT_GENERATE',
+    Patch: '_A_FRAME_DYNAMIC_CONTENT_PATCH',
+} as const;

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

@@ -0,0 +1,348 @@
+import { A_Context, A_Entity, A_Scope } from "@adaas/a-concept";
+import {
+    A_FrameContentPatchResponse,
+    A_FrameDynamicContent_Init,
+    A_FrameDynamicContent_Serialized,
+} from "./A-FrameDynamicContent.types";
+import { A_FrameDynamicContentFeatures } from "./A-FrameDynamicContent.constants";
+import { A_FrameDynamicContentOperation } from "./A-FrameDynamicContentOperation.context";
+import { A_FrameDynamicContentError } from "./A-FrameDynamicContent.error";
+import { A_FrameDynamicPatch } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.entity";
+import { A_FrameDynamicContentIndex } from "./A-FrameDynamicContentIndex.context";
+import { A_FrameSegment } from "../A-FrameSegment";
+import { A_FRAME_MODELS } from "../A-FrameModels/A-FrameModels.constants";
+
+
+export class A_FrameDynamicContent extends A_Entity<A_FrameDynamicContent_Init, A_FrameDynamicContent_Serialized> {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    // ── Identity ─────────────────────────────────────────────────────────────
+    prompt!: string;
+    createdAt!: number;
+
+    // ── Config ───────────────────────────────────────────────────────────────
+    private model!: string;
+    private _system!: string | undefined;
+
+    // ── State ────────────────────────────────────────────────────────────────
+    private _history!: A_FrameDynamicPatch[];
+    private _version!: number;
+    private _patchPieceLimit!: number;
+
+    // ── Initialisation ───────────────────────────────────────────────────────
+
+    /**
+     * The scope of the current Content stores all related data to it 
+     */
+    protected _scope!: A_Scope
+
+    /**
+     * 
+     */
+    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 index(): A_FrameDynamicContentIndex {
+        const index = this.scope.resolve(A_FrameDynamicContentIndex)!;
+        return index;
+    }
+
+    fromNew(options: A_FrameDynamicContent_Init) {
+
+        super.fromNew(options);
+
+        const index = new A_FrameDynamicContentIndex({ name: `${this.aseid.id}` });
+        this.scope.register(index);
+
+        this.createdAt = Date.now();
+
+        this.prompt = options.prompt;
+        this.model = options.options?.model || A_FRAME_MODELS.LYRA;
+        this._system = options.options?.system;
+        this._patchPieceLimit = options.options?.patchPieceLimit || A_FrameDynamicContentIndex.PATCH_PIECE_LIMIT;
+
+        this._history = [];
+        this._version = 0;
+    }
+
+    // ── Accessors ────────────────────────────────────────────────────────────
+
+    /** Ordered list of content pieces (output of the last generate or patch). */
+    get segments(): ReadonlyArray<A_FrameSegment> {
+        return this.index.list();
+    }
+
+    /** Full content reconstructed from all segments in index order. */
+    get content(): string {
+        return this.index.list()
+            .map(s => s.content)
+            .join('\n');
+    }
+
+    /** Alias for `content` — kept for backward compatibility. */
+    get text(): string {
+        return this.content;
+    }
+
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch> {
+        return this._history;
+    }
+
+    /** Current content version (increments with each patch). */
+    get version(): number {
+        return this._version;
+    }
+
+    /** The AI model name to use for generation / patching. */
+    get modelName(): string {
+        return this.model;
+    }
+
+    /** Optional system prompt forwarded to the AI for generation and patching. */
+    get systemPrompt(): string | undefined {
+        return this._system;
+    }
+
+    // ── Main pipeline ─────────────────────────────────────────────────────────
+
+    /**
+     * Generate content from the entity's prompt.
+     * Populates `pieces` and creates the first history entry.
+     */
+    async generate(): Promise<void> {
+        const operation = new A_FrameDynamicContentOperation();
+
+        if (!this.scope.isInheritedFrom(A_Context.scope(this)))
+            this.scope.inherit(A_Context.scope(this));
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-content-generate',
+            fragments: [operation],
+        }).inherit(this.scope);
+
+        try {
+            await this.call(A_FrameDynamicContentFeatures.Generate, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicContentError({
+                title: A_FrameDynamicContentError.GenerationFailed,
+                description: `Failed to generate content: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    /**
+     * Apply a natural-language patch instruction to the current pieces.
+     *
+     * When `targetSegments` is provided the caller pins the exact segments to
+     * patch — no embedding or semantic search is performed.  Every supplied
+     * segment must already belong to this content's index; unknown segments
+     * are rejected with an error.
+     *
+     * When omitted, the server identifies which segments to modify using
+     * semantic search over segment embeddings (original behaviour).
+     */
+    async patch(instruction: string, targetSegments?: A_FrameSegment | A_FrameSegment[]): Promise<void> {
+        if (!this.scope.isInheritedFrom(A_Context.scope(this)))
+            this.scope.inherit(A_Context.scope(this));
+
+        const executionScope = new A_Scope({
+            name: 'a-frame-dynamic-content-patch',
+        }).inherit(this.scope);
+
+        let segments: A_FrameSegment[];
+
+        if (targetSegments !== undefined) {
+            // ── Pinned segments path ──────────────────────────────────────────
+            const pinned = Array.isArray(targetSegments) ? targetSegments : [targetSegments];
+
+            // Validate every pinned segment is part of this content's index
+            const unknown = pinned.filter(s => !this.index.get(s.id as string));
+            if (unknown.length > 0) {
+                executionScope.destroy();
+                throw new A_FrameDynamicContentError({
+                    title: A_FrameDynamicContentError.PatchFailed,
+                    description:
+                        `Segment(s) not found in this content's index: ` +
+                        unknown.map(s => `"${s.id}"`).join(', ') +
+                        `. Only segments that belong to this DynamicContent instance can be targeted.`,
+                });
+            }
+
+            segments = pinned;
+        } else {
+            // ── Semantic search path (original behaviour) ─────────────────────
+            const inputSegment = new A_FrameSegment({
+                content: instruction,
+                options: { task: 'query' },
+            });
+
+            executionScope.register(inputSegment);
+
+            await inputSegment.embed();
+
+            segments = this.index.selectForPatch(inputSegment.vector ?? null, instruction, this._patchPieceLimit);
+        }
+
+        const operation = new A_FrameDynamicContentOperation({
+            instruction,
+            segments,
+        });
+
+        executionScope.register(operation);
+
+        try {
+            await this.call(A_FrameDynamicContentFeatures.Patch, executionScope);
+            executionScope.destroy();
+        } catch (err) {
+            executionScope.destroy();
+            throw new A_FrameDynamicContentError({
+                title: A_FrameDynamicContentError.PatchFailed,
+                description: `Failed to patch content: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+
+    // ── Comparison ────────────────────────────────────────────────────────────
+
+    /**
+     * Returns a cosine similarity score (0–1) between this content and `other`.
+     *
+     * The score is computed from the centroid of each content's embedded
+     * segments — the element-wise mean of all segment vectors.  Two contents
+     * about the same topic should score close to 1; unrelated contents will
+     * score near 0.
+     *
+     * Returns 0 if either content has no embedded segments.
+     *
+     * @example
+     * const cats1 = new A_FrameDynamicContent({ prompt: 'Article about cats' });
+     * const cats2 = new A_FrameDynamicContent({ prompt: 'Article about cats' });
+     * const cars  = new A_FrameDynamicContent({ prompt: 'Article about cars' });
+     * // After generate() on all three:
+     * cats1.compareTo(cats2); // ~0.92 — high
+     * cats1.compareTo(cars);  // ~0.45 — low
+     */
+    compareTo(other: A_FrameDynamicContent): number {
+        const centroidA = this.index.centroid();
+        const centroidB = other.index.centroid();
+        if (!centroidA || !centroidB) return 0;
+        return centroidA.cosineSimilarity(centroidB);
+    }
+
+    // ── Hydration ─────────────────────────────────────────────────────────────
+
+    /**
+     * Populate index from the segments created by the channel after a generate response.
+     * Creates the first history entry.
+     */
+    hydrateFromGeneration(
+        segments: A_FrameSegment[],
+        meta: { model: string; serverVersion: string },
+    ): void {
+
+        segments.forEach(s => this.index.add(s));
+
+        this._history.push(new A_FrameDynamicPatch({
+            version: this._version,
+            timestamp: Date.now(),
+            reason: `Generated for: "${this.prompt}"`,
+            encoded: Buffer.from(JSON.stringify(this.index.list())).toString('base64'),
+            delta: this.index.size,
+        }));
+    }
+
+    /**
+     * Apply a patch diff returned by the server to the current piece list.
+     * Increments the version and records a history entry.
+     */
+    hydrateFromPatch(
+        patchResult: A_FrameContentPatchResponse,
+        meta: { model: string; serverVersion: string },
+    ): void {
+
+        const prevCount = this.index.size;
+
+        // Pre-compute normalized content set for near-duplicate detection.
+        // Normalization: lowercase, strip punctuation, collapse whitespace.
+        const normalize = (s: string): string =>
+            s.toLowerCase().replace(/[^\w\s]/g, '').replace(/\s+/g, ' ').trim();
+
+        const existingNormalized = this.index.list().map(s => normalize(s.content));
+        const isNearDuplicate = (newContent: string): boolean => {
+            const norm = normalize(newContent);
+            if (norm.length < 8) return false; // too short to matter
+            return existingNormalized.some(existing =>
+                existing === norm ||          // exact match
+                existing.includes(norm)       // new text is a strict substring of something existing
+                // Note: do NOT check norm.includes(existing) — that would block  
+                // valid extensions where new content starts with an existing phrase.
+            );
+        };
+
+        for (const op of patchResult.operations) {
+            // Validate action
+            if (!['add', 'replace', 'remove'].includes(op.action)) continue;
+
+            let segment: A_FrameSegment | undefined;
+            if (op.segment) {
+                // Guard: LLM sometimes returns existing (or near-duplicate) content — skip those.
+                const dup = (op.action === 'add' || op.action === 'replace') && isNearDuplicate(op.segment.content);
+                if (dup) continue;
+
+                segment = new A_FrameSegment({ content: op.segment.content, options: { task: 'document' } });
+                if (op.segment.embedding?.length) {
+                    segment.hydrateFromEmbedding(new Float32Array(op.segment.embedding));
+                }
+            }
+
+            // Validate position for 'add' operations — reject composite strings like "before|after|append"
+            if (op.action === 'add') {
+                const validPositions = new Set(['before', 'after', 'append', undefined]);
+                if (!validPositions.has(op.position as any)) {
+                    // Malformed position — treat as append
+                    (op as any).position = 'append';
+                    (op as any).targetId = undefined;
+                }
+            }
+
+            this.index.applyOperation(op, segment);
+        }
+
+        this._version++;
+
+        this._history.push(new A_FrameDynamicPatch({
+            version: this._version,
+            timestamp: Date.now(),
+            reason: patchResult.patchSummary,
+            encoded: Buffer.from(JSON.stringify(this.index.list())).toString('base64'),
+            delta: this.index.size - prevCount,
+        }));
+    }
+
+    // ── Serialisation ──────────────────────────────────────────────────────────
+
+    toJSON(): A_FrameDynamicContent_Serialized {
+        return {
+            ...super.toJSON(),
+            prompt: this.prompt,
+            metadata: {
+                model: this.model,
+                createdAt: this.createdAt,
+            },
+            history: this._history.map(item => item.toJSON()),
+        };
+    }
+
+}
+

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

@@ -0,0 +1,10 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_FrameDynamicContentError extends A_Error {
+
+    static readonly GenerationFailed = 'GenerationFailed';
+    static readonly PatchFailed = 'PatchFailed';
+    static readonly InvalidPatch = 'InvalidPatch';
+    static readonly PieceNotFound = 'PieceNotFound';
+}

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

@@ -0,0 +1,116 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+import { A_FrameDynamicPatch_Serialized } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.types";
+import { A_FrameDynamicContentFeatures } from "./A-FrameDynamicContent.constants";
+
+
+// ── Wire transport types ─────────────────────────────────────────────────────
+
+/**
+ * Lightweight segment representation used over the HTTP wire.
+ * `embedding` is always `number[]` (JSON-serialised), never `Float32Array`.
+ * The channel layer converts this to/from `A_FrameSegment` domain objects.
+ */
+export interface A_FrameContentSegmentWire {
+    /** Text content of the segment */
+    content: string;
+    /** Embedding vector as plain number array */
+    embedding?: number[];
+    /** Name of the model that produced the embedding */
+    model?: string;
+}
+
+// ── Core data types ────────────────────────────────────────────────────────────
+
+/**
+ * A single segment of generated content (legacy wire format, kept for reference).
+ */
+export interface A_FrameContentPiece {
+    /** Stable identifier (UUID) assigned at generation time */
+    id: string;
+    /** Zero-based position in the ordered piece sequence */
+    index: number;
+    /** The actual text content of this piece */
+    text: string;
+    /** Semantic role label (e.g. 'intro', 'section', 'conclusion') */
+    role?: string;
+    /** Embedding vector for semantic patch matching */
+    vector?: number[];
+}
+
+export type A_FrameDynamicContentOptions = {
+    /**
+     * Which AI model to use for content generation and patching.
+     * Defaults to `A_FRAME_MODELS.LYRA` ('adaas-lyra-v1') — the bridge/
+     * classifier model optimised for content-to-structure translation.
+     * Pass any other `A_FRAME_MODELS` constant or a raw model name to override.
+     */
+    model?: string;
+    /**
+     * Optional system prompt forwarded to the AI for both generate and patch calls.
+     * When provided it overrides the server's default system prompt.
+     */
+    system?: string;
+    /**
+     * The maximum number of pieces to include in a patch request. This limits the scope of changes and helps control costs.
+     * The server will select the most relevant pieces based on the instruction and this limit.
+     * If not specified, defaults to A_FrameDynamicContentIndex.PATCH_PIECE_LIMIT.
+     */
+    patchPieceLimit: number;
+}
+
+// ── Init / Serialized ─────────────────────────────────────────────────────────
+
+export type A_FrameDynamicContent_Init = {
+    /** The generation prompt */
+    prompt: string;
+    /**
+     * Optional configuration parameters for generation and patching behavior. This can include model selection, patch piece limits, and other options that influence how the content is generated and modified.
+     */
+    options?: Partial<A_FrameDynamicContentOptions>;
+};
+
+export type A_FrameDynamicContent_Serialized = {
+    prompt: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    history: Array<A_FrameDynamicPatch_Serialized>;
+} & A_TYPES__Entity_Serialized;
+
+// ── Patch operations ──────────────────────────────────────────────────────────
+
+/** How a patch operation positions new or replacement text relative to a target */
+export type A_FrameContentPatchPosition = 'before' | 'after' | 'replace' | 'append';
+
+/** A single patch action returned by the server */
+export interface A_FrameContentPatchOperation {
+    /** 'add' inserts a new segment, 'replace' swaps an existing one, 'remove' deletes it */
+    action: 'add' | 'replace' | 'remove';
+    /** Target segment id (required for replace / remove; optional for add) */
+    targetId?: string;
+    /** Placement relative to target for 'add'; defaults to 'after' */
+    position?: A_FrameContentPatchPosition;
+    /** New segment data (required for add / replace) */
+    segment?: A_FrameContentSegmentWire;
+}
+
+// ── Server response shapes ────────────────────────────────────────────────────
+
+export interface A_FrameContentGenerateResponse {
+    segments: A_FrameContentSegmentWire[];
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
+
+export interface A_FrameContentPatchResponse {
+    patchSummary: string;
+    operations: A_FrameContentPatchOperation[];
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
+
+// ── Feature name union ─────────────────────────────────────────────────────────
+
+export type A_FrameDynamicContentFeatureNames =
+    typeof A_FrameDynamicContentFeatures[keyof typeof A_FrameDynamicContentFeatures];