@workglow/ai 0.0.126 → 0.1.0

package/README.md

@@ -45,15 +45,19 @@ const modelRepo = new InMemoryModelRepository();
 setGlobalModelRepository(modelRepo);
 
 // 2. Add a local ONNX model (Hugging Face Transformers)
+
 await modelRepo.addModel({
   model_id: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
-  tasks: ["TextGenerationTask","TextRewriterTask"],
-  title: "LaMini-Flan-T5-783M",
-  description: "LaMini-Flan-T5-783M quantized to 8bit",
   provider: HF_TRANSFORMERS_ONNX,
   provider_config: {
     pipeline: "text2text-generation",
-    model_path: "Xenova/LaMini-Flan-T5-783M"
+    model_path: "Xenova/LaMini-Flan-T5-783M",
+    dtype: "q8",
+  },
+  tasks: ["TextGenerationTask", "TextRewriterTask"],
+  title: "LaMini-Flan-T5-783M",
+  description: "LaMini-Flan-T5-783M quantized to 8bit",
+  metadata: {},
 });
 
 // 3. Register provider (inline: full ONNX stack in this bundle; creates queue automatically)
@@ -103,9 +107,19 @@ Generates text based on prompts using language models.
 
 ```typescript
 import { TextGenerationTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
 
 const task = new TextGenerationTask({
-  model: "onnx:Xenova/gpt2:q8",
+  model: gpt2ModelConfig,
   prompt: "Explain quantum computing in simple terms",
 });
 
@@ -119,9 +133,20 @@ Generates vector embeddings for text using embedding models.
 
 ```typescript
 import { TextEmbeddingTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const embeddingModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "feature-extraction",
+    model_path: "Xenova/LaMini-Flan-T5-783M",
+    dtype: "q8",
+    native_dimensions: 384,
+  },
+} as const;
 
 const task = new TextEmbeddingTask({
-  model: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
+  model: embeddingModelConfig,
   text: "This is a sample text for embedding",
 });
 
@@ -153,9 +178,19 @@ Generates summaries of longer text content.
 
 ```typescript
 import { TextSummaryTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const summarizationModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "summarization",
+    model_path: "Falconsai/text_summarization",
+    dtype: "fp32",
+  },
+} as const;
 
 const task = new TextSummaryTask({
-  model: "onnx:Falconsai/text_summarization:fp32",
+  model: summarizationModelConfig,
   text: "Long article content here...",
   maxLength: 100,
 });
@@ -170,9 +205,19 @@ Rewrites text in different styles or tones.
 
 ```typescript
 import { TextRewriterTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const laMiniModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text2text-generation",
+    model_path: "Xenova/LaMini-Flan-T5-783M",
+    dtype: "q8",
+  },
+} as const;
 
 const task = new TextRewriterTask({
-  model: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
+  model: laMiniModelConfig,
   text: "This is a formal business proposal.",
   style: "casual",
 });
@@ -187,9 +232,19 @@ Answers questions based on provided context.
 
 ```typescript
 import { TextQuestionAnswerTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const squadModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "question-answering",
+    model_path: "Xenova/distilbert-base-uncased-distilled-squad",
+    dtype: "q8",
+  },
+} as const;
 
 const task = new TextQuestionAnswerTask({
-  model: "onnx:Xenova/distilbert-base-uncased-distilled-squad:q8",
+  model: squadModelConfig,
   context: "The capital of France is Paris. It has a population of about 2.1 million.",
   question: "What is the population of Paris?",
 });
@@ -206,9 +261,20 @@ Computes similarity between texts or embeddings.
 
 ```typescript
 import { VectorSimilarityTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gteSmallConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "feature-extraction",
+    model_path: "Supabase/gte-small",
+    dtype: "q8",
+    native_dimensions: 384,
+  },
+} as const;
 
 const task = new VectorSimilarityTask({
-  model: "onnx:Supabase/gte-small:q8",
+  model: gteSmallConfig,
   text1: "I love programming",
   text2: "Coding is my passion",
 });
