{"id":43657164,"url":"https://github.com/microsoft/windows-ai-electron","last_synced_at":"2026-02-10T21:16:26.217Z","repository":{"id":330490344,"uuid":"1068006829","full_name":"microsoft/windows-ai-electron","owner":"microsoft","description":"An Electron addon which provides JS projections of Windows AI Foundry APIs","archived":false,"fork":false,"pushed_at":"2026-02-06T20:16:20.000Z","size":269,"stargazers_count":9,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-07T05:10:48.894Z","etag":null,"topics":["ai","electron","javascript","native","native-addon","phi-silica","typescript","winappsdk","windows","windows-ai","windows-app-sdk","windows-app-sdk-app"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T17:59:59.000Z","updated_at":"2026-02-06T20:11:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/microsoft/windows-ai-electron","commit_stats":null,"previous_names":["microsoft/winapp-windows-ai","microsoft/windows-ai-electron"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/microsoft/windows-ai-electron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwindows-ai-electron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwindows-ai-electron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwindows-ai-electron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwindows-ai-electron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/windows-ai-electron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwindows-ai-electron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29317057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T20:44:44.282Z","status":"ssl_error","status_checked_at":"2026-02-10T20:44:43.393Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","electron","javascript","native","native-addon","phi-silica","typescript","winappsdk","windows","windows-ai","windows-app-sdk","windows-app-sdk-app"],"created_at":"2026-02-04T21:02:16.538Z","updated_at":"2026-02-10T21:16:26.187Z","avatar_url":"https://github.com/microsoft.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cspan\u003eWindows AI Addon for Electron\u003c/span\u003e\n\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003e\n  \u003cspan\u003eLeverage Windows AI capabilities directly from your app's JavaScript\u003c/span\u003e\n\u003c/h3\u003e\n\n\u003e [!IMPORTANT]\n\u003e :warning: **Status: Public Preview** - The Windows AI Addon is experimental and in active development. We'd love your feedback! Share your thoughts by creating an [issue](https://github.com/microsoft/windows-ai-electron/issues).\n\nThe Windows AI Addon for Electron is a Node.js native addon that provides access to the [Windows AI APIs](https://learn.microsoft.com/en-us/windows/ai/apis/), enabling Electron applications to leverage Windows AI capabilities directly from JavaScript.\n\n## Prerequisites\n\n- **Copilot+PC**\n- **Windows 11** (using Windows Insider Preview build 26120.3073 (Dev and Beta Channels) or later)\n- **Node.js** 18.x or later\n- **Visual Studio 2022** with C++ build tools\n- **Python** 3.x\n- **Limited Access Feature Token for Phi Silica** - Request a token using the [LAF Access Token Request Form](https://forms.office.com/pages/responsepage.aspx?id=v4j5cvGGr0GRqy180BHbR25txIwisw1PlceTVpYHUm9UODlVMkszVTFaRlVLVlBPNkNaV0hKMzM5Mi4u\u0026route=shorturl). Only needed if you wish to use the `GenerateResponseAsync` API.\n\nSee [Windows AI API's Dependencies](https://learn.microsoft.com/windows/ai/apis/get-started?tabs=winget%2Cwinui%2Cwinui2#dependencies) for more information on system requirements to run Windows AI API's and scripts to install required prerequisites.\n\n\u003e [!IMPORTANT]\n\u003e Verify your device is able to access Windows AI models by downloading the [AI Dev Gallery app](https://apps.microsoft.com/detail/9n9pn1mm3bd5?hl=en-US\u0026gl=US). Navigate to the \"AI APIs\" samples and ensure they can run on your device. If the samples are blocked, the AI models may be missing from your machine. You can manually request a download by selecting the \"Request Model\" button and following the directions within Windows Update settings.\n\n## Dependencies\n\nThis package depends on the [@microsoft/winappcli](https://github.com/microsoft/WinAppCli) package. Any electron app which uses this package must also take a dependency on `@microsoft/winappcli` and follow its installation and setup steps.\n\n## Get Started Using @microsoft/windows-ai-electron in an Electron App\n\nLet's walk through a simple tutorial of how to get started using `@microsoft/windows-ai-electron`. In this tutorial, we will create a simple Electron app that summarizes a block of text using Windows AI's Text Summarizer.\n\n### 1. Create an Electron App\n\nCreate an electron app by following the getting started directions at [Electron: Building you First App](https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app).\n\nThe instructions below follow the steps for adding `@microsoft/windows-ai-electron` to a standard Electron app. This module can also be added to Electron apps built using [Electron Forge](https://www.electronforge.io/) and other templates.\n\n### 2. Add @microsoft/windows-ai-electron as a Dependency\n\n```bash\ncd \u003cyour-electron-app\u003e\nnpm i @microsoft/windows-ai-electron\n```\n\n### 3. Add @microsoft/winappcli as a dev Dependency\n\n```bash\nnpm i @microsoft/winappcli -D\n```\n\n### 4. Install and Setup Dependencies\n\nInitialize your project for calling Windows APIs. This will create an appxmanifest.xml, required assets, and make the Windows App SDK available for usage:\n\n```bash\nnpx winapp init\n```\n\n\u003e [!IMPORTANT]\n\u003e When you run `npx winapp init`, it generates a `winapp.yaml` file for managing SDK versions. Make sure the version of the Microsoft.WindowsAppSDK package is `1.8.xxxxx`. If it's not, simply set the version to `1.8.251106002` and run `npx winapp restore` to ensure the proper dependencies are available for the project.\n\n### 5. Add `systemAIModels` Capability\n\nAdd `systemAIModels` Capability in `appxmanifest.xml` for app to gain access to local models:\n\n```xml\n\u003cCapabilities\u003e\n    \u003crescap:Capability Name=\"systemAIModels\" /\u003e\n\u003c/Capabilities\u003e\n```\n### 6. Add Debug Identity\n \nBefore your app can call the AI APIs, we need to make sure the electron process has identity as defined in you appxmanifest.xml. Add app identity to the Electron process for debugging:\n\n```bash\nnpx winapp node add-electron-debug-identity\n```\n\n\u003e [!IMPORTANT]\n\u003e There is a known issue with sparse packaging Electron applications which causes the app to crash on start or not render the web content. The issue has been fixed in Windows but has not yet fully propagated to all Windows devices. If you are seeing this issue after calling `add-electron-debug-identity`, you can [disable sandboxing in your Electron app](https://www.electronjs.org/docs/latest/tutorial/sandbox#disabling-chromiums-sandbox-testing-only) for debug purposes with the `--no-sandbox` flag. This issue does not affect full MSIX packaging.\n\n### 7. Use @microsoft/windows-ai-electron\n\nIn `main.js` or `index.js`:\n\n```javascript\nconst {\n  LanguageModel,\n  AIFeatureReadyResultState,\n  TextSummarizer,\n  LanguageModelResponseStatus,\n} = require(\"@microsoft/windows-ai-electron\");\n\nconst summarizeText = async () =\u003e {\n  try {\n    const readyResult = await LanguageModel.EnsureReadyAsync();\n    if (readyResult.Status !== AIFeatureReadyResultState.Success) {\n      console.log(\"AI not ready:\", readyResult.ErrorDisplayText);\n    }\n\n    const model = await LanguageModel.CreateAsync();\n    const textSummarizer = new TextSummarizer(model);\n\n    const longText = `\n      Artificial intelligence (AI) is intelligence demonstrated by machines, \n      in contrast to the natural intelligence displayed by humans and animals. \n      Leading AI textbooks define the field as the study of \"intelligent agents\": \n      any device that perceives its environment and takes actions that maximize \n      its chance of successfully achieving its goals.\n    `;\n\n    const summarizationPromise = textSummarizer.SummarizeAsync(longText);\n\n    if (summarizationPromise.progress) {\n      summarizationPromise.progress((error, progressText) =\u003e {\n        console.log(progressText);\n      });\n    }\n\n    const result = await summarizationPromise;\n\n    if (result.Status === LanguageModelResponseStatus.Complete) {\n      console.log(result.Text);\n    } else {\n      console.log(\"Summarization failed with status:\", result.Status);\n    }\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\nCall `summarizeText` somewhere in your `main.js` or `index.js`.\n\nHere's an example:\n```diff\nconst createWindow = () =\u003e {\n  const win = new BrowserWindow({\n    width: 800,\n    height: 600,\n    autoHideMenuBar: true,\n    webPreferences: {\n      preload: __dirname + '/preload.js',\n      sandbox: false,\n    }\n  })\n\n  win.loadFile('index.html')\n\n  win.webContents.openDevTools();\n\n+  summarizeText();\n}\n```\n\n### 8. Run Your App\n\n```bash\nnpx electron .\n```\n\nYou should see the local model streaming the response to the console.\n\n## Supported APIs\n\nThis package supports many of the API's within\n\n- [Microsoft.Windows.AI.Text](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.ai.text?view=windows-app-sdk-1.8)\n- [Microsoft.Windows.AI.Imaging](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.ai.imaging?view=windows-app-sdk-1.8)\n- [Microsoft.Windows.AI](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.windows.ai?view=windows-app-sdk-1.8)\n\nFor the full list of supported API's, see [Supported API's](docs/API-Reference.md).\n\nIf you have a request for additional API support, please file an [issue](https://github.com/microsoft/windows-ai-electron/issues/new).\n\n## Usage Examples\n\nFor more examples on how to use `@microsoft/windows-ai-electron` within your Electron application, see the [Usage Guide](docs/Usage.md).\n\n## Development\n\n### Project Structure\n\n```\nwindows-ai-electron/\n├── windows-ai-electron/\n│   ├── windows-ai-electron.cc         # Main addon entry point\n│   ├── LanguageModelProjections.h   # Language model \u0026 text skills APIs\n│   ├── LanguageModelProjections.cpp\n│   ├── ImagingProjections.h         # Imaging APIs\n│   ├── ImagingProjections.cpp\n│   ├── ContentSeverity.h            # Content safety APIs\n│   ├── ContentSeverity.cpp\n│   ├── LimitedAccessFeature.h       # Limited Access Feature token APIs\n│   ├── LimitedAccessFeature.cpp\n│   ├── ProjectionHelper.h           # Utility functions\n│   ├── ProjectionHelper.cpp\n│   └── binding.gyp                  # Build configuration\n├── test-app/                        # Sample Electron application\n│   ├── main.js                      # Electron main process\n│   ├── preload.js                   # Preload script for @microsoft/windows-ai-electron integration\n│   ├── index.html                   # Sample UI for testing APIs\n│   └── package.json                 # Sample app package configuration and dependencies\n├── docs/                            # Documentation files\n├── scripts/                         # Build scripts\n│   ├── build-pkg.ps1                # PowerShell script for package building\n│   └── get-build-number.ps1         # Script to retrieve build numbers\n├── index.d.ts                       # TypeScript type definitions\n├── index.js                         # Main module entry point and exports\n└── package.json                     # Package configuration and dependencies\n```\n\n### Building the Package Locally\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/microsoft/windows-ai-electron.git\n```\n\n#### 2. Install Dependencies\n\n```bash\ncd \u003cpath to @microsoft/windows-ai-electron repo\u003e\nnpm install\nnpx winapp restore\n```\n\n#### 3. Build the Native Addon\n\n```bash\nnpm run build-all\n```\n\n### Building `test-app` Locally\n\n#### 1. Build Package Locally\n\nComplete [Building the Package Locally](#1-build-package-locally) steps above.\n\n#### 2. Setup Dependencies\n\nInstall dependencies:\n```bash\nnpm install\n```\n\nInitialize Windows App Development CLI (select N to preserve dependency versions):\n```bash\nnpx winapp init\nnpm run setup-debug\n```\n\n#### 3. Run the App\n\n```bash\nnpm run start\n```\n\nIf you make changes to the `@microsoft/windows-ai-electron` package and want to see your changes loaded into the sample app, make sure to re-build the addon before re-running `test-app`.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](/LICENSE) for details.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"AI not ready\" or EnsureReadyAsync/GetReadyState return status AIFeatureReadyResultState::Failure(2)**: Ensure Windows 11 25H2+ (Windows Insider Preview) and Copilot+ PC requirements are met. Validate your device has Windows AI models installed and available by downloading the [AI Dev Gallery app](https://apps.microsoft.com/detail/9n9pn1mm3bd5?hl=en-US\u0026gl=US). Then navigate to the \"AI APIs\" samples and ensure they can run on your device. (see [Prerequisites](#prerequisites))\n2. **EnsureReadyAsync cancelled or failed**: Ensure `appxmanifest` has the `systemAIModels` capability added (see [Add Debug Identity + Capabilities to App](#5-add-debug-identity--capabilities-to-app))\n3. **\"Class Not Registered\"**: Make sure you have correctly setup the `@microsoft/winappcli` package (see [Add @microsoft/winappcli as a Dependency](#3-add-microsoftwinappcli-as-a-dependency)).\n   - If the issue is still persisting:\n      1. Delete `node_modules`, `yarn.lock`, and `.winapp`\n      2. Run `npm cache clean --force`\n      3. Run `npm install`\n      4. Run `npx winapp restore`\n      5. Run `npx winapp node add-electron-debug-identity`\n\n4. **App renders blank**: You may need to disable sandboxing when running your Electron app on Windows. Then re-run `npx winapp node add-electron-debug-identity` (see [Add Debug Identity + Capabilities to App](#5-add-debug-identity--capabilities-to-app))\n5. **\"Can't find module: @microsoft/windows-ai-electron\"**: Verify you have added the `@microsoft/windows-ai-electron` package as a dependency to your application.\n7. **Image file not found**: You must use absolute file paths with proper Windows path separators.\n8. **Content moderation blocks**: Adjust `ContentFilterOptions` severity levels as appropriate.\n9. **Memory issues**: Always call `Close()` or `Dispose()` methods to clean up resources.\n10. **GenerateResponseAsync calls are failing**: `GenerateResponseAsync` uses a native API that is currently a [Limited Access Feature](https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.limitedaccessfeatures?view=winrt-26100). To request an unlock token, please use the [LAF Access Token Request Form](https://go.microsoft.com/fwlink/?linkid=2271232\u0026c1cid=04x409). To use this method, you must first call `LimitedAccessFeature.TryUnlockToken`. See [Usage Guide](/docs/Usage.md/#text-generation) for usage examples.\n11. See [Windows AI API's Troubleshooting](https://learn.microsoft.com/windows/ai/apis/troubleshooting) for more information on troubleshooting the native Windows AI API's.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fwindows-ai-electron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fwindows-ai-electron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fwindows-ai-electron/lists"}