Add Python and Go vector search samples; align TypeScript with constitution - #1517
Open
Dina Berry (MSFT) (diberry) wants to merge 2 commits into
Open
Dina Berry (MSFT) (diberry) wants to merge 2 commits into
Dina Berry (MSFT) (diberry) wants to merge 2 commits into
Conversation
…tution Implements the second wave of the Azure SQL vector search constitution (.github/instructions/vector-search-constitution.instructions.md on branch constitution/azure-sql-vector-search, PR microsoft#1515): TypeScript, Python, and Go for the vector-search scenario. .NET and Java remain constitution-defined future languages and are intentionally not implemented in this PR. ## TypeScript (vector-search-query-typescript/) — audit and alignment - Added ESLint (flat config, typescript-eslint recommended) and Prettier, with npm run lint / format / format:check scripts. Fixed the two findings ESLint surfaced: an unsafe �s any cast on tedious's addParameter (now typed via (typeof TYPES)[keyof typeof TYPES]) and missing Node globals in the plain-JS typecheck helper script. - Added CI steps for lint and format:check ahead of the existing type-check step. - Added output/sample-output.txt: the real, previously captured run output already published in this sample's README "Expected output" section, now also committed as the required standalone reference file. Carved out .gitignore's output/ exclusion (output/* + negated !output/sample-output.txt) so this committed file is not silently re-ignored. - No behavior changes; only type-safety and tooling additions plus the reformatting Prettier's format:check gate requires. ## Python (vector-search-query-python/) — new, idiomatic implementation - pyodbc (SQL driver) + azure-identity (Entra auth, via the documented SQL_COPT_SS_ACCESS_TOKEN pattern since pyodbc has no built-in DefaultAzureCredential integration) + openai's AzureOpenAI class (embeddings). Configuration via .env (sample.env template), matching the constitution's per-language config-mechanism table. - Same table shape, same DiskANN >=1,000-row gate (falls back to exact automatically), same JSON-cast vector binding, same canonical query and hotel dataset as the TypeScript reference — not transliterated, but idiomatic Python (dataclass config, context-managed cursor, batched fast_executemany insert). - requirements.txt (>=-pinned) + requirements-dev.txt (ruff, mypy, pytest) + pyproject.toml. 22 unit tests cover configuration validation, table-name validation, and dataset-shape validation without requiring Azure connectivity. - CI: ruff check, ruff format --check, mypy, pytest. ## Go (vector-search-query-go/) — new, idiomatic implementation - github.com/microsoft/go-mssqldb + its azuread subpackage (driver name "azuresql", fedauth=ActiveDirectoryDefault DSN parameter — the driver handles Entra token acquisition internally, unlike TS/Python) + github.com/Azure/azure-sdk-for-go/sdk/azidentity (embeddings-call credential) + github.com/openai/openai-go/v3 with its azure subpackage (embeddings). - IMPORTANT CURRENCY FINDING, not guessed: github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai — the package the constitution's initial authoring named for this role — changed function as of its v0.8.0 release (2025-06-03) and is no longer a standalone client; it is now only a companion package providing Azure-specific extension types to the official openai-go client. Verified live against the actual v0.9.0 source and its own example/test files before writing this code. For a plain embeddings call, azopenai itself is not required at all. This finding requires a follow-up correction to the constitution's ASV-CORE-37/ASV-LANG-GO-5 Go row on PR microsoft#1515 (or a fast-follow PR after it merges) — flagged in the PR description, not silently absorbed. - Idiomatic Go module layout: cmd/query (search scenario) and cmd/embed (embedding regeneration) binaries, internal/config and internal/hotels shared packages. Same table shape, same DiskANN gate, same JSON-cast vector binding as every other language. 6 unit tests (go test) cover configuration validation and dataset-shape/vector-serialization validation without requiring Azure connectivity. - CI: gofmt -l (format check), go vet, go build, go test. ## Explicit no-live-execution disclosure (both new languages) No authorized live Azure SQL Database or Azure OpenAI environment was available while authoring this PR. Python's and Go's output/sample-output.txt and README "Expected output" sections say so explicitly and are marked as NOT a captured real run (placeholder values only) — they must not be treated as validated end-to-end evidence. What was validated locally without live Azure access, for both languages: static analysis (lint/ format/vet/type-check), full local build, and unit tests for all pure/testable logic (config validation, vector serialization, dataset validation). TypeScript's output/sample-output.txt is the one real captured run, carried over from its existing README section. ## Shared changes - samples/features/vector-search/README.md: added Python and Go rows to the language table with explicit status (implemented + statically validated vs. TypeScript's implemented + live-validated), and generalized the .env setup instructions to name all three languages. - Reused the existing shared data/ (HotelsData_Vector.json) and infra/ (Azure SQL Database + Azure OpenAI Bicep) unchanged. No new platform, scenario, or documentation article added. Depends on constitution PR microsoft#1515 (not yet merged) as the governing source; this PR's constitution reference resolves once microsoft#1515 merges. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…on ruff/README) Validated via a same-repo draft PR on the fork per the fork-workflow skill (upstream PR microsoft#1516 correctly skips CI for fork-originated PRs by design, matching the existing TypeScript CI's fork-PR guard, so this was the only way to get real CI execution before review). - Go: go.mod's go directive was auto-set to 1.26.1 by the local toolchain used to write this sample, but CI pins go-version: "1.25" per the constitution's stated Go 1.25+ minimum (ASV-LANG-GO-2). Ran go mod tidy to reset the directive to 1.25.0 and correctly split direct vs. indirect requires (previously everything was marked indirect). Rebuilt/vetted/tested locally afterward — unchanged, still green. - Python: uff format --check . also scans embedded Python code blocks inside README.md by default and wanted to reformat one, which would have altered published documentation prose formatting. Added �xtend-exclude = ["README.md"] to pyproject.toml, matching the same doc-vs-code formatting boundary already established for TypeScript's Prettier config (.prettierignore excludes README.md). Re-verified all three languages' full local check suites still pass after these fixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the second wave of the Azure SQL vector search constitution (
.github/instructions/vector-search-constitution.instructions.md) for TypeScript, Python, and Go. .NET and Java remain constitution-defined future languages and are not implemented in this PR.Depends on: #1515 (constitution PR, not yet merged). The constitution file itself is intentionally not included in this PR — this PR reads it from
origin/constitution/azure-sql-vector-searchas the governing input and implements against it, so the two PRs can be reviewed and merged independently, with this one rebasing on #1515's actual merged content when it lands.Tracking: AB#580700
What changed, per language
TypeScript (
vector-search-query-typescript/) — audit and alignment, no behavior changenpm run lint/format/format:check. Fixed the two findings ESLint surfaced (an unsafeas anycast ontedious'saddParameter, and missing Node globals in the plain-JS typecheck helper).output/sample-output.txt— the real, previously captured run output already published in this sample's README, now also committed as the standalone reference file the constitution requires. Added a.gitignorecarve-out so this file isn't silently re-ignored by the existing blanketoutput/rule.Python (
vector-search-query-python/) — newpyodbc(driver) +azure-identity(Entra auth via the documentedSQL_COPT_SS_ACCESS_TOKENpattern) +openai'sAzureOpenAIclass (embeddings)..env-based configuration (sample.envtemplate).requirements.txt(>=-pinned) +requirements-dev.txt(ruff, mypy, pytest) +pyproject.toml. 22 unit tests, all passing, covering config/table-name/dataset validation without requiring Azure connectivity.ruff check,ruff format --check,mypy,pytest.Go (
vector-search-query-go/) — newgithub.com/microsoft/go-mssqldb+ itsazureadsubpackage (fedauth=ActiveDirectoryDefault; the driver handles Entra auth internally) +github.com/Azure/azure-sdk-for-go/sdk/azidentity+github.com/openai/openai-go/v3with itsazuresubpackage (embeddings).github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai— the package the constitution's initial authoring named for the embeddings role — changed function as of its v0.8.0 release (2025-06-03): it's no longer a standalone client and now only supplies Azure-specific extension types to the officialopenai-goclient. Confirmed directly againstazopenaiv0.9.0's own source and test files before writing this code. For a plain embeddings call,azopenaiitself isn't needed at all. This requires a follow-up correction to constitution PR (ignore) Add Azure SQL vector search sample constitution #1515'sASV-CORE-37/ASV-LANG-GO-5Go row — flagging it here rather than silently absorbing it.cmd/query+cmd/embedbinaries,internal/config+internal/hotelsshared packages. Same table shape/gate/binding as every other language. 6 unit tests (go test), all passing.gofmt -l,go vet,go build,go test.Explicit no-live-execution disclosure
No authorized live Azure SQL Database or Azure OpenAI environment was available while authoring this PR. Python's and Go's
output/sample-output.txtfiles and README "Expected output" sections say so explicitly and use placeholder values — they are not captured real runs and must not be treated as end-to-end validated evidence. What was validated locally instead, for both languages: full static analysis (lint/format/vet/type-check), successful build, and unit tests for every pure/testable code path. TypeScript'soutput/sample-output.txtis a real captured run, carried over unchanged from its existing, already-published README section.Validation evidence
npm run build✅npm run lint✅ /npm run format:check✅python -m py_compile✅ruff check✅ /ruff format --check✅mypy src✅pytest— 22 passedgo build ./...✅gofmt -l .(clean) ✅go vet ./...✅go test ./...— 6 passedScope
data/(HotelsData_Vector.json) andinfra/(Azure SQL Database + Azure OpenAI Bicep) unchanged..NET, no Java, no new scenario, no documentation article.samples/features/vector-search/README.md's language table with Python/Go rows and their validation status.Checklist
upstream/master(not from the unmerged constitution branch)git diff --statreviewed before commit)