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

# Conflicts:
#	docs/reference/evals.md

docs/concepts.md

@@ -38,19 +38,18 @@ This structure makes knowledge **searchable**, **connectable**, **queryable**, a
 Scanning text to find and classify real-world entities:
 
 ```python
-# "Apple Inc. was founded by Steve Jobs in 1976 in Cupertino."
-[
-    Entity(text="Apple Inc.", label="ORG",    start_char=0,  end_char=10, confidence=0.98),
-    Entity(text="Steve Jobs", label="PERSON", start_char=25, end_char=35, confidence=0.99),
-    Entity(text="1976",       label="DATE",   start_char=39, end_char=43, confidence=0.95),
-    Entity(text="Cupertino",  label="GPE",    start_char=47, end_char=56, confidence=0.97),
-]
+# Input: "Apple Inc. was founded by Steve Jobs in 1976 in Cupertino."
+{
+    "entities": [
+        {"text": "Apple Inc.",  "type": "ORGANIZATION", "confidence": 0.98},
+        {"text": "Steve Jobs",  "type": "PERSON",       "confidence": 0.99},
+        {"text": "1976",        "type": "DATE",         "confidence": 0.95},
+        {"text": "Cupertino",   "type": "LOCATION",     "confidence": 0.97}
+    ]
+}
 ```
 
-`NERExtractor(method=...).extract(text)` returns a list of `Entity` objects, each
-with a `label`, character offsets (`start_char` / `end_char`), a `confidence`
-score, and a `metadata` dict recording the extraction method. Three methods are
-available:
+Each entity gets a type, confidence score, and a link to its source document. Three extraction methods are available:
 
 | Method | Speed | Accuracy | Requirements |
 | :------ | :----- | :-------- | :------------ |
@@ -63,19 +62,15 @@ available:
 Finding how entities connect to each other:
 
 ```python
-jobs  = Entity(text="Steve Jobs", label="PERSON", start_char=25, end_char=35)
-apple = Entity(text="Apple Inc.", label="ORG",    start_char=0,  end_char=10)
-
-[
-    Relation(subject=jobs,  predicate="founded",     object=apple, confidence=0.92),
-    Relation(subject=apple, predicate="located_in",  object=Entity(text="Cupertino", label="GPE", start_char=47, end_char=56), confidence=0.89),
-]
+{
+    "relationships": [
+        {"subject": "Steve Jobs", "predicate": "founded",    "object": "Apple Inc.", "confidence": 0.92},
+        {"subject": "Apple Inc.", "predicate": "located_in", "object": "Cupertino",  "confidence": 0.89}
+    ]
+}
 ```
 
-`RelationExtractor(method=...).extract(text, entities=entities)` returns a list of
-`Relation` objects: typed subject-predicate-object triples (the endpoints are
-`Entity` objects) with confidence scores and source attribution. Extraction runs
-via pattern rules, ML models, or LLMs.
+Relationships can be extracted via rule-based methods, ML models, or LLMs: each producing typed triplets with confidence scores and source attribution.
 
 
 ## Knowledge Graph vs. Vector Store
@@ -99,10 +94,9 @@ Both store information for AI retrieval: but they're built for different jobs.
     ```python
     from semantica.kg import GraphBuilder, PathFinder
 
-    graph = GraphBuilder(merge_entities=True).build(
-        {"entities": entities, "relationships": rels}
-    )
-    path  = PathFinder().dijkstra_shortest_path(graph, "Steve Jobs", "Tim Cook")
+    graph   = GraphBuilder(merge_entities=True).build(entities=entities, relationships=rels)
+    finder  = PathFinder()
+    path    = finder.dijkstra_shortest_path(graph, "Steve Jobs", "Tim Cook")
     ```
   </Tab>
 
@@ -146,16 +140,8 @@ Both store information for AI retrieval: but they're built for different jobs.
     context = AgentContext(
         vector_store=VectorStore(backend="faiss", dimension=768),
         knowledge_graph=ContextGraph(advanced_analytics=True),
-        graph_expansion=True,
     )