@@ -225,17 +291,21 @@ Downloads and prepares AI models for use.
 
 ```typescript
 import { DownloadModelTask } from "@workglow/ai";
-
 import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
 
 const task = new DownloadModelTask({
-  modelName: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
-  modelUrl: "Xenova/LaMini-Flan-T5-783M",
-  provider: HF_TRANSFORMERS_ONNX,
+  model: {
+    provider: HF_TRANSFORMERS_ONNX,
+    provider_config: {
+      pipeline: "text2text-generation",
+      model_path: "Xenova/LaMini-Flan-T5-783M",
+      dtype: "q8",
+    },
+  },
 });
 
 const result = await task.run();
-// Output: { status: "downloaded", path: "/models/..." }
+// Output includes resolved model config after download
 ```
 
 ## Model Management
@@ -299,18 +369,27 @@ import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
 
 const modelRepo = getGlobalModelRepository();
 
+const gpt2ModelRecord = {
+  model_id: "onnx:Xenova/gpt2:q8",
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
+
 // Add an ONNX model from Hugging Face
 await modelRepo.addModel({
-  name: "onnx:Xenova/gpt2:q8",
-  url: "Xenova/gpt2",
-  provider: HF_TRANSFORMERS_ONNX,
-  availableOnBrowser: true,
-  availableOnServer: true,
-  contextWindow: 8192,
+  ...gpt2ModelRecord,
+  tasks: ["TextGenerationTask"],
+  title: "GPT-2",
+  description: "GPT-2 ONNX",
+  metadata: {},
 });
 
 // Connect model to specific tasks
-await modelRepo.connectTaskToModel("TextGenerationTask", "onnx:Xenova/gpt2:q8");
+await modelRepo.connectTaskToModel("TextGenerationTask", gpt2ModelRecord.model_id);
 
 // Find models for a specific task
 const textGenModels = await modelRepo.findModelsByTask("TextGenerationTask");
@@ -378,22 +457,41 @@ AI tasks integrate seamlessly with Workglow workflows:
 
 ```typescript
 import { Workflow } from "@workglow/task-graph";
-import { TextGenerationTask, TextEmbeddingTask, VectorSimilarityTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
+
+const gteSmallConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "feature-extraction",
+    model_path: "Supabase/gte-small",
+    dtype: "q8",
+    native_dimensions: 384,
+  },
+} as const;
 
 const workflow = new Workflow();
 
 // Chain AI tasks together
 const result = await workflow
   .textGeneration({
-    model: "onnx:Xenova/gpt2:q8",
+    model: gpt2ModelConfig,
     prompt: "Write about artificial intelligence",
   })
   .textEmbedding({
-    model: "onnx:Supabase/gte-small:q8",
+    model: gteSmallConfig,
     text: workflow.previous().text, // Use previous task output
   })
   .similarity({
-    model: "onnx:Supabase/gte-small:q8",
+    model: gteSmallConfig,
     text1: "artificial intelligence",
     embedding2: workflow.previous().vector, // Use embedding from previous task
   })
@@ -441,6 +539,41 @@ The AI package provides a comprehensive set of tasks for building RAG pipelines.
 ```typescript
 import { Workflow } from "@workglow/task-graph";
 import { createKnowledgeBase } from "@workglow/knowledge-base";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+// 1. Set up a model repository
+const modelRepo = new InMemoryModelRepository();
+setGlobalModelRepository(modelRepo);
+
+// 2. Add a local ONNX model (Hugging Face Transformers)
+await modelRepo.addModel({
+  model_id: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text2text-generation",
+    model_path: "Xenova/LaMini-Flan-T5-783M",
+    dtype: "q8",
+  },
+  tasks: ["TextGenerationTask", "TextRewriterTask"],
+  title: "LaMini-Flan-T5-783M",
+  description: "LaMini-Flan-T5-783M quantized to 8bit",
+  metadata: {},
+});
+
+await modelRepo.addModel({
+  model_id: "onnx:Xenova/all-MiniLM-L6-v2:q8",
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "feature-extraction",
+    model_path: "Xenova/all-MiniLM-L6-v2",
+    dtype: "q8",
+    native_dimensions: 384,
+  },
+  tasks: ["TextEmbeddingTask"],
+  title: "All MiniLM L6 V2 384D",
+  description: "Xenova/all-MiniLM-L6-v2",
+  metadata: {},
+});
 
 // Create a KnowledgeBase (auto-registers globally as "my-kb")
 const kb = await createKnowledgeBase({
@@ -465,7 +598,7 @@ await new Workflow()
     strategy: "hierarchical",
   })
   .textEmbedding({
-    model: "Xenova/all-MiniLM-L6-v2",
+    model: "onnx:Xenova/all-MiniLM-L6-v2:q8",
   })
   .chunkToVector()
   .chunkVectorUpsert({
@@ -478,7 +611,7 @@ const result = await new Workflow()
   .chunkRetrieval({
     knowledgeBase: "my-kb",
     query: "What is transfer learning?",
-    model: "Xenova/all-MiniLM-L6-v2",
+    model: "onnx:Xenova/all-MiniLM-L6-v2:q8",
     topK: 10,
   })
   .reranker({
@@ -491,7 +624,7 @@ const result = await new Workflow()
   })
   .textQuestionAnswer({
     question: "What is transfer learning?",
-    model: "Xenova/LaMini-Flan-T5-783M",
+    model: "onnx:Xenova/LaMini-Flan-T5-783M:q8",
   })
   .run();
 ```
@@ -565,26 +698,24 @@ AI tasks accept model inputs as either string identifiers or direct `ModelConfig
 
 ```typescript
 import { TextGenerationTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
 
-// Using a model ID (resolved from ModelRepository)
-const task1 = new TextGenerationTask({
-  model: "onnx:Xenova/gpt2:q8",
-  prompt: "Generate text",
-});
-
-// Using a direct ModelConfig object
-const task2 = new TextGenerationTask({
-  model: {
-    model_id: "onnx:Xenova/gpt2:q8",
-    provider: "hf-transformers-onnx",
-    tasks: ["TextGenerationTask"],
-    title: "GPT-2",
-    provider_config: { pipeline: "text-generation" },
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
   },
+} as const;
+
+// Inline ModelConfig (provider + provider_config)
+const task = new TextGenerationTask({
+  model: gpt2ModelConfig,
   prompt: "Generate text",
 });
 
-// Both approaches work identically
+// Registered model_id strings (e.g. onnx:org/model:q8) are still resolved via ModelRepository when you pass a string instead
 ```
 
 This resolution is handled by the input resolver system, which inspects schema `format` annotations (like `"model"` or `"model:TextGenerationTask"`) to determine how string values should be resolved.
@@ -604,9 +735,21 @@ This resolution is handled by the input resolver system, which inspects schema `
 Tasks automatically validate that specified models exist and are compatible:
 
 ```typescript
+import { TextGenerationTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
+
 // Models are validated before task execution
 const task = new TextGenerationTask({
-  model: "onnx:Xenova/gpt2:q8", // Must exist in ModelRepository and be connected to TextGenerationTask
+  model: gpt2ModelConfig,
   prompt: "Generate text",
 });
 
@@ -618,8 +761,20 @@ const task = new TextGenerationTask({
 Monitor AI task progress:
 
 ```typescript
+import { TextGenerationTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
+
 const task = new TextGenerationTask({
-  model: "onnx:Xenova/gpt2:q8",
+  model: gpt2ModelConfig,
   prompt: "Long generation task...",
 });
 
@@ -635,10 +790,22 @@ const result = await task.run();
 All AI tasks support cancellation via AbortSignal:
 
 ```typescript
+import { TextGenerationTask } from "@workglow/ai";
+import { HF_TRANSFORMERS_ONNX } from "@workglow/ai-provider/hf-transformers";
+
+const gpt2ModelConfig = {
+  provider: HF_TRANSFORMERS_ONNX,
+  provider_config: {
+    pipeline: "text-generation",
+    model_path: "Xenova/gpt2",
+    dtype: "q8",
+  },
+} as const;
+
 const controller = new AbortController();
 
 const task = new TextGenerationTask({
-  model: "onnx:Xenova/gpt2:q8",
+  model: gpt2ModelConfig,
   prompt: "Generate text...",
 });