@modular-prompt/extract 1.0.0 → 1.2.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,cAAc,EACd,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export { createExtractSession } from './create-extract-session.js';
 export { createMlxExtractRuntime } from './create-mlx-extract-runtime.js';
+export { createPytorchExtractRuntime } from './create-pytorch-extract-runtime.js';
+export { createExtractRuntime } from './create-extract-runtime.js';
 export { createDriver, resolveMergedModels, resolveModelSpec, } from './model-resolution.js';
 export { resolveSessionModules } from './resolve-session-modules.js';
 export { resolveDefaultContainerDir, } from './cli/constants.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EACL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC"}

package/dist/model-resolution.d.ts

@@ -1,24 +1,34 @@
-import { type AIDriver, type ModelSpec, type ModelsConfig, type PromptCacheController } from '@modular-prompt/driver';
+import { type AIDriver, type MlxBackendMode, type ModelSpec, type ModelsConfig, type PromptCacheController } from '@modular-prompt/driver';
+import type { ExtractProvider } from './extract-runtime-types.js';
+export type { ExtractProvider } from './extract-runtime-types.js';
 /** createDriver に渡す extract 固有の runtime オプション */
 export interface ExtractDriverOptions {
     /** セッションと共有する KV cache controller */
     cacheController?: PromptCacheController;
+    /** Explicit extract provider, used for raw model IDs and store validation. */
+    provider?: ExtractProvider;
+    /** Persisted or explicitly selected MLX backend for extract. */
+    backend?: MlxBackendMode;
+    /** VLM image resize limit for driver/cache alignment. */
+    maxImageSize?: number;
 }
 export interface ExtractDriverResult {
     driver: AIDriver;
     /** alias 解決後の生 model ID */
     spec: ModelSpec;
 }
-/** bundled + user models.yaml を解決する（user の default/alias が優先）。 */
+export declare function isExtractProvider(value: unknown): value is ExtractProvider;
+/** user models.yaml を含む models 設定を解決する（user の default/alias を使用）。 */
 export declare function resolveMergedModels(): ModelsConfig;
 /**
  * extract で使用する ModelSpec を解決する。
  *
- * 優先順位は明示 model（alias または生 ID）→ models.default → models の先頭。
+ * 優先順位は明示 model（alias または生 ID）→ models.default。
+ * 同梱の暗黙 default や models の先頭エントリは使用しない。
  */
-export declare function resolveModelSpec(model: string | undefined, models?: ModelsConfig): ModelSpec;
+export declare function resolveModelSpec(model: string | undefined, models?: ModelsConfig, provider?: ExtractProvider): ModelSpec;
 /**
- * ModelSpec を AIService 経由で MLX driver に変換する。
+ * ModelSpec を AIService 経由で extract 対応 driver に変換する。
  * runtime が作成した cache controller は driver と共有する。
  */
 export declare function createDriver(model: string | undefined, options?: ExtractDriverOptions): Promise<ExtractDriverResult>;

