@adaas/a-frame 0.1.1 → 0.1.2

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

@@ -1,10 +1,194 @@
-import { A_TYPES__Entity_Serialized } from "@adaas/a-concept"
+import { A_Component, 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_FrameDynamicFeatureFeatures } from "./A-FrameDynamicFeature.constants";
 
 
-export type A_FrameDynamicFeature_Init = {
+// ── Options ────────────────────────────────────────────────────────────────────
 
-}
+export type A_FrameDynamicFeatureOptions = {
+    /**
+     * Which AI model to use for workflow generation.
+     * Defaults to `A_FRAME_MODELS.PULSAR` — the architecture model.
+     */
+    model?: string;
+
+    /**
+     * Additional context hint forwarded to the AI — e.g. "microservices",
+     * "monolith", "event-driven".
+     */
+    context?: string;
+
+    /**
+     * Only consider methods whose owning class's base is in this allowlist.
+     * Accepts string names or constructors.
+     */
+    includeBases?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment>>;
+
+    /**
+     * Exclude methods whose owning class's base is in this denylist.
+     */
+    excludeBases?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment>>;
+
+    /**
+     * Explicit allowlist of component/fragment names the AI may reference.
+     */
+    enabledComponents?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment>>;
+
+    /**
+     * Minimum cosine-similarity score (0–1) for a workflow step to be matched
+     * to a registered method.  Default: `0.7`
+     */
+    minScore?: number;
+
+    /**
+     * How many server refinement retries before a step is marked unmatched.
+     * Default: `3`
+     */
+    maxRetries?: number;
+};
+
+
+// ── Init / Serialized ──────────────────────────────────────────────────────────
+
+export type A_FrameDynamicFeature_Init = {
+    /** Goal or capability driving workflow generation. */
+    prompt: string;
+    /** Optional generation / filtering options. */
+    options?: Partial<A_FrameDynamicFeatureOptions>;
+};
 
 export type A_FrameDynamicFeature_Serialized = {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    history: Array<A_FrameDynamicPatch_Serialized>;
+} & A_TYPES__Entity_Serialized;
+
+
+// ── Feature name union ──────────────────────────────────────────────────────
+
+export type A_FrameDynamicFeatureFeatureNames =
+    typeof A_FrameDynamicFeatureFeatures[keyof typeof A_FrameDynamicFeatureFeatures];
+
+
+// ── Domain types ───────────────────────────────────────────────────────────────
+
+/**
+ * A single parameter in a workflow step — describes what the caller should
+ * provide or what the step will produce.
+ */
+export type A_FrameDynamicFeatureParam = {
+    /** Parameter name (camelCase). */
+    name: string;
+    /** TypeScript type string, e.g. `"string"`, `"number"`, `"UserEntity"`. */
+    type: string;
+    /** Human-readable purpose of this parameter. */
+    description: string;
+    /** Whether this parameter must be provided (`true`) or is optional. */
+    required: boolean;
+};
+
+/**
+ * A single step in the generated workflow definition.
+ * Each step corresponds to one method call on a component or fragment.
+ */
+export type A_FrameDynamicFeatureStep = {
+    /**
+     * One-sentence description of this step's purpose — used as the primary
+     * key for semantic matching against the A_FrameIndex.
+     */
+    prompt: string;
+    /** Ordered list of input parameters for this step. */
+    inputs: A_FrameDynamicFeatureParam[];
+    /** Ordered list of output values produced by this step. */
+    outputs: A_FrameDynamicFeatureParam[];
+    /** @internal Server-computed search vector (consumed during mapping). */
+    embedding?: number[];
+};
+
+/**
+ * Full workflow definition produced by `generate()` or `patch()`.
+ */
+export type A_FrameDynamicFeatureDefinition = {
+    /**
+     * Short title for the workflow, e.g. "User Registration".
+     */
+    title: string;
+    /**
+     * Description of what the workflow accomplishes end-to-end,
+     * what the caller must supply, and what will be returned.
+     */
+    description: string;
+    /** Ordered sequence of steps that make up the workflow. */
+    steps: A_FrameDynamicFeatureStep[];
+    /**
+     * Supporting components (stateless services / controllers) whose methods
+     * are used in the steps.  No container grouping — workflows are
+     * cross-cutting by nature.
+     */
+    components: Array<{ prompt: string; embedding?: number[] }>;
+    /** Supporting fragments (stateful context objects) referenced in the steps. */
+    fragments: Array<{ prompt: string; embedding?: number[] }>;
+    /** Supporting entities / domain models referenced in step parameters. */
+    entities: Array<{ prompt: string; embedding?: number[]; parameters?: A_FrameDynamicFeatureParam[] }>;
+};
+
+
+// ── Map types ──────────────────────────────────────────────────────────────────
+
+/**
+ * Result of matching one workflow step against the A_FrameIndex.
+ */
+export type A_FrameDynamicFeatureStepMapEntry = {
+    prompt: string;
+    inputs: A_FrameDynamicFeatureParam[];
+    outputs: A_FrameDynamicFeatureParam[];
+    /** Matched class name, or `null` if unresolved. */
+    matchedClass: string | null;
+    /** Matched method name, or `null` if unresolved. */
+    matchedMethod: string | null;
+    /** Cosine-similarity score of the best match (0–1). */
+    matchScore: number;
+    /** Error details when matching failed after all retries. */
+    matchError?: { title: string; description: string } | null;
+};
+
+/**
+ * Result of matching a supporting element (component / fragment / entity)
+ * against the A_FrameIndex.
+ */
+export type A_FrameDynamicFeatureElementMapEntry = {
+    prompt: string;
+    matchedClass: string | null;
+    matchScore: number;
+    matchError?: { title: string; description: string } | null;
+};
+
+/**
+ * Full map result produced by `map()` after matching every element against
+ * the local A_FrameIndex.
+ */
+export type A_FrameDynamicFeatureMapResult = {
+    steps: A_FrameDynamicFeatureStepMapEntry[];
+    components: A_FrameDynamicFeatureElementMapEntry[];
+    fragments: A_FrameDynamicFeatureElementMapEntry[];
+    entities: A_FrameDynamicFeatureElementMapEntry[];
+};
+
+
+// ── Wire transport types ───────────────────────────────────────────────────────
+
+export interface A_FrameFeatureGenerateResponse {
+    definition: A_FrameDynamicFeatureDefinition;
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}
 
