Merge remote-tracking branch 'origin/main' into docs-evals-reference-actual-api

# Conflicts:
#	docs/reference/evals.md

docs/getting-started.md

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

docs/quickstart.md

@@ -78,13 +78,11 @@ from semantica.parse import DocumentParser
 parser = DocumentParser()
 parsed = parser.parse(sources[0].path)   # parse() takes a path string
 
-print(parsed["full_text"][:200])   # extracted text
+print(parsed["text"][:200])   # extracted text
-print(parsed["metadata"])          # document properties (fields vary by format)
+print(parsed["metadata"])     # file_path, encoding, size, and format-specific keys
 ```
 
-`parse()` returns a `dict`. `full_text` and `metadata` are present for every
+`parse()` returns a `dict` with `text`, `full_text`, and `metadata` keys.
-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.
@@ -109,7 +107,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["full_text"]
+text = parsed["text"]
 
 ner      = NERExtractor(method="pattern")
 entities = ner.extract(text)
@@ -124,7 +122,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["full_text"]
+text = parsed["text"]
 
 ner           = NERExtractor(method="llm", provider="groq", llm_model="llama-3.3-70b-versatile")
 entities      = ner.extract(text)
@@ -279,7 +277,7 @@ builder = GraphBuilder(merge_entities=True)
 
 all_entities, all_rels = [], []
 for source in FileIngestor().ingest("data/reports/"):
-    text     = parser.parse(source.path)["full_text"]
+    text     = parser.parse(source.path)["text"]
     entities = ner.extract(text)
     rels     = rel.extract(text, entities=entities)
     all_entities.extend(entities)
@@ -415,7 +413,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"])["full_text"]   # one document loaded at a time
+    text     = parser.parse(info["path"])["text"]   # one document loaded at a time
     entities = ner.extract(text)
     rels     = rel.extract(text, entities=entities)
     builder.build({"entities": entities, "relationships": rels})