@adaas/a-frame 0.0.23 → 0.1.2

package/dist/node/A-FrameDefinition.entity-BIF0sclD.d.ts

@@ -0,0 +1,370 @@
+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-HDXcLGcS.js';
+import { A_FrameVector } from './vector.js';
+
+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;
+};
+
+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 _requestedModel: string;
+    protected _credentialId: string;
+    protected _aFrameVersion: string;
+    protected _aFrameServerVersion: string;
+    protected _aFrameMeta?: DefinitionExtractedMeta;
+    /**
+     * 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;
+    /**
+     * The model requested for embedding at init time. Defaults to `A_FRAME_MODELS.ANTARES`
+     * if not explicitly overridden. Sent to the server in the embed request.
+     */
+    get requestedModel(): 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;
+    /**
+     * Structural metadata extracted server-side when the definition was embedded.
+     * Includes discovered methods, @A_Inject dependencies, and @A_Feature.Extend names.
+     */
+    get aFrameMeta(): DefinitionExtractedMeta | 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 DefinitionExtractedMeta as D, 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 };