Semantica v0.6.6

Released: 2026-08-20
Tag: v0.6.6 · Compare: v0.6.5...v0.6.6 · PyPI: semantica 0.6.6

Highlights

Security release — upgrading is strongly recommended. Fixes for a privately disclosed batch of vulnerabilities spanning backup/restore, database export, outbound requests, and triplet-store backends, plus SSRF hardening across ingestion (tarball path traversal, SQL injection, DNS-rebinding TOCTOU, stored XSS, SPARQL injection, credential leakage across redirects, and more — see CHANGELOG.md for the full breakdown).

Also ships: first-class CrewAI integration, ContextGraph retraction and purge, a declared Semantica RDF vocabulary with deterministic entity/relationship IRIs, and timezone-aware timestamps across export/ and provenance/.

What's Changed

• #862 · 918830a8 · fix(pipeline): resolve broken import and missing run() in PipelineWithProvenance · @Karunasagar12
• #857 · 229cb69c · Added custom _filter_by_metadata for each memory backend · @TaherTadpatri
• #870 · 22bf5810 · fix(mcp): report package version · @oiahoon
• #871 · 9ec79598 · Bump fastapi minimum version to fix PYSEC-2024-38 (starlette DoS) · @agu2347
• #873 · bc63e962 · test(seed): use a real file for CSV loading · @nightcityblade
• #929 · 687a1807 · fix(context): take the lock in ContextGraph.to_dict() · @pravit-amp
• #912 · c1154b6e · fix(security): header injection, link-prediction DoS, import ID sanitization · @Sunil56224972
• #878 · 1a3dd503 · docs(kg): document GraphBuilder public methods · @cakeni
• #941 · 1ee3f2f2 · fix(kg): align GraphBuilder raw-text extraction defaults with the documented contract · @dex0shubham
• #879 · b0080c36 · fix(export): log DistanceExporter metric computation failures instead of swallowing them · @AmirF194
• #881 · 18f1d55d · test(normalize): make optional tests deterministic · @aoright
• #882 · 0fa3483b · fix(context): clarify get_node_property not-found contract (#877) · @ZohaibHassan16
• #960 · 2cfb5de4 · feat(export): add opt-in metric_errors column to DistanceExporter · @Karunasagar12
• #966 · 7c3372c0 · fix(explorer): align dev esbuild target · @le-czs
• #905 · 91d02a0f · fix(ingest): harden RepoIngestor GitPython clone surface (#868) · @pravit-amp
• #914 · 43bac617 · fix(vector_store): make VectorManager methods work on persistent backends (#855) · @yunaremaia
• #928 · 611874e6 · security: apply SSRF guard to feed ingestion requests · @ZohaibHassan16
• #959 · c5d13a45 · feat(seed): allow_private_ips opt-in for trusted internal API sources · @yunaremaia
• #908 · 09c4b1b5 · test(context): skip symlink test without Windows privilege · @ssynb
• #976 · c0a05190 · docs: update CONTRIBUTING.md · @eltociear
• #978 · 94d0c3dc · fix(kg): remap relationship endpoints after entity resolution · @T1mn
• #932 · 1c0cebb1 · security(context): harden Markdown import against TOCTOU symlink races · @lakshanmuruganandam
• #935 · 80b1cca0 · test(semantic_extract): guard openai-dependent tests and assert on the logger, not stdout · @dex0shubham
• #980 · 75f88b1c · Fix/explorer backend failure states · @ZohaibHassan16
• #984 · 5bc09a5f · refactor(explorer): remove dead graph workspace shell · @lakshayxi
• #979 · 80b9bea0 · fix(ingest): lock the repo host DNS resolve cache against concurrent mutation · @manjunathbhaskar
• #983 · 8a4ebafb · fix(context): honor explicit causal edges in decision tracing · @hsd2514
• #945 · 4513b61e · ci: pin Python dependencies in requirements-ci.txt for reproducible CI · @yunaremaia
• #986 · 42afc060 · ci: refresh github/codeql-action pin to current v4 · @ZohaibHassan16
• #987 · c1be6dd7 · docs: fix dead allcontributors emoji-key link · @yzxcj797
• #886 · 557e29ee · fix(explorer): repair /api/enrich/extract (always 503) and the /api/decisions routes (always 500) · @joseedson18jc
• #1000 · b8175ea8 · fix(kg): make k-shortest path search side-effect free · @T1mn
• #926 · 84ce3c51 · fix(context): make ContextGraph.add_edge idempotent by deduping on edge_id · @pravit-amp
• #951 · 6df97cf0 · fix(triplet_store): stop CONSTRUCT detection matching inside a leading comment · @pravit-amp
• #957 · f1e7e64a · feat(context): add retraction and purge to ContextGraph · @pravit-amp
• #995 · 8639cb9f · fix(seed): pass connection string to DBIngestor and stop mislabeling OSError in load_from_database · @yzxcj797
• #1003 · 115e7965 · fix(explorer): gate temporal requests on graph load · @lakshayxi
• #958 · 55798512 · fix(export): harden YAML export input handling · @pravit-amp
• #988 · d94d8f6a · Feat/crewai integration · @Shindevrp
• #1011 · 8177d887 · fix(kg): preserve isolated nodes in graph analytics · @T1mn
• #1016 · 15171fd3 · fix(parse): import get_progress_tracker in ExcelParser · @pravit-amp
• #1030 · c53ca4e8 · docs: formalize issue assignment and duplicate-PR triage workflow · @KaifAhmad1
• #940 · 70aa9d01 · fix(normalize): validate symbol currencies · @Mr-Neutr0n
• #1033 · 6416fbb6 · docs: clarify explainability is system-level, not foundation-model internal · @KaifAhmad1
• #1034 · 4d379200 · docs: surface explainability scope note near the top of the README · @KaifAhmad1
• #1042 · d4cb14c1 · perf(split): avoid repeated spaCy model loading in split/chunking paths · @Accute9
• #1062 · eedf1425 · Fix flatten_dict key collisions · @shahzaib-ahmadcs
• #1067 · 04602a0e · fix(security): prevent Authorization header leakage across redirects (#947) · @Sameer6305
• #1056 · baf8f01f · test(export): guard Parquet tests on pyarrow itself, not the exporter import · @dex0shubham
• #921 · 5c2901ae · docs(context): fix unrunnable ContextGraph docstring example · @pravit-amp
• #1079 · 488e3812 · fix(security): address privately disclosed zip-slip, SQLi, SSRF, XSS, and SPARQLi findings · @KaifAhmad1
• #1026 · 17d878cb · fix(kg): honor exact entity resolution · @T1mn
• #1081 · a1194a15 · feat(context): add to_kg_dict() adapter for canonical KG shape · @cxzg007
• #1013 · 7db2e2f4 · fix(explorer): enable edge label rendering on the graph canvas · @yzxcj797
• #1040 · e6b159e5 · docs(explorer): update stale authentication notes after v0.6.5 · @Kyou12138
• #1094 · 68f7ae38 · fix(ontology): render real SHACL constraint values in explain_violations · @cxzg007
• #1086 · b77e3e8c · fix(kg): preserve entity_id aliases during entity merging · @T1mn
• #942 · 4a886d97 · fix seed SSRF · @ZohaibHassan16
• #1109 · 2a303cf4 · Declare the Semantica vocabulary, and mint entity IRIs deterministically (#1107, #1101) · @fabio-rovai
• #1120 · 58b77ddc · Mint JSON-LD @ids the same way the RDF serializers do (#1101, missed by #1109) · @fabio-rovai
• #1121 · 6b7625ef · Write timestamps with an explicit UTC offset, and tighten sem:exportedAt to xsd:dateTimeStamp (#1114) · @fabio-rovai

61 pull requests merged from 32 contributors.

Contributors

Returning contributors who shipped changes in this release:

@KaifAhmad1, @pravit-amp, @Sameer6305, @Sunil56224972, @ZohaibHassan16

New Contributors

Welcome, and thank you for your first contribution to Semantica:

