Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

docs: add RELEASE_NOTES.md and condense README What's New section

KaifAhmad12d90bdaad5d9
diff --git a/README.md b/README.md
index 65f0eef6..11ca03ee 100644
--- a/README.md
+++ b/README.md
@@ -59,78 +59,22 @@ pip install semantica
## What's New in v0.3.0
-> **First stable release** — promoted to `Production/Stable` on PyPI.
-> Full summary of everything shipped across 0.3.0-alpha → 0.3.0-beta → 0.3.0 stable.
-
-### Context Graph — Feature Completeness
-
-- **Temporal validity windows** — `ContextNode` and `ContextEdge` now carry `valid_from` / `valid_until` ISO datetime fields. Call `node.is_active(at_time=None)` to check whether a node is live at any point in time, or `graph.find_active_nodes(node_type, at_time)` to filter an entire graph by validity. Fields survive full serialisation round-trips via `save_to_file()` / `load_from_file()` and the `to_dict()` / `from_dict()` path.
-- **Weighted multi-hop BFS** — `get_neighbors(hops, min_weight=0.0)` now accepts a minimum edge weight so you can confine traversal to high-confidence causal links and ignore noisy or low-trust relationships. Fully backward-compatible — default `0.0` passes all edges.
-- **Cross-graph navigation** — `link_graph(other_graph, source_node, target_node)` creates a navigable bridge between two separate `ContextGraph` instances and returns a `link_id`. Call `navigate_to(link_id)` to jump to the target graph and entry node. Links now survive save/load: `save_to_file()` writes a `links` section, and `resolve_links({graph_id: instance})` reconnects them after reload. Each graph carries a stable `graph_id` UUID for this purpose.
-- **Bug fixes** — `is_active()` now normalises tz-aware `datetime` inputs to tz-naive UTC (prevents `TypeError`); cross-graph marker nodes are correctly typed `"cross_graph_link"` instead of polluting the graph with phantom `"entity"` nodes; 14 new dedicated tests in `tests/context/test_cross_graph_navigation.py`.
-
-### Decision Intelligence & Agent Context (0.3.0-alpha / beta)
-
-- **Complete decision lifecycle** — `record_decision()`, `add_decision()`, `add_causal_relationship()`, `trace_decision_chain()`, `analyze_decision_impact()`, `analyze_decision_influence()`, and `find_similar_decisions()` all working end-to-end with full audit trails.
-- **Precedent search** — hybrid similarity search over past decisions combining vector, structural, and category similarity with configurable weights; `find_precedents()` and `retrieve_decision_precedents()` fixed for correct entity extraction behaviour.
-- **PolicyEngine** — versioned policy nodes, compliance checking, `check_decision_rules()`, exception handling with `PolicyException`; falls back gracefully when no graph store is present.
-- **AgentContext** — unified wrapper with granular feature flags (`decision_tracking`, `kg_algorithms`, `graph_expansion`), `store()`, `retrieve()`, `get_conversation_history()`, `get_statistics()`; `capture_cross_system_inputs()` for multi-agent pipelines.
-- **AgentMemory** — working, conversation, and long-term memory tiers with statistics.
-- **Multi-hop context assembly** — `expand_context()`, `dynamic_context_traversal()`, and `multi_hop_context_assembly()` all fixed for correct BFS and decision-query behaviour.
-
-### Knowledge Graph Algorithms (0.3.0-alpha)
-
-- **Advanced analytics** — PageRank centrality (`calculate_pagerank`), betweenness centrality, clustering coefficient, community detection via Louvain; all return structured dicts.
-- **Node embeddings** — Node2Vec via `NodeEmbedder`; `compute_embeddings(graph, node_labels, relationship_types)`.
-- **Link prediction** — `LinkPredictor.score_link(graph, n1, n2, method=)` for scoring potential new edges.
-- **Similarity** — `SimilarityCalculator.cosine_similarity(v1, v2)`.
-- **Provenance** — `ProvenanceTracker`, `GraphBuilderWithProvenance`, `AlgorithmTrackerWithProvenance` with 9 domain-specific tracking methods; now correctly exported from `semantica.kg`.
-
-### Semantic Extraction (0.3.0-beta)
-
-- **Multi-founder LLM extraction fix** — unmatched subjects/objects now produce a synthetic `UNKNOWN` entity instead of silently dropping the relation; all co-founders from LLM responses are preserved.
-- **Reasoner inference fix** — `_match_pattern` rewritten to split on `?var` placeholders first; pre-bound variables resolve to exact literals, repeated variables use backreferences, non-greedy matching prevents over-consumption.
-- **Duplicate relation fix** — orphaned legacy block in `_parse_relation_result` that appended every relation twice has been removed.
-- **LLM-typed extraction** — `extraction_method` parameter correctly sets `"llm_typed"` metadata on typed extraction paths.
-
-### Export & Storage (0.3.0-beta)
-
-- **RDF export aliases** — `RDFExporter` now accepts `"ttl"`, `"nt"`, `"xml"`, `"rdf"`, and `"json-ld"` as format aliases; no API changes for existing callers.
-- **ArangoDB AQL export** — full AQL INSERT statement generation for vertices and edges; batch processing; `export_arango()` convenience function; auto-detected from `.aql` extension.
-- **Apache Parquet export** — columnar export with configurable compression (snappy, gzip, brotli, zstd, lz4); explicit Arrow schemas; `export_parquet()` convenience function; analytics-ready for Spark, Snowflake, BigQuery, Databricks.
-
-### Deduplication v2 (0.3.0-beta)
-
-- **Candidate generation v2** — `blocking_v2` and `hybrid_v2` strategies replace O(N²) pair enumeration with multi-key blocking, phonetic Soundex matching, and deterministic `max_candidates_per_entity` budgeting; **63.6% faster** in worst-case scenarios.
-- **Two-stage scoring prefilter** — fast type-mismatch, name-length-ratio, and token-overlap gates skip expensive semantic scoring for obvious non-matches; **18–25% faster** batch processing; configurable thresholds.
-- **Semantic relationship deduplication v2** — canonicalisation engine with predicate synonym mapping (`works_for` → `employed_by`), O(1) hash matching for exact canonical signatures, weighted scoring (60% predicate + 40% object); **6.98x faster** than legacy mode.
-- **`dedup_triplets()` fix** — critical infinite recursion bug fixed; function is now a first-class API in `methods.py`.
-
-### Incremental / Delta Processing (0.3.0-beta)
-
-- **Delta computation** — native diff between graph snapshots using SPARQL; only changed data flows through the pipeline.
-- **Version snapshot management** — graph URI tracking, metadata storage, snapshot retention with `prune_versions()`.
-- **Delta-aware pipelines** — `delta_mode` configuration in `PipelineBuilder`; processes only changes for near-real-time workloads.
-
-### Pipeline & Production (0.3.0-alpha / beta)
-
-- **FailureHandler** — `handle_failure(error, policy, retry_count)` with `LINEAR`, `EXPONENTIAL`, and `FIXED` backoff strategies via `RetryPolicy` / `RetryStrategy`.
-- **PipelineValidator** — `validate(builder)` returns `ValidationResult(valid, errors, warnings)`; does not raise exceptions.
-- **`add_step()` fix** — correctly returns the created `PipelineStep` object (return type annotation corrected to match).
-- **Retry loop fix** — execution engine now iterates up to `max_retries` correctly.
-
-### Graph Database Backends (0.3.0-alpha)
-
-- **Apache AGE** — PostgreSQL graph extension with openCypher via SQL; SQL injection vulnerabilities fixed; input validation added.
-- **AWS Neptune** — Amazon Neptune with IAM authentication.
-- **FalkorDB** — `DecisionQuery` and `CausalChainAnalyzer` work directly with FalkorDB row/header shapes.
-
-### Test Coverage
-
-- **886+ tests passing, 0 failures** across all modules — context (335), KG (~430), semantic extraction (70), reasoning (19), pipeline, export, deduplication.
-- Added **85 real-world comprehensive tests** (`test_030_realworld_comprehensive.py`) covering tech companies, CEOs, investment chains, and healthcare scenarios end-to-end.
-
-See the full [CHANGELOG](CHANGELOG.md) for the complete diff.
+> First stable release — `Production/Stable` on PyPI. Ships across three stages: 0.3.0-alpha, 0.3.0-beta, and 0.3.0 stable.
+
+| Area | Highlights |
+|------|-----------|
+| **Context Graphs** | Temporal validity windows (`valid_from`/`valid_until`), weighted BFS (`min_weight`), cross-graph navigation (`link_graph`, `navigate_to`, `resolve_links`) with full save/load persistence |
+| **Decision Intelligence** | Complete lifecycle: `record_decision` → `trace_decision_chain` → `analyze_decision_impact` → `find_similar_decisions`; hybrid precedent search; `PolicyEngine` with versioned rules |
+| **KG Algorithms** | PageRank, betweenness, community detection (Louvain), Node2Vec embeddings, link prediction, path finding — all returning structured dicts |
+| **Semantic Extraction** | LLM relation extraction fixed (no silent drops); `_match_pattern` rewritten; duplicate relation bug removed; `"llm_typed"` metadata corrected |
+| **Deduplication v2** | `blocking_v2`/`hybrid_v2` candidate generation (**63.6% faster**); two-stage prefilter (**18–25% faster**); semantic dedup v2 (**6.98x faster**) |
+| **Delta Processing** | SPARQL-based incremental diff; `delta_mode` pipelines; snapshot versioning with `prune_versions()` |
+| **Export** | RDF format aliases (`"ttl"`, `"json-ld"`, etc.); ArangoDB AQL export; Apache Parquet export (Spark/BigQuery/Databricks ready) |
+| **Pipeline** | `FailureHandler` with LINEAR/EXPONENTIAL/FIXED backoff; `PipelineValidator` returning `ValidationResult`; retry loop fixed |
+| **Graph Backends** | Apache AGE (SQL injection fixed), AWS Neptune, FalkorDB, PgVector (HNSW/IVFFlat indexing) |
+| **Tests** | **886+ passing, 0 failures** — 335 context, ~430 KG, 70 semantic extraction, 85 real-world E2E |
+
+See [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full per-contributor breakdown and [CHANGELOG](CHANGELOG.md) for the complete diff.
---
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
new file mode 100644
index 00000000..a028313a
--- /dev/null
+++ b/RELEASE_NOTES.md
@@ -0,0 +1,282 @@
+# Semantica v0.3.0 — Release Notes
+
+**Released:** 2026-03-10
+**PyPI:** `pip install semantica`
+**Tag:** [v0.3.0](https://github.com/Hawksight-AI/semantica/releases/tag/v0.3.0)
+**Classification:** Production/Stable
+
+> First stable, full public release of Semantica. Covers everything shipped across three release stages: 0.3.0-alpha (2026-02-19), 0.3.0-beta (2026-03-07), and 0.3.0 stable (2026-03-10).
+
+---
+
+## Contributors
+
+| Contributor | Role |
+|------------|------|
+| [@KaifAhmad1](https://github.com/KaifAhmad1) | Lead maintainer — context graph, decision intelligence, KG algorithms, semantic extraction, pipeline, provenance, bug fixes, release management |
+| [@ZohaibHassan16](https://github.com/ZohaibHassan16) | Deduplication v2 suite (candidate generation, two-stage scoring, semantic dedup), incremental/delta processing, benchmark suite |
+| [@Sameer6305](https://github.com/Sameer6305) | Apache AGE backend, PgVector store, Snowflake connector, Apache Arrow export |
+| [@tibisabau](https://github.com/tibisabau) | ArangoDB AQL export, Apache Parquet export |
+| [@d4ndr4d3](https://github.com/d4ndr4d3) | ResourceScheduler deadlock fix |
+
+---
+
+## v0.3.0 — Stable (2026-03-10)
+
+### Context Graph Feature Completeness
+
+**Temporal Validity Windows** (by @KaifAhmad1)
+
+Nodes and edges now carry first-class `valid_from` / `valid_until` ISO datetime fields. These are stored directly on `ContextNode` and `ContextEdge` dataclasses — not in metadata — and survive full serialisation round-trips through `save_to_file()` / `load_from_file()` and `to_dict()` / `from_dict()`.
+
+- `ContextNode.is_active(at_time=None)` and `ContextEdge.is_active(at_time=None)` — returns `True` if the node/edge is live at the given time (defaults to now). Handles both tz-aware and tz-naive datetime inputs correctly.
+- `ContextGraph.find_active_nodes(node_type=None, at_time=None)` — filters the entire graph and returns only nodes within their validity window.
+- `add_node(valid_from=..., valid_until=...)` and `add_edge(valid_from=..., valid_until=...)` — pass validity fields directly in the call signature.
+- Bug fix: `is_active()` previously crashed with `TypeError` when passed a tz-aware `datetime` (e.g. `datetime.now(timezone.utc)`). Fixed by normalising all inputs to tz-naive UTC via a new `_parse_iso_dt()` helper.
+- Bug fix: validity fields were silently lost in `add_nodes()`, `add_edges()`, `to_dict()`, and `from_dict()`. All four paths now correctly preserve and restore them.
+
+**Weighted Multi-Hop BFS** (by @KaifAhmad1)
+
+`ContextGraph.get_neighbors(node_id, hops=1, relationship_types=None, min_weight=0.0)` now accepts a `min_weight` threshold. Any edge with weight below the threshold is skipped during BFS traversal, allowing callers to confine multi-hop queries to high-confidence causal links. Default `0.0` is fully backward-compatible.
+
+**Cross-Graph Navigation** (by @KaifAhmad1)
+
+Separate `ContextGraph` instances can now be linked and navigated between — hierarchically, like separate knowledge domains that reference each other.
+
+- `link_graph(other_graph, source_node_id, target_node_id, link_type="CROSS_GRAPH") -> str` — creates a navigable bridge and returns a `link_id`. Records a dedicated `"cross_graph_link"` typed marker node internally (not a phantom `"entity"`) and a marker edge.
+- `navigate_to(link_id) -> (other_graph, target_node_id)` — jumps to the target graph and entry node for a given link.
+- `graph_id` field — each `ContextGraph` now carries a stable UUID so instances can identify each other across save/load.
+- `save_to_file()` — now writes a `links` section alongside nodes and edges, containing `link_id`, `source_node_id`, `target_node_id`, and `other_graph_id` for every cross-graph link.
+- `load_from_file()` — restores `graph_id` and populates `_unresolved_links` from the `links` section.
+- `resolve_links(registry: Dict[str, ContextGraph]) -> int` — reconnects unresolved links post-load. Pass `{graph_id: graph_instance}` for each linked graph; returns the count of successfully resolved links. `navigate_to()` raises a clear `KeyError` with a `resolve_links()` hint if called before resolution.
+- Bug fix: the previous implementation auto-created the synthetic marker target as an `"entity"` node (phantom pollution). Fixed by explicitly pre-creating a `"cross_graph_link"` typed `ContextNode` before the marker edge.
+- 14 new tests in `tests/context/test_cross_graph_navigation.py` covering all scenarios including full save/load round-trips with partial registry resolution.
+
+**Other Fixes** (by @KaifAhmad1)
+
+- `PipelineBuilder.add_step()` return type annotation corrected from `"PipelineBuilder"` to `"PipelineStep"` — the implementation was already correct; only the annotation and docstring were stale.
+- `test_hybrid_search_performance` timing computation fixed — now accumulates a true `search_times` list instead of reusing the last loop iteration's `start_time`; threshold relaxed to `< 5.0s` for real `sentence-transformers` (384-dim) latency on development machines.
+
+**Test Coverage Added**
+
+- 14 cross-graph navigation tests (`tests/context/test_cross_graph_navigation.py`)
+- **Total: 335 context tests, 886+ tests across all modules — 0 failures**
+
+---
+
+## v0.3.0-beta — Beta (2026-03-07)
+
+### Semantic Extraction Fixes
+
+**Multi-Founder LLM Extraction & Reasoner Inference Fix** (PR #354, by @KaifAhmad1)
+
+- `_parse_relation_result` in `methods.py` — unmatched subjects/objects now produce a synthetic `UNKNOWN` entity instead of silently dropping the relation. All co-founders returned by the LLM are preserved in the output.
+- Duplicate relation fix — an orphaned legacy block that appended every relation twice has been removed.
+- `extraction_method` parameter added — typed extraction paths now correctly record `"llm_typed"` in relation metadata instead of `"llm"`.
+- `_match_pattern` in `reasoner.py` rewritten — splits patterns on `?var` placeholders first, then escapes only literal segments. Pre-bound variables resolve to exact literals, repeated variables use backreferences, non-greedy `.+?` prevents over-consumption of separators.
+- Added `tests/reasoning/test_reasoner.py` (4 tests) and `tests/semantic_extract/test_relation_extractor.py` (6 tests).
+
+**TTL Export Alias Fix** (PR #355, by @KaifAhmad1)
+
+- `RDFExporter` now accepts `"ttl"`, `"nt"`, `"xml"`, `"rdf"`, and `"json-ld"` as format aliases in `export_to_rdf()`. Aliases resolve before format validation — zero public API changes.
+- Added `tests/export/test_rdf_exporter.py` (8 tests).
+
+### Incremental / Delta Processing
+
+**Native Delta Computation** (PR #349, by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1)
+
+- Native SPARQL-based diff between graph snapshots — only changed triples flow through the pipeline.
+- `delta_mode` configuration in `PipelineBuilder` for near-real-time workloads.
+- Version snapshot management with graph URI tracking and metadata storage.
+- `prune_versions()` for automatic snapshot retention cleanup.
+- Bug fixes: corrected SPARQL variable order, fixed class references, resolved duplicate dictionary keys.
+
+### Deduplication v2
+
+**Candidate Generation v2** (PR #338, by @ZohaibHassan16)
+
+- New opt-in strategies: `blocking_v2` and `hybrid_v2`, replacing O(N²) pair enumeration.
+- Multi-key blocking with normalised token prefixes, type-aware keys, and optional phonetic (Soundex) blocking.
+- 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, by @ZohaibHassan16)
+
+- 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 with prefilter enabled (`prefilter_enabled=False` by default).
+
+**Semantic Relationship Deduplication v2** (PR #340, by @ZohaibHassan16, fixes by @KaifAhmad1)
+
+- Canonicalisation engine with predicate synonym mapping (`works_for` → `employed_by`).
+- O(1) hash matching for exact canonical signatures.
+- Weighted scoring: 60% predicate + 40% object composition with explainable `semantic_match_score`.
+- **6.98x faster** than legacy mode (83ms vs 579ms).
+- `dedup_triplets()` infinite recursion bug fixed; function is now a first-class API in `methods.py`.
+
+**Deduplication v2 Migration Guide** (PR #344, by @ZohaibHassan16, fixes by @KaifAhmad1)
+
+- Comprehensive `MIGRATION_V2.md` documenting all v2 strategies with code examples.
+- Full backward compatibility maintained — legacy mode remains the default.
+
+### Export Formats
+
+**ArangoDB AQL Export** (PR #342, by @tibisabau)
+
+- 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, by @tibisabau)
+
+- Columnar storage format with configurable compression: snappy, gzip, brotli, zstd, lz4, none.
+- Explicit Apache Arrow schemas with type safety; field normalisation for varied naming conventions.
+- `export_parquet()` convenience function; `.parquet` auto-detection.
+- Analytics-ready for pandas, Spark, Snowflake, BigQuery, Databricks.
+- 25 tests, 100% pass rate.
+
+### Bug Fixes & Test Suite Stabilisation
+
+**Test Suite Fixes** (by @KaifAhmad1)
+
+Context module:
+- `retrieve_decision_precedents` — gated entity extraction on `use_hybrid_search=True` correctly.
+- `_extract_entities_from_query` — now uses `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`, and `multi_hop_context_assembly` for correct single-pass BFS.
+- Fixed `_retrieve_from_vector` fallback to `result["metadata"]["content"]` to prevent empty content and negative re-ranking scores.
+
+KG module:
+- `calculate_pagerank` — added `alpha`/`max_iter` aliases; return format changed to `{"centrality": scores, "rankings": sorted_list}`.
+- `community_detector._to_networkx` — now returns a NetworkX graph directly when one is passed (previously lost all edges).
+- Added 9 domain-specific tracking methods to `AlgorithmTrackerWithProvenance`.
+- Created `provenance_tracker.py` with `ProvenanceTracker` (`track_entity`, `get_all_sources`, `clear`).
+
+Pipeline module:
+- Retry loop fixed — now correctly iterates to `max_retries`.
+- `RecoveryAction` dataclass and `handle_failure(error, policy, retry_count)` added with LINEAR, EXPONENTIAL, and FIXED strategies.
+- `add_step()` fixed to return the created `PipelineStep`.
+- `validate` added as alias for `validate_pipeline` in `PipelineValidator`.
+
+Other:
+- Fixed `NameError` for missing `Type` import in `utils/helpers.py`.
+- Vector store performance threshold relaxed (100ms → 500ms per decision for development machines).
+- Windows cp1252 encoding fix in test files (emoji → ASCII).
+- `ProvenanceTracker` added to `semantica/kg/__init__.py` exports.
+
+**Results: ~840 tests passing, 36 skipped (external services), 0 failed**
+
+---
+
+## v0.3.0-alpha — Alpha (2026-02-19)
+
+### Context & Decision Intelligence
+
+**Context Engineering Enhancement** (PR #307, by @KaifAhmad1)
+
+The foundational 0.3.0 feature — complete overhaul of the context module for production-grade decision intelligence:
+
+- Full decision lifecycle: `record_decision()` → `add_decision()` → `add_causal_relationship()` → `trace_decision_chain()` → `analyze_decision_impact()` → `analyze_decision_influence()` → `find_similar_decisions()`
+- `AgentContext` unified wrapper with granular feature flags: `decision_tracking`, `kg_algorithms`, `graph_expansion`; methods: `store()`, `retrieve()`, `get_conversation_history()`, `get_statistics()`, `capture_cross_system_inputs()`
+- `AgentMemory` with working, conversation, and long-term memory tiers
+- `PolicyEngine` with versioned policy nodes, compliance checking (`check_decision_rules()`), and `PolicyException` model
+- Hybrid precedent search combining vector, structural, and category similarity with configurable weights
+- Decision influence analysis via centrality measures and causal chain tracking
+- GraphStore validation preventing runtime failures; secure logging
+- 9 critical bug fixes across logging, security, audit trails, API compatibility, Cypher queries, centrality access, validation
+
+**Context Decision Tracking Fixes** (PR #315, by @KaifAhmad1)
+
+- Fixed empty/None decision ID handling in `add_decision()`
+- Fixed None metadata handling preventing `TypeError`
+- Fixed causal chain depth logic and node exclusion
+- Fixed nonexistent node handling in `add_causal_relationship()`
+- Fixed precedent search direction in `find_precedents()`
+- Added missing `properties` field in `to_dict()`; added `from_dict()` method
+- Fixed UUID generation across all decision models
+- All 71 context tests passing
+
+### Knowledge Graph Algorithms
+
+**Improved Graph Algorithms** (PR #292, by @KaifAhmad1)
+
+- 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`
+- `GraphBuilderWithProvenance` and `AlgorithmTrackerWithProvenance` with full execution metadata
+
+**Improved Vector Store for Decision Tracking** (PR #293, by @KaifAhmad1)
+
+- `DecisionEmbeddingPipeline` with semantic and structural embeddings
+- `HybridSimilarityCalculator` with configurable weights (semantic: 0.7, structural: 0.3)
+- `ContextRetriever` with multi-hop reasoning
+- Convenience API: `quick_decision()`, `find_precedents()`, `explain()`, `similar_to()`, `batch_decisions()`, `filter_decisions()`
+- 34+ tests; performance: 0.028s per decision, 0.031s search, ~0.8KB memory per decision
+
+### Graph Database Backends
+
+**Apache AGE Backend Security Fixes** (PR #311, by @Sameer6305, fixes by @KaifAhmad1)
+
+- `AgeStore` class with `GraphStore` API compatibility (openCypher via SQL on PostgreSQL)
+- SQL injection vulnerabilities fixed with input validation
+- psycopg2-binary dependency and migration guide added
+- Fixed parameter replacement and test mock leakage
+
+**PgVector Store Support** (PR #303, by @Sameer6305, @KaifAhmad1)
+
+- Native PostgreSQL vector storage using the pgvector extension
+- Multiple distance metrics: cosine, L2/Euclidean, inner product
+- HNSW and IVFFlat indexing for approximate nearest neighbour search
+- JSONB metadata storage with flexible filtering; batch operations
+- Connection pooling with psycopg3/psycopg2 fallback
+- SQL injection protection via `psycopg_sql.SQL()`; idempotent index and table management
+- 36+ tests with Docker integration
+
+### Infrastructure
+
+**ResourceScheduler Deadlock Fix** (PR #299, #301, by @d4ndr4d3, @KaifAhmad1)
+
+- Replaced `threading.Lock()` with `threading.RLock()` to fix nested lock acquisition deadlock in `allocate_resources()`
+- Added `ValidationError` when no resources can be allocated
+- Progress tracking updates moved outside lock scope
+- 6 regression tests for deadlock prevention
+
+**Security Configuration** (by @KaifAhmad1)
+
+- Dependabot bi-weekly security updates with manual review
+- Automated security scans (Bandit, Safety, Semgrep) on schedule
+- Security-critical package grouping; zero auto-merge policy
+
+---
+
+## Summary by the Numbers
+
+| Metric | Value |
+|--------|-------|
+| Total tests passing | **886+** |
+| Test failures | **0** |
+| Context tests | 335 |
+| KG tests | ~430 |
+| Semantic extraction tests | 70 (9 skipped — external LLM APIs) |
+| Reasoning tests | 19 |
+| Real-world scenario tests | 85 |
+| PyPI classifier | Production/Stable |
+| Python support | 3.8 – 3.12 |
+
+---
+
+## Upgrade
+
+```bash
+pip install --upgrade semantica
+```
+
+No breaking changes. All new parameters have safe defaults and all new methods are additive.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full line-by-line diff.