@gmickel/gno 1.18.0 → 1.19.0

package/spec/output-schemas/ask.schema.json

@@ -0,0 +1,366 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/ask@1.0",
+  "title": "GNO Ask Response",
+  "description": "Response from gno ask command",
+  "type": "object",
+  "required": ["query", "mode", "results", "meta"],
+  "$defs": {
+    "searchResult": {
+      "type": "object",
+      "required": ["docid", "score", "uri", "snippet", "source"],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Document ID (short hash of source)",
+          "pattern": "^#[a-f0-9]{6,8}$"
+        },
+        "score": {
+          "type": "number",
+          "description": "Relevance score (0-1 normalized)",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "uri": {
+          "type": "string",
+          "description": "Document URI (gno://collection/path)",
+          "pattern": "^gno://[^/]+/.+"
+        },
+        "title": {
+          "type": "string",
+          "description": "Extracted document title (optional)"
+        },
+        "snippetLanguage": {
+          "type": "string",
+          "description": "Language of snippet content (BCP-47 or 'und')"
+        },
+        "context": {
+          "type": "string",
+          "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
+        },
+        "snippet": {
+          "type": "string",
+          "description": "Matching text snippet from document mirror"
+        },
+        "snippetRange": {
+          "type": "object",
+          "description": "Line range of snippet in mirror content",
+          "properties": {
+            "startLine": {
+              "type": "integer",
+              "description": "Start line (1-indexed)",
+              "minimum": 1
+            },
+            "endLine": {
+              "type": "integer",
+              "description": "End line (1-indexed, inclusive)",
+              "minimum": 1
+            }
+          },
+          "required": ["startLine", "endLine"]
+        },
+        "source": {
+          "type": "object",
+          "description": "Source file metadata",
+          "required": ["relPath", "mime", "ext"],
+          "properties": {
+            "absPath": {
+              "type": "string",
+              "description": "Absolute path (included with --source or in MCP)"
+            },
+            "relPath": {
+              "type": "string",
+              "description": "Path relative to collection root"
+            },
+            "mime": {
+              "type": "string",
+              "description": "MIME type of source file"
+            },
+            "ext": {
+              "type": "string",
+              "description": "File extension (including dot)",
+              "pattern": "^\\.[a-zA-Z0-9]+$"
+            },
+            "modifiedAt": {
+              "type": "string",
+              "description": "Last modification time (ISO 8601)",
+              "format": "date-time"
+            },
+            "sizeBytes": {
+              "type": "integer",
+              "description": "File size in bytes",
+              "minimum": 0
+            },
+            "sourceHash": {
+              "type": "string",
+              "description": "SHA-256 hash of source file"
+            }
+          }
+        },
+        "conversion": {
+          "type": "object",
+          "description": "Conversion metadata",
+          "properties": {
+            "converterId": {
+              "type": "string",
+              "description": "Converter identifier (e.g., 'adapter/markitdown-js')"
+            },
+            "converterVersion": {
+              "type": "string",
+              "description": "Converter version"
+            },
+            "mirrorHash": {
+              "type": "string",
+              "description": "SHA-256 hash of mirror content"
+            },
+            "warnings": {
+              "type": "array",
+              "description": "Conversion warnings",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "LOSSY",
+                      "TRUNCATED",
+                      "PARTIAL",
+                      "UNSUPPORTED_FEATURE",
+                      "LOW_CONFIDENCE"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                },
+                "required": ["code", "message"]
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Original query"
+    },
+    "mode": {
+      "type": "string",
+      "description": "Retrieval mode used",
+      "enum": ["hybrid", "bm25_only"]
+    },
+    "queryLanguage": {
+      "type": "string",
+      "description": "Detected or specified query language",
+      "default": "auto"
+    },
+    "answer": {
+      "type": "string",
+      "description": "Grounded answer (present only if --answer and generation available)"
+    },
+    "citations": {
+      "type": "array",
+      "description": "Citations for the answer",
+      "items": {
+        "type": "object",
+        "required": ["docid", "uri"],
+        "properties": {
+          "docid": {
+            "type": "string",
+            "description": "Document ID",
+            "pattern": "^#[a-f0-9]{6,8}$"
+          },
+          "uri": {
+            "type": "string",
+            "description": "Document URI",
+            "pattern": "^gno://[^/]+/.+"
+          },
+          "startLine": {
+            "type": "integer",
+            "description": "Citation start line",
+            "minimum": 1
+          },
+          "endLine": {
+            "type": "integer",
+            "description": "Citation end line",
+            "minimum": 1
+          }
+        }
+      }
+    },
+    "results": {
+      "type": "array",
+      "description": "Search results (same shape as query results)",
+      "items": {
+        "$ref": "#/$defs/searchResult"
+      }
+    },
+    "meta": {
+      "type": "object",
+      "description": "Retrieval metadata",
+      "required": ["expanded", "reranked", "vectorsUsed"],
+      "properties": {
+        "expanded": {
+          "type": "boolean",
+          "description": "Whether query expansion was used"
+        },
+        "reranked": {
+          "type": "boolean",
+          "description": "Whether reranking was applied"
+        },
+        "vectorsUsed": {
+          "type": "boolean",
+          "description": "Whether vector search was used"
+        },
+        "intent": {
+          "type": "string",
+          "description": "Disambiguating context used to steer retrieval without being searched directly"
+        },
+        "candidateLimit": {
+          "type": "integer",
+          "description": "Max candidates sent to reranking (if applicable)",
+          "minimum": 1
+        },
+        "exclude": {
+          "type": "array",
+          "description": "Explicit exclusion terms applied",
+          "items": { "type": "string" }
+        },
+        "queryModes": {
+          "type": "object",
+          "description": "Summary of structured query modes applied",
+          "required": ["term", "intent", "hyde"],
+          "properties": {
+            "term": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "intent": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "hyde": {
+              "type": "boolean"
+            }
+          }
+        },
+        "answerGenerated": {
+          "type": "boolean",
+          "description": "Whether an answer was generated"
+        },
+        "totalResults": {
+          "type": "integer",
+          "description": "Number of results returned",
+          "minimum": 0
+        },
+        "answerContext": {
+          "type": "object",
+          "description": "Answer context selection explain payload",
+          "required": [
+            "strategy",
+            "targetSources",
+            "facets",
+            "selected",
+            "dropped"
+          ],
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["adaptive_coverage_v1"]
+            },
+            "targetSources": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "facets": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "selected": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "docid",
+                  "uri",
+                  "score",
+                  "queryTokenHits",
+                  "facetHits",
+                  "reason"
+                ],
+                "properties": {
+                  "docid": {
+                    "type": "string",
+                    "pattern": "^#[a-f0-9]{6,8}$"
+                  },
+                  "uri": {
+                    "type": "string",
+                    "pattern": "^gno://[^/]+/.+"
+                  },
+                  "score": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "queryTokenHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "facetHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            },
+            "dropped": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "docid",
+                  "uri",
+                  "score",
+                  "queryTokenHits",
+                  "facetHits",
+                  "reason"
+                ],
+                "properties": {
+                  "docid": {
+                    "type": "string",
+                    "pattern": "^#[a-f0-9]{6,8}$"
+                  },
+                  "uri": {
+                    "type": "string",
+                    "pattern": "^gno://[^/]+/.+"
+                  },
+                  "score": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "queryTokenHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "facetHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/backlinks.schema.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/backlinks@1.0",
+  "title": "GNO Backlinks",
+  "description": "List of documents linking to a target document",
+  "type": "object",
+  "required": ["backlinks", "meta"],
+  "properties": {
+    "backlinks": {
+      "type": "array",
+      "description": "List of documents linking to this one",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["sourceDocid", "sourceUri", "startLine", "startCol"],
+            "additionalProperties": false,
+            "properties": {
+              "sourceDocid": {
+                "type": "string",
+                "description": "Source document ID"
+              },
+              "sourceUri": {
+                "type": "string",
+                "description": "Source document URI"
+              },
+              "sourceTitle": {
+                "type": "string",
+                "description": "Source document title"
+              },
+              "linkText": {
+                "type": "string",
+                "description": "Link display text"
+              },
+              "startLine": {
+                "type": "integer",
+                "description": "1-based line number in source",
+                "minimum": 1
+              },
+              "startCol": {
+                "type": "integer",
+                "description": "1-based column in source",
+                "minimum": 1
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "sourceDocid",
+              "sourceUri",
+              "edgeType",
+              "confidence",
+              "edgeSource"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "sourceDocid": {
+                "type": "string",
+                "description": "Source document ID"
+              },
+              "sourceUri": {
+                "type": "string",
+                "description": "Source document URI"
+              },
+              "sourceTitle": {
+                "type": "string",
+                "description": "Source document title"
+              },
+              "edgeType": {
+                "type": "string",
+                "description": "Semantic relationship type"
+              },
+              "relationType": {
+                "type": "string",
+                "description": "Alias of edgeType"
+              },
+              "confidence": {
+                "type": "string",
+                "enum": ["parsed", "configured", "manual", "inferred"]
+              },
+              "edgeSource": {
+                "type": "string",
+                "enum": ["wikilink", "markdown-link", "frontmatter-relation"]
+              }
+            }
+          }
+        ]
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["docid", "totalBacklinks"],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Target document ID"
+        },
+        "uri": {
+          "type": "string",
+          "description": "Target document URI"
+        },
+        "title": {
+          "type": "string",
+          "description": "Target document title"
+        },
+        "totalBacklinks": {
+          "type": "integer",
+          "description": "Total number of backlinks",
+          "minimum": 0
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection filter applied"
+        },
+        "edgeTypeFilter": {
+          "type": "string",
+          "description": "Semantic edge-type filter applied"
+        },
+        "relationFilter": {
+          "type": "string",
+          "description": "Semantic relation filter applied"
+        },
+        "semantic": {
+          "type": "boolean",
+          "description": "Whether backlinks came from the semantic edge layer"
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/bench-result.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GNO Bench Result",
+  "type": "object",
+  "required": ["fixture", "generatedAt", "modes", "meta"],
+  "additionalProperties": false,
+  "properties": {
+    "fixture": {
+      "type": "object",
+      "required": ["path", "version", "queryCount", "topK"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "version": { "const": 1 },
+        "queryCount": { "type": "integer", "minimum": 1 },
+        "topK": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "modes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "type",
+          "status",
+          "queryCount",
+          "failures",
+          "metrics",
+          "latency",
+          "cases"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "enum": ["bm25", "vector", "hybrid"] },
+          "status": { "type": "string", "enum": ["ok", "failed"] },
+          "queryCount": { "type": "integer", "minimum": 1 },
+          "failures": { "type": "integer", "minimum": 0 },
+          "metrics": { "$ref": "#/definitions/metrics" },
+          "latency": { "$ref": "#/definitions/latency" },
+          "cases": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "query",
+                "topK",
+                "expected",
+                "hits",
+                "topDocs",
+                "metrics",
+                "latencyMs"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "query": { "type": "string", "minLength": 1 },
+                "topK": { "type": "integer", "minimum": 1 },
+                "expected": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                },
+                "hits": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                },
+                "topDocs": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                },
+                "metrics": { "$ref": "#/definitions/metrics" },
+                "latencyMs": { "type": "number", "minimum": 0 },
+                "error": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["indexName"],
+      "additionalProperties": false,
+      "properties": {
+        "indexName": { "type": "string", "minLength": 1 },
+        "collection": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "definitions": {
+    "metrics": {
+      "type": "object",
+      "required": ["precisionAtK", "recallAtK", "f1AtK", "mrr", "ndcgAtK"],
+      "additionalProperties": false,
+      "properties": {
+        "precisionAtK": { "type": "number", "minimum": 0, "maximum": 1 },
+        "recallAtK": { "type": "number", "minimum": 0, "maximum": 1 },
+        "f1AtK": { "type": "number", "minimum": 0, "maximum": 1 },
+        "mrr": { "type": "number", "minimum": 0, "maximum": 1 },
+        "ndcgAtK": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "latency": {
+      "type": "object",
+      "required": ["p50Ms", "p95Ms", "meanMs"],
+      "additionalProperties": false,
+      "properties": {
+        "p50Ms": { "type": "number", "minimum": 0 },
+        "p95Ms": { "type": "number", "minimum": 0 },
+        "meanMs": { "type": "number", "minimum": 0 }
+      }
+    }
+  }
+}