Merge 2.0 to master (#651)

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