Merge branch 'main' into docs-mcp-tool-count-15

docs/faq.md

@@ -16,7 +16,7 @@ icon: "circle-question"
 | Python version? | 3.8+ (3.11+ recommended) |
 | API key required? | Optional: pattern extraction works with no keys |
 | Works with LangChain / LlamaIndex? | Yes: Semantica is a layer on top, not a replacement |
-| Production-ready? | Yes: 1,000+ tests, security fixes shipped in every release (see [CHANGELOG](https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md)) |
+| Production-ready? | Yes: 1,000+ tests, v0.5.0 ships with 12 security fixes |
 | Latest version? | **v0.6.7** (August 2026) |
 | Local LLMs? | Yes: Ollama via LiteLLM, HuggingFaceLLM for air-gapped |
 
@@ -70,9 +70,9 @@ Yes: MIT licensed, no vendor lock-in, no paywalled features. Some capabilities r
 
 <Accordion title="What's the latest version?" icon="star">
 
-**v0.6.7**: released August 2026.
+**v0.5.0**: released May 2026.
 
-Highlights: first-class LangChain integration, SAP OData ingestor, human-editable Markdown round-trip persistence for `ContextGraph`, a structured Action layer for the reasoning engine, and a public `run_shacl_validation` entry point. The 0.6.x line also added first-class CrewAI support and the Semantica RDF vocabulary with deterministic IRIs. See the [CHANGELOG](https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md) for the full history.
+Highlights: Ontology Hub, Distance Intelligence, Parquet/XML ingestion, 12 security fixes, Graph Explorer redesign, NER gateway fix.
 
 ```bash
 pip install --upgrade semantica
@@ -173,7 +173,7 @@ This includes PyTorch with CUDA, FAISS GPU, and CuPy.
 <Accordion title="How does Semantica handle large datasets?" icon="layer-group">
 
 - **Batching**: process documents in configurable chunks to control memory usage
-- **Parallel processing**: `PipelineBuilder().set_parallelism(N)` runs independent pipeline steps concurrently
+- **Parallel processing**: `Pipeline(workers=N)` runs extraction steps concurrently
 - **Delta processing**: update graphs incrementally without full recompute on new data
 - **Persistent backends**: swap in-memory NetworkX for Neo4j, FalkorDB, or Apache AGE for large-scale production graphs
 
@@ -269,13 +269,13 @@ Groq, OpenAI, Anthropic, Google Gemini, Ollama (fully local), DeepSeek, Novita A
 
 <Accordion title="Is Semantica production-ready?" icon="shield-check">
 
-Yes. Every release ships with:
+Yes. v0.5.0 ships with:
 
 - 1,000+ passing tests across Python 3.8–3.12
 - `PipelineValidator` and `FailureHandler` with exponential backoff and configurable retry policies
 - W3C PROV-O provenance tracking across all modules
 - Change management with SHA-256 checksums and full audit trails
-- Ongoing security hardening: eval injection, pickle deserialization, SQL injection, XXE, SSRF, ReDoS, and path traversal fixes have all landed across recent releases (see the [CHANGELOG](https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md) security sections)
+- 12 security vulnerability fixes: eval injection, pickle deserialization, SQL injection, XXE, SSRF, ReDoS, path traversal, and more
 
 </Accordion>
 

docs/index.md

@@ -404,7 +404,7 @@ Semantica was designed for domains where every decision must be explainable and
 - 1,000+ passing tests with full regression coverage
 - `PipelineValidator` catches configuration errors at startup
 - `FailureHandler` with exponential backoff and dead-letter queues
-- Ongoing security hardening: fixes shipped in every release ([CHANGELOG](https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md))
+- 12 security vulnerabilities fixed in v0.5.0
 
 **Modular by Design** — Import only what you need.
 - Use `NERExtractor` without a graph store

docs/quickstart.md

@@ -5,7 +5,7 @@ icon: "rocket"
 ---
 
 <Info>
-  **v0.6.7** — first-class LangChain integration, SAP OData ingestor, human-editable Markdown persistence for `ContextGraph`, and a structured Action layer for the reasoning engine. <a href="https://github.com/semantica-agi/semantica/releases" style={{color:"#10B981",fontWeight:600,textDecoration:"none"}}>What's new →</a>
+  **v0.5.0** — Ontology Hub, Distance Intelligence, Parquet & XML ingestion, 12 security fixes. <a href="https://github.com/semantica-agi/semantica/releases" style={{color:"#10B981",fontWeight:600,textDecoration:"none"}}>What's new →</a>
 </Info>
 
 This guide walks you through the end-to-end pipeline for building your first knowledge graph. Start here after installation. An LLM API key is optional: pattern-based extraction works out of the box.
@@ -35,7 +35,7 @@ Verify:
 
 ```bash
 python -c "import semantica; print(semantica.__version__)"
