> ## Documentation Index
> Fetch the complete documentation index at: https://docs.locusmedical.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphRAG retrieving (MKF 0.1.3, LangGraph 2-paths)

> Query maker → (semantic ‖ concept+graph) → context → frontier answer. No judge, no safety sweep. Traced in LangSmith.

`answer` is **Markdown**. Content negotiation on `Accept`:
- `application/json` (default) — full payload, answer + provenance;
- `text/markdown` — answer and provenance as one Markdown document;
- `text/html` — the same, rendered as a readable page.



## OpenAPI

````yaml /openapi.json post /v2/retrieve
openapi: 3.1.0
info:
  title: Locus API
  description: >-
    Locus knowledge layer — REST + MCP for clinical knowledge.


    Two categories of surface:

    - **query** (read) — `/v1/search`, `/v1/answer`, `/v1/context` (legacy Meili
    contract serving AlmaPro) and `/v2/retrieve` (knowledge-graph retrieval, MKF
    0.1.3).

    - **ops** — `/health`.


    The write plane (PDF → Neo4j graph: ingest, summarize, MKU extraction) is
    NOT exposed over HTTP — it is a batch pipeline driven by the `locus` CLI,
    which runs where the source PDFs are.
  version: 0.2.0
servers:
  - url: https://core.locusmedical.fr
    description: Production
security: []
paths:
  /v2/retrieve:
    post:
      tags:
        - query
      summary: GraphRAG retrieving (MKF 0.1.3, LangGraph 2-paths)
      description: >-
        Query maker → (semantic ‖ concept+graph) → context → frontier answer. No
        judge, no safety sweep. Traced in LangSmith.


        `answer` is **Markdown**. Content negotiation on `Accept`:

        - `application/json` (default) — full payload, answer + provenance;

        - `text/markdown` — answer and provenance as one Markdown document;

        - `text/html` — the same, rendered as a readable page.
      operationId: retrieve_endpoint_v2_retrieve_post
      parameters:
        - name: accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
            title: Accept
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveResponse'
            text/markdown:
              schema:
                type: string
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - lsk: []
components:
  schemas:
    RetrieveRequest:
      properties:
        query:
          type: string
          title: Query
        patient_ehr:
          anyOf:
            - type: string
            - type: 'null'
          title: Patient Ehr
          description: Dossier patient libre (EHR)
        concept_k:
          type: integer
          maximum: 20
          minimum: 1
          title: Concept K
          default: 5
        chunk_k:
          type: integer
          maximum: 50
          minimum: 1
          title: Chunk K
          default: 10
        mku_k:
          type: integer
          maximum: 50
          minimum: 1
          title: Mku K
          description: Top-k du chemin vectoriel MKU
          default: 12
        mku_weight:
          type: number
          maximum: 1
          minimum: 0
          title: Mku Weight
          description: >-
            Pondération hybride d'accès aux MKU : 0 = concepts seuls (un MKU
            n'est atteignable que par les termes de son propre verbatim), 1 =
            vecteurs seuls (sur l'embedding contextualisé doc+section), 0.5 =
            les deux.
          default: 0.5
        use_cross_refs:
          type: boolean
          title: Use Cross Refs
          description: >-
            Étendre le résultat aux MKU voisins par CROSS_REF (multi-hop, cap
            3).
          default: true
      type: object
      required:
        - query
      title: RetrieveRequest
    RetrieveResponse:
      properties:
        query:
          type: string
          title: Query
        reformulated:
          type: string
          title: Reformulated
          default: ''
        ehr_summary:
          type: string
          title: Ehr Summary
          default: ''
        answer:
          type: string
          title: Answer
          description: >-
            Réponse rédigée, en **Markdown** (titres, listes, tableaux,
            citations). En JSON les sauts de ligne sont échappés en `\n` : lire
            avec `jq -r '.answer'`, ou demander `Accept: text/markdown` pour
            recevoir le Markdown brut, ou `Accept: text/html` pour une page
            lisible.
          default: ''
        answer_format:
          type: string
          title: Answer Format
          description: Format de `answer`. Déclaré pour qu'un client sache le rendre.
          default: markdown
        mkus:
          items:
            $ref: '#/components/schemas/RetrieveMku'
          type: array
          title: Mkus
        chunks:
          items:
            $ref: '#/components/schemas/RetrieveChunk'
          type: array
          title: Chunks
        cross_refs:
          items:
            $ref: '#/components/schemas/RetrieveCrossRef'
          type: array
          title: Cross Refs
        concepts:
          items:
            $ref: '#/components/schemas/RetrieveConcept'
          type: array
          title: Concepts
      type: object
      required:
        - query
      title: RetrieveResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetrieveMku:
      properties:
        id:
          type: string
          title: Id
        verbatim:
          type: string
          title: Verbatim
        criteria:
          type: string
          title: Criteria
          default: ''
        directive:
          type: string
          title: Directive
          default: ''
        mku_class:
          anyOf:
            - type: string
            - type: 'null'
          title: Mku Class
        population:
          items:
            type: string
          type: array
          title: Population
        doc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Id
        doc_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Title
        section_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Section Title
        score:
          type: number
          title: Score
          default: 0
        via:
          type: string
          title: Via
          description: concept | vector | concept+vector | cross_ref
          default: ''
      type: object
      required:
        - id
        - verbatim
      title: RetrieveMku
    RetrieveChunk:
      properties:
        id:
          type: string
          title: Id
        text:
          type: string
          title: Text
        score:
          type: number
          title: Score
        doc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Id
        doc_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Title
        section_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Section Title
      type: object
      required:
        - id
        - text
        - score
      title: RetrieveChunk
    RetrieveCrossRef:
      properties:
        id1:
          type: string
          title: Id1
        id2:
          type: string
          title: Id2
        polarity:
          type: string
          title: Polarity
      type: object
      required:
        - id1
        - id2
        - polarity
      title: RetrieveCrossRef
    RetrieveConcept:
      properties:
        id:
          type: string
          title: Id
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
      type: object
      required:
        - id
      title: RetrieveConcept
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    lsk:
      type: http
      description: Locus API key — paste the raw `lsk_…` value (no 'Bearer ' prefix).
      scheme: bearer

````