correct schema

* docs(getting-started): fix broken APIs in KG and GraphRAG tabs

* docs: tighten GraphRAG example

* docs: use extract_text() so the PDF example doesn't keyError

docs/getting-started.md

@@ -84,13 +84,13 @@ icon: "rocket"
     # 1. Ingest
     sources = FileIngestor().ingest("data/report.pdf")
 
-    # 2. Parse
-    parsed = DocumentParser().parse(sources[0])
+    # 2. Parse (extract_text returns a plain string for any supported format)
+    text = DocumentParser().extract_text(sources[0].path)
 
-    # 3. Extract
+    # 3. Extract (extractors take text, return Entity / Relation objects)
     ner           = NERExtractor(method="pattern")  # no API key needed
-    entities      = ner.extract(parsed)
-    relationships = RelationExtractor().extract(parsed, entities=entities)
+    entities      = ner.extract(text)
+    relationships = RelationExtractor(method="pattern").extract(text, entities=entities)
 
     # 4. Build
     graph = GraphBuilder(merge_entities=True).build(
@@ -144,23 +144,31 @@ icon: "rocket"
     context = AgentContext(
         vector_store=VectorStore(backend="faiss", dimension=768),
         knowledge_graph=ContextGraph(advanced_analytics=True),
+        graph_expansion=True,       # blend graph traversal into retrieval
+        max_expansion_hops=3,       # how far to walk from the seed nodes
     )
 
-    # Load your knowledge graph
-    context.load_graph("company_kg.json")
+    # store() runs extraction and populates both the vector index and the graph
+    context.store([
+        {"content": "Steve Wozniak co-founded Apple with Steve Jobs in 1976."},
+        {"content": "Tony Fadell led the iPod team at Apple, then founded Nest."},
+    ])
 
-    # Multi-hop GraphRAG query
-    result = context.query(
+    # GraphRAG retrieval: seed from vector matches, expand along graph edges
+    results = context.retrieve(
         "What companies were founded by people who worked at Apple?",
-        mode="graphrag",
-        reasoning=True,
+        use_graph=True,
+        expand_graph=True,
     )
-
-    # Every claim links back to a source node
-    for claim in result.claims:
-        print(f"{claim.text}  →  source: {claim.source_node}")
+    for r in results:
+        print(f"[{r['score']:.3f}]  {r['content'][:70]}  (source: {r['source']})")
     ```
 
+    Each result carries `content`, `score`, `source`, and `metadata`. For a
+    grounded natural-language answer plus an auditable traversal, use
+    `context.query_with_reasoning(query, llm_provider=...)` — it returns
+    `response`, `reasoning_path`, `sources`, and `confidence`.
+
     **Next:** [GraphRAG concepts →](/concepts#graphrag)
   </Tab>
 

docs/quickstart.md

@@ -78,11 +78,13 @@ from semantica.parse import DocumentParser
 parser = DocumentParser()
 parsed = parser.parse(sources[0].path)   # parse() takes a path string
 
-print(parsed["text"][:200])   # extracted text
-print(parsed["metadata"])     # file_path, encoding, size, and format-specific keys
+print(parsed["full_text"][:200])   # extracted text
+print(parsed["metadata"])          # document properties (fields vary by format)
 ```
 
-`parse()` returns a `dict` with `text`, `full_text`, and `metadata` keys.
+`parse()` returns a `dict`. `full_text` and `metadata` are present for every
+format; other keys depend on the parser (`pages` for PDF, `tables` and
+`paragraphs` for DOCX, `tables` for `DoclingParser`).
 
 <Tip>
   For PDFs with tables, charts, or multi-column layouts, use `DoclingParser` (`pip install semantica[parse-docling]`): it applies advanced layout analysis and returns structured table data alongside text.
@@ -107,7 +109,7 @@ Identify named entities and extract typed relationships between them.
 ```python Pattern-based (fast, no API key)
 from semantica.semantic_extract import NERExtractor, RelationExtractor
 
-text = parsed["text"]
+text = parsed["full_text"]
 
 ner      = NERExtractor(method="pattern")
 entities = ner.extract(text)
@@ -122,7 +124,7 @@ relationships = rel.extract(text, entities=entities)
 from semantica.semantic_extract import NERExtractor, RelationExtractor
 
 # Reads GROQ_API_KEY from the environment; provider/llm_model select the backend
-text = parsed["text"]
+text = parsed["full_text"]
 
 ner           = NERExtractor(method="llm", provider="groq", llm_model="llama-3.3-70b-versatile")
 entities      = ner.extract(text)
@@ -277,7 +279,7 @@ builder = GraphBuilder(merge_entities=True)
 
 all_entities, all_rels = [], []
 for source in FileIngestor().ingest("data/reports/"):
-    text     = parser.parse(source.path)["text"]
+    text     = parser.parse(source.path)["full_text"]
     entities = ner.extract(text)
     rels     = rel.extract(text, entities=entities)
     all_entities.extend(entities)
@@ -413,7 +415,7 @@ store    = GraphStore(backend="neo4j", uri="bolt://localhost:7687",
 builder  = GraphBuilder(merge_entities=True, graph_store=store)
 
 for info in ingestor.scan_directory("data/reports/", recursive=True):
-    text     = parser.parse(info["path"])["text"]   # one document loaded at a time
+    text     = parser.parse(info["path"])["full_text"]   # one document loaded at a time
     entities = ner.extract(text)
     rels     = rel.extract(text, entities=entities)
     builder.build({"entities": entities, "relationships": rels})