mirror of
https://github.com/microsoft/postgres-skills.git
synced 2026-11-04 12:01:44 +00:00
5d003f1837
## What Adds a new **pg-graph** skill to the plugin, covering the full knowledge-graph lifecycle on PostgreSQL with Apache AGE. It is a sibling to `postgresql-best-practices`, which now points here for anything involving Apache AGE, openCypher, `ag_catalog`, knowledge graphs, or ontology. **Hard constraint:** everything uses capabilities available **today** — agent-driven extraction over the MCP query tools, the `azure_ai` extension, pgvector, and Apache AGE. It does **not** depend on unreleased `ai.*` pipeline primitives. ## Lifecycle covered 1. **Derive an ontology** from structured or unstructured data — taxonomy learning, confidence/quality scores, and a reader-friendly human feedback loop before finalizing (`ontology-derivation`). 2. **Build the graph** — idempotent `MERGE` load, context-aware deduplication, jargon/taxonomy learning (`extract-to-graph`, `context-dedup`). 3. **Consume the graph** — openCypher/AGE patterns, natural-language-to-Cypher, schema introspection, worked examples (`opencypher-age-patterns`, `text-to-cypher`, `graph-schema-introspection`, `examples`). 4. **Retrieve and explain** — pgvector seed + AGE traversal + rerank, `azure_ai` embeddings, and explainability/traceability with provenance, a returned reasoning path, weakest-link path confidence, and a reproducible reasoning-trace log (`graph-augmented-rag`, `azure-ai-semantic-search`, `graph-explainability`). ## Key AGE-on-managed-Azure caveats baked in - `age` is in `shared_preload_libraries` on managed Azure, so `LOAD 'age'` is unnecessary and blocked for non-superusers. - `ag_catalog.cypher()` requires the graph name as a **literal**, not a bind parameter. - `search_path = public, ag_catalog` (ag_catalog not first). ## Evals - Added **11 quality** + **10 routing** challenges for pg-graph, in line with the existing evals framework. - Narrowed the pg-graph container `.skills.json` keywords to meta/help phrases (matching `postgres-skills`) so the SKILL root no longer co-fires on every graph query. - Routing eval: **100% precision/recall/F1** for pg-graph on the copilot-cli and codex-cli hosts; overall routing precision 97.9%. - Deterministic test suite passes (pre-existing marketplace.json symlink failures unrelated). ## Validation Ontology derivation, dedup jargon-mining, NL→Cypher incident traversal, `azure_ai` embeddings (1536-dim), confidence scoring, and the explainability path/trace patterns were all validated live against an Azure Database for PostgreSQL Flexible Server with Apache AGE. --------- Co-authored-by: Aditi Gupta <adig@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
postgres-skills plugin
The installable plugin payload for the postgres-skills marketplace. It bundles
the PostgreSQL skill and the postgres-mcp MCP server so AI-agent CLIs (GitHub Copilot CLI,
Claude Code, Codex) can route PostgreSQL work to the right guidance and tools.
Contents
| Path | Purpose |
|---|---|
skills/postgresql-best-practices/ |
The skill (SKILL.md routing table + reference docs). |
.mcp.json |
Declares the postgres-mcp MCP server (stdio, node ${PLUGIN_ROOT}/run_mcp.js). |
run_mcp.js |
Launcher for the postgres-mcp MCP server. |
POSTGRES_MCP_CLI_VERSION |
Pinned postgres-mcp CLI version. |
.codex-plugin/plugin.json |
Plugin manifest required by Codex. |
Codex compatibility: plugin.json
Codex requires a manifest at .codex-plugin/plugin.json inside the plugin folder.
Without it, codex plugin add postgres-skills@postgres-skills fails with
Error: missing plugin.json.
It should be updated along with the plugin field in .github/plugin/marketplace.json.