@huggingface/tasks 0.0.5 → 0.0.7

package/README.md

@@ -9,7 +9,7 @@ The Task pages are made to lower the barrier of entry to understand a task that
 The task pages avoid jargon to let everyone understand the documentation, and if specific terminology is needed, it is explained on the most basic level possible. This is important to understand before contributing to Tasks: at the end of every task page, the user is expected to be able to find and pull a model from the Hub and use it on their data and see if it works for their use case to come up with a proof of concept.
 
 ## How to Contribute
-You can open a pull request to contribute a new documentation about a new task. Under `src` we have a folder for every task that contains two files, `about.md` and `data.ts`. `about.md` contains the markdown part of the page, use cases, resources and minimal code block to infer a model that belongs to the task. `data.ts` contains redirections to canonical models and datasets, metrics, the schema of the task and the information the inference widget needs. 
+You can open a pull request to contribute a new documentation about a new task. Under `src/tasks` we have a folder for every task that contains two files, `about.md` and `data.ts`. `about.md` contains the markdown part of the page, use cases, resources and minimal code block to infer a model that belongs to the task. `data.ts` contains redirections to canonical models and datasets, metrics, the schema of the task and the information the inference widget needs. 
 
 ![Anatomy of a Task Page](https://huggingface.co/datasets/huggingfacejs/tasks/resolve/main/contribution-guide/anatomy.png)
 
@@ -17,4 +17,18 @@ We have a [`dataset`](https://huggingface.co/datasets/huggingfacejs/tasks) that
 
 ![Libraries of a Task](https://huggingface.co/datasets/huggingfacejs/tasks/resolve/main/contribution-guide/libraries.png)
 
-This might seem overwhelming, but you don't necessarily need to add all of these in one pull request or on your own, you can simply contribute one section. Feel free to ask for help whenever you need. 
+This might seem overwhelming, but you don't necessarily need to add all of these in one pull request or on your own, you can simply contribute one section. Feel free to ask for help whenever you need. 
+
+## Other data
+
+This package contains the definition files (written in Typescript) for the huggingface.co hub's:
+
+- **pipeline types** a.k.a. **task types** (used to determine which widget to display on the model page, and which inference API to run)
+- **default widget inputs** (when they aren't provided in the model card)
+- definitions and UI elements for **third party libraries**.
+
+Please add to any of those definitions by opening a PR. Thanks 🔥
+
+⚠️ The hub's definitive doc is at https://huggingface.co/docs/hub.
+
+## Feedback (feature requests, bugs, etc.) is super welcome 💙💚💛💜♥️🧡

package/dist/index.d.ts

@@ -40,6 +40,7 @@ declare enum ModelLibrary {
     "mindspore" = "MindSpore"
 }
 type ModelLibraryKey = keyof typeof ModelLibrary;
+declare const ALL_DISPLAY_MODEL_LIBRARY_KEYS: string[];
 
 declare const MODALITIES: readonly ["cv", "nlp", "audio", "tabular", "multimodal", "rl", "other"];
 type Modality = (typeof MODALITIES)[number];
@@ -278,6 +279,11 @@ declare const PIPELINE_DATA: {
         modality: "cv";
         color: "indigo";
     };
+    "image-to-video": {
+        name: string;
+        modality: "multimodal";
+        color: "indigo";
+    };
     "unconditional-image-generation": {
         name: string;
         modality: "cv";
@@ -400,6 +406,16 @@ declare const PIPELINE_DATA: {
         modality: "multimodal";
         color: "green";
     };
+    "mask-generation": {
+        name: string;
+        modality: "cv";
+        color: "indigo";
+    };
+    "zero-shot-object-detection": {
+        name: string;
+        modality: "cv";
+        color: "yellow";
+    };
     other: {
         name: string;
         modality: "other";
@@ -409,8 +425,251 @@ declare const PIPELINE_DATA: {
     };
 };
 type PipelineType = keyof typeof PIPELINE_DATA;
-declare const PIPELINE_TYPES: ("other" | "text-classification" | "token-classification" | "table-question-answering" | "question-answering" | "zero-shot-classification" | "translation" | "summarization" | "conversational" | "feature-extraction" | "text-generation" | "text2text-generation" | "fill-mask" | "sentence-similarity" | "text-to-speech" | "text-to-audio" | "automatic-speech-recognition" | "audio-to-audio" | "audio-classification" | "voice-activity-detection" | "depth-estimation" | "image-classification" | "object-detection" | "image-segmentation" | "text-to-image" | "image-to-text" | "image-to-image" | "unconditional-image-generation" | "video-classification" | "reinforcement-learning" | "robotics" | "tabular-classification" | "tabular-regression" | "tabular-to-text" | "table-to-text" | "multiple-choice" | "text-retrieval" | "time-series-forecasting" | "text-to-video" | "visual-question-answering" | "document-question-answering" | "zero-shot-image-classification" | "graph-ml")[];
+declare const PIPELINE_TYPES: ("other" | "text-classification" | "token-classification" | "table-question-answering" | "question-answering" | "zero-shot-classification" | "translation" | "summarization" | "conversational" | "feature-extraction" | "text-generation" | "text2text-generation" | "fill-mask" | "sentence-similarity" | "text-to-speech" | "text-to-audio" | "automatic-speech-recognition" | "audio-to-audio" | "audio-classification" | "voice-activity-detection" | "depth-estimation" | "image-classification" | "object-detection" | "image-segmentation" | "text-to-image" | "image-to-text" | "image-to-image" | "image-to-video" | "unconditional-image-generation" | "video-classification" | "reinforcement-learning" | "robotics" | "tabular-classification" | "tabular-regression" | "tabular-to-text" | "table-to-text" | "multiple-choice" | "text-retrieval" | "time-series-forecasting" | "text-to-video" | "visual-question-answering" | "document-question-answering" | "zero-shot-image-classification" | "graph-ml" | "mask-generation" | "zero-shot-object-detection")[];
+declare const SUBTASK_TYPES: string[];
+declare const PIPELINE_TYPES_SET: Set<"other" | "text-classification" | "token-classification" | "table-question-answering" | "question-answering" | "zero-shot-classification" | "translation" | "summarization" | "conversational" | "feature-extraction" | "text-generation" | "text2text-generation" | "fill-mask" | "sentence-similarity" | "text-to-speech" | "text-to-audio" | "automatic-speech-recognition" | "audio-to-audio" | "audio-classification" | "voice-activity-detection" | "depth-estimation" | "image-classification" | "object-detection" | "image-segmentation" | "text-to-image" | "image-to-text" | "image-to-image" | "image-to-video" | "unconditional-image-generation" | "video-classification" | "reinforcement-learning" | "robotics" | "tabular-classification" | "tabular-regression" | "tabular-to-text" | "table-to-text" | "multiple-choice" | "text-retrieval" | "time-series-forecasting" | "text-to-video" | "visual-question-answering" | "document-question-answering" | "zero-shot-image-classification" | "graph-ml" | "mask-generation" | "zero-shot-object-detection">;
+
+/**
+ * Mapping from library name (excluding Transformers) to its supported tasks.
+ * Inference API should be disabled for all other (library, task) pairs beyond this mapping.
+ * As an exception, we assume Transformers supports all inference tasks.
+ * This mapping is generated automatically by "python-api-export-tasks" action in huggingface/api-inference-community repo upon merge.
+ * Ref: https://github.com/huggingface/api-inference-community/pull/158
+ */
+declare const LIBRARY_TASK_MAPPING_EXCLUDING_TRANSFORMERS: Partial<Record<ModelLibraryKey, PipelineType[]>>;
 
+type TableData = Record<string, (string | number)[]>;
+type WidgetExampleOutputLabels = Array<{
+    label: string;
+    score: number;
+}>;
+interface WidgetExampleOutputAnswerScore {
+    answer: string;
+    score: number;
+}
+interface WidgetExampleOutputText {
+    text: string;
+}
+interface WidgetExampleOutputUrl {
+    url: string;
+}
+type WidgetExampleOutput = WidgetExampleOutputLabels | WidgetExampleOutputAnswerScore | WidgetExampleOutputText | WidgetExampleOutputUrl;
+interface WidgetExampleBase<TOutput> {
+    example_title?: string;
+    group?: string;
+    /**
+     * Potential overrides to API parameters for this specific example
+     * (takes precedences over the model card metadata's inference.parameters)
+     */
+    parameters?: {
+        aggregation_strategy?: string;
+        top_k?: number;
+        top_p?: number;
+        temperature?: number;
+        max_new_tokens?: number;
+        do_sample?: boolean;
+        negative_prompt?: string;
+        guidance_scale?: number;
+        num_inference_steps?: number;
+    };
+    /**
+     * Optional output
+     */
+    output?: TOutput;
+}
+interface WidgetExampleTextInput<TOutput = WidgetExampleOutput> extends WidgetExampleBase<TOutput> {
+    text: string;
+}
+interface WidgetExampleTextAndContextInput<TOutput = WidgetExampleOutput> extends WidgetExampleTextInput<TOutput> {
+    context: string;
+}
+interface WidgetExampleTextAndTableInput<TOutput = WidgetExampleOutput> extends WidgetExampleTextInput<TOutput> {
+    table: TableData;
+}
+interface WidgetExampleAssetInput<TOutput = WidgetExampleOutput> extends WidgetExampleBase<TOutput> {
+    src: string;
+}
+interface WidgetExampleAssetAndPromptInput<TOutput = WidgetExampleOutput> extends WidgetExampleAssetInput<TOutput> {
+    prompt: string;
+}
+type WidgetExampleAssetAndTextInput<TOutput = WidgetExampleOutput> = WidgetExampleAssetInput<TOutput> & WidgetExampleTextInput<TOutput>;
+type WidgetExampleAssetAndZeroShotInput<TOutput = WidgetExampleOutput> = WidgetExampleAssetInput<TOutput> & WidgetExampleZeroShotTextInput<TOutput>;
+interface WidgetExampleStructuredDataInput<TOutput = WidgetExampleOutput> extends WidgetExampleBase<TOutput> {
+    structured_data: TableData;
+}
+interface WidgetExampleTableDataInput<TOutput = WidgetExampleOutput> extends WidgetExampleBase<TOutput> {
+    table: TableData;
+}
+interface WidgetExampleZeroShotTextInput<TOutput = WidgetExampleOutput> extends WidgetExampleTextInput<TOutput> {
+    text: string;
+    candidate_labels: string;
+    multi_class: boolean;
+}
+interface WidgetExampleSentenceSimilarityInput<TOutput = WidgetExampleOutput> extends WidgetExampleBase<TOutput> {
+    source_sentence: string;
+    sentences: string[];
+}
+type WidgetExample<TOutput = WidgetExampleOutput> = WidgetExampleTextInput<TOutput> | WidgetExampleTextAndContextInput<TOutput> | WidgetExampleTextAndTableInput<TOutput> | WidgetExampleAssetInput<TOutput> | WidgetExampleAssetAndPromptInput<TOutput> | WidgetExampleAssetAndTextInput<TOutput> | WidgetExampleAssetAndZeroShotInput<TOutput> | WidgetExampleStructuredDataInput<TOutput> | WidgetExampleTableDataInput<TOutput> | WidgetExampleZeroShotTextInput<TOutput> | WidgetExampleSentenceSimilarityInput<TOutput>;
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+type WidgetExampleAttribute = KeysOfUnion<WidgetExample>;
+declare enum InferenceDisplayability {
+    /**
+     * Yes
+     */
+    Yes = "Yes",
+    /**
+     * And then, all the possible reasons why it's no:
+     */
+    ExplicitOptOut = "ExplicitOptOut",
+    CustomCode = "CustomCode",
+    LibraryNotDetected = "LibraryNotDetected",
+    PipelineNotDetected = "PipelineNotDetected",
+    PipelineLibraryPairNotSupported = "PipelineLibraryPairNotSupported"
+}
+/**
+ * Public interface for model metadata
+ */
+interface ModelData {
+    /**
+     * id of model (e.g. 'user/repo_name')
+     */
+    id: string;
+    /**
+     * Kept for backward compatibility
+     */
+    modelId?: string;
+    /**
+     * Whether or not to enable inference widget for this model
+     */
+    inference: InferenceDisplayability;
+    /**
+     * is this model private?
+     */
+    private?: boolean;
+    /**
+     * this dictionary has useful information about the model configuration
+     */
+    config?: Record<string, unknown> & {
+        adapter_transformers?: {
+            model_class?: string;
+            model_name?: string;
+        };
+        architectures?: string[];
+        sklearn?: {
+            filename?: string;
+            model_format?: string;
+        };
+        speechbrain?: {
+            interface?: string;
+        };
+        peft?: {
+            base_model_name?: string;
+            task_type?: string;
+        };
+    };
+    /**
+     * all the model tags
+     */
+    tags?: string[];
+    /**
+     * transformers-specific info to display in the code sample.
+     */
+    transformersInfo?: TransformersInfo;
+    /**
+     * Pipeline type
+     */
+    pipeline_tag?: PipelineType | undefined;
+    /**
+     * for relevant models, get mask token
+     */
+    mask_token?: string | undefined;
+    /**
+     * Example data that will be fed into the widget.
+     *
+     * can be set in the model card metadata (under `widget`),
+     * or by default in `DefaultWidget.ts`
+     */
+    widgetData?: WidgetExample[] | undefined;
+    /**
+     * Parameters that will be used by the widget when calling Inference API
+     * https://huggingface.co/docs/api-inference/detailed_parameters
+     *
+     * can be set in the model card metadata (under `inference/parameters`)
+     * Example:
+     * inference:
+     *     parameters:
+     *         key: val
+     */
+    cardData?: {
+        inference?: boolean | {
+            parameters?: Record<string, unknown>;
+        };
+        base_model?: string;
+    };
+    /**
+     * Library name
+     * Example: transformers, SpeechBrain, Stanza, etc.
+     */
+    library_name?: string;
+}
+/**
+ * transformers-specific info to display in the code sample.
+ */
+interface TransformersInfo {
+    /**
+     * e.g. AutoModelForSequenceClassification
+     */
+    auto_model: string;
+    /**
+     * if set in config.json's auto_map
+     */
+    custom_class?: string;
+    /**
+     * e.g. text-classification
+     */
+    pipeline_tag?: PipelineType;
+    /**
+     * e.g. "AutoTokenizer" | "AutoFeatureExtractor" | "AutoProcessor"
+     */
+    processor?: string;
+}
+
+/**
+ * Elements configurable by a model library.
+ */
+interface LibraryUiElement {
+    /**
+     * Name displayed on the main
+     * call-to-action button on the model page.
+     */
+    btnLabel: string;
+    /**
+     * Repo name
+     */
+    repoName: string;
+    /**
+     * URL to library's repo
+     */
+    repoUrl: string;
+    /**
+     * URL to library's docs
+     */
+    docsUrl?: string;
+    /**
+     * Code snippet displayed on model page
+     */
+    snippets: (model: ModelData) => string[];
+}
+declare const MODEL_LIBRARIES_UI_ELEMENTS: Partial<Record<ModelLibraryKey, LibraryUiElement>>;
+
+type PerLanguageMapping = Map<PipelineType, string[] | WidgetExample[]>;
+declare const MAPPING_DEFAULT_WIDGET: Map<string, PerLanguageMapping>;
+
+/**
+ * Model libraries compatible with each ML task
+ */
+declare const TASKS_MODEL_LIBRARIES: Record<PipelineType, ModelLibraryKey[]>;
+declare const TASKS_DATA: Record<PipelineType, TaskData | undefined>;
 interface ExampleRepo {
     description: string;
     id: string;
@@ -461,7 +720,109 @@ interface TaskData {
     widgetModels: string[];
     youtubeId?: string;
 }
+type TaskDataCustom = Omit<TaskData, "id" | "label" | "libraries">;
 
-declare const TASKS_DATA: Record<PipelineType, TaskData | undefined>;
+declare const TAG_NFAA_CONTENT = "not-for-all-audiences";
+declare const OTHER_TAGS_SUGGESTIONS: string[];
+declare const TAG_TEXT_GENERATION_INFERENCE = "text-generation-inference";
+declare const TAG_CUSTOM_CODE = "custom_code";
+
+declare function getModelInputSnippet(model: ModelData, noWrap?: boolean, noQuotes?: boolean): string;
+
+declare const inputs_getModelInputSnippet: typeof getModelInputSnippet;
+declare namespace inputs {
+  export {
+    inputs_getModelInputSnippet as getModelInputSnippet,
+  };
+}
+
+declare const snippetBasic$2: (model: ModelData, accessToken: string) => string;
+declare const snippetZeroShotClassification$2: (model: ModelData, accessToken: string) => string;
+declare const snippetFile$2: (model: ModelData, accessToken: string) => string;
+declare const curlSnippets: Partial<Record<PipelineType, (model: ModelData, accessToken: string) => string>>;
+declare function getCurlInferenceSnippet(model: ModelData, accessToken: string): string;
+declare function hasCurlInferenceSnippet(model: ModelData): boolean;
+
+declare const curl_curlSnippets: typeof curlSnippets;
+declare const curl_getCurlInferenceSnippet: typeof getCurlInferenceSnippet;
+declare const curl_hasCurlInferenceSnippet: typeof hasCurlInferenceSnippet;
+declare namespace curl {
+  export {
+    curl_curlSnippets as curlSnippets,
+    curl_getCurlInferenceSnippet as getCurlInferenceSnippet,
+    curl_hasCurlInferenceSnippet as hasCurlInferenceSnippet,
+    snippetBasic$2 as snippetBasic,
+    snippetFile$2 as snippetFile,
+    snippetZeroShotClassification$2 as snippetZeroShotClassification,
+  };
+}
+
+declare const snippetZeroShotClassification$1: (model: ModelData) => string;
+declare const snippetBasic$1: (model: ModelData) => string;
+declare const snippetFile$1: (model: ModelData) => string;
+declare const snippetTextToImage$1: (model: ModelData) => string;
+declare const snippetTextToAudio$1: (model: ModelData) => string;
+declare const pythonSnippets: Partial<Record<PipelineType, (model: ModelData) => string>>;
+declare function getPythonInferenceSnippet(model: ModelData, accessToken: string): string;
+declare function hasPythonInferenceSnippet(model: ModelData): boolean;
+
+declare const python_getPythonInferenceSnippet: typeof getPythonInferenceSnippet;
+declare const python_hasPythonInferenceSnippet: typeof hasPythonInferenceSnippet;
+declare const python_pythonSnippets: typeof pythonSnippets;
+declare namespace python {
+  export {
+    python_getPythonInferenceSnippet as getPythonInferenceSnippet,
+    python_hasPythonInferenceSnippet as hasPythonInferenceSnippet,
+    python_pythonSnippets as pythonSnippets,
+    snippetBasic$1 as snippetBasic,
+    snippetFile$1 as snippetFile,
+    snippetTextToAudio$1 as snippetTextToAudio,
+    snippetTextToImage$1 as snippetTextToImage,
+    snippetZeroShotClassification$1 as snippetZeroShotClassification,
+  };
+}
+
+declare const snippetBasic: (model: ModelData, accessToken: string) => string;
+declare const snippetZeroShotClassification: (model: ModelData, accessToken: string) => string;
+declare const snippetTextToImage: (model: ModelData, accessToken: string) => string;
+declare const snippetTextToAudio: (model: ModelData, accessToken: string) => string;
+declare const snippetFile: (model: ModelData, accessToken: string) => string;
+declare const jsSnippets: Partial<Record<PipelineType, (model: ModelData, accessToken: string) => string>>;
+declare function getJsInferenceSnippet(model: ModelData, accessToken: string): string;
+declare function hasJsInferenceSnippet(model: ModelData): boolean;
+
+declare const js_getJsInferenceSnippet: typeof getJsInferenceSnippet;
+declare const js_hasJsInferenceSnippet: typeof hasJsInferenceSnippet;
+declare const js_jsSnippets: typeof jsSnippets;
+declare const js_snippetBasic: typeof snippetBasic;
+declare const js_snippetFile: typeof snippetFile;
+declare const js_snippetTextToAudio: typeof snippetTextToAudio;
+declare const js_snippetTextToImage: typeof snippetTextToImage;
+declare const js_snippetZeroShotClassification: typeof snippetZeroShotClassification;
+declare namespace js {
+  export {
+    js_getJsInferenceSnippet as getJsInferenceSnippet,
+    js_hasJsInferenceSnippet as hasJsInferenceSnippet,
+    js_jsSnippets as jsSnippets,
+    js_snippetBasic as snippetBasic,
+    js_snippetFile as snippetFile,
+    js_snippetTextToAudio as snippetTextToAudio,
+    js_snippetTextToImage as snippetTextToImage,
+    js_snippetZeroShotClassification as snippetZeroShotClassification,
+  };
+}
+
+declare const index_curl: typeof curl;
+declare const index_inputs: typeof inputs;
+declare const index_js: typeof js;
+declare const index_python: typeof python;
+declare namespace index {
+  export {
+    index_curl as curl,
+    index_inputs as inputs,
+    index_js as js,
+    index_python as python,
+  };
+}
 
-export { ExampleRepo, MODALITIES, MODALITY_LABELS, Modality, ModelLibrary, ModelLibraryKey, PIPELINE_DATA, PIPELINE_TYPES, PipelineData, PipelineType, TASKS_DATA, TaskData, TaskDemo, TaskDemoEntry };
+export { ALL_DISPLAY_MODEL_LIBRARY_KEYS, ExampleRepo, InferenceDisplayability, LIBRARY_TASK_MAPPING_EXCLUDING_TRANSFORMERS, LibraryUiElement, MAPPING_DEFAULT_WIDGET, MODALITIES, MODALITY_LABELS, MODEL_LIBRARIES_UI_ELEMENTS, Modality, ModelData, ModelLibrary, ModelLibraryKey, OTHER_TAGS_SUGGESTIONS, PIPELINE_DATA, PIPELINE_TYPES, PIPELINE_TYPES_SET, PipelineData, PipelineType, SUBTASK_TYPES, TAG_CUSTOM_CODE, TAG_NFAA_CONTENT, TAG_TEXT_GENERATION_INFERENCE, TASKS_DATA, TASKS_MODEL_LIBRARIES, TaskData, TaskDataCustom, TaskDemo, TaskDemoEntry, TransformersInfo, WidgetExample, WidgetExampleAssetAndPromptInput, WidgetExampleAssetAndTextInput, WidgetExampleAssetAndZeroShotInput, WidgetExampleAssetInput, WidgetExampleAttribute, WidgetExampleOutput, WidgetExampleOutputAnswerScore, WidgetExampleOutputLabels, WidgetExampleOutputText, WidgetExampleOutputUrl, WidgetExampleSentenceSimilarityInput, WidgetExampleStructuredDataInput, WidgetExampleTableDataInput, WidgetExampleTextAndContextInput, WidgetExampleTextAndTableInput, WidgetExampleTextInput, WidgetExampleZeroShotTextInput, index as snippets };