microsoft · ashokginjala · Jun 11, 2026 · Jun 12, 2026 · Jun 16, 2026 · Jun 16, 2026
@@ -0,0 +1,59 @@
+---
+applyTo: "**/*.cs,**/*.csproj"
+---
+
+# C# Sample Conventions — Copilot Instructions
+
+Shared C# conventions used across the C# samples in this repository. This repository contains samples for multiple Dragon Copilot products (Physicians, Radiologists, and potentially others in the future). Product-specific patterns live in the matching `<product>.instructions.md` overlay (loaded automatically via `applyTo: <product>/**`).
+
+## Stack
+
+- ASP.NET Core (Web SDK, `Microsoft.NET.Sdk.Web`).
+- Target framework varies by product and sample: Physicians use `net9.0`; Radiologists Quickstart uses `net10.0`; Radiologists AI uses `net10.0-windows10.0.26100` (Windows-only due to Foundry Local). Check the product overlay or `.csproj` for the exact TFM.
+- `Microsoft.Identity.Web` and `Microsoft.AspNetCore.Authentication.JwtBearer` for Entra ID JWT bearer authentication.
+- `System.Text.Json` for serialization, with `JsonStringEnumConverter` registered for enum-as-string serialization and `PropertyNameCaseInsensitive = true`.
+- `Swashbuckle.AspNetCore` for OpenAPI / Swagger documentation in Development.
+
+## Endpoint and controller pattern
+
+- Single-purpose controller per extension capability, decorated with `[ApiController]`, `[Route("v1")]`, `[Produces("application/json")]`.
+- Apply `[Authorize(Policy = "RequiredClaims")]` to the process endpoint, either at the controller level or on the action method. Do not use anonymous routes for business endpoints.
+- POST the process endpoint at `v1/process` and return `Task<ActionResult<ProcessResponse>>`. All samples use an async controller action that accepts a `CancellationToken` parameter to support request cancellation.
+- Include explicit `[ProducesResponseType]` attributes covering at minimum `200`, `400`, `500`. Add `401` / `403` when the sample stacks additional auth layers on top of JWT.
+
+## Authentication pattern
+
+- Configure authentication via the `AddCustomAuthentication(IConfiguration)` extension method.
+- The "RequiredClaims" authorization policy uses a disabled-mode pass-through (`RequireAssertion(_ => true)`) when `Authentication.Enabled` is `false` so disabled-mode requests pass through cleanly.
+- In enabled mode the policy chains `RequireAuthenticatedUser()` plus one `RequireClaim` call per entry under `RequiredClaims` in configuration.
+- The JWT bearer `OnAuthenticationFailed` handler parses the incoming bearer header and logs the actual audience versus the expected audience, which makes "wrong audience" failures easy to diagnose.
+- An `OnTokenValidated` handler logs the inbound claims that the policy will evaluate.
+
+## Pipeline pattern
+
+- Health-check endpoints return a JSON body (e.g. `{"status":"Healthy"}`); samples either use `MapGet` returning `Results.Ok(...)` or a `HealthCheckOptions.ResponseWriter` that writes JSON. Route names vary by product (Physicians use `/health`; Radiologists use `/health/liveness` and `/health/readiness`).
+- Wire up the security pipeline via `app.UseFullSecurity()`.
+- `UseFullSecurity` wraps `UseAuthentication` and `UseAuthorization` inside `app.UseWhen(ctx => !isPublicRoute(ctx), ...)` so public routes bypass JWT validation.
+- Public routes:
+    - `/health/liveness`
+    - `/health/readiness`
+    - Swagger UI at the application root in Development
+
+## Coding conventions
+
+- Mark concrete classes as `sealed` unless they are intended for inheritance.
+- Null-check constructor parameters at the top with `ArgumentNullException.ThrowIfNull(...)`.
+- Use the options pattern (`IOptions<T>`) for configuration sections; do not pass `IConfiguration` to deep collaborators.
+- Use primary constructors or explicit constructor injection. Use `ILogger<T>` for logging.
+- Sample projects suppress documentation analyzers commonly noisy on minimal samples (CA1812, CA1515, CA1848, CA1873, CS1591, CA2227).
+
+## Out of scope
+
+The following patterns appear in some samples but are **not** universal across the repository. Do not assume them when generating new C# code unless the product overlay calls them out:
+
+- Additional business-auth middleware on top of JWT (e.g. license-key validation).
+- A dedicated static class for public-route lists (some samples use an inline string array instead).
+- Source-generated `[LoggerMessage]` partials.
+- A per-sample `extension.yaml` manifest checked into the C# sample folder.
+
+When working inside a specific product folder, also follow that product's overlay (e.g. `radiologists.instructions.md`).
@@ -0,0 +1,82 @@
+---
+applyTo: "**/*.py,**/requirements.txt,**/pyproject.toml"
+---
+
+# Python Sample Conventions — Copilot Instructions
+
+Shared Python conventions for sample extensions in this repository. This repository contains samples for multiple Dragon Copilot products (Physicians, Radiologists, and potentially others in the future). Product-specific patterns live in the matching `<product>.instructions.md` overlay.
+
+## Stack
+
+| Component         | Version |
+| ----------------- | ------- |
+| Python            | 3.12    |
+| FastAPI           | 0.116.1 |
+| uvicorn           | 0.35.0  |
+| pydantic          | 2.11.7  |
+| pydantic-settings | 2.10.1  |
+| pytest            | 9.0.3   |
+
+Pin these exact versions in `requirements.txt`. Use `requirements.txt`, not `pyproject.toml`, to match the existing precedent and keep installation simple for partners.
+
+> Python 3.12 is recommended over 3.14 because several ML / AI Python SDKs do not yet fully support 3.14.
+
+## Project layout
+
+```
+<sample-name>/
+├── README.md
+├── requirements.txt
+└── app/
+    ├── __init__.py
+    ├── main.py            # FastAPI app, /v1/process, /health endpoints
+    ├── config.py          # pydantic-settings
+    ├── auth.py            # Entra ID JWT bearer validation (toggleable)
+    ├── models.py          # Pydantic mirrors of the C# models (Physicians: DragonStandardPayload; Radiologists: ProcessRequest/ProcessResponse)
+    ├── service.py         # Business logic / mock data fallback
+    └── tests/
+        ├── __init__.py
+        └── test_*.py
+```
+
+## Endpoint pattern
+
+- Use FastAPI's decorator-based routing: `@app.post("/v1/process")`.
+- Define request and response models with Pydantic; do not return raw dicts. The exact DTO types vary by product — Physicians use `DragonStandardPayload`, Radiologists use `ProcessRequest`/`ProcessResponse`. Mirror the corresponding C# models project (`physician/src/models/` or `radiologists/src/models/`).
+- Health endpoints at `/health/liveness` and `/health/readiness` return JSON status payloads, matching the C# samples and the scaffold prompt.
+- Enable FastAPI's automatic Swagger / OpenAPI generation; expose it at `/docs`.
+
+## Configuration
+
+- Use `pydantic_settings.BaseSettings` in `app/config.py`.
+- Load `.env` via `model_config = SettingsConfigDict(env_file=".env")`.
+- Authentication is disabled by default for development. Document the flag in the sample's README so partners enable it intentionally when they harden for production.
+
+## Naming
+
+- snake_case for filenames inside the `app/` package.
+- Mock data filenames use the language's idiomatic casing (e.g., `qualitycheck_response.json` for Radiologists). The exact filename varies — check the corresponding C# sample's `MockData/` folder.
+- PascalCase for Pydantic model classes mirroring C# DTOs (`Report`, `PatientInformation`, `DragonStandardPayload`, etc.).
+- snake_case for field names exposed by Pydantic; use `alias` / `populate_by_name` if the JSON contract uses camelCase.
+
+## Running locally
+
+```powershell
+python3.12 -m venv .venv
+. .\.venv\Scripts\Activate.ps1
+python3.12 -m pip install --upgrade pip
+python3.12 -m pip install -r requirements.txt
+python3.12 -m uvicorn app.main:app --host 0.0.0.0 --port <port> --reload
+```
+
+```bash
+python3.12 -m venv .venv && source .venv/bin/activate && python3.12 -m pip install --upgrade pip && python3.12 -m pip install -r requirements.txt
+python3.12 -m uvicorn app.main:app --host 0.0.0.0 --port <port> --reload
+```
+
+Pick a port that matches the C# sample default for the same product (Physicians: 5181, Radiologists: 5080) so partners can swap implementations without changing client URLs.
+
+## Testing
+
+- Use `pytest` and FastAPI's `TestClient` (`from fastapi.testclient import TestClient`).
+- Keep tests minimal: happy-path `/v1/process`, health endpoints, and deserialization of the mock response.
@@ -0,0 +1,116 @@
+---
+applyTo: "radiologists/**"
+---
+
+# Radiologists Extension Samples — Copilot Instructions
+
+Radiologists extensions analyze radiology reports and return quality-check recommendations.
+
+## Authoritative contract
+
+- **OpenAPI spec:** `radiologists/radiologists-extensibility-api.yaml` is the canonical wire contract for `POST /v1/process`. It defines the envelope as `ProcessRequest` (request) and `ProcessResponse` (response), and contains the full schema definitions for all Radiologists domain types (`SessionData`, `PatientInformation`, `Report`, `QualityCheckResult`, `Recommendation`, `Provenance`, `ReferenceResource`).
+- **Models project:** `radiologists/src/models/Dragon.Copilot.Radiologists.Models/` — C# classes that mirror the OpenAPI spec (`ProcessRequest`, `ProcessResponse`, `SessionData`, `PatientInformation`, `Report`, `QualityCheckResult`, …). The wire envelope lives **here**, not in each sample.
+- **Wire shape (from the spec):**
+    - Request `ProcessRequest`: required `sessionData`; optional `extensibilityApiVersion` (string, e.g. `"1.1.1"`, informational metadata from Dragon Copilot), `patientInformation`, and `report`. Additional named inputs flow through `additionalProperties`. The Radiologists C# model declares `patientInformation` and `report` as explicit properties for convenience.
+    - Response `ProcessResponse`: optional `success`, `message`, and `payload` — a **map** of output name → `QualityCheckResult` (the output name comes from the extension's manifest, e.g. `qualityCheckResult`).
+- **Field casing on the wire is mixed**, matching the YAML: top-level uses camelCase (`extensibilityApiVersion`, `sessionData`, `patientInformation`, `report`); `SessionData` fields are snake_case (`correlation_id`, `session_start`, `environment_id`); `PatientInformation` and `Report` fields are camelCase (`dateOfBirth`, `biologicalSex`, `reportText`).
+
+## Sample variants
+
+Three C# sample variants live under `radiologists/src/samples/Workflow/`:
+
+| Variant      | Folder                                           | Purpose                                                                                                                           | Target                      | Platform       |
+| ------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------- |
+| Quickstart   | `SampleExtension.Radiologists.Web.Quickstart/`   | Returns a canned response from `MockData/qualitycheck-response.json`. The fastest way to get a working extension running locally. | `net10.0`                   | Cross-platform |
+| Ai           | `SampleExtension.Radiologists.Web.Ai/`           | Calls **Azure OpenAI** when the `OpenAI` config is populated; otherwise returns a `503` "not configured" error.                   | `net10.0`                   | Cross-platform |
+| FoundryLocal | `SampleExtension.Radiologists.Web.FoundryLocal/` | Runs an on-device model via **Foundry Local** (`Microsoft.AI.Foundry.Local.WinML`); no cloud account or API key needed.           | `net10.0-windows10.0.26100` | Windows-only   |
+
+## Stack facts
+
+- C# target framework: `net10.0` (Quickstart and Ai, cross-platform), `net10.0-windows10.0.26100` (FoundryLocal, due to the Foundry Local dependency).
+- Default dev ports: **5080** (HTTP), **7080** (HTTPS).
+- `Authentication.Enabled` is `false` by default in `appsettings.json` so partners can clone and run without setting up Entra ID first.
+- Health probes at `/health/liveness` and `/health/readiness`, returning a JSON body (e.g. `{"status":"Healthy"}`) via a health-check response writer.
+- Swagger UI is served at the application root in Development.
+
+## Domain types
+
+Defined in `Dragon.Copilot.Radiologists.Models`:
+
+- `Report` — the radiology report text and metadata
+- `PatientInformation` — patient demographics relevant to the report
+- `QualityCheckResult` — the structured result returned to Dragon Copilot
+- `Recommendation` — an individual quality-check finding
+- `Provenance` — the span of report text a recommendation was derived from (`text`, `startPosition`, `endPosition`)
+- `ReferenceResource` — supporting references attached to a recommendation
+- `BiologicalSex` — the patient's biological sex enum (`Male`, `Female`, `Unknown`, `Other`)
+- `QualityCheckType` — the quality-check category enum (`Billing`, `Clinical`)
+
+## Quality-check service
+
+All sample variants use `IQualityCheckService.ProcessAsync` (async with `CancellationToken`) as the single integration point. Replace its implementation to wire in your own logic.
+
+- **Quickstart variant** (`net10.0`, cross-platform): Returns the canned response in `MockData/qualitycheck-response.json`. Partners can edit the JSON directly to tweak the stubbed output without rebuilding (the file is copied to the build output with `PreserveNewest`).
+- **Ai variant** (`net10.0`, cross-platform): Calls **Azure OpenAI** when the `OpenAI` section in `appsettings.json` has `Endpoint`, `ApiKey`, and `DeploymentName` populated; otherwise returns `503 Service Unavailable` with a clear "not configured" message.
+- **FoundryLocal variant** (`net10.0-windows`, **Windows-only**): Runs an on-device model via **Foundry Local** (`Microsoft.AI.Foundry.Local.WinML`). No cloud account or API key is required — all inference is local.
+
+    **Graceful fallback:** If the model returns malformed JSON or omits the expected `qualityCheckResult` property, the Ai/FoundryLocal services log a warning and return a well-formed `ProcessResponse` with an empty recommendations list instead of throwing. Partners adapting these samples can replace this fallback with their own error-handling strategy.
+
+    The full AI system prompt lives in code as the private `SystemPrompt` const in the Ai and FoundryLocal samples' `Services/QualityCheckService.cs`, so it stays in sync with the running code.
+
+## Endpoint shape
+
+All three samples use an async controller action with `CancellationToken`:
+
+```csharp
+[ApiController]
+[Route("v1")]
+[Produces("application/json")]
+[Authorize(Policy = "RequiredClaims")]
+public sealed class QualityCheckController : ControllerBase
+{
+    [HttpPost("process")]
+    public async Task<ActionResult<ProcessResponse>> PostAsync(
+        [FromBody] ProcessRequest payload,
+        CancellationToken cancellationToken) { ... }
+}
+```
+
+## Manifest format (Radiologists)
+
+Radiologists extension manifests differ from Physicians manifests. Key required fields:
+
+```yaml
+name: sampleQualityCheckExtension # camelCase, starts lowercase
+description: Extension to provide radiology report quality checking
+version: 0.0.1 # Partner's own version (x.y.z)
+radiologistsExtensibilityApiVersion: 1.0.0 # API version from radiologists-extensibility-api.yaml
+auth:
+    tenantId: 00000000-0000-0000-0000-000000000000
+tools:
+    - name: sampleQualityCheckTool # camelCase, starts lowercase
+      toolType: contractBased # Required for Radiologists
+      capability: qualityCheck # Required for Radiologists
+      description: Tool to check quality of a radiology report
+      endpoint: https://publisher.example.com/quality-check
+      inputs:
+          - name: report
+            description: Radiology report from Dragon Copilot
+            content-type: application/vnd.ms-dragon.rad.report+json
+            schemaVersion: "1.0" # Required: version of Report schema accepted
+          - name: patientInformation
+            description: Patient demographic information from Dragon Copilot
+            content-type: application/vnd.ms-dragon.rad.patient-information+json
+            schemaVersion: "1.0" # Required: version of PatientInformation schema accepted
+      outputs:
+          - name: qualityCheckResult
+            description: Quality check findings and score
+            content-type: application/vnd.ms-dragon.rad.quality-check-result+json
+            schemaVersion: "1.0" # Required: version of QualityCheckResult schema produced
+```
+
+See `tools/dragon-copilot-cli/src/schemas/radiologists/radiologists-extension-manifest-schema.json` for the full JSON Schema.
+
+## Scaffolding a sample in another language
+
+When a partner wants a Radiologists sample in a language other than C# (for example Python, Go, Java, or Node.js), invoke the reusable Copilot prompt at `.github/prompts/radiologists-scaffold-language-sample.prompt.md`. Its usage instructions live inside the prompt file itself.