{"openapi":"3.1.0","info":{"title":"Alessandro Berti — GraphRAG CV API","version":"1.0.0","description":"Graph Retrieval-Augmented Generation API over Alessandro Berti's academic CV knowledge graph (Neo4j). Performs fulltext search and returns matching entities together with their N-hop neighbourhood."},"servers":[{"url":"https://aleberti.com"}],"paths":{"/api/graphrag":{"get":{"operationId":"graphragGet","summary":"Query the CV knowledge graph (GET)","parameters":[{"name":"q","in":"query","required":true,"description":"Natural language or keyword query (e.g. 'quantum state preparation', 'Alessandro Berti', 'Fermilab').","schema":{"type":"string"}},{"name":"hops","in":"query","required":false,"description":"Graph traversal depth (1–4, default 1). Higher values return richer but larger subgraphs.","schema":{"type":"integer","minimum":1,"maximum":4,"default":1}},{"name":"type","in":"query","required":false,"description":"Restrict results to a specific entity type. Valid values: Person | Publication | Software | Degree | Certification | Award | Position | Institution | Topic | ResearchProject | Event | TrainingActivity | ResearchGroup | Venue | OrganizationMembership | OtherExperience | ReviewActivity | Patent | Presentation.","schema":{"type":"string"}}],"responses":{"200":{"description":"GraphRAG result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphRAGResponse"}}}},"400":{"description":"Missing or invalid query"},"500":{"description":"Internal server error"}}},"post":{"operationId":"graphragPost","summary":"Query the CV knowledge graph (POST)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphRAGRequest"}}}},"responses":{"200":{"description":"GraphRAG result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GraphRAGResponse"}}}},"400":{"description":"Missing or invalid query"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"GraphRAGRequest":{"type":"object","required":["q"],"properties":{"q":{"type":"string","description":"Natural language or keyword query."},"hops":{"type":"integer","minimum":1,"maximum":4,"default":1},"type":{"type":"string","description":"Optional entity type filter.","enum":["Person","Publication","Software","Degree","Certification","Award","Position","Institution","Topic","ResearchProject","Event","TrainingActivity","ResearchGroup","Venue","OrganizationMembership","OtherExperience","ReviewActivity","Patent","Presentation"]}}},"ContextHop":{"type":"object","properties":{"distance":{"type":"integer","description":"Edge distance from the seed node."},"path_rels":{"type":"array","items":{"type":"string"},"description":"Ordered list of relationship types along the path."},"neighborType":{"type":"string","description":"Entity type of the neighbour node."},"neighbor":{"type":"object","additionalProperties":true,"description":"All properties of the neighbour node."}}},"GraphRAGItem":{"type":"object","properties":{"type":{"type":"string","description":"Entity type of the matched node."},"score":{"type":"number","description":"Fulltext relevance score."},"summary":{"type":"string","description":"Human-readable summary extracted from the entity (biography, description, title, or name — truncated to 400 chars)."},"entity":{"type":"object","additionalProperties":true,"description":"All properties of the matched node."},"context":{"type":"array","items":{"$ref":"#/components/schemas/ContextHop"},"description":"Deduplicated N-hop neighbourhood (one entry per unique neighbour, shortest path kept)."}}},"GraphRAGResponse":{"type":"object","properties":{"query":{"type":"string"},"hops":{"type":"integer"},"type":{"type":"string","nullable":true},"search_terms":{"type":"string","description":"Keywords sent to the fulltext index."},"total":{"type":"integer","description":"Number of matched seed nodes."},"graph_context":{"type":"array","items":{"$ref":"#/components/schemas/GraphRAGItem"}}}}}}}