@aikdna/kdna-studio-cli 0.3.0 → 0.3.2

package/bin/kdna-studio.js

@@ -710,6 +710,27 @@ function cmdMigrate(args) {
   try { creatorIdentity = creatorApi.loadIdentity(); } catch { /* proceed without */ }
   const { project } = importFromFolder(sourceDir, tmpDir, name, creatorIdentity);
 
+  // Reject if critical judgment fields are missing from axioms
+  const criticalMissing = [];
+  for (const card of (project.cards || [])) {
+    if (card.type !== 'axiom') continue;
+    for (const field of ['applies_when', 'does_not_apply_when', 'failure_risk']) {
+      const val = card.fields && card.fields[field];
+      if (!val || (Array.isArray(val) && val.length === 0) || val === '') {
+        criticalMissing.push(`${card.id}: missing ${field}`);
+      }
+    }
+  }
+  if (criticalMissing.length > 0) {
+    fail(
+      `Cannot migrate: ${criticalMissing.length} critical fields missing from axioms.\n` +
+      `  These fields are required for domain routing (kdna-loader uses them to\n` +
+      `  decide when to load this domain). Add them to your source files first.\n` +
+      `  Missing:\n    ` + criticalMissing.slice(0, 10).join('\n    ') +
+      (criticalMissing.length > 10 ? `\n    ... and ${criticalMissing.length - 10} more` : '')
+    );
+  }
+
   // Step 2: approve and Human Lock all cards
   let locked = 0;
   for (let i = 0; i < (project.cards || []).length; i++) {
@@ -760,7 +781,13 @@ function cmdMigrate(args) {
 
   if (args.includes('--sign')) applySignature(files, option(args, '--passphrase'));
   const absOut = path.resolve(out);
-  buildZip(files, absOut);
+  const entries = [['mimetype', files.mimetype]];
+  for (const name of Object.keys(files).filter(k => k !== 'mimetype').sort()) {
+    entries.push([name, files[name]]);
+  }
+  const zip = buildZip(entries);
+  fs.mkdirSync(path.dirname(absOut), { recursive: true });
+  fs.writeFileSync(absOut, zip);
   console.log(`Exported: ${absOut}`);
   console.log(`  Name: ${name}`);
   console.log(`  Cards: ${project.cards.length} (${locked} locked)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Official KDNA Studio command-line authoring entry for creating, locking, compiling, and exporting trusted .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin/",
+    "src/",
     "tests/",
     "README.md"
   ],

package/src/ai/distill.js

@@ -0,0 +1,77 @@
+// AI Distillation — extract candidate judgment patterns from evidence
+const llm = require('../llm');
+
+const SYSTEM = `You are a domain judgment extraction engine. Your task is to analyze source materials and extract candidate cognitive patterns that can become axioms, ontologies, misunderstandings, or self-checks in a knowledge domain.
+
+For each candidate you find, provide:
+- candidate_id: unique identifier (kebab-case, e.g. "axiom-early-feedback")
+- type: one of [axiom, ontology, misunderstanding, self_check, framework, stance]
+- one_sentence: a single clear sentence capturing the judgment principle
+- full_statement: 2-4 sentence explanation with concrete examples
+- confidence: one of [high, medium, low]
+- evidence_ids: array of source file names that support this candidate
+- scope_fit: true (unless the candidate clearly belongs to a different domain)
+
+IMPORTANT:
+- Extract ONLY patterns that represent judgment, standards, or cognitive frameworks — not facts or summaries
+- Each candidate must be testable: you should be able to construct an eval case that verifies the agent applies it
+- Prefer quality over quantity: 5-15 strong candidates is better than 30 weak ones
+- Skip anything that is purely factual, biographical, or outside the domain's scope
+
+Return ONLY valid JSON: {"candidates": [...]}`;
+
+async function distill(config, evidence, target, options = {}) {
+  const evidenceText = formatEvidence(evidence);
+  const targetText = formatTarget(target);
+
+  const userPrompt = [
+    `## Distillation Target`,
+    targetText,
+    ``,
+    `## Source Materials`,
+    evidenceText,
+    ``,
+    `Extract candidate judgment patterns from these materials that are relevant to the target domain.`,
+  ].join('\n');
+
+  const result = await llm.chatWithJSON([
+    { role: 'system', content: SYSTEM },
+    { role: 'user', content: userPrompt },
+  ], options);
+
+  const candidates = (result.data && result.data.candidates) || [];
+  return candidates.map(c => ({
+    id: c.candidate_id || `cand_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    one_sentence: c.one_sentence || '',
+    full_statement: c.full_statement || '',
+    suggested_card_type: c.type || 'axiom',
+    supporting_evidence_ids: (c.evidence_ids || []).map(String),
+    confidence: c.confidence || 'medium',
+    candidate_status: 'proposed',
+    scope_fit: c.scope_fit !== false,
+  }));
+}
+
+function formatEvidence(evidence) {
+  if (!evidence || evidence.length === 0) return '(no evidence loaded)';
+  return evidence.map((e, i) => {
+    const label = e.filename || e.name || `Source ${i + 1}`;
+    const content = (e.content || '').slice(0, 8000);
+    return `### ${label}\n\`\`\`\n${content}\n\`\`\``;
+  }).join('\n\n');
+}
+
+function formatTarget(target) {
+  if (!target) return '(no target declared)';
+  const parts = [];
+  if (target.domain_name) parts.push(`Domain: ${target.domain_name}`);
+  if (target.category) parts.push(`Category: ${target.category}`);
+  if (target.owner_scope) parts.push(`Scope: ${target.owner_scope}`);
+  if (target.granularity) parts.push(`Granularity: ${target.granularity}`);
+  if (target.task_scope) parts.push(`Task Scope: ${target.task_scope}`);
+  if (target.include_areas) parts.push(`Include: ${target.include_areas.join(', ')}`);
+  if (target.exclude_areas) parts.push(`Exclude: ${target.exclude_areas.join(', ')}`);
+  return parts.join('\n');
+}
+
+module.exports = { distill, SYSTEM };

package/src/ai/feynman.js

@@ -0,0 +1,57 @@
+// Feynman Evaluation — AI-driven assessment of understanding quality
+const llm = require('../llm');
+
+const CRITERIA = {
+  notJustRepeat: 'NOT just repeating the axiom text verbatim — uses different words/phrasing',
+  notTooAbstract: 'NOT too abstract — grounds the explanation in concrete terms',
+  hasConcreteExample: 'Provides at least one specific, realistic example or scenario',
+  clarifiesBoundary: 'Makes clear when the judgment does NOT apply (boundary awareness)',
+  ordinaryPersonUnderstands: 'Would make sense to someone unfamiliar with the domain',
+};
+
+const SYSTEM = `You are a Feynman evaluation engine. Your task is to assess how well someone understands a judgment principle based on their restatement of it in their own words.
+
+Evaluate the restatement on these 5 criteria (each YES/NO):
+${Object.entries(CRITERIA).map(([k, v]) => `- ${k}: ${v}`).join('\n')}
+
+Also provide a brief explanation for each criterion (1-2 sentences) and a suggested improvement if any criterion fails.
+
+Return ONLY valid JSON:
+{
+  "score": <0-5 integer>,
+  "criteria": {
+    "notJustRepeat": true/false,
+    "notTooAbstract": true/false,
+    "hasConcreteExample": true/false,
+    "clarifiesBoundary": true/false,
+    "ordinaryPersonUnderstands": true/false
+  },
+  "explanations": { "<criterion>": "<explanation>" },
+  "suggestions": ["<improvement suggestion>"]
+}`;
+
+async function evaluate(config, card, options = {}) {
+  const axiomText = card.one_sentence || card.full_statement || '';
+  const restatement = card.feynman_text || '';
+
+  if (!restatement) return { score: 0, criteria: {}, explanations: { notJustRepeat: 'No Feynman restatement provided.' }, suggestions: ['Write a Feynman restatement before evaluation.'] };
+
+  const userPrompt = [
+    `## Original Axiom`,
+    `"${axiomText}"`,
+    ``,
+    `## User's Restatement (Feynman)`,
+    `"${restatement}"`,
+    ``,
+    `Evaluate this restatement.`,
+  ].join('\n');
+
+  const result = await llm.chatWithJSON([
+    { role: 'system', content: SYSTEM },
+    { role: 'user', content: userPrompt },
+  ], options);
+
+  return result.data || { score: 0, criteria: {}, explanations: {}, suggestions: [] };
+}
+
+module.exports = { evaluate, CRITERIA, SYSTEM };

package/src/ai/filter.js

@@ -0,0 +1,70 @@
+// Sensitive Content Filter — blocks 6 domains in English and Chinese
+// Matches behavior of Studio App's SensitiveInferenceFilter
+const SENSITIVE_PATTERNS = {
+  identity: {
+    en: /\b(passport\s*(no|number|#)|id\s*(card|number|#)|social\s*security|ssn|driver'?s?\s*license|national\s*id|身份证|护照号)\b/i,
+    zh: /(身份证号|护照号码|社保号|驾驶证号|军官证)/
+  },
+  health: {
+    en: /\b(medical\s*record|patient\s*(id|number)|diagnosis\s*(code|report)|HIV|AIDS|cancer\s*diagnosis|病历|诊断)\b/i,
+    zh: /(病历|诊断报告|体检报告|HIV|艾滋病|癌症诊断)/
+  },
+  political: {
+    en: /\b(political\s*(party|affiliation|view)|voting\s*record|party\s*membership|political|政治)\b/i,
+    zh: /(政治面貌|党派|政治立场|政见)/
+  },
+  religious: {
+    en: /\b(religious\s*(belief|affiliation|view)|religion|faith\s*(group|community)|宗教)\b/i,
+    zh: /(宗教信仰|宗教派别|教派)/
+  },
+  financial: {
+    en: /\b(bank\s*account|credit\s*card\s*number|financial\s*(record|history)|income\s*(level|bracket)|salary|银行|金融)\b/i,
+    zh: /(银行卡号|信用卡号|银行账户|收入水平|财务状况|工资)/
+  },
+  intimate: {
+    en: /\b(sexual\s*(orientation|preference|identity)|gender\s*identity|sex\s*(life|history)|marital\s*status|性|性别|婚姻)\b/i,
+    zh: /(性取向|性别认同|性生活|婚姻状况|性偏好)/
+  },
+};
+
+function check(text, options = {}) {
+  if (!text || typeof text !== 'string') return { safe: true, flagged: [], matches: {} };
+
+  const flagged = [];
+  const matches = {};
+
+  for (const [domain, patterns] of Object.entries(SENSITIVE_PATTERNS)) {
+    const activePatterns = [];
+    if (options.lang !== 'zh' && patterns.en) activePatterns.push(patterns.en);
+    if (options.lang !== 'en' && patterns.zh) activePatterns.push(patterns.zh);
+
+    for (const pattern of activePatterns) {
+      const match = text.match(pattern);
+      if (match) {
+        flagged.push(domain);
+        matches[domain] = match[0];
+        break;
+      }
+    }
+  }
+
+  return { safe: flagged.length === 0, flagged, matches };
+}
+
+function checkEvidence(evidenceList, options = {}) {
+  const results = [];
+  for (const evidence of evidenceList) {
+    const content = evidence.raw_text || evidence.content || '';
+    const result = check(content, options);
+    if (!result.safe) {
+      results.push({
+        filename: evidence.filename || evidence.name || 'unknown',
+        flagged: result.flagged,
+        matches: result.matches,
+      });
+    }
+  }
+  return results;
+}
+
+module.exports = { check, checkEvidence, SENSITIVE_PATTERNS };

package/src/ai/index.js

@@ -0,0 +1,6 @@
+const distill = require('./distill');
+const interview = require('./interview');
+const feynman = require('./feynman');
+const testlab = require('./testlab');
+
+module.exports = { distill, interview, feynman, testlab };

package/src/ai/interview.js

@@ -0,0 +1,144 @@
+// AI Interview — 4-stage guided judgment authoring
+const llm = require('../llm');
+
+const STAGES = {
+  distillJudgment: {
+    label: 'Extract Judgment',
+    system: `You are a domain judgment expert. Your task is to help the user distill their raw knowledge into clear, actionable judgment principles (axioms).
+
+For each axiom, ask the user:
+1. What is the core judgment? (one sentence)
+2. When does this apply? (specific triggers)
+3. When does it NOT apply? (boundaries, exceptions)
+4. What happens if they get this wrong? (failure risk)
+
+Be conversational but focused. After the user provides their thoughts, synthesize them into a draft axiom with the format:
+- one_sentence: "..."
+- full_statement: "..."
+- applies_when: [...]
+- does_not_apply_when: [...]
+- failure_risk: "..."
+
+Then ask if they want to refine it or move to the next principle.`,
+  },
+  clarifyBoundaries: {
+    label: 'Clarify Boundaries',
+    system: `You are a boundary clarification expert. Review the axioms drafted so far and help the user identify gaps:
+
+1. Where might these axioms conflict with each other?
+2. What edge cases are not covered?
+3. Are the "does not apply" conditions specific enough, or are they vague?
+4. Would a reasonable person disagree with any of these judgments?
+
+Present one gap at a time and ask the user to clarify. Be direct but constructive.`,
+  },
+  correctMisreadings: {
+    label: 'Correct Misreadings',
+    system: `You are a misunderstanding detector. For each axiom, imagine how an AI agent might MISINTERPRET it:
+
+1. Literal vs intended meaning
+2. Over-application (applying too broadly)
+3. Under-application (not applying when it should)
+4. Cultural or context-specific assumptions
+
+For each potential misunderstanding, ask the user: "Is this a valid concern? How would you correct it?"
+
+The user's corrections will become misunderstanding cards that guide the agent toward correct interpretation.`,
+  },
+  replayScenario: {
+    label: 'Replay Scenario',
+    system: `You are a scenario simulation expert. For the axioms and misunderstandings defined so far, create realistic test scenarios:
+
+1. A clear-cut case where the judgment applies perfectly
+2. An ambiguous case that tests the boundaries
+3. A case where the judgment should NOT apply (tempting but wrong)
+
+Present each scenario to the user and ask:
+- "What would the correct judgment be here?"
+- "What makes this tricky?"
+- "Does this reveal any gaps in the axioms?"
+
+The user's responses become the basis for eval cases and scenario cards.`,
+  },
+};
+
+async function runInterview(config, project, stage, context, options = {}) {
+  const stageConfig = STAGES[stage];
+  if (!stageConfig) throw new Error(`Unknown interview stage: ${stage}. Valid: ${Object.keys(STAGES).join(', ')}`);
+
+  const systemPrompt = stageConfig.system;
+  const userPrompt = [
+    `## Project: ${project.name || 'Untitled'}`,
+    project.description ? `## Description: ${project.description}` : '',
+    ``,
+    `## Current State`,
+    `Cards: ${(project.cards || []).length} (${(project.cards || []).filter(c => c.locked).length} locked)`,
+    project.distillation_candidates ? `Candidates: ${project.distillation_candidates.length}` : '',
+    ``,
+    `## Context`,
+    context || '(no additional context)',
+    ``,
+    `Begin ${stageConfig.label} stage.`,
+  ].filter(Boolean).join('\n');
+
+  const result = await llm.chat([
+    { role: 'system', content: systemPrompt },
+    { role: 'user', content: userPrompt },
+  ], options);
+
+  return { stage, label: stageConfig.label, content: result.content };
+}
+
+async function runInterviewInteractive(config, project, options = {}) {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  console.log(`\n=== KDNA Studio — AI Interview ===`);
+  console.log(`Project: ${project.name || 'Untitled'}`);
+  console.log(`4 stages: distill → clarify → correct → replay\n`);
+
+  const conversation = [];
+  let results = [];
+
+  for (const [stageId, stageConfig] of Object.entries(STAGES)) {
+    console.log(`\n--- ${stageConfig.label} ---`);
+
+    const contextParts = [`Project: ${project.name || 'Untitled'}`];
+    if (project.description) contextParts.push(`Description: ${project.description}`);
+    const cardsSummary = (project.cards || []).map(c => `[${c.type}] ${c.one_sentence || c.concept_name || c.wrong_interpretation || ''}`).join('\n');
+    if (cardsSummary) contextParts.push(`Existing cards:\n${cardsSummary}`);
+
+    const initialResponse = await llm.chat([
+      { role: 'system', content: stageConfig.system },
+      { role: 'user', content: `Start the ${stageConfig.label} stage.\n\nContext:\n${contextParts.join('\n')}` },
+    ], options);
+    console.log(`\nAI: ${initialResponse.content}\n`);
+
+    let keepGoing = true;
+    while (keepGoing) {
+      const answer = await ask('You (type "next" to proceed, "done" to finish this stage): ');
+      if (answer.toLowerCase() === 'next' || answer.toLowerCase() === 'done') {
+        keepGoing = false;
+        if (answer.toLowerCase() === 'done') break;
+        continue;
+      }
+      if (!answer.trim()) continue;
+
+      conversation.push({ stage: stageId, role: 'user', content: answer });
+      const response = await llm.chat([
+        { role: 'system', content: stageConfig.system },
+        ...conversation.filter(m => m.stage === stageId).map(m => ({ role: m.role, content: m.content })),
+      ], options);
+      conversation.push({ stage: stageId, role: 'assistant', content: response.content });
+      console.log(`\nAI: ${response.content}\n`);
+    }
+
+    results.push({ stage: stageId, label: stageConfig.label, conversation: conversation.filter(m => m.stage === stageId) });
+  }
+
+  rl.close();
+  return results;
+}
+
+module.exports = { STAGES, runInterview, runInterviewInteractive };

package/src/ai/testlab.js

@@ -0,0 +1,73 @@
+// TestLab — A/B comparison testing with LLM
+const llm = require('../llm');
+
+const COMPARE_SYSTEM = `You are a controlled experiment evaluator. You will see the same user input twice — once with a knowledge domain loaded, and once without. Your task is to produce a structured comparison.
+
+IMPORTANT: You must respond with raw JSON only, no markdown wrapping, no explanatory text.
+
+The JSON format:
+{
+  "without_kdna": {
+    "response": "how you would respond WITHOUT the domain knowledge",
+    "classification": "how you categorized the task",
+    "diagnosis": "your analysis of the situation",
+    "actions": "what actions you would take"
+  },
+  "with_kdna": {
+    "response": "how you respond WITH the domain knowledge applied",
+    "classification": "domain-specific classification from the loaded domain",
+    "diagnosis": "analysis informed by domain axioms and ontology",
+    "actions": "actions influenced by domain judgment"
+  },
+  "delta": {
+    "classification_changed": true/false,
+    "diagnosis_changed": true/false,
+    "actions_changed": true/false,
+    "terminology_changed": true/false,
+    "overall_impact": "none" | "minor" | "moderate" | "significant"
+  }
+}`;
+
+async function compare(config, domainName, input, domainPrompt, options = {}) {
+  // Run WITHOUT KDNA
+  const withoutResult = await llm.chat([
+    { role: 'system', content: COMPARE_SYSTEM },
+    { role: 'user', content: `Respond to the following WITHOUT any special domain knowledge:\n\n${input}\n\nRespond with the structured JSON comparison format. For the "without_kdna" section, fill in your normal response. For the "with_kdna" section, fill in what you think would change (we will verify this in a separate pass).` },
+  ], { ...options, responseFormat: { type: 'json_object' } });
+
+  let withoutData;
+  try { withoutData = JSON.parse(withoutResult.content); } catch { withoutData = { without_kdna: { response: withoutResult.content } }; }
+
+  // Run WITH KDNA
+  const withResult = await llm.chat([
+    { role: 'system', content: `${domainPrompt}\n\n${COMPARE_SYSTEM}` },
+    { role: 'user', content: `Respond to the following WITH the domain knowledge loaded:\n\n${input}\n\nRespond with the structured JSON comparison format. Fill in the "with_kdna" section and the "delta" section based on what actually changed.` },
+  ], { ...options, responseFormat: { type: 'json_object' } });
+
+  let withData;
+  try { withData = JSON.parse(withResult.content); } catch { withData = { with_kdna: { response: withResult.content } }; }
+
+  return {
+    input,
+    domain: domainName,
+    without_kdna: withoutData.without_kdna || { response: withoutResult.content },
+    with_kdna: withData.with_kdna || { response: withResult.content },
+    delta: withData.delta || { overall_impact: 'unknown' },
+  };
+}
+
+async function testPreset(config, domainName, input, domainPrompt, options = {}) {
+  const presets = {
+    baseline: `Test the core judgment: ${input}`,
+    edge_case: `Test a boundary case where domain judgment may or may not apply: ${input}`,
+    contradiction: `Test for potential contradiction: present a scenario that challenges the domain's axioms: ${input}`,
+  };
+
+  const results = {};
+  for (const [name, prompt] of Object.entries(presets)) {
+    results[name] = await compare(config, domainName, prompt, domainPrompt, options);
+  }
+  return results;
+}
+
+module.exports = { compare, testPreset, COMPARE_SYSTEM };

package/src/llm/config.js

@@ -0,0 +1,72 @@
+// LLM Provider Configuration
+// Sources (priority order): env vars > ~/.kdna/config.json > defaults
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ENV_PREFIX = 'KDNA_LLM_';
+
+const WELL_KNOWN = {
+  openai: { baseURL: 'https://api.openai.com/v1', models: ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo'] },
+  anthropic: { baseURL: 'https://api.anthropic.com/v1', models: ['claude-sonnet-4-20250514', 'claude-3-5-haiku-latest'] },
+  deepseek: { baseURL: 'https://api.deepseek.com/v1', models: ['deepseek-chat', 'deepseek-reasoner'] },
+  openrouter: { baseURL: 'https://openrouter.ai/api/v1', models: ['openai/gpt-4o', 'anthropic/claude-sonnet-4', 'deepseek/deepseek-chat'] },
+  gemini: { baseURL: 'https://generativelanguage.googleapis.com/v1beta', models: ['gemini-2.5-flash', 'gemini-2.5-pro'] },
+  perplexity: { baseURL: 'https://api.perplexity.ai', models: ['sonar-pro', 'sonar'] },
+  groq: { baseURL: 'https://api.groq.com/openai/v1', models: ['llama-4-scout-17b-16e-instruct', 'deepseek-r1-distill-llama-70b'] },
+  local: { baseURL: 'http://localhost:11434/v1', models: ['llama3.2'] },
+  ollama: { baseURL: 'http://localhost:11434/v1', models: ['llama3.2'] },
+  openai_compatible: { baseURL: null, models: [] },
+};
+
+function loadConfig() {
+  const config = { provider: null, apiKey: null, model: null, baseURL: null, temperature: 0.7, maxTokens: 4096 };
+
+  // 1. Read from ~/.kdna/config.json
+  const configPath = path.join(os.homedir(), '.kdna', 'config.json');
+  try { if (fs.existsSync(configPath)) Object.assign(config, JSON.parse(fs.readFileSync(configPath, 'utf8')).llm || {}); } catch {}
+
+  // 2. Env vars override
+  if (process.env.KDNA_LLM_PROVIDER) config.provider = process.env.KDNA_LLM_PROVIDER;
+  if (process.env.KDNA_LLM_API_KEY) config.apiKey = process.env.KDNA_LLM_API_KEY;
+  if (process.env.KDNA_LLM_MODEL) config.model = process.env.KDNA_LLM_MODEL;
+  if (process.env.KDNA_LLM_BASE_URL) config.baseURL = process.env.KDNA_LLM_BASE_URL;
+  if (process.env.KDNA_LLM_TEMPERATURE) config.temperature = parseFloat(process.env.KDNA_LLM_TEMPERATURE);
+  if (process.env.KDNA_LLM_MAX_TOKENS) config.maxTokens = parseInt(process.env.KDNA_LLM_MAX_TOKENS, 10);
+
+  // 3. Resolve well-known provider
+  if (config.provider && WELL_KNOWN[config.provider]) {
+    const wk = WELL_KNOWN[config.provider];
+    if (wk.baseURL && !config.baseURL) config.baseURL = wk.baseURL;
+    if (wk.models.length > 0 && !config.model) config.model = wk.models[0];
+  }
+
+  // 4. Also check provider-specific env vars
+  if (!config.apiKey) {
+    const keyEnv = `KDNA_LLM_API_KEY_${(config.provider || '').toUpperCase().replace(/-/g, '_')}`;
+    if (process.env[keyEnv]) config.apiKey = process.env[keyEnv];
+    // Fallback: OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY
+    if (!config.apiKey) config.apiKey = process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.DEEPSEEK_API_KEY || '';
+  }
+
+  return config;
+}
+
+function saveConfig(updates) {
+  const configPath = path.join(os.homedir(), '.kdna', 'config.json');
+  let existing = {};
+  try { if (fs.existsSync(configPath)) existing = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  existing.llm = { ...(existing.llm || {}), ...updates };
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n');
+}
+
+function validateConfig(config) {
+  const errors = [];
+  if (!config.provider) errors.push('Missing KDNA_LLM_PROVIDER. Set via env var or ~/.kdna/config.json');
+  if (!config.apiKey) errors.push('Missing KDNA_LLM_API_KEY');
+  if (!config.model) errors.push('Missing KDNA_LLM_MODEL');
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = { loadConfig, saveConfig, validateConfig, WELL_KNOWN };

package/src/llm/index.js

@@ -0,0 +1,49 @@
+// KDNA Studio CLI — unified LLM interface
+// Supports OpenAI-compatible and Anthropic APIs
+// Configuration via KDNA_LLM_* env vars or ~/.kdna/config.json
+const { loadConfig, saveConfig, validateConfig } = require('./config');
+const openai = require('./providers/openai');
+const anthropic = require('./providers/anthropic');
+
+function getProvider(config) {
+  if (!config || !config.provider) throw new Error('LLM not configured. Run: kdna-studio llm config');
+  if (config.provider === 'anthropic') return anthropic;
+  return openai; // All OpenAI-compatible providers use the same API
+}
+
+async function chat(messages, options = {}) {
+  const config = loadConfig();
+  if (options.provider) config.provider = options.provider;
+  if (options.model) config.model = options.model;
+  if (options.apiKey) config.apiKey = options.apiKey;
+  if (options.baseURL) config.baseURL = options.baseURL;
+
+  const validation = validateConfig(config);
+  if (!validation.valid) throw new Error(`LLM configuration error:\n${validation.errors.map(e => `  - ${e}`).join('\n')}`);
+
+  const provider = getProvider(config);
+  return provider.chat(config, messages, options);
+}
+
+async function chatWithJSON(messages, options = {}) {
+  const result = await chat(messages, { ...options, responseFormat: { type: 'json_object' } });
+  try {
+    result.data = JSON.parse(result.content);
+  } catch {
+    // Try to extract JSON from markdown code blocks
+    const match = result.content.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (match) {
+      try { result.data = JSON.parse(match[1].trim()); } catch { /* raw text */ }
+    }
+  }
+  return result;
+}
+
+function config() { return loadConfig(); }
+
+function configure(updates) {
+  saveConfig(updates);
+  return loadConfig();
+}
+
+module.exports = { chat, chatWithJSON, config, configure };

package/src/llm/providers/anthropic.js

@@ -0,0 +1,40 @@
+// Anthropic Messages API provider
+
+async function chat(config, messages, options = {}) {
+  const url = `${config.baseURL}/messages`;
+  const model = options.model || config.model;
+  const maxTokens = options.maxTokens || config.maxTokens || 4096;
+
+  // Convert OpenAI-format messages to Anthropic format
+  const systemMessages = messages.filter(m => m.role === 'system').map(m => m.content).join('\n\n');
+  const conversationMessages = messages.filter(m => m.role !== 'system').map(m => ({
+    role: m.role === 'assistant' ? 'assistant' : 'user',
+    content: m.content,
+  }));
+
+  const body = { model, max_tokens: maxTokens, messages: conversationMessages };
+  if (systemMessages) body.system = systemMessages;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    'x-api-key': config.apiKey,
+    'anthropic-version': '2023-06-01',
+  };
+
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 500)}`);
+  }
+  const data = await res.json();
+  const content = data.content?.[0]?.text;
+  if (!content) throw new Error('Anthropic returned empty response');
+
+  return {
+    content: content.trim(),
+    model: data.model || model,
+    usage: data.usage || null,
+  };
+}
+
+module.exports = { chat };

package/src/llm/providers/openai.js

@@ -0,0 +1,41 @@
+// OpenAI-compatible chat completions provider
+// Works with: OpenAI, DeepSeek, OpenRouter, Groq, Ollama, LM Studio, Perplexity, and any OpenAI-compatible API
+
+async function chat(config, messages, options = {}) {
+  const url = `${config.baseURL}/chat/completions`;
+  const model = options.model || config.model;
+  const temperature = options.temperature ?? config.temperature ?? 0.7;
+  const maxTokens = options.maxTokens || config.maxTokens || 4096;
+  const responseFormat = options.responseFormat || null;
+
+  const body = { model, messages, temperature, max_tokens: maxTokens };
+  if (responseFormat) body.response_format = responseFormat;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${config.apiKey}`,
+  };
+
+  // Provider-specific headers
+  if (config.provider === 'openrouter') {
+    headers['HTTP-Referer'] = 'https://github.com/aikdna/kdna-studio-cli';
+    headers['X-Title'] = 'KDNA Studio CLI';
+  }
+
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`LLM API error ${res.status}: ${text.slice(0, 500)}`);
+  }
+  const data = await res.json();
+  const content = data.choices?.[0]?.message?.content;
+  if (!content) throw new Error('LLM returned empty response');
+
+  return {
+    content: content.trim(),
+    model: data.model || model,
+    usage: data.usage || null,
+  };
+}
+
+module.exports = { chat };