microsoft / microsoft/winappCli

[Feature]: `winapp find-api` — semantic search for Windows APIs

Open
#626 0 comments 0 reactions 1 assignee Claimed by @Jaylyn-Barbee View on GitHub
cli enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.