microsoft / microsoft/winappCli
[Feature]: `winapp find-api` — semantic search for Windows APIs
- Dominant language
- C#
- Stars
- 1.3k
- Forks
- 80
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 51
Description
> **Depends on #652** — the lexical/fuzzy port of the `winmd` tool into `winapp` (full v1). This issue adds the **semantic layer** on top of that ported foundation.
## Is your feature request related to a problem? Please describe.
To call a Windows API, a developer (or agent) has to already know the namespace/type/method and then find a usage example. Discovery today means grepping metadata, browsing docs, or guessing — and agents in particular waste turns hallucinating API shapes instead of grounding on the real surface. There's no way to ask, in natural language, "which API does X, and how do I call it?" from the CLI.
## Current state
- API discovery lives in the separate **`winmd`** tool (in the **microsoft/win-dev-skills** repo). It's a native-AOT, fully-local/offline tool that scans a project's referenced `.winmd`/`.dll` metadata (NuGet + Windows SDK + WinAppSDK), parses it **plus XML docs** (48K+ IntelliSense-grade API descriptions), and caches structured JSON to `%LOCALAPPDATA%\winmd-cache` — refreshing when the project's packages change.
- Its query commands (`search`, `members`, `check-property`, `types`, `enums`) read that local cache, but `search` is **fuzzy/lexical** — natural-language intent ("read a file the user picked") doesn't resolve.
- The repo's own `WinmdService` is unrelated: it only finds activatable classes / WinRT components for packaging, not the full API surface — so the search-oriented winmd work needs to be brought over.
## Describe the solution you'd like
Add a **`winapp find-api ""`** command: natural-language, **semantic** search over Windows/WinRT APIs that returns the relevant API plus how to call it. Same shape as `winapp find-ui` (#625), over a different primary corpus (Windows/WinRT API metadata rather than UI controls).
- **Natural-language query** — "read a file the user picked", "show a toast", not just exact type names.
- **Semantic matching** — ranks by intent, computed locally; the existing fuzzy/lexical search stays as the fast exact-name path.
- **Framework-agnostic** — covers any framework that references WinRT metadata (WASDK/WinUI, Windows SDK/UWP, C++/WinRT, C#/WinRT, Rust/WinRT).
- **Agent-friendly output** — `--json` with a structured result (API, signature, snippet, source, link) so an agent grounds on the real surface in one shot.
Replaces the `winmd` tool (from **microsoft/win-dev-skills**), upgrading it from fuzzy to semantic.
## Proposed architecture
`find-api` searches **three sources**, split by **locality**, unified in **one shared vector space** (shared with `find-ui`):
- **Local — your project's API surface** (referenced winmds, including private/preview): reuse the ported winmd scan/cache, embed those records **on-device** with the bundled model. Never uploaded; the only place this data can be indexed.
- **Global — docs + samples** (same for every user): gathered and embedded **centrally at release**, delivered as a **download-only, fetch-and-cached** vector index (small bundled baseline for offline). No user data is uploaded.
- **Query — on-device**: embedded locally and compared against both; the existing fuzzy/lexical winmd search stays as the fast exact-name path.
```
winapp find-api ""
├─ (local) ported winmd scan/cache → embed your referenced APIs on-device [lazy, incremental]
├─ (global) ensure docs+samples index (bundled baseline + fetch/refresh online)
├─ embed the query locally with the bundled model
├─ search all sources in one vector space; merge/rank hits
│ (semantic hits can also generate candidate API/type names → feed the local lexical winmd search)
└─ return ranked results (API, signature, snippet, source, link) [+ --json]
```
- **Reuse, don't rebuild:** port the winmd tool's parser/cache/query engine; the new work is the on-device semantic layer + the global index integration.
- **Payload minimized:** the only heavy bundled artifact is the shared embedding model. Local API vectors are computed on-device (winmd already caches to `%LOCALAPPDATA%`); the global docs/samples index is fetched-and-cached, not shipped whole.
- **Lazy/incremental local indexing:** embed on first probe; refresh when the project's packages change (reuse the `project.assets.json` staleness check); explicit refresh for CI/force.
- **Cross-source, one call:** semantically search docs + samples, ground against your local API surface, and use semantic hits to generate concrete API names for the local lexical search — one call, all sources (fewer agent turns, fewer tokens).
- **Download-only cloud:** the service serves *public* prebuilt vectors to the client; it never receives the query or your project's metadata.
- **Shared model / one vector space** with `find-ui`, toward a future unified index across UI, docs, and APIs.
- **The main thing to approve:** `find-api` = on-device local winmd index + fetch-and-cached global docs/samples index + local query embedding, on the shared model.
## Stretch goal
Grow the corpus to include **popular/common API records beyond your project**, so a broad question ("what's the best API for X?") can **recommend packages/APIs you haven't referenced yet** — discovery on top of v1's grounding.
## Open questions
- [ ] Cost of embedding the local cache at scan time — embed only the referenced surface (subset) vs. the full 48K; incremental vs. full.
- [ ] Global docs/samples index: how it's gathered/embedded centrally (sources, chunking, release pipeline) and how much ships offline vs. fetch-and-cache.
- [ ] Payload budget for the bundled model (~30–40 MB quantized), shared with `find-ui`.
- [ ] Result schema shape? needs to be aligned with `find-ui`.
- [ ] Command placement
## Additional context
Part of the single-`winapp`-CLI direction (new top-level command). Migrates the **`winmd`** tool from **microsoft/win-dev-skills** into `winapp`. Sibling of `winapp find-ui` (semantic control/sample search) — the two share an embedding model/vector space toward a future unified semantic index across UI, docs, and APIs. Future function `winapp ask ` once each has been established?
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.