Skip to content

v0.4.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 08 Apr 05:16
· 522 commits to main since this release
v0.4.0
1d04005

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

Contributors

Alex-yang00, KaifAhmad1, and 3 other contributors
Assets 4
Loading