Update API specs for 2.1 (#699)

* Updating API specs for 2.1

* Updated API and SDK docs

specs/api/components/common/RdfValue.yaml

@@ -1,14 +1,60 @@
 type: object
-description: RDF value - can be entity/URI or literal
-required:
-  - v
-  - e
+description: |
+  RDF Term - typed representation of a value in the knowledge graph.
+
+  Term types (discriminated by `t` field):
+  - `i`: IRI (URI reference)
+  - `l`: Literal (string value, optionally with datatype or language tag)
+  - `r`: Quoted triple (RDF-star reification)
+  - `b`: Blank node
 properties:
+  t:
+    type: string
+    description: Term type discriminator
+    enum: [i, l, r, b]
+    example: i
+  i:
+    type: string
+    description: IRI value (when t=i)
+    example: http://example.com/Person1
   v:
     type: string
-    description: Value (URI or literal text)
-    example: https://example.com/entity1
-  e:
-    type: boolean
-    description: True if entity/URI, false if literal
-    example: true
+    description: Literal value (when t=l)
+    example: John Doe
+  d:
+    type: string
+    description: Datatype IRI for literal (when t=l, optional)
+    example: http://www.w3.org/2001/XMLSchema#integer
+  l:
+    type: string
+    description: Language tag for literal (when t=l, optional)
+    example: en
+  r:
+    type: object
+    description: Quoted triple (when t=r) - contains s, p, o as nested Term objects with the same structure
+    properties:
+      s:
+        type: object
+        description: Subject term
+      p:
+        type: object
+        description: Predicate term
+      o:
+        type: object
+        description: Object term
+required:
+  - t
+examples:
+  - description: IRI term
+    value:
+      t: i
+      i: http://schema.org/name
+  - description: Literal term
+    value:
+      t: l
+      v: John Doe
+  - description: Literal with language tag
+    value:
+      t: l
+      v: Bonjour
+      l: fr

specs/api/components/common/Triple.yaml

@@ -1,5 +1,6 @@
 type: object
-description: RDF triple (subject-predicate-object)
+description: |
+  RDF triple (subject-predicate-object), optionally scoped to a named graph.
 required:
   - s
   - p
@@ -14,3 +15,7 @@ properties:
   o:
     $ref: './RdfValue.yaml'
     description: Object
+  g:
+    type: string
+    description: Named graph URI (optional)
+    example: urn:graph:source

specs/api/components/schemas/agent/AgentResponse.yaml

@@ -9,12 +9,26 @@ properties:
       - action
       - observation
       - answer
+      - final-answer
       - error
     example: answer
   content:
     type: string
     description: Chunk content (streaming mode only)
     example: Paris is the capital of France.
+  message_type:
+    type: string
+    description: Message type - "chunk" for agent chunks, "explain" for explainability events
+    enum: [chunk, explain]
+    example: chunk
+  explain_id:
+    type: string
+    description: Explainability node URI (for explain messages)
+    example: urn:trustgraph:agent:abc123
+  explain_graph:
+    type: string
+    description: Named graph containing the explainability data
+    example: urn:graph:retrieval
   end-of-message:
     type: boolean
     description: Current chunk type is complete (streaming mode)

specs/api/components/schemas/common/RdfValue.yaml

@@ -1,21 +1,60 @@
 type: object
 description: |
-  RDF value - represents either a URI/entity or a literal value.
+  RDF Term - typed representation of a value in the knowledge graph.
 
-  When `e` is true, `v` must be a full URI (e.g., http://schema.org/name).
-  When `e` is false, `v` is a literal value (string, number, etc.).
+  Term types (discriminated by `t` field):
+  - `i`: IRI (URI reference)
+  - `l`: Literal (string value, optionally with datatype or language tag)
+  - `r`: Quoted triple (RDF-star reification)
+  - `b`: Blank node
 properties:
+  t:
+    type: string
+    description: Term type discriminator
+    enum: [i, l, r, b]
+    example: i
+  i:
+    type: string
+    description: IRI value (when t=i)
+    example: http://example.com/Person1
   v:
     type: string
-    description: The value - full URI when e=true, literal when e=false
-    example: http://example.com/Person1
-  e:
-    type: boolean
-    description: True if entity/URI, false if literal value
-    example: true
+    description: Literal value (when t=l)
+    example: John Doe
+  d:
+    type: string
+    description: Datatype IRI for literal (when t=l, optional)
+    example: http://www.w3.org/2001/XMLSchema#integer
+  l:
+    type: string
+    description: Language tag for literal (when t=l, optional)
+    example: en
+  r:
+    type: object
+    description: Quoted triple (when t=r) - contains s, p, o as nested Term objects with the same structure
+    properties:
+      s:
+        type: object
+        description: Subject term
+      p:
+        type: object
+        description: Predicate term
+      o:
+        type: object
+        description: Object term
 required:
-  - v
-  - e
-example:
-  v: http://schema.org/name
-  e: true
+  - t
+examples:
+  - description: IRI term
+    value:
+      t: i
+      i: http://schema.org/name
+  - description: Literal term
+    value:
+      t: l
+      v: John Doe
+  - description: Literal with language tag
+    value:
+      t: l
+      v: Bonjour
+      l: fr

specs/api/components/schemas/common/Triple.yaml

@@ -1,6 +1,7 @@
 type: object
 description: |
-  RDF triple representing a subject-predicate-object statement in the knowledge graph.
+  RDF triple representing a subject-predicate-object statement in the knowledge graph,
+  optionally scoped to a named graph.
 
   Example: (Person1) -[has name]-> ("John Doe")
 properties:
@@ -13,17 +14,26 @@ properties:
   o:
     $ref: './RdfValue.yaml'
     description: Object - the value or target entity
+  g:
+    type: string
+    description: |
+      Named graph URI (optional). When absent, the triple is in the default graph.
+      Well-known graphs:
+      - (empty/absent): Core knowledge facts
+      - urn:graph:source: Extraction provenance
+      - urn:graph:retrieval: Query-time explainability
+    example: urn:graph:source
 required:
   - s
   - p
   - o
 example:
   s:
-    v: http://example.com/Person1
-    e: true
+    t: i
+    i: http://example.com/Person1
   p:
-    v: http://schema.org/name
-    e: true
+    t: i
+    i: http://schema.org/name
   o:
+    t: l
     v: John Doe
-    e: false

specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryResponse.yaml

@@ -1,12 +1,22 @@
 type: object
-description: Document embeddings query response
+description: Document embeddings query response with matching chunks and similarity scores
 properties:
   chunks:
     type: array
-    description: Similar document chunks (text strings)
+    description: Matching document chunks with similarity scores
     items:
-      type: string
+      type: object
+      properties:
+        chunk_id:
+          type: string
+          description: Chunk identifier URI
+          example: "urn:trustgraph:chunk:abc123"
+        score:
+          type: number
+          description: Similarity score (higher is more similar)
+          example: 0.89
     example:
-      - "Quantum computing uses quantum mechanics principles for computation..."
-      - "Neural networks are computing systems inspired by biological neurons..."
-      - "Machine learning algorithms learn patterns from data..."
+      - chunk_id: "urn:trustgraph:chunk:abc123"
+        score: 0.95
+      - chunk_id: "urn:trustgraph:chunk:def456"
+        score: 0.82

specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryResponse.yaml

@@ -1,12 +1,21 @@
 type: object
-description: Graph embeddings query response
+description: Graph embeddings query response with matching entities and similarity scores
 properties:
   entities:
     type: array
-    description: Similar entities (RDF values)
+    description: Matching graph entities with similarity scores
     items:
-      $ref: '../../common/RdfValue.yaml'
+      type: object
+      properties:
+        entity:
+          $ref: '../../common/RdfValue.yaml'
+          description: Matching graph entity
+        score:
+          type: number
+          description: Similarity score (higher is more similar)
+          example: 0.92
     example:
-      - {v: "https://example.com/person/alice", e: true}
-      - {v: "https://example.com/person/bob", e: true}
-      - {v: "https://example.com/concept/quantum", e: true}
+      - entity: {t: i, i: "https://example.com/person/alice"}
+        score: 0.95
+      - entity: {t: i, i: "https://example.com/concept/quantum"}
+        score: 0.82

specs/api/components/schemas/query/TriplesQueryRequest.yaml

@@ -28,3 +28,23 @@ properties:
     description: Collection to query
     default: default
     example: research
+  g:
+    type: string
+    description: |
+      Named graph filter (optional).
+      - Omitted/null: all graphs
+      - Empty string: default graph only
+      - URI string: specific named graph (e.g., urn:graph:source, urn:graph:retrieval)
+    example: urn:graph:source
+  streaming:
+    type: boolean
+    description: Enable streaming response delivery
+    default: false
+    example: true
+  batch-size:
+    type: integer
+    description: Number of triples per streaming batch
+    default: 20
+    minimum: 1
+    maximum: 1000
+    example: 50

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

@@ -1,13 +1,31 @@
 type: object
-description: Document RAG response
+description: Document RAG response message
 properties:
+  message_type:
+    type: string
+    description: Type of message - "chunk" for LLM response chunks, "explain" for explainability events
+    enum: [chunk, explain]
+    example: chunk
   response:
     type: string
-    description: Generated response based on retrieved documents
-    example: The research papers found three key findings...
+    description: Generated response text (for chunk messages)
+    example: Based on the policy documents, customers can return items within 30 days...
+  explain_id:
+    type: string
+    description: Explainability node URI (for explain messages)
+    example: urn:trustgraph:question:abc123
+  explain_graph:
+    type: string
+    description: Named graph containing the explainability data
+    example: urn:graph:retrieval
   end-of-stream:
     type: boolean
-    description: Indicates streaming is complete (streaming mode)
+    description: Indicates LLM response stream is complete
+    default: false
+    example: true
+  end_of_session:
+    type: boolean
+    description: Indicates entire session is complete (all messages sent)
     default: false
     example: true
   error:

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

@@ -3,17 +3,21 @@ description: Graph RAG response message
 properties:
   message_type:
     type: string
-    description: Type of message - "chunk" for LLM response chunks, "provenance" for provenance announcements
-    enum: [chunk, provenance]
+    description: Type of message - "chunk" for LLM response chunks, "explain" for explainability events
+    enum: [chunk, explain]
     example: chunk
   response:
     type: string
     description: Generated response text (for chunk messages)
     example: Quantum physics and computer science intersect in quantum computing...
-  provenance_id:
+  explain_id:
     type: string
-    description: Provenance node URI (for provenance messages)
-    example: urn:trustgraph:session:abc123
+    description: Explainability node URI (for explain messages)
+    example: urn:trustgraph:question:abc123
+  explain_graph:
+    type: string
+    description: Named graph containing the explainability data
+    example: urn:graph:retrieval
   end_of_stream:
     type: boolean
     description: Indicates LLM response stream is complete

specs/api/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: TrustGraph API Gateway
-  version: "1.8"
+  version: "2.1"
   description: |
     REST API for TrustGraph - an AI-powered knowledge graph and RAG system.
 
@@ -28,7 +28,7 @@ info:
     Require running flow instance, accessed via `/api/v1/flow/{flow}/service/{kind}`:
     - AI services: agent, text-completion, prompt, RAG (document/graph)
     - Embeddings: embeddings, graph-embeddings, document-embeddings
-    - Query: triples, objects, nlp-query, structured-query
+    - Query: triples, rows, nlp-query, structured-query, row-embeddings
     - Data loading: text-load, document-load
     - Utilities: mcp-tool, structured-diag
 
@@ -140,6 +140,10 @@ paths:
   /api/v1/flow/{flow}/service/document-load:
     $ref: './paths/flow/document-load.yaml'
 
+  # Document streaming
+  /api/v1/document-stream:
+    $ref: './paths/document-stream.yaml'
+
   # Import/Export endpoints
   /api/v1/import-core:
     $ref: './paths/import-core.yaml'

specs/api/paths/document-stream.yaml

@@ -0,0 +1,53 @@
+get:
+  tags:
+    - Import/Export
+  summary: Stream document content from library
+  description: |
+    Streams the raw content of a document stored in the library.
+    Returns the document content in chunked transfer encoding.
+
+    ## Parameters
+
+    - `user`: User identifier (required)
+    - `document-id`: Document IRI to retrieve (required)
+    - `chunk-size`: Size of each response chunk in bytes (optional, default: 1MB)
+
+  operationId: documentStream
+  security:
+    - bearerAuth: []
+  parameters:
+    - name: user
+      in: query
+      required: true
+      schema:
+        type: string
+      description: User identifier
+      example: trustgraph
+    - name: document-id
+      in: query
+      required: true
+      schema:
+        type: string
+      description: Document IRI to retrieve
+      example: "urn:trustgraph:doc:abc123"
+    - name: chunk-size
+      in: query
+      required: false
+      schema:
+        type: integer
+        default: 1048576
+      description: Chunk size in bytes (default 1MB)
+  responses:
+    '200':
+      description: Document content streamed as raw bytes
+      content:
+        application/octet-stream:
+          schema:
+            type: string
+            format: binary
+    '400':
+      description: Missing required parameters
+    '401':
+      $ref: '../components/responses/Unauthorized.yaml'
+    '500':
+      $ref: '../components/responses/Error.yaml'

specs/build-docs.sh

@@ -24,7 +24,7 @@ echo
 # Build WebSocket API documentation
 echo "Building WebSocket API documentation (AsyncAPI)..."
 cd ../websocket
-npx --yes -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o /tmp/asyncapi-build -p singleFile=true --force-write
+npx --yes -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o /tmp/asyncapi-build -p singleFile=true --force-write
 mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
 rm -rf /tmp/asyncapi-build
 echo "✓ WebSocket API docs generated: docs/websocket.html"

specs/websocket/asyncapi.yaml

@@ -2,7 +2,7 @@ asyncapi: 3.0.0
 
 info:
   title: TrustGraph WebSocket API
-  version: "1.8"
+  version: "2.1"
   description: |
     WebSocket API for TrustGraph - providing multiplexed, asynchronous access to all services.
 
@@ -31,7 +31,7 @@ info:
     **Flow-Hosted Services** (require `flow` parameter):
     - agent, text-completion, prompt, document-rag, graph-rag
     - embeddings, graph-embeddings, document-embeddings
-    - triples, objects, nlp-query, structured-query, structured-diag
+    - triples, rows, nlp-query, structured-query, structured-diag, row-embeddings
     - text-load, document-load, mcp-tool
 
     ## Schema Reuse