-# 0.6.7
+# 0.5.0
 ```
 
 
@@ -62,19 +62,18 @@ sources  = ingestor.ingest("data/report.pdf")
 ```python Web
 from semantica.ingest import WebIngestor
 
-ingestor = WebIngestor()
-page     = ingestor.ingest_url("https://example.com/article")
-# WebContent: page.text, page.title, page.html, page.links, page.metadata
+ingestor = WebIngestor(max_depth=2)
+sources  = ingestor.ingest("https://example.com/article")
 ```
 
-```python Parquet / XML
+```python Parquet / XML (v0.5.0)
 from semantica.ingest import ParquetIngestor, XMLIngestor
 
 # Single file or Hive-partitioned directory
 sources = ParquetIngestor().ingest("data/events.parquet")
 
-# XML; pass an XSD to validate against during ingestion
-sources = XMLIngestor().ingest("data/records/", schema_path="schema.xsd")
+# XML with XSD schema validation
+sources = XMLIngestor(validate_xsd="schema.xsd").ingest("data/records/")
 ```
 
 </CodeGroup>
@@ -89,24 +88,22 @@ Extract structured text and layout from raw documents.
 from semantica.parse import DocumentParser
 
 parser = DocumentParser()
-parsed = parser.parse(sources[0].path)   # parse() takes a path string
+parsed = parser.parse(sources[0])
 
-print(parsed["text"][:200])   # extracted text
-print(parsed["metadata"])     # file_path, encoding, size, and format-specific keys
+print(parsed.text[:200])  # extracted text
+print(parsed.metadata)    # title, author, date, source
 ```
 
-`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.
+  For PDFs with tables, charts, or multi-column layouts, use `DoclingParser`: it applies advanced layout analysis and returns structured table data alongside text.
 </Tip>
 
 ```python
 from semantica.parse import DoclingParser
 
 parser = DoclingParser()
-parsed = parser.parse(sources[0].path)
-print(parsed["tables"])   # structured table data
+parsed = parser.parse(sources[0])
+print(parsed.tables)  # structured table objects
 ```
 
 </Step>
@@ -120,28 +117,26 @@ 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"]
-
 ner      = NERExtractor(method="pattern")
-entities = ner.extract(text)
-# Returns: [Entity(text="Apple Inc.", label="ORG", start_char=0, end_char=10, confidence=0.7), ...]
+entities = ner.extract(parsed)
+# Returns: [{"text": "Apple Inc.", "type": "ORGANIZATION", "confidence": 0.98}, ...]
 
-rel           = RelationExtractor(method="pattern")
-relationships = rel.extract(text, entities=entities)
-# Returns: [Relation(subject=Entity(...), predicate="founded_by", object=Entity(...), confidence=0.7), ...]
+rel           = RelationExtractor(method="rule")
+relationships = rel.extract(parsed, entities=entities)
+# Returns: [{"subject": "Steve Jobs", "predicate": "founded", "object": "Apple Inc."}, ...]
 ```
 
 ```python LLM-powered (higher accuracy)
 from semantica.semantic_extract import NERExtractor, RelationExtractor
+from semantica.llms import Groq
 
-# Reads GROQ_API_KEY from the environment; provider/llm_model select the backend
-text = parsed["text"]
+llm = Groq(model="llama-3.3-70b-versatile")
 
-ner           = NERExtractor(method="llm", provider="groq", llm_model="llama-3.3-70b-versatile")
-entities      = ner.extract(text)
+ner           = NERExtractor(method="llm", llm_provider=llm)
+entities      = ner.extract(parsed)
 
