@adaas/a-frame 0.0.23 → 0.1.2

package/dist/node/A-FrameNamespace.entity-HDXcLGcS.d.ts

@@ -0,0 +1,136 @@
+import { A_TYPES__Entity_Serialized, A_Entity, A_Scope } from '@adaas/a-concept';
+import { A_FrameVector } from './vector.js';
+
+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/node/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 };

package/dist/node/A-FrameSchema.entity-DjYIhsoj.d.ts

@@ -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 };

package/dist/node/A-FrameSegment.entity-C0izuOmC.d.ts

@@ -0,0 +1,161 @@
+import { A_TYPES__Entity_Serialized, A_Entity, A_Scope } from '@adaas/a-concept';
+import { A_FrameVector } from './vector.js';
+
+type A_FrameSegmentOptions = {
+    /**
+     * model: Optional name of the embedding model to associate with this segment (e.g. "adaas-antares-v1"). If not provided, the server will attempt to infer the model based on the vector dimensions or other available metadata.
+     */
+    model: string;
+    /**
+     * Retrieval task hint for asymmetric embedding models (e.g. adaas-antares-v1).
+     * - 'query'    — text is a search query
+     * - 'document' — text is content being indexed
+     * - 'default'  — no prefix / symmetric mode
+     */
+    task: 'document' | 'query' | 'default';
+};
+type A_FrameSegment_Init = {
+    /** Unique identifier / slug for the namespace (e.g. "math", "finance/options") */
+    content: string;
+    metadata?: Record<string, any>;
+    options?: Partial<A_FrameSegmentOptions>;
+};
+type A_FrameSegment_Serialized = {
+    hash: string;
+    content: string;
+    embedding?: Float32Array;
+    embeddedAt: string;
+    /**
+     * Embedding task used when this segment was embedded.
+     * Persisted so that re-embedding after cache invalidation uses the same task.
+     */
+    task?: 'document' | 'query' | 'default';
+    model?: string;
+    credentialId?: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+} & A_TYPES__Entity_Serialized;
+type A_FrameSegment_Record = {
+    /** SHA-256 hex of the namespace name — acts as stable identity key */
+    hash: string;
+    /** Segment name / slug */
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    embedding: Float32Array;
+    embeddedAt: string;
+    /** Embedding task used when this segment was embedded ('document' | 'query' | 'default'). */
+    task?: 'document' | 'query' | 'default';
+    /** 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_FrameSegment_EmbeddingMeta = {
+    model?: string;
+    date: string;
+    dimensions: number;
+    inputCount: number;
+    credentialId?: string | null;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+};
+type A_FrameSegment_SearchResult = {
+    name: string;
+    score: number;
+    hash: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare class A_FrameSegment extends A_Entity<A_FrameSegment_Init, A_FrameSegment_Serialized> {
+    static get concept(): string;
+    protected _content: string;
+    protected _hash: string;
+    protected _vector?: A_FrameVector;
+    protected _embeddedAt?: string;
+    protected _model?: string;
+    protected _credentialId?: string;
+    protected _aFrameVersion?: string;
+    protected _aFrameServerVersion?: string;
+    protected _options?: Partial<A_FrameSegmentOptions>;
+    get id(): string;
+    get content(): string;
+    get hash(): string;
+    get vector(): A_FrameVector | undefined;
+    get embedding(): Float32Array | null;
+    get aFrameServerVersion(): string | undefined;
+    get aFrameVersion(): string | undefined;
+    get isEmbed(): boolean;
+    get options(): Partial<A_FrameSegmentOptions> | undefined;
+    /**
+     * Physical model name returned by the server after embedding.
+     * `undefined` until `embed()` has been called successfully.
+     */
+    get model(): string | undefined;
+    /**
+     * ISO timestamp of when the embedding was produced.
+     * `undefined` until `embed()` has been called successfully.
+     */
+    get embeddedAt(): string | undefined;
+    /**
+     * ID of the server credential (API key) used during embedding.
+     * `undefined` until `embed()` has been called successfully.
+     */
+    get credentialId(): string | undefined;
+    /**
+      * Saves Segment to storage. The actual implementation of saving is handled by the A_FrameSegmentFeatures.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_FrameSegmentFeatures.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_FrameSegmentFeatures.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_FrameSegment, 'content'>>): void;
+    /**
+     * Generates an embedding vector for the namespace using the A_FrameSegmentFeatures.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_FrameSegment_Init): void;
+    fromJSON(serialized: A_FrameSegment_Serialized): void;
+    toJSON(): A_FrameSegment_Serialized;
+    hydrateFromRecord(record: A_FrameSegment_Record): void;
+    /**
+     * Populate the embedding vector directly from a raw `Float32Array`.
+     * Use this when the vector is obtained externally (e.g. from a server
+     * response) without going through the full `embed()` feature pipeline.
+     */
+    hydrateFromEmbedding(embedding: Float32Array): void;
+    /**
+     * Build the text string sent to the embedding model.
+     * Uses content so the vector captures semantic intent.
+     */
+    toString(): string;
+}
+
+export { A_FrameSegment as A, type A_FrameSegmentOptions as a, type A_FrameSegment_EmbeddingMeta as b, type A_FrameSegment_Init as c, type A_FrameSegment_Record as d, type A_FrameSegment_SearchResult as e, type A_FrameSegment_Serialized as f };