docs(skill): align skill markdown with /query contract and Postgres architecture#128
Conversation
…rchitecture Resolves sub-issues #125, #126, #127 (parent #123). Sub-issue A — Architecture and runtime terminology (#125): - Replace Qdrant/Neo4j/Redis wording with Postgres + pgvector in all three skill files - Update docker-compose startup comments (no Qdrant, Redis, or Neo4j) - Update enrichment and knowledge graph sections to reflect current Postgres-backed architecture Sub-issue B — /query contract and filter example modernisation (#126): - Replace Qdrant-native filter.must arrays with flat key-value filter objects in all skill files - Add strategy enum (semantic|metadata|graph|hybrid) to params table - Demote graphExpand to deprecated; strategy:"graph" is primary guidance - Update CLI flags table: remove "Qdrant collection" label Sub-issue C — Response envelope, metadata strategy caveat, reference cleanup (#127): - Add routing field to all /query response examples - metadata strategy: score is 1.0; text may be present (clients must not rely on absence) - Replace Qdrant infrastructure row with Postgres+pgvector in REFERENCE.md - Replace QDRANT_URL/QDRANT_COLLECTION env vars with DATABASE_URL No code changes. All edits limited to the three listed skill markdown files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR updates skill documentation to align with the current Postgres-based architecture and unified /query routing contract introduced in PR #122. The changes remove all references to legacy backends (Qdrant, Neo4j, Redis) and modernize API examples to use the current filter syntax and response envelope format.
Changes:
- Migrated architecture references from Qdrant/Neo4j/Redis to Postgres + pgvector across all three skill markdown files
- Modernized
/queryfilter examples from nestedmustarrays to flat key-value objects ({"repoId":"my-repo","lang":"ts"}) - Added
routingfield to all query response examples and documented thestrategyparameter
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| skill/skills/raged/SKILL.md | Updated architecture descriptions, docker-compose comments, filter syntax, query parameters table, response examples with routing field, and metadata strategy caveat |
| skill/SKILL.md | Updated architecture descriptions, docker-compose comments, ingestion descriptions, enrichment prerequisites, and knowledge graph storage location |
| skill/references/REFERENCE.md | Updated ingest/query endpoint descriptions, filter examples, response envelope, environment variables table, and infrastructure table |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9fe76723df
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mfittko
deleted the
docs/skill-align-query-contract-and-postgres-architecture
branch
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `DATABASE_URL` | _(required)_ | Postgres connection string (e.g. `postgresql://raged:raged@localhost:5432/raged`) | | ||
| | `OLLAMA_URL` | `http://ollama:11434` | Ollama connection | | ||
| | `QDRANT_COLLECTION` | `docs` | Default collection | | ||
| | `VECTOR_SIZE` | `768` | Embedding dimensions | |
There was a problem hiding this comment.
VECTOR_SIZE is still documented here, but the current API code does not read a VECTOR_SIZE env var (embedding dimensions aren’t runtime-configured via this setting). Consider removing it (or replacing it with the supported embedding config env vars) to avoid implying a non-functional knob.
| | `VECTOR_SIZE` | `768` | Embedding dimensions | |
| docker compose up -d # base stack (Postgres, Ollama, API) | ||
| docker compose --profile enrichment up -d # full stack with enrichment worker |
There was a problem hiding this comment.
The docker-compose guidance implies that enabling the enrichment profile is sufficient for enrichment/graph features, but the API gates enrichment task enqueueing on ENRICHMENT_ENABLED=true. Consider updating the comment to mention setting ENRICHMENT_ENABLED (or pointing to the canonical local-dev docs) so users don’t start the worker and still see no enrichment/graph data.
| docker compose up -d # base stack (Qdrant, Ollama, API) | ||
| docker compose --profile enrichment up -d # full stack with Redis, Neo4j, worker | ||
| docker compose up -d # base stack (Postgres, Ollama, API) | ||
| docker compose --profile enrichment up -d # full stack with enrichment worker |
There was a problem hiding this comment.
The docker-compose guidance implies that enabling the enrichment profile is sufficient for enrichment/graph features, but the API gates enrichment task enqueueing on ENRICHMENT_ENABLED=true. Consider updating the comment to mention setting ENRICHMENT_ENABLED (or pointing to the canonical local-dev docs) so users don’t start the worker and still see no enrichment/graph data.
| docker compose --profile enrichment up -d # full stack with enrichment worker | |
| docker compose --profile enrichment up -d # full stack with enrichment worker (requires ENRICHMENT_ENABLED=true for enrichment/graph) |
|
|
||
| | Field | Type | Default | Description | | ||
| |-------|------|---------|-------------| | ||
| | `query` | string | **required** | Natural-language search text | |
There was a problem hiding this comment.
The query parameters table marks query as required, but the canonical /query contract allows filter-only requests when strategy resolves to metadata (and generally requires query only for semantic/graph/hybrid). Updating this row will prevent clients/agents from incorrectly rejecting valid metadata-only requests.
| | `query` | string | **required** | Natural-language search text | | |
| | `query` | string | _(required for semantic/graph/hybrid; optional for metadata-only)_ | Natural-language search text | |
| ## Knowledge Graph | ||
|
|
||
| When Neo4j is enabled, raged builds a knowledge graph of entities and relationships extracted from documents. | ||
| raged builds a knowledge graph of entities and relationships extracted from documents. |
There was a problem hiding this comment.
This Knowledge Graph section now reads as unconditional (“raged builds a knowledge graph…”), but graph/entity data is only produced when enrichment is enabled and the worker is running. Consider qualifying this sentence (similar to skill/SKILL.md) so users don’t expect graph results on a base stack.
| raged builds a knowledge graph of entities and relationships extracted from documents. | |
| When enrichment is enabled and the enrichment worker is running, raged builds a knowledge graph of entities and relationships extracted from documents. On a base stack without enrichment, graph and entity data will not be available. |
| ## Ingesting Content | ||
|
|
||
| Ingest any text into the knowledge base. raged chunks it, embeds each chunk, and stores vectors in Qdrant. | ||
| Ingest any text into the knowledge base. raged chunks it, embeds each chunk, and stores vectors in Postgres with pgvector. |
There was a problem hiding this comment.
skill/SKILL.md still states that for metadata strategy “text is absent”, but the current contract (and the updated wording in the other skill docs) is that text may be present and clients must not rely on its absence. Please update the metadata strategy note in this file to match the canonical API reference and keep the three skill docs consistent.
Fixes #125, #126, #127 (closes parent #123).
Summary
Docs-only alignment pass across the three skill markdown files to match the canonical
/querycontract and current Postgres architecture introduced by epic #109 / PR #122.Changes
All edits are limited to
skill/SKILL.md,skill/skills/raged/SKILL.md, andskill/references/REFERENCE.md.Sub-issue A — Architecture and runtime terminology (#125)
Sub-issue B — /query contract and filter example modernisation (#126)
filter.mustarrays with flat key-value filter objects ({"repoId":"my-repo","lang":"ts"})strategyenum (semantic|metadata|graph|hybrid) to query params table inskill/skills/raged/SKILL.mdgraphExpanddemoted to deprecated note;strategy: "graph"is primary guidance--collectionflagsSub-issue C — Response envelope, metadata strategy caveat, reference cleanup (#127)
routingfield to all/queryresponse examplesscoreis always1.0;textmay be present — clients must not rely on its absenceREFERENCE.mdQDRANT_URL/QDRANT_COLLECTIONenv vars withDATABASE_URLinREFERENCE.mdVerification Checklist
grep -r "Qdrant|Neo4j|Redis|QDRANT" skill/returns 0 results/queryfilter examples use flat key-value objectsfilter.mustreplaced; examples use{"repoId":"...","lang":"..."}strategyparam documented andgraphExpanddeprecatedskill/skills/raged/SKILL.mdupdated/queryresponses includeroutingfieldmetadatastrategy caveat ontextpresenceDATABASE_URLreplacesQDRANT_URL/QDRANT_COLLECTIONREFERENCE.mdenv vars table updatedgit diff --statshows only the 3 skill markdown files