-
-    # store() extracts entities and populates the graph + vector index
-    context.store([{"content": "Steve Jobs co-founded Apple Inc. in 1976."}])
-
-    # retrieve() blends vector similarity with graph traversal
-    results = context.retrieve("Who founded Apple?", use_graph=True, expand_graph=True)
-    for r in results:
-        print(r["score"], r["content"], r["source"])
+    result = context.query("Who founded Apple?", mode="graphrag")
     ```
   </Tab>
 </Tabs>
@@ -235,80 +221,70 @@ Inferred: Steve Jobs has a connection to Cupertino
     Applies IF/THEN rules repeatedly until no new facts can be derived. Best for alert systems, compliance checks, and trigger-based workflows.
 
     ```python
-    from semantica.reasoning import Reasoner
+    from semantica.reasoning import Reasoner, Rule, Fact, RuleType
 
     engine = Reasoner()
-    engine.add_fact("Manager(Alice)")
-    engine.add_rule("IF Manager(?x) THEN HasAuthority(?x)")
-
-    results = engine.forward_chain()   # list of InferenceResult
-    for r in results:
-        print(r.conclusion)           # "HasAuthority(Alice)"
+    engine.add_fact(Fact(subject="Alice", predicate="is_a", obj="Manager"))
+    engine.add_rule(Rule(
+        rule_type=RuleType.FORWARD_CHAIN,
+        conditions=[{"subject": "?x", "predicate": "is_a", "object": "Manager"}],
+        conclusion={"subject": "?x", "predicate": "has_authority", "object": "true"}
+    ))
+    result = engine.infer()
     ```
   </Tab>
   <Tab title="Rete Network">
     Efficient pattern matching for large rule sets: the Rete algorithm avoids re-evaluating rules whose preconditions haven't changed. Best for thousands of rules over millions of facts.
 
     ```python
-    from semantica.reasoning import ReteEngine, Rule, Fact
+    from semantica.reasoning import ReteEngine
 
     engine = ReteEngine()
-    engine.build_network([
-        Rule(rule_id="r1", name="manager_authority",
-             conditions=["Manager(?x)"], conclusion="HasAuthority(?x)"),
-    ])
-    engine.add_fact(Fact(fact_id="f1", predicate="Manager", arguments=["Alice"]))
-
-    matches = engine.match_patterns()
-    results = engine.execute_matches(matches)   # ["HasAuthority(?x)"]
+    engine.load_rules("rules/domain_rules.json")
+    results = engine.run(kg)
     ```
   </Tab>
-  <Tab title="LLM Reasoning">
-    `GraphReasoner` answers open-ended questions over a knowledge graph with an
-    LLM, returning a natural-language answer grounded in the graph's facts. Best
-    for exploratory and investigative questions that fixed rules can't anticipate.
+  <Tab title="Deductive & Abductive">
+    **Deductive**: classical syllogistic reasoning from premises to guaranteed conclusions.
+
+    **Abductive**: infers the most likely explanation for observed evidence. Best for diagnostic and investigative use cases.
 
     ```python
     from semantica.reasoning import GraphReasoner
 
-    reasoner = GraphReasoner(provider="openai", model="gpt-4o-mini")
-    answer = reasoner.reason(kg, "Which suppliers are indirectly exposed to the Acme outage?")
+    graph_reasoner = GraphReasoner(kg)
+    graph_reasoner.add_rule({"if": [{"subject": "?a", "predicate": "parent_of", "object": "?b"}], "then": {"subject": "?a", "predicate": "ancestor_of", "object": "?b"}})
+    inferences = graph_reasoner.infer(kg)
     ```
   </Tab>
   <Tab title="Datalog (v0.4.0)">
     Recursive Horn clause rules with fixpoint semantics: handles transitive closure and recursive relationships that forward chaining cannot express.
 
     ```python
-    from semantica.reasoning import DatalogReasoner
+    from semantica.reasoning import DatalogReasoner, DatalogFact, DatalogRule
 
     reasoner = DatalogReasoner()