package/dist/model-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolution.d.ts","sourceRoot":"","sources":["../src/model-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EAEb,KAAK,SAAS,EACd,KAAK,YAAY,EAEjB,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAGhC,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,QAAQ,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,SAAS,CAAC;CACjB;AAWD,kEAAkE;AAClE,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,GAAE,YAAoC,GAC3C,SAAS,CAgBX;AAyBD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAK9B"}
+{"version":3,"file":"model-resolution.d.ts","sourceRoot":"","sources":["../src/model-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EAGjB,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,gEAAgE;IAChE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,QAAQ,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAMD,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,GAAE,YAAoC,EAC5C,QAAQ,CAAC,EAAE,eAAe,GACzB,SAAS,CA6CX;AAmED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAQ9B"}

package/dist/model-resolution.js

@@ -1,56 +1,116 @@
-import { AIService, resolveDefaultModelFromConfig, resolveModelName, resolveModelReference, } from '@modular-prompt/driver';
+import { AIService, inferProvider, resolveModelName, resolveModelReference, } from '@modular-prompt/driver';
 import { BUNDLED_MODELS_CONFIG } from './default-models.js';
-function inferProvider(_model) {
-    // extract runtime は MLX 専用。生の model ID は MLX model として扱う。
-    return 'mlx';
+export function isExtractProvider(value) {
+    return value === 'mlx' || value === 'pytorch';
 }
 function createAIService() {
     return AIService.fromMergedConfig(BUNDLED_MODELS_CONFIG, undefined, { mode: 'merge' });
 }
-/** bundled + user models.yaml を解決する（user の default/alias が優先）。 */
+/** user models.yaml を含む models 設定を解決する（user の default/alias を使用）。 */
 export function resolveMergedModels() {
     return createAIService().modelsConfig;
 }
 /**
  * extract で使用する ModelSpec を解決する。
  *
- * 優先順位は明示 model（alias または生 ID）→ models.default → models の先頭。
+ * 優先順位は明示 model（alias または生 ID）→ models.default。
+ * 同梱の暗黙 default や models の先頭エントリは使用しない。
  */
-export function resolveModelSpec(model, models = resolveMergedModels()) {
+export function resolveModelSpec(model, models = resolveMergedModels(), provider) {
     const explicitModel = model?.trim();
     if (explicitModel) {
-        return resolveModelReference({ ref: explicitModel }, models)
-            ?? resolveModelName(explicitModel, models, inferProvider);
+        const alias = resolveModelReference({ ref: explicitModel }, models);
+        if (alias) {
+            if (provider && alias.provider !== provider) {
+                throw providerMismatchError(alias.model, provider, alias.provider);
+            }
+            return alias;
+        }
+        // Validate raw IDs against exact models.yaml matches when one exists.
+        // An explicit provider makes otherwise unconfigured raw IDs usable.
+        if (provider) {
+            const matchingEntry = Object.values(models.models ?? {})
+                .find(entry => entry.model === explicitModel);
+            if (matchingEntry) {
+                const configured = resolveModelName(explicitModel, models, inferProvider);
+                if (configured.provider !== provider) {
+                    throw providerMismatchError(explicitModel, provider, configured.provider);
+                }
+                return configured;
+            }
+            return {
+                model: explicitModel,
+                provider,
+                capabilities: [],
+            };
+        }
+        return resolveModelName(explicitModel, models, inferProvider);
     }
-    const fallback = resolveDefaultModelFromConfig(models);
-    if (fallback) {
-        return fallback;
+    const configuredDefault = resolveModelReference({ ref: 'default' }, models);
+    if (configuredDefault) {
+        if (provider && configuredDefault.provider !== provider) {
+            throw providerMismatchError(configuredDefault.model, provider, configuredDefault.provider);
+        }
+        return configuredDefault;
     }
-    throw new Error('No extract model configured: specify -m <model-id-or-alias> '
+    throw new Error('No model configured: specify -m <model-id-or-alias> '
         + 'or define models.default in ~/.modular-prompt/models.yaml');
 }
+function providerMismatchError(model, expected, actual) {
+    return new Error(`Extract provider mismatch for model '${model}': expected '${expected}', got '${actual}'`);
+}
 function withExtractDriverOptions(spec, options) {
-    if (spec.provider !== 'mlx') {
-        throw new Error(`Extract requires an MLX model, but '${spec.model}' uses provider '${spec.provider}'`);
+    if (spec.provider === 'mlx') {
+        const existingDriverOptions = spec.driverOptions;
+        // Preserve a model's explicit backend and let MLX auto-detect when none is
+        // configured.  In particular, extract must not force a VLM model through
+        // the mlx-lm backend just to enable prompt caching.
+        const backend = options.backend ?? spec.backend ?? existingDriverOptions?.backend ?? 'auto';
+        const maxImageSize = options.maxImageSize ?? existingDriverOptions?.maxImageSize;
+        const driverOptions = {
+            ...existingDriverOptions,
+            backend,
+            ...(maxImageSize !== undefined ? { maxImageSize } : {}),
+            ...(options.cacheController ? { cacheController: options.cacheController } : {}),
+        };
+        return {
+            ...spec,
+            backend,
+            driverOptions,
+        };
+    }
+    if (spec.provider === 'pytorch') {
+        const existingDriverOptions = spec.driverOptions;
+        // MLX-only backend/image options intentionally do not cross into the
+        // text-only PyTorch runtime. Keep PyTorch-specific options intact.
+        const pytorchSpec = { ...spec };
+        delete pytorchSpec.backend;
+        const driverOptions = {
+            ...(existingDriverOptions?.venvPath !== undefined
+                ? { venvPath: existingDriverOptions.venvPath }
+                : {}),
+            ...(existingDriverOptions?.device !== undefined
+                ? { device: existingDriverOptions.device }
+                : {}),
+            ...(existingDriverOptions?.cacheDir !== undefined
+                ? { cacheDir: existingDriverOptions.cacheDir }
+                : {}),
+            ...(options.cacheController ? { cacheController: options.cacheController } : {}),
+        };
+        return {
+            ...pytorchSpec,
+            driverOptions,
+        };
     }
-    const driverOptions = {
-        ...spec.driverOptions,
-        backend: 'lm',
-        ...(options.cacheController ? { cacheController: options.cacheController } : {}),
-    };
-    return {
-        ...spec,
-        backend: 'lm',
-        driverOptions,
-    };
+    throw new Error(`Extract supports MLX and PyTorch models, but '${spec.model}' uses provider '${spec.provider}'`);
 }
 /**
- * ModelSpec を AIService 経由で MLX driver に変換する。
+ * ModelSpec を AIService 経由で extract 対応 driver に変換する。
  * runtime が作成した cache controller は driver と共有する。
  */
 export async function createDriver(model, options = {}) {
     const ai = createAIService();
-    const spec = withExtractDriverOptions(resolveModelSpec(model, ai.modelsConfig), options);
+    const spec = withExtractDriverOptions(resolveModelSpec(model, ai.modelsConfig, options.provider), options);
     const driver = await ai.createDriver(spec);
     return { driver, spec };
 }

package/dist/model-resolution.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolution.js","sourceRoot":"","sources":["../src/model-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,6BAA6B,EAC7B,gBAAgB,EAChB,qBAAqB,GAOtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAc5D,SAAS,aAAa,CAAC,MAAc;IACnC,0DAA0D;IAC1D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe;IACtB,OAAO,SAAS,CAAC,gBAAgB,CAAC,qBAAqB,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,mBAAmB;IACjC,OAAO,eAAe,EAAE,CAAC,YAAY,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAyB,EACzB,SAAuB,mBAAmB,EAAE;IAE5C,MAAM,aAAa,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IACpC,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,qBAAqB,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC;eACvD,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,QAAQ,GAAG,6BAA6B,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,KAAK,CACb,8DAA8D;UAC5D,2DAA2D,CAC9D,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB,CAC/B,IAAe,EACf,OAA6B;IAE7B,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,CAAC,KAAK,oBAAoB,IAAI,CAAC,QAAQ,GAAG,CACtF,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAA0B;QAC3C,GAAI,IAAI,CAAC,aAAmD;QAC5D,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjF,CAAC;IAEF,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,IAAI;QACb,aAAa;KACd,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAyB,EACzB,UAAgC,EAAE;IAElC,MAAM,EAAE,GAAG,eAAe,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,wBAAwB,CAAC,gBAAgB,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;IACzF,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"model-resolution.js","sourceRoot":"","sources":["../src/model-resolution.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -16,6 +16,12 @@ export interface ExtractSessionOptions<TContext = ExtractContext> {
     cacheController: PromptCacheController;
     /** Model identifier for cache prepare (must match the driver). */
     model: string;
+    /**
+     * Maximum image edge used by the MLX VLM cache normalizer.  The MLX extract
+     * runtime supplies this automatically; custom sessions should match the
+     * driver's `maxImageSize` setting.
+     */
+    maxImageSize?: number;
     /**
      * Base prompt for extraction task.
      * 省略時は {@link defaultExtractBaseModule} を使用する。
@@ -30,6 +36,12 @@ export interface ExtractSessionOptions<TContext = ExtractContext> {
     corpus: ExtractCorpus;
     /** Output schema (Phase 3: structured output). Accepted at session creation. */
     schema?: object;
+    /**
+     * Automatically create a missing disk cache. Existing cache hits remain
+     * usable when this is false; misses fall back to an uncached query.
+     * Defaults to true.
+     */
+    autoRebuildCache?: boolean;
     /**
      * Cache preparation policy. Normal sessions are best-effort; store
      * preparation uses `required` so an empty cache handle cannot be committed.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,qBAAqB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ,GAAG,cAAc;IAC9D,MAAM,EAAE,QAAQ,CAAC;IACjB,kDAAkD;IAClD,eAAe,EAAE,qBAAqB,CAAC;IACvC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,kDAAkD;IAClD,MAAM,EAAE,aAAa,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzD,UAAU,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,KAAK,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,qBAAqB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ,GAAG,cAAc;IAC9D,MAAM,EAAE,QAAQ,CAAC;IACjB,kDAAkD;IAClD,eAAe,EAAE,qBAAqB,CAAC;IACvC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,kDAAkD;IAClD,MAAM,EAAE,aAAa,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzD,UAAU,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,KAAK,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D"}

package/docs/API.md

@@ -0,0 +1,320 @@
+# @modular-prompt/extract API 仕様
+
+> **対象バージョン**: `0.1.0`  
+> **利用者向けガイド**: [README.md](./README.md)（サンプル・キャッシュ制約含む）
+
+## 概要
+
+`@modular-prompt/extract` は、同一 corpus（文書・対話ログ）に対して **複数の切り口（cue）で繰り返し情報抽出** するためのセッション API を提供する。
+
+- 基盤プロンプト（`baseModule`）と corpus（`materials` / `messages`）はセッション存続中固定
+- 各 `extract()` 呼び出しで `cue`（出力切り口）と `inputs`（補強情報）を差し替え
+- **KV キャッシュ連携は必須** — `driver` / `cacheController` / `model` は呼び出し側が用意する
+- **リソースのライフサイクルは呼び出し側が管理** — `ExtractSession.close()` はセッション内 cache handle の `release()` のみ行う
+
+## 責務の分離
+
+| コンポーネント | 生成 | 終了 |
+|--------------|------|------|
+| `driver` + `cacheController` | 呼び出し側（または provider runtime factory） | 呼び出し側（`runtime.close()` 等） |
+| `ExtractSession` | `createExtractSession()` | `session.close()` — handle `release()` のみ |
+
+`ExtractSession` は driver / cacheController を **借りる** だけで、所有しない。
+
+---
+
+## モジュール構成
+
+```
+base (+ domain) + corpus (materials / messages) + request (inputs) ← cue
+```
+
+| レイヤ | 指定方法 | 役割 |
+|--------|---------|------|
+| **base** | 省略可 → `defaultExtractBaseModule` | 抽出タスクの基本方針 |
+| **domain** | `domainModule`（任意） | 用語定義・追加指示などのドメイン調整 |
+| **data** | `corpus` + `request.inputs` | 抽出対象・補強情報 |
+| **cue** | `request.cue` | 今回の抽出切り口 |
+
+### 入力型（最小入力 → Element 正規化）
+
+API 境界では Element を直接渡さない。`buildExtractContext` が正規化する。
+
+| スロット | 入力型 | 正規化結果 |
+|---------|--------|-----------|
+| `corpus.materials` | `MaterialInput \| MaterialInput[]` | `MaterialElement`（`cacheHint: immutable`） |
+| `corpus.messages` | `MessageInput \| MessageInput[]` | `MessageElement`（role 別 cacheHint） |
+| `request.inputs` | `string \| ChunkInput \| ...[]` | `ChunkElement`（`cacheHint: contextual`） |
+| `request.cue` | `string \| SectionContent` | `TextElement`（`cacheHint: contextual`） |
+
+#### `MaterialInput`
+
+```typescript
+{ title: string; content: string | Attachment[]; id?: string; usage?: number }
+```
+
+`id` 省略時は `title` を使用。
+
+library API では `content: Attachment[]` による画像 material を指定できます。MLX VLM の画像 cache 経路で利用できる画像は local file path のみで、URL / data URI は未対応です。CLI の `create` / `add` は入力ファイルを UTF-8 text として読むだけで `Attachment` を生成しないため、CLI 画像 material は Phase 3 の対象外です。
+
+#### `MessageInput`
+
+標準: `{ role: 'system' | 'assistant' | 'user'; content: ... }`  
+ツール結果: `{ role: 'tool'; toolCallId; name; kind; value }`
+
+#### `ChunkInput` / `ChunkInputValue`
+
+`string` は `content` の省略記法。`partOf` 省略時は `'inputs'`。
+
+---
+
+## エントリポイント
+
+```typescript
+import {
+  createExtractSession,
+  createMlxExtractRuntime,
+  createPytorchExtractRuntime,
+  createExtractRuntime,
+  resolveModelSpec,
+  createDriver,
+  buildPreviousExtractionsInputs,
+  inputChunk,
+  inputChunksFromJson,
+  mergeExtractBaseModule,
+  defaultExtractBaseModule,
+  resolveDefaultContainerDir,
+  resolveStoreDir,
+  validateStorename,
+} from '@modular-prompt/extract';
+```
+
+named store のパス解決と入力検証をライブラリから利用する場合:
+
+```typescript
+import {
+  resolveDefaultContainerDir,
+  resolveStoreDir,
+  validateStorename,
+} from '@modular-prompt/extract';
+
+validateStorename('meeting');
+const storeDir = resolveStoreDir(resolveDefaultContainerDir(), 'meeting');
+```
+
+### 公開シンボル
+
+| シンボル | 種別 | 説明 |
+|---------|------|------|
+| `createExtractSession` | 関数 | 抽出セッションを生成 |
+| `createMlxExtractRuntime` | 関数 | MLX 用 driver + cacheController バンドル |
+| `createPytorchExtractRuntime` | 関数 | PyTorch 用 driver + cacheController バンドル（text-only） |
+| `createExtractRuntime` | 関数 | 解決済み provider に応じた runtime factory |
+| `resolveModelSpec` | 関数 | models.yaml の alias または生 model ID を extract 用 ModelSpec に解決 |
+| `createDriver` | 関数 | 解決済み ModelSpec から AIService 経由で MLX / PyTorch driver を生成 |
+| `resolveSessionModules` | 関数 | base (+ domain) モジュールを解決 |
+| `resolveDefaultContainerDir` | 関数 | `MODULAR_PROMPT_HOME` に基づくデフォルト cache container を解決 |
+| `resolveStoreDir` | 関数 | cache コンテナと storename から store ディレクトリを解決 |
+| `validateStorename` | 関数 | storename の形式と予約語を検証 |
+| `compileExtractPrompt` | 関数 | context 付き compile（高度な用途） |
+| `buildExtractContext` | 関数 | corpus + request から `ExtractContext` を構築 |
+| `defaultExtractBaseModule` | 定数 | デフォルト base `PromptModule` |
+| `mergeExtractBaseModule` | 関数 | デフォルト base に overlay を merge |
+| `buildPreviousExtractionsInputs` | 関数 | 過去抽出結果を `inputs` に変換 |
+| `formatPreviousExtractions` | 関数 | 過去抽出結果をテキストブロック列に整形 |
+| `inputChunk` / `inputChunksFromJson` | 関数 | chunk 入力ヘルパ |
+| `normalizeMaterials` 等 | 関数 | 正規化ヘルパ（テスト・高度な用途） |
+
+### 内部 API（named store 拡張の共有実装）
+
+`src/extract-store.ts` は package root からは export しない内部 API ですが、CLI と将来の store 管理入口が共有する disk 上の store 操作を担当します。`add-command.ts` はファイル読み込み、引数由来のエラー、`--dry-run` の出力だけを担当し、prefill と manifest の更新はこの層を呼び出します。
+
+| API | 入力 / 出力 | 責務と保証 |
+|-----|-------------|------------|
+| `mergeMaterials(existing, incoming)` | `MaterialInput[]` → merged `MaterialInput[]` | `id`（省略時は `title`）で順序を保ってマージ。同一 id・同一内容はスキップし、内容差分はエラー |
+| `prepareExtractCache({ cacheDir, model, provider?, backend?, maxImageSize?, materials })` | `Promise<{ model, provider, backend?, maxImageSize? }>`（解決済み model/provider） | prepare cue で corpus を KV prefill し、session/runtime を close。manifest は変更しない |
+| `ensureStoreKvCache({ storeDir, storename, manifest?, autoRebuildCache? })` | `Promise<{ status, rebuilt }>` | extract 前に cache-index と cache 実体を検査し、必要なら staging store で manifest から full prefill。manifest は変更しない |
+| `appendToExtractStore({ storeDir, storename, incomingMaterials, existingManifest?, now?, autoRebuildCache? })` | `Promise<{ manifest, model, provider, backend?, addedMaterials, cacheRebuilt }>` | 既存 store を staging に複製して incremental prefill と manifest 更新を行い、成功時に rename 交換。incremental base が無い場合は既定で full prefill にフォールバックし、`autoRebuildCache: false` なら明示エラーで停止する。prefill / manifest / runtime の失敗時は元の corpus・manifest・KV を保持 |
+
+`appendToExtractStore` は `manifest.provider`（未指定の legacy manifest は MLX）、`manifest.model`、`manifest.backend`（MLX のみ。未指定時は `auto` fallback）、および保存済み `maxImageSize` を使い、provider + model の不一致を検証します。成功時だけ `updatedAt`、materials、解決済み provider/backend、画像 resize 条件を反映します。`readExtractStoreManifest` は store の存在と manifest を検証し、存在しない store には `create` を案内するエラーを返します。ライブラリ層のマージ、prefill、失敗時保全は `src/extract-store.test.ts` で CLI から独立して検証しています。
+
+---
+
+create/add が内部で使う `prepareExtractCache` は `cachePreparation: 'required'` で session を実行するため、cache controller が空 handle を返した場合は driver query、manifest 書き込み、store の rename 交換に進みません。通常の `createExtractSession` は省略時の `best-effort` 契約を維持します。
+
+## `createMlxExtractRuntime(options)`
+
+```typescript
+function createMlxExtractRuntime(
+  options: MlxExtractRuntimeOptions
+): Promise<MlxExtractRuntime>
+```
+
+| プロパティ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | `string` | — | MLX モデルの alias または生の HF model ID。省略時は user models.yaml の `models.default` から解決。未設定時はエラー |
+| `backend` | `'auto' \| 'lm' \| 'vlm' \| 'optiq'` | — | MLX backend の明示指定。省略時は models.yaml の指定、さらに未指定なら `auto` |
+| `cacheDir` | `string` | — | 固定キャッシュディレクトリ。省略時は managed temp dir |
+| `maxImageSize` | `number` | — | VLM 画像キャッシュの最大辺。省略時は models.yaml の指定、さらに未指定なら 768 |
+
+`MlxExtractRuntime.close()` は `driver.close()` + `cacheController.close()` を行う。
+
+runtime の `backend` プロパティは実際に driver へ渡した選択値であり、extract store の manifest に保存されます。backend のない既存 manifest は `auto` として再開します。
+
+`createMlxExtractRuntime` は AIService 経由でモデルを解決・生成し、models.yaml の MLX backend 指定を保持する。backend 未指定時は `auto` としてモデル種別に応じて `mlx-lm` / `mlx-vlm` を選択する。`backend: 'vlm'` の場合、画像なしの text-only exact KV cache と、画像 material を含む vision cache を固定 cacheDir に別 namespace で永続化できる。画像付き cache は text-only VLM / LM cache と非互換で、VLM incremental prefill は対象外。モデル指定を省略した場合は user の `~/.modular-prompt/models.yaml` にある `models.default` を使用する。同梱モデルや `models` の先頭エントリへの fallback はなく、モデル未設定時は driver 作成前にエラーになる。生の model ID を指定する場合は、models.yaml の一致エントリで `provider: mlx` を設定するか、既知の MLX model 名パターンを使用してください。provider を推論できない ID はエラーになります。
+
+## `createPytorchExtractRuntime(options)`
+
+```typescript
+function createPytorchExtractRuntime(
+  options: PyTorchExtractRuntimeOptions
+): Promise<PyTorchExtractRuntime>
+```
+
+| プロパティ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `model` | `string` | — | PyTorch (Transformers) モデルの alias または生の HF model ID。省略時は user models.yaml の `models.default` から解決 |
+| `cacheDir` | `string` | — | 固定キャッシュディレクトリ。省略時は managed temp dir |
+
+PyTorch runtime は `PyTorchCacheController` と `PyTorchDriver` を共有し、`getCapabilities()` で cache binding を完了してから返します。現状の PyTorch backend は text-only のため、MLX の `backend` / `maxImageSize` は渡されません。`runtime.close()` は driver と cache controller を解放します。
+
+## `createExtractRuntime(options)`
+
+`createExtractRuntime({ model, provider?, cacheDir?, backend?, maxImageSize? })` は alias / raw model の解決結果に応じて MLX または PyTorch runtime を生成します。`provider` を指定した場合は models.yaml の alias/provider と一致することを検証し、raw model ID の provider を明示できます。PyTorch では `backend` / `maxImageSize` は無視されます。
+
+`createDriver(model, { provider?, cacheController, backend?, maxImageSize? })` は runtime 内部で使用する低レベル helper で、戻り値は `{ driver, spec }`。`spec.model` は alias 解決後の生 model ID である。
+
+---
+
+## `createExtractSession(options)`
+
+```typescript
+function createExtractSession<TContext = ExtractContext>(
+  options: ExtractSessionOptions<TContext>
+): ExtractSession
+```
+
+### `ExtractSessionOptions<TContext>`
+
+| プロパティ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `driver` | `AIDriver` | ✅ | 推論実行ドライバー |
+| `cacheController` | `PromptCacheController` | ✅ | KV キャッシュコントローラ |
+| `model` | `string` | ✅ | `prepare()` 用モデル識別子 |
+| `baseModule` | `PromptModule<TContext>` | — | 省略時 `defaultExtractBaseModule` |
+| `domainModule` | `PromptModule<TContext>` | — | base の上に merge |
+| `corpus` | `ExtractCorpus` | ✅ | セッション固定 corpus |
+| `schema` | `object` | — | JSON Schema（structured output） |
+| `autoRebuildCache` | `boolean` | — | 欠損 cache を自動作成するか（既定 `true`）。`false` では既存 cache の read-only hit のみ利用し、miss は cache を作らず uncached query にフォールバック |
+| `cachePreparation` | `'best-effort' \| 'required'` | — | 通常は `best-effort`（省略時）。`required` は空 handle をエラーにして driver query を実行しない |
+| `maxImageSize` | `number` | — | VLM 画像キャッシュの正規化に使う最大辺。driver の設定と一致させる。runtime 経由では自動設定 |
+
+#### `ExtractCorpus`
+
+| プロパティ | 型 | 説明 |
+|-----------|-----|------|
+| `materials` | `MaterialsInput` | 文書 corpus |
+| `messages` | `MessagesInput` | 対話ログ |
+
+### `ExtractSession.extract(request)`
+
+#### `ExtractRequest`
+
+| プロパティ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `cue` | `string \| SectionContent` | ✅ | 抽出切り口 |
+| `inputs` | `InputsInput` | — | 補強情報 |
+| `options` | `QueryOptions` | — | ドライバークエリオプション |
+
+#### `ExtractResult`
+
+| プロパティ | 型 | 説明 |
+|-----------|-----|------|
+| `text` | `string` | 抽出テキスト |
+| `structured` | `unknown` | schema 指定時の構造化出力 |
+| `usage` | `QueryResult['usage']` | トークン使用量（`cacheReadTokens` 含む） |
+| `index` | `number` | セッション内連番（0 始まり） |
+
+### `getHistory()` / `close()`
+
+- `getHistory()` — セッション内全結果のコピー
+- `close(options?)` — セッション終了（冪等）。`close()` 後の `extract()` は拒否
+  - `releaseCache`（デフォルト `true`）— `false` のとき handle を release しない。固定 cacheDir をプロセス間で再利用する場合に使う
+  - `releaseCache: true` のとき `cacheController.release()` が呼ばれ、続く `runtime.close()` で KV ファイルが削除される（固定 cacheDir モード）
+
+CLI の `clean <storename>` で store 単位、`clean --all` で cache container 全体を削除できる。対象が存在しない場合は no-op になる。
+
+---
+
+## CLI（`modular-prompt-extract`）
+
+`modular-prompt-extract` は cache container 内に named store を作成・利用する。`-d` の値は container パスで、create/add/extract/list/clean 共通で使用する。省略時は `~/.modular-prompt/extract-cache`（`MODULAR_PROMPT_HOME` を設定した場合は `${MODULAR_PROMPT_HOME}/extract-cache`）。
+
+CLI の `create` / `add` は各入力ファイルを UTF-8 の文字列として `MaterialInput.content` に格納します。画像ファイルを `Attachment` に変換する CLI 経路はなく、CLI 画像 material は Phase 3 の対象外です。画像 material の縦切りは library API の `MaterialInput.content: Attachment[]` を使用してください。
+
+```bash
+modular-prompt-extract create <storename> [-m <model>] [--provider <mlx|pytorch>] [--dry-run] <files...>
+modular-prompt-extract add <storename> [--auto-rebuild-cache|--no-auto-rebuild-cache] [--dry-run] <files...>
+modular-prompt-extract extract <storename> [--max-tokens <n>] [--auto-rebuild-cache|--no-auto-rebuild-cache] [--dry-run] <query...>
+modular-prompt-extract list
+modular-prompt-extract clean <storename>
+modular-prompt-extract clean --all
+```
+
+container を指定する場合は、各コマンドに `-d <cache-dir>` を追加する。
+
+```bash
+modular-prompt-extract create meeting -d ~/.modular-prompt/extract-cache -m default docs/meeting.txt
+modular-prompt-extract add meeting -d ~/.modular-prompt/extract-cache docs/day2.txt
+modular-prompt-extract extract meeting -d ~/.modular-prompt/extract-cache '参加者を列挙'
+modular-prompt-extract list -d ~/.modular-prompt/extract-cache
+modular-prompt-extract clean meeting -d ~/.modular-prompt/extract-cache
+modular-prompt-extract clean --all -d ~/.modular-prompt/extract-cache
+```
+
+`<storename>` は create/add/extract/clean の positional 第1引数として必須（`clean --all` を除く）で、`[a-zA-Z0-9][a-zA-Z0-9_-]*` に一致する必要がある。`create`、`add`、`extract`、`list`、`clean` は予約語である。
+
+`add <storename> [--dry-run] <files...>` は既存 store の manifest にファイルを追記し、manifest の model で prepare cue を実行する。既存 cache を staging store に複製してから incremental prefill と manifest 更新を行い、成功時にだけ store を入れ替える。incremental base が無い場合は既定で full prefill にフォールバックし、再生成時だけ stderr に warning を出す。`--no-auto-rebuild-cache` を指定すると、その場合は明示エラーで停止する。prefill または manifest 更新が失敗した場合は元の store を保持する。同じ絶対パス `id` の同一内容はスキップし、内容が異なる場合は `clean` + `create` を案内してエラーにする。
+
+`add --dry-run` はマージ後の compile 済みプロンプトを表示し、driver の起動・KV cache の書き込み・manifest の更新を行わない。`add` では `-m`、`--provider`、`--max-tokens` は指定できない。create の `--provider` は `mlx` または `pytorch` を受け付け、以降の add/extract は manifest に保存された provider を使用する。
+
+`create` は store と `manifest.json` を作るために必須です。KV cache は manifest から再生成できる派生データであり、`extract` は欠損・破損・`cache-index.json` が指す実体の欠損を検知すると既定で full prefill を行ってから抽出を続けます。`list` の `KV cache: missing` はこの復旧対象を示します。`MODULAR_PROMPT_EXTRACT_AUTO_REBUILD_CACHE=false`（`0` / `no` / `off` も可）または `--no-auto-rebuild-cache` で自動再生成を無効化できます。環境変数が OFF のときに一時的に有効化する場合は `--auto-rebuild-cache` を指定します。CLI 引数が環境変数より優先され、既定値は有効です。ライブラリの `ExtractSessionOptions.autoRebuildCache: false` では既存 cache の read-only hit を利用し、miss は cache を作らず uncached query にフォールバックします。
+
+これは破壊的変更であり、旧 CLI 引数形式と旧レイアウト（container 直下の `manifest.json` と cache files）はサポートしない。旧デフォルト `./.extract-cache` の自動検出・自動移行も行わない。既存データを利用する場合は、[README の旧 CLI / キャッシュレイアウトからの手動移行手順](./README.md#旧-cli--キャッシュレイアウトからの移行)に従って、新しいデフォルトまたは `-d` で指定した store container へ移動する。
+
+---
+
+## キャッシュ連携
+
+毎回の `extract()` で:
+
+1. `compileExtractPrompt` — `ExtractContext` を解決して compile
+2. `cacheController.prepare()` — cacheable 部分を prefill
+3. `supersedes` 返却時 — 旧 handle を `release()`
+4. `driver.query()` — `{ cache: false, cacheHandle }` で二重 prepare を回避
+
+| セクション | キャッシュ |
+|-----------|-----------|
+| baseModule（instructions） | ✅ |
+| corpus（materials, messages） | ✅ |
+| inputs | ✅（incremental） |
+| cue | ❌ |
+
+### 制約（再掲）
+
+- **corpus / baseModule 変更** → 新セッション
+- **inputs 累積** → 自動ではない。`buildPreviousExtractionsInputs` 等で明示的に渡す
+- **driver / cacheController の close** → 呼び出し側（`runtime.close()`）
+
+---
+
+## 実装状況
+
+| 項目 | 状態 |
+|------|------|
+| Phase 1 コア API | ✅ |
+| Phase 2 キャッシュ統合 | ✅ |
+| Phase 3 便利機能 | ✅ |
+| Phase 4 ドキュメント・サンプル | ✅ |
+
+**テスト**: `pnpm --filter @modular-prompt/extract test:run`