@adaas/a-frame 0.1.1 → 0.1.2

package/dist/browser/A-FrameDefinition.types-BT02yAhQ.d.mts

@@ -0,0 +1,232 @@
+import { A_TYPES__Container_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Component_Constructor, A_TYPES__Fragment_Constructor, A_Component, A_Container, A_Entity, A_Fragment, A_TYPES__Entity_Serialized } from '@adaas/a-concept';
+import { A as A_FrameNamespace } from './A-FrameNamespace.entity-BDg1FUgo.mjs';
+
+type A_FrameOptions = {
+    namespace?: string;
+    description?: string;
+};
+type A_FrameDefineOptions<T extends Record<string, any> = Record<string, any>> = {
+    /**
+     * The description of the Method or Class to be indexed. Uses for the better explanation and retrieval strategy
+     */
+    description?: string;
+    /**
+     * Define Namespace to separate and group together related components, entities and containers.
+     *
+     * [!] Namespace is a hard separation between groups.
+     */
+    namespace?: string | A_FrameNamespace;
+    /***
+     * Optional parameters that can be used to store any additional information about the component, entity or container.
+     * This information can be used for the better retrieval strategy or for the better explanation of the component, entity or container.
+     */
+    metadata?: T;
+    /**
+     * Can add a custom way of explaining the component, entity or container, so it can be used in the better retrieval strategy.
+     */
+    examples?: string[];
+};
+type A_FrameMetaTarget = A_TYPES__Container_Constructor | A_TYPES__Entity_Constructor | A_TYPES__Component_Constructor | A_TYPES__Fragment_Constructor;
+/**
+ * Indicates a type of Feature Define decorator
+ */
+type A_FrameDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>;
+/**
+ * Describes a target where Feature Define decorator can be applied
+ *
+ * [!] The feature can be defined on Container, Entity, Component or Command
+ */
+type A_FrameDecoratorTarget = A_FrameMetaTarget | A_Component | A_Container | A_Entity | A_Fragment;
+/**
+ * Targets types that can be indexed
+ */
+declare enum A_FrameTargetType {
+    COMPONENT = "component",
+    ENTITY = "entity",
+    CONTAINER = "container",
+    FRAGMENT = "fragment",
+    METHOD = "method"
+}
+/**
+ * A type of Meta information stored by Index decorator
+ * This information is used by A-Context to build a proper index structure
+ */
+type A_FrameDecoratorMeta = {
+    /**
+     * Component name
+     */
+    name: string;
+    /**
+     * Component description
+     */
+    description?: string;
+    /**
+     * Type of the component
+     */
+    type: A_FrameTargetType;
+    /**
+     * Namespace for the component
+     */
+    namespace?: string | A_FrameNamespace;
+    /**
+     * Constructor reference
+     */
+    constructor: A_FrameDecoratorTarget;
+};
+/**
+ * Indicates a type of Feature Define decorator
+ */
+type A_FrameNamespaceDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => any> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>> | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>;
+/**
+ * Describes a target where Feature Define decorator can be applied
+ *
+ * [!] The feature can be defined on Container, Entity, Component or Command
+ */
+type A_FrameNamespaceDecoratorTarget = A_Container | A_Entity | A_Component | A_Fragment | A_TYPES__Fragment_Constructor | A_TYPES__Component_Constructor | A_TYPES__Container_Constructor | A_TYPES__Entity_Constructor;
+type A_FrameIndexMetaType = {
+    namespaces: string;
+    descriptions: string;
+    type: string;
+    name: string;
+    methods: Map<string, A_FrameIndexMetaMethodMeta>;
+};
+type A_FrameIndexMetaMethodMeta = {
+    name: string;
+    description?: string;
+    methodName: string;
+};
+type A_FrameNamespaceOptions = {
+    /**
+     * Must have UNIQUE name of the Namespace. This is used for the indexing and retrieval strategy. It should be descriptive and concise.
+     */
+    name: string;
+    /**
+     * The description of the Namespace to be indexed. Uses for the better explanation and retrieval strategy
+     */
+    description?: string;
+};
+
+/**
+ * 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.
+ */
+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;
+}
+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>;
+    /**
+     * 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;
+};
+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;
+    /**
+     * Structural metadata extracted server-side from the definition's source (methods, deps, features).
+     */
+    aFrameMeta?: DefinitionExtractedMeta;
+} & A_TYPES__Entity_Serialized;
+type A_FrameDefinition_EmbeddingMeta = {
+    model: string;
+    dimensions: number;
+    inputCount: number;
+    date: string;
+    credentialId: string;
+    aFrameVersion: string;
+    aFrameServerVersion: string;
+    /** Structural metadata extracted server-side from the source code */
+    aFrameMeta?: DefinitionExtractedMeta;
+};
+
+export { type A_FrameDefinition_EmbeddingMeta as A, type DefinitionExtractedMeta as D, type A_FrameDefinition_Init as a, type A_FrameDefinition_Serialized as b, A_FrameTargetType as c, type A_FrameDefineOptions as d, type A_FrameNamespaceOptions as e, type A_FrameDecoratorTarget as f, type A_FrameDecoratorDescriptor as g, type A_FrameDecoratorMeta as h, type A_FrameIndexMetaMethodMeta as i, type A_FrameIndexMetaType as j, type A_FrameMetaTarget as k, type A_FrameNamespaceDecoratorDescriptor as l, type A_FrameNamespaceDecoratorTarget as m, type A_FrameOptions as n };

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

@@ -0,0 +1,297 @@
+import { A_TYPES__Entity_Serialized, A_Entity, A_Fragment, A_Scope } from '@adaas/a-concept';
+import { A_FrameVector } from './vector.mjs';
+import { A as A_FrameSegment } from './A-FrameSegment.entity-D1xjjWvG.mjs';
+
+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;
+}
+
+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.
+     *
+     * 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).
+     */
+    patch(instruction: string, targetSegments?: A_FrameSegment | A_FrameSegment[]): 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, A_FrameDynamicPatch as m, type A_FrameDynamicPatch_Init as n, type A_FrameDynamicPatch_Serialized as o };