-    reasoner.add_fact("parent(alice, bob)")
-    reasoner.add_fact("parent(bob, charlie)")
-    reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
-    reasoner.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")
-
-    reasoner.derive_all()
-    results = reasoner.query("ancestor(alice, ?Z)")   # {"Z": "bob"} and {"Z": "charlie"}, order not guaranteed
+    reasoner.add_fact(DatalogFact("parent", ("alice", "bob")))
+    reasoner.add_rule(DatalogRule("ancestor(?X, ?Y) :- parent(?X, ?Y)."))
+    reasoner.evaluate()
+    results = reasoner.query("ancestor(alice, ?Z)")
     ```
   </Tab>
   <Tab title="Engine Comparison">
 
-    | Engine | Class | Best For |
-    | :------ | :----- | :-------- |
-    | Forward chaining | `Reasoner` | Alert systems, compliance checks |
-    | Rete network | `ReteEngine` | Large rule sets, high fact throughput |
-    | SPARQL expansion | `SPARQLReasoner` | Semantic web, ontology reasoning over RDF |
-    | Datalog (v0.4.0) | `DatalogReasoner` | Transitive closure, graph reachability |
-    | Temporal | `TemporalReasoningEngine` | Allen interval algebra, time-aware inference |
-    | LLM over the graph | `GraphReasoner` | Open-ended, investigative questions |
+    | Engine | Description | Best For |
+    | :------ | :----------- | :-------- |
+    | Forward chaining | Applies rules until fixpoint | Alert systems, compliance checks |
+    | Rete network | Efficient pattern matching | Large rule sets, high fact throughput |
+    | Deductive | Classical syllogistic reasoning | Mathematical and logical inference |
+    | Abductive | Most likely explanation | Diagnostics, investigation |
+    | SPARQL | Query-based inference over RDF | Semantic web, ontology reasoning |
+    | Datalog (v0.4.0) | Recursive Horn clause rules | Transitive closure, graph reachability |
 
   </Tab>
 </Tabs>
 
-`Reasoner.forward_chain()` returns `InferenceResult` objects that carry the rule
-applied (`rule_used`) and the premises it fired on, and `ExplanationGenerator`
-turns one into a step-by-step natural-language justification: reasoning here is
-**not** a black box.
+All engines produce **explainable inference paths**: not black-box conclusions. Every derived fact includes the rules and premises that produced it.
 
 
 ## Temporal Intelligence
@@ -337,16 +313,11 @@ Explore the semantic neighborhood of any entity in your graph: useful for unders
 ```python
 from semantica.kg import SimilarityCalculator
 
-calc = SimilarityCalculator(method="cosine")   # "cosine" | "euclidean" | "manhattan" | "correlation"
-
-# Similarity for every unique pair of node embeddings: {(node_a, node_b): score}
-pairs = calc.pairwise_similarity({"apple": vec_apple, "google": vec_google, "nest": vec_nest})
-
-# Or rank a set of embeddings by closeness to one query vector
-nearest = calc.find_most_similar(embeddings, query_embedding, top_k=10)
+calc   = SimilarityCalculator()
+scores = calc.calculate_similarity(entity_a, entity_b)
 ```
 
-**Features:** N×N semantic distance matrices, ego-mode visualization, distance band classification (`direct` / `near` / `mid-range` / `distant`), embedding cache optimization for large graphs.
+**Features:** N×N semantic distance matrices, ego-mode visualization, distance band classification (`near` / `mid` / `far`), embedding cache optimization for large graphs.
 
 The [Visualization module](/reference/visualization) renders distance matrices as interactive heatmaps and ego-mode neighborhood graphs. The [Explorer](/reference/explorer) embeds distance intelligence directly in the browser dashboard.
 
@@ -370,11 +341,11 @@ Real-world data contains the same entity under many names: "Apple", "Apple Inc."
     ```python
     from semantica.deduplication import DuplicateDetector, EntityMerger
 
-    detector   = DuplicateDetector(similarity_threshold=0.85)
-    candidates = detector.detect_duplicates(entities)
+    detector = DuplicateDetector(similarity_threshold=0.85)
+    duplicates = detector.detect_duplicates(entities)
 
-    merger     = EntityMerger()
-    operations = merger.merge_duplicates(entities, strategy="keep_most_complete")
+    merger = EntityMerger()
+    deduplicated_entities = merger.merge_duplicates(entities)
     ```
   </Tab>
 </Tabs>
@@ -390,21 +361,19 @@ Every fact in Semantica links back to:
 - The **reasoning steps** that produced any inferred fact
 
 <Note>
-  This is W3C PROV-O compliant lineage: suitable for regulated industries that require audit trails (HIPAA, SOX, GDPR, FDA 21 CFR Part 11). `ProvenanceManager.export_prov(format="turtle")` serialises the recorded lineage as PROV-O RDF.
+  This is W3C PROV-O compliant lineage: suitable for regulated industries that require audit trails (HIPAA, SOX, GDPR, FDA 21 CFR Part 11). Use `RDFExporter(include_provenance=True)` to embed provenance inline in any RDF export.
 </Note>
 
 ```python
 from semantica.provenance import ProvenanceManager
 