• @Karunasagar12 first contribution in #862
• @TaherTadpatri first contribution in #857
• @oiahoon first contribution in #870
• @agu2347 first contribution in #871
• @nightcityblade first contribution in #873
• @cakeni first contribution in #878
• @dex0shubham first contribution in #941
• @AmirF194 first contribution in #879
• @aoright first contribution in #881
• @le-czs first contribution in #966
• @yunaremaia first contribution in #914
• @ssynb first contribution in #908
• @eltociear first contribution in #976
• @T1mn first contribution in #978
• @lakshanmuruganandam first contribution in #932
• @lakshayxi first contribution in #984
• @manjunathbhaskar first contribution in #979
• @hsd2514 first contribution in #983
• @yzxcj797 first contribution in #987
• @joseedson18jc first contribution in #886
• @Shindevrp first contribution in #988
• @Mr-Neutr0n first contribution in #940
• @Accute9 first contribution in #1042
• @shahzaib-ahmadcs first contribution in #1062
• @cxzg007 first contribution in #1081
• @Kyou12138 first contribution in #1040
• @fabio-rovai first contribution in #1109

Full Changelog: v0.6.5...v0.6.6

Release Date: August 11, 2026
Version: 0.6.5

Semantica 0.6.5 is a security release closing 6 externally-reported vulnerabilities across the Explorer API and the graph/triplet store backends — including a Critical missing-authentication gap and a Critical Cypher-injection path — plus a CodeQL-flagged ReDoS. It also ships an embedded Oxigraph TripletStore backend, full PROV-O trust/spec completeness for ProvenanceManager, the Altair Anzo triplet store backend, and closes out 25+ correctness bugs across vector stores, provenance, ontology validation, and the Explorer frontend.

Upgrading is strongly recommended for all deployments, especially anyone running the Explorer API.

What's Changed

Security

