Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

docs: add SVG diagrams and Semantica wordmark logo

KaifAhmad198bc2de20b26
diff --git a/docs/architecture.md b/docs/architecture.md
index d2ab458d..80531aa3 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -8,18 +8,7 @@ Semantica is built around a three-layer modular architecture. Import only what y
## Three-Layer Architecture
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│ Layer 1: Data Ingestion │
-│ Files · Web · APIs · Databases · Streams │
-├─────────────────────────────────────────────────────────────────┤
-│ Layer 2: Semantic Processing │
-│ Parse · Normalize · Extract · Build · QA │
-├─────────────────────────────────────────────────────────────────┤
-│ Layer 3: Application │
-│ GraphRAG · AI Agents · Analytics · Export · Visualization │
-└─────────────────────────────────────────────────────────────────┘
-```
+<img src="/assets/img/diagrams/architecture-overview.svg" alt="Semantica four-layer architecture" style={{ width: '100%', borderRadius: '12px', margin: '16px 0 24px' }} />
<Tabs>
@@ -80,16 +69,7 @@ Consumes the knowledge graph for downstream use cases.
Every pipeline follows the same linear path from raw source to delivered output:
-```text
-Ingest → raw data from files, web, databases, streams
-Parse → structured text and layout extraction
-Normalize → canonical forms, date and name standardization
-Extract → entities, relationships, events, triplets
-Build → entity resolution and graph construction
-QA → deduplication, conflict resolution, validation
-Store → vector store, graph store, triplet store
-Deliver → GraphRAG, agents, export, visualization
-```
+<img src="/assets/img/diagrams/pipeline-flow.svg" alt="Semantica 8-step pipeline: Ingest → Parse → Normalize → Extract → Build KG → QA → Store → Deliver" style={{ width: '100%', borderRadius: '10px', margin: '16px 0 24px' }} />
## Module Map
diff --git a/docs/assets/img/diagrams/agent-context-flow.svg b/docs/assets/img/diagrams/agent-context-flow.svg
new file mode 100644
index 00000000..789c05fa
--- /dev/null
+++ b/docs/assets/img/diagrams/agent-context-flow.svg
@@ -0,0 +1,109 @@
+<svg viewBox="0 0 780 310" xmlns="http://www.w3.org/2000/svg">
+<title>AgentContext Memory and Decision Flow</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-12%" y="-12%" width="124%" height="130%">
+ <feDropShadow dx="0" dy="2" stdDeviation="6" flood-color="#00000014"/>
+ </filter>
+ <linearGradient id="g-agent" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#475569"/><stop offset="100%" stop-color="#1e293b"/>
+ </linearGradient>
+ <linearGradient id="g-ctx" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#818cf8"/><stop offset="100%" stop-color="#4f46e5"/>
+ </linearGradient>
+ <linearGradient id="g-vec" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#38bdf8"/><stop offset="100%" stop-color="#0284c7"/>
+ </linearGradient>
+ <linearGradient id="g-kg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#34d399"/><stop offset="100%" stop-color="#059669"/>
+ </linearGradient>
+ <clipPath id="cag"><rect x="20" y="100" width="140" height="110" rx="12"/></clipPath>
+ <clipPath id="cctx"><rect x="270" y="70" width="240" height="170" rx="14"/></clipPath>
+ <clipPath id="cvec"><rect x="620" y="80" width="144" height="80" rx="10"/></clipPath>
+ <clipPath id="ckg"><rect x="620" y="190" width="144" height="80" rx="10"/></clipPath>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+ <marker id="arr-rev" markerWidth="9" markerHeight="7" refX="1" refY="3.5" orient="auto">
+ <polygon points="9 0, 0 3.5, 9 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="780" height="310" fill="#f1f5f9" rx="16"/>
+<text x="390" y="30" text-anchor="middle" font-size="13" font-weight="700" fill="#334155">AgentContext — Memory, Decisions &amp; Graph Intelligence</text>
+
+<!-- ── AI AGENT ── -->
+<rect x="20" y="100" width="140" height="110" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="20" y="100" width="140" height="36" fill="url(#g-agent)" clip-path="url(#cag)"/>
+<text x="90" y="118" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1">AGENT</text>
+<text x="90" y="132" text-anchor="middle" font-size="12.5" font-weight="700" fill="white">AI Agent</text>
+<text x="90" y="157" text-anchor="middle" font-size="10.5" fill="#475569" font-weight="600">store(fact)</text>
+<text x="90" y="172" text-anchor="middle" font-size="10.5" fill="#475569" font-weight="600">retrieve(query)</text>
+<text x="90" y="187" text-anchor="middle" font-size="10.5" fill="#475569" font-weight="600">record_decision()</text>
+
+<!-- Bidirectional arrow Agent ↔ AgentContext -->
+<line x1="162" y1="148" x2="262" y2="148" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="262" y1="162" x2="162" y2="162" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="212" y="144" text-anchor="middle" font-size="9" fill="#94a3b8">calls</text>
+<text x="212" y="176" text-anchor="middle" font-size="9" fill="#94a3b8">results</text>
+
+<!-- ── AGENT CONTEXT (hub) ── -->
+<rect x="270" y="70" width="240" height="170" rx="14" fill="white" filter="url(#sh)"/>
+<rect x="270" y="70" width="240" height="40" fill="url(#g-ctx)" clip-path="url(#cctx)"/>
+<text x="390" y="89" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1">CORE MODULE</text>
+<text x="390" y="105" text-anchor="middle" font-size="13" font-weight="700" fill="white">AgentContext</text>
+
+<!-- Method pills inside AgentContext -->
+<rect x="286" y="124" width="96" height="22" rx="6" fill="#eef2ff"/>
+<text x="334" y="139" text-anchor="middle" font-size="10" font-weight="600" fill="#4f46e5">store(content)</text>
+
+<rect x="392" y="124" width="102" height="22" rx="6" fill="#eef2ff"/>
+<text x="443" y="139" text-anchor="middle" font-size="10" font-weight="600" fill="#4f46e5">retrieve(query)</text>
+
+<rect x="286" y="155" width="130" height="22" rx="6" fill="#f0fdf4"/>
+<text x="351" y="170" text-anchor="middle" font-size="10" font-weight="600" fill="#059669">record_decision()</text>
+
+<rect x="426" y="155" width="68" height="22" rx="6" fill="#f0fdf4"/>
+<text x="460" y="170" text-anchor="middle" font-size="10" font-weight="600" fill="#059669">find_precedents()</text>
+
+<rect x="286" y="186" width="106" height="22" rx="6" fill="#ecfeff"/>
+<text x="339" y="201" text-anchor="middle" font-size="10" font-weight="600" fill="#0891b2">analyze_influence()</text>
+
+<rect x="402" y="186" width="92" height="22" rx="6" fill="#ecfeff"/>
+<text x="448" y="201" text-anchor="middle" font-size="10" font-weight="600" fill="#0891b2">get_causal_chain()</text>
+
+<!-- Arrow AgentContext → VectorStore -->
+<line x1="510" y1="130" x2="612" y2="118" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="558" y="116" text-anchor="middle" font-size="9" fill="#94a3b8">embed + index</text>
+
+<!-- Arrow VectorStore → AgentContext (return) -->
+<line x1="612" y1="134" x2="510" y2="148" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="558" y="148" text-anchor="middle" font-size="9" fill="#94a3b8">top-k results</text>
+
+<!-- Arrow AgentContext → ContextGraph -->
+<line x1="510" y1="200" x2="612" y2="220" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="558" y="222" text-anchor="middle" font-size="9" fill="#94a3b8">store decision</text>
+
+<!-- Arrow ContextGraph → AgentContext (return) -->
+<line x1="612" y1="234" x2="510" y2="216" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<text x="558" y="250" text-anchor="middle" font-size="9" fill="#94a3b8">causal chain</text>
+
+<!-- ── VECTOR STORE ── -->
+<rect x="620" y="80" width="144" height="80" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="620" y="80" width="144" height="28" fill="url(#g-vec)" clip-path="url(#cvec)"/>
+<text x="692" y="97" text-anchor="middle" font-size="10" font-weight="700" fill="white">VectorStore</text>
+<text x="692" y="124" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Semantic memory</text>
+<text x="692" y="139" text-anchor="middle" font-size="9.5" fill="#64748b">FAISS · Pinecone · Qdrant</text>
+<text x="692" y="152" text-anchor="middle" font-size="9.5" fill="#64748b">embedding-backed retrieval</text>
+
+<!-- ── CONTEXT GRAPH ── -->
+<rect x="620" y="190" width="144" height="80" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="620" y="190" width="144" height="28" fill="url(#g-kg)" clip-path="url(#ckg)"/>
+<text x="692" y="207" text-anchor="middle" font-size="10" font-weight="700" fill="white">ContextGraph</text>
+<text x="692" y="234" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Decision graph</text>
+<text x="692" y="249" text-anchor="middle" font-size="9.5" fill="#64748b">causal chains · precedents</text>
+<text x="692" y="262" text-anchor="middle" font-size="9.5" fill="#64748b">centrality · community</text>
+
+<!-- Bottom note -->
+<text x="390" y="290" text-anchor="middle" font-size="10" fill="#94a3b8">decision_tracking=True enables full audit trail — every agent action is recorded and traceable</text>
+</svg>
diff --git a/docs/assets/img/diagrams/architecture-overview.svg b/docs/assets/img/diagrams/architecture-overview.svg
new file mode 100644
index 00000000..56077fce
--- /dev/null
+++ b/docs/assets/img/diagrams/architecture-overview.svg
@@ -0,0 +1,159 @@
+<svg viewBox="0 0 900 380" xmlns="http://www.w3.org/2000/svg">
+<title>Semantica Architecture Overview</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-10%" y="-10%" width="120%" height="130%">
+ <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00000012"/>
+ </filter>
+ <linearGradient id="gi" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#818cf8"/><stop offset="100%" stop-color="#4f46e5"/>
+ </linearGradient>
+ <linearGradient id="gp" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#a78bfa"/><stop offset="100%" stop-color="#7c3aed"/>
+ </linearGradient>
+ <linearGradient id="gc" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#38bdf8"/><stop offset="100%" stop-color="#0284c7"/>
+ </linearGradient>
+ <linearGradient id="ge" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#34d399"/><stop offset="100%" stop-color="#059669"/>
+ </linearGradient>
+ <clipPath id="c1"><rect x="16" y="16" width="188" height="348" rx="12"/></clipPath>
+ <clipPath id="c2"><rect x="240" y="16" width="188" height="348" rx="12"/></clipPath>
+ <clipPath id="c3"><rect x="464" y="16" width="188" height="348" rx="12"/></clipPath>
+ <clipPath id="c4"><rect x="688" y="16" width="196" height="348" rx="12"/></clipPath>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="900" height="380" fill="#f1f5f9" rx="16"/>
+
+<!-- ── COLUMN 1: INGESTION ── -->
+<rect x="16" y="16" width="188" height="348" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="16" y="16" width="188" height="70" fill="url(#gi)" clip-path="url(#c1)"/>
+<text x="110" y="41" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1.8">INGESTION</text>
+<text x="110" y="62" text-anchor="middle" font-size="13.5" font-weight="700" fill="white">Data Sources</text>
+
+<rect x="26" y="86" width="4" height="28" rx="2" fill="#6366f1"/>
+<text x="38" y="102" font-size="11.5" font-weight="600" fill="#0f172a">Files &amp; PDFs</text>
+<text x="38" y="115" font-size="10" fill="#64748b">FileIngestor · DocxParser</text>
+<line x1="30" y1="124" x2="196" y2="124" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="26" y="128" width="4" height="28" rx="2" fill="#6366f1"/>
+<text x="38" y="144" font-size="11.5" font-weight="600" fill="#0f172a">Web &amp; APIs</text>
+<text x="38" y="157" font-size="10" fill="#64748b">WebIngestor · REST</text>
+<line x1="30" y1="166" x2="196" y2="166" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="26" y="170" width="4" height="28" rx="2" fill="#6366f1"/>
+<text x="38" y="186" font-size="11.5" font-weight="600" fill="#0f172a">Databases</text>
+<text x="38" y="199" font-size="10" fill="#64748b">DBIngestor · DuckDB</text>
+<line x1="30" y1="208" x2="196" y2="208" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="26" y="212" width="4" height="28" rx="2" fill="#6366f1"/>
+<text x="38" y="228" font-size="11.5" font-weight="600" fill="#0f172a">Streams</text>
+<text x="38" y="241" font-size="10" fill="#64748b">StreamIngestor · Kafka</text>
+<line x1="30" y1="250" x2="196" y2="250" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="26" y="254" width="4" height="28" rx="2" fill="#6366f1"/>
+<text x="38" y="270" font-size="11.5" font-weight="600" fill="#0f172a">Parquet &amp; XML</text>
+<text x="38" y="283" font-size="10" fill="#64748b">PyArrow · lxml · v0.5.0</text>
+
+<!-- Arrow 1 -->
+<line x1="206" y1="190" x2="232" y2="190" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── COLUMN 2: PROCESSING ── -->
+<rect x="240" y="16" width="188" height="348" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="240" y="16" width="188" height="70" fill="url(#gp)" clip-path="url(#c2)"/>
+<text x="334" y="41" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1.8">PROCESSING</text>
+<text x="334" y="62" text-anchor="middle" font-size="13.5" font-weight="700" fill="white">Semantic Engine</text>
+
+<rect x="250" y="86" width="4" height="28" rx="2" fill="#8b5cf6"/>
+<text x="262" y="102" font-size="11.5" font-weight="600" fill="#0f172a">Parse &amp; Layout</text>
+<text x="262" y="115" font-size="10" fill="#64748b">DocumentParser · Docling</text>
+<line x1="254" y1="124" x2="420" y2="124" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="250" y="128" width="4" height="28" rx="2" fill="#8b5cf6"/>
+<text x="262" y="144" font-size="11.5" font-weight="600" fill="#0f172a">Normalize</text>
+<text x="262" y="157" font-size="10" fill="#64748b">TextNormalizer · dates</text>
+<line x1="254" y1="166" x2="420" y2="166" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="250" y="170" width="4" height="28" rx="2" fill="#8b5cf6"/>
+<text x="262" y="186" font-size="11.5" font-weight="600" fill="#0f172a">NER &amp; Relations</text>
+<text x="262" y="199" font-size="10" fill="#64748b">pattern · ml · llm</text>
+<line x1="254" y1="208" x2="420" y2="208" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="250" y="212" width="4" height="28" rx="2" fill="#8b5cf6"/>
+<text x="262" y="228" font-size="11.5" font-weight="600" fill="#0f172a">Build Graph</text>
+<text x="262" y="241" font-size="10" fill="#64748b">GraphBuilder · merge</text>
+<line x1="254" y1="250" x2="420" y2="250" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="250" y="254" width="4" height="28" rx="2" fill="#8b5cf6"/>
+<text x="262" y="270" font-size="11.5" font-weight="600" fill="#0f172a">QA &amp; Dedup</text>
+<text x="262" y="283" font-size="10" fill="#64748b">ConflictDetector · merge</text>
+
+<!-- Arrow 2 -->
+<line x1="430" y1="190" x2="456" y2="190" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── COLUMN 3: INTELLIGENCE ── -->
+<rect x="464" y="16" width="188" height="348" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="464" y="16" width="188" height="70" fill="url(#gc)" clip-path="url(#c3)"/>
+<text x="558" y="41" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1.8">INTELLIGENCE</text>
+<text x="558" y="62" text-anchor="middle" font-size="13.5" font-weight="700" fill="white">Knowledge Store</text>
+
+<rect x="474" y="86" width="4" height="28" rx="2" fill="#0891b2"/>
+<text x="486" y="102" font-size="11.5" font-weight="600" fill="#0f172a">Knowledge Graph</text>
+<text x="486" y="115" font-size="10" fill="#64748b">NetworkX · Neo4j · AGE</text>
+<line x1="478" y1="124" x2="644" y2="124" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="474" y="128" width="4" height="28" rx="2" fill="#0891b2"/>
+<text x="486" y="144" font-size="11.5" font-weight="600" fill="#0f172a">Vector Store</text>
+<text x="486" y="157" font-size="10" fill="#64748b">FAISS · Pinecone · Qdrant</text>
+<line x1="478" y1="166" x2="644" y2="166" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="474" y="170" width="4" height="28" rx="2" fill="#0891b2"/>
+<text x="486" y="186" font-size="11.5" font-weight="600" fill="#0f172a">Ontology</text>
+<text x="486" y="199" font-size="10" fill="#64748b">OWL · SHACL · SKOS</text>
+<line x1="478" y1="208" x2="644" y2="208" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="474" y="212" width="4" height="28" rx="2" fill="#0891b2"/>
+<text x="486" y="228" font-size="11.5" font-weight="600" fill="#0f172a">Triplet Store</text>
+<text x="486" y="241" font-size="10" fill="#64748b">SPARQL · Blazegraph · Jena</text>
+<line x1="478" y1="250" x2="644" y2="250" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="474" y="254" width="4" height="28" rx="2" fill="#0891b2"/>
+<text x="486" y="270" font-size="11.5" font-weight="600" fill="#0f172a">Embeddings</text>
+<text x="486" y="283" font-size="10" fill="#64748b">ST · FastEmbed · BGE</text>
+
+<!-- Arrow 3 -->
+<line x1="654" y1="190" x2="680" y2="190" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── COLUMN 4: APPLICATION ── -->
+<rect x="688" y="16" width="196" height="348" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="688" y="16" width="196" height="70" fill="url(#ge)" clip-path="url(#c4)"/>
+<text x="786" y="41" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="1.8">APPLICATION</text>
+<text x="786" y="62" text-anchor="middle" font-size="13.5" font-weight="700" fill="white">Output Layer</text>
+
+<rect x="698" y="86" width="4" height="28" rx="2" fill="#059669"/>
+<text x="710" y="102" font-size="11.5" font-weight="600" fill="#0f172a">GraphRAG Agents</text>
+<text x="710" y="115" font-size="10" fill="#64748b">AgentContext · memory</text>
+<line x1="702" y1="124" x2="876" y2="124" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="698" y="128" width="4" height="28" rx="2" fill="#059669"/>
+<text x="710" y="144" font-size="11.5" font-weight="600" fill="#0f172a">Decision Tracking</text>
+<text x="710" y="157" font-size="10" fill="#64748b">causal chains · audit</text>
+<line x1="702" y1="166" x2="876" y2="166" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="698" y="170" width="4" height="28" rx="2" fill="#059669"/>
+<text x="710" y="186" font-size="11.5" font-weight="600" fill="#0f172a">Reasoning</text>
+<text x="710" y="199" font-size="10" fill="#64748b">forward chain · Datalog</text>
+<line x1="702" y1="208" x2="876" y2="208" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="698" y="212" width="4" height="28" rx="2" fill="#059669"/>
+<text x="710" y="228" font-size="11.5" font-weight="600" fill="#0f172a">Explorer &amp; Hub</text>
+<text x="710" y="241" font-size="10" fill="#64748b">SHACL Studio · Ontology</text>
+<line x1="702" y1="250" x2="876" y2="250" stroke="#f1f5f9" stroke-width="1"/>
+
+<rect x="698" y="254" width="4" height="28" rx="2" fill="#059669"/>
+<text x="710" y="270" font-size="11.5" font-weight="600" fill="#0f172a">Export &amp; Provenance</text>
+<text x="710" y="283" font-size="10" fill="#64748b">RDF · Parquet · PROV-O</text>
+</svg>
diff --git a/docs/assets/img/diagrams/extraction-pipeline.svg b/docs/assets/img/diagrams/extraction-pipeline.svg
new file mode 100644
index 00000000..e6c36d0f
--- /dev/null
+++ b/docs/assets/img/diagrams/extraction-pipeline.svg
@@ -0,0 +1,82 @@
+<svg viewBox="0 0 740 300" xmlns="http://www.w3.org/2000/svg">
+<title>Semantic Extraction Pipeline</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-12%" y="-12%" width="124%" height="124%">
+ <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00000012"/>
+ </filter>
+ <linearGradient id="g-text" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#475569"/><stop offset="100%" stop-color="#334155"/>
+ </linearGradient>
+ <linearGradient id="g-ner" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#818cf8"/><stop offset="100%" stop-color="#4f46e5"/>
+ </linearGradient>
+ <linearGradient id="g-rel" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#a78bfa"/><stop offset="100%" stop-color="#7c3aed"/>
+ </linearGradient>
+ <linearGradient id="g-coref" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#38bdf8"/><stop offset="100%" stop-color="#0284c7"/>
+ </linearGradient>
+ <linearGradient id="g-trip" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#34d399"/><stop offset="100%" stop-color="#059669"/>
+ </linearGradient>
+ <linearGradient id="g-kg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#fb923c"/><stop offset="100%" stop-color="#ea580c"/>
+ </linearGradient>
+ <clipPath id="ctext"><rect x="250" y="20" width="240" height="54" rx="10"/></clipPath>
+ <clipPath id="cner"><rect x="40" y="120" width="170" height="72" rx="10"/></clipPath>
+ <clipPath id="crel"><rect x="285" y="120" width="170" height="72" rx="10"/></clipPath>
+ <clipPath id="ccoref"><rect x="530" y="120" width="170" height="72" rx="10"/></clipPath>
+ <clipPath id="ctrip"><rect x="200" y="228" width="340" height="52" rx="10"/></clipPath>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="740" height="300" fill="#f1f5f9" rx="16"/>
+<text x="370" y="288" text-anchor="middle" font-size="10" fill="#94a3b8">All extractors support pattern · ml · llm modes — swap with one parameter change</text>
+
+<!-- ── INPUT TEXT ── -->
+<rect x="250" y="20" width="240" height="54" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="250" y="20" width="240" height="24" fill="url(#g-text)" clip-path="url(#ctext)"/>
+<text x="370" y="35" text-anchor="middle" font-size="9.5" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">INPUT</text>
+<text x="370" y="50" text-anchor="middle" font-size="12" font-weight="700" fill="white">Raw Text</text>
+<text x="370" y="65" text-anchor="middle" font-size="10.5" fill="#475569">"Apple Inc. was founded by Steve Jobs in 1976"</text>
+
+<!-- Fan-out arrows: Text → 3 extractors -->
+<line x1="310" y1="74" x2="160" y2="118" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="370" y1="74" x2="370" y2="118" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="430" y1="74" x2="580" y2="118" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── NER EXTRACTOR ── -->
+<rect x="40" y="120" width="170" height="72" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="40" y="120" width="170" height="28" fill="url(#g-ner)" clip-path="url(#cner)"/>
+<text x="125" y="136" text-anchor="middle" font-size="10" font-weight="700" fill="white">NERExtractor</text>
+<text x="125" y="163" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Entities</text>
+<text x="125" y="178" text-anchor="middle" font-size="9.5" fill="#64748b">PERSON · ORG · LOC · DATE</text>
+
+<!-- ── RELATION EXTRACTOR ── -->
+<rect x="285" y="120" width="170" height="72" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="285" y="120" width="170" height="28" fill="url(#g-rel)" clip-path="url(#crel)"/>
+<text x="370" y="136" text-anchor="middle" font-size="10" font-weight="700" fill="white">RelationExtractor</text>
+<text x="370" y="163" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Relations</text>
+<text x="370" y="178" text-anchor="middle" font-size="9.5" fill="#64748b">founded · located_in · works_for</text>
+
+<!-- ── COREFERENCE RESOLVER ── -->
+<rect x="530" y="120" width="170" height="72" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="530" y="120" width="170" height="28" fill="url(#g-coref)" clip-path="url(#ccoref)"/>
+<text x="615" y="136" text-anchor="middle" font-size="10" font-weight="700" fill="white">CoreferenceResolver</text>
+<text x="615" y="163" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">References</text>
+<text x="615" y="178" text-anchor="middle" font-size="9.5" fill="#64748b">"the company" → Apple Inc.</text>
+
+<!-- Fan-in arrows: 3 extractors → Triplet Generator -->
+<line x1="160" y1="192" x2="280" y2="226" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="370" y1="192" x2="370" y2="226" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="580" y1="192" x2="460" y2="226" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── TRIPLET GENERATOR ── -->
+<rect x="200" y="228" width="340" height="52" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="200" y="228" width="340" height="24" fill="url(#g-trip)" clip-path="url(#ctrip)"/>
+<text x="370" y="243" text-anchor="middle" font-size="10" font-weight="700" fill="white">TripletExtractor — (subject, predicate, object)</text>
+<text x="370" y="267" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">(Steve Jobs, founded, Apple Inc.) · (Apple Inc., located_in, Cupertino)</text>
+</svg>
diff --git a/docs/assets/img/diagrams/graphrag-flow.svg b/docs/assets/img/diagrams/graphrag-flow.svg
new file mode 100644
index 00000000..1446775e
--- /dev/null
+++ b/docs/assets/img/diagrams/graphrag-flow.svg
@@ -0,0 +1,100 @@
+<svg viewBox="0 0 860 240" xmlns="http://www.w3.org/2000/svg">
+<title>GraphRAG Retrieval Flow</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-12%" y="-12%" width="124%" height="124%">
+ <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00000012"/>
+ </filter>
+ <linearGradient id="g1" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#818cf8"/><stop offset="100%" stop-color="#4f46e5"/>
+ </linearGradient>
+ <linearGradient id="g2" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#38bdf8"/><stop offset="100%" stop-color="#0284c7"/>
+ </linearGradient>
+ <linearGradient id="g3" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#a78bfa"/><stop offset="100%" stop-color="#7c3aed"/>
+ </linearGradient>
+ <linearGradient id="g4" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#34d399"/><stop offset="100%" stop-color="#059669"/>
+ </linearGradient>
+ <clipPath id="cc1"><rect x="18" y="70" width="130" height="100" rx="12"/></clipPath>
+ <clipPath id="cc2a"><rect x="184" y="62" width="160" height="56" rx="10"/></clipPath>
+ <clipPath id="cc2b"><rect x="184" y="130" width="160" height="56" rx="10"/></clipPath>
+ <clipPath id="cc3"><rect x="384" y="62" width="148" height="124" rx="12"/></clipPath>
+ <clipPath id="cc4"><rect x="574" y="70" width="130" height="100" rx="12"/></clipPath>
+ <clipPath id="cc5"><rect x="750" y="70" width="94" height="100" rx="12"/></clipPath>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="860" height="240" fill="#f1f5f9" rx="16"/>
+<text x="430" y="32" text-anchor="middle" font-size="13" font-weight="700" fill="#334155">GraphRAG — Graph-Augmented Retrieval Flow</text>
+
+<!-- ── BOX 1: User Query ── -->
+<rect x="18" y="70" width="130" height="100" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="18" y="70" width="130" height="38" fill="url(#g1)" clip-path="url(#cc1)"/>
+<text x="83" y="88" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">QUERY</text>
+<text x="83" y="104" text-anchor="middle" font-size="12" font-weight="700" fill="white">User Query</text>
+<text x="83" y="135" text-anchor="middle" font-size="11" fill="#475569">"Who founded</text>
+<text x="83" y="151" text-anchor="middle" font-size="11" fill="#475569">Apple Inc.?"</text>
+
+<!-- Arrow from Query → Retrieve (splits to 2) -->
+<line x1="148" y1="99" x2="176" y2="86" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="148" y1="121" x2="176" y2="154" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── BOX 2a: Vector Search ── -->
+<rect x="184" y="62" width="160" height="56" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="184" y="62" width="160" height="24" fill="url(#g2)" clip-path="url(#cc2a)"/>
+<text x="264" y="77" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">Vector Search</text>
+<text x="264" y="100" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Embedding similarity</text>
+<text x="264" y="113" text-anchor="middle" font-size="9.5" fill="#64748b">top-k semantic matches</text>
+
+<!-- ── BOX 2b: Graph Traversal ── -->
+<rect x="184" y="130" width="160" height="56" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="184" y="130" width="160" height="24" fill="url(#g3)" clip-path="url(#cc2b)"/>
+<text x="264" y="145" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">Graph Traversal</text>
+<text x="264" y="168" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Relation paths + context</text>
+<text x="264" y="181" text-anchor="middle" font-size="9.5" fill="#64748b">entity neighborhood</text>
+
+<!-- Arrows from Retrieve → Context Builder -->
+<line x1="344" y1="90" x2="376" y2="112" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="344" y1="158" x2="376" y2="136" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── BOX 3: Context Builder ── -->
+<rect x="384" y="62" width="148" height="124" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="384" y="62" width="148" height="38" fill="url(#g3)" clip-path="url(#cc3)"/>
+<text x="458" y="80" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">CONTEXT</text>
+<text x="458" y="96" text-anchor="middle" font-size="12" font-weight="700" fill="white">Build Context</text>
+<text x="458" y="124" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Merge vectors + graph</text>
+<text x="458" y="140" text-anchor="middle" font-size="9.5" fill="#64748b">rank by relevance</text>
+<text x="458" y="156" text-anchor="middle" font-size="9.5" fill="#64748b">attach source links</text>
+<text x="458" y="172" text-anchor="middle" font-size="9.5" fill="#64748b">provenance metadata</text>
+
+<!-- Arrow Context → LLM -->
+<line x1="532" y1="124" x2="566" y2="120" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── BOX 4: LLM Generation ── -->
+<rect x="574" y="70" width="130" height="100" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="574" y="70" width="130" height="38" fill="url(#g1)" clip-path="url(#cc4)"/>
+<text x="639" y="88" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">GENERATE</text>
+<text x="639" y="104" text-anchor="middle" font-size="12" font-weight="700" fill="white">LLM</text>
+<text x="639" y="131" text-anchor="middle" font-size="10.5" fill="#334155" font-weight="600">Grounded generation</text>
+<text x="639" y="147" text-anchor="middle" font-size="9.5" fill="#64748b">context-aware answer</text>
+<text x="639" y="161" text-anchor="middle" font-size="9.5" fill="#64748b">no hallucination</text>
+
+<!-- Arrow LLM → Answer -->
+<line x1="704" y1="120" x2="742" y2="120" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── BOX 5: Answer ── -->
+<rect x="750" y="70" width="94" height="100" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="750" y="70" width="94" height="38" fill="url(#g4)" clip-path="url(#cc5)"/>
+<text x="797" y="88" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">ANSWER</text>
+<text x="797" y="104" text-anchor="middle" font-size="12" font-weight="700" fill="white">Output</text>
+<text x="797" y="132" text-anchor="middle" font-size="10" fill="#334155" font-weight="600">Traceable</text>
+<text x="797" y="147" text-anchor="middle" font-size="10" fill="#334155" font-weight="600">answer</text>
+<text x="797" y="162" text-anchor="middle" font-size="9.5" fill="#64748b">+ source nodes</text>
+
+<!-- Bottom label -->
+<text x="430" y="220" text-anchor="middle" font-size="10" fill="#94a3b8">Every claim links back to a source node — no black-box outputs</text>
+</svg>
diff --git a/docs/assets/img/diagrams/kg-structure.svg b/docs/assets/img/diagrams/kg-structure.svg
new file mode 100644
index 00000000..47e6b659
--- /dev/null
+++ b/docs/assets/img/diagrams/kg-structure.svg
@@ -0,0 +1,90 @@
+<svg viewBox="0 0 700 360" xmlns="http://www.w3.org/2000/svg">
+<title>Knowledge Graph Structure</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-15%" y="-15%" width="130%" height="130%">
+ <feDropShadow dx="0" dy="3" stdDeviation="6" flood-color="#00000014"/>
+ </filter>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="700" height="360" fill="#f1f5f9" rx="16"/>
+
+<!-- Title -->
+<text x="350" y="30" text-anchor="middle" font-size="13" font-weight="700" fill="#334155">Knowledge Graph — Entity &amp; Relation Structure</text>
+
+<!-- ── EDGES (drawn first, under nodes) ── -->
+
+<!-- Steve Jobs → Apple Inc. "founded" -->
+<line x1="222" y1="158" x2="345" y2="100" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="240" y="114" width="64" height="20" rx="4" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+<text x="272" y="128" text-anchor="middle" font-size="10" font-weight="600" fill="#4f46e5">founded</text>
+
+<!-- Steve Jobs → Cupertino "connected_to" -->
+<line x1="224" y1="178" x2="430" y2="238" stroke="#94a3b8" stroke-width="1.5" stroke-dasharray="5,3" marker-end="url(#arr)"/>
+<rect x="285" y="195" width="90" height="20" rx="4" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+<text x="330" y="209" text-anchor="middle" font-size="10" font-weight="600" fill="#64748b">connected_to</text>
+
+<!-- Apple Inc. → Cupertino "located_in" -->
+<line x1="448" y1="118" x2="456" y2="220" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="420" y="162" width="72" height="20" rx="4" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+<text x="456" y="176" text-anchor="middle" font-size="10" font-weight="600" fill="#059669">located_in</text>
+
+<!-- Steve Jobs → 1976 "born" -->
+<line x1="148" y1="202" x2="178" y2="280" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="106" y="234" width="52" height="20" rx="4" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+<text x="132" y="248" text-anchor="middle" font-size="10" font-weight="600" fill="#d97706">born_in</text>
+
+<!-- Apple Inc. → 1976 "founded_in" -->
+<line x1="380" y1="120" x2="248" y2="284" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+<rect x="282" y="195" width="76" height="20" rx="4" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+
+<!-- ── NODES (drawn on top of edges) ── -->
+
+<!-- Node: Steve Jobs (PERSON) — center left (150, 170) -->
+<rect x="50" y="144" width="160" height="52" rx="26" fill="#4f46e5" filter="url(#sh)"/>
+<rect x="50" y="144" width="160" height="52" rx="26" fill="none" stroke="#6366f1" stroke-width="1.5"/>
+<text x="130" y="167" text-anchor="middle" font-size="12.5" font-weight="700" fill="white">Steve Jobs</text>
+<text x="130" y="184" text-anchor="middle" font-size="10" fill="white" opacity="0.75">PERSON</text>
+
+<!-- Node: Apple Inc. (ORGANIZATION) — top right (400, 90) -->
+<rect x="308" y="64" width="176" height="52" rx="26" fill="#7c3aed" filter="url(#sh)"/>
+<rect x="308" y="64" width="176" height="52" rx="26" fill="none" stroke="#8b5cf6" stroke-width="1.5"/>
+<text x="396" y="87" text-anchor="middle" font-size="12.5" font-weight="700" fill="white">Apple Inc.</text>
+<text x="396" y="104" text-anchor="middle" font-size="10" fill="white" opacity="0.75">ORGANIZATION</text>
+
+<!-- Node: Cupertino (LOCATION) — right (486, 246) -->
+<rect x="394" y="220" width="160" height="52" rx="26" fill="#059669" filter="url(#sh)"/>
+<rect x="394" y="220" width="160" height="52" rx="26" fill="none" stroke="#10b981" stroke-width="1.5"/>
+<text x="474" y="243" text-anchor="middle" font-size="12.5" font-weight="700" fill="white">Cupertino</text>
+<text x="474" y="260" text-anchor="middle" font-size="10" fill="white" opacity="0.75">LOCATION</text>
+
+<!-- Node: 1976 (DATE) — bottom left (200, 296) -->
+<rect x="118" y="270" width="130" height="52" rx="26" fill="#d97706" filter="url(#sh)"/>
+<rect x="118" y="270" width="130" height="52" rx="26" fill="none" stroke="#f59e0b" stroke-width="1.5"/>
+<text x="183" y="293" text-anchor="middle" font-size="12.5" font-weight="700" fill="white">1976</text>
+<text x="183" y="310" text-anchor="middle" font-size="10" fill="white" opacity="0.75">DATE</text>
+
+<!-- ── LEGEND ── -->
+<rect x="36" y="48" width="80" height="18" rx="9" fill="#eef2ff"/>
+<circle cx="50" cy="57" r="5" fill="#4f46e5"/>
+<text x="60" y="61" font-size="10" fill="#4f46e5" font-weight="600">PERSON</text>
+
+<rect x="126" y="48" width="110" height="18" rx="9" fill="#f5f3ff"/>
+<circle cx="140" cy="57" r="5" fill="#7c3aed"/>
+<text x="150" y="61" font-size="10" fill="#7c3aed" font-weight="600">ORGANIZATION</text>
+
+<rect x="246" y="48" width="90" height="18" rx="9" fill="#ecfdf5"/>
+<circle cx="260" cy="57" r="5" fill="#059669"/>
+<text x="270" y="61" font-size="10" fill="#059669" font-weight="600">LOCATION</text>
+
+<rect x="346" y="48" width="60" height="18" rx="9" fill="#fffbeb"/>
+<circle cx="360" cy="57" r="5" fill="#d97706"/>
+<text x="370" y="61" font-size="10" fill="#d97706" font-weight="600">DATE</text>
+
+<rect x="416" y="48" width="148" height="18" rx="9" fill="#f8fafc"/>
+<line x1="430" y1="57" x2="450" y2="57" stroke="#94a3b8" stroke-width="1.5" stroke-dasharray="4,2"/>
+<text x="456" y="61" font-size="10" fill="#64748b" font-weight="600">inferred relation</text>
+</svg>
diff --git a/docs/assets/img/diagrams/pipeline-flow.svg b/docs/assets/img/diagrams/pipeline-flow.svg
new file mode 100644
index 00000000..a8038810
--- /dev/null
+++ b/docs/assets/img/diagrams/pipeline-flow.svg
@@ -0,0 +1,85 @@
+<svg viewBox="0 0 900 112" xmlns="http://www.w3.org/2000/svg">
+<title>Semantica Pipeline Flow</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-10%" y="-20%" width="120%" height="140%">
+ <feDropShadow dx="0" dy="2" stdDeviation="4" flood-color="#00000014"/>
+ </filter>
+ <marker id="arr" markerWidth="7" markerHeight="6" refX="6" refY="3" orient="auto">
+ <polygon points="0 0, 7 3, 0 6" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="900" height="112" fill="#f1f5f9" rx="12"/>
+
+<!-- Step 1: Ingest (#4f46e5) x=12 -->
+<rect x="12" y="18" width="96" height="76" rx="10" fill="#4f46e5" filter="url(#sh)"/>
+<rect x="12" y="18" width="96" height="28" rx="10" fill="#4338ca"/>
+<rect x="12" y="36" width="96" height="10" fill="#4338ca"/>
+<text x="60" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">01</text>
+<text x="60" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Ingest</text>
+<text x="60" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">FileIngestor</text>
+<line x1="108" y1="56" x2="122" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 2: Parse (#7c3aed) x=124 -->
+<rect x="124" y="18" width="96" height="76" rx="10" fill="#7c3aed" filter="url(#sh)"/>
+<rect x="124" y="18" width="96" height="28" rx="10" fill="#6d28d9"/>
+<rect x="124" y="36" width="96" height="10" fill="#6d28d9"/>
+<text x="172" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">02</text>
+<text x="172" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Parse</text>
+<text x="172" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">DocumentParser</text>
+<line x1="220" y1="56" x2="234" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 3: Normalize (#9333ea) x=236 -->
+<rect x="236" y="18" width="96" height="76" rx="10" fill="#9333ea" filter="url(#sh)"/>
+<rect x="236" y="18" width="96" height="28" rx="10" fill="#7e22ce"/>
+<rect x="236" y="36" width="96" height="10" fill="#7e22ce"/>
+<text x="284" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">03</text>
+<text x="284" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Normalize</text>
+<text x="284" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">TextNormalizer</text>
+<line x1="332" y1="56" x2="346" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 4: Extract (#2563eb) x=348 -->
+<rect x="348" y="18" width="96" height="76" rx="10" fill="#2563eb" filter="url(#sh)"/>
+<rect x="348" y="18" width="96" height="28" rx="10" fill="#1d4ed8"/>
+<rect x="348" y="36" width="96" height="10" fill="#1d4ed8"/>
+<text x="396" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">04</text>
+<text x="396" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Extract</text>
+<text x="396" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">NERExtractor</text>
+<line x1="444" y1="56" x2="458" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 5: Build KG (#0891b2) x=460 -->
+<rect x="460" y="18" width="96" height="76" rx="10" fill="#0891b2" filter="url(#sh)"/>
+<rect x="460" y="18" width="96" height="28" rx="10" fill="#0e7490"/>
+<rect x="460" y="36" width="96" height="10" fill="#0e7490"/>
+<text x="508" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">05</text>
+<text x="508" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Build KG</text>
+<text x="508" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">GraphBuilder</text>
+<line x1="556" y1="56" x2="570" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 6: QA (#0f766e) x=572 -->
+<rect x="572" y="18" width="96" height="76" rx="10" fill="#0f766e" filter="url(#sh)"/>
+<rect x="572" y="18" width="96" height="28" rx="10" fill="#0d5e57"/>
+<rect x="572" y="36" width="96" height="10" fill="#0d5e57"/>
+<text x="620" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">06</text>
+<text x="620" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">QA</text>
+<text x="620" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">ConflictDetector</text>
+<line x1="668" y1="56" x2="682" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 7: Store (#059669) x=684 -->
+<rect x="684" y="18" width="96" height="76" rx="10" fill="#059669" filter="url(#sh)"/>
+<rect x="684" y="18" width="96" height="28" rx="10" fill="#047857"/>
+<rect x="684" y="36" width="96" height="10" fill="#047857"/>
+<text x="732" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">07</text>
+<text x="732" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Store</text>
+<text x="732" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">VectorStore</text>
+<line x1="780" y1="56" x2="794" y2="56" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- Step 8: Deliver (#d97706) x=796 -->
+<rect x="796" y="18" width="96" height="76" rx="10" fill="#d97706" filter="url(#sh)"/>
+<rect x="796" y="18" width="96" height="28" rx="10" fill="#b45309"/>
+<rect x="796" y="36" width="96" height="10" fill="#b45309"/>
+<text x="844" y="33" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.75" letter-spacing="0.5">08</text>
+<text x="844" y="58" text-anchor="middle" font-size="12" font-weight="700" fill="white">Deliver</text>
+<text x="844" y="74" text-anchor="middle" font-size="9.5" fill="white" opacity="0.7">AgentContext</text>
+</svg>
diff --git a/docs/assets/img/diagrams/reasoning-chain.svg b/docs/assets/img/diagrams/reasoning-chain.svg
new file mode 100644
index 00000000..f482daec
--- /dev/null
+++ b/docs/assets/img/diagrams/reasoning-chain.svg
@@ -0,0 +1,90 @@
+<svg viewBox="0 0 800 280" xmlns="http://www.w3.org/2000/svg">
+<title>Reasoning and Inference Chain</title>
+<defs>
+ <style>text{font-family:Inter,system-ui,-apple-system,sans-serif}</style>
+ <filter id="sh" x="-12%" y="-12%" width="124%" height="130%">
+ <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00000012"/>
+ </filter>
+ <linearGradient id="g-fact" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#38bdf8"/><stop offset="100%" stop-color="#0284c7"/>
+ </linearGradient>
+ <linearGradient id="g-rule" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#a78bfa"/><stop offset="100%" stop-color="#7c3aed"/>
+ </linearGradient>
+ <linearGradient id="g-inf" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#34d399"/><stop offset="100%" stop-color="#059669"/>
+ </linearGradient>
+ <linearGradient id="g-exp" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0%" stop-color="#fb923c"/><stop offset="100%" stop-color="#ea580c"/>
+ </linearGradient>
+ <clipPath id="cf1"><rect x="20" y="60" width="176" height="68" rx="10"/></clipPath>
+ <clipPath id="cf2"><rect x="20" y="152" width="176" height="68" rx="10"/></clipPath>
+ <clipPath id="cr"><rect x="270" y="90" width="176" height="100" rx="12"/></clipPath>
+ <clipPath id="ci"><rect x="516" y="60" width="176" height="68" rx="10"/></clipPath>
+ <clipPath id="ce"><rect x="516" y="152" width="176" height="68" rx="10"/></clipPath>
+ <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+ <polygon points="0 0, 9 3.5, 0 7" fill="#94a3b8"/>
+ </marker>
+</defs>
+
+<rect width="800" height="280" fill="#f1f5f9" rx="16"/>
+<text x="400" y="30" text-anchor="middle" font-size="13" font-weight="700" fill="#334155">Reasoning Engine — Forward Chaining Inference</text>
+
+<!-- ── FACT 1 ── -->
+<rect x="20" y="60" width="176" height="68" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="20" y="60" width="176" height="26" fill="url(#g-fact)" clip-path="url(#cf1)"/>
+<text x="108" y="76" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">KNOWN FACT</text>
+<text x="108" y="104" text-anchor="middle" font-size="11" fill="#334155" font-weight="600">Steve Jobs</text>
+<text x="108" y="120" text-anchor="middle" font-size="10.5" fill="#64748b">founded Apple Inc.</text>
+
+<!-- ── FACT 2 ── -->
+<rect x="20" y="152" width="176" height="68" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="20" y="152" width="176" height="26" fill="url(#g-fact)" clip-path="url(#cf2)"/>
+<text x="108" y="168" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">KNOWN FACT</text>
+<text x="108" y="196" text-anchor="middle" font-size="11" fill="#334155" font-weight="600">Apple Inc.</text>
+<text x="108" y="212" text-anchor="middle" font-size="10.5" fill="#64748b">headquartered in Cupertino</text>
+
+<!-- Arrows: Facts → Rule Engine -->
+<line x1="196" y1="100" x2="262" y2="128" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<line x1="196" y1="186" x2="262" y2="158" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- "Facts" label -->
+<text x="108" y="50" text-anchor="middle" font-size="10" font-weight="600" fill="#0891b2">Base Facts</text>
+
+<!-- ── RULE ENGINE ── -->
+<rect x="270" y="90" width="176" height="100" rx="12" fill="white" filter="url(#sh)"/>
+<rect x="270" y="90" width="176" height="32" fill="url(#g-rule)" clip-path="url(#cr)"/>
+<text x="358" y="107" text-anchor="middle" font-size="9" font-weight="700" fill="white" opacity="0.8" letter-spacing="1">RULE ENGINE</text>
+<text x="358" y="120" text-anchor="middle" font-size="12" font-weight="700" fill="white">IF / THEN Rule</text>
+<text x="358" y="148" text-anchor="middle" font-size="10" fill="#334155">IF ?x founded ?y</text>
+<text x="358" y="163" text-anchor="middle" font-size="10" fill="#334155">AND ?y located_in ?z</text>
+<text x="358" y="178" text-anchor="middle" font-size="10" fill="#334155">THEN ?x connected_to ?z</text>
+
+<!-- Arrow Rule → Inference -->
+<line x1="446" y1="130" x2="508" y2="106" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+<!-- Arrow Rule → Explanation -->
+<line x1="446" y1="150" x2="508" y2="182" stroke="#cbd5e1" stroke-width="1.5" marker-end="url(#arr)"/>
+
+<!-- ── DERIVED FACT ── -->
+<rect x="516" y="60" width="260" height="68" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="516" y="60" width="260" height="26" fill="url(#g-inf)" clip-path="url(#ci)"/>
+<text x="646" y="76" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">DERIVED FACT</text>
+<text x="646" y="104" text-anchor="middle" font-size="11" fill="#334155" font-weight="600">Steve Jobs connected_to Cupertino</text>
+<text x="646" y="120" text-anchor="middle" font-size="10" fill="#059669">confidence: 0.91 · derived via rule #3</text>
+
+<!-- ── EXPLANATION PATH ── -->
+<rect x="516" y="152" width="260" height="68" rx="10" fill="white" filter="url(#sh)"/>
+<rect x="516" y="152" width="260" height="26" fill="url(#g-exp)" clip-path="url(#ce)"/>
+<text x="646" y="168" text-anchor="middle" font-size="9.5" font-weight="700" fill="white">EXPLANATION PATH</text>
+<text x="646" y="196" text-anchor="middle" font-size="10.5" fill="#334155">Jobs→founded→Apple→located_in→Cupertino</text>
+<text x="646" y="212" text-anchor="middle" font-size="10" fill="#64748b">traceable steps · not a black box</text>
+
+<!-- Output labels -->
+<text x="646" y="50" text-anchor="middle" font-size="10" font-weight="600" fill="#059669">Derived Knowledge</text>
+
+<!-- Engine label -->
+<text x="358" y="82" text-anchor="middle" font-size="10" font-weight="600" fill="#7c3aed">Rete · Forward Chain · Datalog</text>
+
+<!-- Bottom note -->
+<text x="400" y="264" text-anchor="middle" font-size="10" fill="#94a3b8">Every derived fact ships with a traceable explanation path — zero black-box conclusions</text>
+</svg>
diff --git a/docs/assets/img/semantica-wordmark-dark.svg b/docs/assets/img/semantica-wordmark-dark.svg
new file mode 100644
index 00000000..ba58497b
--- /dev/null
+++ b/docs/assets/img/semantica-wordmark-dark.svg
@@ -0,0 +1,12 @@
+<svg viewBox="0 0 168 36" xmlns="http://www.w3.org/2000/svg" fill="none">
+ <title>Semantica</title>
+ <!-- Icon: green rounded square with S -->
+ <rect width="36" height="36" rx="8" fill="#10b981"/>
+ <text x="18" y="26" text-anchor="middle"
+ font-family="system-ui,-apple-system,'Segoe UI',sans-serif"
+ font-size="22" font-weight="800" fill="#0A0A0A" letter-spacing="-0.5">S</text>
+ <!-- Wordmark: Semantica in bright green for dark bg -->
+ <text x="46" y="25"
+ font-family="system-ui,-apple-system,'Segoe UI',sans-serif"
+ font-size="18.5" font-weight="700" fill="#10b981" letter-spacing="-0.3">Semantica</text>
+</svg>
diff --git a/docs/assets/img/semantica-wordmark-light.svg b/docs/assets/img/semantica-wordmark-light.svg
new file mode 100644
index 00000000..bc207671
--- /dev/null
+++ b/docs/assets/img/semantica-wordmark-light.svg
@@ -0,0 +1,12 @@
+<svg viewBox="0 0 168 36" xmlns="http://www.w3.org/2000/svg" fill="none">
+ <title>Semantica</title>
+ <!-- Icon: green rounded square with S -->
+ <rect width="36" height="36" rx="8" fill="#059669"/>
+ <text x="18" y="26" text-anchor="middle"
+ font-family="system-ui,-apple-system,'Segoe UI',sans-serif"
+ font-size="22" font-weight="800" fill="white" letter-spacing="-0.5">S</text>
+ <!-- Wordmark: Semantica in green -->
+ <text x="46" y="25"
+ font-family="system-ui,-apple-system,'Segoe UI',sans-serif"
+ font-size="18.5" font-weight="700" fill="#059669" letter-spacing="-0.3">Semantica</text>
+</svg>
diff --git a/docs/concepts.md b/docs/concepts.md
index 88eaa595..107d6059 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -14,6 +14,8 @@ At its core, Semantica adds a **context and intelligence layer** on top of your
## Knowledge Graphs
+<img src="/assets/img/diagrams/kg-structure.svg" alt="Knowledge graph node and edge structure showing entities (Person, Organization, Location, Date) and their typed relations" style={{ width: '100%', borderRadius: '12px', margin: '0 0 20px' }} />
+
The foundation of everything in Semantica. A knowledge graph stores information as three building blocks:
- **Nodes (entities)** — people, companies, locations, events, concepts
@@ -76,6 +78,8 @@ Semantica uses embeddings for:
GraphRAG (Graph-Augmented Retrieval Augmented Generation) enhances LLM responses by grounding them in a structured knowledge graph rather than raw text chunks alone.
+<img src="/assets/img/diagrams/graphrag-flow.svg" alt="GraphRAG flow: User Query → Vector Search + Graph Traversal → Context Builder → LLM → Grounded Answer" style={{ width: '100%', borderRadius: '12px', margin: '16px 0 20px' }} />
+
**How it works:**
1. User submits a query
diff --git a/docs/docs.json b/docs/docs.json
index c2ffe747..a1813096 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -10,8 +10,8 @@
},
"favicon": "/assets/img/semantica-logo.png",
"logo": {
- "light": "/assets/img/semantica-logo.png",
- "dark": "/assets/img/semantica-logo.png"
+ "light": "/assets/img/semantica-wordmark-light.svg",
+ "dark": "/assets/img/semantica-wordmark-dark.svg"
},
"font": {
"headings": {
diff --git a/docs/index.md b/docs/index.md
index d4845ac2..ec684db1 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -34,6 +34,8 @@ Semantica is the **accountability and context layer** you add on top of your exi
Works alongside any LLM provider and any agent framework.
+<img src="/assets/img/diagrams/architecture-overview.svg" alt="Semantica four-layer architecture: Ingestion → Processing → Intelligence → Application" style={{ width: '100%', borderRadius: '12px', margin: '24px 0' }} />
+
## Quick Start
```bash
diff --git a/docs/quickstart.md b/docs/quickstart.md
index ae68c050..dfb11686 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -39,6 +39,8 @@ python -c "import semantica; print(semantica.__version__)"
## Full Pipeline
+<img src="/assets/img/diagrams/pipeline-flow.svg" alt="Semantica end-to-end pipeline: Ingest → Parse → Normalize → Extract → Build KG → QA → Store → Deliver" style={{ width: '100%', borderRadius: '10px', margin: '0 0 24px' }} />
+
<Steps>
<Step title="Ingest">
diff --git a/docs/reference/context.md b/docs/reference/context.md
index 02b7d411..44042e70 100644
--- a/docs/reference/context.md
+++ b/docs/reference/context.md
@@ -15,6 +15,8 @@ icon: "brain"
- **`CausalAnalyzer`** — traces downstream impact of any decision
- **`PolicyEngine`** — validates decisions against configurable rules before they're recorded
+<img src="/assets/img/diagrams/agent-context-flow.svg" alt="AgentContext hub: AI Agent calls store/retrieve against VectorStore and record_decision against ContextGraph" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />
+
## AgentContext
The main entry point. Wraps memory, graph, and decision tracking behind a single API.
diff --git a/docs/reference/kg.md b/docs/reference/kg.md
index 09d4d327..f823bf6d 100644
--- a/docs/reference/kg.md
+++ b/docs/reference/kg.md
@@ -21,6 +21,8 @@ icon: "diagram-project"
For conflict detection and advanced entity resolution, use `semantica.conflicts` and `semantica.deduplication` alongside this module.
</Tip>
+<img src="/assets/img/diagrams/kg-structure.svg" alt="Knowledge graph entity and relation structure: Person, Organization, Location, Date nodes with typed labeled edges" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />
+
## GraphBuilder
Constructs knowledge graphs from extracted entities and relationships:
diff --git a/docs/reference/pipeline.md b/docs/reference/pipeline.md
index be9c7d9b..32723a7f 100644
--- a/docs/reference/pipeline.md
+++ b/docs/reference/pipeline.md
@@ -14,6 +14,8 @@ icon: "gear"
- **`FailureHandler`** — skip, stop, or retry failed documents without halting the pipeline
- **Progress tracking** — console (tqdm), WebSocket streaming, or file logging
+<img src="/assets/img/diagrams/pipeline-flow.svg" alt="Pipeline step sequence: Ingest → Parse → Normalize → Extract → Build KG → QA → Store → Deliver" style={{ width: '100%', borderRadius: '10px', margin: '0 0 24px' }} />
+
## Basic Pipeline
```python
diff --git a/docs/reference/reasoning.md b/docs/reference/reasoning.md
index 9012abbb..876e67b8 100644
--- a/docs/reference/reasoning.md
+++ b/docs/reference/reasoning.md
@@ -16,6 +16,8 @@ icon: "microchip"
- **`TemporalReasoningEngine`** — all 13 Allen interval algebra relations for time-aware inference
- **`ExplanationGenerator`** — structured explanation paths for every derived conclusion
+<img src="/assets/img/diagrams/reasoning-chain.svg" alt="Forward chaining inference: known facts + IF/THEN rules produce derived facts with a full traceable explanation path" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />
+
## Reasoner (Main Facade)
The unified entry point for rule-based forward-chaining inference:
diff --git a/docs/reference/semantic_extract.md b/docs/reference/semantic_extract.md
index b3f1cd18..63ff85ae 100644
--- a/docs/reference/semantic_extract.md
+++ b/docs/reference/semantic_extract.md
@@ -14,6 +14,8 @@ icon: "magnifying-glass-chart"
- **`EventExtractor`** — event detection with participants, temporal context, and confidence scores
- **`CoreferenceResolver`** — resolve "Apple" and "the company" to the same entity across a document
+<img src="/assets/img/diagrams/extraction-pipeline.svg" alt="Semantic extraction pipeline: raw text fans into NER, Relation, and Coreference extractors, then merges into a Triplet Generator" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />
+
## NERExtractor
```python