@adaas/a-frame 0.0.23 → 0.1.2

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

@@ -0,0 +1,235 @@
+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;
+}
+
+/** 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, type A_FrameDynamicPatch_Serialized as m, A_FrameDynamicPatch as n, A_FrameDynamicStructureOperation as o };

package/dist/browser/A-FrameEnv.types-DnK-CYVk.d.mts

@@ -0,0 +1,21 @@
+interface IA_FrameEnv {
+    A_FRAME_TOKEN: string;
+    A_FRAME_SERVER_URL: string;
+    A_FRAME_SERVER_API_KEY: string;
+    A_FRAME_STORAGE_DIR: string;
+    /**
+     * Glob pattern(s) used to discover additional `.aframe` storage directories
+     * at startup.  Multiple patterns can be provided as a comma-separated list.
+     * Definitions and namespaces found in these locations are merged with the
+     * primary storage (read-only merge — writes always go to A_FRAME_STORAGE_DIR).
+     *
+     * Default: `node_modules/**\/.aframe` — discovers embedded storage shipped
+     * inside npm packages.
+     *
+     * Set A_FRAME_STORAGE_PATTERN='' to disable scanning entirely.
+     */
+    A_FRAME_STORAGE_PATTERN: string;
+    A_FRAME_VERSION: string;
+}
+
+export type { IA_FrameEnv as I };

package/dist/browser/A-FrameNamespace.entity-BDg1FUgo.d.mts