-} & A_TYPES__Entity_Serialized
+export interface A_FrameFeaturePatchResponse {
+    patchSummary: string;
+    definition: A_FrameDynamicFeatureDefinition;
+    model: string;
+    date: string;
+    meta: { server_version: string };
+}

package/src/lib/A-FrameDynamicFeature/A-FrameDynamicFeatureOperation.context.ts

@@ -0,0 +1,33 @@
+import { A_Fragment } from "@adaas/a-concept";
+
+
+/**
+ * Thin context fragment that carries parameters for a single DynamicFeature
+ * operation (generate or patch).  Injected into the feature execution scope and
+ * resolved by channel feature-extension handlers via `@A_Inject`.
+ */
+export class A_FrameDynamicFeatureOperation<
+    _InputParams = any,
+> extends A_Fragment {
+
+    protected _meta: Map<string, any> = new Map();
+
+    constructor(
+        params: _InputParams = {} as _InputParams
+    ) {
+        super({ name: 'a-frame-dynamic-feature-operation-context' });
+        this._meta.set('params', params);
+    }
+
+    get params(): _InputParams {
+        return this._meta.get('params');
+    }
+
+    get(key: string): any {
+        return this._meta.get(key);
+    }
+
+    set(key: string, value: any): void {
+        this._meta.set(key, value);
+    }
+}

package/src/lib/A-FrameDynamicFeature/A-FrameMethodMapIndex.context.ts