-prov = ProvenanceManager()
-prov.track_entity("apple_inc", source="report.pdf",
-                  metadata={"extractor": "NamedEntityRecognizer", "confidence": 0.98})
+prov    = ProvenanceManager()
+lineage = prov.get_entity_lineage("apple_inc")
 
-record = prov.get_provenance("apple_inc")   # dict; use get_lineage() for the full chain
-print(record["source_document"])
-print(record["timestamp"])
-print(record["checksum"])
-print(record["metadata"])          # extractor, confidence, and any custom keys
+print(f"Source:    {lineage.source_document}")
+print(f"Method:    {lineage.extraction_method}")
+print(f"Extracted: {lineage.timestamp}")
+print(f"Checksum:  {lineage.checksum}")
 ```
 
 
@@ -487,27 +456,27 @@ Semantica is designed for extension. Any component: ingestor, extractor, graph b
     **Extension points available:** ingestors, parsers, normalizers, extractors, reasoning engines, export formats, vector store backends, graph store backends, visualization renderers.
 
   </Accordion>
-  <Accordion title="MethodRegistry: swap a built-in graph operation for your own">
+  <Accordion title="MethodRegistry: add domain-specific graph operations">
 
-    `method_registry` lets you register an alternative implementation for a
-    knowledge-graph task (`build`, `analyze`, `centrality`, `resolve`, …) under a
-    name, then select it wherever that task runs.
+    `MethodRegistry` lets you register custom methods on knowledge graph objects by name: useful for adding domain-specific graph operations without subclassing.
 
     ```python
-    from semantica.kg import method_registry
-    from semantica.kg.methods import calculate_centrality
+    from semantica.kg import MethodRegistry
 
-    def fast_centrality(graph, **kwargs):
-        """Custom centrality implementation."""
+    registry = MethodRegistry()
+
+    def find_supply_chain_hops(graph, source_node, max_hops=3):
+        """Custom BFS traversal for supply chain graphs."""
         ...
 
-    # register(task, name, func)
-    method_registry.register("centrality", "fast_centrality", fast_centrality)
+    # Register under a string key
+    registry.register("supply_chain_hops", find_supply_chain_hops)
 
-    # The task wrappers consult method_registry, so the name is now selectable:
-    scores = calculate_centrality(kg, method="fast_centrality")
+    # Call by name on any graph object
+    result = registry.call("supply_chain_hops", kg, source_node="Supplier_A", max_hops=5)
 
-    print(method_registry.list_all("centrality"))   # {"centrality": ["fast_centrality", ...]}
+    # List all registered methods
+    print(registry.list_methods())   # ["supply_chain_hops", ...]
     ```
 
   </Accordion>

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)
-    text = DocumentParser().extract_text(sources[0].path)
+    # 2. Parse
+    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)
-    relationships = RelationExtractor(method="pattern").extract(text, entities=entities)
+    entities      = ner.extract(parsed)
+    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
-    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."},
-    ])
+    # Load your knowledge graph
+    context.load_graph("company_kg.json")
 
-    # GraphRAG retrieval: seed from vector matches, expand along graph edges
-    results = context.retrieve(
+    # Multi-hop GraphRAG query
+    result = context.query(
         "What companies were founded by people who worked at Apple?",
-        use_graph=True,
-        expand_graph=True,
+        mode="graphrag",
+        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
-    grounded natural-language answer plus an auditable traversal, use
-    `context.query_with_reasoning(query, llm_provider=...)` — it returns
-    `response`, `reasoning_path`, `sources`, and `confidence`.
+    # Every claim links back to a source node
+    for claim in result.claims:
+        print(f"{claim.text}  →  source: {claim.source_node}")
+    ```
 
     **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["metadata"])          # document properties (fields vary by format)
+print(parsed["text"][:200])   # extracted text
+print(parsed["metadata"])     # file_path, encoding, size, and format-specific 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`).
+`parse()` returns a `dict` with `text`, `full_text`, and `metadata` keys.
 
 <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})