@adaas/a-frame 0.0.23 → 0.1.2

package/src/lib/A-FrameDynamicStructure/A-FrameDynamicStructure.types.ts

@@ -1,128 +1,224 @@
 import { A_Component, A_Container, A_Fragment, A_TYPES__Ctor, A_TYPES__Entity_Serialized } from "@adaas/a-concept";
 import { A_FrameDynamicPatch_Serialized } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.types";
-import { A_FrameDynamicStructureEvents, A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
-import { A_FrameDynamicStructureOperation } from "./A-FrameDynamicStructureOperation.context";
+import { A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
 
 
 export type DynamicStructureDefaultBasesNames = 'A_Component' | 'A_Container' | 'A_Fragment';
 export type BaseClassName = DynamicStructureDefaultBasesNames | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>;
 
+// ── Options ────────────────────────────────────────────────────────────────────
 
-export type A_FrameDynamicStructure_Init = {
-    /** The goal / initial prompt driving structure generation */
-    prompt: string;
+export type A_FrameDynamicStructureOptions = {
+    /**
+     * Which AI model to use for structure generation and patching.
+     * Defaults to `A_FRAME_MODELS.PULSAR` — the architecture model.
+     */
+    model?: string;
 
-    /** Which model to use for content generation */
-    model: string;
+    /** Context hint passed to the AI to scope the expected architecture style. */
+    context?: string;
+
+    /** Free-form hint about meta/prop requirements for component selection. */
+    metaHint?: 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>>;
+    /**
+     * Only include elements whose base class is in this list.
+     * Accepts class name strings (e.g. `'A_Component'`) or constructors.
+     */
+    includeBases?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
 
-    /** Exclude components whose base class is in this list */
+    /**
+     * Exclude elements 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) */
+    /**
+     * Explicit allowlist of component/fragment/entity names for the AI to pick from.
+     */
     enabledComponents?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+};
 
-    /** Rendering context hint passed to content generator */
-    context?: string;
+export type A_FrameComponentMapOptions = {
+    /**
+     * Minimum cosine-similarity score (0–1) required for a generated element to
+     * be considered matched to a registered component in the local index.
+     * Default: `0.7`
+     */
+    minScore?: number;
 
-    /** Free-form hint about required prop types (forwarded to content generator) */
-    metaHint?: string;
+    /**
+     * How many times the mapper will invoke the server's select/suggest endpoint
+     * for unmatched elements before giving up and recording a `matchError`.
+     * Default: `3`
+     */
+    maxRetries?: number;
+
+    /**
+     * Number of top-scoring candidates to pull from the local index and send to
+     * the AI on each retry.  Larger values give the AI more choices but increase
+     * the request payload size.
+     * Default: `5`
+     */
+    candidateCount?: number;
+};
+
+
+// ── Init / Serialized ──────────────────────────────────────────────────────────
+
+export type A_FrameDynamicStructure_Init = {
+    /** Goal or description driving structure generation. */
+    prompt: string;
+    /** Optional generation / filtering options. */
+    options?: Partial<A_FrameDynamicStructureOptions & A_FrameComponentMapOptions>;
 };
 
 export type A_FrameDynamicStructure_Serialized = {
     name: string;
     description?: string;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
     history: Array<A_FrameDynamicPatch_Serialized>;
-} & A_TYPES__Entity_Serialized
+} & A_TYPES__Entity_Serialized;
 
+// ── Feature name union ──────────────────────────────────────────────────────────
 
-export type A_FrameDynamicStructureListener = (context: A_FrameDynamicStructureOperation) => void;
-
-
-export type A_FrameDynamicStructureResolvedComponent<P extends Record<string, any> = Record<string, any>> = {
-    component: string;
-    score: number;
-    meta: P
-}
-
-export type A_FrameDynamicStructureFeatureNames = typeof A_FrameDynamicStructureFeatures[keyof typeof A_FrameDynamicStructureFeatures];
-
-
-export type A_FrameDynamicStructureEventNames = typeof A_FrameDynamicStructureEvents[keyof typeof A_FrameDynamicStructureEvents];
+export type A_FrameDynamicStructureFeatureNames =
+    typeof A_FrameDynamicStructureFeatures[keyof typeof A_FrameDynamicStructureFeatures];
 
+// ── Domain types ───────────────────────────────────────────────────────────────
 
+/**
+ * A single architectural element in the generated structure as returned by the
+ * server. The `prompt` is a one-sentence description of its purpose and
+ * responsibilities. `embedding` is the server-computed search vector — present
+ * immediately after generate/patch, and used by the mapper for cosine search.
+ */
 export 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;
+    /** Why this element is needed — the requirement or concern that justifies its inclusion. */
+    role?: string;
+    class?: string;
+    /** @internal Server-computed search vector; consumed during mapping. */
+    embedding?: number[];
+};
 
-    /**
-     * 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
-}
-
+/**
+ * Single element in the component-map result. Carries the original prompt/class
+ * from the definition plus the match outcome from the A_FrameComponentMapper.
+ */
+export type A_FrameComponentMapEntry = {
+    prompt: string;
+    /** Why this element is needed — the requirement or concern that justifies its inclusion. */
+    role?: string;
+    class?: string;
+    /** Name of the registered class matched to this element, or `null` if unmatched. */
+    matchedClass: string | null;
+    /** Cosine-similarity score of the best found candidate (0–1). */
+    matchScore: number;
+    /** Populated when the element could not be matched after all retries. */
+    matchError?: { title: string; description: string } | null;
+};
 
+/**
+ * Full architecture definition produced by `generate()` or `patch()`.
+ */
 export 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.
-     * 
+     * Infrastructure/runtime hosts (HTTP server, worker process, database, etc.).
+     * Each container lists the components, fragments and entities that belong to it.
      */
     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.
-     */
+    /** Stateless logic units with methods and features (controllers, services, renderers, etc.). */
     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.
-     */
+    /** Stateful context objects shared across components (session, config, state store, etc.). */
     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.
-     */
+    /** Domain data models with unique identities (User, Article, Order, etc.). */
     entities: Array<A_FrameDynamicStructureDefinitionEntity>;
-}
+};
+
+/**
+ * Result produced by `map()` after matching all definition elements against the
+ * local A_FrameIndex. Mirrors the definition's shape but uses
+ * `A_FrameComponentMapEntry` nodes (match outcome) instead of raw definition
+ * nodes (embeddings).
+ */
+export type A_FrameComponentMapResult = {
+    containers: Array<A_FrameComponentMapEntry & {
+        components: Array<A_FrameComponentMapEntry>;
+        fragments: Array<A_FrameComponentMapEntry>;
+        entities: Array<A_FrameComponentMapEntry>;
+    }>;
+    components: Array<A_FrameComponentMapEntry>;
+    fragments: Array<A_FrameComponentMapEntry>;
+    entities: Array<A_FrameComponentMapEntry>;
+};
+
+// ── Wire transport types ───────────────────────────────────────────────────────
+
+export interface A_FrameStructureGenerateResponse {
+    definition: A_FrameDynamicStructureDefinition;
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
+
+export interface A_FrameStructurePatchResponse {
+    patchSummary: string;
+    definition: A_FrameDynamicStructureDefinition;
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
+
+// ── Select / suggest ─────────────────────────────────────────────────────────
+
+export interface A_FrameStructureSelectCandidate {
+    name: string;
+    description?: string;
+}
+
+export interface A_FrameStructureSelectElement {
+    prompt: string;
+    role?: string;
+    candidates: A_FrameStructureSelectCandidate[];
+}
+
+export type A_FrameStructureSelectResolutionType = 'select' | 'suggest' | 'none';
+
+export interface A_FrameStructureSelectResolution {
+    elementPrompt: string;
+    type: A_FrameStructureSelectResolutionType;
+    /** Present when type === 'select' */
+    selectedClass?: string;
+    /** Present when type === 'suggest' */
+    suggestion?: {
+        prompt: string;
+        role?: string;
+        /** Server-computed embedding ready for immediate local re-search. */
+        embedding?: number[];
+    };
+}
+
+export interface A_FrameStructureSelectRequest {
+    originalPrompt: string;
+    elements: A_FrameStructureSelectElement[];
+    model?: string;
+}
+
+export interface A_FrameStructureSelectResponse {
+    resolutions: A_FrameStructureSelectResolution[];
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
+
+export interface A_FrameStructurePatchResponse {
+    patchSummary: string;
+    definition: A_FrameDynamicStructureDefinition;
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}

package/src/lib/A-FrameDynamicStructure/index.ts

@@ -2,4 +2,7 @@ export * from './A-FrameDynamicStructure.constants';
 export * from './A-FrameDynamicStructure.entity';
 export * from './A-FrameDynamicStructure.types';
 export * from './A-FrameDynamicStructure.error';
+export * from './A-FrameComponentMapIndex.context';
+export * from './A-FrameComponentMapper.component';
+export * from '../A-FrameDynamicPatch';
 // export * from './A-FrameDynamicStructureO';

package/src/lib/A-FrameEnv/A-FrameEnv.fragment.env-browser.ts

@@ -26,6 +26,10 @@ export class A_FrameEnv extends A_Fragment implements IA_FrameEnv {
     }
 
     get A_FRAME_STORAGE_DIR() {
-        return (window as any).A_FRAME_STORAGE_DIR || '.aframestr';
+        return (window as any).A_FRAME_STORAGE_DIR || '.aframe';
+    }
+
+    get A_FRAME_STORAGE_PATTERN() {
+        return '';
     }
 }

package/src/lib/A-FrameEnv/A-FrameEnv.fragment.env-node.ts

@@ -30,10 +30,32 @@ export class A_FrameEnv extends A_Fragment implements IA_FrameEnv {
     }
 
     get A_FRAME_STORAGE_DIR() {
-        return process.env.A_FRAME_STORAGE_DIR || '.aframestr';
+        return process.env.A_FRAME_STORAGE_DIR || '.aframe';
+    }
+
+    /**
+     * Comma-separated glob pattern(s) used to discover additional storage
+     * directories at startup (read-only merge source).
+     *
+     * Each pattern is resolved relative to `process.cwd()`.
+     * Default scans for any `.aframe` folder inside node_modules packages.
+     */
+    get A_FRAME_STORAGE_PATTERN() {
+        return process.env.A_FRAME_STORAGE_PATTERN ?? 'node_modules/**/.aframe';
     }
 
     get A_FRAME_VERSION() {
         return pkg.version || '0.0.1';
     }
+
+    /**
+     * Maximum time (ms) the HTTP client waits for a single response.
+     * AI inference can be slow; default is 120 seconds.
+     * Override with A_FRAME_REQUEST_TIMEOUT env var.
+     */
+    get A_FRAME_REQUEST_TIMEOUT(): number {
+        const raw = process.env.A_FRAME_REQUEST_TIMEOUT;
+        const parsed = raw ? parseInt(raw, 10) : NaN;
+        return isNaN(parsed) ? 120_000 : parsed;
+    }
 }

package/src/lib/A-FrameEnv/A-FrameEnv.types.ts

@@ -3,5 +3,17 @@ export interface IA_FrameEnv {
     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;
 }

package/src/lib/A-FrameIndex/A-FrameIndex.context.ts

@@ -1,7 +1,7 @@
-import { A_Dependency, A_Fragment, A_Scope, ASEID } from "@adaas/a-concept";
+import { A_Concept, A_Context, A_Dependency, A_Fragment, A_Scope, ASEID } from "@adaas/a-concept";
 import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
 import { A_FrameNamespace } from "../A-FrameNamespace/A-FrameNamespace.entity";
-import { A_FrameDefinition_SearchResult, A_FrameSearchOptions } from "./A-FrameIndex.types";
+import { A_FrameDefinition_SearchResult, A_FrameInheritanceFilter, A_FrameListOptions, A_FrameSearchOptions } from "./A-FrameIndex.types";
 import { A_FrameDefinition } from "../A-FrameDefinition";
 import { A_FRAME_DEFAULT_NAMESPACE_KEY } from "../A-FrameNamespace/A-FrameNamespace.constants";
 
@@ -22,6 +22,11 @@ export class A_FrameIndex extends A_Fragment {
         return A_FrameIndex.instance.indexSize;
     }
 
+
+    static get scope(): A_Scope {
+        return A_Context.scope(this);
+    }
+
     // ------------------------------------------------------------------------------------
     // --------------------Static Access to Instance Methods-------------------------------
     // ------------------------------------------------------------------------------------
@@ -34,9 +39,7 @@ export class A_FrameIndex extends A_Fragment {
     static getDefinition(nameOrHash: string): A_FrameDefinition | undefined {
         return A_FrameIndex.instance.getDefinition(nameOrHash);
     }
-    static listDefinitions(filter: {
-        namespace?: string | A_FrameNamespace
-    }): A_FrameDefinition[] {
+    static listDefinitions(filter: A_FrameListOptions): A_FrameDefinition[] {
         return A_FrameIndex.instance.listDefinitions(filter);
     }
     static removeDefinition(def: A_FrameDefinition): void {
@@ -137,9 +140,7 @@ export class A_FrameIndex extends A_Fragment {
         return undefined;
     }
 
-    listDefinitions(filter: {
-        namespace?: string | A_FrameNamespace
-    } = {}): A_FrameDefinition[] {
+    listDefinitions(filter: A_FrameListOptions = {}): A_FrameDefinition[] {
         const namespaceName = filter.namespace
             ? typeof filter.namespace === 'string'
                 ? ASEID.isASEID(filter.namespace)
@@ -148,7 +149,15 @@ export class A_FrameIndex extends A_Fragment {
                 : filter.namespace.id
             : undefined;
 
-        return [...this.definitions.values()].filter(r => !namespaceName || r.namespace.name === namespaceName);
+        const inheritFilters = filter.inherit
+            ? Array.isArray(filter.inherit) ? filter.inherit : [filter.inherit]
+            : undefined;
+
+        return [...this.definitions.values()].filter(r => {
+            if (namespaceName && r.namespace.name !== namespaceName) return false;
+            if (inheritFilters && !this.matchesInheritanceFilters(r, inheritFilters)) return false;
+            return true;
+        });
     }
 
     removeDefinition(def: A_FrameDefinition): void {
@@ -201,11 +210,17 @@ export class A_FrameIndex extends A_Fragment {
         options: A_FrameSearchOptions = {},
     ): A_FrameDefinition_SearchResult[] {
 
-        const { topK = 10, namespace, minScore = 0 } = options;
+        const { topK = 10, namespace, minScore = 0, inherit } = options;
+
+        const inheritFilters = inherit
+            ? Array.isArray(inherit) ? inherit : [inherit]
+            : undefined;
 
-        const pool = namespace
-            ? [...this.definitions.values()].filter(r => r.namespace.id === namespace)
-            : [...this.definitions.values()];
+        const pool = [...this.definitions.values()].filter(r => {
+            if (namespace && r.namespace.id !== namespace) return false;
+            if (inheritFilters && !this.matchesInheritanceFilters(r, inheritFilters)) return false;
+            return true;
+        });
 
         const scored = pool.map(r => ({
             record: r,
@@ -222,6 +237,41 @@ export class A_FrameIndex extends A_Fragment {
             }));
     }
 
+    /**
+     * Test whether a definition's resolved constructor satisfies at least one
+     * of the provided inheritance filters (OR semantics).
+     *
+     * The constructor is resolved from the internal scope by the definition's
+     * name using `scope.resolveConstructor(name)` — the same mechanism the
+     * framework uses everywhere for class lookup.
+     *
+     * - `strict: false` (default) — any depth, using A_Context's O(1) indexed
+     *   inheritance map: `A_Context.isIndexedInheritedFrom(ctor, targetClass)`
+     * - `strict: true`            — direct child only:
+     *   `Object.getPrototypeOf(ctor) === targetClass`
+     *
+     * Definitions whose name cannot be resolved from the scope (e.g. restored
+     * from storage without a live container) never match.
+     */
+    private matchesInheritanceFilters(
+        def: A_FrameDefinition,
+        filters: A_FrameInheritanceFilter[],
+    ): boolean {
+        const ctor = this.scope.resolveConstructor(def.name);
+        if (!ctor) return false;
+
+        return filters.some(filter => {
+            const targetClass = filter.class;
+            if (filter.strict) {
+                // Direct child: the immediate prototype must be exactly targetClass
+                return Object.getPrototypeOf(ctor) === targetClass;
+            } else {
+                // Any depth: use A_Context's indexed inheritance check (O(1))
+                return A_Context.isIndexedInheritedFrom(ctor, targetClass);
+            }
+        });
+    }
+
     // protected cosineSimilarity(vectorA: A_FrameVector, vectorB?: A_FrameVector): number {
     //     const a = vectorA.values ?? new Float32Array();
     //     const b = vectorB?.values ?? new Float32Array();

package/src/lib/A-FrameIndex/A-FrameIndex.types.ts

@@ -43,6 +43,40 @@ export type A_FrameIndexMetaMethodMeta = {
 }
 
 
+// ---------------------------------------------------------------------------
+// ------------- A-Frame Inheritance Filter ----------------------------------
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a single inheritance constraint applied when listing or searching
+ * definitions.
+ *
+ * - `class`  — the target constructor to test against
+ * - `strict` — controls how deep the prototype chain is walked:
+ *     - `false` (default) — matches any descendant at **any depth**
+ *       (`targetClass.isPrototypeOf(originClass)`)
+ *     - `true`  — matches only **direct children** (one prototype hop):
+ *       (`Object.getPrototypeOf(originClass) === targetClass`)
+ *
+ * @example
+ * // All definitions whose origin class extends A_Container (any depth)
+ * { class: A_Container }
+ *
+ * // Only definitions whose origin class directly extends A_Container
+ * { class: A_Container, strict: true }
+ *
+ * // All definitions whose origin class extends HttpServer at any depth
+ * { class: HttpServer, strict: false }
+ *
+ * // Combine multiple filters (OR semantics — a definition passes if ANY filter matches)
+ * [{ class: A_Fragment }, { class: A_Entity, strict: true }]
+ */
+export type A_FrameInheritanceFilter = {
+    class: Function;
+    strict?: boolean;
+};
+
+
 // ---------------------------------------------------------------------------
 // ------------- A-Frame Runtime Search Types --------------------------------
 // ---------------------------------------------------------------------------
@@ -54,6 +88,25 @@ export type A_FrameSearchOptions = {
     namespace?: string
     /** Minimum cosine similarity score (0–1); default 0 */
     minScore?: number
+    /**
+     * Restrict the candidate pool to definitions whose origin class satisfies
+     * one or more inheritance rules.  Multiple entries use OR semantics —
+     * a definition passes if it matches ANY of the provided filters.
+     */
+    inherit?: A_FrameInheritanceFilter | A_FrameInheritanceFilter[]
+}
+
+/**
+ * Options accepted by `A_FrameIndex.listDefinitions()`.
+ */
+export type A_FrameListOptions = {
+    /** Restrict to a single namespace */
+    namespace?: string | A_FrameNamespace
+    /**
+     * Restrict to definitions whose origin class satisfies one or more
+     * inheritance rules.  Multiple entries use OR semantics.
+     */
+    inherit?: A_FrameInheritanceFilter | A_FrameInheritanceFilter[]
 }
 
 

package/src/lib/A-FrameModels/A-FrameModels.constants.ts

@@ -0,0 +1,75 @@
+/**
+ * Adaas named model identifiers — client-side mirror of the server catalog.
+ *
+ * These are the stable logical identifiers for each model role. Pass them
+ * wherever an entity or channel method accepts a `model` option to target a
+ * specific named model on the server.
+ *
+ * The server resolves these IDs to physical backend models (e.g. Ollama,
+ * OpenAI) and applies any required task prefixes automatically. Swapping to a
+ * dedicated fine-tuned model in the future requires no changes on the client.
+ *
+ * @see adaas-a-frame-mcp/README.models.md
+ */
+
+export const A_FRAME_MODELS = {
+
+    // ── Embedding ─────────────────────────────────────────────────────────────
+
+    /**
+     * Antares — component definition embedding model.
+     *
+     * Indexes component sources and namespace definitions with the
+     * `search_document:` prefix.  The reference system everything navigates
+     * against.  Use when storing content that will be retrieved later.
+     */
+    ANTARES: 'adaas-antares-v1' as const,
+
+    /**
+     * Vega — search query embedding model.
+     *
+     * Produces `search_query:` prefixed vectors for retrieval against the
+     * Antares index.  Use when embedding a user query or search term.
+     */
+    VEGA: 'adaas-vega-v1' as const,
+
+    // ── Completion ────────────────────────────────────────────────────────────
+
+    /**
+     * Rigel — code completion model.
+     *
+     * Generates TypeScript/JavaScript code with syntax precision.
+     * Default model for `A_FrameCompletion` — use for code generation,
+     * scaffolding, and structured source output.
+     */
+    RIGEL: 'adaas-rigel-v1' as const,
+
+    /**
+     * Pulsar — software architecture completion model.
+     *
+     * Decomposes requirements into structured component designs.
+     * Use for architecture analysis, DSG structure generation, and
+     * patch planning.
+     */
+    PULSAR: 'adaas-pulsar-v1' as const,
+
+    /**
+     * Lyra — bridge/classifier model.
+     *
+     * Translates content semantics into structured text.
+     * Default model for `A_FrameDynamicContent` — use for content
+     * generation and patching.
+     */
+    LYRA: 'adaas-lyra-v1' as const,
+
+    /**
+     * Nova — param extraction model.
+     *
+     * Illuminates structured JSON parameters hidden inside unstructured text.
+     * Outputs constrained JSON by default.
+     */
+    NOVA: 'adaas-nova-v1' as const,
+
+} as const;
+
+export type A_FrameModelId = typeof A_FRAME_MODELS[keyof typeof A_FRAME_MODELS];

package/src/lib/A-FrameModels/index.ts

@@ -0,0 +1 @@
+export * from './A-FrameModels.constants';