@adaas/a-frame 0.0.23 → 0.1.2

package/examples/interaction/main.ts

@@ -0,0 +1,426 @@
+/**
+ * Interactive Article Workshop
+ *
+ * A collaborative article builder where you and the AI work together.
+ * The article renders in full after each step. You type corrections,
+ * additions, or rewrites — the AI patches the content and re-renders.
+ *
+ * Usage:
+ *   npx ts-node interactive-article.ts
+ *
+ * Flow:
+ *   1. You enter a topic
+ *   2. The article is generated and rendered section-by-section
+ *   3. You see the full rendered article
+ *   4. You type a correction ("make the intro shorter", "add a stats section")
+ *   5. The AI patches the content, re-maps, and re-renders the full article
+ *   6. Repeat until you type "done"
+ *
+ * All diagnostic logs go to logs/<timestamp>.log
+ */
+
+import { A_Component, A_Concept, A_Container, A_Error } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { A_FrameIndex } from '@adaas/a-frame/index';
+import { A_FrameSegment } from '@adaas/a-frame/segment';
+import { A_FrameSchema } from '@adaas/a-frame/schema';
+import { A_FrameCompletion } from '@adaas/a-frame/completion';
+import { A_FrameDynamicContent } from '@adaas/a-frame/dynamic-content';
+import { config } from 'dotenv';
+import { createInterface } from 'readline';
+import { FileLogger } from '../logger';
+import { ALL_COMPONENTS, Paragraph, RENDERERS } from '../components';
+
+config();
+process.env.A_FRAME_SYNC = 'false';
+
+const MAX_RETRIES = 2;
+const MIN_SCORE = 0.50;
+
+// ─── Component selector prompt (bridge: generated content → semantic search query) ──
+
+const COMPONENT_SELECTOR_SYSTEM = [
+    'You are a UI component selector. Given a piece of article content, describe in 1–2 sentences',
+    'the most appropriate visual UI component to display it.',
+    'Available types: Title/Headline, Paragraph, Profile Card (entity attributes), Bar Chart (comparative numbers),',
+    'Data Table (attribute-value pairs), Stat Callout (single prominent figure + context),',
+    'Bulleted List, Image Block (scene description).',
+    'Output ONLY the component description. No preamble, no markdown, no punctuation at end.',
+    'Example: "A bar chart component showing comparative numerical values across named categories"',
+].join('\n');
+
+// ─── Terminal colors ──────────────────────────────────────────────────────────
+
+const ESC = '\x1b[';
+const S = {
+    reset: `${ESC}0m`, bold: `${ESC}1m`, dim: `${ESC}2m`, italic: `${ESC}3m`,
+    cyan: `${ESC}36m`, bcyan: `${ESC}96m`, green: `${ESC}32m`, bgreen: `${ESC}92m`,
+    yellow: `${ESC}33m`, blue: `${ESC}34m`, bblue: `${ESC}94m`, magenta: `${ESC}35m`,
+    red: `${ESC}31m`, gray: `${ESC}90m`, white: `${ESC}37m`,
+};
+const c = (s: string, ...st: string[]) => st.join('') + s + S.reset;
+const CLEAR = '\x1b[2J\x1b[H';
+
+type P = { content: string } & Record<string, string | undefined>;
+
+function wrap(text: string, w = 72): string[] {
+    const words = text.split(/\s+/);
+    const lines: string[] = [];
+    let line = '';
+    for (const word of words) {
+        const next = line ? `${line} ${word}` : word;
+        if (next.length > w) { if (line) lines.push(line); line = word; } else line = next;
+    }
+    if (line) lines.push(line);
+    return lines;
+}
+
+// ─── Section parsing ──────────────────────────────────────────────────────────
+
+const SECTION_RE = /===SECTION:\s*(\w+):\s*(.+?)===\n([\s\S]*?)(?=\n===SECTION:|$)/g;
+
+interface ParsedSection {
+    type: string;
+    title: string;
+    body: string;
+}
+
+interface MappedSection extends ParsedSection {
+    component: string;
+    score: number;
+    params: P;
+}
+
+function parseSections(text: string): ParsedSection[] {
+    const out: ParsedSection[] = [];
+    SECTION_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = SECTION_RE.exec(text)) !== null) {
+        const body = m[3].trim();
+        if (body) out.push({ type: m[1].trim().toLowerCase(), title: m[2].trim(), body });
+    }
+    if (!out.length && text.trim()) {
+        text.split(/\n{2,}/).map(p => p.trim()).filter(Boolean).forEach((p, i) => {
+            out.push({ type: i === 0 ? 'heading' : 'paragraph', title: `Section ${i + 1}`, body: p });
+        });
+    }
+    return out;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function parseJson<T>(raw: string | undefined, label: string): T {
+    if (!raw?.trim()) throw new Error(`${label}: empty`);
+    const m = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    return JSON.parse((m ? m[1] : raw).trim()) as T;
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise(r => setTimeout(r, ms));
+}
+
+// ─── Map all sections to components ───────────────────────────────────────────
+
+async function mapAllSections(
+    sections: ParsedSection[],
+    index: A_FrameIndex,
+    container: A_Container,
+    log: FileLogger,
+): Promise<MappedSection[]> {
+    const mapped: MappedSection[] = [];
+
+    for (const sec of sections) {
+        let mapMs = Date.now();
+        let success = false;
+
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                // 1. LLM component selector: describe the best visual component for this content
+                const selector = new A_FrameCompletion({
+                    prompt: sec.body.slice(0, 400),
+                    options: { system: COMPONENT_SELECTOR_SYSTEM,  max_tokens: 80 },
+                });
+                container.scope.register(selector);
+                await selector.generate();
+
+                const componentQuery = selector.text?.trim() ?? sec.body.slice(0, 200);
+                log.prompt(`COMPONENT QUERY [${sec.title}]`, sec.body.slice(0, 100), componentQuery);
+
+                // 2. Embed the component descriptor and search the index
+                const contentSegment = new A_FrameSegment({ content: componentQuery });
+                container.scope.register(contentSegment);
+                await contentSegment.embed();
+
+                const results = index.search(contentSegment.vector!, { topK: 3 });
+
+                log.searchResults(sec.body.slice(0, 80), results.map(r => ({
+                    name: r.record.name,
+                    score: r.score,
+                    description: r.record.description,
+                })));
+
+                const best = results[0];
+                if (!best || best.score < MIN_SCORE) {
+                    log.warn(`Score too low for "${sec.title}": ${best?.score.toFixed(3) ?? 'none'} < ${MIN_SCORE}`);
+                    if (attempt < MAX_RETRIES) { await sleep(400); continue; }
+                }
+
+                // 3. Extract draw params via A_FrameSchema
+                let params: P = { content: sec.body };
+                const meta = (best?.record.metadata as any)?.params as Record<string, string> | undefined;
+
+                if (meta && Object.keys(meta).length > 0) {
+                    try {
+                        const schemaDescriptor: Record<string, string> = {};
+                        for (const [k, v] of Object.entries(meta)) schemaDescriptor[k] = String(v);
+
+                        const extractor = new A_FrameSchema({
+                            prompt: sec.body.slice(0, 500),
+                            schema: schemaDescriptor,
+                        });
+                        container.scope.register(extractor);
+                        await extractor.extract();
+
+                        params = { content: sec.body, ...(extractor.data as Record<string, string> ?? {}) };
+
+                        log.prompt(`EXTRACT [${sec.title}]`, sec.body.slice(0, 100), JSON.stringify(extractor.data));
+                    } catch (e) {
+                        log.error(`Param extraction failed for "${sec.title}" — using raw content`, e);
+                    }
+                }
+
+                mapped.push({
+                    ...sec,
+                    component: best?.record.name ?? 'Paragraph',
+                    score: best?.score ?? 0,
+                    params,
+                });
+
+                log.mapped({
+                    title: sec.title,
+                    type: sec.type,
+                    component: best?.record.name ?? 'Paragraph',
+                    score: best?.score ?? 0,
+                    params,
+                    ms: Date.now() - mapMs,
+                });
+
+                success = true;
+                break;
+
+            } catch (err) {
+                log.error(`Map attempt ${attempt} failed for "${sec.title}"`, err);
+                if (attempt < MAX_RETRIES) await sleep(400 * attempt);
+            }
+        }
+
+        if (!success) {
+            log.error(`Section "${sec.title}" failed to map after ${MAX_RETRIES} attempts`);
+            mapped.push({ ...sec, component: 'Paragraph', score: 0, params: { content: sec.body } });
+        }
+    }
+
+    return mapped;
+}
+
+// ─── Full article renderer ───────────────────────────────────────────────────
+
+function renderArticle(mapped: MappedSection[], revision: number): void {
+    process.stdout.write(CLEAR);
+
+    // Header bar
+    const revLabel = revision === 0 ? 'initial draft' : `revision ${revision}`;
+    console.log(c(`  ╸ ${revLabel}  ·  ${mapped.length} sections`, S.dim));
+    console.log(c('━'.repeat(72), S.gray));
+
+    for (const sec of mapped) {
+        const renderer = RENDERERS.get(sec.component);
+        if (renderer) {
+            renderer(sec.params);
+        } else {
+            Paragraph.render(sec.params);
+        }
+    }
+
+    // Footer
+    console.log(c(`\n${'━'.repeat(72)}`, S.gray));
+}
+
+// ─── Readline helper ──────────────────────────────────────────────────────────
+
+function createPromptInterface() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q: string): Promise<string> => new Promise(res => rl.question(q, res));
+    return { rl, ask };
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+    const { rl, ask } = createPromptInterface();
+
+    process.stdout.write(CLEAR);
+    console.log(c('\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Interactive Article Workshop                    ', S.bold) + c('┃', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Generate → Render → Patch → Repeat              ', S.dim) + c('┃', S.bcyan));
+    console.log(c('  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛', S.bcyan));
+
+    const topic = await ask(c('\n  What should the article be about?\n  ▸ ', S.bcyan));
+    if (!topic.trim()) { console.log('  No topic given.'); rl.close(); return; }
+
+    const log = new FileLogger(topic);
+
+    console.log(c(`\n  Setting up…`, S.dim));
+
+    // ── Framework setup ───────────────────────────────────────────────────
+
+    const container = new A_Container({ name: 'ArticleUI', components: ALL_COMPONENTS });
+    const concept = new A_Concept({
+        name: 'InteractiveArticle',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+
+    const index = concept.scope.resolve(A_FrameIndex)!;
+
+    for (const d of index.listDefinitions()) await d.embed();
+    log.info('Setup complete', { components: ALL_COMPONENTS.length, indexSize: index.indexSize });
+
+    // ── Generate initial article ──────────────────────────────────────────
+
+    console.log(c(`  Generating article about "${topic}"…\n`, S.dim));
+
+    const articlePrompt = [
+        `Write an engaging article about: "${topic}".`,
+        '',
+        'FORMAT: wrap each section with ===SECTION: <type>: <title>===',
+        'Available types: heading, paragraph, profile_card, bar_chart, data_table, stat_callout, list, quote',
+        '',
+        'Content rules per type:',
+        '- heading: single title line, no markdown #',
+        '- paragraph: 2–4 sentences of prose',
+        '- profile_card: entity name on first line, then "Label: value" lines',
+        '- bar_chart: "Category: number" lines',
+        '- data_table: "Attribute | Value" lines',
+        '- stat_callout: one number/fact on first line, context on second',
+        '- list: short items, one per line, with dashes',
+        '- quote: a notable quote or key excerpt',
+        '',
+        'Use 6–10 sections with varied types. Never repeat the same type twice in a row.',
+        'Do NOT use any markdown headings (#). Write only body content after each marker.',
+    ].join('\n');
+
+    const content = new A_FrameDynamicContent({
+        prompt: articlePrompt,
+    });
+    container.scope.register(content);
+
+    const t0 = Date.now();
+    await content.generate();
+    log.prompt('GENERATE', articlePrompt, content.text, Date.now() - t0);
+
+    if (!content.text?.trim()) {
+        console.log(c('  ✗ Generation failed — empty response.', S.red));
+        rl.close();
+        return;
+    }
+
+    // ── Initial render ────────────────────────────────────────────────────
+
+    let sections = parseSections(content.text!);
+    log.info('Parsed sections', { count: sections.length, titles: sections.map(s => s.title) });
+
+    let mapped = await mapAllSections(sections, index, container, log);
+    let revision = 0;
+
+    renderArticle(mapped, revision);
+
+    // ── Interactive loop ──────────────────────────────────────────────────
+
+    console.log(c('  Commands:', S.dim));
+    console.log(c('    Type a correction to patch the article', S.dim));
+    console.log(c('    "done" to exit  ·  "redraw" to refresh  ·  "raw" to see source\n', S.dim));
+
+    while (true) {
+        const input = await ask(c('  ▸ ', S.yellow));
+        const cmd = input.trim();
+
+        if (!cmd) continue;
+
+        // Exit
+        if (cmd.toLowerCase() === 'done' || cmd.toLowerCase() === 'exit' || cmd.toLowerCase() === 'quit') {
+            console.log(c(`\n  ✓ Final article: ${mapped.length} sections, ${revision} revision(s)`, S.green));
+            console.log(c(`  ✓ Log saved: ${log.path}\n`, S.dim));
+            break;
+        }
+
+        // Redraw
+        if (cmd.toLowerCase() === 'redraw') {
+            renderArticle(mapped, revision);
+            continue;
+        }
+
+        // Show raw source
+        if (cmd.toLowerCase() === 'raw') {
+            process.stdout.write(CLEAR);
+            console.log(c('  ╸ raw article source\n', S.dim));
+            console.log(c(content.text?.slice(0, 2000) ?? '(empty)', S.gray));
+            console.log(c(`\n  … (${content.text?.length ?? 0} chars total)\n`, S.dim));
+            continue;
+        }
+
+        // Patch
+        log.header('PATCH REQUEST', { input: cmd, revision: revision + 1 });
+
+        console.log(c('  Applying changes…', S.dim));
+
+        try {
+            const patchInstruction = [
+                cmd,
+                '',
+                'Keep the ===SECTION: type: title=== format for all sections.',
+                'Preserve sections that don\'t need changes.',
+            ].join('\n');
+
+            const pt0 = Date.now();
+            await content.patch(patchInstruction);
+            const patchMs = Date.now() - pt0;
+
+            log.prompt('PATCH', patchInstruction, content.text, patchMs);
+
+            if (!content.text?.trim()) {
+                console.log(c('  ⚠ Patch returned empty — keeping previous version.', S.yellow));
+                continue;
+            }
+
+            sections = parseSections(content.text!);
+            log.info('Re-parsed after patch', { count: sections.length, titles: sections.map(s => s.title) });
+
+            mapped = await mapAllSections(sections, index, container, log);
+            revision++;
+
+            renderArticle(mapped, revision);
+
+            console.log(c(`  ✓ Revision ${revision} applied (${patchMs}ms)`, S.green));
+            console.log(c(`  ${sections.length} sections mapped\n`, S.dim));
+
+        } catch (err) {
+            log.error('Patch failed', err);
+            const msg = err instanceof Error ? err.message : String(err);
+            console.log(c(`  ✗ Patch failed: ${msg.slice(0, 80)}`, S.red));
+            console.log(c('  Previous version preserved. Try a different instruction.\n', S.dim));
+        }
+    }
+
+    rl.close();
+}
+
+main().catch((err) => {
+    if (err instanceof A_Error) {
+        console.error(c('\n  ✗ A_Error:', S.red), JSON.stringify(err.toJSON(), null, 2));
+    } else {
+        console.error(c('\n  ✗ Error:', S.red), err);
+    }
+    process.exit(1);
+});

package/examples/logger.ts

@@ -0,0 +1,126 @@
+/**
+ * FileLogger — writes detailed structured logs to a file for post-run analysis.
+ *
+ * All terminal output from the main example is visual-only; every diagnostic
+ * detail (prompts, raw responses, embeddings, scores, timings, errors) goes here.
+ */
+
+import { writeFileSync, appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+export class FileLogger {
+    readonly path: string;
+    private startMs: number;
+
+    constructor(topic: string) {
+        mkdirSync('.logs', { recursive: true });
+
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const slug = topic.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
+        this.path = join('.logs', `${ts}_${slug}.log`);
+        this.startMs = Date.now();
+
+        writeFileSync(this.path, '');
+        this.header('SESSION START', {
+            topic,
+            timestamp: new Date().toISOString(),
+            pid: process.pid,
+        });
+    }
+
+    /** Elapsed ms since logger creation */
+    private elapsed(): string {
+        const ms = Date.now() - this.startMs;
+        return ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${ms}ms`;
+    }
+
+    /** Write a raw line */
+    private write(line: string): void {
+        appendFileSync(this.path, line + '\n');
+    }
+
+    /** Section header */
+    header(title: string, meta?: Record<string, unknown>): void {
+        this.write(`\n${'═'.repeat(80)}`);
+        this.write(`  ${title}  [${this.elapsed()}]`);
+        this.write('═'.repeat(80));
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                this.write(`  ${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
+            }
+        }
+        this.write('');
+    }
+
+    /** Informational log */
+    info(message: string, data?: Record<string, unknown>): void {
+        this.write(`[${this.elapsed()}] INFO  ${message}`);
+        if (data) {
+            for (const [k, v] of Object.entries(data)) {
+                const val = typeof v === 'string' ? v : JSON.stringify(v, null, 2);
+                // Indent multi-line values
+                const indented = val.split('\n').map((l, i) => i === 0 ? l : `         ${l}`).join('\n');
+                this.write(`    ${k}: ${indented}`);
+            }
+        }
+    }
+
+    /** Prompt/response pair */
+    prompt(label: string, promptText: string, response?: string, durationMs?: number): void {
+        this.write(`\n[${this.elapsed()}] PROMPT  ${label}${durationMs != null ? `  (${durationMs}ms)` : ''}`);
+        this.write(`  ┌─ prompt ${'─'.repeat(68)}`);
+        for (const line of promptText.split('\n')) {
+            this.write(`  │ ${line}`);
+        }
+        this.write(`  └${'─'.repeat(76)}`);
+        if (response != null) {
+            this.write(`  ┌─ response ${'─'.repeat(66)}`);
+            for (const line of response.split('\n')) {
+                this.write(`  │ ${line}`);
+            }
+            this.write(`  └${'─'.repeat(76)}`);
+        }
+    }
+
+    /** Index search results */
+    searchResults(query: string, results: Array<{ name: string; score: number; description?: string }>): void {
+        this.write(`\n[${this.elapsed()}] SEARCH`);
+        this.write(`  query: "${query.slice(0, 120)}"`);
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            this.write(`  [${i + 1}] ${r.score.toFixed(4)}  ${r.name}  — ${r.description?.slice(0, 60) ?? ''}`);
+        }
+    }
+
+    /** Error */
+    error(message: string, err?: unknown): void {
+        this.write(`\n[${this.elapsed()}] ERROR  ${message}`);
+        if (err instanceof Error) {
+            this.write(`  ${err.message}`);
+            if (err.stack) {
+                for (const line of err.stack.split('\n').slice(1, 5)) {
+                    this.write(`  ${line.trim()}`);
+                }
+            }
+        } else if (err != null) {
+            this.write(`  ${String(err)}`);
+        }
+    }
+
+    /** Warn */
+    warn(message: string): void {
+        this.write(`[${this.elapsed()}] WARN   ${message}`);
+    }
+
+    /** Section mapping result */
+    mapped(section: { title: string; type: string; component: string; score: number; params?: Record<string, unknown>; ms: number }): void {
+        this.write(`\n[${this.elapsed()}] MAPPED  "${section.title}"`);
+        this.write(`  type:      ${section.type}`);
+        this.write(`  component: ${section.component}`);
+        this.write(`  score:     ${section.score.toFixed(4)}`);
+        this.write(`  time:      ${section.ms}ms`);
+        if (section.params) {
+            this.write(`  params:    ${JSON.stringify(section.params)}`);
+        }
+    }
+}