@adaas/a-frame 0.0.22 → 0.0.23

package/dist/node/A-FrameDefinition.entity-DWGN_Ujr.d.mts

@@ -0,0 +1,329 @@
+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, A_Dependency, A_Scope } from '@adaas/a-concept';
+import { A as A_FrameNamespace } from './A-FrameNamespace.entity-rCm1AavP.mjs';
+import { A_FrameVector } from './vector.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;
+};
+
+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>;
+};
+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;
+} & A_TYPES__Entity_Serialized;
+type A_FrameDefinition_EmbeddingMeta = {
+    model: string;
+    dimensions: number;
+    inputCount: number;
+    date: string;
+    credentialId: string;
+    aFrameVersion: string;
+    aFrameServerVersion: string;
+};
+
+declare class A_FrameDefinition extends A_Entity<A_FrameDefinition_Init, A_FrameDefinition_Serialized> {
+    static get concept(): string;
+    protected _name: string;
+    protected _type: A_FrameTargetType;
+    protected _source: string;
+    protected _dependency: string;
+    protected _description?: string;
+    protected _namespace: A_FrameNamespace;
+    protected _metadata?: Record<string, any>;
+    protected _vector?: A_FrameVector;
+    /**
+     * Common properties for all definition types (component, entity, container, fragment, method
+     */
+    protected _hash: string;
+    protected _date?: string;
+    protected _model: string;
+    protected _credentialId: string;
+    protected _aFrameVersion: string;
+    protected _aFrameServerVersion: string;
+    /**
+     * Definition Identifier from ASEID unique name
+     */
+    get id(): string;
+    /**
+     * The type of the definition target (component, entity, container, fragment, or method)
+     */
+    get type(): A_FrameTargetType;
+    /**
+     * The name of the defined feature (e.g. "MyComponent", "myMethod", etc.)
+     */
+    get name(): string;
+    /**
+     * Description that explains the purpose of the defined feature, its inputs/outputs, or any other relevant information.
+     */
+    get description(): string | undefined;
+    get dependency(): A_Dependency;
+    /**
+     * The original source code string that implements the defined feature. This is the main content that gets embedded and indexed for search.
+     */
+    get source(): string;
+    /**
+     * The vector embedding representing the definition's source and metadata. This is populated after embedding and is used for similarity search in the index.
+     */
+    get vector(): A_FrameVector | undefined;
+    /**
+     * Namespace to which this definition belongs. Used for scoping search and organizing definitions. If not specified, defaults to the global namespace.
+     */
+    get namespace(): A_FrameNamespace;
+    /**
+     * Additional metadata about the definition, stored as key-value pairs. This can include any relevant information that doesn't fit into the other properties but may be useful for search or organization.
+     */
+    get metadata(): Record<string, any>;
+    /**
+     * A unique hash string computed from the definition's name, source, description, and metadata. This is used to identify identical definitions and avoid duplicates in the index.
+     */
+    get hash(): string;
+    /**
+     * The timestamp (in milliseconds since epoch) when the definition was embedded. This is used for tracking the freshness of the embedding and can be useful for re-embedding stale definitions.
+     */
+    get date(): string | undefined;
+    /**
+     * The name of the embedding model used to produce the vector. This is important for understanding the characteristics of the embedding and for debugging purposes.
+     */
+    get model(): string;
+    /**
+     * ID of the server credential (API key) used during embedding. This is useful for auditing and debugging embedding operations, especially when multiple credentials are in use.
+     */
+    get credentialId(): string | undefined;
+    /**
+     * Version of @adaas/a-frame that produced this record. This helps track compatibility and understand which version of the library was used to create the definition.
+     */
+    get aFrameVersion(): string | undefined;
+    /**
+     * Version of a-frame-server that produced the vector. This is useful for debugging embedding issues and ensuring compatibility between the library and the embed server.
+     */
+    get aFrameServerVersion(): string | undefined;
+    get isEmbed(): boolean;
+    /**
+     * Saves the definition to storage. The actual implementation of saving is handled by the A_FrameDefinitionFeatures.Save feature, which can be implemented by the environment (e.g. browser, Node.js) to persist the definition in a database, file system, or other storage mechanism.
+     *
+     * @param scope
+     * @returns
+     */
+    save(scope?: A_Scope): Promise<void> | void;
+    /**
+     * Deletes the definition from storage. The actual implementation of deletion is handled by the A_FrameDefinitionFeatures.Destroy feature, which can be implemented by the environment to remove the definition from the database, file system, or other storage mechanism.
+     *
+     * @param scope
+     * @returns
+     */
+    destroy(scope?: A_Scope): Promise<void> | void;
+    /**
+     * Loads the definition from storage. The actual implementation of loading is handled by the A_FrameDefinitionFeatures.Load feature, which can be implemented by the environment to retrieve the definition from the database, file system, or other storage mechanism and populate the entity's properties accordingly.
+     *
+     * @param scope
+     * @returns
+     */
+    load(scope?: A_Scope): Promise<void> | void;
+    /**
+     * 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_FrameDefinition, 'source' | 'description' | 'metadata' | 'namespace'>>): void;
+    /**
+     * Generates the embedding for the definition's source and metadata.
+     *
+     * @param scope
+     * @returns
+     */
+    embed(scope?: A_Scope): Promise<void> | void;
+    fromNew(newEntity: A_FrameDefinition_Init): void;
+    fromJSON(serialized: A_FrameDefinition_Serialized): void;
+    toJSON(): A_FrameDefinition_Serialized;
+    /** Populate the vector from a pre-existing storage record */
+    /** Populate the vector from a freshly-fetched embedding */
+    hydrateFromEmbedding(embedding: Float32Array, meta?: A_FrameDefinition_EmbeddingMeta): void;
+    /**
+     * Build the text string sent to the embedding model.
+     * Concatenates name + description + source so the resulting
+     * vector captures both intent and implementation.
+     */
+    toString(): string;
+}
+
+export { A_FrameDefinition as A, type A_FrameDefinition_EmbeddingMeta as a, type A_FrameDefinition_Init as b, type A_FrameDefinition_Serialized 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, A_FrameTargetType as o };

package/dist/node/A-FrameDynamicStructure.entity-DaBgSRCR.d.mts

@@ -0,0 +1,188 @@
+import { A_TYPES__Entity_Serialized, A_Fragment, A_TYPES__Ctor, A_Component, A_Container, 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 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>;
+};
+
+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 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;
+    /**
+     * Run the full generation pipeline:
+     *   content generation → structure mapping → encode → patch
+     *
+     * @returns The resolved component list.
+     */
+    generate(): Promise<void>;
+    patch(prompt: string): Promise<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, A_FrameDynamicStructureOperation as k };