@adaas/a-frame 0.0.23 → 0.1.2

package/dist/browser/A-FrameDynamicContentOperation.context-Dd7Lb7X2.d.mts

@@ -0,0 +1,266 @@
+import { A_TYPES__Entity_Serialized, A_Fragment, A_Entity, A_Scope } from '@adaas/a-concept';
+import { A as A_FrameDynamicPatch_Serialized, a as A_FrameDynamicPatch } from './A-FrameDynamicPatch.entity-BRuF1tqs.mjs';
+import { A_FrameVector } from './vector.mjs';
+import { A as A_FrameSegment } from './A-FrameSegment.entity-D7Aj39Wh.mjs';
+
+declare const A_FrameDynamicContentFeatures: {
+    readonly Generate: "_A_FRAME_DYNAMIC_CONTENT_GENERATE";
+    readonly Patch: "_A_FRAME_DYNAMIC_CONTENT_PATCH";
+};
+
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * A single segment of generated content (legacy wire format, kept for reference).
+ */
+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[];
+}
+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;
+};
+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>;
+};
+type A_FrameDynamicContent_Serialized = {
+    prompt: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    history: Array<A_FrameDynamicPatch_Serialized>;
+} & A_TYPES__Entity_Serialized;
+/** How a patch operation positions new or replacement text relative to a target */
+type A_FrameContentPatchPosition = 'before' | 'after' | 'replace' | 'append';
+/** A single patch action returned by the server */
+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;
+}
+interface A_FrameContentGenerateResponse {
+    segments: A_FrameContentSegmentWire[];
+    model: string;
+    date: string;
+    meta: {
+        server_version: string;
+    };
+}
+interface A_FrameContentPatchResponse {
+    patchSummary: string;
+    operations: A_FrameContentPatchOperation[];
+    model: string;
+    date: string;
+    meta: {
+        server_version: string;
+    };
+}
+type A_FrameDynamicContentFeatureNames = typeof A_FrameDynamicContentFeatures[keyof typeof A_FrameDynamicContentFeatures];
+
+interface A_FrameDynamicContentIndex_SearchResult {
+    segment: A_FrameSegment;
+    score: number;
+}
+declare 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;
+    /** O(1) lookup by id. */
+    private _map;
+    get count(): number;
+    get size(): number;
+    /** Append one or more segments to the end. */
+    add(...segments: A_FrameSegment[]): void;
+    /** Replace the content of an existing segment in-place (position unchanged). */
+    update(segment: A_FrameSegment): void;
+    /** Remove a segment by id. */
+    remove(id: string): void;
+    /** Remove all segments. */
+    clear(): void;
+    /** Insert `segment` immediately before the segment with `targetId`. */
+    insertBefore(targetId: string, segment: A_FrameSegment): void;
+    /** Insert `segment` immediately after the segment with `targetId`. */
+    insertAfter(targetId: string, segment: A_FrameSegment): void;
+    /** Swap the content of `targetId` with `segment`, keeping the same position. */
+    replace(targetId: string, segment: A_FrameSegment): void;
+    /** Move the segment with `id` to absolute zero-based `newPosition`. */
+    moveTo(id: string, newPosition: number): void;
+    /** Move `id` to directly before `targetId`. */
+    moveBefore(id: string, targetId: string): void;
+    /** Move `id` to directly after `targetId`. */
+    moveAfter(id: string, targetId: string): void;
+    /**
+     * 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;
+    get(id: string): A_FrameSegment | undefined;
+    /** Returns all segments in their current canonical order. */
+    list(): A_FrameSegment[];
+    /**
+     * 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;
+    /**
+     * Rank all embedded segments by cosine similarity to the query vector.
+     */
+    search(vector: A_FrameVector, topK?: number): A_FrameDynamicContentIndex_SearchResult[];
+    /**
+     * 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_SearchResult[];
+    /**
+     * 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_FrameSegment[];
+    cosineSimilarity(a: A_FrameVector, b?: A_FrameVector): number;
+}
+
+declare class A_FrameDynamicContent extends A_Entity<A_FrameDynamicContent_Init, A_FrameDynamicContent_Serialized> {
+    static get concept(): string;
+    prompt: string;
+    createdAt: number;
+    private model;
+    private _system;
+    private _history;
+    private _version;
+    private _patchPieceLimit;
+    /**
+     * The scope of the current Content stores all related data to it
+     */
+    protected _scope: A_Scope;
+    /**
+     *
+     */
+    get scope(): A_Scope;
+    get index(): A_FrameDynamicContentIndex;
+    fromNew(options: A_FrameDynamicContent_Init): void;
+    /** Ordered list of content pieces (output of the last generate or patch). */
+    get segments(): ReadonlyArray<A_FrameSegment>;
+    /** Full content reconstructed from all segments in index order. */
+    get content(): string;
+    /** Alias for `content` — kept for backward compatibility. */
+    get text(): string;
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch>;
+    /** Current content version (increments with each patch). */
+    get version(): number;
+    /** The AI model name to use for generation / patching. */
+    get modelName(): string;
+    /** Optional system prompt forwarded to the AI for generation and patching. */
+    get systemPrompt(): string | undefined;
+    /**
+     * Generate content from the entity's prompt.
+     * Populates `pieces` and creates the first history entry.
+     */
+    generate(): Promise<void>;
+    /**
+     * Apply a natural-language patch instruction to the current pieces.
+     * The server identifies which pieces to add, replace, or remove using
+     * semantic search over piece embeddings.
+     */
+    patch(instruction: string): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    toJSON(): A_FrameDynamicContent_Serialized;
+}
+
+declare class A_FrameDynamicContentOperation<_InputParams = any> extends A_Fragment {
+    protected _meta: Map<string, any>;
+    constructor(params?: _InputParams);
+    get params(): _InputParams;
+    get(key: string): any;
+    set(key: string, value: any): void;
+}
+
+export { type A_FrameContentGenerateResponse as A, type A_FrameContentPatchOperation as a, type A_FrameContentPatchPosition as b, type A_FrameContentPatchResponse as c, type A_FrameContentPiece as d, type A_FrameContentSegmentWire as e, A_FrameDynamicContent as f, type A_FrameDynamicContentFeatureNames as g, A_FrameDynamicContentFeatures as h, A_FrameDynamicContentOperation as i, type A_FrameDynamicContentOptions as j, type A_FrameDynamicContent_Init as k, type A_FrameDynamicContent_Serialized as l };