@@ -0,0 +1,136 @@
+import { A_TYPES__Entity_Serialized, A_Entity, A_Scope } from '@adaas/a-concept';
+import { A_FrameVector } from './vector.mjs';
+
+type A_FrameNamespace_Init = {
+    /** Unique identifier / slug for the namespace (e.g. "math", "finance/options") */
+    name: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    /**
+     * Optional embedding model override (e.g. `A_FRAME_MODELS.ANTARES`). When omitted the
+     * server defaults to the Antares model.
+     */
+    model?: string;
+};
+type A_FrameNamespace_Serialized = {
+    hash: string;
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    embedding?: Float32Array;
+    embeddedAt: number;
+    embeddingModel?: string;
+    credentialId?: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+} & A_TYPES__Entity_Serialized;
+type A_FrameNamespace_Record = {
+    /** SHA-256 hex of the namespace name — acts as stable identity key */
+    hash: string;
+    /** Namespace name / slug */
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    embedding: Float32Array;
+    embeddedAt: number;
+    /** Name of the embedding model used to produce the vector */
+    embeddingModel?: 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 that produced the vector */
+    aFrameServerVersion?: string;
+};
+type A_FrameNamespace_EmbeddingMeta = {
+    model?: string;
+    date: string;
+    dimensions: number;
+    inputCount: number;
+    credentialId?: string | null;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+};
+type A_FrameNamespace_SearchResult = {
+    name: string;
+    score: number;
+    hash: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare class A_FrameNamespace extends A_Entity<A_FrameNamespace_Init, A_FrameNamespace_Serialized> {
+    static get concept(): string;
+    protected _name: string;
+    protected _hash: string;
+    protected _description?: string;
+    protected _metadata?: Record<string, any>;
+    protected _vector?: A_FrameVector;
+    protected _embeddedAt?: number;
+    protected _embeddingModel?: string;
+    protected _requestedModel: string;
+    protected _credentialId?: string;
+    protected _aFrameVersion?: string;
+    protected _aFrameServerVersion?: string;
+    get id(): string;
+    get name(): string;
+    get hash(): string;
+    get description(): string | undefined;
+    get metadata(): Record<string, any>;
+    get vector(): A_FrameVector | undefined;
+    get embedding(): Float32Array | null;
+    get aFrameServerVersion(): string | undefined;
+    get aFrameVersion(): string | undefined;
+    get isEmbed(): boolean;
+    /**
+     * The model requested for embedding at init time. Defaults to `A_FRAME_MODELS.ANTARES`.
+     * Sent to the server in the embed request body as the `model` field.
+     */
+    get requestedModel(): string;
+    /**
+      * Saves Namespace to storage. The actual implementation of saving is handled by the A_FrameNamespaceFeatures.Save feature, which can be implemented by the environment to persist the definition to a database, file system, or other storage mechanism.
+      *
+      * @param scope
+      * @returns
+      */
+    save(scope?: A_Scope): Promise<void> | void;
+    /**
+     * Deletes the namespace from storage. The actual implementation of deletion is handled by the A_FrameNamespaceFeatures.Destroy feature, which can be implemented by the environment to remove the namespace from the database, file system, or other storage mechanism.
+     *
+     * @param scope
+     * @returns
+     */
+    destroy(scope?: A_Scope): Promise<void> | void;
+    /**
+     * Loads the namespace from storage. The actual implementation of loading is handled by the A_FrameNamespaceFeatures.Load feature, which can be implemented by the environment to retrieve the namespace 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>;
+    /**
+     * 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_FrameNamespace, 'name' | 'description' | 'metadata'>>): void;
+    /**
+     * Generates an embedding vector for the namespace using the A_FrameNamespaceFeatures.Embed feature. This typically involves sending the namespace's content (name + description) to an embedding model and storing the resulting vector in the entity. Once embedded, the namespace can be searched using its vector representation.
+     *
+     * @param scope
+     * @returns
+     */
+    embed(scope?: A_Scope): Promise<void> | void;
+    fromNew(init: A_FrameNamespace_Init): void;
+    fromJSON(serialized: A_FrameNamespace_Serialized): void;
+    toJSON(): A_FrameNamespace_Serialized;
+    hydrateFromRecord(record: A_FrameNamespace_Record): void;
+    hydrateFromEmbedding(embedding: Float32Array, meta?: A_FrameNamespace_EmbeddingMeta): void;
+    /**
+     * Build the text string sent to the embedding model.
+     * Uses name + description so the vector captures semantic intent.
+     */
+    toString(): string;
+}
+
+export { A_FrameNamespace as A, type A_FrameNamespace_EmbeddingMeta as a, type A_FrameNamespace_Init as b, type A_FrameNamespace_Record as c, type A_FrameNamespace_SearchResult as d, type A_FrameNamespace_Serialized as e };

package/dist/browser/A-FrameSchema.entity-DjYIhsoj.d.mts

@@ -0,0 +1,141 @@
+import { A_TYPES__Entity_Serialized, A_Entity, A_Scope } from '@adaas/a-concept';
+
+type A_FrameSchemaOptions = {
+    /**
+     * Override the AI model used for parameter extraction.
+     *
+     * Defaults to `A_FRAME_MODELS.NOVA` ('adaas-nova-v1') — the structured
+     * JSON extraction model.  Pass any other `A_FRAME_MODELS` constant or a
+     * raw model name to override.
+     */
+    model?: string;
+    /**
+     * Optional system prompt that describes the target JSON schema to the model.
+     *
+     * When provided this is prepended before the standard extraction instructions,
+     * giving the model additional context about the shape it should produce.
+     *
+     * Example:
+     * ```
+     * system: 'You extract { name: string, age: number, city: string } from text.'
+     * ```
+     */
+    system?: string;
+    /** Temperature 0–1.  Lower values produce more deterministic JSON.  Default: 0. */
+    temperature?: number;
+    /** Maximum tokens the model may generate for the JSON response. */
+    max_tokens?: number;
+};
+
+/**
+ * `T` — the shape of the structured data object you expect back from the model.
+ *
+ * Example:
+ * ```ts
+ * const scheme = new A_FrameSchema<{ city: string; date: string }>({
+ *     prompt: 'Book a flight to Paris next Monday.',
+ *     schema: { city: 'string', date: 'string' },
+ * });
+ * ```
+ */
+type A_FrameSchema_Init<T extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * The natural-language input from which parameters should be extracted.
+     * This is the text sent to the model together with schema instructions.
+     */
+    prompt: string;
+    /**
+     * A plain-object describing the expected output schema.
+     *
+     * Each key is a field name; each value is either a type hint string
+     * (`'string'`, `'number'`, `'boolean'`) or a nested schema object.
+     * The server converts this into a system prompt that instructs the model
+     * to return JSON matching the shape.
+     *
+     * Example: `{ name: 'string', age: 'number', active: 'boolean' }`
+     */
+    schema: Record<keyof T, string | Record<string, string>>;
+    options?: A_FrameSchemaOptions;
+};
+type A_FrameSchema_Serialized<T extends Record<string, unknown> = Record<string, unknown>> = {
+    prompt: string;
+    schema: Record<string, string | Record<string, string>>;
+    data?: T;
+    model?: string;
+    date?: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+} & A_TYPES__Entity_Serialized;
+type A_FrameSchema_ExtractionMeta = {
+    model: string;
+    date: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+};
+
+/**
+ * A_FrameSchema<T>
+ *
+ * Sends a natural-language prompt together with a schema descriptor to the
+ * server's `/api/v1/schema/extract` endpoint (Nova model).  The server
+ * returns a structured JSON object that maps the prompt's content to the
+ * fields described by `schema`.
+ *
+ * Generic parameter `T` constrains the shape of the extracted `data` getter
+ * so call-sites get full type-safety without casting.
+ *
+ * Usage:
+ * ```ts
+ * const scheme = new A_FrameSchema<{ city: string; date: string }>({
+ *     prompt: 'Book a flight to Paris next Monday.',
+ *     schema: { city: 'string', date: 'string' },
+ * });
+ * container.scope.register(scheme);
+ * await scheme.extract();
+ *
+ * console.log(scheme.data);   // { city: 'Paris', date: '...' }
+ * console.log(scheme.model);  // physical model name returned by the server
+ * console.log(scheme.isExtracted); // true
+ * ```
+ */
+declare class A_FrameSchema<T extends Record<string, unknown> = Record<string, unknown>> extends A_Entity<A_FrameSchema_Init<T>, A_FrameSchema_Serialized<T>> {
+    static get concept(): string;
+    protected _prompt: string;
+    protected _schema: Record<keyof T, string | Record<string, string>>;
+    protected _options?: A_FrameSchemaOptions;
+    protected _data?: T;
+    protected _model?: string;
+    protected _date?: string;
+    protected _aFrameVersion?: string;
+    protected _aFrameServerVersion?: string;
+    /** The natural-language input prompt used for extraction. */
+    get prompt(): string;
+    /** The schema descriptor passed at construction time. */
+    get schema(): Record<keyof T, string | Record<string, string>>;
+    /** Configured options (model, system, temperature, max_tokens). */
+    get options(): A_FrameSchemaOptions | undefined;
+    /**
+     * The structured data extracted by the model.
+     * Returns `undefined` until `extract()` has been called successfully.
+     */
+    get data(): T | undefined;
+    /** Physical model name returned by the server after extraction. */
+    get model(): string | undefined;
+    /** ISO timestamp string of when the extraction was performed. */
+    get date(): string | undefined;
+    /** `true` once `extract()` has been called and data is populated. */
+    get isExtracted(): boolean;
+    fromNew(init: A_FrameSchema_Init<T>): void;
+    fromJSON(serialized: A_FrameSchema_Serialized<T>): void;
+    toJSON(): A_FrameSchema_Serialized<T>;
+    /**
+     * Sends the prompt and schema to the server for structured extraction.
+     * After completion, `data` will be populated with a typed `T` object.
+     *
+     * The feature is implemented by `A_FrameChannel.extractSchema`.
+     */
+    extract(scope?: A_Scope): Promise<void> | void;
+    hydrateFromExtraction(data: T, meta: A_FrameSchema_ExtractionMeta): void;
+}
+
+export { A_FrameSchema as A, type A_FrameSchemaOptions as a, type A_FrameSchema_ExtractionMeta as b, type A_FrameSchema_Init as c, type A_FrameSchema_Serialized as d };