• Missing authentication on all Explorer API routes (#909, GHSA-j4mq-hprp-987v, Critical) by @KaifAhmad1

  • Every route across all 11 API routers (graph, ontology, SPARQL, SHACL, provenance, temporal, analytics, import/export) was reachable with no credential — full read/write graph access and arbitrary SPARQL execution for anyone who could reach the port
  • New Depends(require_auth) validates X-API-Key against SEMANTICA_API_KEY; fails closed (503) when unset, rather than silently allowing anonymous access
  • SEMANTICA_ALLOW_ANONYMOUS=true remains available as an explicit opt-out for local/dev use

• SSRF via redirect bypass in ontology URL fetching, plus DNS check-then-use hardening (#898, #916, GHSA-8c7v-62gr-hj6g, High) by @Sunil56224972 and @KaifAhmad1

  • A validated public first hop could redirect (302) to http://169.254.169.254/... (cloud instance metadata) or an internal service with no re-validation; redirects are now followed manually, capped at 5 hops, with every hop's target (including relative Location headers) re-validated
  • Follow-up (#916) closed a secondary DNS check-then-use (TOCTOU) window: the connection is now pinned directly to the validated IP via a custom requests adapter, with the real hostname still presented for the HTTP Host header and TLS SNI/certificate verification
  • Verified with real (non-mocked) local HTTP/HTTPS test servers, including a negative control confirming a hostname/cert mismatch is still rejected

• Cypher injection via unvalidated node labels, relationship types, and property keys (#910, GHSA-482h-hw99-h62p, Critical) by @KaifAhmad1, review fix by @Sameer6305

  • Labels and property keys can't be parameterized like values; a document-derived entity type or property name could close the current Cypher token early and append arbitrary statements (e.g. DETACH DELETE) across the Neptune, Neo4j, and FalkorDB backends
  • New shared semantica/graph_store/query_sanitize.py validates every label/relationship-type/property-key interpolation site

• SPARQL injection via unvalidated triplet IRIs (#911, #916, GHSA-8vgg-8mr4-r236, Critical) by @KaifAhmad1, review fix by @ZohaibHassan16

  • A subject/predicate/object containing > could close the <...> IRI token early and append arbitrary SPARQL (e.g. CLEAR ALL) across the Blazegraph, RDF4J, and Jena backends
  • Applied sparql_escaping.validate_uri() at every interpolation site; a follow-up (#916) closed a remaining gap where an already-<...>-wrapped object skipped validation

• Missing Origin validation on the WebSocket handshake (#917, GHSA-4643-wpgq-w329, Moderate — anonymous-mode only) by @KaifAhmad1

  • CORSMiddleware doesn't cover WebSocket handshakes; under SEMANTICA_ALLOW_ANONYMOUS=true, /ws/graph-updates accepted a connection from any browser origin
  • Now checks Origin against the same allowlist CORSMiddleware already enforces for HTTP, before the key check

• Polynomial-time ReDoS in the SPARQL route's _PREFIX_DECL regex (#915, CodeQL py/polynomial-redos) by @Sameer6305

  • Two overlapping quantifiers allowed O(n²) backtracking, reachable from req.query; fixed by making them character-disjoint, plus a 10,000-char defense-in-depth query length cap

• 4 additional critical/high vulnerabilities in the Explorer API and vector store: RCE, XXE, DoS (#898) by @Sunil56224972

  • [CWE-502] Arbitrary code execution via pickle.load() in VectorStore.save()/load() — replaced with JSON; legacy .pkl files are now refused rather than deserialized
  • [CWE-611] XXE in the RDF/XML parser — defusedxml is now a declared dependency and _safe_parse_rdf() fails closed if it isn't importable
  • [CWE-770] DoS via unbounded SPARQL graph materialization — capped at 50,000 nodes/edges
  • Plus Cypher-injection hardening for Apache AGE's graph_name/$$-delimiter breakout, and comment/PREFIX-hiding bypass hardening for the read-only SPARQL keyword check

• CI/CD supply-chain hardening against mutable-tag Action compromise (#824) by @KaifAhmad1

  • Every third-party GitHub Action across all 8 workflows pinned to a full commit SHA (closing the vector used against LiteLLM in March 2026); added a CI check that fails closed on any non-SHA uses: reference; added SLSA build provenance attestation and a protected pypi GitHub Environment

• security-scan.yml's Safety dependency check was silently non-functional, pypdf2==3.0.1 removed (CVE-2023-36464), and 10 Bandit B324 false positives suppressed (#824) by @KaifAhmad1

• SSRF protection for WebIngestor, SitemapCrawler, and RESTIngestor (#906, closes #867) by @pravit-amp

  • New shared validate_url_for_request() SSRF guard, wired into all three ingestors; allow_private_ips remains available as an explicit opt-in for trusted internal deployments

Added

• Embedded Oxigraph backend for TripletStore (#838, closes #834) by @Linxiushen

  • In-process SPARQL 1.1 store via the optional pyoxigraph dependency — no external server (Blazegraph/Jena/RDF4J/Anzo) required
  • pip install "semantica[tripletstore-oxigraph]"; runs in memory by default or persists to a local directory

• PROV-O trust blockers and general spec completeness for ProvenanceManager (#825) by @KaifAhmad1

  • Invalidation-instead-of-delete tombstoning, hash-chained integrity (verify_chain()), typed Agent/Activity records, downstream lineage traversal, W3C PROV-O qualified relations, bitemporal + Bundle support, and a configurable namespace
  • New CLI commands: semantica provenance invalidate|verify-chain|descendants

• Altair Anzo triplet store backend (#813) by @KaifAhmad1 — a fourth peer to Blazegraph/RDF4J/Jena speaking plain SPARQL 1.1 over HTTP, no new dependency required

• Comprehensive unit and security test suite for the /api/sparql Explorer route (#773) by @Sameer6305 — 34 new tests covering read-only allowlist enforcement, resource limiting, and RDF projection fidelity

• Global default persistent storage for ProvenanceManager, plus a working provenance CLI (#795, #802) by @Sameer6305 and @KaifAhmad1 — every ingestion module now actually persists to the SQLite audit trail instead of silently falling back to in-memory storage

• Markdown round-trip export/import for AgentMemory (#765, #786) by @SaurabhScripts and @Sameer6305 — human-editable, diff-friendly Markdown alternative to JSON serialization, with atomic upsert-by-ID import

Fixed

• VectorStore.search_vectors() returned inconsistent result shapes across backend implementations (#853, closes #845) by @Sameer6305, reviewed by @KaifAhmad1
• DecisionEmbeddingPipeline.find_similar_decisions() crashed for any VectorStore backend other than inmemory (#842, closes #839) by @Sameer6305
• QdrantStore.search_vectors() returned results keyed by "payload" instead of "metadata" (#841, closes #840) by @divyankshah
• Explorer Temporal panel never rendered after clicking the toolbar button (#830, #836) by @Sameer6305
• HybridSearch.search() crashed for any VectorStore backend other than inmemory (#833, #837) by @KaifAhmad1
• VectorStore.store_vectors() silently dropped metadata for FAISS (#832, #835) by @KaifAhmad1
• AgnoDecisionKit.check_policy silently treated unevaluable policy rules as compliant (#778, #822) by @Sameer6305
• No cycle detection for SKOS concepts at write time (#774, #819) by @mikemikimike, reviewed by @Sameer6305 and @KaifAhmad1
• Agno _AgentScopedStore.upsert_memory silently swallowed decision recording failures (#779)
• AgnoDecisionKit/AgnoKGToolkit silently swallowed Agno tool registration failures (#780, #818) by @Sameer6305 and @KaifAhmad1
• ProvenanceManager tracking methods silently swallowed failures without logging (#783)
• MCP handle_get_causal_chain returned an empty-but-valid response when unsupported (#781, #817) by @Sameer6305 and @KaifAhmad1
• ProvenanceManager.track_entity persisted partial history on storage failure (#782, #816) by @Sameer6305 and @KaifAhmad1
• ProvenanceManager duplicated checksum/persist/exception-swallow logic across 4 methods (#784, #815) by @Sameer6305 and @KaifAhmad1
• SQLiteStorage/ProvenanceManager connection churn, non-atomic writes, batch tracking overhead (#807) by @Sameer6305
• Closed remaining ProvenanceManager storage-failure test-coverage gaps (#785)
• Explorer's Provenance UI used a naive 2-hop traversal instead of the audit-grade ProvenanceManager backend (#792, #809) by @Sameer6305
• POST /shacl/validate and the /health SHACL dimension never ran live SHACL validation (#772, #804) by @Sameer6305 and @KaifAhmad1
• Neptune cookbook CloudFormation stack exposed the database port to the entire internet (code scanning #26–28) by @KaifAhmad1
• Knowledge-explorer Helm chart namespace/seccomp scanner findings reopened (code scanning #846–848, #68, #63) by @KaifAhmad1
• react-hooks/set-state-in-effect cascading renders across 12 Explorer workspace files (#769, #796) by @Sameer6305 and @KaifAhmad1
• Checkov flagged the knowledge-explorer Helm chart for the default Kubernetes namespace (code scanning #777–779) by @KaifAhmad1
• No React error boundaries around lazy-loaded Explorer workspaces (#768, #794) by @Sameer6305
• Explorer frontend workspaces silently swallowed network/server errors (#767, #790) by @Sameer6305
• tests/explorer/test_explorer_api.py failed on current httpx (#788, #789) by @Sameer6305
• Explorer backend routes returned HTTP 200 with error/empty bodies on failure (#770, #787) by @Sameer6305 and @KaifAhmad1

Testing

• New test coverage for previously untested/lightly-covered split chunkers (SlidingWindow, Structural, Table, EntityAware, and KG chunkers) (#904, closes #864) by @pravit-amp
• New test coverage for ClusterBuilder, MergeStrategyManager/PropertyMergeRule, and EntityMerger.merge_duplicates() in deduplication (#907, closes #866) by @pravit-amp

Contributors

@KaifAhmad1 · @Sameer6305 · @Sunil56224972 · @Linxiushen · @SaurabhScripts · @divyankshah · @mikemikimike · @pravit-amp · @ZohaibHassan16

Full Changelog: https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md

Release Date: July 21, 2026
Version: 0.6.0

Semantica 0.6.0 closes out cross-backend SPARQL parity (named graphs and CONSTRUCT templates now work identically across Blazegraph, RDF4J, and Jena), adds Databricks and SQLite as new data connectors, and fixes seven correctness bugs in provenance tracking and rule-based reasoning.

What's Changed

Added

• Named-Graph Support for JenaStore (#756, #757) by @Sameer6305 and @KaifAhmad1

  • Migrated onto rdflib.Dataset(default_union=False); add_triplets() gains a graph= option for named-graph writes
  • Completes cross-backend named-graph parity across Blazegraph, RDF4J, and Jena
  • Also fixes the remote Fuseki path silently failing every write (wrong rdflib store class, self.endpoint never set)
  • 9 tests

• SPARQL CONSTRUCT Query Templates (#752, #322, #755, #754) by @Sameer6305

  • ConstructTemplate, ParameterDescriptor, ConstructTemplateRegistry for parameterized, injection-safe CONSTRUCT queries
  • CONSTRUCT execution extended from Blazegraph-only to the RDF4J and Jena backends
  • New construct_template pipeline step type

• Databricks Connector (#747) by @KaifAhmad1

  • DatabricksIngestor for Unity Catalog + Delta Lake ingestion, mirroring SnowflakeIngestor's API shape
  • PAT and OAuth M2M (service principal) auth; ingest_table()/ingest_query(); catalog/schema/table introspection; table + column lineage
  • Optional dep: pip install "semantica[db-databricks]"; included in db-all
  • 35 tests

• SQLite Vector Store Backend (#726) by @Luffy2208 and @KaifAhmad1

  • SQLiteVecStore, a disk-backed local vector store on sqlite-vec's vec0 virtual tables
  • Cosine/L2 metrics, JSON metadata filtering, read-only and in-memory modes, optional WAL mode for write concurrency
  • Optional dep: pip install semantica[vectorstore-sqlite]
  • 25 tests

Fixed

• kg.ProvenanceTracker out of sync with ProvenanceManager, now deprecated in favor of it (#744, #751) by @Sameer6305 and @KaifAhmad1
• ProvenanceManager.track_entity silently overriding an explicit parent_entity_id/derived_from on re-track (#742) by @Sameer6305
• ProvenanceManager.get_lineage not linking entities that share a source URL (#735) by @KaifAhmad1
• Reasoner.add_rule had no deduplication, doubling rules and silently emptying forward_chain() on rerun (#732) by @KaifAhmad1
• InferenceResult.premises always empty from forward_chain/backward_chain (#739) by @Sameer6305
• Missing shacl optional-dependency extra (#736) by @Sameer6305
• NodeEmbedder AttributeError masked in ContextGraph.analyze_graph_with_kg (#734) by @Sameer6305

Full Changelog: https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md

What's Changed

Added

• Apache Arrow & Feather File Ingestion (#705) by @Luffy2208

  • ArrowIngestor for .arrow, .feather, and .ipc files via PyArrow
  • Supports IPC File, IPC Stream, Feather v1/v2; selective column reads, row limits, batch-aware iteration
  • ingest_arrow() convenience function and ingest(..., source_type="arrow") unified dispatch
  • Auto-detection by file extension and IPC magic bytes in FileTypeDetector
  • Optional dep: pip install semantica[ingest-arrow]; included in pip install semantica[all]
  • 34 tests

• Knowledge Explorer Deployment Templates (#684) by @ZohaibHassan16 and @KaifAhmad1

  • deploy/ directory with ready-to-use templates for Docker, Railway, Render, Fly.io, GCP Cloud Run, Azure Container Apps, Kubernetes + Helm
  • Fixed Dockerfile (correct path, non-root user, healthcheck, .dockerignore); full-stack docker-compose.yml; dev compose with hot-reload
  • Added /api/health endpoint; wired ALLOWED_ORIGINS, FALKORDB_HOST, FALKORDB_PORT from env vars
  • Helm chart passes helm lint; all templates carry namespace: {{ .Release.Namespace }}

• Neo4j Bulk CSV Export (#665) by @Luffy2208

  • Neo4jCSVExporter for neo4j-admin database import-compatible CSV files
  • Deterministic output, multi-label support, SHA-256 content-based stable IDs, dry_run() and validate_export()
  • export_neo4j_csv() convenience function; 13 tests

Fixed

• Arrow ingestion double full-scan on every data read (#705) by @KaifAhmad1
• Dead num_record_batches property materialising all table batches (#705) by @KaifAhmad1
• Arrow _open_file chaining the wrong exception in fallback cascade (#705) by @KaifAhmad1
• Neo4j CSV _write_csv crash with TypeError on dialect kwargs (#665) by @KaifAhmad1
• export_neo4j_csv double-passing kwargs to constructor and export() (#665) by @KaifAhmad1

Security

• Dependency updates: lxml ≥ 6.1.1, pydantic ≥ 2.13.4, azure-storage-blob, websockets, kafka-python, watchdog

Full Changelog: https://github.com/semantica-agi/semantica/blob/main/CHANGELOG.md

Semantica 0.5.0 — Distance Intelligence & Ontology Hub 🚀

Released: 2026-05-11

Highlights

• Distance Intelligence — measure semantic distance between any two nodes across the graph, API, and Explorer
• Ontology Hub — full workspace for browsing, loading, aligning, and validating ontologies in the Explorer
• Parquet Ingest — native Parquet file ingestion support
• KnowledgeGraph dataclass — first-class KnowledgeGraph type with native visualizer support
• MCP Server — modular, pipx-installable MCP server package with 4 new plugin bundles

New Features

Distance Intelligence

• Semantic distance between nodes across ContextGraph, REST API, and Knowledge Explorer — #502, #512 by @KaifAhmad1
• Node distance semantics in PathResponse (step count, hop distance, relationship type) — #472, #477 by @KaifAhmad1
• Bidirectional path finding via directed=false parameter — #469, #476 by @KaifAhmad1
• Distance intelligence optimization and UI polish — #550 by @KaifAhmad1

Ontology Hub

• Ontology Hub workspace in the Explorer: Registry, Loader, Entity Search, SKOS browser — #518, #521, #523 by @KaifAhmad1
• Alignments panel, SHACL Studio, and ontology health dashboard — #524 by @KaifAhmad1 and @ZohaibHassan16

Knowledge Explorer UI

• Full Explorer UI with graph, decision, provenance, temporal, and vocabulary workspaces — #453 by @KaifAhmad1 and @ZohaibHassan16
• Redesigned landing page — #516 by @ZohaibHassan16
• Grouped graph view — collapse related nodes into logical clusters — #493 by @ZohaibHassan16
• Graph declutter mode and calm layout — #483 by @ZohaibHassan16
• Stabilized local graph interaction — #487 by @Sameer6305
• Welcome screen and SPA root handler — #501, #463 by @KaifAhmad1
• Explorer visual refresh and graph element rendering system — #503 by @ZohaibHassan16
• Indexed search for large graphs (bisect-based, thread-safe) — #481 by @ZohaibHassan16

Parquet Ingest

• Native Parquet file ingestion (ParquetIngester) — #548 by @Luffy2208

KnowledgeGraph Dataclass

• New KnowledgeGraph dataclass with native KGVisualizer support — #471, #474 by @KaifAhmad1
• All visualize_* methods now accept KnowledgeGraph objects directly — #459 by @KaifAhmad1

MCP Server & Plugins

• Modular MCP server package at repo root, installable via pipx — by @KaifAhmad1
• New plugin bundles: Windsurf, Cline, Continue, VS Code — by @KaifAhmad1
• OpenClaw integration module — #460 by @KaifAhmad1
• Plugin local install fixed (hooks field, auto-load) — #489 by @serge

Deduplication

• DuplicateDetector now supports max_results, top_k_per_entity, min_similarity, and sort_by — by @KaifAhmad1

Cookbooks

• Datalog-style reasoning end-to-end notebook — #457 by @KaifAhmad1
• Manual ontology + Snowflake mapping cookbook — by @KaifAhmad1

Bug Fixes 🐛

• Windows install failure from gpu in [all] extra — #538 by @KaifAhmad1
• UnicodeEncodeError on cp1252 / Windows consoles in progress tracker — #537 by @KaifAhmad1
• Circular import in semantic_extract — #536 by @ZohaibHassan16
• Lazy-load optional ingest backends — uninstalled extras no longer raise on import — #535 by @ZohaibHassan16
• ConflictDetector.detect_conflicts duplicate method definition — #539 by @KaifAhmad1
• DuplicateDetector merged group key normalization — #540 by @ZohaibHassan16
• MCP server package structure for pipx installation — #544 by @KaifAhmad1
• OWL/Turtle exporter silent data-property omission — #478 / #479 by @KaifAhmad1
• Blazegraph literal serialization and prefixed datatype expansion — #450 by @KaifAhmad1
• TripletStore IRI resolution against ontology namespace base URI — #447 / #451 by @KaifAhmad1
• OWL generation — preserve user-facing schema fields, align IRIs with namespace — #449 by @KaifAhmad1
• Provenance upstream ancestor traversal and direction classification — #480 by @Sameer6305
• DeepSeek provider switched to OpenAI SDK client — #482 by @lingli
• Distance intelligence visibility and slash-safe API calls — #513 / #515 by @ZohaibHassan16
• Explorer graph motion and live layout restore — #486 by @KaifAhmad1
• Polynomial ReDoS regex removed from format detection — #521 by @KaifAhmad1

Security 🔒

• Patched 12 vulnerabilities (CRITICAL → LOW) across path traversal, injection, and unsafe deserialization — #452 by @KaifAhmad1
• Updated mkdocs ≥1.6.1 — #507
• Updated mkdocs-mermaid2-plugin — #508
• Updated mkdocs-jupyter — #509
• Updated mkdocs-material — #511
• Updated pymdown-extensions — #510

Dependencies

• Docker base image: python 3.12-slim → 3.14-slim — #466
• Docker base image: node 20-alpine → 25-alpine — #465
• pytest-benchmark ≥5.2.3 — #522

Contributors

• @KaifAhmad1 — Distance intelligence, Ontology Hub, KnowledgeGraph dataclass, TripletStore, Blazegraph, MCP server, security, Windows fixes, Explorer welcome screen, OWL exporter, OpenClaw, MCP packaging, Datalog cookbook
• @ZohaibHassan16 — Explorer UI overhaul, grouped view, graph declutter, indexed search, landing page, lazy ingest, circular import fix
• @Sameer6305 — Provenance upstream traversal fix, local graph interaction
• @lingli — DeepSeek provider fix
• @Luffy2208 — Parquet ingest support
• @serge — Plugin local install fix
• @dependabot — Automated dependency and security updates

Breaking Changes

None.

Semantica v0.4.0 — Release Notes

Released: 2026-04-08
PyPI: pip install semantica==0.4.0
Tag: v0.4.0
Full Changelog: CHANGELOG.md

v0.4.0 is the largest feature release to date. It ships a complete bi-temporal intelligence stack, a production-ready Knowledge Explorer API, first-class SHACL validation, SKOS vocabulary management, ontology alignment & diff, an Agno agentic framework integration, a Datalog reasoning engine, and a broad sweep of reliability, performance, and security fixes.

Test suite: 886 passed · 9 skipped · 0 failed

What's New

Temporal Intelligence

A full bi-temporal model is now baked into the core. Every entity, relationship, decision, and provenance record can carry valid time (when a fact was true in the world) and transaction time (when it was recorded in the system).

Core Temporal Data Model (PR #396)

• New semantica.kg.temporal_model with shared parsing, normalization, and serialization helpers used across all temporal APIs
• TemporalBound and BiTemporalFact exported from semantica.kg
• valid, transaction, and both time-axis filtering in all temporal queries
• TemporalValidationError raised consistently on invalid inputs — no silent coercions
• History-preserving revisions in TemporalVersionManager.apply_revision() with supersession semantics

Temporal Query Engine: Point-in-Time Correctness (PR #397)

• TemporalGraphQuery.reconstruct_at_time(graph, at_time) — builds a consistent point-in-time subgraph without mutating the source
• query_at_time() uses reconstruction internally so returned subgraphs never contain dangling edges
• TemporalConsistencyReport — detects inverted intervals, relationships outside entity lifetimes, missing endpoints, overlapping same-type relationships, and temporal gaps
• validate_temporal_consistency(graph) available as a top-level module function
• Sequence and cycle pattern detection with pattern_type, signature, frequency, and per-occurrence detail
• Calendar-aligned temporal evolution bucketing via temporal_granularity
• Causal ordering controls on find_temporal_paths() — enforce_causal_ordering, ordering_strategy (strict, overlap, loose)

Deterministic Temporal Reasoning Engine (PR #398)

• New semantica.kg.temporal_reasoning — zero LLM calls, pure deterministic reasoning
• Full Allen interval algebra via IntervalRelation — all 13 relations (before, meets, overlaps, starts, during, finishes, equals, and inverses)
• TemporalReasoningEngine with helpers for interval merging, gap analysis, coverage calculation, timelines, and retroactive coverage
• Circular import risk between semantica.reasoning and semantica.kg eliminated; semantica.reasoning access preserved via re-exports

Temporal Awareness in Context Graph (PR #399)

• Decision dataclass carries valid_from / valid_until validity windows — superseded decisions remain in the graph (immutable history)
• find_precedents_by_scenario(include_superseded=False, as_of=None) — defaults exclude expired decisions; as_of enables point-in-time queries
• ContextGraph.state_at(timestamp) — serializable point-in-time snapshot; source graph never mutated
• CausalChainAnalyzer.trace_at_time(event_id, at_time) — reconstructs causal chain using only edges recorded up to at_time
• AgentContext.checkpoint(label), diff_checkpoints(label1, label2), flush_checkpoint(label) — named in-memory snapshots with structured diffs

Temporal Metadata Extraction from Text (PR #400)

• extract_relations_llm(extract_temporal_bounds=True) — each returned Relation gains valid_from, valid_until, temporal_confidence (0.0–1.0), and temporal_source_text; default False is 100% backward-compatible
• Calibrated confidence anchors baked into the prompt: 1.00 = full ISO date → 0.00 = no temporal signal
• New TemporalNormalizer — zero LLM calls, pure regex + dateutil:
  • normalize(value) → (valid_from, valid_until) UTC datetime tuple or None
  • normalize_phrase(phrase) → domain metadata dict or None
  • 13-domain default phrase map covering General/Policy, Healthcare, Cybersecurity, Supply Chain, Finance, and Energy
  • Ambiguous DD/MM/YYYY inputs issue TemporalAmbiguityWarning — never silently guesses locale
  • User-supplied phrase_map merged over defaults at construction

Temporal Provenance & Export (PR #401)

• ProvenanceTracker.track_entity() auto-stamps recorded_at on every new record
• query_recorded_between(start, end) — returns all provenance records within an inclusive time range
• revision_history(fact_id) — complete revision chain ordered by recorded_at ascending
• export_audit_log(fact_ids, format) — "json" (pretty-printed) or "csv" (with header row)
• RDFExporter.export_to_rdf(include_temporal=True, time_axis="valid"|"transaction"|"both") — emits OWL-Time triples for all temporally-annotated relationships
• create_snapshot() stamps "format_version": "1.0"; validate_snapshot() and migrate_snapshot() for stable snapshot lifecycle management

Temporal GraphRAG Integration (PR #402)

• TemporalGraphRetriever — drop-in wrapper for any ContextRetriever; filters retrieved entities and relationships to a point in time; at_time=None is a true passthrough
• ContextRetriever.query_with_reasoning(at_time=..., header_template=...) — structured temporal header prepended to LLM context; format-string injection guard via str.replace
• TemporalQueryRewriter — extracts temporal_intent, at_time, start_time, end_time, and rewritten_query from natural language; regex-only by default, optional LLM-assisted mode

Ontology & Knowledge Representation

SHACL Shape Generation & Validation (PR #318)

• SHACLGenerator derives SHACL node and property shapes from any Semantica ontology dict — zero hand-authoring required
• Three quality tiers: "basic" (structure + cardinality), "standard" (adds sh:in, sh:pattern, inheritance), "strict" (adds sh:closed true + sh:ignoredProperties)
• Output formats: Turtle, JSON-LD, N-Triples; iterative multi-level inheritance propagation, cycle-safe
• OntologyEngine.to_shacl(), export_shacl(), and validate_graph(explain=True) — plain-English explanations for all 7 SHACL constraint types
• SHACLValidationReport with conforms, violations, warnings, summary(), explain_violations(), to_dict()
• Install: pip install semantica[shacl]

SKOS Vocabulary Module (PR #319)

• TripletStore.add_skos_concept() — assembles and stores all required SKOS triples automatically via existing add_triplets() API
• TripletStore.get_skos_concepts(scheme_uri=None) — SPARQL-backed retrieval with multi-value altLabel/broader/narrower collapsing
• OntologyEngine.list_vocabularies(), list_concepts(scheme_uri), search_concepts(query, scheme_uri=None) — injection-safe SPARQL throughout
• NamespaceManager.get_skos_uri(local_name) and build_concept_scheme_uri(name) namespace helpers

Ontology Alignment API (PR #361)

• OntologyEngine.create_alignment(source_uri, target_uri, predicate) — stores triples using standard OWL/SKOS predicates (owl:equivalentClass, skos:exactMatch, skos:relatedMatch, etc.)
• get_alignments(entity_uri) — bidirectional retrieval of all alignments for an entity
• ReuseManager.suggest_alignments(target, source) — O(N+M) hashmap heuristic over exact label matches
• QueryEngine.expand_entity_uri(uri, store, use_alignments=True) — SPARQL expansion to automatically include aligned equivalents in queries
• SPARQL injection hardened in list_alignments and build_values_clause

Ontology Diff & Migration (PR #367)

• VersionManager.diff_ontologies(base, target) — structured diff covering classes, properties, individuals, and axioms
• ChangeLogAnalyzer.analyze(diff) — classifies impact: CRITICAL/BREAKING, HIGH/BREAKING, MEDIUM/POTENTIALLY_BREAKING, INFO/NON_BREAKING
• ImpactReport and generate_change_report(diff) — structured output with summary, impact_classification, and recommendations
• OntologyEngine.compare_versions(base_id, target_id, run_validation=True, graph_data=...) — end-to-end orchestrator with optional validation and graph-instance checks

Knowledge Explorer

A full FastAPI backend for the Semantica dashboard. Install with pip install semantica[explorer] and launch via semantica-explorer --graph my_graph.json.

Graph API (PR #384)

• GET /api/graph/nodes|edges|stats — type/keyword filter, skip/limit pagination
• GET /api/graph/node/{id}/neighbors — BFS traversal, configurable depth 1–5
• GET /api/graph/node/{id}/path — BFS or Dijkstra, dispatched via algorithm param
• POST /api/graph/search — full-text search across node content and metadata

Analytics, Decisions & Temporal (PR #384)

• GET /api/analytics — centrality, community detection, connectivity (comma-separated metrics param)
• GET /api/decisions/{id}/chain|precedents|compliance — causal chain BFS, ranked precedent retrieval, in-graph compliance edge scan
• GET /api/temporal/snapshot|diff|patterns — point-in-time snapshots, node-set diffs between timestamps, pattern detection

Enrichment & Export (PR #384)

• POST /api/enrich/extract|links|dedup|reason — NLP extraction, link prediction, deduplication, forward/backward inference
• POST /api/export — 12 formats: JSON, Turtle, RDF-XML, N-Triples, CSV, GraphML, GEXF, OWL, Cypher, AQL, YAML; temp files always cleaned via try/finally
• POST /api/import — JSON/JSON-LD multipart upload with WebSocket real-time progress events

SKOS Vocabulary REST API (PR #426)

• GET /api/vocabulary/schemes — all skos:ConceptScheme nodes
• GET /api/vocabulary/hierarchy?scheme=<uri> — full broader/narrower concept tree with cycle detection
• POST /api/vocabulary/import — accepts .ttl, .rdf, .owl uploads; invalid files return HTTP 422

Infrastructure

• Thread-safe GraphSession with 8 lazily-initialized analytics components under RLock (PR #385)
• WebSocket ConnectionManager for real-time broadcast and per-client messaging
• 28 Pydantic v2 request/response models; 99 integration tests, all passing

Integrations

Agno Agentic Framework (Issue #249)

Five components making Semantica the memory and knowledge layer for Agno agents. All degrade gracefully when agno is not installed.

• AgnoContextStore — graph-backed agent memory implementing agno.memory.db.base.MemoryDb; supports full CRUD plus record_decision(), find_precedents(), retrieve()
• AgnoKnowledgeGraph — multi-hop GraphRAG knowledge base implementing agno.knowledge.base.AgentKnowledge; ingests files, directories, URLs, and raw text via NER → relation extraction → graph → vector index pipeline
• AgnoDecisionKit — Agno Toolkit exposing 6 decision-intelligence tools: record_decision, find_precedents, trace_causal_chain, analyze_impact, check_policy, get_decision_summary
• AgnoKGToolkit — Agno Toolkit exposing 7 KG pipeline tools: extract_entities, extract_relations, add_to_graph, query_graph, find_related, infer_facts, export_subgraph
• AgnoSharedContext — team-level coordinator with a single shared ContextGraph; bind_agent(role) returns a role-scoped view with cross-agent memory visibility; thread-safe via RLock

Install: pip install semantica[agno]
Cookbooks: cookbook/integrations/agno_decision_intelligence.ipynb, agno_graphrag_context.ipynb, agno_multi_agent_shared_context.ipynb

Novita AI Provider (PR #374)

• create_provider("novita") — OpenAI-compatible integration; default model deepseek/deepseek-v3.2; configured via NOVITA_API_KEY

Reasoning

Native Datalog Reasoning Engine (PR #371)

• DatalogReasoner — pure-Python bottom-up semi-naive fixpoint engine with guaranteed termination on finite graphs
• Supports recursive Horn clause rules (e.g. ancestor(X,Y) :- parent(X,Z), ancestor(Z,Y).) — handles cases that loop the existing forward/backward engine indefinitely
• query("pred(?X, ?Y)") returns variable-binding dicts; bindings={"Y": "val"} for pre-bound verification
• load_from_graph(ContextGraph) — one-call conversion of all graph edges and nodes to Datalog facts
• O(1) delta-index lookup per iteration; derive_all() skips re-evaluation when inputs are unchanged
• DatalogReasoner, DatalogFact, DatalogRule exported from semantica.reasoning

Pattern Matcher Restored (PR #387)

• Dead code silently overwrote _match_pattern's full regex (pre-bound variable embedding, repeated-variable backreferences (?P=var)) with a simple re.escape pattern — breaking transitivity, symmetry, and self-join rules entirely
• Removed; re.error exceptions now surfaced instead of swallowed

Performance & Reliability

ContextGraph O(N) → O(limit) Pagination (PR #431)

• find_nodes and find_edges now use generator expressions consumed via itertools.islice — on a 50k-node / 100k-edge graph, each paginated request previously allocated up to 2.5M dicts and caused 502 timeouts; now O(limit) in both time and space
• Ghost-node fix: add_edges accepts both "source_id"/"target_id" and "source"/"target" key names — edges from find_edges no longer silently produce None → None entries
• Deterministic page boundaries: find_nodes and find_active_nodes call sorted() on index sets before iterating
• stats() applies the same validity filters as find_nodes/find_edges so counts always match what pagination returns

ContextGraph Thread Safety (PR #385)

• threading.RLock added to ContextGraph.__init__; all mutation and read/query paths protected
• GraphSession lazy analytics properties initialized under RLock — no double-instantiation under concurrent FastAPI workers

ContextGraph Traversal Fallbacks (PR #386)

• All 7 DecisionQuery methods and 4 DecisionRecorder methods have native ContextGraph fallback paths — in-memory usage no longer requires a graph database backend

Snapshot & Audit Trail (PRs #393, #394)

• restore_snapshot() requires explicit confirmation before destructive restore — rollback protection
• get_node_history() for per-entity audit inspection; diff() as a Git-like alias over version comparisons
• Both nodes/edges and entities/relationships snapshot schemas accepted transparently

Named Graph Support (PR #432)

• enable_named_graphs config flag correctly forwarded through TripletStore.execute_query()
• Duplicate FROM <...> / FROM NAMED <...> clause prevention in QueryEngine.prepare_query()
• default_graph_uri config alias added alongside existing default_graph
• Graph URIs percent-encoded before SPARQL interpolation in version-pruning DROP SILENT GRAPH statements

Bug Fixes

• OllamaProvider ignored base_url (PR #408) — all requests silently hit localhost:11434; fixed by instantiating ollama.Client(host=self.base_url) instead of assigning the raw module
• CentralityCalculator crash — _build_adjacency() failed on ContextGraph edges (dataclass objects vs plain dicts); fixed to handle both shapes
• find_path always used BFS (PR #384) — algorithm query param was parsed but never dispatched; now correctly routes to dijkstra_shortest_path or bfs_shortest_path
• /api/enrich/links blocked the event loop (PR #385) — score_link scoring loop ran inline in async def; wrapped in asyncio.to_thread
• Temp file leak in export_graph (PR #384) — file not deleted on exception; fixed with try/finally cleanup
• spaCy NER crash — NERExtractor crashed in environments where spaCy is installed but broken at runtime; fallback now catches runtime initialization failures, not just missing-model errors
• ChangeCategory enum typo (PR #367) — "potenitally_breaking" → "potentially_breaking"

Security

• CWE-312/359/532 — Sensitive data in logs — Removed debug print blocks in relation_extractor.py and triplet_extractor.py that wrote api_key values to stdout in verbose mode
• CWE-20 — Incomplete URL sanitization — "url" in urls replaced with any(url == "url" for url in urls) — eliminates substring match that could match attacker-controlled URLs at arbitrary positions
• Overpermissioned CI workflows — permissions: contents: read added to benchmark.yml and security.yml; both previously inherited repo-default (potentially read-write) permissions
• SHACL path traversal — Replaced len < 500 and "\n" not in s path-vs-content heuristic with os.path.exists(); prevents attacker-controlled SHACL strings from being silently interpreted as file paths
• SHACL inheritance mutation — _propagate_inheritance now uses dataclasses.replace() instead of appending parent PropertyShape objects by reference; child mutations no longer silently corrupt parent shapes
• SPARQL injection — Hardened search_concepts, list_alignments, and build_values_clause with full character escaping and _sanitize_uri guards on all user-controlled inputs

Installation

pip install semantica==0.4.0

pip install semantica[shacl]      # SHACL validation (requires pyshacl)
pip install semantica[explorer]   # Knowledge Explorer API (requires FastAPI)
pip install semantica[agno]       # Agno framework integration
pip install semantica[llm-all]    # All LLM providers
pip install semantica[all]        # Everything

Contributors

@KaifAhmad1

• Authored the full temporal intelligence stack — data model (#396), point-in-time query engine (#397), deterministic reasoning engine (#398), context graph temporal awareness (#399), text-to-temporal extraction + TemporalNormalizer (#400), provenance & OWL-Time export (#401), GraphRAG integration (#402)
• Authored SHACL shape generation & validation (#318) and SKOS vocabulary module (#319)
• Security hardening — CodeQL alert remediation, SPARQL injection fixes, context explainability output fixes
• Review patches and follow-up fixes across all contributor PRs

@ZohaibHassan16

• Knowledge Explorer API backend (#384), thread safety & pagination (#385), ContextGraph traversal fallbacks (#386)
• SKOS vocabulary REST API (#426) and RDF parsing utility (#425)
• ContextGraph pagination & edge integrity fixes (#431)
• Snapshot schema compatibility (#393), audit trail & rollback protection (#394)
• Ontology alignment API (#361), ontology diff & migration (#367)
• Native Datalog reasoning engine (#371)

@Sameer6305

• Named graph support (#432)

@Alex-wuhu

• Novita AI provider integration (#374)

@AlexeyMyslin

• OllamaProvider base_url fix (#408)

PyPI · GitHub Release · Documentation

🧠 Semantica v0.3.0 — First Stable Release

Released: 2026-03-10  |  PyPI: pip install semantica  |  Python: 3.8 – 3.12  |  License: MIT

The first Production/Stable release of Semantica — an open-source framework for building context graphs and decision intelligence layers for AI agents. This release consolidates everything shipped across three stages: 0.3.0-alpha (2026-02-19), 0.3.0-beta (2026-03-07), and 0.3.0 stable (2026-03-10).

pip install --upgrade semantica

No breaking changes. All new parameters carry safe defaults. All new methods are purely additive.

🚦 Release Highlights

• 🕐 Temporal Validity — valid_from/valid_until on nodes & edges; query what's active at any point in time
• 🔗 Cross-Graph Navigation — link separate ContextGraph instances; navigate across them; survives save/load
• ⚖️ Weighted BFS Traversal — filter multi-hop queries by edge confidence with min_weight
• 🧠 Decision Intelligence — full lifecycle: record → causal chain → impact analysis → precedent search → policy enforcement
• 🔄 Delta Processing — SPARQL-based incremental graph diffs; only changed data flows through the pipeline
• 🗃️ Deduplication v2 — 6.98x faster semantic dedup, 63.6% faster candidate generation
• 📤 New Export Formats — ArangoDB AQL, Apache Parquet (Spark/BigQuery/Databricks ready)
• 🗄️ Graph Backends — Apache AGE, PgVector, AWS Neptune, FalkorDB
• ✅ 886+ tests passing — 0 failures

👥 Contributors

✨ v0.3.0 Stable — Context Graph Feature Completeness

Shipped 2026-03-10 · All changes by @KaifAhmad1

🕐 Temporal Validity Windows

Nodes and edges now carry first-class valid_from / valid_until ISO datetime fields — stored directly on the ContextNode and ContextEdge dataclasses, not buried in metadata.

New API:

• add_node(valid_from=..., valid_until=...) and add_edge(valid_from=..., valid_until=...) — set validity window at creation
• node.is_active(at_time=None) and edge.is_active(at_time=None) — returns True if live at the given time (defaults to now)
• graph.find_active_nodes(node_type=None, at_time=None) — filters entire graph to active nodes only

Bug fixes:

• is_active() crashed with TypeError on tz-aware datetime inputs — fixed by normalising to tz-naive UTC via new _parse_iso_dt() helper
• Validity fields silently lost during serialisation — fixed across all four paths: add_nodes(), add_edges(), to_dict(), from_dict()

🔗 Cross-Graph Navigation

Separate ContextGraph instances can now be linked and navigated between. Links are fully durable — they survive save_to_file() / load_from_file() and reconnect via a registry.

New API:

• graph.graph_id — stable UUID assigned at init; persisted to JSON
• link_graph(other_graph, source_node_id, target_node_id) — creates a navigable bridge; returns link_id
• navigate_to(link_id) — returns (other_graph, target_node_id)
• resolve_links({graph_id: instance}) — reconnects links after load; returns count resolved
• save_to_file() — now writes a links section alongside nodes and edges
• load_from_file() — restores graph_id and populates _unresolved_links

Bug fix: Previous implementation auto-created marker targets as phantom "entity" nodes — fixed by pre-creating a "cross_graph_link" typed ContextNode before inserting the marker edge.

14 new tests in tests/context/test_cross_graph_navigation.py covering link creation, phantom-node prevention, partial registry resolution, and full save/load round-trips.

⚖️ Weighted Multi-Hop BFS Traversal

get_neighbors() now accepts a min_weight threshold to confine traversal to high-confidence causal links only. Default 0.0 passes all edges — fully backward-compatible.

🔧 Additional Fixes in v0.3.0 Stable

• PipelineBuilder.add_step() return type annotation corrected from "PipelineBuilder" to "PipelineStep"
• test_hybrid_search_performance fixed to accumulate a true search_times list; threshold relaxed to < 5.0s for real sentence-transformers latency

🔧 v0.3.0-beta — Semantic Extraction, Deduplication v2, New Export Formats

Shipped 2026-03-07

🧩 Semantic Extraction Fixes — @KaifAhmad1 (PR #354, #355)

LLM Relation Extraction:

• Unmatched subjects/objects now produce a synthetic UNKNOWN entity instead of silently dropping the relation
• Orphaned legacy block in _parse_relation_result that appended every relation twice has been removed
• extraction_method parameter added — typed extraction paths now record "llm_typed" instead of "llm"

Reasoner Pattern Matching:

• _match_pattern in reasoner.py fully rewritten — splits patterns on ?var placeholders, escapes only literal segments, uses backreferences for repeated variables and non-greedy .+? to prevent over-consumption

RDF Export Aliases:

• RDFExporter now accepts "ttl", "nt", "xml", "rdf", and "json-ld" as format aliases — zero API changes

Tests added: tests/reasoning/test_reasoner.py (4 tests), tests/semantic_extract/test_relation_extractor.py (6 tests), tests/export/test_rdf_exporter.py (8 tests)

🔄 Incremental / Delta Processing — @ZohaibHassan16, @KaifAhmad1 (PR #349)

• Native SPARQL-based diff between graph snapshots — only changed triples enter the pipeline
• delta_mode flag in PipelineBuilder for near-real-time incremental workloads
• Version snapshot management with graph URI tracking and per-snapshot metadata storage
• prune_versions() for automatic retention cleanup of old snapshots

Bug fixes: corrected SPARQL variable order, fixed class references, resolved duplicate dictionary keys.

🗃️ Deduplication v2 Suite — @ZohaibHassan16, @KaifAhmad1 (PR #338, #339, #340, #344)

Three independently opt-in tiers — legacy mode remains the default, fully backward-compatible.

Candidate Generation v2 (PR #338):

• New blocking_v2 and hybrid_v2 strategies replace O(N²) pair enumeration
• Multi-key blocking with normalised token prefixes, type-aware keys, and optional phonetic (Soundex) matching
• Deterministic max_candidates_per_entity budgeting with stable sorting
• 63.6% faster in worst-case scenarios (0.259s → 0.094s for 100 entities)

Two-Stage Scoring Prefilter (PR #339):

• Fast gates for type mismatch, name-length ratio, and token overlap eliminate expensive semantic scoring for obvious non-matches
• Configurable thresholds: min_length_ratio, min_token_overlap_ratio, required_shared_token
• 18–25% faster batch processing when enabled (prefilter_enabled=False by default)

Semantic Relationship Deduplication v2 (PR #340):

• Canonicalisation engine with predicate synonym mapping (e.g. works_for → employed_by)
• O(1) hash matching for exact canonical signatures before any semantic scoring
• Weighted scoring: 60% predicate + 40% object with explainable semantic_match_score in metadata
• 6.98x faster than legacy mode (83ms vs 579ms)
• dedup_triplets() infinite recursion bug fixed; promoted to first-class API in methods.py

Migration guide: MIGRATION_V2.md with complete examples for all v2 strategies (PR #344)

📤 New Export Formats — @tibisabau (PR #342, #343)

ArangoDB AQL Export (PR #342):

• Full AQL INSERT statement generation for vertices and edges
• Configurable collection names with validation and sanitisation; batch processing (default: 1000)
• export_arango() convenience function; .aql auto-detection in the unified exporter
• 17 tests — 100% pass rate

Apache Parquet Export (PR #343):

• Columnar storage with configurable compression: snappy, gzip, brotli, zstd, lz4, none
• Explicit Apache Arrow schemas with type safety and field normalisation
• Analytics-ready: pandas, Spark, Snowflake, BigQuery, Databricks
• export_parquet() convenience function; .parquet auto-detection
• 25 tests — 100% pass rate

🐛 Beta Bug Fixes — @KaifAhmad1

Context module:

• retrieve_decision_precedents — entity extraction correctly gated on use_hybrid_search=True
• _extract_entities_from_query — switched to word[0].isupper() to capture camelCase identifiers like CreditCard
• Added missing expand_context() (BFS traversal) and _get_decision_query() methods
• Fixed hybrid_retrieval, dynamic_context_traversal, multi_hop_context_assembly for correct single-pass BFS
• Fixed _retrieve_from_vector fallback to prevent empty content and negative similarity scores

KG module:

• calculate_pagerank — added alpha/max_iter aliases; return format structured to {"centrality": scores, "rankings": sorted_list}
• community_detector._to_networkx — fixed silent edge-loss when a NetworkX graph is passed directly
• Added 9 domain-specific tracking methods to AlgorithmTrackerWithProvenance
• Created provenance_tracker.py with ProvenanceTracker; correctly exported from semantica.kg

Pipeline module:

• Retry loop fixed — now correctly iterates to max_retries
• Added RecoveryAction + handle_failure(error, policy, retry_count) with LINEAR, EXPONENTIAL, and FIXED backoff
• add_step() fixed to return the created PipelineStep
• validate added as public alias for validate_pipeline in PipelineValidator

Other:

• Fixed NameError — missing Type import in utils/helpers.py
• Vector store performance threshold relaxed from < 100ms to < 500ms per decision
• Windows cp1252 encoding fixed in test files

Beta result: ~840 tests passing, 36 skipped (external services), 0 failed

🚀 v0.3.0-alpha — Foundational Features

Shipped 2026-02-19

🧠 Decision Intelligence & Agent Context — @KaifAhmad1 (PR #307, #315)

The foundational 0.3.0 feature — complete overhaul of semantica.context for production-grade decision intelligence.

Full decision lifecycle:

• record_decision() → add_causal_relationship() → trace_decision_chain() → analyze_decision_impact() → analyze_decision_influence() → find_similar_decisions()

AgentContext — unified wrapper:

• Feature flags: decision_tracking, kg_algorithms, graph_expansion
• Methods: store(), retrieve(), get_conversation_history(), get_statistics(), capture_cross_system_inputs()

Supporting components:

• AgentMemory — working, conversation, and long-term memory tiers
• PolicyEngine — versioned policy nodes, check_decision_rules(), PolicyException model, graceful fallback without a graph store
• Hybrid precedent search — vector + structural + category similarity with configurable weights

9 critical bug fixes in PR #315: causal chain depth, None metadata, nonexistent node handling, find_precedents() direction, missing from_dict(), missing properties in to_dict(), UUID generation — all 71 context tests passing after fixes.

📊 KG Algorithms — @KaifAhmad1 (PR #292, #293)

30+ graph algorithms across 7 categories:

• Node embeddings: Node2Vec, DeepWalk, Word2Vec via NodeEmbedder
• Similarity: cosine, Euclidean, Manhattan, correlation via SimilarityCalculator
• Path finding: Dijkstra, A*, BFS, K-shortest paths via PathFinder
• Link prediction: preferential attachment, Jaccard, Adamic-Adar via LinkPredictor
• Centrality: degree, betweenness, closeness, PageRank via CentralityAnalyzer
• Community detection: Louvain, Leiden, label propagation via CommunityDetector
• Connectivity: components, bridges, density via ConnectivityAnalyzer

Decision embedding pipeline (PR #293):

• DecisionEmbeddingPipeline — semantic + structural embeddings
• HybridSimilarityCalculator — configurable weights (semantic: 0.7, structural: 0.3)
• Convenience API: quick_decision(), find_precedents(), explain(), similar_to(), batch_decisions(), filter_decisions()
• Performance: 0.028s per decision, 0.031s search, ~0.8KB memory per decision

🗄️ Graph Database Backends — @Sameer6305, @KaifAhmad1

Apache AGE (PR #311):

• AgeStore class with full GraphStore API compatibility (openCypher via SQL on PostgreSQL)
• SQL injection vulnerabilities fixed with comprehensive input validation
• psycopg2-binary dependency added; migration guide included

PgVector Store (PR #303):

• Native PostgreSQL vector storage using the pgvector extension
• Distance metrics: cosine, L2/Euclidean, inner product with automatic score normalisation
• HNSW and IVFFlat indexing for approximate nearest-neighbour search
• JSONB metadata with flexible filtering; connection pooling with psycopg3/psycopg2 fallback
• SQL injection protection via psycopg_sql.SQL(); 36+ tests with Docker integration

⚙️ Infrastructure — @d4ndr4d3, @KaifAhmad1 (PR #299, #301)

ResourceScheduler Deadlock Fix:

• Root cause: nested lock acquisition in allocate_resources() with threading.Lock() deadlocked under concurrent load
• Fix: replaced with threading.RLock() to allow reentrant acquisition
• Added ValidationError when no resources can be allocated; progress tracking moved outside lock scope
• 6 regression tests for deadlock prevention

Security Configuration:

• Dependabot configured for bi-weekly security updates with manual review
• Automated security scans (Bandit, Safety, Semgrep) on schedule
• Zero auto-merge policy for security-critical packages

📊 Test Coverage Summary

• semantica.context — 335 tests
• semantica.kg — ~430 tests
• semantica.semantic_extract — 70 tests (9 skipped — external LLM APIs)
• semantica.reasoning — 19 tests
• semantica.pipeline, semantica.export, semantica.deduplication — all passing
• Real-world E2E scenarios — 85 tests
• Grand total: 886+ passing — 0 failures

Semantica v0.3.0-beta — Release Notes

Date: 2026-03-07 | Tag: v0.3.0-beta | Status: Internal Beta (Pre-release)

Consolidates all alpha and unreleased features for internal validation ahead of the public 0.3.0 launch.

What's New

Semantic Extraction & Reasoning

• Multi-Founder LLM Extraction Fix (#354) — Unmatched relation subjects/objects now produce synthetic UNKNOWN entities instead of being silently dropped; all LLM-returned co-founders preserved
• Reasoner Pattern Matching Rewrite (#354) — _match_pattern correctly handles multi-word values, pre-bound variables, repeated variable backreferences, and non-greedy separators

Export

• RDF / TTL Alias Fix (#355) — format="ttl", "nt", "xml", "rdf", "json-ld" all resolve without breaking existing callers
• ArangoDB AQL Export (#342) — Full AQL INSERT generation for vertices and edges; configurable batching; 17 tests passing
• Apache Parquet Export (#343) — Columnar storage with configurable compression (snappy, gzip, brotli, zstd, lz4); explicit Arrow schemas; 25 tests passing

Deduplication v2 (Epic #333)

• Candidate Generation v2 (#338) — blocking_v2 / hybrid_v2 strategies with multi-key and phonetic blocking; 63.6% faster worst-case
• Two-Stage Scoring Prefilter (#339) — Fast prefilter gates before expensive semantic scoring; 18–25% faster batch processing
• Semantic Deduplication v2 (#340) — Opt-in semantic_v2 with canonicalization, O(1) hash matching, weighted scoring; 6.98x speedup; fixed infinite recursion bug
• Migration Guide (#344) — MIGRATION_V2.md with full examples; 5.86x speedup confirmed; backward compatible

Incremental / Delta Processing

• Delta Processing (#349) — Native SPARQL delta computation between graph snapshots; delta_mode pipeline config; prune_versions() for snapshot retention; production-ready for near real-time pipelines

Bug Fixes

• NameError — missing Type import in utils/helpers.py; removed unused import from config_manager.py
• Context module — fixed retrieve_decision_precedents, hybrid_retrieval, dynamic_context_traversal, multi_hop_context_assembly, _retrieve_from_vector, _extract_entities_from_query; added missing expand_context and _get_decision_query methods
• Knowledge Graph module — fixed calculate_pagerank, community_detector._to_networkx, detect_communities, _build_adjacency; added ProvenanceTracker and 9 domain-specific tracking methods
• Pipeline module — fixed retry loop in execution_engine; added RecoveryAction with LINEAR / EXPONENTIAL / FIXED backoff; fixed add_step return value; added validate alias
• Test files — replaced emoji with ASCII for Windows cp1252 compatibility; fixed assertion ordering and loop bugs across 4 test files

Test Results

Contributors

@KaifAhmad1 · @ZohaibHassan16 · @tibisabau

🎉 Semantica v0.3.0-alpha Release

This alpha release introduces comprehensive decision tracking capabilities, advanced knowledge graph algorithms, and production-ready architecture for testing.

🚀 Major Features

Decision Tracking System

• Complete decision lifecycle management with audit trails
• Provenance tracking and lineage management
• Policy compliance and exception handling
• Decision influence analysis and impact scoring

Advanced Knowledge Graph Algorithms

• Node2Vec embeddings for semantic similarity
• Centrality analysis (degree, betweenness, closeness, eigenvector)
• Community detection and graph analytics
• Path finding and link prediction

Enhanced Context Module

• Unified AgentContext with granular feature flags
• Decision tracking integration
• Production-ready architecture with validation
• GraphStore capability validation

Vector Store Features

• Hybrid search combining semantic, structural, and category similarity
• Advanced retrieval with configurable weights
• FastEmbed integration for efficient operations

🧪 Testing & Quality

• 113+ tests passing across context and core modules
• Comprehensive decision tracking test coverage
• Enhanced error handling and edge case testing
• Fixed all critical test failures for release readiness

📦 Installation

pip install semantica==0.3.0a0

Overview

Release 0.2.7 adds Snowflake integration, Apache Arrow export, and benchmark suite.

🚀 New Features

Snowflake Connector for Data Ingestion

PR #276 by @Sameer6305

Native Snowflake connector with multi-authentication support (password, OAuth, key-pair, SSO). Includes table/query ingestion, schema introspection, and SQL injection prevention.

Tests: 24/24 passing
Dependency: db-snowflake optional

Apache Arrow Export Support

PR #273 by @Sameer6305

High-performance columnar export with explicit schemas, compression, and Pandas/DuckDB compatibility.

Tests: 20/20 passing
Dependency: db-arrow optional

Comprehensive Benchmark Suite

PR #289 by @ZohaibHassan16, @KaifAhmad1

137+ benchmarks across all modules with regression detection and CI/CD integration.

Features: Statistical analysis, environment-agnostic design, CLI tool

📊 Quality Assurance

• Total Tests: 44/44 passing
• Breaking Changes: None
• Backward Compatible: Yes

🛠 Installation

pip install semantica==0.2.7
pip install semantica[db-snowflake,db-arrow]==0.2.7

🙏 Contributors

• @Sameer6305: Snowflake Connector, Arrow Export
• @ZohaibHassan16: Benchmark Suite implementation
• @KaifAhmad1: Benchmark enhancements, CI/CD integration

🔗 Links

• GitHub: https://github.com/Hawksight-AI/semantica
• PyPI: https://pypi.org/project/semantica/
• Benchmarks: python benchmarks/benchmark_runner.py

📈 Performance

• Text Processing: >10,000 ops/sec
• Arrow Export: 10x faster
• Benchmark Coverage: 137+ tests

Thanks to all contributors for making this release possible!