REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/components/schemas/rag/DocumentRagRequest.yaml

@@ -0,0 +1,33 @@
+type: object
+description: |
+  Document RAG (Retrieval-Augmented Generation) query request.
+  Searches document embeddings and generates answer using retrieved context.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: User query or question
+    example: What are the key findings in the research papers?
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search within
+    default: default
+    example: research
+  doc-limit:
+    type: integer
+    description: Maximum number of documents to retrieve
+    default: 20
+    minimum: 1
+    maximum: 100
+    example: 10
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/rag/DocumentRagResponse.yaml

@@ -0,0 +1,24 @@
+type: object
+description: Document RAG response
+properties:
+  response:
+    type: string
+    description: Generated response based on retrieved documents
+    example: The research papers found three key findings...
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to retrieve documents
+      type:
+        type: string
+        description: Error type
+        example: RETRIEVAL_ERROR

specs/api/components/schemas/rag/GraphRagRequest.yaml

@@ -0,0 +1,54 @@
+type: object
+description: |
+  Graph RAG (Retrieval-Augmented Generation) query request.
+  Searches knowledge graph and generates answer using retrieved subgraph.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: User query or question
+    example: What connections exist between quantum physics and computer science?
+  user:
+    type: string
+    description: User identifier for multi-tenancy
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search within
+    default: default
+    example: research
+  entity-limit:
+    type: integer
+    description: Maximum number of entities to retrieve
+    default: 50
+    minimum: 1
+    maximum: 200
+    example: 30
+  triple-limit:
+    type: integer
+    description: Maximum number of triples to retrieve per entity
+    default: 30
+    minimum: 1
+    maximum: 100
+    example: 20
+  max-subgraph-size:
+    type: integer
+    description: Maximum total subgraph size (triples)
+    default: 1000
+    minimum: 10
+    maximum: 5000
+    example: 500
+  max-path-length:
+    type: integer
+    description: Maximum path length for graph traversal
+    default: 2
+    minimum: 1
+    maximum: 5
+    example: 3
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true

specs/api/components/schemas/rag/GraphRagResponse.yaml

@@ -0,0 +1,24 @@
+type: object
+description: Graph RAG response
+properties:
+  response:
+    type: string
+    description: Generated response based on retrieved knowledge graph
+    example: Quantum physics and computer science intersect in quantum computing...
+  end-of-stream:
+    type: boolean
+    description: Indicates streaming is complete (streaming mode)
+    default: false
+    example: true
+  error:
+    type: object
+    description: Error details if request failed
+    properties:
+      message:
+        type: string
+        description: Error message
+        example: Failed to retrieve graph data
+      type:
+        type: string
+        description: Error type
+        example: GRAPH_ERROR