docs: add copilot-instructions.md for AI coding assistants#550
docs: add copilot-instructions.md for AI coding assistants#550MaanavD wants to merge 1 commit intomicrosoft:mainfrom
Conversation
|
@MaanavD is attempting to deploy a commit to the MSFT-AIP Team on Vercel. A member of the Team first needs to authorize it. |
There was a problem hiding this comment.
Pull request overview
Adds a .github/copilot-instructions.md reference document intended to give AI coding assistants accurate context and usage patterns for Foundry Local’s SDKs (chat + audio transcription), to reduce incorrect/omitted generated code.
Changes:
- Introduces a GitHub Copilot instructions file with JS and C# “quick reference” snippets for chat + transcription.
- Adds “Key Rules” guidance (dynamic ports, aliases, single manager) and a model alias table.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
.github/copilot-instructions.md
Outdated
| Foundry Local is an on-device AI inference runtime. It provides: | ||
|
|
||
| - **Chat completions** (text generation) via native SDK or OpenAI-compatible REST API | ||
| - **Audio transcription** (speech-to-text via Whisper) via native SDK or REST API |
There was a problem hiding this comment.
Line 6 claims audio transcription is available via the OpenAI-compatible REST API, but the C# SDK docs for the built-in web service only document /v1/chat_completions and /v1/models (no audio endpoints). Please either remove the REST claim for audio, or update it to the exact supported endpoint(s) if audio-over-HTTP is actually implemented.
| - **Audio transcription** (speech-to-text via Whisper) via native SDK or REST API | |
| - **Audio transcription** (speech-to-text via Whisper) via native SDK only |
|
|
||
| var config = new Configuration { AppName = "foundry_local_samples" }; | ||
| await FoundryLocalManager.CreateAsync(config); |
There was a problem hiding this comment.
The C# quick reference won't compile as written: FoundryLocalManager.CreateAsync requires an ILogger parameter (and optional cancellation token). Update the snippet to pass a logger (e.g., NullLogger.Instance or a real ILogger), matching the SDK's actual signature.
| var config = new Configuration { AppName = "foundry_local_samples" }; | |
| await FoundryLocalManager.CreateAsync(config); | |
| using Microsoft.Extensions.Logging; | |
| using Microsoft.Extensions.Logging.Abstractions; | |
| var config = new Configuration { AppName = "foundry_local_samples" }; | |
| await FoundryLocalManager.CreateAsync(config, NullLogger.Instance); |
.github/copilot-instructions.md
Outdated
| var chatModel = await catalog.GetModelAsync("qwen2.5-0.5b"); | ||
| await chatModel.DownloadAsync(); | ||
| await chatModel.LoadAsync(); | ||
| var chatClient = await chatModel.GetChatClientAsync(); | ||
|
|
||
| // Audio transcription | ||
| var whisperModel = await catalog.GetModelAsync("whisper-tiny"); | ||
| await whisperModel.DownloadAsync(); | ||
| await whisperModel.LoadAsync(); | ||
| var audioClient = await whisperModel.GetAudioClientAsync(); | ||
| ``` |
There was a problem hiding this comment.
GetCatalogAsync().GetModelAsync(...) returns a nullable Model? in the C# SDK. The snippet uses chatModel/whisperModel without a null check, which will lead to nullable warnings and can hide the 'model not found' case. Prefer ?? throw (or an explicit null check) in the sample to make the expected failure mode clear.
.github/copilot-instructions.md
Outdated
|
|
||
| ## Key Rules | ||
|
|
||
| - **Never hardcode ports.** The service port is dynamic. Use `manager.endpoint` (JS/Python) or `config.Web.Urls` (C#). |
There was a problem hiding this comment.
The dynamic-port guidance is inaccurate for both SDKs. JS FoundryLocalManager exposes urls (populated after startWebService()), not endpoint; and in C# Configuration.Web.Urls is the bind setting, while the actual chosen port is exposed via FoundryLocalManager.Instance.Urls after StartWebServiceAsync(). Please update this rule to reference the actual runtime URLs properties.
| - **Never hardcode ports.** The service port is dynamic. Use `manager.endpoint` (JS/Python) or `config.Web.Urls` (C#). | |
| - **Never hardcode ports.** The service port is dynamic. In JS, read `manager.urls` after `await manager.startWebService()`. In C#, `Configuration.Web.Urls` controls the bind addresses, while the actual runtime URLs are exposed via `FoundryLocalManager.Instance.Urls` after `await FoundryLocalManager.Instance.StartWebServiceAsync()`. |
| | Task | Aliases | | ||
| |------|---------| | ||
| | Chat | `phi-3.5-mini`, `phi-4-mini`, `qwen2.5-0.5b`, `qwen2.5-coder-0.5b` | | ||
| | Audio Transcription | `whisper-tiny`, `whisper-base`, `whisper-small` | |
There was a problem hiding this comment.
The markdown table under "Model Aliases" is malformed (rows start with ||), which will render as an extra empty column or not render as a table depending on the markdown renderer. Update the table to standard |-delimited syntax.
| | Chat | `phi-3.5-mini`, `phi-4-mini`, `qwen2.5-0.5b`, `qwen2.5-coder-0.5b` | | ||
| | Audio Transcription | `whisper-tiny`, `whisper-base`, `whisper-small` | |
There was a problem hiding this comment.
Several aliases listed here (e.g., phi-4-mini, qwen2.5-coder-0.5b, whisper-base, whisper-small) are not referenced anywhere else in this repo’s SDK docs/examples/tests, while phi-3.5-mini, qwen2.5-0.5b, and whisper-tiny are. To avoid teaching assistants nonexistent aliases, please confirm these names are actually present in the Foundry Local catalog and, if not, remove or replace them with aliases that are known to exist.
| | Chat | `phi-3.5-mini`, `phi-4-mini`, `qwen2.5-0.5b`, `qwen2.5-coder-0.5b` | | |
| | Audio Transcription | `whisper-tiny`, `whisper-base`, `whisper-small` | | |
| | Chat | `phi-3.5-mini`, `qwen2.5-0.5b` | | |
| | Audio Transcription | `whisper-tiny` | |
Adds a .github/copilot-instructions.md that provides AI coding assistants (Copilot, Cursor, etc.) with context about Foundry Local's SDK APIs: - JavaScript and C# quick reference for both chat and audio transcription - Key rules: dynamic ports, model aliases, single manager pattern - Model alias table for chat and audio tasks This helps AI agents generate correct Foundry Local code on the first try, particularly for audio transcription which is commonly missed without guidance.
MaanavD
force-pushed
the
docs/copilot-instructions
branch
from
17e78f7 to
d528fa9
Compare
|
Addressed all Copilot review points:
|
Adds a .github/copilot-instructions.md\ that gives AI coding assistants (Copilot, Cursor, etc.) context about Foundry Local's SDK APIs for both chat and audio transcription.
Includes:
This directly addresses findings from testing where AI agents consistently failed to discover audio transcription capabilities or generated incorrect SDK code.