-rel           = RelationExtractor(method="llm", provider="groq", llm_model="llama-3.3-70b-versatile")
-relationships = rel.extract(text, entities=entities)
+rel           = RelationExtractor(method="llm", llm_provider=llm)
+relationships = rel.extract(parsed, entities=entities)
 ```
 
 </CodeGroup>
@@ -203,17 +198,16 @@ exporter.export(graph, file_path="graph.nt",     format="nt")
 from semantica.export import ParquetExporter
 
 exporter = ParquetExporter()
-exporter.export(graph, file_path="output/graph")
-# Dict input writes one file per key: output/graph_entities.parquet and
-# output/graph_relationships.parquet: ready for Spark, BigQuery, Databricks
+exporter.export(graph, file_path="output/graph.parquet")
+# Writes nodes.parquet + edges.parquet: ready for Spark, BigQuery, Databricks
 ```
 
 ```python ArangoDB
 from semantica.export import ArangoAQLExporter
 
 exporter = ArangoAQLExporter()
-exporter.export(graph, file_path="graph.aql")
-# Writes ready-to-run AQL INSERT statements to graph.aql
+aql      = exporter.export(graph)
+# Returns ready-to-run AQL INSERT statements
 ```
 
 </CodeGroup>
@@ -278,21 +272,14 @@ relationships = rel.extract(text, entities=entities)
 <Accordion title="Multi-source incremental graph build" icon="layer-group">
 
 ```python
-from semantica.ingest import FileIngestor
-from semantica.parse import DocumentParser
-from semantica.semantic_extract import NERExtractor, RelationExtractor
 from semantica.kg import GraphBuilder
 
-parser  = DocumentParser()
-ner     = NERExtractor(method="pattern")
-rel     = RelationExtractor(method="pattern")
-builder = GraphBuilder(merge_entities=True)
-
+builder     = GraphBuilder(merge_entities=True)
 all_entities, all_rels = [], []
-for source in FileIngestor().ingest("data/reports/"):
-    text     = parser.parse(source.path)["text"]
-    entities = ner.extract(text)
-    rels     = rel.extract(text, entities=entities)
+
+for doc in parsed_docs:
+    entities = ner.extract(doc)
+    rels     = rel.extract(doc, entities=entities)
     all_entities.extend(entities)
     all_rels.extend(rels)
 
@@ -372,8 +359,7 @@ graph   = builder.build({"entities": entities, "relationships": relationships})
 # Retrieve full lineage for any entity
 sources = prov.get_all_sources("Apple Inc.")
 print(sources[0])
-# {"source": "data/report.pdf", "location": None, "timestamp": "...",
-#  "confidence": 1.0, "metadata": {"confidence": 0.98}}
+# {"source": "data/report.pdf", "location": None, "timestamp": "...", "confidence": 0.98}
 ```
 
 </Accordion>
@@ -387,42 +373,30 @@ print(sources[0])
 
 <Accordion title="No entities extracted" icon="magnifying-glass">
 
-The document likely contains scanned images rather than machine-readable text. `DocumentParser` warns when a PDF has no text layer; switch to `DoclingParser` with OCR enabled:
+The document likely contains scanned images rather than machine-readable text. Enable OCR:
 
 ```python
-from semantica.parse import DoclingParser   # pip install semantica[parse-docling]
+from semantica.parse import DocumentParser
 
-parser = DoclingParser(enable_ocr=True)
-parsed = parser.parse(sources[0].path)
+parser = DocumentParser(ocr=True)  # enables Tesseract OCR
+parsed = parser.parse(sources[0])
 ```
 
 </Accordion>
 
 <Accordion title="Slow processing on large corpora" icon="gauge">
 
-Enable GPU acceleration and run pipeline steps in parallel:
+Enable parallel processing and GPU acceleration:
 
 ```bash
 pip install semantica[gpu]
 ```
 
 ```python
-from semantica.pipeline import PipelineBuilder, ExecutionEngine
+from semantica.pipeline import Pipeline
 
-builder = PipelineBuilder()
-builder.add_step("ingest",  step_type="ingest", source="data/reports/", recursive=True)
-builder.add_step("extract", step_type="ner_extract")
-builder.add_step("build",   step_type="kg_build", merge_entities=True)
-
-pipeline = (
-    builder
-    .connect_steps("ingest",  "extract")
-    .connect_steps("extract", "build")
-    .set_parallelism(8)
-    .build(name="reports_pipeline")
-)
-
-result = ExecutionEngine().execute_pipeline(pipeline)
+pipeline = Pipeline(workers=8, batch_size=32)
+pipeline.run(sources)
 ```
 
 </Accordion>