> ## 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.

# Recall-first MKU retrieval over the knowledge graph (MKF v0.1.2)

> Retrieves adjudicated Medical Knowledge Units (MKU) for a query + patient EHR from the curated Neo4j graph: patient/query concept mapping, R1∪R2 retrieval, out-of-band safety sweep, LLM sufficiency judge, raw-chunk fallback, deterministic parent-doc enrichment, CROSS_REF reconciliation, and agent adjudication. Provenance-first and trace-rich (the eval surface).



## OpenAPI

````yaml /openapi.json post /v2/context
openapi: 3.1.0
info:
  title: Locus API
  description: Locus knowledge layer — REST + MCP for clinical knowledge.
  version: 0.1.0
servers:
  - url: https://core.locusmedical.fr
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /v2/context:
    post:
      tags:
        - v2
      summary: Recall-first MKU retrieval over the knowledge graph (MKF v0.1.2)
      description: >-
        Retrieves adjudicated Medical Knowledge Units (MKU) for a query +
        patient EHR from the curated Neo4j graph: patient/query concept mapping,
        R1∪R2 retrieval, out-of-band safety sweep, LLM sufficiency judge,
        raw-chunk fallback, deterministic parent-doc enrichment, CROSS_REF
        reconciliation, and agent adjudication. Provenance-first and trace-rich
        (the eval surface).
      operationId: mku_context_endpoint_v2_context_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MkuContextRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MkuContextResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - lsk: []
