@aikdna/kdna-core 0.1.0

package/src/loader.js

@@ -0,0 +1,263 @@
+/**
+ * KDNA Core Loader — Pure logic for loading KDNA domain cognition.
+ *
+ * No fs, no path, no Node.js dependencies.
+ * Data-first API: accepts already-parsed JSON objects.
+ */
+
+const FILE_MAP = {
+  core: 'KDNA_Core.json',
+  patterns: 'KDNA_Patterns.json',
+  scenarios: 'KDNA_Scenarios.json',
+  cases: 'KDNA_Cases.json',
+  reasoning: 'KDNA_Reasoning.json',
+  evolution: 'KDNA_Evolution.json',
+};
+
+/**
+ * Load the minimum required KDNA data from already-parsed objects.
+ * @param {object} coreData — parsed KDNA_Core.json
+ * @param {object} patternsData — parsed KDNA_Patterns.json
+ * @returns {object|null}
+ */
+function loadCorePatternsFromData(coreData, patternsData) {
+  if (!coreData || !patternsData) return null;
+  return { core: coreData, patterns: patternsData };
+}
+
+/**
+ * Load a complete KDNA domain from a map of already-parsed data.
+ *
+ * @param {Object} dataMap — keyed by file type: { core, patterns, scenarios?, cases?, reasoning?, evolution? }
+ * @param {object} [options]
+ * @param {string} [options.input] — user input text for conditional loading
+ * @param {'all'|'minimum'|'auto'} [options.mode='auto']
+ * @returns {object|null}
+ */
+function loadDomainFromData(dataMap, options = {}) {
+  const { input = '', mode = 'auto' } = options;
+
+  const base = loadCorePatternsFromData(dataMap.core, dataMap.patterns);
+  if (!base) return null;
+
+  const result = { ...base };
+
+  if (mode === 'minimum') return result;
+
+  const toLoad =
+    mode === 'all'
+      ? ['scenarios', 'cases', 'reasoning', 'evolution']
+      : classifyInput(input);
+
+  for (const key of toLoad) {
+    if (dataMap[key]) result[key] = dataMap[key];
+  }
+
+  return result;
+}
+
+/**
+ * Load a KDNA domain from a map keyed by filename.
+ * Converts filename keys to type keys, then delegates to loadDomainFromData.
+ *
+ * @param {Object} fileDataMap — e.g. { 'KDNA_Core.json': parsedObj, 'KDNA_Patterns.json': parsedObj, ... }
+ * @param {object} [options] — same as loadDomainFromData
+ * @returns {object|null}
+ */
+function loadDomainFromFiles(fileDataMap, options = {}) {
+  const dataMap = {};
+  for (const [key, filename] of Object.entries(FILE_MAP)) {
+    if (fileDataMap[filename]) dataMap[key] = fileDataMap[filename];
+  }
+  return loadDomainFromData(dataMap, options);
+}
+
+/**
+ * Determine which optional files to load based on user input text.
+ * Pure function — no side effects.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function classifyInput(text) {
+  const lower = (text || '').toLowerCase();
+  const optional = [];
+
+  if (
+    /\b(situation|scenario|conflict|happened|tell\s+me\s+about|describe|instance|specific)\b/.test(
+      lower,
+    ) ||
+    /(情况|场景|冲突|发生了什么|具体|描述一下|谈谈|说说看)/.test(text || '')
+  ) {
+    optional.push('scenarios');
+  }
+
+  if (
+    /\b(example|demonstrat|full\s+case|show\s+me|sample|illustrate|walk\s+through|case)\b/.test(
+      lower,
+    ) ||
+    /(案例|示例|演示|展示一下|完整案例|示范|讲解|举例|举个)/.test(text || '')
+  ) {
+    optional.push('cases');
+  }
+
+  if (
+    /\b(why|rationale|principle|explain|reason|logic|how\s+come|cause)\b/.test(lower) ||
+    /(为什么|原理|逻辑|解释|理由|原因|推理|依据)/.test(text || '')
+  ) {
+    optional.push('reasoning');
+  }
+
+  if (
+    /\b(practice|improv|learn|grow|level|progress|measur|assess|evaluat|benchmark)\b/.test(lower) ||
+    /(练习|提高|学习|成长|水平|进度|评估|测量|改进|提升|训练)/.test(text || '')
+  ) {
+    optional.push('evolution');
+  }
+
+  return [...new Set(optional)];
+}
+
+/**
+ * Format a loaded KDNA domain into a context string suitable for
+ * inclusion in an agent's system prompt.
+ *
+ * @param {object} domain — result from loadDomainFromData() or loadDomainFromFiles()
+ * @returns {string}
+ */
+function formatContext(domain) {
+  if (!domain || !domain.core || !domain.patterns) return '';
+
+  const parts = [];
+  const core = domain.core;
+  const pat = domain.patterns;
+
+  parts.push('## Domain Cognition (KDNA)');
+  parts.push(`Domain: ${core.meta.domain}`);
+  parts.push('');
+
+  if (core.stances && core.stances.length) {
+    parts.push('### Stances');
+    for (const s of core.stances) {
+      parts.push(`- ${s}`);
+    }
+    parts.push('');
+  }
+
+  if (core.axioms && core.axioms.length) {
+    parts.push('### Axioms');
+    for (const a of core.axioms) {
+      parts.push(`- **${a.one_sentence}** ${a.full_statement}`);
+      parts.push(`  *Why:* ${a.why}`);
+    }
+    parts.push('');
+  }
+
+  if (core.ontology && core.ontology.length) {
+    parts.push('### Key Concepts');
+    for (const c of core.ontology) {
+      parts.push(`- **${c.id.replace(/_/g, ' ')}** — ${c.one_sentence}`);
+      parts.push(`  Boundary: ${c.boundary}`);
+    }
+    parts.push('');
+  }
+
+  if (core.frameworks && core.frameworks.length) {
+    parts.push('### Frameworks');
+    for (const fw of core.frameworks) {
+      parts.push(`- **${fw.name}**: ${fw.when_to_use}`);
+    }
+    parts.push('');
+  }
+
+  if (pat.terminology && pat.terminology.banned_terms && pat.terminology.banned_terms.length) {
+    parts.push('### Avoid These Terms');
+    for (const b of pat.terminology.banned_terms) {
+      parts.push(`- Avoid "${b.term}". ${b.why} Use "${b.replace_with}" instead.`);
+    }
+    parts.push('');
+  }
+
+  if (pat.misunderstandings && pat.misunderstandings.length) {
+    parts.push('### Watch For These Misunderstandings');
+    for (const m of pat.misunderstandings) {
+      parts.push(`- **Wrong:** ${m.wrong}`);
+      parts.push(`  **Correct:** ${m.correct}`);
+    }
+    parts.push('');
+  }
+
+  if (pat.self_check && pat.self_check.length) {
+    parts.push('### Before Responding, Check');
+    for (const s of pat.self_check) {
+      parts.push(`- [ ] ${s}`);
+    }
+    parts.push('');
+  }
+
+  if (domain.scenarios && domain.scenarios.scenes) {
+    parts.push('### Relevant Scenarios');
+    for (const scene of domain.scenarios.scenes) {
+      parts.push(`- **${scene.name}**: ${scene.trigger_signal}`);
+    }
+    parts.push('');
+  }
+
+  if (domain.reasoning && domain.reasoning.reasoning_chains) {
+    parts.push('### Reasoning Chains');
+    for (const r of domain.reasoning.reasoning_chains) {
+      parts.push(`- **${r.one_sentence}** → ${r.so_what}`);
+    }
+    parts.push('');
+  }
+
+  if (domain.cases && domain.cases.cases && domain.cases.cases.length) {
+    parts.push('### Cases');
+    for (const c of domain.cases.cases) {
+      parts.push(`- **${c.title}**`);
+      parts.push(`  Context: ${c.context}`);
+      parts.push(`  What happened: ${c.what_happened}`);
+      parts.push(`  Learned: ${c.what_was_learned}`);
+      parts.push(`  Pattern: ${c.structural_pattern}`);
+    }
+    parts.push('');
+  }
+
+  if (domain.evolution) {
+    const evo = domain.evolution;
+    if (evo.stages && evo.stages.length) {
+      parts.push('### Growth Stages');
+      for (const stage of evo.stages) {
+        parts.push(`- **${stage.name}**: ${stage.description}`);
+      }
+      parts.push('');
+    }
+    if (evo.evolution_layers && evo.evolution_layers.length) {
+      parts.push('### Capability Layers');
+      for (const layer of evo.evolution_layers) {
+        parts.push(
+          `- **${layer.name}**: ${layer.capability} (${layer.from_stage} → ${layer.to_stage})`,
+        );
+      }
+      parts.push('');
+    }
+    if (evo.measurement && evo.measurement.length) {
+      parts.push('### Measurement');
+      for (const m of evo.measurement) {
+        parts.push(`- **${m.what}**: ${m.how} (threshold: ${m.threshold})`);
+      }
+      parts.push('');
+    }
+  }
+
+  return parts.join('\n').trim();
+}
+
+module.exports = {
+  FILE_MAP,
+  loadCorePatternsFromData,
+  loadDomainFromData,
+  loadDomainFromFiles,
+  classifyInput,
+  formatContext,
+};

