Spaces:
Running
Running
| <html lang="en"> | |
| <head> | |
| <meta charset="UTF-8"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| <title>LogosKG Documentation | API Reference</title> | |
| <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600&family=IBM+Plex+Mono:wght@400;500;600&display=swap" | |
| rel="stylesheet"> | |
| <style> | |
| :root { | |
| --primary: #2563eb; | |
| --primary-dark: #1e40af; | |
| --primary-light: #eff6ff; | |
| --accent: #059669; | |
| --bg-main: #ffffff; | |
| --bg-sidebar: #f8fafc; | |
| --bg-surface: #f1f5f9; | |
| --text-main: #0f172a; | |
| --text-body: #334155; | |
| --text-muted: #64748b; | |
| --border: #e2e8f0; | |
| --code-bg: #0f172a; | |
| --code-text: #e2e8f0; | |
| --code-kw: #c678dd; | |
| --code-str: #98c379; | |
| --code-func: #61afef; | |
| --code-type: #e5c07b; | |
| --code-com: #64748b; | |
| --header-h: 64px; | |
| --sidebar-w: 300px; | |
| } | |
| * { | |
| margin: 0; | |
| padding: 0; | |
| box-sizing: border-box; | |
| } | |
| body { | |
| font-family: 'IBM Plex Sans', -apple-system, sans-serif; | |
| background: var(--bg-main); | |
| color: var(--text-body); | |
| line-height: 1.6; | |
| -webkit-font-smoothing: antialiased; | |
| } | |
| header { | |
| position: fixed; | |
| top: 0; | |
| width: 100%; | |
| height: var(--header-h); | |
| background: rgba(255, 255, 255, 0.95); | |
| backdrop-filter: blur(8px); | |
| border-bottom: 1px solid var(--border); | |
| z-index: 1000; | |
| display: flex; | |
| align-items: center; | |
| padding: 0 2rem; | |
| justify-content: space-between; | |
| } | |
| .logo-area { | |
| display: flex; | |
| align-items: center; | |
| gap: 1.5rem; | |
| } | |
| .logo { | |
| font-size: 1.25rem; | |
| font-weight: 600; | |
| color: var(--text-main); | |
| font-family: 'IBM Plex Mono', monospace; | |
| text-decoration: none; | |
| } | |
| .version-badge { | |
| background: var(--bg-surface); | |
| border: 1px solid var(--border); | |
| padding: 0.1rem 0.5rem; | |
| border-radius: 4px; | |
| font-size: 0.75rem; | |
| font-family: 'IBM Plex Mono', monospace; | |
| color: var(--text-muted); | |
| } | |
| .nav-links { | |
| display: flex; | |
| gap: 1.5rem; | |
| list-style: none; | |
| align-items: center; | |
| } | |
| .nav-links a { | |
| color: var(--text-muted); | |
| text-decoration: none; | |
| font-size: 0.9rem; | |
| font-weight: 500; | |
| transition: color 0.2s; | |
| } | |
| .nav-links a:hover { | |
| color: var(--primary); | |
| } | |
| .layout-container { | |
| display: flex; | |
| max-width: 1400px; | |
| margin: var(--header-h) auto 0; | |
| width: 100%; | |
| min-height: calc(100vh - var(--header-h)); | |
| } | |
| .sidebar { | |
| width: var(--sidebar-w); | |
| background: var(--bg-sidebar); | |
| border-right: 1px solid var(--border); | |
| position: fixed; | |
| height: calc(100vh - var(--header-h)); | |
| overflow-y: auto; | |
| padding: 2rem 1.5rem; | |
| } | |
| .sidebar-group { | |
| margin-bottom: 2rem; | |
| } | |
| .sidebar-title { | |
| font-size: 0.75rem; | |
| font-weight: 600; | |
| text-transform: uppercase; | |
| letter-spacing: 0.05em; | |
| color: var(--text-main); | |
| margin-bottom: 0.75rem; | |
| } | |
| .sidebar-list { | |
| list-style: none; | |
| } | |
| .sidebar-list li { | |
| margin-bottom: 0.25rem; | |
| } | |
| .sidebar-link { | |
| display: block; | |
| padding: 0.4rem 0.75rem; | |
| color: var(--text-muted); | |
| text-decoration: none; | |
| font-size: 0.85rem; | |
| border-radius: 6px; | |
| transition: all 0.2s; | |
| line-height: 1.4; | |
| } | |
| .sidebar-link:hover { | |
| background: var(--bg-surface); | |
| color: var(--text-main); | |
| } | |
| .sidebar-link.active { | |
| background: var(--primary-light); | |
| color: var(--primary); | |
| font-weight: 500; | |
| } | |
| .main-content { | |
| flex: 1; | |
| margin-left: var(--sidebar-w); | |
| padding: 3rem 4rem 5rem; | |
| max-width: 1000px; | |
| } | |
| h1 { | |
| font-size: 2.2rem; | |
| font-weight: 600; | |
| color: var(--text-main); | |
| margin-bottom: 1rem; | |
| letter-spacing: -0.02em; | |
| } | |
| h2 { | |
| font-size: 1.5rem; | |
| font-weight: 600; | |
| color: var(--text-main); | |
| margin: 3.5rem 0 1.5rem; | |
| padding-bottom: 0.5rem; | |
| border-bottom: 1px solid var(--border); | |
| } | |
| h3 { | |
| font-size: 1.25rem; | |
| font-weight: 600; | |
| color: var(--text-main); | |
| margin: 2.5rem 0 1rem; | |
| } | |
| p { | |
| margin-bottom: 1.2rem; | |
| } | |
| .api-card { | |
| border: 1px solid var(--border); | |
| border-radius: 8px; | |
| margin: 2rem 0; | |
| overflow: hidden; | |
| background: var(--bg-main); | |
| box-shadow: 0 1px 3px rgba(0, 0, 0, 0.02); | |
| } | |
| .api-signature { | |
| background: var(--bg-sidebar); | |
| padding: 1rem 1.5rem; | |
| border-bottom: 1px solid var(--border); | |
| font-family: 'IBM Plex Mono', monospace; | |
| font-size: 0.9rem; | |
| color: var(--text-main); | |
| line-height: 1.6; | |
| display: block; | |
| text-align: left ; | |
| white-space: normal; | |
| word-wrap: break-word; | |
| overflow-wrap: break-word; | |
| } | |
| .api-signature .def { | |
| color: var(--primary); | |
| font-weight: 600; | |
| margin-right: 0.25rem; | |
| } | |
| .api-signature .method-name { | |
| color: var(--text-main); | |
| font-weight: 600; | |
| } | |
| .api-signature .type-hint { | |
| color: var(--text-muted); | |
| } | |
| .api-body { | |
| padding: 1.5rem; | |
| } | |
| .api-desc { | |
| margin-bottom: 1.5rem; | |
| font-size: 0.95rem; | |
| } | |
| .param-table { | |
| width: 100%; | |
| border-collapse: collapse; | |
| font-size: 0.9rem; | |
| text-align: left; | |
| margin-bottom: 1.5rem; | |
| } | |
| .param-table th { | |
| color: var(--text-main); | |
| font-weight: 600; | |
| padding: 0.5rem 1rem; | |
| border-bottom: 2px solid var(--border); | |
| } | |
| .param-table td { | |
| padding: 1rem; | |
| border-bottom: 1px solid var(--border); | |
| vertical-align: top; | |
| } | |
| .param-table tr:last-child td { | |
| border-bottom: none; | |
| } | |
| .p-name { | |
| font-family: 'IBM Plex Mono', monospace; | |
| font-weight: 600; | |
| color: var(--text-main); | |
| display: block; | |
| margin-bottom: 0.25rem; | |
| } | |
| .p-type { | |
| display: inline-block; | |
| background: var(--bg-surface); | |
| padding: 0.1rem 0.4rem; | |
| border-radius: 4px; | |
| font-family: 'IBM Plex Mono', monospace; | |
| font-size: 0.8rem; | |
| color: var(--primary-dark); | |
| margin-bottom: 0.5rem; | |
| border: 1px solid var(--border); | |
| } | |
| .return-block { | |
| background: var(--primary-light); | |
| border-left: 3px solid var(--primary); | |
| padding: 1rem 1.5rem; | |
| border-radius: 0 4px 4px 0; | |
| margin-top: 1.5rem; | |
| } | |
| .return-title { | |
| font-size: 0.8rem; | |
| font-weight: 600; | |
| text-transform: uppercase; | |
| color: var(--primary-dark); | |
| margin-bottom: 0.4rem; | |
| letter-spacing: 0.05em; | |
| } | |
| .return-type { | |
| font-family: 'IBM Plex Mono', monospace; | |
| font-size: 0.85rem; | |
| color: var(--text-main); | |
| margin-bottom: 0.25rem; | |
| font-weight: 600; | |
| } | |
| .return-desc { | |
| font-size: 0.9rem; | |
| color: var(--text-body); | |
| margin: 0; | |
| } | |
| .code-block { | |
| background: var(--code-bg); | |
| border-radius: 8px; | |
| margin: 1.5rem 0; | |
| position: relative; | |
| overflow: hidden; | |
| } | |
| .code-header { | |
| background: rgba(255, 255, 255, 0.05); | |
| padding: 0.5rem 1rem; | |
| font-family: 'IBM Plex Sans', sans-serif; | |
| font-size: 0.75rem; | |
| color: var(--text-muted); | |
| display: flex; | |
| justify-content: space-between; | |
| border-bottom: 1px solid rgba(255, 255, 255, 0.1); | |
| } | |
| .copy-btn { | |
| background: transparent; | |
| border: none; | |
| color: var(--text-muted); | |
| cursor: pointer; | |
| transition: color 0.2s; | |
| font-family: 'IBM Plex Sans', sans-serif; | |
| } | |
| .copy-btn:hover { | |
| color: white; | |
| } | |
| pre { | |
| padding: 1.2rem; | |
| overflow-x: auto; | |
| font-family: 'IBM Plex Mono', monospace; | |
| font-size: 0.85rem; | |
| line-height: 1.5; | |
| color: var(--code-text); | |
| margin: 0; | |
| } | |
| p code, li code { | |
| font-family: 'IBM Plex Mono', monospace; | |
| background: var(--bg-surface); | |
| padding: 0.15rem 0.4rem; | |
| border-radius: 4px; | |
| font-size: 0.85em; | |
| border: 1px solid var(--border); | |
| color: var(--text-main); | |
| } | |
| .note { | |
| display: flex; | |
| gap: 1rem; | |
| background: var(--bg-surface); | |
| border-left: 3px solid var(--text-muted); | |
| padding: 1rem 1.5rem; | |
| border-radius: 0 6px 6px 0; | |
| margin: 1.5rem 0; | |
| } | |
| .note-icon { | |
| font-size: 1.2rem; | |
| } | |
| .note-content p { | |
| margin: 0; | |
| font-size: 0.95rem; | |
| } | |
| @media (max-width: 1024px) { | |
| .sidebar { | |
| display: none; | |
| } | |
| .main-content { | |
| margin-left: 0; | |
| padding: 2rem; | |
| width: 100%; | |
| max-width: 100%; | |
| } | |
| } | |
| </style> | |
| </head> | |
| <body> | |
| <header> | |
| <div class="logo-area"> | |
| <span class="logo">LogosKG Docs</span> | |
| <span class="version-badge">v1.0.0</span> | |
| </div> | |
| <ul class="nav-links"> | |
| <li><a href="logoskg.html" style="color: var(--text-muted); font-weight: 500;">← Back to Home</a></li> | |
| <li><a href="https://github.com/LARK-NLP-Lab/LogosKG" target="_blank" | |
| style="background: var(--primary-light); color: var(--primary-dark); padding: 0.4rem 1.2rem; border-radius: 99px; font-weight: 600;">GitHub | |
| ↗</a></li> | |
| </ul> | |
| </header> | |
| <div class="layout-container"> | |
| <aside class="sidebar"> | |
| <div class="sidebar-group"> | |
| <div class="sidebar-title">Introduction</div> | |
| <ul class="sidebar-list"> | |
| <li><a href="#knowledge-graph" class="sidebar-link active">Knowledge Graph</a></li> | |
| <li><a href="#quickstart" class="sidebar-link">Installation & Setup</a></li> | |
| <li><a href="#architecture" class="sidebar-link">Core Architecture</a></li> | |
| </ul> | |
| </div> | |
| <div class="sidebar-group"> | |
| <div class="sidebar-title">LogosKG (Small)</div> | |
| <ul class="sidebar-list"> | |
| <li><a href="#small-init" class="sidebar-link">Initialization</a></li> | |
| <li><a href="#small-at-k" class="sidebar-link">retrieve_at_k_hop</a></li> | |
| <li><a href="#small-within-k" class="sidebar-link">retrieve_within_k_hop</a></li> | |
| <li><a href="#small-paths-at-k" class="sidebar-link">retrieve_with_paths_at_k_hop</a></li> | |
| <li><a href="#small-paths-within-k" class="sidebar-link">retrieve_with_paths_within_k_hop</a></li> | |
| <li><a href="#small-batch" class="sidebar-link">GPU Batch Optimization</a></li> | |
| </ul> | |
| </div> | |
| <div class="sidebar-group"> | |
| <div class="sidebar-title">LogosKG (Large)</div> | |
| <ul class="sidebar-list"> | |
| <li><a href="#large-intro" class="sidebar-link">Partitioning Engine Overview</a></li> | |
| <li><a href="#large-init" class="sidebar-link">Initialization</a></li> | |
| <li><a href="#large-at-k" class="sidebar-link">retrieve_at_k_hop</a></li> | |
| <li><a href="#large-within-k" class="sidebar-link">retrieve_within_k_hop</a></li> | |
| <li><a href="#large-paths-at-k" class="sidebar-link">retrieve_with_paths_at_k_hop</a></li> | |
| <li><a href="#large-paths-within-k" class="sidebar-link">retrieve_with_paths_within_k_hop</a></li> | |
| <li><a href="#large-batch" class="sidebar-link">Batch Caching Optimization</a></li> | |
| </ul> | |
| </div> | |
| </aside> | |
| <main class="main-content"> | |
| <h1>API Reference</h1> | |
| <p>LogosKG is a production-grade library for efficient multi-hop knowledge graph retrieval, optimized | |
| specifically for LLM-KG applications at scale.</p> | |
| <h2 id="knowledge-graph">Knowledge Graph</h2> | |
| <p>LogosKG operates on graph data structured as a list of <code>(head, relation, tail)</code> triplets. Before | |
| initializing the engine, ensure your knowledge graph is parsed into this standard format.</p> | |
| <div class="api-card" style="padding: 1.5rem; border-left: 4px solid var(--primary);"> | |
| <p style="margin-bottom: 0.5rem; font-size: 1.05rem; color: var(--text-main);"> | |
| Pre-build UMLS SNOMED CUI graph object (with physician-selected relations pertinent to diagnosis): | |
| <a href="https://drive.google.com/file/d/1zlb0zey_tAnFWtCY_NvhA0dqfydL4Ph7/view?usp=sharing" | |
| target="_blank" | |
| style="color: var(--primary); font-weight: 600; text-decoration: underline;">download</a> | |
| </p> | |
| <p style="margin: 0; font-size: 0.9rem; color: var(--text-muted);">This file is about 700 MB.</p> | |
| </div> | |
| <p style="font-size: 0.95rem; color: var(--text-muted); margin-bottom: 3.5rem;"> | |
| <strong>Reference:</strong> The customized clinical relations and graph subsets are derived from the | |
| <a href="https://github.com/serenayj/DRKnows?tab=readme-ov-file" target="_blank" | |
| style="color: var(--primary); text-decoration: none; font-weight: 500;">DR.KNOWs repository ↗</a>. | |
| </p> | |
| <h2 id="quickstart">Installation & Setup</h2> | |
| <div class="code-block"> | |
| <div class="code-header"> | |
| <span>Bash</span> | |
| <button class="copy-btn" onclick="copyCode(this)">Copy</button> | |
| </div> | |
| <pre><code><span style="color: var(--code-com)"># 1. Clone the repository</span> | |
| git clone https://github.com/LARK-NLP-Lab/LogosKG.git | |
| <span style="color: var(--code-com)"># 2. Enter the repository directory</span> | |
| cd LogosKG-Efficient-and-Scalable-Graph-Retrieval | |
| <span style="color: var(--code-com)"># 3. Install dependencies from requirements.txt</span> | |
| pip install -r requirements.txt</code></pre> | |
| </div> | |
| <h2 id="architecture">Core Architecture</h2> | |
| <div class="note"> | |
| <div class="note-icon">💡</div> | |
| <div class="note-content"> | |
| <p><strong>Vectorized Topology:</strong> The graph is decomposed into three CSR matrices: Subject Matrix | |
| (Sub), Object Matrix (Obj), and Relation Matrix (Rel). This transforms pointer-chasing into highly | |
| optimized matrix multiplications.</p> | |
| </div> | |
| </div> | |
| <h2 id="small-init">LogosKG (Small / In-Memory Engine)</h2> | |
| <p>The standard high-performance engine designed for knowledge graphs that fit entirely within system RAM or GPU | |
| VRAM.</p> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">class</span> <span | |
| class="method-name">LogosKG</span>(triplets<span | |
| class="type-hint">: List[Tuple[str, str, str]]</span>, backend<span class="type-hint">: str = 'numba'</span>, | |
| device<span class="type-hint">: str = 'cpu'</span>) | |
| </div> | |
| <div class="api-body"> | |
| <p class="api-desc">Initializes the engine, maps string entities to internal indices, and automatically | |
| constructs the CSR topology matrices.</p> | |
| <table class="param-table"> | |
| <thead> | |
| <tr> | |
| <th>Parameters</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><span class="p-name">triplets</span><span class="p-type">List[Tuple[str, str, str]]</span> | |
| </td> | |
| <td>List of <code>(head, relation, tail)</code> tuples representing the graph.</td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">backend</span><span class="p-type">str = "numba"</span></td> | |
| <td>Computation backend. Supported options: <code>"scipy"</code>, <code>"numba"</code>, or | |
| <code>"torch"</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">device</span><span class="p-type">str = "cpu"</span></td> | |
| <td>Target hardware device. Use <code>"cuda"</code> when <code>backend="torch"</code> for GPU | |
| acceleration. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">LogosKG</div> | |
| <p class="return-desc">An initialized LogosKG engine instance ready for multi-hop queries.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="small-at-k">1. retrieve_at_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_at_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int</span>, shortest_path<span | |
| class="type-hint">: bool = True</span>) <span class="type-hint">-> List[str]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Retrieves entities exactly <code>hops</code> away from the seed entities.</p> | |
| <table class="param-table"> | |
| <thead> | |
| <tr> | |
| <th>Parameters</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><span class="p-name">entity_ids</span><span class="p-type">List[str]</span></td> | |
| <td>List of seed anchor entities (e.g., extracted symptoms).</td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">hops</span><span class="p-type">int</span></td> | |
| <td>Exact traversal depth. Cannot be negative.</td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">shortest_path</span><span class="p-type">bool = True</span></td> | |
| <td>If True, prevents revisiting nodes discovered in earlier hops.</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[str]</div> | |
| <p class="return-desc">A list of unique entity string identifiers located exactly at the specified | |
| depth.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="small-within-k">2. retrieve_within_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span | |
| class="method-name">retrieve_within_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int</span>, shortest_path<span | |
| class="type-hint">: bool = True</span>) <span class="type-hint">-> List[str]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Retrieves an accumulated list of all entities discovered from hop 0 up to | |
| <code>hops</code>.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[str]</div> | |
| <p class="return-desc">A list of all unique entity identifiers encountered within the given | |
| depth.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="small-paths-at-k">3. retrieve_with_paths_at_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_with_paths_at_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int = 2</span>, | |
| shortest_path<span class="type-hint">: bool = True</span>, max_paths_per_entity<span class="type-hint">: Optional[int] = None</span>) | |
| <span class="type-hint">-> Dict[str, Any]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Retrieves entities at exactly K hops, returning both the entities and their | |
| reconstructed topological paths.</p> | |
| <table class="param-table"> | |
| <thead> | |
| <tr> | |
| <th>Parameters</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><span class="p-name">max_paths_per_entity</span><span | |
| class="p-type">Optional[int] = None</span></td> | |
| <td>Limits the number of returned paths per target node to prevent memory explosion in dense | |
| subgraphs. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">Dict[str, Any]</div> | |
| <p class="return-desc">A dictionary containing <code>"entities"</code> (List[str]) and | |
| <code>"paths"</code> (Dictionary mapping endpoints to their path lists).</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="small-paths-within-k">4. retrieve_with_paths_within_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_with_paths_within_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int = 2</span>, | |
| shortest_path<span class="type-hint">: bool = True</span>, max_paths_per_entity<span class="type-hint">: Optional[int] = None</span>) | |
| <span class="type-hint">-> Dict[str, Any]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Performs full path reconstruction for all entities discovered up to K hops. Crucial | |
| for providing interpretable context to LLMs.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">Dict[str, Any]</div> | |
| <p class="return-desc">A dictionary containing complete paths mapping seed anchors to every | |
| discovered entity.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="small-batch">GPU Batch Optimization</h3> | |
| <p>While <code>LogosKG</code> (Small) exposes single-query signatures, it contains a powerful <strong>internal | |
| automatic batching engine</strong>. If <code>backend='torch'</code> and multiple <code>entity_ids</code> are | |
| provided simultaneously, the engine dynamically switches to <code>_retrieve_at_k_hop_torch_batched()</code>, | |
| exploiting PyTorch sparse matrix multiplications across concurrent seed dimensions for massive throughput. | |
| </p> | |
| <h2 id="large-intro" style="margin-top: 5rem;">LogosKGLarge (Partitioned Engine)</h2> | |
| <p>For massive graphs (e.g., combining UMLS + PrimeKG) that exceed memory limits, <code>LogosKGLarge</code> | |
| implements disk-backed partitioning with an intelligent LRU cache memory management system, ensuring | |
| Out-Of-Memory (OOM) errors are completely avoided while maintaining graph consistency.</p> | |
| <h3 id="large-init">Initialization</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">class</span> <span class="method-name">LogosKGLarge</span>(partition_dir<span | |
| class="type-hint">: str</span>, backend<span class="type-hint">: str = 'numba'</span>, device<span | |
| class="type-hint">: str = 'cpu'</span>, cache_size<span class="type-hint">: int = 10</span>, | |
| triplets<span class="type-hint">: Optional[List] = None</span>, num_partitions<span | |
| class="type-hint">: int = 16</span>) | |
| </div> | |
| <div class="api-body"> | |
| <table class="param-table"> | |
| <thead> | |
| <tr> | |
| <th>Parameters</th> | |
| <th>Description</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><span class="p-name">partition_dir</span><span class="p-type">str</span></td> | |
| <td>Directory containing partitioned data (<code>metadata.pkl</code>).</td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">cache_size</span><span class="p-type">int = 10</span></td> | |
| <td>Number of subgraph partitions to keep active in memory (LRU).</td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">triplets</span><span class="p-type">Optional[List]</span></td> | |
| <td>If partitions don't exist, provide raw triplets here to trigger <code>KnowledgeGraphPartitioner</code> | |
| automatically. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td><span class="p-name">num_partitions</span><span class="p-type">int = 16</span></td> | |
| <td>Target number of subgraphs to generate during automatic partitioning.</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">LogosKGLarge</div> | |
| <p class="return-desc">A disk-backed, memory-efficient knowledge graph engine.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="large-at-k">1. retrieve_at_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_at_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int</span>, shortest_path<span | |
| class="type-hint">: bool = True</span>) <span class="type-hint">-> List[str]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Performs a cross-partition <code>hops</code> depth traversal. Automatically manages | |
| dynamic loading and unloading of partition chunks via the LRU cache.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[str]</div> | |
| <p class="return-desc">List of entities exactly at depth K, seamlessly bridging multiple | |
| partitions.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="large-within-k">2. retrieve_within_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span | |
| class="method-name">retrieve_within_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int</span>, shortest_path<span | |
| class="type-hint">: bool = True</span>) <span class="type-hint">-> List[str]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Accumulates entities from hop 0 to K across all necessary partitions.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[str]</div> | |
| <p class="return-desc">List of all unique entities within the depth boundary.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="large-paths-at-k">3. retrieve_with_paths_at_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_with_paths_at_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int = 2</span>, | |
| shortest_path<span class="type-hint">: bool = True</span>, max_paths_per_entity<span class="type-hint">: Optional[int] = None</span>) | |
| <span class="type-hint">-> Dict[str, Any]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Tracks topological path indices across multiple graph partitions simultaneously.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">Dict[str, Any]</div> | |
| <p class="return-desc">Dictionary mapping endpoints at exactly hop K to their cross-partition | |
| topological paths.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="large-paths-within-k">4. retrieve_with_paths_within_k_hop</h3> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">retrieve_with_paths_within_k_hop</span>(entity_ids<span | |
| class="type-hint">: List[str]</span>, hops<span class="type-hint">: int = 2</span>, | |
| shortest_path<span class="type-hint">: bool = True</span>, max_paths_per_entity<span class="type-hint">: Optional[int] = None</span>) | |
| <span class="type-hint">-> Dict[str, Any]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">The most comprehensive method. Reconstructs every step taken across all partitions | |
| up to depth K.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">Dict[str, Any]</div> | |
| <p class="return-desc">Dictionary mapping all discovered endpoints to their complete pathways.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <h3 id="large-batch">Batch Caching Optimization</h3> | |
| <p>Unlike standard single-query batching, <code>LogosKGLarge</code> provides specialized | |
| <code>batch_retrieve_*</code> methods. These methods mathematically analyze the subgraphs required for an | |
| entire array of user queries, <strong>sorting and clustering them internally</strong> to maximize LRU cache | |
| hits, drastically eliminating disk I/O bottlenecks.</p> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">batch_retrieve_within_k_hop</span>(batch_entity_ids<span | |
| class="type-hint">: List[List[str]]</span>, hops<span class="type-hint">: int</span>, | |
| shortest_path<span class="type-hint">: bool = True</span>) <span | |
| class="type-hint">-> List[List[str]]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Processes an entire batch of independent patient narratives / seed groupings | |
| simultaneously.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[List[str]]</div> | |
| <p class="return-desc">A 2D array of results mapped perfectly back to the original input query | |
| order.</p> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="api-card"> | |
| <div class="api-signature"><span class="def">def</span> <span class="method-name">batch_retrieve_with_paths_within_k_hop</span>(batch_entity_ids<span | |
| class="type-hint">: List[List[str]]</span>, hops<span class="type-hint">: int = 2</span>, ...) <span | |
| class="type-hint">-> List[Dict[str, Any]]</span></div> | |
| <div class="api-body"> | |
| <p class="api-desc">Batch version of the full path reconstruction algorithm with LRU cache sorting logic | |
| applied.</p> | |
| <div class="return-block"> | |
| <div class="return-title">Returns</div> | |
| <div class="return-type">List[Dict[str, Any]]</div> | |
| <p class="return-desc">A list of dictionaries, where each dictionary contains the reconstructed | |
| paths matching its respective input query.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </main> | |
| </div> | |
| <script> | |
| function copyCode(btn) { | |
| const pre = btn.parentElement.nextElementSibling; | |
| const code = pre.innerText; | |
| navigator.clipboard.writeText(code).then(() => { | |
| const originalText = btn.innerText; | |
| btn.innerText = 'Copied!'; | |
| btn.style.color = 'white'; | |
| setTimeout(() => { | |
| btn.innerText = originalText; | |
| btn.style.color = 'var(--text-muted)'; | |
| }, 2000); | |
| }); | |
| } | |
| const sections = document.querySelectorAll('.main-content h2, .main-content h3'); | |
| const leftLinks = document.querySelectorAll('.sidebar-link'); | |
| leftLinks.forEach(link => { | |
| link.addEventListener('click', function (e) { | |
| e.preventDefault(); | |
| const targetId = this.getAttribute('href'); | |
| const targetElement = document.querySelector(targetId); | |
| if (targetElement) { | |
| const headerOffset = 100; | |
| const elementPosition = targetElement.getBoundingClientRect().top; | |
| const offsetPosition = elementPosition + window.pageYOffset - headerOffset; | |
| window.scrollTo({ | |
| top: offsetPosition, | |
| behavior: 'smooth' | |
| }); | |
| history.replaceState(null, null, targetId); | |
| } | |
| }); | |
| }); | |
| window.addEventListener('scroll', () => { | |
| let current = ''; | |
| sections.forEach(section => { | |
| const sectionTop = section.offsetTop; | |
| if (pageYOffset >= sectionTop - 150) { | |
| current = section.getAttribute('id'); | |
| } | |
| }); | |
| leftLinks.forEach(link => { | |
| link.classList.remove('active'); | |
| if (link.getAttribute('href') === `#${current}`) { | |
| link.classList.add('active'); | |
| } | |
| }); | |
| }); | |
| </script> | |
| </body> | |
| </html> |