From 664d1d0384cb9f60b25e38df66ac2373083a3bbb Mon Sep 17 00:00:00 2001 From: cybermaggedon Date: Tue, 17 Mar 2026 20:36:31 +0000 Subject: [PATCH] Update API specs for 2.1 (#699) * Updating API specs for 2.1 * Updated API and SDK docs --- docs/api-gateway-changes-v1.8-to-v2.1.md | 108 + docs/api.html | 2018 ++++++++------- docs/cli-changes-v1.8-to-v2.1.md | 112 + docs/python-api.md | 2234 +++++++++++++++-- docs/websocket.html | 1411 +++++------ specs/api/components/common/RdfValue.yaml | 66 +- specs/api/components/common/Triple.yaml | 7 +- .../schemas/agent/AgentResponse.yaml | 14 + .../components/schemas/common/RdfValue.yaml | 67 +- .../api/components/schemas/common/Triple.yaml | 22 +- .../DocumentEmbeddingsQueryResponse.yaml | 22 +- .../GraphEmbeddingsQueryResponse.yaml | 21 +- .../schemas/query/TriplesQueryRequest.yaml | 20 + .../schemas/rag/DocumentRagResponse.yaml | 26 +- .../schemas/rag/GraphRagResponse.yaml | 14 +- specs/api/openapi.yaml | 8 +- specs/api/paths/document-stream.yaml | 53 + specs/build-docs.sh | 2 +- specs/websocket/asyncapi.yaml | 4 +- 19 files changed, 4280 insertions(+), 1949 deletions(-) create mode 100644 docs/api-gateway-changes-v1.8-to-v2.1.md create mode 100644 docs/cli-changes-v1.8-to-v2.1.md create mode 100644 specs/api/paths/document-stream.yaml diff --git a/docs/api-gateway-changes-v1.8-to-v2.1.md b/docs/api-gateway-changes-v1.8-to-v2.1.md new file mode 100644 index 00000000..099dadb0 --- /dev/null +++ b/docs/api-gateway-changes-v1.8-to-v2.1.md @@ -0,0 +1,108 @@ +# API Gateway Changes: v1.8 to v2.1 + +## Summary + +The API gateway gained new WebSocket service dispatchers for embeddings +queries, a new REST streaming endpoint for document content, and underwent +a significant wire format change from `Value` to `Term`. The "objects" +service was renamed to "rows". + +--- + +## New WebSocket Service Dispatchers + +These are new request/response services available through the WebSocket +multiplexer at `/api/v1/socket` (flow-scoped): + +| Service Key | Description | +|-------------|-------------| +| `document-embeddings` | Queries document chunks by text similarity. Request/response uses `DocumentEmbeddingsRequest`/`DocumentEmbeddingsResponse` schemas. | +| `row-embeddings` | Queries structured data rows by text similarity on indexed fields. Request/response uses `RowEmbeddingsRequest`/`RowEmbeddingsResponse` schemas. | + +These join the existing `graph-embeddings` dispatcher (which was already +present in v1.8 but may have been updated). + +### Full list of WebSocket flow service dispatchers (v2.1) + +Request/response services (via `/api/v1/flow/{flow}/service/{kind}` or +WebSocket mux): + +- `agent`, `text-completion`, `prompt`, `mcp-tool` +- `graph-rag`, `document-rag` +- `embeddings`, `graph-embeddings`, `document-embeddings` +- `triples`, `rows`, `nlp-query`, `structured-query`, `structured-diag` +- `row-embeddings` + +--- + +## New REST Endpoint + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/v1/document-stream` | Streams document content from the library as raw bytes. Query parameters: `user` (required), `document-id` (required), `chunk-size` (optional, default 1MB). Returns the document content in chunked transfer encoding, decoded from base64 internally. | + +--- + +## Renamed Service: "objects" to "rows" + +| v1.8 | v2.1 | Notes | +|------|------|-------| +| `objects_query.py` / `ObjectsQueryRequestor` | `rows_query.py` / `RowsQueryRequestor` | Schema changed from `ObjectsQueryRequest`/`ObjectsQueryResponse` to `RowsQueryRequest`/`RowsQueryResponse`. | +| `objects_import.py` / `ObjectsImport` | `rows_import.py` / `RowsImport` | Import dispatcher for structured data. | + +The WebSocket service key changed from `"objects"` to `"rows"`, and the +import dispatcher key similarly changed from `"objects"` to `"rows"`. + +--- + +## Wire Format Change: Value to Term + +The serialization layer (`serialize.py`) was rewritten to use the new `Term` +type instead of the old `Value` type. + +### Old format (v1.8 — `Value`) + +```json +{"v": "http://example.org/entity", "e": true} +``` + +- `v`: the value (string) +- `e`: boolean flag indicating whether the value is a URI + +### New format (v2.1 — `Term`) + +IRIs: +```json +{"t": "i", "i": "http://example.org/entity"} +``` + +Literals: +```json +{"t": "l", "v": "some text", "d": "datatype-uri", "l": "en"} +``` + +Quoted triples (RDF-star): +```json +{"t": "r", "r": {"s": {...}, "p": {...}, "o": {...}}} +``` + +- `t`: type discriminator — `"i"` (IRI), `"l"` (literal), `"r"` (quoted triple), `"b"` (blank node) +- Serialization now delegates to `TermTranslator` and `TripleTranslator` from `trustgraph.messaging.translators.primitives` + +### Other serialization changes + +| Field | v1.8 | v2.1 | +|-------|------|------| +| Metadata | `metadata.metadata` (subgraph) | `metadata.root` (simple value) | +| Graph embeddings entity | `entity.vectors` (plural) | `entity.vector` (singular) | +| Document embeddings chunk | `chunk.vectors` + `chunk.chunk` (text) | `chunk.vector` + `chunk.chunk_id` (ID reference) | + +--- + +## Breaking Changes + +- **`Value` to `Term` wire format**: All clients sending/receiving triples, embeddings, or entity contexts through the gateway must update to the new Term format. +- **`objects` to `rows` rename**: WebSocket service key and import key changed. +- **Metadata field change**: `metadata.metadata` (a serialized subgraph) replaced by `metadata.root` (a simple value). +- **Embeddings field changes**: `vectors` (plural) became `vector` (singular); document embeddings now reference `chunk_id` instead of inline `chunk` text. +- **New `/api/v1/document-stream` endpoint**: Additive, not breaking. diff --git a/docs/api.html b/docs/api.html index 201771ec..7cbddd32 100644 --- a/docs/api.html +++ b/docs/api.html @@ -12,413 +12,417 @@ margin: 0; } - -
API docs by Redocly
API docs by Redocly

TrustGraph API Gateway (1.8)

Download OpenAPI specification:

URL: https://trustgraph.ai License: Apache 2.0

REST API for TrustGraph - an AI-powered knowledge graph and RAG system.

-

Overview

TrustGraph API Gateway (2.1)

Download OpenAPI specification:

URL: https://trustgraph.ai License: Apache 2.0

REST API for TrustGraph - an AI-powered knowledge graph and RAG system.

+

Overview

Import/Export: Bulk data operations for triples, embeddings, entity contexts
  • WebSocket: Multiplexed interface for all services
    • -

    Service Types

    Service Types

  • 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
    • -

    Authentication

    Authentication

    : Bearer <token>

    If GATEWAY_SECRET is not set, API runs without authentication (development mode).

    -

    Field Naming

    Field Naming

    All JSON fields use kebab-case: flow-id, blueprint-name, doc-limit, etc.

    -

    Error Responses

    Error Responses

    } } -

    Config

    Config

    Configuration management (global service)

    -

    Configuration service

    Configuration service

    Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.

    Operations

    config

    Get the complete system configuration including all flows, prompts, token costs, etc.

    @@ -576,7 +580,7 @@ The flow service (/api/v1/flow) manages runnin
  • Use config service to store/retrieve flow definitions
  • Use flow service to start/stop/manage running flows
    • -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "config" "list" "get" "put" "delete"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "config" "list" "get" "put" "delete"

    Operation to perform:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Operation to perform:

    • config: Get complete configuration
    • list: List all items of a specific type
      • @@ -592,25 +596,25 @@ The flow service (/api/v1/flow) manages runnin
    • put: Set/update configuration values
    • delete: Delete configuration items
    -
    type
    string
    		type
    string

    Configuration type (required for list, get, put, delete operations). +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Configuration type (required for list, get, put, delete operations). Common types: flow, prompt, token-cost, parameter-type, interface-description

    -
    Array of objects

    Keys to retrieve (for get operation) or delete (for delete operation)

    -
    Array of objects

    Values to set/update (for put operation)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "config"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "version": 42,
    • "config": {
      }
    }

    Flow

    Array of objects

    Keys to retrieve (for get operation) or delete (for delete operation)

    +
    Array of objects

    Values to set/update (for put operation)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "config"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "version": 42,
    • "config": {
      }
    }

    Flow

    Flow lifecycle and blueprint management (global service)

    -

    Flow lifecycle and blueprint management

    Flow lifecycle and blueprint management

    Manage flow instances and blueprints.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage flow instances and blueprints.

    Important Distinction

    The flow service manages running flow instances. The config service (/api/v1/config) manages stored configuration.

    @@ -688,7 +692,7 @@ The config service (/api/v1/config) manages st

    delete-blueprint

    Delete a custom blueprint definition. Built-in blueprints cannot be deleted.

    -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "start-flow" "stop-flow" "list-flows" "get-flow" "list-blueprints" "get-blueprint" "put-blueprint" "delete-blueprint"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "start-flow" "stop-flow" "list-flows" "get-flow" "list-blueprints" "get-blueprint" "put-blueprint" "delete-blueprint"

    Flow operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Flow operation:

    • start-flow: Start a new flow instance from a blueprint
    • stop-flow: Stop a running flow instance
      • @@ -710,29 +714,29 @@ The config service (/api/v1/config) manages st
    • put-blueprint: Create/update blueprint definition
    • delete-blueprint: Delete blueprint definition
    -
    flow-id
    string

    Flow instance ID (required for start-flow, stop-flow, get-flow)

    -
    blueprint-name
    string

    Flow blueprint name (required for start-flow, get-blueprint, put-blueprint, delete-blueprint)

    -
    object

    Flow blueprint definition (required for put-blueprint)

    -
    description
    string

    Flow description (optional for start-flow)

    -
    object
    		flow-id
    string

    Flow instance ID (required for start-flow, stop-flow, get-flow)

    +
    blueprint-name
    string

    Flow blueprint name (required for start-flow, get-blueprint, put-blueprint, delete-blueprint)

    +
    object

    Flow blueprint definition (required for put-blueprint)

    +
    description
    string

    Flow description (optional for start-flow)

    +
    object

    Flow parameters (for start-flow). +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Flow parameters (for start-flow). All values are stored as strings, regardless of input type.

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "start-flow",
    • "flow-id": "my-flow",
    • "blueprint-name": "document-rag",
    • "description": "My document processing flow",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "flow-id": "my-flow"
    }

    Librarian

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "start-flow",
    • "flow-id": "my-flow",
    • "blueprint-name": "document-rag",
    • "description": "My document processing flow",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "flow-id": "my-flow"
    }

    Librarian

    Document library management (global service)

    -

    Document library management

    Document library management

    Manage document library: add, remove, list documents, and control processing.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage document library: add, remove, list documents, and control processing.

    Document Library

    The librarian service manages a persistent library of documents that can be:

      @@ -780,7 +784,7 @@ for processing and handled asynchronously.

      Stop ongoing library document processing.

      list-processing

      List current processing tasks and their status.

      -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "add-document" "remove-document" "list-documents" "start-processing" "stop-processing" "list-processing"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "add-document" "remove-document" "list-documents" "start-processing" "stop-processing" "list-processing"

    Library operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Library operation:

    • add-document: Add document to library
    • remove-document: Remove document from library
      • @@ -798,35 +802,35 @@ for processing and handled asynchronously.

    • stop-processing: Stop library processing
    • list-processing: List processing status
    -
    flow
    string

    Flow ID

    -
    collection
    string
    Default: "default"

    Collection identifier

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    document-id
    string

    Document identifier

    -
    processing-id
    string

    Processing task identifier

    -
    object (DocumentMetadata)

    Document metadata for library management

    -
    object (ProcessingMetadata)

    Processing metadata for library document processing

    -
    content
    string

    Document content (for add-document with inline content)

    -
    Array of objects

    Search criteria for filtering documents

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "add-document",
    • "flow": "my-flow",
    • "collection": "default",
    • "document-metadata": {}
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Knowledge

    		flow
    string

    Flow ID

    +
    collection
    string
    Default: "default"

    Collection identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    document-id
    string

    Document identifier

    +
    processing-id
    string

    Processing task identifier

    +
    object (DocumentMetadata)

    Document metadata for library management

    +
    object (ProcessingMetadata)

    Processing metadata for library document processing

    +
    content
    string

    Document content (for add-document with inline content)

    +
    Array of objects

    Search criteria for filtering documents

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "add-document",
    • "flow": "my-flow",
    • "collection": "default",
    • "document-metadata": {}
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Knowledge

    Knowledge graph core management (global service)

    -

    Knowledge graph core management

    Knowledge graph core management

    Manage knowledge graph cores - persistent storage of triples and embeddings.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage knowledge graph cores - persistent storage of triples and embeddings.

    Knowledge Cores

    Knowledge cores are the foundational storage units for:

      @@ -890,7 +894,7 @@ Removes data from flow instance but doesn't delete the core.

    • Multiple messages with triples or graph-embeddings
    • Final message with eos: true to signal completion
      • -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-kg-cores" "get-kg-core" "put-kg-core" "delete-kg-core" "load-kg-core" "unload-kg-core"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-kg-cores" "get-kg-core" "put-kg-core" "delete-kg-core" "load-kg-core" "unload-kg-core"

    Knowledge core operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Knowledge core operation:

    • list-kg-cores: List knowledge cores for user
    • get-kg-core: Get knowledge core by ID
      • @@ -908,29 +912,29 @@ Removes data from flow instance but doesn't delete the core.

    • load-kg-core: Load knowledge core into flow
    • unload-kg-core: Unload knowledge core from flow
    -
    user
    string
    Default: "trustgraph"

    User identifier (for list-kg-cores, put-kg-core, delete-kg-core)

    -
    id
    string

    Knowledge core ID (for get, put, delete, load, unload)

    -
    flow
    string

    Flow ID (for load-kg-core)

    -
    collection
    string
    Default: "default"

    Collection identifier (for load-kg-core)

    -
    object

    Triples to store (for put-kg-core)

    -
    object

    Graph embeddings to store (for put-kg-core)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-kg-cores",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "ids": [
      ]
    }

    Collection

    		user
    string
    Default: "trustgraph"

    User identifier (for list-kg-cores, put-kg-core, delete-kg-core)

    +
    id
    string

    Knowledge core ID (for get, put, delete, load, unload)

    +
    flow
    string

    Flow ID (for load-kg-core)

    +
    collection
    string
    Default: "default"

    Collection identifier (for load-kg-core)

    +
    object

    Triples to store (for put-kg-core)

    +
    object

    Graph embeddings to store (for put-kg-core)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-kg-cores",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "ids": [
      ]
    }

    Collection

    Collection metadata management (global service)

    -

    Collection metadata management

    Collection metadata management

    Manage collection metadata for organizing documents and knowledge.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage collection metadata for organizing documents and knowledge.

    Collections

    Collections are organizational units for grouping:

      @@ -982,45 +986,45 @@ If it exists, metadata is updated. Allows setting name, description, and tags.delete-collection

      Delete a collection by user and collection ID. This removes the metadata but typically does not delete the associated data (documents, knowledge cores).

      -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-collections" "update-collection" "delete-collection"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-collections" "update-collection" "delete-collection"

    Collection operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Collection operation:

    • list-collections: List collections for user
    • update-collection: Create or update collection metadata
    • delete-collection: Delete collection
    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string

    Collection identifier (for update, delete)

    -
    timestamp
    string <date-time>

    ISO timestamp

    -
    name
    string

    Human-readable collection name (for update)

    -
    description
    string

    Collection description (for update)

    -
    tags
    Array of strings

    Collection tags for organization (for update)

    -
    tag-filter
    Array of strings

    Filter collections by tags (for list)

    -
    limit
    integer
    Default: 0

    Maximum number of results (for list)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-collections",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2024-01-15T10:30:00Z",
    • "collections": [
      ]
    }

    Flow Services

    		user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string

    Collection identifier (for update, delete)

    +
    timestamp
    string <date-time>

    ISO timestamp

    +
    name
    string

    Human-readable collection name (for update)

    +
    description
    string

    Collection description (for update)

    +
    tags
    Array of strings

    Collection tags for organization (for update)

    +
    tag-filter
    Array of strings

    Filter collections by tags (for list)

    +
    limit
    integer
    Default: 0

    Maximum number of results (for list)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-collections",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2024-01-15T10:30:00Z",
    • "collections": [
      ]
    }

    Flow Services

    Services hosted within flow instances

    -

    Agent service - conversational AI with reasoning

    Agent service - conversational AI with reasoning

    AI agent that can understand questions, reason about them, and take actions.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    AI agent that can understand questions, reason about them, and take actions.

    Agent Overview

    The agent service provides a conversational AI that:

      @@ -1104,29 +1108,29 @@ Each step has: thought, action, arguments, observation.</p>

      Multi-turn Conversations

      Include history array with previous steps to maintain context. Each step has: thought, action, arguments, observation.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    User question or prompt for the agent

    -
    state
    string

    Agent state for continuation (optional, for multi-turn)

    -
    group
    Array of strings

    Group identifiers for collaborative agents (optional)

    -
    Array of objects

    Conversation history (optional, list of previous agent steps)

    -
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "What is the capital of France?",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "chunk-type": "thought",
    • "content": "I need to search for information about quantum computing",
    • "end-of-message": false,
    • "end-of-dialog": false
    }

    Document RAG - retrieve and generate from documents

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    User question or prompt for the agent

    +
    state
    string

    Agent state for continuation (optional, for multi-turn)

    +
    group
    Array of strings

    Group identifiers for collaborative agents (optional)

    +
    Array of objects

    Conversation history (optional, list of previous agent steps)

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "What is the capital of France?",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "chunk-type": "thought",
    • "content": "I need to search for information about quantum computing",
    • "end-of-message": false,
    • "end-of-dialog": false
    }

    Document RAG - retrieve and generate from documents

    Retrieval-Augmented Generation over document embeddings.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieval-Augmented Generation over document embeddings.

    Document RAG Overview

    Document RAG combines:

      @@ -1192,27 +1196,27 @@ Each step has: thought, action, arguments, observation.

    1. collection: Target specific document collection
    2. user: Multi-tenant isolation
      3. -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    -
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    -
    collection
    string
    Default: "default"

    Collection to search within

    -
    doc-limit
    integer [ 1 .. 100 ]
    Default: 20

    Maximum number of documents to retrieve

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What are the key findings in the research papers?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "The research papers present three key findings:\n1. Quantum entanglement exhibits non-local correlations\n2. Bell's inequality is violated in experimental tests\n3. Applications in quantum cryptography are promising\n",
    • "end-of-stream": false
    }

    Graph RAG - retrieve and generate from knowledge graph

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    collection
    string
    Default: "default"

    Collection to search within

    +
    doc-limit
    integer [ 1 .. 100 ]
    Default: 20

    Maximum number of documents to retrieve

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What are the key findings in the research papers?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "The research papers present three key findings:\n1. Quantum entanglement exhibits non-local correlations\n2. Bell's inequality is violated in experimental tests\n3. Applications in quantum cryptography are promising\n",
    • "end-of-stream": false
    }

    Graph RAG - retrieve and generate from knowledge graph

    Retrieval-Augmented Generation over knowledge graph.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieval-Augmented Generation over knowledge graph.

    Graph RAG Overview

    Graph RAG combines:

      @@ -1302,33 +1306,33 @@ Each step has: thought, action, arguments, observation.

    1. Multi-hop reasoning ("What's the path from A to B?")
    2. Structural analysis ("What are the main entities related to X?")
      3. -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    -
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    -
    collection
    string
    Default: "default"

    Collection to search within

    -
    entity-limit
    integer [ 1 .. 200 ]
    Default: 50

    Maximum number of entities to retrieve

    -
    triple-limit
    integer [ 1 .. 100 ]
    Default: 30

    Maximum number of triples to retrieve per entity

    -
    max-subgraph-size
    integer [ 10 .. 5000 ]
    Default: 1000

    Maximum total subgraph size (triples)

    -
    max-path-length
    integer [ 1 .. 5 ]
    Default: 2

    Maximum path length for graph traversal

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What connections exist between quantum physics and computer science?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Quantum physics and computer science intersect primarily through quantum computing.\nThe knowledge graph shows connections through:\n- Quantum algorithms (Shor's algorithm, Grover's algorithm)\n- Quantum information theory\n- Computational complexity theory\n",
    • "end-of-stream": false
    }

    Text completion - direct LLM generation

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    collection
    string
    Default: "default"

    Collection to search within

    +
    entity-limit
    integer [ 1 .. 200 ]
    Default: 50

    Maximum number of entities to retrieve

    +
    triple-limit
    integer [ 1 .. 100 ]
    Default: 30

    Maximum number of triples to retrieve per entity

    +
    max-subgraph-size
    integer [ 10 .. 5000 ]
    Default: 1000

    Maximum total subgraph size (triples)

    +
    max-path-length
    integer [ 1 .. 5 ]
    Default: 2

    Maximum path length for graph traversal

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What connections exist between quantum physics and computer science?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Quantum physics and computer science intersect primarily through quantum computing.\nThe knowledge graph shows connections through:\n- Quantum algorithms (Shor's algorithm, Grover's algorithm)\n- Quantum information theory\n- Computational complexity theory\n",
    • "end-of-stream": false
    }

    Text completion - direct LLM generation

    Direct text completion using LLM without retrieval augmentation.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Direct text completion using LLM without retrieval augmentation.

    Text Completion Overview

    Pure LLM generation for:

      @@ -1422,23 +1426,23 @@ Each step has: thought, action, arguments, observation.

    • Want to leverage knowledge graph relationships
    • Require citations or provenance
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    system
    required
    string

    System prompt that sets behavior and context for the LLM

    -
    prompt
    required
    string

    User prompt or question

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "system": "You are a helpful assistant that provides concise answers.",
    • "prompt": "Explain the concept of recursion in programming."
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Recursion is a programming technique where a function calls itself\nto solve a problem by breaking it down into smaller, similar subproblems.\nEach recursive call works on a simpler version until reaching a base case.\n",
    • "in-token": 45,
    • "out-token": 128,
    • "model": "gpt-4",
    • "end-of-stream": false
    }

    Prompt service - template-based generation

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    system
    required
    string

    System prompt that sets behavior and context for the LLM

    +
    prompt
    required
    string

    User prompt or question

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "system": "You are a helpful assistant that provides concise answers.",
    • "prompt": "Explain the concept of recursion in programming."
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Recursion is a programming technique where a function calls itself\nto solve a problem by breaking it down into smaller, similar subproblems.\nEach recursive call works on a simpler version until reaching a base case.\n",
    • "in-token": 45,
    • "out-token": 128,
    • "model": "gpt-4",
    • "end-of-stream": false
    }

    Prompt service - template-based generation

    Execute stored prompt templates with variable substitution.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Execute stored prompt templates with variable substitution.

    Prompt Service Overview

    The prompt service enables:

      @@ -1556,25 +1560,25 @@ Each step has: thought, action, arguments, observation.

    • Data transformation
    • Any repeatable LLM task with consistent prompting
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    id
    required
    string

    Prompt template ID (stored in config)

    -
    object

    Template variables as key-value pairs (values are JSON strings)

    -
    object

    Alternative to terms - variables as native JSON values (auto-converted)

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "summarize-document",
    • "terms": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "This document provides an overview of quantum computing fundamentals and cryptographic applications.",
    • "end-of-stream": false
    }

    Embeddings - text to vector conversion

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    id
    required
    string

    Prompt template ID (stored in config)

    +
    object

    Template variables as key-value pairs (values are JSON strings)

    +
    object

    Alternative to terms - variables as native JSON values (auto-converted)

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "summarize-document",
    • "terms": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "This document provides an overview of quantum computing fundamentals and cryptographic applications.",
    • "end-of-stream": false
    }

    Embeddings - text to vector conversion

    Convert text to embedding vectors for semantic similarity search.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Convert text to embedding vectors for semantic similarity search.

    Embeddings Overview

    Embeddings transform text into dense vector representations that:

      @@ -1630,19 +1634,19 @@ For bulk operations, use document-load or text-load services.</p>

      Single Request

      Unlike batch embedding APIs, this endpoint processes one text at a time. For bulk operations, use document-load or text-load services.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    text
    required
    string

    Text to convert to embedding vector

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "Machine learning"
    }

    Response samples

    Content type
    application/json
    {
    • "vectors": [
      ]
    }

    MCP Tool - execute Model Context Protocol tools

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    text
    required
    string

    Text to convert to embedding vector

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "Machine learning"
    }

    Response samples

    Content type
    application/json
    {
    • "vectors": [
      ]
    }

    MCP Tool - execute Model Context Protocol tools

    Execute MCP (Model Context Protocol) tools for agent capabilities.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Execute MCP (Model Context Protocol) tools for agent capabilities.

    MCP Tool Overview

    MCP tools provide agent capabilities through standardized protocol:

      @@ -1734,21 +1738,21 @@ For bulk operations, use document-load or text-load services.

    • File operations: Read/write files
    • Code execution: Run scripts
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    name
    required
    string

    Tool name to execute

    -
    object

    Tool parameters (JSON object, auto-converted to string internally)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "search",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "The result is 309"
    }

    Triples query - pattern-based graph queries

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    name
    required
    string

    Tool name to execute

    +
    object

    Tool parameters (JSON object, auto-converted to string internally)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "search",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "The result is 309"
    }

    Triples query - pattern-based graph queries

    Query knowledge graph using subject-predicate-object patterns.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query knowledge graph using subject-predicate-object patterns.

    Triples Query Overview

    Query RDF triples with flexible pattern matching:

      @@ -1840,38 +1844,54 @@ For bulk operations, use document-load or text-load services.

    • More specific patterns = faster queries
    • Consider limit for large result sets
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    object (RdfValue)

    Subject filter (optional)

    -
    object (RdfValue)

    Predicate filter (optional)

    -
    object (RdfValue)

    Object filter (optional)

    -
    limit
    integer [ 1 .. 100000 ]
    Default: 10000

    Maximum number of triples to return

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection to query

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {}

    Response samples

    Content type
    application/json
    {}

    Objects query - GraphQL over knowledge graph

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    object (RdfValue)

    Subject filter (optional)

    +
    object (RdfValue)

    Predicate filter (optional)

    +
    object (RdfValue)

    Object filter (optional)

    +
    limit
    integer [ 1 .. 100000 ]
    Default: 10000

    Maximum number of triples to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +
    g
    string

    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)
      • +
    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +
    batch-size
    integer [ 1 .. 1000 ]
    Default: 20

    Number of triples per streaming batch

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {}

    Response samples

    Content type
    application/json
    {}

    Rows query - GraphQL over structured data

    Query knowledge graph using GraphQL for object-oriented data access.

    -

    Objects Query Overview

    -

    GraphQL interface to knowledge graph:

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query structured data using GraphQL for row-oriented data access.

    +

    Rows Query Overview

    +

    GraphQL interface to structured data:

    • Schema-driven: Predefined types and relationships
    • Flexible queries: Request exactly what you need
    • Nested data: Traverse relationships in single query
    • Type-safe: Strong typing with introspection
    -

    Abstracts RDF triples into familiar object model.

    +

    Abstracts structured rows into familiar object model.

    GraphQL Benefits

    Compared to triples query:

      @@ -1956,27 +1976,27 @@ Use introspection query to discover schema.</p>

      Schema Definition

      Schema defines available types via config service. Use introspection query to discover schema.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    GraphQL query string

    -
    object

    GraphQL query variables

    -
    operation-name
    string

    Operation name (for multi-operation documents)

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection to query

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "{\n person(id: \"https://example.com/person/alice\") {\n name\n email\n }\n}\n",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "extensions": {
      }
    }

    NLP Query - natural language to structured query

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    GraphQL query string

    +
    object

    GraphQL query variables

    +
    operation-name
    string

    Operation name (for multi-operation documents)

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "{\n person(id: \"https://example.com/person/alice\") {\n name\n email\n }\n}\n",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "extensions": {
      }
    }

    NLP Query - natural language to structured query

    Convert natural language questions to structured GraphQL queries.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Convert natural language questions to structured GraphQL queries.

    NLP Query Overview

    Transforms user questions into executable GraphQL:

      @@ -2056,7 +2076,7 @@ Use introspection query to discover schema.

      Example workflow:

      1. User asks: "Who does Alice know?"
 2. NLP Query generates GraphQL
