@thanh01.pmt/domain-kit 0.1.0

package/dist/graph/index.d.cts

@@ -0,0 +1,226 @@
+import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.cjs';
+import { d as Feature, c as Step, u as ProjectGraph } from '../projectGraphSchema-DnD7orZV.cjs';
+import { K as Keyword } from '../keywordExtractor-zPAz2isq.cjs';
+export { H as Hallucination, V as VerifyOptions, v as verifyProjectGraph } from '../graphVerifier-QjgDAJce.cjs';
+export { C as ConceptMapping, E as EscalateOptions, e as escalateAndMapConcepts } from '../conceptEscalator-ltRLtPhf.cjs';
+import { g as KnowledgeGraph, j as HybridGraph } from '../hybridGraphSchema-BCgXicgA.cjs';
+import 'zod';
+import '../parsers/index.cjs';
+
+/**
+ * STEP C0: Extract FOUNDATION & SETUP feature (F0) via LLM.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py extract_scaffold_llm()
+ * The F0 feature covers MUST-KNOW steps before the first feature:
+ * tools, project creation, minimal programming knowledge, repo map, dev loop.
+ */
+
+interface ExtractScaffoldOptions {
+    goal: string;
+    techStack: string;
+    fileList: string[];
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract the FOUNDATION & SETUP feature (F0) via LLM.
+ * Returns a Feature with steps covering tool setup, project creation,
+ * minimal programming knowledge, repo map, and dev loop.
+ */
+declare function extractScaffold(options: ExtractScaffoldOptions): Promise<Feature | null>;
+
+/**
+ * STEP C1: Extract PROJECT OVERVIEW via LLM (features meta — NO steps).
+ *
+ * Ported from knowledge-tree/llm_project_graph.py extract_project_overview_llm()
+ * Output: project, product, features[], user_journeys, architecture, decomposition.
+ */
+
+interface ExtractOverviewOptions {
+    goal: string;
+    techStack: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+    astKeywords?: Keyword[];
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract project overview (features meta) via LLM.
+ * Does NOT include steps — those are extracted per-feature in STEP C2.
+ */
+declare function extractProjectOverview(options: ExtractOverviewOptions): Promise<Record<string, unknown>>;
+
+/**
+ * STEP C2: Extract feature STEPS via LLM.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py
+ *   - extract_feature_steps_llm() — single feature
+ *   - extract_feature_steps_batched() — batch of features
+ */
+
+interface ExtractStepsOptions {
+    goal: string;
+    techStack: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+    feature: Feature;
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract steps for a SINGLE feature via LLM.
+ */
+declare function extractFeatureSteps(options: ExtractStepsOptions): Promise<Step[]>;
+/**
+ * Extract steps for MULTIPLE features in a single LLM call.
+ */
+declare function extractFeatureStepsBatched(goal: string, techStack: string, sdkApiIndex: {
+    sdk_apis: Array<{
+        name: string;
+        kind: string;
+        used_in_demo: boolean;
+    }>;
+}, fileContentsMap: Map<string, string>, featuresMeta: Feature[], llmConfig?: LlmClientConfig): Promise<Map<string, Step[]>>;
+
+/**
+ * Knowledge Graph Pipeline — generates knowledge_graph for concept-driven learning.
+ *
+ * Input: syllabus text, subject description, grade band
+ * Output: KnowledgeGraph with concepts, problem_types, prerequisites, learning_path
+ *
+ * Includes:
+ *   - Cycle detection in prerequisite chains
+ *   - Topological sort for learning_path
+ *   - Multi-language syllabus support
+ *   - ULO/CIO/SIO depth control per concept
+ */
+
+interface KnowledgeGraphPipelineOptions {
+    subject: string;
+    description?: string;
+    syllabusText?: string;
+    gradeBand?: [number, number];
+    domain?: string;
+    /** Target technology for SIO keyword binding (e.g. "python", "swift"); auto-detected fallback applies. */
+    techStack?: string;
+    llmConfig?: LlmClientConfig;
+    onProgress?: (step: string, message: string) => void;
+    /** Path to mlo-knowlege-tree.tsv. When provided, STEP_2_5 standardizes every concept against the tree (fail-closed). */
+    knowledgeTreePath?: string;
+    /** Where to persist proposed-new concepts for the later merge. Default: tmpdir/domain-kit-debug/concept-proposals.json */
+    proposalsPath?: string;
+}
+interface KnowledgeGraphPipelineResult {
+    knowledgeGraph: KnowledgeGraph;
+    warnings: string[];
+}
+/**
+ * Generate a KnowledgeGraph from syllabus/description via LLM.
+ */
+declare function generateKnowledgeGraph(options: KnowledgeGraphPipelineOptions): Promise<KnowledgeGraphPipelineResult>;
+
+interface DepthLayerAudit {
+    conceptId: string;
+    uloHasTechSignals: boolean;
+    uloTechSignals: string[];
+    uloHasImplementationVerbs: boolean;
+    sioAllKeywordBound: boolean;
+    sioUnboundItems: string[];
+    sioConceptKeywordBound: boolean;
+    sioOffConceptItems: string[];
+    sioAllCompletable: boolean;
+    sioNotCompletable: string[];
+    concretenessIncreases: boolean;
+    clauseOk: boolean;
+    codesOk: boolean;
+    codeIssues: string[];
+    passed: boolean;
+}
+declare function auditDepthLayers(concepts: Array<{
+    id: string;
+    name?: string;
+    ulo?: string;
+    cio?: string;
+    sio?: string[];
+    code?: string;
+    ulo_code?: string;
+    cio_code?: string;
+    sio_codes?: string[];
+    keywords?: string[];
+}>): DepthLayerAudit[];
+
+/**
+ * LO code + statement standard — calibrated against the production
+ * learning_objectives table (6,693 live rows) and the knowledge-tree
+ * Naming Conventions v2.2 (Appendix C of adaptive-learning-platform.md).
+ *
+ * Codes (deterministic, never LLM-generated):
+ *   concept  CONCEPT_CODE            UPPER_SNAKE_CASE, technology-neutral
+ *   ULO      ULO-[CONCEPT]-NN        one primary ULO per concept (NN = 01)
+ *   CIO      CIO-[CONCEPT]-NN-[ACTION]  parent = ULO, ACTION = SNAKE verb phrase
+ *   SIO      SIO-[TECH]-[CONCEPT]-NN    only tier carrying a tech tag (PY, SW, TS...)
+ *
+ * Statements: every LO description uses the normalized clause
+ *   "The learner will be able to ..."  (production Supabase style).
+ */
+/** Map a tech stack string to the production SIO tech tag (PY, SW, TS...). */
+declare function techTagFor(techStack: string): string;
+/** Derive a neutral UPPER_SNAKE_CASE concept code from a human concept name. */
+declare function conceptCodeFromName(name: string): string;
+/**
+ * Assign unique concept codes to every concept (first occurrence keeps the
+ * plain code, later collisions get a _2.._N suffix) — mirrors the DB where
+ * concept_codes are unique neutral UPPER_SNAKE keys.
+ */
+declare function assignConceptCodes(concepts: Array<{
+    id: string;
+    name: string;
+}>): Record<string, string>;
+declare function uloCode(conceptCode: string, seq?: number): string;
+/** Extract a short SNAKE_CASE action phrase (2-4 content words) for a CIO code. */
+declare function cioActionSlug(cioText: string): string;
+declare function cioCode(conceptCode: string, uloSeq: number, actionSlug: string): string;
+declare function sioCode(techTag: string, conceptCode: string, seq: number): string;
+declare const LEARNER_CLAUSE = "The learner will be able to ";
+/** Normalize any LO text into the production statement form with the standard clause. */
+declare function standardStatement(text: string): string;
+declare const CONCEPT_CODE_RE: RegExp;
+declare const ULO_CODE_RE: RegExp;
+declare const CIO_CODE_RE: RegExp;
+declare const SIO_CODE_RE: RegExp;
+
+/**
+ * Hybrid Graph Pipeline - generates hybrid_graph combining project + knowledge.
+ *
+ * STEP_1 generates feature-concept links. STEP_2 decomposes the build into
+ * PROGRESSIVE COMPLETION PHASES (cross-feature): each phase describes what the
+ * product can demonstrably do once complete, owns every feature built in it
+ * (each feature in EXACTLY one phase), and declares which concepts are
+ * introduced (new) or revisited at higher depth (advanced) at the phase start.
+ * Later phases depend on earlier ones and may only raise the knowledge level -
+ * verified against the concept prerequisite graph (fail-closed).
+ */
+
+interface HybridGraphPipelineOptions {
+    projectGraph: ProjectGraph;
+    knowledgeGraph: KnowledgeGraph;
+    llmConfig?: LlmClientConfig;
+    onProgress?: (step: string, message: string) => void;
+}
+interface HybridGraphPipelineResult {
+    hybridGraph: HybridGraph;
+    warnings: string[];
+}
+declare function generateHybridGraph(options: HybridGraphPipelineOptions): Promise<HybridGraphPipelineResult>;
+
+export { CIO_CODE_RE, CONCEPT_CODE_RE, type DepthLayerAudit, type ExtractOverviewOptions, type ExtractScaffoldOptions, type ExtractStepsOptions, type HybridGraphPipelineOptions, type HybridGraphPipelineResult, type KnowledgeGraphPipelineOptions, type KnowledgeGraphPipelineResult, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, cioActionSlug, cioCode, conceptCodeFromName, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode };

package/dist/graph/index.d.ts

@@ -0,0 +1,226 @@
+import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.js';
+import { d as Feature, c as Step, u as ProjectGraph } from '../projectGraphSchema-DnD7orZV.js';
+import { K as Keyword } from '../keywordExtractor-CKaXqSku.js';
+export { H as Hallucination, V as VerifyOptions, v as verifyProjectGraph } from '../graphVerifier-DsTP9uAN.js';
+export { C as ConceptMapping, E as EscalateOptions, e as escalateAndMapConcepts } from '../conceptEscalator-YfMKIKCZ.js';
+import { g as KnowledgeGraph, j as HybridGraph } from '../hybridGraphSchema-BCgXicgA.js';
+import 'zod';
+import '../parsers/index.js';
+
+/**
+ * STEP C0: Extract FOUNDATION & SETUP feature (F0) via LLM.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py extract_scaffold_llm()
+ * The F0 feature covers MUST-KNOW steps before the first feature:
+ * tools, project creation, minimal programming knowledge, repo map, dev loop.
+ */
+
+interface ExtractScaffoldOptions {
+    goal: string;
+    techStack: string;
+    fileList: string[];
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract the FOUNDATION & SETUP feature (F0) via LLM.
+ * Returns a Feature with steps covering tool setup, project creation,
+ * minimal programming knowledge, repo map, and dev loop.
+ */
+declare function extractScaffold(options: ExtractScaffoldOptions): Promise<Feature | null>;
+
+/**
+ * STEP C1: Extract PROJECT OVERVIEW via LLM (features meta — NO steps).
+ *
+ * Ported from knowledge-tree/llm_project_graph.py extract_project_overview_llm()
+ * Output: project, product, features[], user_journeys, architecture, decomposition.
+ */
+
+interface ExtractOverviewOptions {
+    goal: string;
+    techStack: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+    astKeywords?: Keyword[];
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract project overview (features meta) via LLM.
+ * Does NOT include steps — those are extracted per-feature in STEP C2.
+ */
+declare function extractProjectOverview(options: ExtractOverviewOptions): Promise<Record<string, unknown>>;
+
+/**
+ * STEP C2: Extract feature STEPS via LLM.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py
+ *   - extract_feature_steps_llm() — single feature
+ *   - extract_feature_steps_batched() — batch of features
+ */
+
+interface ExtractStepsOptions {
+    goal: string;
+    techStack: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+    feature: Feature;
+    llmConfig?: LlmClientConfig;
+}
+/**
+ * Extract steps for a SINGLE feature via LLM.
+ */
+declare function extractFeatureSteps(options: ExtractStepsOptions): Promise<Step[]>;
+/**
+ * Extract steps for MULTIPLE features in a single LLM call.
+ */
+declare function extractFeatureStepsBatched(goal: string, techStack: string, sdkApiIndex: {
+    sdk_apis: Array<{
+        name: string;
+        kind: string;
+        used_in_demo: boolean;
+    }>;
+}, fileContentsMap: Map<string, string>, featuresMeta: Feature[], llmConfig?: LlmClientConfig): Promise<Map<string, Step[]>>;
+
+/**
+ * Knowledge Graph Pipeline — generates knowledge_graph for concept-driven learning.
+ *
+ * Input: syllabus text, subject description, grade band
+ * Output: KnowledgeGraph with concepts, problem_types, prerequisites, learning_path
+ *
+ * Includes:
+ *   - Cycle detection in prerequisite chains
+ *   - Topological sort for learning_path
+ *   - Multi-language syllabus support
+ *   - ULO/CIO/SIO depth control per concept
+ */
+
+interface KnowledgeGraphPipelineOptions {
+    subject: string;
+    description?: string;
+    syllabusText?: string;
+    gradeBand?: [number, number];
+    domain?: string;
+    /** Target technology for SIO keyword binding (e.g. "python", "swift"); auto-detected fallback applies. */
+    techStack?: string;
+    llmConfig?: LlmClientConfig;
+    onProgress?: (step: string, message: string) => void;
+    /** Path to mlo-knowlege-tree.tsv. When provided, STEP_2_5 standardizes every concept against the tree (fail-closed). */
+    knowledgeTreePath?: string;
+    /** Where to persist proposed-new concepts for the later merge. Default: tmpdir/domain-kit-debug/concept-proposals.json */
+    proposalsPath?: string;
+}
+interface KnowledgeGraphPipelineResult {
+    knowledgeGraph: KnowledgeGraph;
+    warnings: string[];
+}
+/**
+ * Generate a KnowledgeGraph from syllabus/description via LLM.
+ */
+declare function generateKnowledgeGraph(options: KnowledgeGraphPipelineOptions): Promise<KnowledgeGraphPipelineResult>;
+
+interface DepthLayerAudit {
+    conceptId: string;
+    uloHasTechSignals: boolean;
+    uloTechSignals: string[];
+    uloHasImplementationVerbs: boolean;
+    sioAllKeywordBound: boolean;
+    sioUnboundItems: string[];
+    sioConceptKeywordBound: boolean;
+    sioOffConceptItems: string[];
+    sioAllCompletable: boolean;
+    sioNotCompletable: string[];
+    concretenessIncreases: boolean;
+    clauseOk: boolean;
+    codesOk: boolean;
+    codeIssues: string[];
+    passed: boolean;
+}
+declare function auditDepthLayers(concepts: Array<{
+    id: string;
+    name?: string;
+    ulo?: string;
+    cio?: string;
+    sio?: string[];
+    code?: string;
+    ulo_code?: string;
+    cio_code?: string;
+    sio_codes?: string[];
+    keywords?: string[];
+}>): DepthLayerAudit[];
+
+/**
+ * LO code + statement standard — calibrated against the production
+ * learning_objectives table (6,693 live rows) and the knowledge-tree
+ * Naming Conventions v2.2 (Appendix C of adaptive-learning-platform.md).
+ *
+ * Codes (deterministic, never LLM-generated):
+ *   concept  CONCEPT_CODE            UPPER_SNAKE_CASE, technology-neutral
+ *   ULO      ULO-[CONCEPT]-NN        one primary ULO per concept (NN = 01)
+ *   CIO      CIO-[CONCEPT]-NN-[ACTION]  parent = ULO, ACTION = SNAKE verb phrase
+ *   SIO      SIO-[TECH]-[CONCEPT]-NN    only tier carrying a tech tag (PY, SW, TS...)
+ *
+ * Statements: every LO description uses the normalized clause
+ *   "The learner will be able to ..."  (production Supabase style).
+ */
+/** Map a tech stack string to the production SIO tech tag (PY, SW, TS...). */
+declare function techTagFor(techStack: string): string;
+/** Derive a neutral UPPER_SNAKE_CASE concept code from a human concept name. */
+declare function conceptCodeFromName(name: string): string;
+/**
+ * Assign unique concept codes to every concept (first occurrence keeps the
+ * plain code, later collisions get a _2.._N suffix) — mirrors the DB where
+ * concept_codes are unique neutral UPPER_SNAKE keys.
+ */
+declare function assignConceptCodes(concepts: Array<{
+    id: string;
+    name: string;
+}>): Record<string, string>;
+declare function uloCode(conceptCode: string, seq?: number): string;
+/** Extract a short SNAKE_CASE action phrase (2-4 content words) for a CIO code. */
+declare function cioActionSlug(cioText: string): string;
+declare function cioCode(conceptCode: string, uloSeq: number, actionSlug: string): string;
+declare function sioCode(techTag: string, conceptCode: string, seq: number): string;
+declare const LEARNER_CLAUSE = "The learner will be able to ";
+/** Normalize any LO text into the production statement form with the standard clause. */
+declare function standardStatement(text: string): string;
+declare const CONCEPT_CODE_RE: RegExp;
+declare const ULO_CODE_RE: RegExp;
+declare const CIO_CODE_RE: RegExp;
+declare const SIO_CODE_RE: RegExp;
+
+/**
+ * Hybrid Graph Pipeline - generates hybrid_graph combining project + knowledge.
+ *
+ * STEP_1 generates feature-concept links. STEP_2 decomposes the build into
+ * PROGRESSIVE COMPLETION PHASES (cross-feature): each phase describes what the
+ * product can demonstrably do once complete, owns every feature built in it
+ * (each feature in EXACTLY one phase), and declares which concepts are
+ * introduced (new) or revisited at higher depth (advanced) at the phase start.
+ * Later phases depend on earlier ones and may only raise the knowledge level -
+ * verified against the concept prerequisite graph (fail-closed).
+ */
+
+interface HybridGraphPipelineOptions {
+    projectGraph: ProjectGraph;
+    knowledgeGraph: KnowledgeGraph;
+    llmConfig?: LlmClientConfig;
+    onProgress?: (step: string, message: string) => void;
+}
+interface HybridGraphPipelineResult {
+    hybridGraph: HybridGraph;
+    warnings: string[];
+}
+declare function generateHybridGraph(options: HybridGraphPipelineOptions): Promise<HybridGraphPipelineResult>;
+
+export { CIO_CODE_RE, CONCEPT_CODE_RE, type DepthLayerAudit, type ExtractOverviewOptions, type ExtractScaffoldOptions, type ExtractStepsOptions, type HybridGraphPipelineOptions, type HybridGraphPipelineResult, type KnowledgeGraphPipelineOptions, type KnowledgeGraphPipelineResult, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, cioActionSlug, cioCode, conceptCodeFromName, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode };

package/dist/graph/index.mjs

@@ -0,0 +1,4 @@
+export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, cioActionSlug, cioCode, conceptCodeFromName, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode } from '../chunk-3VVPSRAM.mjs';
+export { escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, verifyProjectGraph } from '../chunk-MOKNFLUD.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/graph/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/graphVerifier-DsTP9uAN.d.ts

@@ -0,0 +1,37 @@
+import { u as ProjectGraph } from './projectGraphSchema-DnD7orZV.js';
+
+/**
+ * STEP D: Ground-truth verification of project graph against code and SDK API index.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py verify_project_graph()
+ * Removes invalid files, APIs, keywords and logs hallucinations.
+ */
+
+interface Hallucination {
+    type: string;
+    item: string;
+    feature_id: string;
+    step_id: string;
+    reason: string;
+}
+interface VerifyOptions {
+    repoDir: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+}
+/**
+ * Verify project graph against actual code. Remove hallucinated files, APIs, keywords.
+ * F0 (foundation) keywords are kept as-is since they are pedagogical terms.
+ */
+declare function verifyProjectGraph(projectGraph: ProjectGraph, options: VerifyOptions): {
+    graph: ProjectGraph;
+    hallucinations: Hallucination[];
+};
+
+export { type Hallucination as H, type VerifyOptions as V, verifyProjectGraph as v };

package/dist/graphVerifier-QjgDAJce.d.cts

@@ -0,0 +1,37 @@
+import { u as ProjectGraph } from './projectGraphSchema-DnD7orZV.cjs';
+
+/**
+ * STEP D: Ground-truth verification of project graph against code and SDK API index.
+ *
+ * Ported from knowledge-tree/llm_project_graph.py verify_project_graph()
+ * Removes invalid files, APIs, keywords and logs hallucinations.
+ */
+
+interface Hallucination {
+    type: string;
+    item: string;
+    feature_id: string;
+    step_id: string;
+    reason: string;
+}
+interface VerifyOptions {
+    repoDir: string;
+    sdkApiIndex: {
+        sdk_apis: Array<{
+            name: string;
+            kind: string;
+            used_in_demo: boolean;
+        }>;
+    };
+    fileContentsMap: Map<string, string>;
+}
+/**
+ * Verify project graph against actual code. Remove hallucinated files, APIs, keywords.
+ * F0 (foundation) keywords are kept as-is since they are pedagogical terms.
+ */
+declare function verifyProjectGraph(projectGraph: ProjectGraph, options: VerifyOptions): {
+    graph: ProjectGraph;
+    hallucinations: Hallucination[];
+};
+
+export { type Hallucination as H, type VerifyOptions as V, verifyProjectGraph as v };