Merge branch 'main' into docs-learning-more-audit

- Define sample tasks in concurrency snippet to avoid NameError

- Define document_text in batch extraction snippet

- Define sample entities in deduplication snippet

- Correct GRAPH_STORE_DEFAULT_BACKEND default to neo4j

- Replace ineffective SEMANTICA_PORT with SEMANTICA_API_KEY in config table

.dockerignore

@@ -19,7 +19,7 @@
 .github
 .github/**
 !.github/requirements/
-!.github/requirements/explorer-extra-py314.txt
+!.github/requirements/explorer-extra-py313.txt
 !.github/requirements/pep517-build.txt
 .claude
 .claude/**

.github/requirements/README.md

@@ -8,7 +8,7 @@ These exist because OpenSSF Scorecard's Pinned-Dependencies check flags any
 the project's own local-source install.
 
 Each `.txt` was generated from the adjacent `.in` (or, for `explorer-extra-py311.txt`,
-`explorer-extra-py314.txt`, and `base-deps.txt`, from `pyproject.toml` directly) with:
+`explorer-extra-py313.txt`, and `base-deps.txt`, from `pyproject.toml` directly) with:
 
 ```
 uv pip compile <input> --python-version 3.11 --python-platform linux \
@@ -29,7 +29,7 @@ each file's own autogenerated header comment for its exact command).
 | `bootstrap.txt` | security-scan.yml, benchmark.yml | pip, setuptools (upgrade before anything else) |
 | `pep517-build.txt` | ci.yml, benchmark.yml, Dockerfile | exact `[build-system] requires` from `pyproject.toml` (setuptools, wheel) - installed with `--no-build-isolation` before any `pip install -e .` / `pip install .`, since `--no-deps` alone doesn't stop pip's PEP 517 build isolation from fetching those two *unhashed* |
 | `explorer-extra-py311.txt` | ci.yml | semantica's base deps + the `explorer` extra, resolved for python 3.11 |
-| `explorer-extra-py314.txt` | Dockerfile | the same, resolved for python 3.14 (the image's actual interpreter) |
+| `explorer-extra-py313.txt` | Dockerfile | the same, resolved for python 3.13 (the image's actual interpreter) |
 | `pytest-tool.txt` | ci.yml | pytest, for the pre-all-extras deterministic test |
 | `uv-tool.txt` | ci.yml | uv, to verify requirements-ci.txt is current |
 | `build-tools.txt` | ci.yml, release.yml | build, wheel |
@@ -39,19 +39,19 @@ each file's own autogenerated header comment for its exact command).
 | `base-deps.txt` | benchmark.yml | semantica's base deps (no extras) |
 | `benchmark-extra.txt` | benchmark.yml | the benchmark-only libs (neo4j, pdfplumber, etc.) |
 
-`explorer-extra-py311.txt` and `explorer-extra-py314.txt` are large (they
+`explorer-extra-py31{1,3}.txt` and `base-deps.txt` are large (they mirror
-mirror most of `requirements-ci.txt`) because semantica's `dependencies`
+most of `requirements-ci.txt`) because semantica's `dependencies` list in
-list in `pyproject.toml` isn't extras-gated - installing the package at all
+`pyproject.toml` isn't extras-gated - installing the package at all pulls
-pulls the full base set. That's expected, not a mistake.
+the full base set. That's expected, not a mistake.
 
-`explorer-extra-py311.txt` and `explorer-extra-py314.txt` are **not**
+`explorer-extra-py311.txt` and `explorer-extra-py313.txt` are **not**
 interchangeable, and can't be collapsed into one file compiled for either
 version: `librosa`'s `audioread` dependency needs `standard-aifc` /
 `standard-sunau` only under `python_version >= "3.13"` (Python 3.13 dropped
 `aifc`/`sunau` from stdlib). A file resolved for 3.11 simply omits those
-packages' hashes, so installing it with `--require-hashes` on a real 3.14
+packages' hashes, so installing it with `--require-hashes` on a real 3.13
 interpreter (the Dockerfile's base image) fails outright rather than
-silently under-pinning. Any other file shared across a 3.11 and 3.14
+silently under-pinning. Any other file shared across a 3.11 and 3.13
 consumer would need the same split if it hits a similar stdlib-removal
 edge case - check for `ERROR: In --require-hashes mode, all requirements
 must have their versions pinned` on the *other* Python version before

.github/requirements/explorer-extra-py313.txt

@@ -1,5 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile pyproject.toml --extra explorer --python-version 3.14 --python-platform linux --generate-hashes --constraint requirements-ci.txt -o .github/requirements/explorer-extra-py314.txt
+#    uv pip compile pyproject.toml --extra explorer --python-version 3.13 --python-platform linux --generate-hashes --constraint requirements-ci.txt -o .github/requirements/explorer-extra-py313.txt
 annotated-doc==0.0.5 \
     --hash=sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101 \
     --hash=sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb

.github/workflows/ci.yml

@@ -112,8 +112,8 @@ jobs:
           # `uv pip compile pyproject.toml --extra explorer --python-version 3.11 --constraint requirements-ci.txt --generate-hashes`
           # - regenerate it the same way if pyproject.toml's base/explorer
           # deps change. Resolved specifically for this job's python 3.11
-          # (see the Dockerfile's explorer-extra-py314.txt for why this
+          # (see the Dockerfile's explorer-extra-py313.txt for why this
-          # can't be shared with python 3.14: audioread needs extra
+          # can't be shared with python 3.13: audioread needs extra
           # standard-aifc/standard-sunau hashes only on 3.13+).
           #
           # --no-deps only skips *runtime* dependency resolution - `-e .`

.github/workflows/container-scan.yml

@@ -12,7 +12,7 @@ on:
       - 'README.md'
       - 'LICENSE'
       - 'MANIFEST.in'
-      - '.github/requirements/explorer-extra-py314.txt'
+      - '.github/requirements/explorer-extra-py313.txt'
       - '.github/requirements/pep517-build.txt'
       - 'semantica/**'
       - 'integrations/**'

Dockerfile

@@ -20,7 +20,18 @@ RUN mkdir -p /app/semantica && npm run build
 # .github/dependabot.yml opens a PR bumping the digest pin above. Also: this
 # image only serves plain HTTP via uvicorn and never opens a QUIC listener,
 # so the bug isn't reachable here regardless.
-FROM python:3.14-slim@sha256:cae66f2ef0ec51a9891263eeee7f987dacf0a9879e8aa9353d5606e0530619a5 AS runtime
+#
+# Pinned to 3.13, NOT 3.14: #1290 bumped this to python:3.14-slim and broke
+# the build outright (Container Security Scan, every run since) - gensim
+# (a base, non-extras-gated dependency) ships no cp314 wheel on PyPI yet, so
+# pip falls back to building it from source, which needs a C compiler this
+# slim image doesn't carry ("error: [Errno 2] No such file or directory:
+# 'gcc'"). Revisit the 3.14 bump once gensim (and anything else pulled in
+# transitively) publishes cp314 wheels - check with
+# `pip index versions gensim` / the project's PyPI files page, not just
+# whether `uv pip compile` resolves (resolution only reads sdist metadata,
+# it doesn't attempt the build that fails here).
+FROM python:3.13-slim@sha256:7ce4b6dfe35e55397b7cda544f8a13f191b7ae28dc5aad71fe664dbc9bc2623f AS runtime
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
@@ -34,18 +45,18 @@ RUN groupadd --system semantica \
     && useradd --system --gid semantica --home-dir /app --shell /usr/sbin/nologin semantica
 
 COPY pyproject.toml README.md LICENSE MANIFEST.in \
-     .github/requirements/explorer-extra-py314.txt .github/requirements/pep517-build.txt ./
+     .github/requirements/explorer-extra-py313.txt .github/requirements/pep517-build.txt ./
 COPY semantica/ ./semantica/
 COPY integrations/ ./integrations/
 COPY --from=frontend-builder /app/semantica/static ./semantica/static
 
-# explorer-extra-py314.txt is `uv pip compile pyproject.toml --extra explorer
+# explorer-extra-py313.txt is `uv pip compile pyproject.toml --extra explorer
-# --python-version 3.14 --constraint requirements-ci.txt --generate-hashes`
+# --python-version 3.13 --constraint requirements-ci.txt --generate-hashes`
 # (see ci.yml's explorer-extra-py311.txt for the CI counterpart, resolved
 # for CI's python 3.11 instead - the two aren't interchangeable: audioread
 # (via librosa) needs standard-aifc/standard-sunau only on python>=3.13,
 # since aifc/sunau left stdlib there, so a 3.11-resolved lockfile is
-# missing hashes pip needs on this image's actual 3.14 interpreter and
+# missing hashes pip needs on this image's actual 3.13 interpreter and
 # --require-hashes fails outright rather than silently under-pinning).
 # Every fetched package is hash-verified (Scorecard Pinned-Dependencies)
 # and pinned to the same versions CI audited, e.g. msgpack==1.2.1 and
@@ -59,9 +70,9 @@ COPY --from=frontend-builder /app/semantica/static ./semantica/static
 # build-system.requires; installing it first and passing
 # --no-build-isolation makes pip reuse those hash-verified copies instead
 # of fetching its own.
-RUN pip install --no-cache-dir -r explorer-extra-py314.txt -r pep517-build.txt --require-hashes \
+RUN pip install --no-cache-dir -r explorer-extra-py313.txt -r pep517-build.txt --require-hashes \
     && pip install --no-cache-dir --no-deps --no-build-isolation . \
-    && rm -f explorer-extra-py314.txt pep517-build.txt \
+    && rm -f explorer-extra-py313.txt pep517-build.txt \
     && chown -R semantica:semantica /app
 
 USER semantica

docs/learning-more.md

@@ -64,7 +64,7 @@ Whether you're running your first pipeline or deploying Semantica in production,
         [Temporal Graphs notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb): `valid_from`/`valid_until`, Allen interval algebra, point-in-time queries.
       </Step>
       <Step title="Ontology-driven knowledge bases">
-        [Ontology notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/14_Ontology.ipynb): auto-generation, SHACL validation, Ontology Hub (v0.5.0).
+        [Ontology notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/14_Ontology.ipynb): auto-generation, SHACL validation, Ontology Hub.
       </Step>
       <Step title="Advanced visualization">
         [Complete Visualization Suite notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/03_Complete_Visualization_Suite.ipynb): UMAP, t-SNE, community layouts, embedding projections.
@@ -86,10 +86,10 @@ All settings can be overridden with environment variables: no code changes neede
 | OpenAI API Key | `OPENAI_API_KEY` | `None` |
 | Groq API Key | `GROQ_API_KEY` | `None` |
 | Anthropic API Key | `ANTHROPIC_API_KEY` | `None` |
-| Embedding Provider | `SEMANTICA_EMBEDDING_PROVIDER` | `"openai"` |
+| Graph Store Backend | `GRAPH_STORE_DEFAULT_BACKEND` | `"neo4j"` |
-| Graph Backend | `SEMANTICA_GRAPH_BACKEND` | `"networkx"` |
+| Vector Store Backend | `VECTOR_STORE_DEFAULT_BACKEND` | `"faiss"` |
-| Log Level | `SEMANTICA_LOG_LEVEL` | `"INFO"` |
+| Server Host | `SEMANTICA_HOST` | `"127.0.0.1"` |
-| Log Format | `SEMANTICA_LOG_FORMAT` | `"text"` |
+| Server API Key | `SEMANTICA_API_KEY` | `None` |
 
 
 ## Troubleshooting
@@ -146,10 +146,15 @@ Also reduce batch sizes and enable streaming ingestion for large corpora.
 Enable parallel execution and GPU acceleration:
 
 ```python
-from semantica.pipeline import Pipeline
+from semantica.pipeline import ParallelismManager, Task
 
-pipeline = Pipeline(workers=8, batch_size=32)
+# Run pipeline tasks concurrently across worker threads
-pipeline.run(sources)
+manager = ParallelismManager(max_workers=8)
+tasks = [
+    Task("task_1", lambda: "process part 1"),
+    Task("task_2", lambda: "process part 2"),
+]
+results = manager.execute_parallel(tasks)
 ```
 
 ```bash
@@ -160,19 +165,19 @@ pip install "semantica[gpu]"  # CUDA-backed embeddings
 
 <Accordion title="Windows [all] installation fails" icon="windows">
 
-Fixed in **v0.5.0**. Upgrade:
+Upgrade to the latest release:
 
 ```bash
 pip install --upgrade semantica
 ```
 
-Or install extras individually: `pip install "semantica[core]"`, then add `[llm-openai]`, `[gpu]`, etc. as needed.
+Or install extras individually: `pip install semantica`, then add `[llm-openai]`, `[gpu]`, etc. as needed.
 
 </Accordion>
 
 <Accordion title="cp1252 encoding crash on Windows" icon="windows">
 
-Fixed in **v0.5.0**. For earlier versions, set the encoding environment variable:
+Set the encoding environment variable:
 
 ```bash
 set PYTHONIOENCODING=utf-8
@@ -202,27 +207,44 @@ Use NetworkX for local development and prototyping. Switch to a persistent backe
 
 <Accordion title="Batch processing for large corpora" icon="layer-group">
 
-Process documents in batches rather than one at a time. Configure `chunk_size` based on available RAM: a good starting point is 1,000 documents per batch on a 16 GB machine.
+Process documents in batches rather than one at a time. Split large texts into chunks and extract entities in batches:
 
 ```python
-from semantica.pipeline import Pipeline
+from semantica.split import TextSplitter
+from semantica.semantic_extract import NERExtractor
 
-pipeline = Pipeline(workers=8, batch_size=32)
+document_text = "Acme Corp announced record revenue in Seattle. CEO Jane Doe presented results."
-pipeline.run(sources)
+splitter = TextSplitter(chunk_size=1000, chunk_overlap=100)
+chunks = splitter.split(document_text)
+
+extractor = NERExtractor()
+batch_entities = extractor.extract_entities_batch([c.text for c in chunks])
 ```
 
 </Accordion>
 
 <Accordion title="Deduplication v2: up to 7× faster" icon="bolt">
 
-If deduplication is a bottleneck, switch from v1 strategies to the v2 engine:
+If deduplication is a bottleneck, use candidate blocking to reduce O(n²) comparisons before similarity scoring:
 
 ```python
-resolver = EntityResolver()
+from semantica.deduplication import DuplicateDetector, EntityMerger
-merged   = resolver.resolve(entities, strategy="semantic_v2")  # up to 7x faster
+
+entities = [
+    {"id": "1", "name": "Acme Corp", "type": "Company"},
+    {"id": "2", "name": "Acme Corporation", "type": "Company"},
+    {"id": "3", "name": "Globex", "type": "Company"},
+]
+
+# Fast candidate blocking for large entity sets
+detector = DuplicateDetector(similarity_threshold=0.8)
+duplicates = detector.detect_duplicates(entities, candidate_strategy="blocking_v2")
+
+merger = EntityMerger()
+merged = merger.merge_duplicates(entities, strategy="keep_most_complete")
 ```
 
-The `blocking_v2`, `hybrid_v2`, and `semantic_v2` strategies reduce O(n²) comparisons via candidate blocking before similarity scoring.
+The `blocking_v2` and `hybrid_v2` candidate strategies filter candidate pairs before calculating fine-grained similarity.
 
 </Accordion>
 
@@ -233,8 +255,8 @@ The `blocking_v2`, `hybrid_v2`, and `semantic_v2` strategies reduce O(n²) compa
 
 - **API keys**: store in environment variables or a secrets manager; never commit them to version control; rotate on a schedule
 - **Sensitive data**: use local embedding models (Ollama, HuggingFace) for PII or classified content; avoid sending sensitive data to external APIs without data handling agreements
-- **Graph exports**: encrypt sensitive exports at rest; use the v0.5.0 SSRF-safe `base_url` validation when configuring custom LLM gateways
+- **Graph exports**: encrypt sensitive exports at rest; use SSRF-safe `base_url` validation when configuring custom LLM gateways
-- **XML ingestion**: always use `XMLIngestor` (v0.5.0), which uses the XXE-safe lxml backend; never parse untrusted XML with the standard library parser
+- **XML ingestion**: always use `XMLIngestor`, which uses the XXE-safe lxml backend; never parse untrusted XML with the standard library parser
 
 - [Cookbook](/cookbook): interactive Jupyter notebooks from beginner to advanced.
 - [FAQ](/faq): common questions answered.

requirements-ci.txt

@@ -4409,15 +4409,15 @@ pillow==12.3.0 \
     #   python-pptx
     #   rapidocr
     #   torchvision
-pinecone==9.1.0 \
+pinecone==10.0.0 \
-    --hash=sha256:461632bb07919da32b943100b8a047c74be53a6aa15c8b7679bff7a0f834c939 \
+    --hash=sha256:0994270c514b16c72ec94dd6c29ff2708b81d30ff8467e19de192a28a7c86b7e \
-    --hash=sha256:6c3a6dfa577dc11aed3197e1b221e65522603e9e1f6bd27a1b504a0909b3559f \
+    --hash=sha256:0e05956a3201b1fbb54a1861277df919318a4941797f2d87fd558ac5ec232151 \
-    --hash=sha256:d3871bd3f39cb430ae8470158dc9c5dcffbac5ae31d144d9a7c3b351ac51755f \
+    --hash=sha256:2f4e3200ee3562d195802b363487dd7fe6039a8c13630fc25fa3e8726c7a8654 \
-    --hash=sha256:d53fe6f4978ab0642eb2d3a0ee3b2576ccfeebaa11e0690b18e67dac4e057047 \
+    --hash=sha256:3ab0c843b4fb04fbac22f1b8455e389063208a50f6a95d7a90627939968198de \
-    --hash=sha256:e930ba819f5b7e20aac688d04c840a8b6fbc6d12630d71303bb2130881a9d169 \
+    --hash=sha256:6066bbe9a7ae1d667cde08d262deb6fbea6feb35deb9177dd47141b55bbd9833 \
-    --hash=sha256:fc71ec431108de2df1a1978d3a24ac16f74ba3d8f3265c3760f969386e8742b8 \
+    --hash=sha256:94d4c64779f3213a5cc538d3bd10a873da192cb9b0039db56690e556ba00b55c \
-    --hash=sha256:fe6aeaf6515e9021984755ebc162f643c79d98056059aab2e765962a7538818c \
+    --hash=sha256:995c06e905940b10bb2aefe653225340b5a3f56f3efb373fe07f4e57b5043705 \
-    --hash=sha256:ffae8fb7cbb4056b920586629f15b08107350be4802a5637d10b31e2ad841f9c
+    --hash=sha256:d482ed27a805cbd4aca2660da212008dd6e41d87d255279f405ff13b725970e2
     # via semantica (pyproject.toml)
 platformdirs==4.11.7 \
     --hash=sha256:4f41487eeeeeb07f3a6625e61d9bc0ae6809f92d3386dbd74392fbb76108104d \