-3. Execute via /api/v1/flow/{flow}/service/objects
+3. Execute via /api/v1/flow/{flow}/service/rows
 4. Return results to user

      Schema Detection

      @@ -2080,26 +2100,26 @@ Use introspection query to discover schema.

    • Missing schema coverage
    • Complex query structure
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    -
    max-results
    integer [ 1 .. 10000 ]
    Default: 100

    Maximum results to return when query is executed

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "max-results": 50
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "graphql-query": "query GetConnections($person: ID!) {\n person(id: $person) {\n knows { name email }\n }\n}\n",
    • "variables": {},
    • "detected-schemas": [
      ],
    • "confidence": 0.92
    }

    Structured Query - question to results (all-in-one)

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    +
    max-results
    integer [ 1 .. 10000 ]
    Default: 100

    Maximum results to return when query is executed

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "max-results": 50
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "graphql-query": "query GetConnections($person: ID!) {\n person(id: $person) {\n knows { name email }\n }\n}\n",
    • "variables": {},
    • "detected-schemas": [
      ],
    • "confidence": 0.92
    }

    Structured Query - question to results (all-in-one)

    Ask natural language questions and get results directly.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Ask natural language questions and get results directly.

    Structured Query Overview

    Combines two operations in one call:

    1. NLP Query: Generate GraphQL from question
      2. -
    2. Objects Query: Execute generated query
      3. +
    3. Rows Query: Execute generated query
    4. Return Results: Direct answer data

    Simplest way to query knowledge graph with natural language.

    @@ -2170,7 +2190,7 @@ Use introspection query to discover schema.

  • Output: Query results (data)
  • Use when: Want simple, direct answers
    • -

    NLP Query + Objects Query (separate calls)

    +

    NLP Query + Rows Query (separate calls)

    • Step 1: Convert question → GraphQL
    • Step 2: Execute GraphQL → results
      • @@ -2214,23 +2234,23 @@ Use introspection query to discover schema.

    • Less control: Can't inspect/modify generated query
    • Simpler code: No need to handle intermediate steps
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection to query

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "errors": [ ]
    }

    Structured Diag - analyze structured data formats

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "errors": [ ]
    }

    Structured Diag - analyze structured data formats

    Analyze and understand structured data (CSV, JSON, XML).

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Analyze and understand structured data (CSV, JSON, XML).

    Structured Diag Overview

    Helps process unknown structured data:

      @@ -2352,39 +2372,39 @@ Use introspection query to discover schema.

    • Use descriptor to process full dataset
    • Load data via document-load or text-load
      • -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "detect-type" "generate-descriptor" "diagnose" "schema-selection"
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "detect-type" "generate-descriptor" "diagnose" "schema-selection"

    Diagnosis operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Diagnosis operation:

    • detect-type: Identify data format (CSV, JSON, XML)
    • generate-descriptor: Create schema descriptor for data
    • diagnose: Full analysis (detect + generate descriptor)
    • schema-selection: Find matching schemas for data
    -
    sample
    required
    string

    Data sample to analyze (text content)

    -
    type
    string
    Enum: "csv" "json" "xml"

    Data type (required for generate-descriptor)

    -
    schema-name
    string

    Target schema name for descriptor generation (optional)

    -
    object

    Format-specific options (e.g., CSV delimiter)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "sample": "name,age,email\nAlice,30,alice@example.com\nBob,25,bob@example.com\n"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "detected-type": "csv",
    • "confidence": 0.95
    }

    Graph Embeddings Query - find similar entities

    		sample
    required
    string

    Data sample to analyze (text content)

    +
    type
    string
    Enum: "csv" "json" "xml"

    Data type (required for generate-descriptor)

    +
    schema-name
    string

    Target schema name for descriptor generation (optional)

    +
    object

    Format-specific options (e.g., CSV delimiter)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "sample": "name,age,email\nAlice,30,alice@example.com\nBob,25,bob@example.com\n"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "detected-type": "csv",
    • "confidence": 0.95
    }

    Graph Embeddings Query - find similar entities

    Query graph embeddings to find similar entities by vector similarity.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query graph embeddings to find similar entities by vector similarity.

    Graph Embeddings Query Overview

    Find entities semantically similar to a query vector:

      @@ -2460,25 +2480,25 @@ Use introspection query to discover schema.

    • These are references to knowledge graph entities
    • Use with triples query to get entity details
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    -
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of entities to return

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection to search

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {}

    Document Embeddings Query - find similar text chunks

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of entities to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {}

    Document Embeddings Query - find similar text chunks

    Query document embeddings to find similar text chunks by vector similarity.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query document embeddings to find similar text chunks by vector similarity.

    Document Embeddings Query Overview

    Find document chunks semantically similar to a query vector:

      @@ -2570,25 +2590,113 @@ Use introspection query to discover schema.

    • No metadata (source, position, etc.)
    • Use for LLM context directly
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    -
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of document chunks to return

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection to search

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {
    • "chunks": [
      ]
    }

    Text Load - load text documents

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of document chunks to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {
    • "chunks": [
      ]
    }

    Row Embeddings Query - semantic search on structured data

    Query row embeddings to find similar rows by vector similarity on indexed fields. +Enables fuzzy/semantic matching on structured data.

    +

    Row Embeddings Query Overview

    +

    Find rows whose indexed field values are semantically similar to a query:

    +
      +
    • Input: Query embedding vector, schema name, optional index filter
      • +
    • Search: Compare against stored row index embeddings
      • +
    • Output: Matching rows with index values and similarity scores
      • +
    +

    Core component of semantic search on structured data.

    +

    Use Cases

    +
      +
    • Fuzzy name matching: Find customers by approximate name
      • +
    • Semantic field search: Find products by description similarity
      • +
    • Data deduplication: Identify potential duplicate records
      • +
    • Entity resolution: Match records across datasets
      • +
    +

    Process

    +
      +
    1. Obtain query embedding (via embeddings service)
      2. +
    2. Query stored row index embeddings for the specified schema
      3. +
    3. Calculate cosine similarity
      4. +
    4. Return top N most similar index entries
      5. +
    5. Use index values to retrieve full rows via GraphQL
      6. +
    +

    Response Format

    +

    Each match includes:

    +
      +
    • index_name: The indexed field(s) that matched
      • +
    • index_value: The actual values for those fields
      • +
    • text: The text that was embedded
      • +
    • score: Similarity score (higher = more similar)
      • +
    +
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    schema_name
    required
    string

    Schema name to search within

    +
    index_name
    string

    Optional index name to filter search to specific index

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of matches to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "schema_name": "customers",
    • "limit": 10,
    • "user": "alice",
    • "collection": "sales"
    }

    Response samples

    Content type
    application/json
    {
    • "matches": [
      ]
    }

    Text Load - load text documents

    Load text documents into processing pipeline for indexing and embedding.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Load text documents into processing pipeline for indexing and embedding.

    Text Load Overview

    Fire-and-forget document loading:

      @@ -2682,29 +2790,29 @@ encoded = base64
      Authorizations:
      bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    text
    required
    string <byte>

    Text content (base64 encoded)

    -
    id
    string

    Document identifier

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection for document

    -
    charset
    string
    Default: "utf-8"

    Text character encoding

    -
    Array of objects (Triple)

    Document metadata as RDF triples

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "VGhpcyBpcyB0aGUgZG9jdW1lbnQgdGV4dC4uLg==",
    • "id": "doc-123",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Document Load - load binary documents (PDF, etc.)

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    text
    required
    string <byte>

    Text content (base64 encoded)

    +
    id
    string

    Document identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection for document

    +
    charset
    string
    Default: "utf-8"

    Text character encoding

    +
    Array of objects (Triple)

    Document metadata as RDF triples

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "VGhpcyBpcyB0aGUgZG9jdW1lbnQgdGV4dC4uLg==",
    • "id": "doc-123",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Document Load - load binary documents (PDF, etc.)

    Load binary documents (PDF, Word, etc.) into processing pipeline.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Load binary documents (PDF, Word, etc.) into processing pipeline.

    Document Load Overview

    Fire-and-forget binary document loading:

      @@ -2814,29 +2922,61 @@ encoded = base64
      Authorizations:
      bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    data
    required
    string <byte>

    Document data (base64 encoded)

    -
    id
    string

    Document identifier

    -
    user
    string
    Default: "trustgraph"

    User identifier

    -
    collection
    string
    Default: "default"

    Collection for document

    -
    Array of objects (Triple)

    Document metadata as RDF triples

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqCjw8L1R5cGUvUGFnZXMvS2lkc1szIDAgUl0vQ291bnQgMT4+ZW5kb2JqCg==",
    • "id": "doc-789",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Import/Export

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    data
    required
    string <byte>

    Document data (base64 encoded)

    +
    id
    string

    Document identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection for document

    +
    Array of objects (Triple)

    Document metadata as RDF triples

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqCjw8L1R5cGUvUGFnZXMvS2lkc1szIDAgUl0vQ291bnQgMT4+ZW5kb2JqCg==",
    • "id": "doc-789",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Import/Export

    Bulk data import and export

    -

    Import Core - bulk import triples and embeddings

    Stream document content from library

    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)
      • +
    +
    Authorizations:
    bearerAuth
    query Parameters
    user
    required
    string
    Example: user=trustgraph

    User identifier

    +
    document-id
    required
    string
    Example: document-id=urn:trustgraph:doc:abc123

    Document IRI to retrieve

    +
    chunk-size
    integer
    Default: 1048576

    Chunk size in bytes (default 1MB)

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Import Core - bulk import triples and embeddings

    Import knowledge cores in bulk using streaming MessagePack format.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Import knowledge cores in bulk using streaming MessagePack format.

    Import Core Overview

    Bulk data import for knowledge graph:

      @@ -2944,21 +3084,21 @@ No response body - returns 202 Accepted.

    • Bulk loading: Initial knowledge base population
    • Replication: Copy knowledge cores
    -
    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to import

    -
    user
    required
    string
    Example: user=alice

    User identifier

    -
    Request Body schema: application/msgpack
    required
    string <binary>

    MessagePack stream of knowledge data

    -

    Responses

    Response samples

    Content type
    application/json
    { }

    Export Core - bulk export triples and embeddings

    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to import

    +
    user
    required
    string
    Example: user=alice

    User identifier

    +
    Request Body schema: application/msgpack
    required
    string <binary>

    MessagePack stream of knowledge data

    +

    Responses

    Response samples

    Content type
    application/json
    { }

    Export Core - bulk export triples and embeddings

    Export knowledge cores in bulk using streaming MessagePack format.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Export knowledge cores in bulk using streaming MessagePack format.

    Export Core Overview

    Bulk data export for knowledge graph:

      @@ -3082,21 +3222,21 @@ No response body - returns 202 Accepted.

    • Replication: Copy knowledge cores
    • Analysis: External processing
    -
    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to export

    -
    user
    required
    string
    Example: user=alice

    User identifier

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    WebSocket

    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to export

    +
    user
    required
    string
    Example: user=alice

    User identifier

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    WebSocket

    WebSocket interfaces

    -

    WebSocket - multiplexed service interface

    WebSocket - multiplexed service interface

    WebSocket interface providing multiplexed access to all TrustGraph services over a single persistent connection.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    WebSocket interface providing multiplexed access to all TrustGraph services over a single persistent connection.

    Overview

    The WebSocket API provides access to the same services as the REST API but with:

      @@ -3382,21 +3522,21 @@ See individual service documentation for detailed request/response formats.

    • True streaming: Bidirectional real-time communication
    • Efficient multiplexing: Concurrent operations without connection pooling
    -
    Authorizations:
    bearerAuth
    header Parameters
    Upgrade
    required
    string
    Value: "websocket"

    WebSocket upgrade header

    -
    Connection
    required
    string
    Value: "Upgrade"

    Connection upgrade header

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics

    Authorizations:
    bearerAuth
    header Parameters
    Upgrade
    required
    string
    Value: "websocket"

    WebSocket upgrade header

    +
    Connection
    required
    string
    Value: "Upgrade"

    Connection upgrade header

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics

    System metrics and monitoring

    -

    Metrics - Prometheus metrics endpoint

    Metrics - Prometheus metrics endpoint

    Proxy to Prometheus metrics for system monitoring.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Proxy to Prometheus metrics for system monitoring.

    Metrics Overview

    Exposes system metrics via Prometheus format:

      @@ -3464,29 +3604,29 @@ metric_name{labelPath Parameter

      The {path} parameter allows querying specific Prometheus endpoints or metrics if the backend Prometheus supports it.

      -
    Authorizations:
    bearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics - Prometheus metrics with path

    Proxy to Prometheus metrics with optional path parameter.

    -
    Authorizations:
    bearerAuth
    path Parameters
    path
    required
    string
    Example: query

    Path to specific metrics endpoint

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }
    +
    Authorizations:
    bearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics - Prometheus metrics with path

    Proxy to Prometheus metrics with optional path parameter.

    +
    Authorizations:
    bearerAuth
    path Parameters
    path
    required
    string
    Example: query

    Path to specific metrics endpoint

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }
    + const config = {"show":{"sidebar":true},"sidebar":{"showOperations":"byDefault"}}; + const appRoot = document.getElementById('root'); + AsyncApiStandalone.render( + { schema, config, }, appRoot + ); + \ No newline at end of file diff --git a/specs/api/components/common/RdfValue.yaml b/specs/api/components/common/RdfValue.yaml index 5ed7c992..033e6789 100644 --- a/specs/api/components/common/RdfValue.yaml +++ b/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 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..033e6789 100644 --- a/specs/api/components/schemas/common/RdfValue.yaml +++ b/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 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/build-docs.sh b/specs/build-docs.sh index 3425b339..5e156913 100755 --- a/specs/build-docs.sh +++ b/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" 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