trustgraph/specs/api/paths/flow/graph-rag.yaml

post:
  tags:
    - Flow Services
  summary: Graph RAG - retrieve and generate from knowledge graph
  description: |
    Retrieval-Augmented Generation over knowledge graph.

    ## Graph RAG Overview

    Graph RAG combines:
    1. **Retrieval**: Find relevant entities and subgraph from knowledge graph
    2. **Generation**: Use LLM to reason over graph structure and generate answer

    This provides graph-aware answers that leverage relationships and structure.

    ## Query Process

    1. Identify relevant entities from query (using embeddings)
    2. Retrieve connected subgraph around entities
    3. Optionally traverse paths up to max-path-length hops
    4. Limit subgraph size to stay within context window
    5. Pass query + graph structure to LLM
    6. Generate answer incorporating graph relationships

    ## Streaming

    Enable `streaming: true` to receive the answer as it's generated:
    - Multiple `chunk` messages with `response` content
    - `explain` messages with inline provenance triples (`explain_triples`)
    - Final message with `end-of-stream: true`
    - Session ends with `end_of_session: true`

    Explain events carry `explain_id`, `explain_graph`, and `explain_triples`
    inline in the stream, so no follow-up knowledge graph query is needed.

    Without streaming, returns complete answer in single response.

    ## Parameters

    Control retrieval scope with multiple knobs:
    - **entity-limit**: How many starting entities to find (1-200, default 50)
    - **triple-limit**: Triples per entity (1-100, default 30)
    - **max-subgraph-size**: Total subgraph cap (10-5000, default 1000)
    - **max-path-length**: Graph traversal depth (1-5, default 2)

    Higher limits = more context but:
    - Slower retrieval
    - Larger context for LLM
    - May hit context window limits

    ## Use Cases

    Best for queries requiring:
    - Relationship understanding ("How are X and Y connected?")
    - Multi-hop reasoning ("What's the path from A to B?")
    - Structural analysis ("What are the main entities related to X?")

  operationId: graphRagService
  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/rag/GraphRagRequest.yaml'
        examples:
          basicQuery:
            summary: Basic graph query
            value:
              query: What connections exist between quantum physics and computer science?
              collection: research
          streamingQuery:
            summary: Streaming query with custom limits
            value:
              query: Trace the historical development of AI from Turing to modern LLMs
              collection: research
              entity-limit: 40
              triple-limit: 25
              max-subgraph-size: 800
              max-path-length: 3
              streaming: true
          focusedQuery:
            summary: Focused query with tight limits
            value:
              query: What is the immediate relationship between entity A and B?
              entity-limit: 10
              triple-limit: 15
              max-subgraph-size: 200
              max-path-length: 1
  responses:
    '200':
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '../../components/schemas/rag/GraphRagResponse.yaml'
          examples:
            completeResponse:
              summary: Complete non-streaming response
              value:
                response: |
                  Quantum physics and computer science intersect primarily through quantum computing.
                  The knowledge graph shows connections through:
                  - Quantum algorithms (Shor's algorithm, Grover's algorithm)
                  - Quantum information theory
                  - Computational complexity theory
                end-of-stream: false
            streamingChunk:
              summary: Streaming response chunk
              value:
                response: "Quantum physics and computer science intersect"
                end-of-stream: false
            explainEvent:
              summary: Explain event with inline provenance triples
              value:
                message_type: explain
                explain_id: urn:trustgraph:question:abc123
                explain_graph: urn:graph:retrieval
                explain_triples:
                  - s: {t: i, i: "urn:trustgraph:question:abc123"}
                    p: {t: i, i: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"}
                    o: {t: i, i: "https://trustgraph.ai/ns/GraphRagQuestion"}
                  - s: {t: i, i: "urn:trustgraph:question:abc123"}
                    p: {t: i, i: "https://trustgraph.ai/ns/query"}
                    o: {t: l, v: "What connections exist between quantum physics and computer science?"}
                end_of_stream: false
                end_of_session: false
            streamingComplete:
              summary: Streaming complete marker
              value:
                response: ""
                end-of-stream: true
    '401':
      $ref: '../../components/responses/Unauthorized.yaml'
    '500':
      $ref: '../../components/responses/Error.yaml'