Merge 2.0 to master (#651)

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

@@ -0,0 +1,39 @@
+type: object
+description: |
+  Row embeddings query request - find similar rows by vector similarity on indexed fields.
+  Enables semantic/fuzzy matching on structured data.
+required:
+  - vectors
+  - schema_name
+properties:
+  vectors:
+    type: array
+    description: Query embedding vector
+    items:
+      type: number
+    example: [0.023, -0.142, 0.089, 0.234, -0.067, 0.156]
+  schema_name:
+    type: string
+    description: Schema name to search within
+    example: customers
+  index_name:
+    type: string
+    description: Optional index name to filter search to specific index
+    example: full_name
+  limit:
+    type: integer
+    description: Maximum number of matches to return
+    default: 10
+    minimum: 1
+    maximum: 1000
+    example: 20
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to search
+    default: default
+    example: sales

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

@@ -0,0 +1,53 @@
+type: object
+description: Row embeddings query response with matching row index information
+properties:
+  error:
+    type: object
+    description: Error information if query failed
+    properties:
+      type:
+        type: string
+        description: Error type identifier
+        example: row-embeddings-query-error
+      message:
+        type: string
+        description: Human-readable error message
+        example: Schema not found
+  matches:
+    type: array
+    description: List of matching row index entries with similarity scores
+    items:
+      type: object
+      properties:
+        index_name:
+          type: string
+          description: Name of the indexed field(s)
+          example: full_name
+        index_value:
+          type: array
+          description: Values of the indexed fields for this row
+          items:
+            type: string
+          example: ["John", "Smith"]
+        text:
+          type: string
+          description: The text that was embedded for this index entry
+          example: "John Smith"
+        score:
+          type: number
+          description: Similarity score (higher is more similar)
+          example: 0.89
+example:
+  matches:
+    - index_name: full_name
+      index_value: ["John", "Smith"]
+      text: "John Smith"
+      score: 0.95
+    - index_name: full_name
+      index_value: ["Jon", "Smythe"]
+      text: "Jon Smythe"
+      score: 0.82
+    - index_name: full_name
+      index_value: ["Jonathan", "Schmidt"]
+      text: "Jonathan Schmidt"
+      score: 0.76

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

@@ -1,6 +1,6 @@
 type: object
 description: |
-  Objects query request - GraphQL query over knowledge graph.
+  Rows query request - GraphQL query over structured data.
 required:
   - query
 properties:

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

@@ -1,5 +1,5 @@
 type: object
-description: Objects query response (GraphQL format)
+description: Rows query response (GraphQL format)
 properties:
   data:
     description: GraphQL response data (JSON object or null)

specs/api/openapi.yaml

@@ -121,8 +121,8 @@ paths:
     $ref: './paths/flow/mcp-tool.yaml'
   /api/v1/flow/{flow}/service/triples:
     $ref: './paths/flow/triples.yaml'
-  /api/v1/flow/{flow}/service/objects:
-    $ref: './paths/flow/objects.yaml'
+  /api/v1/flow/{flow}/service/rows:
+    $ref: './paths/flow/rows.yaml'
   /api/v1/flow/{flow}/service/nlp-query:
     $ref: './paths/flow/nlp-query.yaml'
   /api/v1/flow/{flow}/service/structured-query:
@@ -133,6 +133,8 @@ paths:
     $ref: './paths/flow/graph-embeddings.yaml'
   /api/v1/flow/{flow}/service/document-embeddings:
     $ref: './paths/flow/document-embeddings.yaml'
+  /api/v1/flow/{flow}/service/row-embeddings:
+    $ref: './paths/flow/row-embeddings.yaml'
   /api/v1/flow/{flow}/service/text-load:
     $ref: './paths/flow/text-load.yaml'
   /api/v1/flow/{flow}/service/document-load:

specs/api/paths/flow/nlp-query.yaml

@@ -34,7 +34,7 @@ post:
     ```
     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
     ```
 

specs/api/paths/flow/row-embeddings.yaml

@@ -0,0 +1,101 @@
+post:
+  tags:
+    - Flow Services
+  summary: Row Embeddings Query - semantic search on structured data
+  description: |
+    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. Query stored row index embeddings for the specified schema
+    3. Calculate cosine similarity
+    4. Return top N most similar index entries
+    5. Use index values to retrieve full rows via GraphQL
+
+    ## 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)
+
+  operationId: rowEmbeddingsQueryService
+  security:
+    - bearerAuth: []
+  parameters:
+    - name: flow
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Flow instance ID
+      example: my-flow
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../../components/schemas/embeddings-query/RowEmbeddingsQueryRequest.yaml'
+        examples:
+          basicQuery:
+            summary: Find similar customer names
+            value:
+              vectors: [0.023, -0.142, 0.089, 0.234, -0.067, 0.156, 0.201, -0.178]
+              schema_name: customers
+              limit: 10
+              user: alice
+              collection: sales
+          filteredQuery:
+            summary: Search specific index
+            value:
+              vectors: [0.1, -0.2, 0.3, -0.4, 0.5]
+              schema_name: products
+              index_name: description
+              limit: 20
+  responses:
+    '200':
+      description: Successful response
+      content:
+        application/json:
+          schema:
+            $ref: '../../components/schemas/embeddings-query/RowEmbeddingsQueryResponse.yaml'
+          examples:
+            similarRows:
+              summary: Similar rows found
+              value:
+                matches:
+                  - index_name: full_name
+                    index_value: ["John", "Smith"]
+                    text: "John Smith"
+                    score: 0.95
+                  - index_name: full_name
+                    index_value: ["Jon", "Smythe"]
+                    text: "Jon Smythe"
+                    score: 0.82
+                  - index_name: full_name
+                    index_value: ["Jonathan", "Schmidt"]
+                    text: "Jonathan Schmidt"
+                    score: 0.76
+    '401':
+      $ref: '../../components/responses/Unauthorized.yaml'
+    '500':
+      $ref: '../../components/responses/Error.yaml'

specs/api/paths/flow/rows.yaml

@@ -1,19 +1,19 @@
 post:
   tags:
     - Flow Services
-  summary: Objects query - GraphQL over knowledge graph
+  summary: Rows query - GraphQL over structured data
   description: |
-    Query knowledge graph using GraphQL for object-oriented data access.
+    Query structured data using GraphQL for row-oriented data access.
 
-    ## Objects Query Overview
+    ## Rows Query Overview
 
-    GraphQL interface to knowledge graph:
+    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
 
@@ -61,7 +61,7 @@ post:
     Schema defines available types via config service.
     Use introspection query to discover schema.
 
-  operationId: objectsQueryService
+  operationId: rowsQueryService
   security:
     - bearerAuth: []
   parameters:
@@ -77,7 +77,7 @@ post:
     content:
       application/json:
         schema:
-          $ref: '../../components/schemas/query/ObjectsQueryRequest.yaml'
+          $ref: '../../components/schemas/query/RowsQueryRequest.yaml'
         examples:
           simpleQuery:
             summary: Simple query
@@ -129,7 +129,7 @@ post:
       content:
         application/json:
           schema:
-            $ref: '../../components/schemas/query/ObjectsQueryResponse.yaml'
+            $ref: '../../components/schemas/query/RowsQueryResponse.yaml'
           examples:
             successfulQuery:
               summary: Successful query

specs/api/paths/flow/structured-query.yaml

@@ -9,7 +9,7 @@ post:
 
     Combines two operations in one call:
     1. **NLP Query**: Generate GraphQL from question
-    2. **Objects Query**: Execute generated query
+    2. **Rows Query**: Execute generated query
     3. **Return Results**: Direct answer data
 
     Simplest way to query knowledge graph with natural language.
@@ -21,7 +21,7 @@ post:
     - **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
     - **Use when**: Need to inspect/modify query before execution