package/src/render.js

@@ -0,0 +1,111 @@
+/**
+ * KDNA Render — Pure HTML rendering for KDNA domain preview.
+ *
+ * No fs, no path, no Node.js dependencies.
+ * Takes a loaded domain object and optional manifest, returns HTML string.
+ */
+
+/**
+ * Escape HTML special characters.
+ * @param {string} s
+ * @returns {string}
+ */
+function escHtml(s) {
+  return (s || '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Render a card section.
+ * @param {string} title
+ * @param {number|undefined} count
+ * @param {string} items — HTML string of card items
+ * @returns {string}
+ */
+function renderCard(title, count, items) {
+  if (!count || !items) return '';
+  return `<div class="card"><h3>${title} <span>${count}</span></h3>${items}</div>`;
+}
+
+/**
+ * Render a full KDNA domain as a preview HTML page.
+ *
+ * @param {object} domain — loaded domain from loadDomainFromData() / loadDomainFromFiles()
+ * @param {object} [manifest] — parsed kdna.json manifest
+ * @returns {string} complete HTML document
+ */
+function renderPreviewHTML(domain, manifest) {
+  if (!domain || !domain.core) return '<!DOCTYPE html><html><body><p>No domain data</p></body></html>';
+
+  const core = domain.core;
+  const patterns = domain.patterns;
+  const scenarios = domain.scenarios;
+  const cases = domain.cases;
+  const reasoning = domain.reasoning;
+  const evolution = domain.evolution;
+
+  const name = manifest?.name || core.meta?.domain || 'Unnamed Domain';
+  const version = manifest?.version || core.meta?.version || '?';
+  const status = manifest?.status || 'experimental';
+  const desc = manifest?.description || core.meta?.purpose || '';
+
+  // Count present files
+  const fileCount = ['core', 'patterns', 'scenarios', 'cases', 'reasoning', 'evolution']
+    .filter((k) => domain[k])
+    .length;
+
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>${escHtml(name)} — KDNA Preview</title>
+<style>
+:root{--bg:#08100d;--bg2:#0d1713;--border:#24352b;--text:#f0ead7;--dim:#c3baa0;--muted:#8b836c;--accent:#d1ad63;--green:#76b987;--red:#df806d;--blue:#8fa7d7;--sans:Inter,system-ui,sans-serif;--mono:SF Mono,monospace}
+*{box-sizing:border-box;margin:0;padding:0}body{background:var(--bg);color:var(--text);font-family:var(--sans);line-height:1.6;max-width:960px;margin:0 auto;padding:40px 24px}
+.meta{display:flex;flex-wrap:wrap;gap:16px;align-items:center;padding:20px 24px;border:1px solid var(--border);border-radius:10px;background:var(--bg2);margin-bottom:24px}
+.meta .name{font-size:24px;font-weight:700}
+.meta .ver{color:var(--muted);font-size:14px}
+.meta .badge{padding:3px 12px;border-radius:999px;font-size:11px;font-weight:700}
+.badge-ok{background:rgba(118,185,135,.15);color:var(--green)}
+.badge-warn{background:rgba(209,173,99,.15);color:var(--accent)}
+.desc{color:var(--dim);margin:16px 0 24px;font-size:15px;line-height:1.7}
+.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(380px,1fr));gap:14px}
+.card{border:1px solid var(--border);border-radius:10px;background:var(--bg2);padding:20px}
+.card h3{font-size:12px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em;margin-bottom:14px;display:flex;justify-content:space-between}
+.card h3 span{color:var(--dim);font-weight:400}
+.card .item{padding:10px 0;border-bottom:1px solid rgba(36,53,43,.5)}
+.card .item:last-child{border-bottom:0}
+.card .item strong{display:block;font-size:14px;margin-bottom:2px}
+.card .item .detail{font-size:13px;color:var(--dim);line-height:1.5}
+.card .item .meta{font-size:11px;color:var(--muted);margin-top:2px;padding:0;border:0;background:transparent;margin-bottom:0}
+.card .item .why{color:var(--red);font-size:12px}
+.card .item .replace{color:var(--green);font-size:12px}
+.footer{text-align:center;color:var(--muted);margin-top:40px;font-size:13px}
+.footer a{color:var(--accent)}
+@media(max-width:680px){.cards{grid-template-columns:1fr}}
+</style></head><body>
+<h1 style="font-size:14px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em;margin-bottom:16px">KDNA Domain Preview</h1>
+<div class="meta">
+  <span class="name">${escHtml(name)}</span>
+  <span class="ver">v${escHtml(version)}</span>
+  <span class="badge badge-${status === 'validated' || status === 'stable' ? 'ok' : 'warn'}">${escHtml(status)}</span>
+  <span style="color:var(--dim);font-size:13px">${fileCount} files</span>
+</div>
+${desc ? `<p class="desc">${escHtml(desc)}</p>` : ''}
+<div class="cards">
+${renderCard('Axioms', core.axioms?.length, (core.axioms || []).map((a) => `<div class="item"><strong>${escHtml(a.one_sentence || '')}</strong><div class="detail">${escHtml(a.full_statement || a.why || '')}</div></div>`).join(''))}
+${renderCard('Concepts', core.ontology?.length, (core.ontology || []).map((o) => `<div class="item"><strong>${escHtml(o.one_sentence || o.id || '')}</strong><div class="detail">${escHtml(o.essence || '')}</div><div class="meta">Boundary: ${escHtml(o.boundary || '')}</div></div>`).join(''))}
+${renderCard('Frameworks', core.frameworks?.length, (core.frameworks || []).map((f) => `<div class="item"><strong>${escHtml(f.name || '')}</strong><div class="detail">When: ${escHtml(f.when_to_use || '')}</div><div class="detail">Steps: ${(f.steps || []).map((s) => escHtml(s)).join(' → ')}</div></div>`).join(''))}
+${renderCard('Stances', core.stances?.length, (core.stances || []).map((s) => `<div class="item"><strong>${escHtml(typeof s === 'string' ? s : s.one_sentence || '')}</strong></div>`).join(''))}
+${renderCard('Banned Terms', patterns?.terminology?.banned_terms?.length, (patterns?.terminology?.banned_terms || []).map((bt) => `<div class="item"><strong>${escHtml(bt.term)} <span class="replace">→ ${escHtml(bt.replace_with || '')}</span></strong><div class="why">${escHtml(bt.why || '')}</div></div>`).join(''))}
+${renderCard('Misunderstandings', patterns?.misunderstandings?.length, (patterns?.misunderstandings || []).map((mu) => `<div class="item"><strong>Wrong: ${escHtml(mu.wrong || '')}</strong><div class="detail">Correct: ${escHtml(mu.correct || '')}</div><div class="meta">${escHtml(mu.key_distinction || '')}</div></div>`).join(''))}
+${renderCard('Self-Checks', patterns?.self_check?.length, (patterns?.self_check || []).map((sc) => `<div class="item"><strong>✓ ${escHtml(typeof sc === 'string' ? sc : sc.one_sentence || '')}</strong></div>`).join(''))}
+${scenarios ? renderCard('Scenarios', scenarios.scenes?.length || 0, (scenarios.scenes || []).map((s) => `<div class="item"><strong>${escHtml(s.name || s.id || '')}</strong><div class="detail">${escHtml(s.trigger_signal || '')}</div></div>`).join('')) : ''}
+${cases ? renderCard('Cases', cases.cases?.length || 0, (cases.cases || []).map((c) => `<div class="item"><strong>${escHtml(c.title || c.id || '')}</strong><div class="detail">${escHtml((c.what_was_learned || '').substring(0, 150))}</div></div>`).join('')) : ''}
+${reasoning ? renderCard('Reasoning', reasoning.reasoning_chains?.length || 0, (reasoning.reasoning_chains || []).map((r) => `<div class="item"><strong>${escHtml(r.one_sentence || r.id || '')}</strong><div class="detail">${escHtml(r.so_what || '')}</div></div>`).join('')) : ''}
+${evolution ? renderCard('Evolution', evolution.stages?.length || 0, (evolution.stages || []).map((s) => `<div class="item"><strong>${escHtml(s.name || s.id || '')}</strong><div class="detail">${escHtml(s.description || '')}</div></div>`).join('')) : ''}
+</div>
+<div class="footer">Generated: ${new Date().toISOString().slice(0, 10)} · <a href="https://aikdna.com">aikdna.com</a></div>
+</body></html>`;
+}
+
+module.exports = { renderPreviewHTML, escHtml, renderCard };

package/src/types.d.ts

@@ -0,0 +1,254 @@
+export interface KDNAMeta {
+  version: string;
+  domain: string;
+  created: string;
+  purpose: string;
+  load_condition: string;
+}
+
+export interface KDNAAxiom {
+  id: string;
+  one_sentence: string;
+  full_statement: string;
+  why: string;
+}
+
+export interface KDNAOntologyConcept {
+  id: string;
+  one_sentence: string;
+  essence: string;
+  boundary: string;
+  trigger_signal: string;
+}
+
+export interface KDNAFramework {
+  id: string;
+  name: string;
+  when_to_use: string;
+  steps: string[];
+}
+
+export interface KDNACoreStructure {
+  from: string;
+  to: string;
+  via: string;
+}
+
+export interface KDNACore {
+  meta: KDNAMeta;
+  axioms: KDNAAxiom[];
+  ontology: KDNAOntologyConcept[];
+  frameworks: KDNAFramework[];
+  core_structure: KDNACoreStructure[];
+  stances: string[];
+}
+
+export interface KDNAStandardTerm {
+  term: string;
+  definition: string;
+}
+
+export interface KDNABannedTerm {
+  term: string;
+  why: string;
+  replace_with: string;
+}
+
+export interface KDNATerminology {
+  standard_terms: KDNAStandardTerm[];
+  banned_terms: KDNABannedTerm[];
+}
+
+export interface KDNAMisunderstanding {
+  id: string;
+  wrong: string;
+  correct: string;
+  key_distinction: string;
+  why: string;
+}
+
+export interface KDNAPatterns {
+  meta: KDNAMeta;
+  terminology: KDNATerminology;
+  misunderstandings: KDNAMisunderstanding[];
+  self_check: string[];
+}
+
+export interface KDNASubScenario {
+  id: string;
+  trap_belief: string;
+  three_questions: {
+    belief: string;
+    state: string;
+    need: string;
+  };
+  action_template: string[];
+  replace: {
+    avoid: string;
+    use: string;
+  }[];
+  expected_result: string;
+}
+
+export interface KDNAScene {
+  id: string;
+  name: string;
+  trigger_signal: string;
+  sub_scenarios: KDNASubScenario[];
+}
+
+export interface KDNAScenarios {
+  meta: KDNAMeta;
+  scenes: KDNAScene[];
+}
+
+export interface KDNACase {
+  id: string;
+  scene_id?: string;
+  title: string;
+  context: string;
+  what_happened: string;
+  what_was_learned: string;
+  structural_pattern: string;
+}
+
+export interface KDNACases {
+  meta: KDNAMeta;
+  cases: KDNACase[];
+}
+
+export interface KDNAReasoningChain {
+  id: string;
+  one_sentence: string;
+  logic: string[];
+  so_what: string;
+}
+
+export interface KDNAReasoning {
+  meta: KDNAMeta;
+  reasoning_chains: KDNAReasoningChain[];
+}
+
+export interface KDNAStage {
+  id: string;
+  name: string;
+  description: string;
+  indicators: string[];
+}
+
+export interface KDNAEvolutionLayer {
+  id: string;
+  name: string;
+  capability: string;
+  from_stage: string;
+  to_stage: string;
+}
+
+export interface KDNAMeasurement {
+  id: string;
+  what: string;
+  how: string;
+  threshold: string;
+}
+
+export interface KDNAEvolution {
+  meta: KDNAMeta;
+  stages: KDNAStage[];
+  evolution_layers: KDNAEvolutionLayer[];
+  measurement: KDNAMeasurement[];
+}
+
+export type KDNADomainFile =
+  | KDNACore
+  | KDNAPatterns
+  | KDNAScenarios
+  | KDNACases
+  | KDNAReasoning
+  | KDNAEvolution;
+
+export interface LoadedDomain {
+  core: KDNACore;
+  patterns: KDNAPatterns;
+  scenarios?: KDNAScenarios;
+  cases?: KDNACases;
+  reasoning?: KDNAReasoning;
+  evolution?: KDNAEvolution;
+}
+
+export interface LoadOptions {
+  input?: string;
+  mode?: 'all' | 'minimum' | 'auto';
+}
+
+/** Data map keyed by type (core, patterns, scenarios, etc.) */
+export interface KDNADataMap {
+  core: KDNACore;
+  patterns: KDNAPatterns;
+  scenarios?: KDNAScenarios;
+  cases?: KDNACases;
+  reasoning?: KDNAReasoning;
+  evolution?: KDNAEvolution;
+}
+
+/** Data map keyed by filename */
+export interface KDNAFileDataMap {
+  'KDNA_Core.json': KDNACore;
+  'KDNA_Patterns.json': KDNAPatterns;
+  'KDNA_Scenarios.json'?: KDNAScenarios;
+  'KDNA_Cases.json'?: KDNACases;
+  'KDNA_Reasoning.json'?: KDNAReasoning;
+  'KDNA_Evolution.json'?: KDNAEvolution;
+  'kdna.json'?: KDNAManifest;
+  [key: string]: any;
+}
+
+export interface KDNAManifest {
+  kdna_spec: string;
+  name: string;
+  version: string;
+  status: 'experimental' | 'basic' | 'stable' | 'pro';
+  access: 'open' | 'licensed' | 'runtime';
+  language: string;
+  author: { name: string; id?: string };
+  license: { type: string; url?: string };
+  description: string;
+}
+
+export interface LintResult {
+  errors: string[];
+  warnings: string[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// Loader — data-first API
+export function loadCorePatternsFromData(
+  coreData: KDNACore,
+  patternsData: KDNAPatterns,
+): { core: KDNACore; patterns: KDNAPatterns } | null;
+
+export function loadDomainFromData(dataMap: KDNADataMap, options?: LoadOptions): LoadedDomain | null;
+
+export function loadDomainFromFiles(fileDataMap: KDNAFileDataMap, options?: LoadOptions): LoadedDomain | null;
+
+export function classifyInput(text: string): string[];
+
+export function formatContext(domain: LoadedDomain): string;
+
+export const FILE_MAP: Record<string, string>;
+
+// Lint
+export function lintDomain(dataMap: KDNAFileDataMap): LintResult;
+
+// Validate
+export function validateDomainSchema(dataMap: KDNAFileDataMap, schemaMap?: Record<string, any>): ValidationResult;
+export function validateCrossFile(dataMap: KDNAFileDataMap): ValidationResult;
+
+// Render
+export function renderPreviewHTML(domain: LoadedDomain, manifest?: KDNAManifest): string;
+export function escHtml(s: string): string;
+export function renderCard(title: string, count: number | undefined, items: string): string;