components:
  schemas:
    MkuContextRequest:
      properties:
        query:
          type: string
          minLength: 1
          title: Query
          description: Free-text clinical question in French.
          examples:
            - Quelle antibiothérapie pour cette infection urinaire ?
        patient_ehr:
          $ref: '#/components/schemas/PatientContext'
          description: >-
            Coarse patient EHR. Safety-signal facts (treatments, allergies,
            terrain) are mapped to concepts eagerly; used only in intersection
            with the query — never alone, except the safety sweep.
        opts:
          $ref: '#/components/schemas/ContextOpts'
      type: object
      required:
        - query
        - patient_ehr
      title: MkuContextRequest
    MkuContextResponse:
      properties:
        query:
          type: string
          title: Query
        answer:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer
          description: >-
            Agent adjudication (optional). Absent when the agent is disabled —
            the structured retrieval below is the primary payload.
        mkus:
          items:
            $ref: '#/components/schemas/MkuResult'
          type: array
          title: Mkus
          description: Retained MKUs, ranked, with deterministic provenance.
        safety_items:
          items:
            type: string
          type: array
          title: Safety Items
          description: Ids of safety-relevant MKUs — addressed explicitly, never dropped.
        conflicts:
          items:
            $ref: '#/components/schemas/MkuConflict'
          type: array
          title: Conflicts
        cross_refs:
          items:
            $ref: '#/components/schemas/CrossRef'
          type: array
          title: Cross Refs
        fallback:
          items:
            $ref: '#/components/schemas/FallbackChunk'
          type: array
          title: Fallback
        trace:
          $ref: '#/components/schemas/ContextTrace'
        tokens_in:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens In
        tokens_out:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens Out
      type: object
      required:
        - query
        - mkus
        - trace
      title: MkuContextResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PatientContext:
      properties:
        sex:
          anyOf:
            - type: string
            - type: 'null'
          title: Sex
          description: Patient sex.
          examples:
            - F
        age:
          anyOf:
            - type: integer
            - type: 'null'
          title: Age
          description: Age in years.
          examples:
            - 34
        history:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: History
          description: Relevant medical history.
          examples:
            - - diabète type 2
        active_problems:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Active Problems
          description: Current active problems.
          examples:
            - - grossesse 24 SA
        allergies:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allergies
          description: Known allergies.
          examples:
            - - pénicilline
        current_treatments:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Current Treatments
          description: Current treatments.
          examples:
            - - warfarine
      type: object
      title: PatientContext
      description: Coarse patient profile. Every field optional; send what is known.
    ContextOpts:
      properties:
        include_unreviewed:
          type: boolean
          title: Include Unreviewed
          description: >-
            Lift the review gate (tag `unreviewed`). REFUSED unless the
            deployment opted in (CTX_ALLOW_UNREVIEWED=true or ENV=test).
          default: false
        mode:
          type: string
          title: Mode
          description: >-
            `full` = complete pipeline. `fallback_only` = bypass MKU retrieval,
            measure the raw chunk layer alone (safety sweep still runs).
          default: full
          examples:
            - full
        concept_sim_topk:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Concept Sim Topk
          description: query→concept vector resolution breadth. null = server default.
        mku_sim_topk:
          anyOf:
            - type: integer
              maximum: 200
              minimum: 1
            - type: 'null'
          title: Mku Sim Topk
          description: R1 vector top-k over mku_embeddings. null = server default.
        fallback_chunk_topk:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Fallback Chunk Topk
          description: step-5 cosine over raw chunks. null = server default.
        intersection_multihop_depth:
          anyOf:
            - type: integer
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Intersection Multihop Depth
          description: R2 TRIGGERS hop depth (0 = direct only). null = server default.
        judge_sufficiency_cutoff:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Judge Sufficiency Cutoff
          description: gate on the judge's 0..1 score. null = server default.
        judge_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Judge Enabled
          description: >-
            false → bypass the LLM judge (deterministic proxy score). null =
            server default.
        agent_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Agent Enabled
          description: >-
            false → skip agent adjudication (no `answer`). null = server
            default.
        w_cosine:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: W Cosine
          description: 'ranking weight: R1 vector cosine. null = server default.'
        w_overlap:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: W Overlap
          description: 'ranking weight: per query-concept overlap. null = server default.'
        w_intersection:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: W Intersection
          description: 'ranking weight: R2 intersection boost. null = server default.'
      type: object
      title: ContextOpts
    MkuResult:
      properties:
        id:
          type: string
          title: Id
        verbatim:
          type: string
          title: Verbatim
          description: EXACT source text — the ONLY citable unit.
        criteria:
          type: string
          title: Criteria
          description: SI — antecedent (à qui / quand).
        directive:
          type: string
          title: Directive
          description: ALORS — consequent (quoi faire / conclure).
        safety_critical:
          type: boolean
          title: Safety Critical
          default: false
        review:
          type: boolean
          title: Review
          default: false
        evidence_grade:
          anyOf:
            - type: string
            - type: 'null'
          title: Evidence Grade
        strength:
          anyOf:
            - type: string
            - type: 'null'
          title: Strength
        score:
          type: number
          title: Score
          description: Ranking score (higher = stronger).
        paths:
          items:
            type: string
          type: array
          title: Paths
          description: >-
            Retrieval paths that surfaced this MKU (R1_concept, R1_vector, R2,
            safety).
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: e.g. safety-relevant, unreviewed.
        provenance:
          $ref: '#/components/schemas/Provenance'
      type: object
      required:
        - id
        - verbatim
        - criteria
        - directive
        - score
      title: MkuResult
    MkuConflict:
      properties:
        description:
          type: string
          title: Description
        patient_factor:
          anyOf:
            - type: string
            - type: 'null'
          title: Patient Factor
        mku_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mku Id
          description: The MKU this conflict relates to, if any.
      type: object
      required:
        - description
      title: MkuConflict
    CrossRef:
      properties:
        from_id:
          type: string
          title: From Id
        to_id:
          type: string
          title: To Id
        stance:
          type: string
          title: Stance
          description: AGREE | DISAGREE | PARTIAL (lineage excluded).
      type: object
      required:
        - from_id
        - to_id
        - stance
      title: CrossRef
    FallbackChunk:
      properties:
        chunk_id:
          type: string
          title: Chunk Id
        text:
          type: string
          title: Text
        score:
          type: number
          title: Score
        doc_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Title
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
        section_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Section Summary
        doc_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Summary
        tag:
          type: string
          title: Tag
          default: non_adjudiqué
      type: object
      required:
        - chunk_id
        - text
        - score
      title: FallbackChunk
      description: Raw-substrate chunk (step 5). Always tagged `non_adjudiqué`.
    ContextTrace:
      properties:
        mode:
          type: string
          title: Mode
        include_unreviewed:
          type: boolean
          title: Include Unreviewed
        paths_activated:
          items:
            type: string
          type: array
          title: Paths Activated
          description: 'Which paths fired: R1_concept, R1_vector, R2, safety, fallback.'
        judge_score:
          type: number
          title: Judge Score
          description: Sufficiency score — ALWAYS logged.
        judge_sufficient:
          type: boolean
          title: Judge Sufficient
        judge_cutoff:
          type: number
          title: Judge Cutoff
        judge_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Judge Rationale
        judge_skipped:
          type: boolean
          title: Judge Skipped
          default: false
        counts:
          additionalProperties:
            type: integer
          type: object
          title: Counts
          description: Candidate counts per path (r1, r2, safety, union, fallback…).
        query_concepts:
          items:
            $ref: '#/components/schemas/ConceptRef'
          type: array
          title: Query Concepts
        patient_concepts:
          items:
            $ref: '#/components/schemas/ConceptRef'
          type: array
          title: Patient Concepts
        tags:
          items:
            type: string
          type: array
          title: Tags
        config:
          additionalProperties: true
          type: object
          title: Config
          description: The knobs actually used this request.
        enrichment_degraded:
          type: boolean
          title: Enrichment Degraded
          default: false
      type: object
      required:
        - mode
        - include_unreviewed
        - paths_activated
        - judge_score
        - judge_sufficient
        - judge_cutoff
        - counts
        - config
      title: ContextTrace
      description: Per-request eval data (logging is mandatory — spec §Logging).
    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
    Provenance:
      properties:
        doc_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Id
        doc_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Title
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
          description: Deep link — provenance.
        reco_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Reco Id
        year:
          anyOf:
            - type: integer
            - type: 'null'
          title: Year
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
        source_org:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Org
        section_titles:
          items:
            type: string
          type: array
          title: Section Titles
        pages:
          items:
            type: string
          type: array
          title: Pages
        section_summaries:
          items:
            type: string
          type: array
          title: Section Summaries
          description: CONTEXT only — never cite as a source.
        doc_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Summary
          description: CONTEXT only — never cite as a source.
        degraded:
          type: boolean
          title: Degraded
          description: >-
            True when summaries were absent → enrichment fell back to verbatim
            only (non-blocking).
          default: false
      type: object
      title: Provenance
      description: Deterministic parent-doc join (FROM_CHUNK), never similarity (§6).
    ConceptRef:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
      type: object
      required:
        - id
        - label
      title: ConceptRef
  securitySchemes:
    lsk:
      type: http
      description: Locus API key — paste the raw `lsk_…` value (no 'Bearer ' prefix).
      scheme: bearer

````