diff --git a/specs/api/components/common/RdfValue.yaml b/specs/api/components/common/RdfValue.yaml index 5ed7c992..17097efe 100644 --- a/specs/api/components/common/RdfValue.yaml +++ b/specs/api/components/common/RdfValue.yaml @@ -1,14 +1,57 @@ 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 Term fields + properties: + s: + $ref: '#' + p: + $ref: '#' + o: + $ref: '#' +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 diff --git a/specs/api/components/common/Triple.yaml b/specs/api/components/common/Triple.yaml index 142be0e9..5e15436b 100644 --- a/specs/api/components/common/Triple.yaml +++ b/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 diff --git a/specs/api/components/schemas/agent/AgentResponse.yaml b/specs/api/components/schemas/agent/AgentResponse.yaml index 86d636b5..6fe6abbd 100644 --- a/specs/api/components/schemas/agent/AgentResponse.yaml +++ b/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) diff --git a/specs/api/components/schemas/common/RdfValue.yaml b/specs/api/components/schemas/common/RdfValue.yaml index ce8b4c08..17097efe 100644 --- a/specs/api/components/schemas/common/RdfValue.yaml +++ b/specs/api/components/schemas/common/RdfValue.yaml @@ -1,21 +1,57 @@ 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 Term fields + properties: + s: + $ref: '#' + p: + $ref: '#' + o: + $ref: '#' 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 diff --git a/specs/api/components/schemas/common/Triple.yaml b/specs/api/components/schemas/common/Triple.yaml index 1f72b89a..0c36a91c 100644 --- a/specs/api/components/schemas/common/Triple.yaml +++ b/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 diff --git a/specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryResponse.yaml b/specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryResponse.yaml index 6b1d811d..bb72792e 100644 --- a/specs/api/components/schemas/embeddings-query/DocumentEmbeddingsQueryResponse.yaml +++ b/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 diff --git a/specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryResponse.yaml b/specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryResponse.yaml index 80692a12..94bce275 100644 --- a/specs/api/components/schemas/embeddings-query/GraphEmbeddingsQueryResponse.yaml +++ b/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 diff --git a/specs/api/components/schemas/query/TriplesQueryRequest.yaml b/specs/api/components/schemas/query/TriplesQueryRequest.yaml index 88b0a1eb..d49e0300 100644 --- a/specs/api/components/schemas/query/TriplesQueryRequest.yaml +++ b/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 diff --git a/specs/api/components/schemas/rag/DocumentRagResponse.yaml b/specs/api/components/schemas/rag/DocumentRagResponse.yaml index 6a0166e7..1b275c3a 100644 --- a/specs/api/components/schemas/rag/DocumentRagResponse.yaml +++ b/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: diff --git a/specs/api/components/schemas/rag/GraphRagResponse.yaml b/specs/api/components/schemas/rag/GraphRagResponse.yaml index de6c74cc..47513fe1 100644 --- a/specs/api/components/schemas/rag/GraphRagResponse.yaml +++ b/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 diff --git a/specs/api/openapi.yaml b/specs/api/openapi.yaml index 4196f9ec..982a7cc4 100644 --- a/specs/api/openapi.yaml +++ b/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' diff --git a/specs/api/paths/document-stream.yaml b/specs/api/paths/document-stream.yaml new file mode 100644 index 00000000..5f6a11a7 --- /dev/null +++ b/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' diff --git a/specs/websocket/asyncapi.yaml b/specs/websocket/asyncapi.yaml index 43204aa7..056cc055 100644 --- a/specs/websocket/asyncapi.yaml +++ b/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