package/dist/browser/A-FrameDynamicPatch.entity-BRuF1tqs.d.mts

@@ -0,0 +1,29 @@
+import { A_TYPES__Entity_Serialized, A_Entity } from '@adaas/a-concept';
+
+type A_FrameDynamicPatch_Init = {
+    version: number;
+    timestamp: number;
+    reason: string;
+    encoded: string;
+    delta: number;
+};
+type A_FrameDynamicPatch_Serialized = {
+    version: number;
+    timestamp: number;
+    reason: string;
+    encoded: string;
+    delta: number;
+} & A_TYPES__Entity_Serialized;
+
+declare class A_FrameDynamicPatch extends A_Entity<A_FrameDynamicPatch_Init, A_FrameDynamicPatch_Serialized> {
+    static get concept(): string;
+    version: number;
+    timestamp: number;
+    reason: string;
+    encoded: string;
+    delta: number;
+    fromNew(options: A_FrameDynamicPatch_Init): void;
+    toJSON(): A_FrameDynamicPatch_Serialized;
+}
+
+export { type A_FrameDynamicPatch_Serialized as A, A_FrameDynamicPatch as a };

package/dist/browser/A-FrameDynamicStructure.entity-DMvI_EPT.d.mts

@@ -0,0 +1,210 @@
+import { A_Fragment, A_TYPES__Ctor, A_Component, A_Container, A_TYPES__Entity_Serialized, A_Entity } from '@adaas/a-concept';
+import { A as A_FrameDynamicPatch_Serialized, a as A_FrameDynamicPatch } from './A-FrameDynamicPatch.entity-BRuF1tqs.mjs';
+
+declare const A_FrameDynamicStructureFeatures: {
+    readonly Load: "_A_FRAME_DYNAMIC_STRUCTURE_LOAD";
+    readonly Update: "_A_FRAME_DYNAMIC_STRUCTURE_UPDATE";
+    readonly Generate: "_A_FRAME_DYNAMIC_STRUCTURE_GENERATE";
+};
+declare const A_FrameDynamicStructureEvents: {
+    readonly Updated: "_A_FRAME_DYNAMIC_STRUCTURE_UPDATED";
+};
+
+declare class A_FrameDynamicStructureOperation<_InputParams = any> extends A_Fragment {
+    protected _meta: Map<string, any>;
+    constructor(params?: _InputParams);
+    get params(): _InputParams;
+    get(key: string): any;
+    set(key: string, value: any): void;
+}
+
+type DynamicStructureDefaultBasesNames = 'A_Component' | 'A_Container' | 'A_Fragment';
+type BaseClassName = DynamicStructureDefaultBasesNames | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>;
+type A_FrameDynamicStructure_Init = {
+    /** The goal / initial prompt driving structure generation */
+    prompt: string;
+    /** Which model to use for content generation */
+    model: string;
+    /** Only include components whose base class is in this list (empty = allow all) */
+    includeBases?: Array<BaseClassName | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+    /** Exclude components whose base class is in this list */
+    excludeBases?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+    /** Explicit list of component names to enable (subset of registry) */
+    enabledComponents?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+    /** Rendering context hint passed to content generator */
+    context?: string;
+    /** Free-form hint about required prop types (forwarded to content generator) */
+    metaHint?: string;
+};
+type A_FrameDynamicStructure_Serialized = {
+    name: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    history: Array<A_FrameDynamicPatch_Serialized>;
+} & A_TYPES__Entity_Serialized;
+type A_FrameDynamicStructureListener = (context: A_FrameDynamicStructureOperation) => void;
+type A_FrameDynamicStructureResolvedComponent<P extends Record<string, any> = Record<string, any>> = {
+    component: string;
+    score: number;
+    meta: P;
+};
+type A_FrameDynamicStructureFeatureNames = typeof A_FrameDynamicStructureFeatures[keyof typeof A_FrameDynamicStructureFeatures];
+type A_FrameDynamicStructureEventNames = typeof A_FrameDynamicStructureEvents[keyof typeof A_FrameDynamicStructureEvents];
+type A_FrameDynamicStructureDefinitionEntity = {
+    /**
+     * The prompt is the text that describes the element (component, container, fragment or entity) that is needed in the structure based on input prompt
+     *
+     *
+     * e.g. "A component that allows to search for something", "A container that runs a web server", "A fragment that stores user settings", "An entity that represents a user session", etc.
+     *
+     * [!] Note, prompt should also contain the name of the element if it's possible, to make it easier to understand and use in the structure generation.
+     */
+    prompt: string;
+    /**
+     * The string set of params that is necessary to the particular element (component, container, fragment or entity) that is needed in the structure based on input prompt.
+     * Those parameters should be presented in the string manner and then mapped to the actual params in the structure generation process, to make it easier to understand and use in the structure generation.
+     *
+     * e.g. "props: {query: string, resultsCount: number}", "constructorParams: {port: number}", "state: {isLoggedIn: boolean}", "ASEID", etc. or simply text: "Stores user with id=12345 and name=John Doe" if it's hard to define the params in a structured way.
+     *
+     * [!] Params are applicable only for stateful components like Fragment, or Entity. Since components are stateless they can only rely on params in their methods received by @A_Inject(SomeFragment) someFragment: SomeFragment, where SomeFragment has state defined by params. And also for containers, since they can have constructor params and also rely on params of their components and fragments.
+     *
+     *
+     */
+    params?: string;
+};
+type A_FrameDynamicStructureDefinition = {
+    /**
+     * A set of containers that the structure is needed based on input prompt
+     *
+     * Where container is an instance of inherited class from A_Container that should be running independently and may have own components, fragments and entities.
+     *
+     * e.g. HTTPServerContainer, WebWorker, AppContainer, etc.
+     *
+     * [!] Note: should be presented only if initial query allows to have a container, and should be included only if necessary.
+     *
+     */
+    containers: Array<A_FrameDynamicStructureDefinitionEntity & {
+        components: Array<A_FrameDynamicStructureDefinitionEntity>;
+        fragments: Array<A_FrameDynamicStructureDefinitionEntity>;
+        entities: Array<A_FrameDynamicStructureDefinitionEntity>;
+    }>;
+    /**
+     * A set of components that the structure is needed based on input prompt
+     *
+     * Where Component is a constructor class from A_Component that allows to define something that is stateless, has methods and features and can be injected as a dependency in other components, fragments or containers.
+     *
+     * e.g. SearchComponent, SettingsComponent, ButtonComponent, SectionComponent, etc.
+     *
+     * [!] Note: should be presented only if initial query allows to have a component, and should be included only if necessary.
+     */
+    components: Array<A_FrameDynamicStructureDefinitionEntity>;
+    /**
+     * A set of Context Fragments that the structure is needed based on input prompt
+     *
+     * Where Fragment is an instance of inherited class from A_Fragment that allows to define something that has state and can be injected as a dependency in other components, fragments or containers.
+     *
+     * e.g.  Settings, State, Store, etc.
+     *
+     * [!] Note: should be presented only if initial query allows to have a fragment, and should be included only if necessary.
+     */
+    fragments: Array<A_FrameDynamicStructureDefinitionEntity>;
+    /**
+     * A set of Entities that the structure is needed based on input prompt
+     *
+     * Where Entity is a A_Entity or a constructor of A_Entity that allows to define something that has ID(ASEID) and can be injected as a dependency in other components, fragments or containers.
+     *
+     * e.g.  Session, User, Conversation, etc.
+     *
+     * [!] Note: should be presented only if initial query allows to have an entity, and should be included only if necessary.
+     */
+    entities: Array<A_FrameDynamicStructureDefinitionEntity>;
+};
+
+/** Guess item as returned by POST /api/v1/structure/generate */
+interface A_FrameStructureGuessItem {
+    sourceText: string;
+    type: string;
+    prompt: string;
+    role: string;
+}
+/** Patch diff as returned by POST /api/v1/structure/patch */
+interface A_FrameStructurePatchResult {
+    patchSummary: string;
+    additions: A_FrameStructureGuessItem[];
+    removals: string[];
+    modifications: Array<{
+        componentId: string;
+        newRole: string;
+        newPrompt: string;
+    }>;
+}
+declare class A_FrameDynamicStructure extends A_Entity<A_FrameDynamicStructure_Init, A_FrameDynamicStructure_Serialized> {
+    static get concept(): string;
+    prompt: string;
+    createdAt: number;
+    private model;
+    private context;
+    private metaHint;
+    private includeBases;
+    private excludeBases;
+    private enabledComponents;
+    private _components;
+    private _history;
+    private _version;
+    private listeners;
+    fromNew(options: A_FrameDynamicStructure_Init): void;
+    /** The current resolved component list (output of the last generate or patch). */
+    get components(): ReadonlyArray<A_FrameDynamicStructureResolvedComponent>;
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch>;
+    /** Current schema version (increments with each patch). */
+    get version(): number;
+    /** The AI model name to use for generation / patching. */
+    get modelName(): string;
+    /**
+     * Run the full generation pipeline:
+     *   content generation → structure mapping → encode → patch
+     *
+     * @returns The resolved component list.
+     */
+    generate(): Promise<void>;
+    patch(prompt: string): Promise<void>;
+    /**
+     * Populate the component list from pre-resolved components produced by an
+     * SSE-driven generate pipeline (where a server and client cooperate to map
+     * AI guesses to actual registered components).
+     *
+     * Creates the first history entry, identical to `hydrateFromGeneration`.
+     */
+    hydrateFromResolved(components: A_FrameDynamicStructureResolvedComponent[], meta: {
+        model: string;
+        serverVersion: string;
+    }): void;
+    /**
+     * Populate the component list from a freshly-received generate response.
+     * Creates the first history entry.
+     */
+    hydrateFromGeneration(guesses: A_FrameStructureGuessItem[], meta: {
+        model: string;
+        serverVersion: string;
+    }): void;
+    /**
+     * Apply an AI-computed patch diff to the current component list.
+     * Increments the version and records a new history entry.
+     */
+    hydrateFromPatch(patchResult: A_FrameStructurePatchResult, meta: {
+        model: string;
+        serverVersion: string;
+    }): void;
+    /**
+     * Restore the component list to a specific version from history.
+     * Creates a new patch entry so the revert itself is tracked.
+     */
+    revertTo(version: number): this;
+    toJSON(): A_FrameDynamicStructure_Serialized;
+    subscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void;
+    unsubscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void;
+    emit(stage: A_FrameDynamicStructureEventNames, context: any): void;
+}
+
+export { A_FrameDynamicStructure as A, type BaseClassName as B, type DynamicStructureDefaultBasesNames as D, type A_FrameDynamicStructureDefinition as a, type A_FrameDynamicStructureDefinitionEntity as b, type A_FrameDynamicStructureEventNames as c, A_FrameDynamicStructureEvents as d, type A_FrameDynamicStructureFeatureNames as e, A_FrameDynamicStructureFeatures as f, type A_FrameDynamicStructureListener as g, type A_FrameDynamicStructureResolvedComponent as h, type A_FrameDynamicStructure_Init as i, type A_FrameDynamicStructure_Serialized as j, type A_FrameStructureGuessItem as k, type A_FrameStructurePatchResult as l, A_FrameDynamicStructureOperation as m };