@@ -0,0 +1,99 @@
+import { A_Fragment } from "@adaas/a-concept";
+import {
+    A_FrameDynamicFeatureDefinition,
+    A_FrameDynamicFeatureElementMapEntry,
+    A_FrameDynamicFeatureMapResult,
+    A_FrameDynamicFeatureStep,
+    A_FrameDynamicFeatureStepMapEntry,
+} from "./A-FrameDynamicFeature.types";
+
+
+/**
+ * Context fragment that accumulates the method/component-mapping results
+ * produced by `A_FrameMethodMapper.mapFeature()`.
+ *
+ * Uses `prompt` as the unique key — same approach as `A_FrameComponentMapIndex`.
+ * Call `toResult(definition)` after the mapper finishes to build the fully
+ * structured `A_FrameDynamicFeatureMapResult`.
+ */
+export class A_FrameMethodMapIndex extends A_Fragment {
+
+    private _stepEntries:    Map<string, A_FrameDynamicFeatureStepMapEntry>    = new Map();
+    private _elementEntries: Map<string, A_FrameDynamicFeatureElementMapEntry> = new Map();
+
+    constructor() {
+        super({ name: 'a-frame-method-map-index' });
+    }
+
+    // ── Step entries ─────────────────────────────────────────────────────────
+
+    setStep(entry: A_FrameDynamicFeatureStepMapEntry): void {
+        this._stepEntries.set(entry.prompt, entry);
+    }
+
+    getStep(prompt: string): A_FrameDynamicFeatureStepMapEntry | undefined {
+        return this._stepEntries.get(prompt);
+    }
+
+    // ── Element entries (components / fragments / entities) ───────────────────
+
+    setElement(entry: A_FrameDynamicFeatureElementMapEntry): void {
+        this._elementEntries.set(entry.prompt, entry);
+    }
+
+    getElement(prompt: string): A_FrameDynamicFeatureElementMapEntry | undefined {
+        return this._elementEntries.get(prompt);
+    }
+
+    // ── Accessors ─────────────────────────────────────────────────────────────
+
+    clear(): void {
+        this._stepEntries.clear();
+        this._elementEntries.clear();
+    }
+
+    get stepCount():    number { return this._stepEntries.size; }
+    get elementCount(): number { return this._elementEntries.size; }
+
+    get matchedSteps(): A_FrameDynamicFeatureStepMapEntry[] {
+        return Array.from(this._stepEntries.values()).filter(e => e.matchedMethod !== null);
+    }
+
+    get unmatchedSteps(): A_FrameDynamicFeatureStepMapEntry[] {
+        return Array.from(this._stepEntries.values()).filter(e => e.matchedMethod === null);
+    }
+
+    // ── Result building ───────────────────────────────────────────────────────
+
+    /**
+     * Construct a fully structured `A_FrameDynamicFeatureMapResult` from the
+     * accumulated entries and the provided definition.
+     */
+    toResult(definition: A_FrameDynamicFeatureDefinition): A_FrameDynamicFeatureMapResult {
+        const getStep = (step: A_FrameDynamicFeatureStep): A_FrameDynamicFeatureStepMapEntry => {
+            const existing = this._stepEntries.get(step.prompt);
+            if (existing) return existing;
+            return {
+                prompt:       step.prompt,
+                inputs:       step.inputs,
+                outputs:      step.outputs,
+                matchedClass:  null,
+                matchedMethod: null,
+                matchScore:    0,
+            };
+        };
+
+        const getElement = (el: { prompt: string }): A_FrameDynamicFeatureElementMapEntry => {
+            const existing = this._elementEntries.get(el.prompt);
+            if (existing) return existing;
+            return { prompt: el.prompt, matchedClass: null, matchScore: 0 };
+        };
+
+        return {
+            steps:      definition.steps.map(getStep),
+            components: definition.components.map(getElement),
+            fragments:  definition.fragments.map(getElement),
+            entities:   definition.entities.map(getElement),
+        };
+    }
+}

package/src/lib/A-FrameDynamicFeature/A-FrameMethodMapper.component.ts

@@ -0,0 +1,182 @@
+import { A_Caller, A_Component, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_FrameChannel } from "../A-FrameChannel/A-FrameChannel.component";
+import { A_FrameFeatures } from "../A-FrameChannel/A-FrameChannel.constants";
+import { A_FrameChannelRequest } from "../A-FrameChannel/A-FrameChannelRequest.context";
+import { A_FrameIndex } from "../A-FrameIndex/A-FrameIndex.context";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import { A_FrameDynamicFeature } from "./A-FrameDynamicFeature.entity";
+import { A_FrameDynamicFeatureFeatures } from "./A-FrameDynamicFeature.constants";
+import { A_FrameDynamicFeatureError } from "./A-FrameDynamicFeature.error";
+import {
+    A_FrameDynamicFeatureDefinition,
+    A_FrameDynamicFeatureElementMapEntry,
+    A_FrameDynamicFeatureStep,
+    A_FrameDynamicFeatureStepMapEntry,
+    A_FrameFeaturePatchResponse,
+} from "./A-FrameDynamicFeature.types";
+import { A_FrameMethodMapIndex } from "./A-FrameMethodMapIndex.context";
+
+
+/**
+ * Stateless component that implements the `Map` feature for
+ * `A_FrameDynamicFeature`.
+ *
+ * Algorithm:
+ *  1. Read `feature.definition` (includes server-computed embeddings on steps
+ *     and supporting elements).
+ *  2. Run cosine-similarity search against `A_FrameIndex` for every step and
+ *     every supporting element.
+ *  3. For steps that remain unmatched, issue a server patch to refine their
+ *     descriptions (up to `feature.maxRetries` times), then re-match.
+ *  4. Mark any still-unmatched steps with a `matchError`.
+ *  5. Hydrate the feature with `mapIndex.toResult(def)`.
+ */
+export class A_FrameMethodMapper extends A_Component {
+
+    @A_Feature.Extend({
+        name: A_FrameDynamicFeatureFeatures.Map,
+        scope: [A_FrameDynamicFeature],
+    })
+    async mapFeature(
+        @A_Inject(A_Caller) feature: A_FrameDynamicFeature,
+        @A_Inject(A_FrameMethodMapIndex) mapIndex: A_FrameMethodMapIndex,
+        @A_Inject(A_FrameIndex) frameIndex: A_FrameIndex,
+        @A_Inject(A_FrameChannel) channel: A_FrameChannel,
+    ): Promise<void> {
+
+        const def = feature.definition;
+        if (!def) return;
+
+        // ── helpers ──────────────────────────────────────────────────────────
+
+        const tryMatchStep = (
+            step: A_FrameDynamicFeatureStep,
+            minScore: number,
+        ): Pick<A_FrameDynamicFeatureStepMapEntry, 'matchedClass' | 'matchedMethod' | 'matchScore'> => {
+            if (!step.embedding?.length) {
+                return { matchedClass: null, matchedMethod: null, matchScore: 0 };
+            }
+            const results = frameIndex.search(new A_FrameVector(step.embedding), { topK: 1 });
+            const top = results[0];
+            if (top && top.score >= minScore) {
+                // Method definitions store name = "methodName" and dependency.name = "ClassName".
+                // Class definitions store both name and dependency.name as the class name.
+                const matchedClass = top.record.dependency.name;
+                const matchedMethod = top.record.name;
+                return { matchedClass, matchedMethod, matchScore: top.score };
+            }
+            return { matchedClass: null, matchedMethod: null, matchScore: top?.score ?? 0 };
+        };
+
+        const tryMatchElement = (
+            el: { prompt: string; class?: string; embedding?: number[] },
+            minScore: number,
+        ): Pick<A_FrameDynamicFeatureElementMapEntry, 'matchedClass' | 'matchScore'> => {
+            if (!el.embedding?.length) {
+                return { matchedClass: null, matchScore: 0 };
+            }
+            const results = frameIndex.search(new A_FrameVector(el.embedding), { topK: 1 });
+            const top = results[0];
+            if (top && top.score >= minScore) {
+                return { matchedClass: top.record.name, matchScore: top.score };
+            }
+            return { matchedClass: null, matchScore: top?.score ?? 0 };
+        };
+
+        const stripEmbeddings = (d: A_FrameDynamicFeatureDefinition): A_FrameDynamicFeatureDefinition => {
+            const strip = (el: any): any => { const { embedding, ...rest } = el; return rest; };
+            return {
+                ...d,
+                steps:      d.steps.map(strip),
+                components: d.components.map(strip),
+                fragments:  d.fragments.map(strip),
+                entities:   d.entities.map(strip),
+            };
+        };
+
+        const matchAll = (d: A_FrameDynamicFeatureDefinition): void => {
+            mapIndex.clear();
+            for (const step of d.steps) {
+                mapIndex.setStep({
+                    prompt:  step.prompt,
+                    inputs:  step.inputs,
+                    outputs: step.outputs,
+                    ...tryMatchStep(step, feature.minScore),
+                });
+            }
+            for (const el of d.components) {
+                mapIndex.setElement({ prompt: el.prompt, ...tryMatchElement(el, feature.minScore) });
+            }
+            for (const el of d.fragments) {
+                mapIndex.setElement({ prompt: el.prompt, ...tryMatchElement(el, feature.minScore) });
+            }
+            for (const el of d.entities) {
+                mapIndex.setElement({ prompt: el.prompt, ...tryMatchElement(el, feature.minScore) });
+            }
+        };
+
+        // ── initial matching pass ─────────────────────────────────────────────
+
+        let workingDef = def;
+        matchAll(workingDef);
+
+        // ── retry loop: refine unmatched steps via server patch ───────────────
+
+        for (let retry = 0; retry < feature.maxRetries; retry++) {
+            const unmatchedSteps = workingDef.steps.filter(
+                step => step.embedding?.length && mapIndex.getStep(step.prompt)?.matchedMethod === null,
+            );
+            if (unmatchedSteps.length === 0) break;
+
+            const refinementInstruction = [
+                `The following workflow steps could not be matched to any registered method.`,
+                `Please re-describe each step with more specific, method-oriented language:`,
+                unmatchedSteps.map(s => `- "${s.prompt}"`).join('\n'),
+            ].join('\n');
+
+            const patchReq = new A_FrameChannelRequest<A_FrameFeaturePatchResponse>(
+                'POST',
+                '/api/v1/feature/patch',
+                {
+                    originalPrompt:    feature.prompt,
+                    definition:        stripEmbeddings(workingDef),
+                    patchInstruction:  refinementInstruction,
+                    model:             feature.modelName,
+                    context:           feature.contextHint,
+                },
+            );
+
+            const patchScope = new A_Scope({
+                name: `A_FrameMethodMapper.mapFeature:retry${retry}`,
+                fragments: [patchReq],
+            }).inherit(A_Context.scope(channel));
+
+            await channel.call(A_FrameFeatures.Request, patchScope);
+            patchScope.destroy();
+
+            if (!patchReq.response) break;
+
+            workingDef = patchReq.response.definition;
+            matchAll(workingDef);
+        }
+
+        // ── finalize: mark remaining unmatched steps with an error ────────────
+
+        for (const step of workingDef.steps) {
+            const entry = mapIndex.getStep(step.prompt);
+            if (entry && entry.matchedMethod === null && step.embedding?.length) {
+                mapIndex.setStep({
+                    ...entry,
+                    matchError: {
+                        title: A_FrameDynamicFeatureError.MethodNotFound,
+                        description: `Unable to match "${step.prompt}" to any registered method after ${feature.maxRetries} retries.`,
+                    },
+                });
+            }
+        }
+
+        // ── hydrate the feature with the map result ───────────────────────────
+
+        feature.hydrateFromMap(mapIndex.toResult(workingDef));
+    }
+}

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

@@ -1,2 +1,7 @@
+export * from './A-FrameDynamicFeature.constants';
 export * from './A-FrameDynamicFeature.entity';
-export * from './A-FrameDynamicFeature.types';
+export * from './A-FrameDynamicFeature.types';
+export * from './A-FrameDynamicFeature.error';
+export * from './A-FrameDynamicFeatureOperation.context';
+export * from './A-FrameMethodMapIndex.context';
+export * from './A-FrameMethodMapper.component';

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

@@ -0,0 +1,2 @@
+export * from './A-FrameDynamicPatch.entity';
+export * from './A-FrameDynamicPatch.types';

package/src/lib/A-FrameDynamicStructure/A-FrameComponentMapIndex.context.ts

@@ -0,0 +1,99 @@
+import { A_Fragment } from "@adaas/a-concept";
+import {
+    A_FrameComponentMapEntry,
+    A_FrameComponentMapResult,
+    A_FrameDynamicStructureDefinition,
+    A_FrameDynamicStructureDefinitionEntity,
+} from "./A-FrameDynamicStructure.types";
+
+
+/**
+ * Context fragment that accumulates component-mapping results produced by
+ * `A_FrameComponentMapper.mapStructure()`.
+ *
+ * Uses a flat `prompt → A_FrameComponentMapEntry` map so lookups are O(1).
+ * Call `toResult(definition)` after the mapper has finished to build the
+ * structured `A_FrameComponentMapResult` that mirrors the definition layout.
+ */
+export class A_FrameComponentMapIndex extends A_Fragment {
+
+    private _entries: Map<string, A_FrameComponentMapEntry> = new Map();
+
+    constructor() {
+        super({ name: 'a-frame-component-map-index' });
+    }
+
+    // ── Basic mutation ───────────────────────────────────────────────────────
+
+    /**
+     * Store (or overwrite) a map entry for the element identified by `entry.prompt`.
+     */
+    set(entry: A_FrameComponentMapEntry): void {
+        this._entries.set(entry.prompt, entry);
+    }
+
+    /**
+     * Retrieve the map entry for the given prompt, or `undefined` if not yet stored.
+     */
+    get(prompt: string): A_FrameComponentMapEntry | undefined {
+        return this._entries.get(prompt);
+    }
+
+    /** Remove all stored entries. */
+    clear(): void {
+        this._entries.clear();
+    }
+
+    // ── Accessors ────────────────────────────────────────────────────────────
+
+    /** Total number of stored entries. */
+    get size(): number {
+        return this._entries.size;
+    }
+
+    /** All stored entries in insertion order. */
+    list(): A_FrameComponentMapEntry[] {
+        return Array.from(this._entries.values());
+    }
+
+    /** Entries that have been successfully matched to a registered class. */
+    get matched(): A_FrameComponentMapEntry[] {
+        return this.list().filter(e => e.matchedClass !== null);
+    }
+
+    /** Entries where no matching registered class was found. */
+    get unmatched(): A_FrameComponentMapEntry[] {
+        return this.list().filter(e => e.matchedClass === null);
+    }
+
+    // ── Result building ──────────────────────────────────────────────────────
+
+    /**
+     * Construct a fully structured `A_FrameComponentMapResult` from the
+     * accumulated entries and the provided definition.
+     *
+     * For each element in the definition the method looks up its entry by
+     * prompt.  If no entry exists (element had no server embedding), a default
+     * unmatched entry is generated so the result shape always matches the
+     * definition shape.
+     */
+    toResult(definition: A_FrameDynamicStructureDefinition): A_FrameComponentMapResult {
+        const getEntry = (el: A_FrameDynamicStructureDefinitionEntity): A_FrameComponentMapEntry => {
+            const existing = this._entries.get(el.prompt);
+            if (existing) return existing;
+            return { prompt: el.prompt, role: el.role, class: el.class, matchedClass: null, matchScore: 0 };
+        };
+
+        return {
+            containers: definition.containers.map(c => ({
+                ...getEntry(c),
+                components: (c.components ?? []).map(getEntry),
+                fragments:  (c.fragments  ?? []).map(getEntry),
+                entities:   (c.entities   ?? []).map(getEntry),
+            })),
+            components: definition.components.map(getEntry),
+            fragments:  definition.fragments.map(getEntry),
+            entities:   definition.entities.map(getEntry),
+        };
+    }
+}