chore: release v0.4.0

Bump version to 0.4.0, move [Unreleased] changelog entries to [0.4.0]
(2026-04-08), and remove duplicate changelog content appended in prior
merges. Release covers temporal data model, SHACL, SKOS, Knowledge
Explorer API, Agno integration, Named Graphs, Datalog Reasoner, and
many more features landed since 0.3.0.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.all-contributorsrc

@@ -1,17 +0,0 @@
-{
-  "projectName": "Semantica",
-  "projectOwner": "Hawksight-AI",
-  "repoType": "github",
-  "repoHost": "https://github.com",
-  "files": [
-    "CONTRIBUTORS.md"
-  ],
-  "imageSize": 100,
-  "commit": true,
-  "commitConvention": "conventional",
-  "contributors": [],
-  "contributorsPerLine": 7,
-  "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)",
-  "skipCi": true
-}
-

.github/FUNDING.yml

@@ -1,8 +1,3 @@
 # Funding options for Semantica
-# Uncomment and add your usernames/links below
-
-# github: [username]
-# patreon: username
-# ko_fi: username
-# custom: ["https://your-funding-page.com"]
+github: Hawksight-AI
 

.github/SUPPORT.md

@@ -7,7 +7,7 @@ Check the [docs folder](https://github.com/Hawksight-AI/semantica/tree/main/docs
 
 ### 💬 Community Support
 - **GitHub Discussions**: [Ask questions](https://github.com/Hawksight-AI/semantica/discussions)
-- **Discord**: Join our [Discord server](https://discord.gg/semantica) for real-time chat
+- **Discord**: Join our [Discord server](https://discord.gg/sV34vps5hH) for real-time chat
 
 ### 💭 Discussions
 Join the conversation on [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions):
@@ -32,6 +32,8 @@ For enterprise support, custom development, or consulting services:
 
 ## Sponsorship
 
+### Sponsor this project
+
 Support Semantica development:
 - [GitHub Sponsors](https://github.com/sponsors/Hawksight-AI)
 

.github/dependabot.yml

@@ -1,28 +1,130 @@
 version: 2
+
 updates:
-  # Python dependencies (pip/pyproject.toml)
+  # Core Python dependencies
   - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"  # Weekly for security
+      day: "monday"
+      time: "03:30"  # 3:30 AM UTC (9:00 AM IST)
+    open-pull-requests-limit: 10  # Higher limit for security updates
+    reviewers:
+      - "KaifAhmad1"
+    assignees:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "security"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "python"
+      - "security"
+    allow:
+      - dependency-type: "production"
+      - dependency-type: "development"
+    ignore:
+      # Only ignore major version updates for stability-critical packages
+      - dependency-name: "torch"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "transformers"
+        update-types: ["version-update:semver-major"]
+    # Group new feature dependencies
+    groups:
+      security-critical:
+        patterns:
+          - "cryptography"
+          - "requests"
+          - "urllib3"
+          - "certifi"
+          - "pyopenssl"
+        dependency-type: "production"
+      snowflake-features:
+        patterns:
+          - "snowflake-connector-python"
+          - "cryptography"
+      arrow-features:
+        patterns:
+          - "pyarrow"
+      benchmark-tools:
+        patterns:
+          - "pytest-benchmark"
+          - "pytest-cov"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
       day: "monday"
       time: "09:00"
-    open-pull-requests-limit: 0
-    ignore:
-      # Ignore all updates (no PRs will be created)
-      - dependency-name: "*"
-        update-types: ["version-update:semver-major", "version-update:semver-minor", "version-update:semver-patch"]
+    open-pull-requests-limit: 3
+    reviewers:
+      - "KaifAhmad1"
+    assignees:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "github-actions"
+      - "ci"
 
-  # GitHub Actions dependencies
-  - package-ecosystem: "github-actions"
+  # Optional dependencies (separate schedule for stability)
+  - package-ecosystem: "pip"
     directory: "/"
     schedule:
-      interval: "monthly"
-      day: "monday"
+      interval: "weekly"
+      day: "friday"
       time: "09:00"
-    open-pull-requests-limit: 0
-    ignore:
-      # Ignore all updates (no PRs will be created)
-      - dependency-name: "*"
-        update-types: ["version-update:semver-major", "version-update:semver-minor", "version-update:semver-patch"]
+    target-branch: "main"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "KaifAhmad1"
+    assignees:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "python"
+      - "optional"
+    allow:
+      - dependency-type: "production"
+
+  # Docker dependencies (if you use Docker)
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "wednesday"
+      time: "09:00"
+    open-pull-requests-limit: 2
+    reviewers:
+      - "KaifAhmad1"
+    assignees:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "docker"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "docker"
+
+  # Documentation dependencies
+  - package-ecosystem: "pip"
+    directory: "docs"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 2
+    reviewers:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "docs"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "documentation"
 

.github/workflows/benchmark.yml

@@ -0,0 +1,58 @@
+name: Semantica Performance Suite
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '**/*.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  performance-test:
+    name: Benchmark Runner (Ubuntu/Python 3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install Dependencies
+        env:
+
+          BENCHMARK_REAL_LIBS: "1"
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install -r benchmarks/requirements.txt
+          python -m spacy download en_core_web_sm
+          pip install rdflib neo4j faiss-cpu torch pyarrow pdfplumber python-pptx openpyxl lxml python-docx beautifulsoup4 chardet langdetect
+
+      - name: Execute Benchmarks (Real Mode)
+        env:
+          BENCHMARK_REAL_LIBS: "1"
+        run: |
+          python benchmarks/benchmarks_runner.py
+          # Optional: Compare to baseline (requires previous run artifact)
+          # pytest-benchmark --storage file://benchmarks/results --benchmark-compare
+
+      - name: Upload Benchmark Results
+        uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: benchmark-report-${{ github.run_id }}
+          path: benchmarks/results
+          retention-days: 30

.github/workflows/ci.yml

@@ -3,8 +3,18 @@ name: CI
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '**/*.md'
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '**/*.md'
 
 jobs:
   build:

.github/workflows/codeql.yml

@@ -0,0 +1,86 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '30 1 * * 1'  # Every Monday 7 AM IST
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"
+          upload: false
+        id: codeql
+
+      - name: Upload SARIF (Advanced Setup only)
+        # Uploads results only when Default Setup is not active.
+        # If Default Setup is still enabled, this step skips gracefully
+        # instead of failing the workflow with HTTP 409.
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: ${{ steps.codeql.outputs.sarif-output }}
+          category: "/language:python"
+          wait-for-processing: true
+        continue-on-error: true
+
+  dismiss-fixed-alerts:
+    name: Dismiss Fixed Security Alerts
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - name: Dismiss resolved CodeQL alerts via API
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          FIXED_PATTERNS=(
+            "py/clear-text-logging-sensitive-data"
+            "py/incomplete-url-substring-sanitization"
+            "actions/missing-workflow-permissions"
+          )
+
+          # Fetch all open code scanning alerts
+          ALERTS=$(gh api repos/$REPO/code-scanning/alerts \
+            --jq '.[] | {number: .number, rule: .rule.id, state: .state}' \
+            -X GET -f state=open -f per_page=100)
+
+          for PATTERN in "${FIXED_PATTERNS[@]}"; do
+            ALERT_NUMS=$(echo "$ALERTS" | jq -r \
+              "select(.rule == \"$PATTERN\") | .number")
+            for NUM in $ALERT_NUMS; do
+              echo "Dismissing alert #$NUM ($PATTERN) — fixed in security-enhancement PR"
+              gh api repos/$REPO/code-scanning/alerts/$NUM \
+                -X PATCH \
+                -f state=dismissed \
+                -f dismissed_reason="won't fix" \
+                -f dismissed_comment="Fixed in PR security-enhancement: code changes remove the vulnerability. Dismissing because Default Setup prevents Advanced Setup SARIF upload." \
+                && echo "  ✓ Alert #$NUM dismissed" \
+                || echo "  ⚠ Could not dismiss alert #$NUM (may already be closed)"
+            done
+          done

.github/workflows/docs.yml

@@ -8,11 +8,12 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
-      - 'semantica/**'
       - 'mkdocs.yml'
       - 'requirements-docs.txt'
       - 'CHANGELOG.md'
       - 'RELEASE.md'
+  release:
+    types: [published]
   workflow_dispatch:
 
 # Permissions needed to deploy to GitHub Pages
@@ -58,7 +59,7 @@ jobs:
         continue-on-error: true
 
       - name: Setup Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v6
         continue-on-error: true
 
       - name: Upload artifact
@@ -76,4 +77,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/security-scan.yml

@@ -0,0 +1,185 @@
+name: Security Scan
+
+on:
+  schedule:
+    - cron: '30 1 * * 1,4'  # Mon/Thu 7 AM IST
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '**/*.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '**/*.md'
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+        
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install safety bandit semgrep jq
+        
+      - name: Run Safety Check (Package Vulnerabilities)
+        run: |
+          safety check --json --output safety-report.json || true
+          echo "Checking for package vulnerabilities..."
+          
+          # Count vulnerabilities safely
+          VULNS=$(safety check --json --output /dev/stdout 2>/dev/null | jq '.vulnerabilities | length' 2>/dev/null || echo "0")
+          
+          if [ "$VULNS" -gt 0 ]; then
+            echo "❌ Security vulnerabilities found: $VULNS"
+            echo "CI will fail to prevent merging of vulnerable dependencies"
+            echo ""
+            echo "Vulnerability details:"
+            safety check || true
+            exit 1
+          else
+            echo "✅ No security vulnerabilities found"
+          fi
+        
+      - name: Run Bandit (Code Security Linter)
+        run: |
+          bandit -r semantica/ -f json -o bandit-report.json || true
+          echo "Checking for HIGH severity security issues..."
+          
+          # Count HIGH severity issues
+          HIGH_ISSUES=$(bandit -r semantica/ -f json -ll 2>/dev/null | jq -r '.results[]? | select(.issue_severity == "HIGH") | .test_name' 2>/dev/null | wc -l || echo "0")
+          
+          if [ "$HIGH_ISSUES" -gt 0 ]; then
+            echo "❌ HIGH severity security issues found: $HIGH_ISSUES"
+            echo "CI will fail to prevent merging of high-risk code"
+            echo ""
+            echo "High severity issues:"
+            bandit -r semantica/ -ll | grep "Severity: High" -A 5 -B 1 || true
+            exit 1
+          else
+            echo "✅ No HIGH severity security issues found"
+          fi
+        
+      - name: Run Semgrep (Static Analysis)
+        run: |
+          echo "Running Semgrep static analysis..."
+          semgrep --config=auto --json --output=semgrep-report.json semantica/ || true
+          
+          # Run security-focused rules
+          echo "Checking for security patterns..."
+          SECURITY_ISSUES=$(semgrep --config=p/security --json semantica/ 2>/dev/null | jq '.results | length' 2>/dev/null || echo "0")
+          
+          if [ "$SECURITY_ISSUES" -gt 0 ]; then
+            echo "⚠️ Security patterns found: $SECURITY_ISSUES"
+            echo "Review these findings for potential improvements"
+            semgrep --config=p/security semantica/ || true
+          else
+            echo "✅ No security patterns found"
+          fi
+        
+      - name: Upload Security Reports
+        uses: actions/upload-artifact@v7
+        with:
+          name: security-reports
+          path: |
+            safety-report.json
+            bandit-report.json
+            semgrep-report.json
+        
+      - name: Comment PR with Security Results
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('fs');
+            
+            // Read safety report
+            let safetyResults = '';
+            try {
+              const safetyData = JSON.parse(fs.readFileSync('safety-report.json', 'utf8'));
+              if (safetyData.vulnerabilities && safetyData.vulnerabilities.length > 0) {
+                safetyResults = `## Safety Vulnerabilities Found\\n`;
+                safetyData.vulnerabilities.forEach(vuln => {
+                  safetyResults += `- **${vuln.package}**: ${vuln.advisory}\\n`;
+                });
+              } else {
+                safetyResults = '## No Safety Vulnerabilities Found\\n';
+              }
+            } catch (e) {
+              safetyResults = '## Safety scan completed\\n';
+            }
+            
+            // Read bandit report
+            let banditResults = '';
+            try {
+              const banditData = JSON.parse(fs.readFileSync('bandit-report.json', 'utf8'));
+              if (banditData.results && banditData.results.length > 0) {
+                const highIssues = banditData.results.filter(issue => issue.issue_severity === 'HIGH');
+                if (highIssues.length > 0) {
+                  banditResults = `## High Severity Security Issues Found\\n`;
+                  highIssues.forEach(issue => {
+                    banditResults += `- **${issue.test_name}**: ${issue.filename}:${issue.line_number}\\n`;
+                  });
+                } else {
+                  banditResults = '## No High Severity Security Issues Found\\n';
+                }
+              } else {
+                banditResults = '## No Bandit Issues Found\\n';
+              }
+            } catch (e) {
+              banditResults = '## Bandit scan completed\\n';
+            }
+            
+            // Read semgrep report
+            let semgrepResults = '';
+            try {
+              const semgrepData = JSON.parse(fs.readFileSync('semgrep-report.json', 'utf8'));
+              if (semgrepData.results && semgrepData.results.length > 0) {
+                semgrepResults = `## Security Patterns Found\\n`;
+                semgrepData.results.slice(0, 10).forEach(issue => {
+                  semgrepResults += `- **${issue.rule_id}**: ${issue.path}\\n`;
+                });
+                if (semgrepData.results.length > 10) {
+                  semgrepResults += `- ... and ${semgrepData.results.length - 10} more\\n`;
+                }
+              } else {
+                semgrepResults = '## No Security Patterns Found\\n';
+              }
+            } catch (e) {
+              semgrepResults = '## Semgrep scan completed\\n';
+            }
+            
+            // Create summary comment
+            const comment = `# 🔒 Security Scan Results\\n\\n${safetyResults}\\n\\n${banditResults}\\n\\n${semgrepResults}\\n\\n---\\n\\n*This security scan runs automatically on source-code PRs and bi-weekly (skipped for doc/markdown-only changes).*\\n\\n📊 **Security Policy**: CI fails on vulnerabilities and HIGH severity issues.`;
+            
+            // Post comment with error handling
+            try {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: comment
+              });
+              console.log('✅ Security comment posted successfully');
+            } catch (error) {
+              console.log('⚠️ Could not post security comment:', error.message);
+              console.log('📋 Security scan results saved to artifacts');
+            }

.github/workflows/security.yml

@@ -5,6 +5,9 @@ on:
     - cron: '0 0 * * 1'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   audit:
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        exclude: 'neptune-setup\.yaml$'
       - id: check-json
       - id: check-toml
       - id: check-added-large-files
@@ -49,9 +50,15 @@ repos:
     hooks:
       - id: yamllint
         args: ['-d', '{extends: default, rules: {line-length: {max: 120}}}']
+        exclude: 'neptune-setup\.yaml$'
+
+  - repo: https://github.com/aws-cloudformation/cfn-lint
+    rev: v1.43.3
+    hooks:
+      - id: cfn-lint
+        files: 'neptune-setup\.yaml$'
 
   # Removed slow hooks for faster development:
   # - mypy: Type checking (can be run manually or in CI)
   # - bandit: Security scanning (can be run separately)
   # - pytest: Testing (should be run manually, not on every commit)
-

CHANGELOG.md

@@ -7,6 +7,891 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-08
+
+- **Named Graph Support: Review Follow-up Fixes** (PR #432 by @Sameer6305, follow-up patch by @KaifAhmad1):
+  - Fixed `enable_named_graphs` handling so `TripletStore.execute_query()` now forwards `supports_named_graphs=False` when named-graph support is disabled in config.
+  - Fixed duplicate dataset clause behavior in `QueryEngine.prepare_query()` so the same URI is not emitted as both `FROM <...>` and `FROM NAMED <...>`.
+  - Added backward-compatible config alias support for `default_graph_uri` alongside existing `default_graph`.
+  - Hardened graph URI handling in version-pruning `DROP SILENT GRAPH` updates by percent-encoding unsafe characters before SPARQL interpolation.
+  - Added focused regression tests covering config-flag enforcement, duplicate clause prevention, `default_graph_uri` alias behavior, and pruning-path URI sanitization.
+  - Verified with targeted feature tests: `tests/triplet_store/test_triplet_store.py` and `tests/change_management/test_managers.py` (54 passed).
+
+- **ContextGraph Pagination & Edge Integrity Fixes** (PR #431 by @ZohaibHassan16, reviewed and patched by @KaifAhmad1):
+  - **O(N) pagination bug** (`semantica/context/context_graph.py`): `find_nodes` and `find_edges` previously materialised the entire graph into a list before slicing — on a 50k-node / 100k-edge graph this allocated up to 2.5 million dicts per paginated request, starving the asyncio event loop and producing 502 Bad Gateway timeouts from the Vite proxy. Both methods now use generator expressions consumed via `itertools.islice(gen, skip, skip + limit)`, reducing time and space complexity from O(N) to O(limit) for the hot path.
+  - **Ghost-node / "Nothing → Nothing" edge bug**: `add_edges` previously only accepted the `"source_id"` / `"target_id"` key names; edges serialised with `"source"` / `"target"` (the format emitted by `find_edges`) silently produced `None → None` edges that crashed the frontend physics engine. `add_edges` now accepts both naming conventions (`edge.get("source_id") or edge.get("source")`). A `continue` guard rejects any edge still missing either endpoint after the dual-key lookup.
+  - **Deterministic pagination**: `find_nodes` and `find_active_nodes` now call `sorted()` on `node_type_index` sets before iterating, eliminating non-deterministic page boundaries caused by Python's unordered set iteration.
+  - **`sorted()` TypeError** (review fix by @KaifAhmad1): the `sorted()` call filtered to `isinstance(nid, str)` entries only — previously a `None` or `int` node ID in the index caused an immediate `TypeError` crash on any type-filtered node query.
+  - **`stats()` / pagination total mismatch** (review fix by @KaifAhmad1): `stats()` previously counted all entries in `self.nodes` and `self.edges` including structurally invalid ones that `find_nodes`/`find_edges` now silently skip. `stats()` applies the same validity filters (`n.node_id`, `e.source_id and e.target_id`) so that `node_count`, `edge_count`, `node_types`, and `edge_types` totals always match what the pagination methods can actually return — preventing the Explorer UI from computing phantom extra pages.
+  - All 424 context tests pass, 0 regressions.
+
+- **Security: CodeQL Alert Remediation** (PR by @KaifAhmad1, branch `security-enhancement`):
+  - **Clear-text logging of sensitive information** (#6, #7 — CWE-312/359/532): Removed debug `print` blocks in `semantica/semantic_extract/relation_extractor.py` and `semantica/semantic_extract/triplet_extractor.py` that accessed and logged `method_options["api_key"]` (even partially masked). No sensitive data is now written to stdout in verbose mode.
+  - **Incomplete URL substring sanitization** (#8 — CWE-20): Replaced `"http://a.com" in urls` in `tests/ingest/test_web_ingestor.py` with `any(url == "http://a.com" for url in urls)` — explicit exact equality per element, eliminating the ambiguous substring check that could match attacker-controlled URLs at arbitrary positions.
+  - **Missing workflow permissions** (#1, #3 — least-privilege): Added `permissions: contents: read` at the workflow level in `.github/workflows/benchmark.yml` and `.github/workflows/security.yml`. Both workflows previously inherited repository-default permissions (potentially read-write); they only require read access to checkout code.
+
+- **SKOS Vocabulary REST API & Hierarchy Engine** (PR #426 by @ZohaibHassan16):
+  - Added `semantica/explorer/routes/vocabulary.py` with three endpoints: `GET /api/vocabulary/schemes` returns all `skos:ConceptScheme` nodes as `VocabularyScheme` dicts; `GET /api/vocabulary/hierarchy?scheme=<uri>` returns the full broader/narrower concept tree for a scheme using an O(V+E) in-memory adjacency-list algorithm with cycle detection via a visited set; `POST /api/vocabulary/import` accepts `.ttl`, `.rdf`, and `.owl` uploads, delegates parsing to `rdf_parser.parse_skos_file`, and ingests results into the active `GraphSession` via `add_nodes`/`add_edges`. Invalid files return HTTP 422.
+  - Added `VocabularyScheme` and `ConceptNode` Pydantic models to `semantica/explorer/schemas.py`. `ConceptNode` is self-referential (`children: Optional[List['ConceptNode']]`) to support arbitrarily deep hierarchy trees.
+  - All session calls offloaded via `asyncio.to_thread` to keep the event loop unblocked.
+  - Added `tests/explorer/test_vocabulary.py` — 16 tests covering all three endpoints: scheme listing, metadata envelope fallback, empty graph, `broader`/`narrower`/`topConceptOf`/`hasTopConcept` edge directions, flat schemes, missing query params, cyclic edge safety, `.rdf`/`.owl` format paths, and invalid file 422 response. 99 total explorer tests passing, 0 regressions.
+  - Depends on `semantica/explorer/utils/rdf_parser.py` introduced in PR #425.
+- **Explorer Server Integration & RDF Parsing Utility** (PR #425 by @ZohaibHassan16):
+  - Added `semantica/explorer/utils/rdf_parser.py` — dedicated SKOS/RDF parsing utility using `rdflib`. Exposes `parse_skos_file(file_bytes, rdf_format)` which parses `.ttl` (Turtle) and `.rdf` (RDF/XML) files and returns a `(nodes, edges)` tuple of flat dicts compatible with `ContextGraph` ingestion. Extracts `skos:ConceptScheme` and `skos:Concept` nodes with a 3-priority label resolution strategy (exact `en` → `en-*` variants → untagged → any-language fallback → URI fragment). Collects all `skos:altLabel` values as a deduplicated list. Emits edges for all 6 SKOS structural predicates: `broader`, `narrower`, `inScheme`, `related`, `topConceptOf`, `hasTopConcept`. Edges pointing to external URIs not declared in the same file are silently dropped to avoid dangling references in the graph. Raises `ValueError` with a descriptive message on unparseable input.
+  - Added `semantica/explorer/utils/__init__.py` — package initialiser for the new `utils` sub-package.
+  - Updated `semantica/server.py` — mounts all Explorer API routers (`analytics`, `annotations`, `decisions`, `enrich`, `export_import`, `graph`, `temporal`) inside a graceful `try/except ImportError` block. The `vocabulary` router (pending #421) is guarded in its own isolated block so a missing module cannot prevent the existing routes from mounting. Both blocks log at `INFO`/`DEBUG` level rather than raising on absence.
+  - Added `tests/explorer/test_rdf_parser.py` — 32 tests across 9 classes covering node/edge extraction, label priority, `altLabel` deduplication, all 6 SKOS edge types, orphan-edge filtering, empty graph, error cases, and RDF/XML format. 32 passed, 0 failures, 0 regressions against `tests/explorer/test_explorer_api.py` (51 tests).
+  - Provides the necessary infrastructure for the upcoming `POST /api/vocabulary/import` endpoint tracked in #421.
+
+- **SKOS Vocabulary Module** (PR #319 by @KaifAhmad1):
+  - **Namespace helpers** (`semantica/ontology/namespace_manager.py`): Added `get_skos_uri(local_name)` — returns the full `http://www.w3.org/2004/02/skos/core#<local_name>` URI for any SKOS term. Added `build_concept_scheme_uri(name)` — slugifies a human-readable vocabulary name (spaces/special chars → hyphens, lower-cased) and anchors the result at the configured base URI as `<base>/vocab/<slug>`.
+  - **Triplet-store SKOS helpers** (`semantica/triplet_store/triplet_store.py`): Added `add_skos_concept(concept_uri, scheme_uri, pref_label, alt_labels, broader, narrower, related, definition, notation)` — assembles and stores all required SKOS triples (auto-declares the `skos:ConceptScheme`, asserts `rdf:type skos:Concept`, `skos:inScheme`, `skos:prefLabel`, and all optional predicates) via the existing `add_triplets()` API; no new storage paths introduced. Added `get_skos_concepts(scheme_uri=None)` — issues a SPARQL `SELECT` via `execute_query()` and collapses multi-valued `altLabel`/`broader`/`narrower`/`related` bindings into structured concept dicts; optional `scheme_uri` restricts results to one vocabulary.
+  - **OntologyEngine vocabulary APIs** (`semantica/ontology/engine.py`): Added three public methods that delegate to `QueryEngine` via `self.store.execute_query()` — `list_vocabularies()` returns all `skos:ConceptScheme` instances with labels; `list_concepts(scheme_uri)` returns every `skos:Concept` in a scheme with `pref_label` and `alt_labels`; `search_concepts(query, scheme_uri=None)` performs case-insensitive substring matching across `skos:prefLabel` and `skos:altLabel` with optional scheme scoping.
+  - **Security**: `search_concepts` sanitises user input (escapes `\`, `"`, newlines) before embedding it in the SPARQL string literal. All URI interpolation uses the existing `_sanitize_uri` helper.
+  - **Tests**: Added `TestSKOSOntologyEngine` (14 tests) to `tests/ontology/test_ontology_comprehensive.py` and `TestSKOSTripletStore` (6 tests) to `tests/triplet_store/test_triplet_store.py`. Coverage: URI helpers, vocabulary listing + deduplication, concept listing with multi-value alt-label collapse, search with/without scheme filter, injection sanitisation, empty results, and no-store error paths. 20 new tests, 0 failures, 1162 total passing, 0 regressions.
+  - **Docs** (`docs/reference/ontology.md`): Added "SKOS Vocabulary Management" section with SKOS data-model reference table, `add_skos_concept` usage example, bulk import via rdflib + `add_triplets`, `list_vocabularies` / `list_concepts` / `search_concepts` usage examples, and `NamespaceManager` URI helper examples.
+  - No new top-level Python package created; all code extends existing `semantica/ontology/` and `semantica/triplet_store/` packages. Fully opt-in and non-breaking.
+
+- **SHACL Shape Generation & Validation** (PR #318 by @KaifAhmad1):
+  - **Phase 1 — Generation**: Added `SHACLGenerator` to `semantica/ontology/ontology_generator.py` — 6-stage internal pipeline: `_build_class_index` → `_generate_node_shapes` → `_attach_property_shapes` → `_propagate_inheritance` → `_apply_quality_tier` → `serialize`. Derives SHACL node and property shapes from any Semantica ontology dict; zero hand-authoring. Three output formats: Turtle, JSON-LD, N-Triples. Three quality tiers: `"basic"` (structure + cardinality), `"standard"` (+ `sh:in`, `sh:pattern`, inheritance; default), `"strict"` (+ `sh:closed true` + `sh:ignoredProperties` on all non-empty shapes). Iterative inheritance propagation up to 3+ levels, cycle-safe (max 20 passes), no duplicate property shapes per shape. No-domain properties attach to all node shapes. Added `PropertyShape`, `NodeShape`, `SHACLGraph` dataclasses.
+  - **Phase 1 — Engine API**: Added `OntologyEngine.to_shacl(ontology, *, format, base_uri, shapes_uri, include_inherited, severity, quality_tier, validate_output)` and `OntologyEngine.export_shacl(ontology, path, format, encoding)` to `semantica/ontology/engine.py`. Added `RDFExporter.export_shacl(shacl_string, file_path, format, encoding)` to `semantica/export/rdf_exporter.py` with extension validation (`.ttl`, `.jsonld`, `.nt`, `.shacl`).
+  - **Phase 2 — Runtime Validation**: Added `SHACLViolation` (8 fields: `focus_node`, `result_path`, `constraint`, `severity`, `message`, `value`, `shape`, `explanation`; `to_dict()`) and `SHACLValidationReport` (`conforms`, `violations`, `warnings`, `infos`, `raw_report`; `violation_count`/`warning_count` properties; `summary()`, `explain_violations()`, `to_dict()`) to `semantica/ontology/ontology_validator.py`. Added `_run_pyshacl(data_graph_str, shacl_str, data_graph_format, shacl_format)` — thin wrapper around `pyshacl.validate()` returning typed `SHACLValidationReport`. `pyshacl` and `rdflib` are optional deferred imports (`pip install semantica[shacl]`); `ImportError` with install hint raised if absent. Added `OntologyEngine.validate_graph(data_graph, shacl=None, *, ontology=None, data_graph_format, shacl_format, explain, abort_on_first)` — exactly one of `shacl`/`ontology` must be provided (`ValueError` otherwise); `explain=True` populates plain-English explanations via rule-based templates for all 7 SHACL constraint types (`MinCount`, `MaxCount`, `Datatype`, `Class`, `In`, `Pattern`, `Closed`).
+  - **Exports**: `SHACLGenerator`, `SHACLGraph`, `NodeShape`, `PropertyShape`, `SHACLValidationReport`, `SHACLViolation` added to `semantica/ontology/__init__.py`.
+  - **Security & reliability fixes**:
+    - **High** (`engine.py`): Replaced path-vs-content heuristic (`len < 500 and "\n" not in s`) with `os.path.exists()` — prevents attacker-controlled SHACL strings from being silently interpreted as file paths.
+    - **High** (`ontology_generator.py`): `_propagate_inheritance` now uses `dataclasses.replace(pps)` instead of appending parent `PropertyShape` objects by reference — mutations on a child's inherited property no longer silently affect the parent.
+    - **Medium** (`engine.py` / `ontology_validator.py`): Added `shacl_format` parameter to `validate_graph` and `_run_pyshacl`; full format alias map (`"ttl"→"turtle"`, `"jsonld"→"json-ld"`, `"ntriples"→"nt"`) in both `to_shacl` validate-output and `_run_pyshacl` — JSON-LD and N-Triples shapes no longer fail parsing.
+    - **Medium** (`ontology_generator.py`): `sh:ignoredProperties` now emits full URI `<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>` instead of prefixed `rdf:type` — eliminates prefix-dependency in strict-tier Turtle output.
+    - **Low** (`ontology_generator.py`): `_prefix_decls` now iterates `sorted(graph.prefixes.items())` — deterministic Turtle output for reproducible CI `git diff` checks.
+  - **Tests**: Added `TestSHACLGeneration` (16 tests) to `tests/ontology/test_ontology_comprehensive.py` and `TestSHACLHierarchicalAndValidation` (18 tests) to `tests/ontology/test_ontology_advanced.py`. 34 new tests, 0 failures, 1111 total passing, 0 regressions.
+  - **README**: Added `## Unreleased / Coming Next` section, SHACL bullet points under Features → Ontology and Export Formats, updated Modules table, full Phase 1 + Phase 2 code examples under `## Ontology`, `pip install semantica[shacl]` under Installation.
+
+- **Temporal GraphRAG Integration** (PR #402 by @KaifAhmad1):
+  - Added `TemporalGraphRetriever` to `semantica/context/context_retriever.py` — drop-in wrapper for any `ContextRetriever`; calls `base_retriever.retrieve(query)` then filters `related_entities`/`related_relationships` via `reconstruct_at_time()`; `at_time=None` is a true passthrough; returns new `RetrievedContext` objects via `dataclasses.replace()` (no in-place mutation); temporal modules guarded with `try/except` at import time.
+  - Extended `ContextRetriever._generate_reasoned_response()` and `query_with_reasoning()` with `at_time` and `header_template` parameters — when `at_time` is set a structured temporal header (`[Graph context valid as of: … UTC | Source: KnowledgeGraph snapshot]`) is prepended to the LLM context block; omitted when `at_time=None` (prompt byte-identical to previous behaviour); naive datetimes normalised to UTC; header built via `str.replace` not `.format` (format-string injection guard).
+  - Added `TemporalQueryRewriter` and `TemporalQueryResult` in `semantica/kg/temporal_query_rewriter.py` — extracts `temporal_intent` (`"before"`, `"after"`, `"at"`, `"during"`, `"between"`, `None`), `at_time`, `start_time`, `end_time`, and `rewritten_query` from natural-language queries; regex-only by default (zero LLM calls), optional LLM-assisted mode; datetime resolution always delegated to `TemporalNormalizer`; word-boundary guards prevent false matches (`at` inside `that`); year fallback handles noun-phrase dates like `"the 2021 merger"`; never calls `reconstruct_at_time`.
+  - Exported `TemporalGraphRetriever` from `semantica.context`; exported `TemporalQueryRewriter`, `TemporalQueryResult` from `semantica.kg`.
+  - **Security fixes**: format-string injection in header template (medium); unconditional temporal module import at package init (low).
+  - **Bug fixes**: in-place mutation of `RetrievedContext` (high); naive datetime formatted without timezone (low); missing `timezone` import causing `NameError` (low).
+  - Added 99 tests across `tests/context/test_temporal_retriever.py` (56) and `tests/kg/test_temporal_query_rewriter.py` (43); 0 failures, 0 regressions.
+
+- **Temporal Provenance & Export** (PR #401 by @KaifAhmad1):
+  - **Transaction time on provenance records** (`semantica/kg/provenance_tracker.py`): `track_entity()` now automatically attaches `recorded_at = datetime.now(UTC).isoformat()` to every new record — no opt-in required. Existing records without `recorded_at` continue to work in all existing query methods (treated as unknown, not an error). Added `query_recorded_between(start, end) -> list` returning all provenance records whose `recorded_at` falls within the inclusive range; accepts `datetime` objects or ISO strings including trailing `Z`.
+  - **Fact revision audit trail** (`semantica/kg/provenance_tracker.py`): Added `revision_history(fact_id) -> list` returning the complete revision chain ordered by `recorded_at` ascending; each entry includes `version` (int, 1-based), `valid_from`, `valid_until`, `recorded_at`, `author`, and optionally `revision_type`/`supersedes`; returns `[]` for unknown facts (never raises). Added `export_audit_log(fact_ids, format) -> str` supporting `"json"` (pretty-printed) and `"csv"` (with header row) formats.
+  - **OWL-Time RDF export** (`semantica/export/rdf_exporter.py`): `export_to_rdf()` gains `include_temporal: bool = False` and `time_axis: str = "valid"` parameters. When `include_temporal=True`, emits OWL-Time triples (`http://www.w3.org/2006/time#`) for every relationship carrying `valid_from`/`valid_until` — a `time:Interval` node linked via `time:hasTime`, `time:hasBeginning`/`time:hasEnd` with `time:Instant` nodes, and `time:inXSDDateTimeStamp` values. `time_axis` controls which axis is exported: `"valid"`, `"transaction"`, or `"both"`. Relationships without temporal metadata are unaffected. Default `include_temporal=False` produces output identical to current behavior. **Design decision for `TemporalBound.OPEN`**: OWL-Time has no standard predicate for "no known end date" — `time:hasEnd` is omitted and `semantica:openEndedInterval "true"^^xsd:boolean` is emitted on the interval node instead. Output parses without errors in rdflib.
+  - **Stable snapshot serialization format** (`semantica/kg/temporal_query.py`, new `semantica/kg/schemas/temporal_snapshot_v1.json`): `create_snapshot()` now stamps `"format_version": "1.0"` on every snapshot. Added `validate_snapshot(snapshot) -> bool` — validates required fields (`format_version`, `label`, `timestamp`, `author`, `description`, `entities`, `relationships`, `checksum`); returns `False` with structured DEBUG-level error details on failure, never raises. Added `migrate_snapshot(snapshot) -> dict` — deep-copies and upgrades old-format snapshots to v1.0, populating missing required fields with `None`; already-v1.0 snapshots returned unchanged with no data loss. New `semantica/kg/schemas/temporal_snapshot_v1.json` — JSON Schema (draft 2020-12) defining required and optional fields, types, and constraints.
+  - Added 28 new tests in `tests/test_401_temporal_provenance_export.py` covering every acceptance criterion; 451 related tests pass, 0 regressions.
+
+- **Temporal Metadata Extraction from Text** (PR #400 by @KaifAhmad1):
+  - Added `extract_temporal_bounds: bool = False` parameter to `extract_relations_llm()`. When `True`, the LLM prompt is extended with a calibrated confidence scale and four few-shot examples; each returned `Relation` gains `valid_from`, `valid_until`, `temporal_confidence` (0.0–1.0), and `temporal_source_text` in its `metadata` dict. Default `False` preserves 100% backward compatibility.
+  - Confidence scale anchors baked into the prompt: `1.00` = full ISO date, `0.90` = year+month, `0.85` = year only, `0.75` = quarter, `0.65` = named season/approximate range, `0.50` = vague relative with computable anchor, `0.35` = highly vague, `0.00` = no temporal signal. LLMs self-report certainty rather than clustering near 1.0.
+  - Low temporal confidence (< 0.5) with a non-null date logs a `WARNING`; signal is never suppressed — callers decide how to filter.
+  - Cache key now includes the `extract_temporal_bounds` flag to prevent cross-mode cache pollution.
+  - Flag propagated through `_extract_relations_chunked()` so long-text chunked extraction also carries temporal metadata.
+  - Added `RelationWithTemporalOut` and `RelationsWithTemporalResponse` Pydantic schemas in `semantica/semantic_extract/schemas.py`. A separate schema is required because `RelationOut` uses `extra="ignore"`, which silently drops any undeclared field including the four temporal fields.
+  - New `semantica/kg/temporal_normalizer.py` — `TemporalNormalizer` class (zero LLM calls, pure regex + `dateutil` arithmetic):
+    - `normalize(value)` → `(valid_from, valid_until)` UTC `datetime` tuple or `None`. Resolution order: ISO 8601 full parse → partial-date regex (year-only, month+year, YYYY-MM, Q[1-4] YYYY) → ambiguous-slash-date detection → domain phrase map → relative phrase resolution via `relativedelta`.
+    - `normalize_phrase(phrase)` → metadata dict `{"maps_to": ..., "type": ..., "domain": [...]}` or `None` — exact match then regex-pattern keys.
+    - Ambiguous `DD/MM/YYYY`-style inputs issue `TemporalAmbiguityWarning` and return `None` — never silently guesses locale.
+    - Unparseable inputs return `None` with a debug log — never raise.
+    - Relative phrases (`"last year"`, `"three months ago"`, etc.) raise `ValueError` if `reference_date` is `None` rather than guessing.
+    - Default phrase map covers 13 domains: General/Policy (`effective date`, `effective from/as of/beginning`, `in force until`, `retroactive to`, `sunset clause`), Healthcare (`approval date`, `expiry date`, `market authorization`), Cybersecurity (`incident window`, `campaign period`), Supply Chain (`certification valid through`), Finance (`trading halt`), Energy (`commissioned date`, `decommissioned date`).
+    - User-supplied `phrase_map` is merged over defaults at construction (`{**defaults, **user_map}`) — custom entries win without forking the library.
+  - Added `TemporalAmbiguityWarning(UserWarning)` to `semantica/utils/exceptions.py`.
+  - Exported `TemporalNormalizer` from `semantica/kg/__init__.py`.
+  - Added 53 new tests in `tests/semantic_extract/test_temporal_extraction.py`; zero real LLM calls, suite runs in ~3.5 s. All 873 existing tests continue to pass.
+
+- **Fix: OllamaProvider ignores `base_url`** (PR #408 by @AlexeyMyslin, fixed by @KaifAhmad1):
+  - `OllamaProvider._init_client()` was assigning the raw `ollama` module to `self.client` instead of instantiating `ollama.Client(host=self.base_url)`, causing all requests to silently hit `localhost:11434` regardless of the `base_url` passed by the user
+  - Fixed by replacing `self.client = ollama` with `self.client = ollama.Client(host=self.base_url)` — remote Ollama servers (e.g. `http://192.168.1.3:11434`) are now reachable
+  - Added 3 regression tests: default URL forwarded as host, custom URL forwarded as host, and guard ensuring `self.client` is never the raw module
+
+- **Temporal Awareness in Context Graph** (PR #399 by @KaifAhmad1):
+  - Added `valid_from` and `valid_until` fields to the `Decision` dataclass and `record_decision()` — decisions now carry explicit validity windows; superseded decisions remain in the graph (history is immutable)
+  - Added `include_superseded=False` and `as_of=None` parameters to `find_precedents_by_scenario()` — defaults exclude expired decisions; `as_of` enables point-in-time precedent queries
+  - Added `ContextGraph.state_at(timestamp)` — returns a serializable point-in-time snapshot of all nodes, edges, and decisions whose validity windows include `timestamp`; source graph is never mutated
+  - Stamped `recorded_at` on causal relationship edges created via `add_causal_relationship()` — enables transaction-time filtering
+  - Added `CausalChainAnalyzer.trace_at_time(event_id, at_time)` — reconstructs a causal chain using only edges recorded up to `at_time` (transaction time); returns an empty list when `at_time` predates all facts, never raises
+  - Added `AgentContext.checkpoint(label)`, `diff_checkpoints(label1, label2)`, and `flush_checkpoint(label)` — named in-memory context snapshots with structured diffs (`decisions_added`, `decisions_removed`, `relationships_added`, `relationships_removed`) and optional persistence via `TemporalVersionManager`
+  - **Review fixes applied in the same PR**:
+    - Fixed `max_depth` error message in `trace_at_time` to match actual bound (1–100)
+    - Fixed Cypher `at_time` query parameter to RFC3339 UTC (`Z` suffix) for unambiguous external DB comparisons
+    - `_normalize_temporal_input` now raises `ValueError` on unparseable strings instead of silently returning raw input
+    - Replaced `datetime.now()` with `datetime.utcnow()` for all `recorded_at` and checkpoint timestamps — aligns with codebase convention and avoids wrong local time on Windows
+    - `flush_checkpoint` wraps `TemporalVersionManager()` construction in a `try/except` and re-raises as `RuntimeError` with a clear actionable message
+  - Added 7 new tests (93 total across context modules, 0 failures)
+
+- **spaCy Runtime Fallback for NER Benchmarks**:
+    - Hardened `NERExtractor` spaCy initialization so installed-but-broken spaCy environments no longer crash during extractor construction.
+    - Updated ML entity extraction fallback behavior to catch runtime spaCy initialization failures, not just missing-model errors.
+    - Added regression coverage for the "spaCy present but unusable at runtime" initialization path.
+- **Deterministic Temporal Reasoning Engine** (PR #398 by @KaifAhmad1, implemented and follow-up fixes by OpenAI Codex):
+  - Added `semantica.kg.temporal_reasoning` as the single source of truth for deterministic, LLM-free temporal reasoning with an explicit zero-LLM module contract
+  - Implemented `TemporalInterval`, full Allen interval algebra via `IntervalRelation`, and `TemporalReasoningEngine`
+  - Added deterministic helpers for interval overlap/containment checks, open-ended activity checks, interval merging, gap analysis, coverage calculation, timelines, retroactive coverage, and temporal normalization
+  - Integrated temporal query interval logic with the reasoning engine in `TemporalGraphQuery`
+  - Preserved `semantica.reasoning` access via re-exports without making it the canonical implementation source
+  - Fixed open-ended `query_time_range(..., end_time=None)` handling so temporal range queries no longer crash on `TemporalBound.OPEN`
+  - Restored `temporal_granularity` behavior for point-in-time checks in `query_at_time()`
+  - Eliminated the `semantica.reasoning` / `semantica.kg` circular import risk introduced during the initial module move
+  - Added regression coverage for all 13 Allen relations, open-ended intervals, month-granularity point queries, open-ended range queries, retroactive coverage, and normalization idempotence
+
+- **Temporal Query Engine: Point-in-Time Correctness** (PR #397 by @KaifAhmad1, implemented and follow-up fixes by OpenAI Codex):
+  - Added `reconstruct_at_time(graph, at_time)` to `TemporalGraphQuery` to build a self-consistent point-in-time subgraph without mutating the input graph
+  - Updated `query_at_time()` to use point-in-time reconstruction internally so returned subgraphs exclude dangling edges when entity lifetimes are available
+  - Added `TemporalConsistencyIssue` and `TemporalConsistencyReport` plus temporal consistency validation for:
+    - inverted relationship intervals
+    - relationships outside entity lifetimes
+    - missing source/target entities
+    - overlapping same-type relationships on the same edge
+    - temporal gaps where a fact ends and restarts later
+  - Added a module-level `validate_temporal_consistency(graph)` API alongside the query-engine method
+  - Implemented sequence and cycle pattern detection with structured outputs containing `pattern_type`, `signature`, `frequency`, and per-occurrence node/edge/time details
+  - Implemented calendar-aligned temporal evolution bucketing based on `temporal_granularity`
+  - Added causal ordering controls to `find_temporal_paths()` via `enforce_causal_ordering` and `ordering_strategy` (`strict`, `overlap`, `loose`)
+  - **Follow-up fixes applied in the same PR**:
+    - Made `validate_temporal_consistency()` non-throwing on malformed temporal fields and return report errors instead of raising
+    - Enforced exclusive `valid_until` semantics for point-in-time checks (`valid_from <= at_time < valid_until`)
+    - Kept `query_time_range(..., temporal_aggregation="evolution")` backward-compatible by returning the flat relationship list plus a new `relationship_buckets` field
+    - Hardened temporal pattern detection for open-ended intervals (`TemporalBound.OPEN`) to avoid datetime arithmetic/comparison crashes
+    - Normalized relationship endpoints during point-in-time reconstruction so mixed-type IDs like `1` and `"1"` do not silently drop valid edges
+    - Added in-code design comments documenting the sequence/cycle output structure required by the checklist
+  - Added and expanded regression coverage for point-in-time reconstruction, exclusive end bounds, non-throwing validation, module-level validator access, pattern detection with gap tolerance/open bounds, evolution bucketing, causal ordering, and mixed-type IDs
+
+- **Core Temporal Data Model Overhaul** (PR #396 by @KaifAhmad1, implemented and follow-up fixes by OpenAI Codex):
+  - Added `semantica.kg.temporal_model` with shared helpers for parsing, normalizing, serializing, and deserializing temporal relationship fields
+  - Exported `TemporalBound` and `BiTemporalFact` from `semantica.kg` for backward-compatible temporal relationship handling
+  - Updated `TemporalGraphQuery` to use shared temporal parsing/model helpers instead of ad hoc string handling
+  - Added support for `valid`, `transaction`, and `both` time axes in temporal query filtering
+  - Standardized temporal normalization on `timezone.utc` for better cross-version portability
+  - Added `TemporalValidationError` to utils exports and made invalid temporal inputs consistently raise it
+  - Added history-preserving temporal revisions in `TemporalVersionManager.apply_revision()` with provenance metadata and supersession semantics
+  - Added safer snapshot persistence by serializing revision metadata before storage and surfacing storage failures as `ProcessingError`
+  - **Follow-up fixes applied in the same PR**:
+    - Added a default factory for `BiTemporalFact.recorded_at` and preserved legacy transaction-axis behavior by falling back to `valid_from` when `recorded_at` is missing
+    - Treated `TemporalBound.OPEN` as an unbounded value in shared query parsing so open-ended facts do not fail in public APIs like `analyze_evolution()` and path filtering
+    - Recomputed snapshot checksums before persisting revised snapshots and any original snapshot inserted during revision flow
+    - Replaced second-based revision suffixes with collision-resistant revision IDs/labels to avoid duplicate save failures under rapid revisions
+    - Removed warning spam caused by canonical serialized open bounds represented as `None`
+  - Added and expanded regression coverage for UTC normalization, transaction-axis queries, open-ended bounds, revision integrity, checksum verification, and collision-resistant revision identifiers
+
+- **Audit Trail, Named Tags, and Rollback Protection** (PR #394 by @ZohaibHassan16, reviewed by @KaifAhmad1, follow-up fixes by OpenAI Codex):
+  - Added mutation-level audit tracking for `ContextGraph` node and edge changes via `TemporalVersionManager.attach_to_graph()` and persistent mutation logging backends
+  - Added named version tags in both in-memory and SQLite storage so human-readable tags can point to saved snapshots
+  - Added rollback protection to `restore_snapshot()` so destructive graph restores require explicit confirmation
+  - Added `get_node_history()` for per-entity audit inspection and `diff()` as a Git-like alias over version comparisons
+  - Preserved backward compatibility for snapshot payloads and diff outputs by supporting both `nodes`/`edges` and `entities`/`relationships`
+  - Fixed mixed-schema snapshot comparison and version metadata counts after the audit-trail feature landed on top of PR #393
+  - Fixed restore replay so rollback does not generate synthetic mutation events in the audit log
+  - Added version-label assignment for previously unlabeled mutations when a snapshot is created
+  - Resolved merge conflicts against updated `main` in `managers.py`, `version_storage.py`, `context_graph.py`, and `test_managers.py`
+  - Added and updated regression coverage for audit history, rollback safety, version-label persistence, and snapshot compatibility
+
+- **Snapshot Schema Compatibility Fix** (PR #393 by @ZohaibHassan16, reviewed by @KaifAhmad1, follow-up fixes by OpenAI Codex):
+  - Fixed silent snapshot restore failures caused by the `ContextGraph` `nodes`/`edges` schema not matching the version manager's legacy `entities`/`relationships` expectations
+  - Updated temporal snapshot handling to accept both `nodes`/`edges` and `entities`/`relationships`
+  - Preserved both schema shapes in stored snapshots to maintain backward compatibility during migration
+  - Fixed temporal diffing and detailed comparison paths so new-format and mixed-format snapshots compare correctly
+  - Fixed version metadata counts so `entity_count` and `relationship_count` remain accurate for both snapshot schemas
+  - Restored ontology snapshot compatibility fields removed during the PR follow-up iteration
+  - Added regression coverage for new-format snapshot creation, metadata counts, and mixed-schema diffing
+
+- **ContextGraph Traversal Fallbacks for DecisionQuery & DecisionRecorder** (PR #386 by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1):
+  - Added native `ContextGraph` fallback execution paths to all 7 `DecisionQuery` methods (`_find_precedents_basic`, `find_by_category`, `find_by_entity`, `find_by_time_range`, `multi_hop_reasoning`, `trace_decision_path`, `find_similar_exceptions`) — resolves issue #379 where hardcoded Cypher queries broke in-memory usage
+  - Added native `ContextGraph` fallback paths to 4 `DecisionRecorder` methods (`link_entities`, `record_exception`, `link_precedents`, `_store_decision_node`, `_store_exception_node`) using `add_node` / `add_edge` primitives
+  - Implemented undirected BFS in `multi_hop_reasoning` fallback — traverses both outgoing and incoming edges so decisions are reachable from linked entities (matches Cypher `(start)-[*1..N]-(d:Decision)` semantics)
+  - Fixed `isinstance(graph_store, ContextGraph)` guards → `type(graph_store) is ContextGraph` — prevents `Mock(spec=ContextGraph)` from triggering fallback branches and breaking 2 existing tests
+  - Fixed `add_node(properties=metadata)` call in `_store_decision_node` and `_store_exception_node` — changed to `**metadata` so all decision fields are stored flat and remain readable via `_dict_to_decision`; previous form silently nested every field under a `"properties"` key
+  - Fixed spurious `properties={}` keyword argument in all `add_edge` fallback calls — argument did not match the actual `add_edge(**properties)` signature
+  - Fixed tz-aware / naive `datetime` mismatch in `find_by_time_range` fallback — strips `tzinfo` from aware bounds when stored timestamps are naive, preventing `TypeError` at comparison time
+  - Hoisted `find_edges()` calls out of the BFS `while` loop in `trace_decision_path` — edges are now fetched once per call instead of once per visited node, eliminating O(nodes × total_edges) repeated full-graph scans
+  - Removed duplicate `from ..embeddings import EmbeddingGenerator` import in `decision_query.py`
+  - Added `tests/context/test_decision_query_fallback.py` with 14 tests: full integration test covering the complete fallback flow end-to-end, plus 13 targeted unit tests covering each `DecisionQuery` and `DecisionRecorder` fallback method individually, tz-aware/naive datetime mixing, and `Mock` guard correctness
+
+- **ContextGraph Thread Safety & Pagination** (PR #385, Issues #378 #376 by @ZohaibHassan16, review & fixes by @KaifAhmad1):
+  - `ContextGraph`: added `threading.RLock` (`self._lock`) to `__init__`; all mutation paths (`add_nodes`, `add_edges`, `add_node`, `add_edge`, `save_to_file`, `load_from_file`, `link_graph`) and all read/query paths (`find_nodes`, `find_edges`, `find_node`, `find_active_nodes`, `get_neighbors`, `query`, `stats`, `density`) now protected with `with self._lock:` to prevent race-condition corruption under concurrent FastAPI workers
+  - `find_nodes` and `find_edges` gained native `skip`/`limit` pagination parameters so the explorer layer never loads the full collection into memory to slice it
+  - `GraphSession` (`session.py`): introduced session-level `RLock` wrapping all graph access; all 8 lazy analytics properties (`centrality`, `community`, `connectivity`, `path_finder`, `node_embedder`, `similarity`, `link_predictor`, `validator`) initialised under the lock (thread-safe double-checked); `get_nodes()` and `get_edges()` delegate pagination to the graph layer when no in-memory filter is needed
+  - `pyproject.toml`: removed duplicate entry and added missing comma in the `all` optional-dependency array that caused `ERROR Failed to parse pyproject.toml: Unclosed array` in CI
+  - **Fixes applied post-review (by @KaifAhmad1)**:
+    - Fixed `/api/graph/search` returning empty `content` and `properties` — `ContextGraph.query()` wraps results in `node.to_dict()` which uses a `"properties"` envelope, but `_node_dict_to_response` expected a flat `{id, type, content, metadata}` shape; `session.search()` now normalises the envelope before returning
+    - Fixed edge metadata silently dropped on import — `add_edges()` read only from the `"properties"` key, but edges produced by `find_edges()` and `build_graph_dict()` use `"metadata"`; fixed with `edge.get("properties") or edge.get("metadata", {})` fallback
+    - Fixed `POST /api/enrich/links` blocking the asyncio event loop — the O(n) `score_link` scoring loop ran inline in the `async` handler; wrapped in `asyncio.to_thread(_score_all)`
+    - Removed merge-artifact dead code in `session.py`: duplicate `self.annotations` assignment, duplicate un-locked property set, and double-query logic in `get_nodes()`/`get_edges()` that recomputed results outside the lock and threw away the correctly-paginated result computed inside it
+    - Removed merge-artifact dead code in `enrich.py`: unreachable second `predict_links` implementation block after early `return`, and duplicate `nodes, _` fetch in `detect_duplicates`
+
+- **Knowledge Explorer API Backend** (PR #384, Issue #377 by @ZohaibHassan16, review & fixes by @KaifAhmad1):
+  - Added `semantica.explorer` package — a full FastAPI backend for the Semantica Knowledge Explorer dashboard
+  - `app.py`: `create_app(session)` factory with CORS middleware, custom exception handlers (`KeyError→404`, `ValueError→422`), and HTML5 static-file fallback routing; generic `Exception` handler correctly re-raises `HTTPException` so dependency-injection 503s are not swallowed
+  - `session.py`: `GraphSession` — thread-safe container wrapping a `ContextGraph` with 8 lazily-initialised analytics components (`CentralityCalculator`, `CommunityDetector`, `ConnectivityAnalyzer`, `PathFinder`, `NodeEmbedder`, `SimilarityCalculator`, `LinkPredictor`, `GraphValidator`); all lazy properties initialised under `RLock` to prevent double-instantiation under concurrent requests; shared `build_graph_dict(node_ids=None)` method eliminates duplication across route files; `from_file(path)` classmethod loads from JSON
+  - `ws.py`: `ConnectionManager` — thread-safe WebSocket manager with `connect()`, `disconnect()`, `broadcast(event_type, data)`, and `send_personal()` support; safe disconnection cleanup during broadcast
+  - `dependencies.py`: `get_session(request)` and `get_ws_manager(request)` FastAPI `Depends`-compatible callables; `get_session` raises `HTTP 503` when no session is attached
+  - 7 modular route files, all using `asyncio.to_thread` for sync graph operations:
+    - `routes/graph.py`: `GET /api/graph/nodes` (type/keyword filter, pagination), `GET /api/graph/node/{id}`, `GET /api/graph/node/{id}/neighbors` (BFS, depth 1–5), `GET /api/graph/edges` (type/source/target filter), `GET /api/graph/node/{id}/path` (BFS or Dijkstra — algorithm param now correctly dispatched), `POST /api/graph/search`, `GET /api/graph/stats`
+    - `routes/analytics.py`: `GET /api/analytics` (centrality, community, connectivity — comma-separated metrics param), `GET /api/analytics/validation`
+    - `routes/decisions.py`: `GET /api/decisions` (category filter, pagination), `GET /api/decisions/{id}`, `GET /api/decisions/{id}/chain` (BFS causal chain up to 5 hops), `GET /api/decisions/{id}/precedents` (category + scenario keyword ranking), `GET /api/decisions/{id}/compliance` (in-graph check over `violates`/`non_compliant`/`breaches` edges — no longer a stub)
+    - `routes/temporal.py`: `GET /api/temporal/snapshot` (ISO-8601 `at` param), `GET /api/temporal/diff` (added/removed node sets between two timestamps), `GET /api/temporal/patterns` (graceful fallback when `TemporalPatternDetector` unavailable, with warning log for unexpected errors)
+    - `routes/enrich.py`: `POST /api/enrich/extract` (NLP entity/relation extraction), `POST /api/enrich/links` (per-node link prediction via `score_link` against all non-adjacent candidates — fixed from broken `predict_links` call), `POST /api/enrich/dedup` (duplicate detection — fixed missing `asyncio.to_thread` that was blocking the event loop), `POST /api/reason` (forward/backward inference via `Reasoner`)
+    - `routes/export_import.py`: `POST /api/export` (12 formats: JSON, Turtle, RDF-XML, N-Triples, CSV, GraphML, GEXF, OWL, Cypher, AQL, YAML — temp file always cleaned up via `try/finally`), `POST /api/import` (JSON/JSON-LD multipart upload with WebSocket progress events)
+    - `routes/annotations.py`: `GET /api/annotations`, `POST /api/annotations` (validates node exists; `add_annotation` mutates dict in-place so no extra roundtrip), `DELETE /api/annotations/{id}`
+  - `schemas.py`: 28 Pydantic v2 request/response models covering all endpoint shapes including pagination, temporal, enrichment, compliance, and annotation types
+  - `__init__.py`: `semantica-explorer` CLI entry point — `--graph`, `--host`, `--port`, `--no-browser` args; validates graph file exists; checks for `uvicorn`; opens browser after 1.5 s delay
+  - `pyproject.toml`: added `[project.optional-dependencies] explorer` group (`fastapi`, `uvicorn[standard]`, `websockets`, `python-multipart`); registered `semantica-explorer` script entry point; fixed missing comma in `all` extra that broke `pip install semantica[all]`
+  - **Fixes applied post-review (by @KaifAhmad1)**:
+    - Fixed `predict_links` endpoint — was calling `predictor.predict_links(graph_dict, node_id, top_n=...)` with wrong type (`dict` as `graph_store`), wrong positional arg (`node_id` as `node_labels`), and wrong kwarg (`top_n` vs `top_k`); rewrote to iterate all non-adjacent candidate nodes and call `predictor.score_link(session.graph, source, candidate)` directly
+    - Fixed `detect_duplicates` endpoint — `session.get_nodes()` was called directly in an `async def` handler without `asyncio.to_thread`, blocking the event loop
+    - Fixed temp file leak in `export_graph` — file was not deleted on exception from `export_fn` or `open()`; wrapped in `try/finally`; moved `import os` to module level
+    - Fixed `pyproject.toml` `all` extra — two consecutive strings with no comma between them caused a TOML syntax error
+    - Fixed generic `Exception` handler swallowing `HTTPException(503)` raised by `get_session`
+    - Fixed compliance endpoint — imported `PolicyEngine` then discarded it, always returning `compliant=True`; replaced with in-graph edge scan
+    - Fixed `temporal_patterns` bare `except Exception` silently hiding bugs — split into `ImportError` (silent graceful) and `Exception` (warning log)
+    - Fixed all 8 lazy analytics properties to initialise under `_lock` (thread-safe double-checked)
+    - Fixed `find_path` ignoring the `algorithm` query param — now dispatches to `dijkstra_shortest_path` or `bfs_shortest_path`
+    - Removed unnecessary `get_annotations()` round-trip in `create_annotation`
+    - Removed `import traceback` unused import in `app.py`
+    - Deduplicated `_build_graph_dict` (was copied identically in `graph.py`, `analytics.py`, `export_import.py`) into `GraphSession.build_graph_dict()`
+  - 49 integration tests in `tests/explorer/test_explorer_api.py` using `starlette.testclient.TestClient` — all passing; covers health, nodes, edges, search, stats, decisions, causal chains, precedents, compliance (including violation detection), temporal snapshots/diff/patterns, analytics, reasoning, entity extraction, link prediction, deduplication, annotations, export (JSON + node-subset), and import (JSON + edges + unsupported format)
+- **Reasoning Dead Code Removal** (PR #387, Issue #382 by @ZohaibHassan16):
+  - Removed lines 357–358 in `semantica/reasoning/reasoner.py` that silently overwrote the sophisticated `_match_pattern` regex (which handles pre-bound variable embedding, repeated-variable backreferences via `(?P=var)`, and non-greedy named capture groups) with a simpler `re.escape`-based pattern, making all the prior logic unreachable dead code
+  - Removed duplicate unreachable `return None` on line 368 (syntactically dead, appearing immediately after another `return None` in the same branch)
+  - Surfaced `re.error` exceptions instead of swallowing them with `except Exception: pass`, preventing silent failures when malformed patterns were passed to `re.match`
+  - Before this fix, any rule using the same variable twice (e.g. `rel(?x, ?x)`) generated a duplicate named group error that was silently caught, causing the match to return `None` regardless of the fact — breaking transitivity, symmetry, and self-join rule patterns entirely
+
+- **Agno Agentic Framework Integration** (Issue #249):
+  - Added `AgnoContextStore` — graph-backed agent memory implementing the `agno.memory.db.base.MemoryDb` protocol; wraps `AgentContext` + `VectorStore`; supports `create()`, `table_exists()`, `memory_exists()`, `read_memories()`, `upsert_memory()`, `delete_memory()`, `drop_table()`, `clear()` plus extended `record_decision()`, `find_precedents()`, `retrieve()` methods
+  - Added `AgnoKnowledgeGraph` — multi-hop GraphRAG knowledge base implementing `agno.knowledge.base.AgentKnowledge`; ingests files, directories, URLs, and raw text via NER → relation extraction → graph build → vector index pipeline; `search()` returns `AgnoDocument` objects; `get_graph_context(entity)` returns text summary of entity's graph neighbourhood
+  - Added `AgnoDecisionKit` — Agno `Toolkit` subclass exposing 6 decision-intelligence tools: `record_decision`, `find_precedents`, `trace_causal_chain`, `analyze_impact`, `check_policy`, `get_decision_summary`
+  - Added `AgnoKGToolkit` — Agno `Toolkit` subclass exposing 7 KG pipeline tools: `extract_entities`, `extract_relations`, `add_to_graph`, `query_graph`, `find_related`, `infer_facts`, `export_subgraph`
+  - Added `AgnoSharedContext` — team-level coordinator with a single shared `ContextGraph`; `bind_agent(role)` returns a role-scoped `_AgentScopedStore` with cross-agent memory visibility; thread-safe via `RLock`
+  - All 5 components degrade gracefully when `agno` is not installed (`AGNO_AVAILABLE` flag); importable and functional without agno present
+  - Added `agno = ["agno>=1.0.0"]` optional dependency in `pyproject.toml`; included in `all` extra
+  - 110 integration tests in `tests/integrations/agno/` covering all public APIs, MemoryDb protocol compliance, GraphRAG search, tool registration, shared memory isolation, and thread-safety
+  - 3 cookbook notebooks in `cookbook/integrations/`: `agno_decision_intelligence.ipynb` (loan underwriting), `agno_graphrag_context.ipynb` (regulatory compliance), `agno_multi_agent_shared_context.ipynb` (multi-agent team coordination)
+  - Full reference documentation in `docs/integrations/agno.md`
+
+- **Novita AI Provider** (PR #374 by @Alex-wuhu):
+  - Added `NovitaProvider` — OpenAI-compatible integration via `https://api.novita.ai/v1`; supports `generate()` and `generate_structured()` (JSON forced format)
+  - Default model: `deepseek/deepseek-v3.2`; configurable via `NOVITA_API_KEY` environment variable
+  - Registered `"novita"` in the built-in provider factory; usable via `create_provider("novita")`
+  - Added integration tests in `tests/test_novita_integration.py` with proper assertions and graceful skip when `NOVITA_API_KEY` is unset
+
+- **Native Datalog Reasoning Engine** (PR #371, Issue #368 by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1):
+  - Added `DatalogReasoner` to `semantica.reasoning` — a 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).`) that existing engines loop on indefinitely
+  - Memory-optimized `_unify()` with deferred dict allocation — zero allocation on failed unifications
+  - `O(1)` delta-index lookup per iteration eliminates redundant `O(N)` rule re-evaluations in semi-naive loop
+  - `query("pred(?X, ?Y)")` returns variable-binding dicts; supports both uppercase `?Y` and lowercase `?y` variable syntax
+  - `query(..., bindings={"Y": "val"})` pre-binds variables for exact-match verification
+  - `load_from_graph(ContextGraph)` converts all edges and nodes to Datalog facts in one call; handles both `find_edges`/`find_nodes` and raw `edges`/`nodes` graph APIs
+  - `add_fact()` accepts `"pred(a, b)"` strings and Semantica dicts (`subject/predicate/object`, `source/target/type`, `type/id` shapes); warns on unrecognised dict format instead of silently dropping
+  - `_derived` cache flag — `derive_all()` skips re-evaluation when no facts or rules have changed since last run; `query()` respects the cache
+  - Progress tracking wrapped in `try/finally` — `stop_tracking()` always called even on exception
+  - `DatalogReasoner`, `DatalogFact`, `DatalogRule` exported from `semantica.reasoning`
+  - 18 tests covering recursive rules, multi-hop inference, variable binding, graph integration, idempotency, and edge cases — all passing
+- **Ontology Diff & Migration** (PR #367 by @ZohaibHassan16, review & fixes by @KaifAhmad1):
+  - `VersionManager.diff_ontologies(base, target)` — structured diff between two ontology dicts using hash-map lookups; handles URI-less items via `name` fallback; deep equality checks for unordered lists; now covers classes, properties, individuals, and axioms
+  - `ChangeLogAnalyzer.analyze(diff)` — classifies each change by semantic impact: removed classes/properties → `CRITICAL/BREAKING`; narrowed domain/range/cardinality → `HIGH/BREAKING`; hierarchy modifications → `MEDIUM/POTENTIALLY_BREAKING`; added elements and annotation updates → `INFO/NON_BREAKING`
+  - `ImpactReport` dataclass and `generate_change_report(diff)` public helper — returns a structured dict with `summary`, `impact_classification` (breaking / potentially_breaking / safe), `recommendations`, and the raw `diff`
+  - `OntologyEngine.compare_versions(base_id, target_id, **options)` — end-to-end orchestrator: loads versions from `VersionManager`, runs `diff_ontologies`, generates impact report; accepts `base_dict`/`target_dict` overrides to bypass version store; `run_validation=True` triggers `OntologyValidator` on the target schema; `graph_data=...` additionally runs `GraphValidator` on instance data against the new schema
+  - `OntologyEngine.get_ontology_version_dict(version_id)` — utility to load a registered version as a plain dict ready for diffing
+  - Documentation added to `docs/reference/change_management.md`: "Ontology Diff & Migration" section with code example and full report format reference
+  - 7 tests added to `tests/change_management/test_managers.py` covering: empty diff, unordered list equality, URI/name fallback, breaking class removal, narrowed domain (HIGH), safe additions and annotation changes, `compare_versions` dict override, version-not-found error path, individuals/axioms diff coverage, null constraint value flagged as breaking
+  - **Fixes applied post-review (by @KaifAhmad1)**:
+    - Fixed typo in `ChangeCategory` enum value: `"potenitally_breaking"` → `"potentially_breaking"`
+    - Fixed missing space in impact description string: `f"New{entity_type}"` → `f"New {entity_type}"`
+    - Added null-value guard in `_analyze_field_changes` — constraint fields with `None` old/new value are now correctly flagged as breaking instead of silently passing the subset check
+    - Made `ChangeLogAnalyzer` stateless — `report` is now a local variable passed into `_generate_recommendations(report)` rather than stored as `self.report`; removes re-entrancy hazard
+    - Removed no-op `__init__` from `ChangeLogAnalyzer`
+    - Replaced non-portable emoji markers in recommendations (`✘✘✘`, `¤¤¤`, `☺☺☺`) with plain-text tags (`[BREAKING]`, `[WARNING]`, `[SAFE]`)
+    - Extended `diff_ontologies` to cover `individuals` and `axioms` — previously only classes and properties were diffed; the public `compare_versions` path now returns all four element types
+    - Fixed exception chaining in `compare_versions`: `raise ProcessingError(...) from e` to preserve original traceback
+    - Removed silent `ImportError` swallow for `GraphValidator` — it is a first-party module; an `ImportError` indicates a broken install, not a graceful skip
+    - Added comment on deferred `VersionManager` import in `OntologyEngine.__init__` explaining the circular-import constraint
+    - Fixed import-before-docstring in `tests/change_management/test_managers.py`
+    - Fixed broken Markdown link syntax in docs JSON example block: `"[http://...](http://...)"` → bare URI string
+    - Updated docs recommendations example to match the new plain-text tag format
+
+- **Ontology Alignment API** (PR #361 by @ZohaibHassan16, review & fixes by @KaifAhmad1):
+  - Alignment representation using standard RDF predicates: `owl:equivalentClass`, `owl:equivalentProperty`, `owl:sameAs`, `skos:exactMatch`, `skos:closeMatch`, `skos:broadMatch`, `skos:narrowMatch`, `skos:relatedMatch`
+  - `OntologyEngine.create_alignment(source_uri, target_uri, predicate)` — store alignment triples in TripletStore
+  - `OntologyEngine.get_alignments(entity_uri)` — bidirectional retrieval of all alignments for an entity
+  - `OntologyEngine.list_alignments(ontology_uri=None)` — list all alignments, optionally filtered by ontology namespace
+  - `NamespaceManager.get_alignment_predicates()` — expose standard OWL/SKOS alignment URIs as a convenience dict
+  - `ReuseManager.suggest_alignments(target, source)` — O(N+M) hashmap heuristic to suggest alignments based on exact label matches across ontologies
+  - `ReuseManager.merge_ontology_data(..., compute_alignments=True)` — optionally attach suggested alignments to merge output without auto-committing unverified triples
+  - `QueryEngine.expand_entity_uri(uri, store, use_alignments=True)` — bidirectional SPARQL expansion to include aligned equivalents; no-ops when flag is False
+  - `QueryEngine.build_values_clause(variable, uris)` — generate a SPARQL `VALUES` clause for injecting expanded URIs into queries
+  - Alignment-aware queries section added to `docs/reference/triplet_store.md`
+  - Ontology Alignment section added to `docs/reference/ontology.md`
+  - **Fixes applied post-review (by @KaifAhmad1)**:
+    - Fixed progress tracker leak in `expand_entity_uri` — `stop_tracking` was only called inside the `hasattr(execute_sparql)` branch; backends without it silently leaked a tracker entry
+    - Fixed `relatedMatch` predicate gap — `get_alignment_predicates()` exposed `skos:relatedMatch` but all three SPARQL FILTER lists omitted it, making those alignments permanently invisible
+    - Fixed SPARQL injection in `list_alignments` — previously only `"` was escaped; `\`, `{`, and `}` are now also percent-encoded to prevent WHERE block breakout
+    - Fixed SPARQL injection in `build_values_clause` — URIs now run through `_sanitize_uri` before wrapping in angle-bracket literals
+    - Added full-URI validation in `create_alignment` — raises `ProcessingError` if predicate is a CURIE instead of a full URI, preventing silent storage of unqueryable triples
+    - Fixed E2E test `test_end_to_end_cross_ontology_uri_flow` — previously mocked the method under test; now uses a real mock backend with `execute_sparql` to exercise the actual expansion and VALUES clause injection flow
+  - 19 tests added covering: `create_alignment`, `get_alignments`, `suggest_alignments`, merge with alignment computation, `expand_entity_uri` (enabled/disabled), `build_values_clause`, and full E2E cross-ontology query flow
+- **Context Explainability Output Fixes** (by @KaifAhmad1):
+  - Fixed decision-node storage in `ContextGraph` so full human-readable `scenario`, `reasoning`, and decision metadata are preserved on graph nodes instead of degrading into opaque IDs or truncated display text
+  - Fixed causal and precedent reconstruction paths in the context module so returned `Decision` objects prefer readable stored fields over raw node identifiers
+  - Fixed context aggregate outputs to return enriched readable payloads for influence, causality, similarity, policy-impact, and entity-similarity workflows instead of bare UUID lists or tuple-only results
+  - Fixed `PolicyEngine.get_affected_decisions()` so both Cypher and fallback branches return consistent decision metadata including `scenario`, `category`, `outcome`, and `confidence`
+  - Fixed `EntityLinker` similarity flows so enriched similarity results are consumed correctly across internal linking paths and public search aliases
+  - Fixed `CentralityCalculator._build_adjacency()` to handle `ContextGraph` edges (dataclass `ContextEdge` objects with `source_id`/`target_id`) so `calculate_degree_centrality()` and related centrality algorithms work correctly when a `ContextGraph` is passed as the graph store
+  - Fixed downstream KG integrations in `node_embeddings`, `link_predictor`, `centrality_calculator`, `path_finder`, and context retrieval fallbacks to normalize enriched neighbor/node outputs without breaking graph algorithms
+  - Added 23 regression tests in `tests/context/test_context_explainability_regression.py` covering readable decision text preservation, enriched causal/path outputs, policy-impact results, entity similarity payloads, and compatibility with KG consumers
+
+## [0.3.0] - 2026-03-10
+
+- **Context Graph Feature Completeness** (by @KaifAhmad1):
+  - Added `valid_from` / `valid_until` temporal validity fields to `ContextNode` and `ContextEdge` dataclasses — both expose `is_active(at_time=None) -> bool`; nodes/edges without these fields are always considered active
+  - Added `add_node(valid_from=..., valid_until=...)` and `add_edge(valid_from=..., valid_until=...)` support — validity windows are extracted from `**properties` and stored as first-class dataclass fields, not in metadata
+  - Added `ContextGraph.find_active_nodes(node_type=None, at_time=None)` — returns only nodes whose validity window includes the given time (defaults to `datetime.utcnow()`); complements `find_nodes()` with temporal filtering
+  - Added `min_weight: float = 0.0` parameter to `ContextGraph.get_neighbors()` — edges with weight below the threshold are skipped during BFS traversal, enabling weighted/confidence-filtered multi-hop navigation; fully backward-compatible (default 0.0 passes all edges)
+  - Added `ContextGraph.link_graph(other_graph, source_node_id, target_node_id, link_type="CROSS_GRAPH") -> str` — creates a navigable bridge between two separate `ContextGraph` instances; records a marker edge internally and returns a `link_id`
+  - Added `ContextGraph.navigate_to(link_id) -> (other_graph, target_node_id)` — resolves a `link_id` to the target graph and its entry node, enabling hierarchical cross-graph traversal (e.g. agent moving from a high-level decision graph into a domain-specific sub-graph)
+  - Added `ContextGraph.resolve_links(registry)` — reconnects cross-graph links after `load_from_file()`; `save_to_file()` now persists a `links` section with `other_graph_id` so navigation survives the full save/load cycle
+  - Added `graph_id` field to `ContextGraph` — stable UUID per instance, persisted to JSON, so separate graphs can identify each other after reload
+  - Fixed `is_active()` on `ContextNode` and `ContextEdge` — tz-aware `datetime` inputs are now normalised to tz-naive UTC before comparison, preventing `TypeError` when callers pass `datetime.now(timezone.utc)`
+  - Fixed `valid_from` / `valid_until` serialisation — `add_nodes()`, `add_edges()`, `to_dict()`, and `from_dict()` all now preserve and restore validity windows; previously these fields were silently lost
+  - Fixed cross-graph link artifact — `link_graph()` now pre-creates a `"cross_graph_link"` typed `ContextNode` for the marker before inserting the marker edge, preventing `_add_internal_edge()` from auto-creating a phantom `"entity"` node
+  - Added 14 tests in `tests/context/test_cross_graph_navigation.py` covering link creation, phantom-node prevention, and full save/load round-trips with `resolve_links()`
+  - Fixed `pipeline_builder.add_step()` return type annotation from `"PipelineBuilder"` to `"PipelineStep"` — implementation was already correct per 0.3.0-beta changelog, only signature and docstring were stale
+  - Fixed `test_hybrid_search_performance` timing computation — accumulated a real `search_times` list and compute true average; raised threshold to `< 5.0s` to account for real `sentence-transformers` (384-dim) latency
+
+
+
+- **0.3.0 Bug Fixes & Comprehensive Real-World Tests** (by @KaifAhmad1):
+  - Fixed `ProvenanceTracker` missing from `semantica/kg/__init__.py` exports — `from semantica.kg import ProvenanceTracker` now works correctly
+  - Fixed duplicate relation creation in `_parse_relation_result` — orphaned legacy block was appending every relation twice; removed the duplicate block
+  - Added `extraction_method` parameter to `_parse_relation_result`; typed extraction path now correctly sets `"llm_typed"` instead of `"llm"` in relation metadata
+  - Fixed cross-test cache pollution in `tests/semantic_extract/test_retry_logic.py` — module-level `_result_cache` now cleared in `setUp()` to prevent intermittent failures when tests share input text
+  - Added `tests/test_030_realworld_comprehensive.py`: 85 real-world tests covering all 0.3.0-alpha/beta features with real data (tech companies, CEOs, products, investment chains, healthcare scenarios)
+    - ContextGraph basic operations and decision tracking lifecycle
+    - KG algorithms: centrality, community detection, embeddings, path finding, similarity, link prediction, connectivity
+    - PolicyEngine, DecisionQuery, AgentContext, Decision model serialization
+    - ProvenanceTracker with GraphBuilderWithProvenance and AlgorithmTrackerWithProvenance
+    - Deduplication v2 with blocking strategies, RDF/TTL export, Reasoner inference
+    - Pipeline builder/validator/failure handler with retry policies
+    - Multi-hop investment chain (Microsoft→OpenAI, Google→Anthropic) end-to-end
+    - Healthcare entity extraction and knowledge graph construction E2E
+
+## [0.3.0-beta] - 2026-03-07
+
+- **Multi-Founder LLM Extraction & Reasoner Inference Fix** (PR #354 by @KaifAhmad1):
+  - Fixed `_parse_relation_result` in `methods.py` — unmatched subjects/objects now produce a synthetic `UNKNOWN` entity instead of silently dropping the relation; all LLM-returned co-founders are preserved
+  - Rewrote `_match_pattern` in `reasoner.py` — splits pattern on `?var` placeholders first, then escapes only the literal segments; pre-bound variables resolve to exact literals, repeated variables use backreferences, non-greedy `.+?` prevents over-consumption of literal separators
+  - Added `tests/reasoning/test_reasoner.py` with 4 tests covering multi-word value inference, pre-bound variables, binding conflicts, and single-word regression
+  - Added `tests/semantic_extract/test_relation_extractor.py` with 6 tests covering all-founders returned, synthetic entity creation, matched entity integrity, predicate/confidence preservation, empty response, and malformed entries
+- **TTL Export Alias Fix** (PR #355 by @KaifAhmad1):
+  - Added `_format_aliases` map in `RDFExporter` so `format="ttl"`, `"nt"`, `"xml"`, `"rdf"`, and `"json-ld"` resolve to their canonical counterparts without breaking existing callers
+  - Alias resolution applied at the top of `export_to_rdf()` before format validation — zero public API changes
+  - Added working TTL export cell to `cookbook/introduction/15_Export.ipynb` (Step 3: RDF Export)
+  - Added `tests/export/test_rdf_exporter.py` with 8 tests covering all aliases, canonical formats, error handling, and file export
+
+- **Incremental/Delta Processing Feature** (PR #349 by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1):
+  - Native delta computation between graph snapshots using SPARQL queries
+  - Delta-aware pipeline execution with `delta_mode` configuration for processing only changed data
+  - Version snapshot management with graph URI tracking and metadata storage
+  - Snapshot retention policies with automatic cleanup via `prune_versions()` method
+  - Integration with pipeline execution engine for incremental workflows
+  - Significant performance improvements: processes only changes instead of full datasets
+  - Cost optimization: dramatically reduces compute and storage requirements for large-scale operations
+  - Production-ready for near real-time pipelines and frequent deployment scenarios
+  - Bug fixes: corrected SPARQL variable order, fixed class references, resolved duplicate dictionary keys
+  - Comprehensive test coverage including delta mode integration tests
+  - Complete documentation with usage examples and API references
+  - Essential for enterprise-grade, large-scale semantic infrastructure
+- **Deduplication v2 Migration Guide** (PR #344 by @ZohaibHassan16, fixes by @KaifAhmad1):
+  - Added comprehensive MIGRATION_V2.md documentation for Deduplication v2 Epic #333
+  - Documented Candidate Generation V2 with multi-key blocking and phonetic matching
+  - Documented Two-Stage Scoring prefilter with configurable thresholds
+  - Documented Semantic Relationship Deduplication v2 with synonym mapping
+  - Added practical code examples for all V2 features with opt-in configuration
+  - Fixed critical infinite recursion bug in dedup_triplets() function
+  - Completed Epic #333 with comprehensive migration path and documentation
+  - Performance: 5.86x speedup confirmed (129ms vs 754ms) for semantic deduplication
+  - Full backward compatibility maintained with legacy mode as default
+- **Semantic Relationship Deduplication v2** (PR #340 by @ZohaibHassan16, fixes by @KaifAhmad1):
+  - Implemented opt-in semantic relationship deduplication mode (`semantic_v2`) with 6.98x performance improvement
+  - Added canonicalization engine with predicate synonym mapping (`works_for` → `employed_by`)
+  - Implemented fast-path O(1) hash matching for exact canonical signature comparisons
+  - Added weighted semantic scoring (60% predicate + 40% object composition) with explainable `semantic_match_score` metadata
+  - Enhanced `dedup_triplets()` function as first-class API in `methods.py`
+  - Integrated semantic deduplication into merge strategy with canonical key generation
+  - Added literal normalization for whitespace cleanup in object matching
+  - Maintained full backward compatibility with legacy mode as default
+  - Fixed critical infinite recursion bug in `dedup_triplets()` function via registry name checking
+  - Performance: Semantic V2 (~83ms) vs Legacy (~579ms) - 6.98x speedup confirmed
+  - All 13 deduplication benchmarks passing with comprehensive test coverage
+- **Two-Stage Scoring Prefilter** (PR #339 by @ZohaibHassan16):
+  - Implemented opt-in two-stage scoring with fast prefilter gates to eliminate expensive semantic scoring for obvious non-matches
+  - Prefilter gates: type mismatch detection, name length ratio validation, token overlap requirements
+  - Performance improvements: 18-25% faster batch processing with prefilter enabled
+  - Configurable thresholds: `min_length_ratio`, `min_token_overlap_ratio`, `required_shared_token`
+  - Enhanced explainability with score breakdown and rejection reasons in metadata
+  - Complete backward compatibility with default `prefilter_enabled=False`
+
+- **Candidate Generation v2 with Multi-Key Blocking** (PR #338 by @ZohaibHassan16):
+  - Implemented opt-in candidate generation strategies (`legacy`, `blocking_v2`, `hybrid_v2`) to address O(N²) pair explosion during deduplication
+  - Multi-key blocking with normalized token prefixes, type-aware keys, and optional phonetic (Soundex) blocking
+  - Deterministic candidate budgeting with `max_candidates_per_entity` limit using stable sorting
+  - Efficient pair generation with set-based deduplication across overlapping blocks
+  - Performance improvements: 63.6% faster in worst-case scenarios (0.259s → 0.094s for 100 entities)
+  - Complete backward compatibility with default `candidate_strategy="legacy"`
+  - Added configuration options: `blocking_keys`, `enable_phonetic_blocking`, `max_candidates_per_entity`
+
+- **ArangoDB AQL Export Support** (PR #342 by @tibisabau):
+### Added
+
+- **ArangoDB AQL Export Support** (PR #342 by @tibisabau)
+  - Full-featured ArangoDB AQL exporter with 642 lines of production-ready code
+  - Comprehensive AQL INSERT statement generation for vertices and edges
+  - Configurable collection names with validation and sanitization
+  - Batch processing support for large knowledge graphs (default: 1000)
+  - Added export_arango() convenience function for easy access
+  - Enhanced unified export with AQL format support and .aql auto-detection
+  - Added `export_arango()` convenience function for easy access
+  - Enhanced unified export with AQL format support and `.aql` auto-detection
+  - Integrated with method registry for extensibility
+  - 17 comprehensive test cases with 100% pass rate
+  - Enterprise-grade ArangoDB multi-model database integration
+
+- **Apache Parquet Export Support** (PR #343 by @tibisabau):
+- **Apache Parquet Export Support** (PR #343 by @tibisabau)
+  - Full-featured Apache Parquet exporter with 701 lines of production-ready code
+  - Columnar storage format optimized for analytics and data warehousing
+  - Configurable compression codecs (snappy, gzip, brotli, zstd, lz4, none)
+  - Explicit Arrow schemas with type safety and consistency
+  - Field normalization for varied entity and relationship naming conventions
+  - Structured metadata handling using Parquet struct fields
+  - Added export_parquet() convenience function for easy access
+  - Enhanced unified export with Parquet format support and .parquet auto-detection
+  - Added `export_parquet()` convenience function for easy access
+  - Enhanced unified export with Parquet format support and `.parquet` auto-detection
+  - Integrated with method registry for extensibility
+  - 25 comprehensive test cases with 100% pass rate
+  - Enterprise-grade analytics integration with pandas, Spark, Snowflake, BigQuery, Databricks
+
+### Fixed
+- **Fixed NameError**: missing Type import in utils/helpers.py
+
+- Fixed NameError: missing Type import in utils/helpers.py
+  - Added Type to typing imports to fix retry_on_error decorator
+  - Removed unused Type import from config_manager.py
+  - Resolves ImportError when importing semantica modules
+  - Fixes capability gap analysis notebook execution
+
+- **Test Suite Fixes: 0.3.0-alpha & Unreleased Features** (PR utils by @KaifAhmad1):
+
+  **Context Module (`semantica/context/`)**
+  - Fixed `retrieve_decision_precedents` to gate entity extraction on `use_hybrid_search=True` — was incorrectly extracting entities when flag was `False`
+  - Fixed `_extract_entities_from_query` to use `word[0].isupper()` instead of `word.istitle()` — correctly captures `CreditCard`, `CustomerID` etc.
+  - Added missing `expand_context` method — BFS graph traversal via `knowledge_graph.get_neighbors`
+  - Added missing `_get_decision_query` method — creates a `DecisionQuery` from the knowledge graph
+  - Fixed `hybrid_retrieval` to call `expand_context(query)` once (not per-entity) and include `"query"` key in return dict
+  - Fixed `dynamic_context_traversal` to call `expand_context` once per query instead of per entity
+  - Fixed `multi_hop_context_assembly` to use `_get_decision_query()` for robust decision lookup
+  - Fixed `_retrieve_from_vector` to fall back to `result["metadata"]["content"]` when `result["content"]` is absent — prevents empty content and negative similarity scores during semantic re-ranking
+
+  **Knowledge Graph Module (`semantica/kg/`)**
+  - Fixed `calculate_pagerank` — added `alpha` and `max_iter` parameter aliases; changed return format to structured dict `{"centrality": scores, "rankings": sorted_list}`
+  - Fixed `community_detector._to_networkx` to return a NetworkX graph directly when one is passed (was converting to adjacency list, silently losing all edges)
+  - Added `method` as alias for `algorithm` parameter in `detect_communities`
+  - Fixed `_build_adjacency` to handle `"edges"` key (list of tuples) in addition to `"relationships"` (list of dicts)
+  - Added `_track_generic` base method and 9 domain-specific tracking methods to `AlgorithmTrackerWithProvenance`: `track_influence_analysis`, `track_verification_analysis`, `track_supply_chain_paths`, `track_bottleneck_analysis`, `track_quality_analysis`, `track_lead_time_analysis`, `track_cross_domain_analysis`, `track_cross_domain_similarity`, `track_collaboration_potential`
+  - Created new `provenance_tracker.py` module with `ProvenanceTracker` class (`track_entity`, `get_all_sources`, `clear`)
+
+  **Pipeline Module (`semantica/pipeline/`)**
+  - Fixed `execution_engine` retry loop to properly iterate up to `max_retries` (was only retrying once regardless of policy)
+  - Added `RecoveryAction` dataclass and `handle_failure(error, policy, retry_count)` method to `FailureHandler` — implements LINEAR, EXPONENTIAL, and FIXED backoff strategies
+  - Fixed `pipeline_builder.add_step` to return the created `PipelineStep` object instead of `self`
+  - Added `validate` as a public alias for `validate_pipeline` in `PipelineValidator`
+  - Updated missing-dependency error message to `"Missing dependency '{dep}' for step '{name}'"` for consistent test assertions
+
+  **Vector Store (`semantica/vector_store/`)**
+  - Relaxed `test_batch_processing_performance` threshold from `< 100ms` to `< 500ms` per decision — original threshold was too tight for development machines running a real `sentence-transformers` embedding model (384-dim)
+
+  **Test File Fixes**
+  - `test_end_to_end_context_integration.py` — replaced emoji characters (`✅`, `❌`, `🔄`, `⚠️`) with ASCII equivalents (`[OK]`, `[FAIL]`, `[...]`, `[WARN]`) to fix Windows cp1252 encoding error
+  - `test_context_retriever_precedents.py` — moved `assert_called_once_with` inside `with patch.object` block; fixed assertion to use `decision.scenario` not `decision.decision_id`; removed `"iPhone"` (lowercase-first) from entity extraction assertion
+  - `test_real_world_scenarios.py` — fixed duplicate `source=` keyword argument (renamed to `label=`); fixed cross-domain analysis loop to iterate over all social network users instead of only `academic_users`
+  - `test_pipeline_comprehensive.py` — changed `test_pipeline_validator_missing_deps` to call `validator.validate(builder)` directly instead of `builder.build()` which raises `ValidationError` before validation can complete
+
+  **Results: ~840 tests passing, 36 skipped (external services), 0 failed**
+
+## [0.3.0-alpha] - 2026-02-19
+
+### Added / Changed
+
+- **Decision Tracking System**: Complete decision lifecycle management with audit trails and provenance tracking
+- **Advanced KG Algorithms**: Node2Vec embeddings, centrality analysis, community detection for decision insights  
+- **Enhanced Context Module**: Unified AgentContext with granular feature flags and decision tracking integration
+- **Vector Store Features**: Hybrid search combining semantic, structural, and category similarity
+- **Policy Management**: Versioning, compliance checking, and exception handling
+- **Production Ready Architecture**: Scalable design with comprehensive error handling and validation
+
+### Fixed
+
+- Fixed import issues in test suite (ProvenanceTracker location fixes)
+- Fixed causal analyzer validation (max_depth bounds checking)
+- Fixed test compatibility with updated method signatures
+- Fixed mock object setup in test suites
+- Comprehensive test suite fixes for decision tracking features
+
+### Testing
+
+- 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
+
+### Documentation
+
+- Enhanced context module documentation
+- Updated API references for decision tracking features
+- Comprehensive usage guides and examples
+
+- Fixed: Context Graphs decision tracking bugs and added comprehensive test coverage (PR #315 by @KaifAhmad1)
+  - Fixed empty/None decision ID handling in ContextGraph.add_decision()
+  - Fixed None metadata handling to prevent TypeError
+  - Fixed causal chain depth logic and node exclusion
+  - Fixed nonexistent node handling in add_causal_relationship()
+  - Added missing properties field in to_dict serialization
+  - Added missing from_dict method for graph deserialization
+  - Fixed precedent search direction in find_precedents()
+  - Fixed UUID generation logic in all decision models
+  - Added comprehensive test suite with 9 tests covering all features
+  - All 71 context tests now passing (100% success rate)
+
+- Fixed: PolicyEngine latest version selection on ContextGraph; AgentContext fallback robustness and secure logging (PR #TBD by @KaifAhmad1)
+- Tests: Added ContextGraph fallback and AgentContext smoke tests; full suite passing
+
+  - **Apache AGE Backend Security Fixes** (PR #311 by @Sameer6305, fixes by @KaifAhmad1):
+  - Added AgeStore class with GraphStore API compatibility
+  - Fixed SQL injection vulnerabilities with input validation
+  - Added psycopg2-binary dependency and migration guide
+  - Fixed parameter replacement and test mock leakage
+  - Enhanced error handling and Unicode display issues
+
+- **Context Engineering Enhancement** (PR #307 by @KaifAhmad1):
+  - Comprehensive decision tracking system with full lifecycle management (record → analyze → query → precedent → influence)
+  - Advanced KG algorithm integration: centrality analysis, community detection, node embeddings with ContextGraph
+  - Enhanced AgentContext with granular feature flags for decision tracking, KG algorithms, and vector store features
+  - PolicyException model replacing conflicting Exception name for meaningful business domain modeling
+  - GraphStore validation preventing runtime failures with explicit capability checking
+  - Hybrid search combining semantic, structural, and category similarity with configurable weights
+  - Decision influence analysis with centrality measures and causal chain tracking
+  - Policy management with versioning, compliance checking, and exception handling
+  - Production-ready architecture with audit trails, security, and scalability features
+  - 9 critical bug fixes: logging, security, audit trails, API compatibility, Cypher queries, centrality access, validation, naming
+  - Comprehensive documentation with usage guides, production examples, and API references
+  - 100% test coverage with all validation tests passing (9/9 tests)
+  - Enterprise-grade features for financial services, healthcare, legal, and business domains
+  - Complete backward compatibility with existing semantica components
+  - Performance optimizations: caching, indexing, and efficient graph operations
+
+- **Added PgVector Store Support** (PR #303 by @Sameer6305, @KaifAhmad1):
+  - Native PostgreSQL vector storage using pgvector extension with full integration
+  - Multiple distance metrics: cosine, L2/Euclidean, inner product with automatic score normalization
+  - Advanced indexing: HNSW and IVFFlat for approximate nearest neighbor search with tunable parameters
+  - JSONB metadata storage with flexible filtering capabilities and batch operations
+  - Connection pooling support with psycopg3/psycopg2 fallback and efficient resource management
+  - Comprehensive VectorStore integration with backend delegation and unified API
+  - Idempotent index creation and table management with safe migration support
+  - Production-ready security: SQL injection protection with psycopg_sql.SQL() and input validation
+  - Performance optimizations: UUID4-based IDs, batch executemany operations, connection pooling
+  - Full backward compatibility with existing vector store implementations
+  - 36+ comprehensive test cases with Docker integration and dependency skipping
+  - Complete documentation with setup guides, examples, and performance tuning
+  - CI/CD integration: resolved benchmark compatibility and fixed documentation links
+
+- **Improved Vector Store for Decision Tracking** (PR #293 by @KaifAhmad1):
+  - Comprehensive decision tracking capabilities with hybrid search combining semantic and structural embeddings
+  - New DecisionEmbeddingPipeline for generating semantic and structural embeddings with KG algorithm integration
+  - HybridSimilarityCalculator with configurable weights (semantic: 0.7, structural: 0.3)
+  - DecisionContext high-level interface for decision management with explainable AI features
+  - ContextRetriever with hybrid precedent search and multi-hop reasoning
+  - User-friendly convenience API: quick_decision(), find_precedents(), explain(), similar_to(), batch_decisions(), filter_decisions()
+  - Knowledge Graph algorithm integration: Node2Vec, PathFinder, CommunityDetector, CentralityCalculator, SimilarityCalculator, ConnectivityAnalyzer
+  - Explainable AI with path tracing, confidence scoring, and comprehensive decision explanations
+  - Performance optimizations: 0.028s per decision processing, 0.031s search performance, ~0.8KB per decision memory usage
+  - 100% backward compatibility maintained with existing VectorStore functionality
+  - 34+ comprehensive tests covering all functionality including end-to-end scenarios and performance benchmarks
+  - Real-world validation examples for banking and insurance domains
+  - Documentation with clear imports, examples, and API references
+
+- **Improved Graph Algorithms in KG Module** (PR #292 by @KaifAhmad1):
+  - Complete algorithm suite with 30+ graph algorithms across 7 categories
+  - Node Embeddings: Node2Vec, DeepWalk, Word2Vec for structural similarity analysis
+  - Similarity Analysis: Cosine, Euclidean, Manhattan, Correlation metrics with batch processing
+  - Path Finding: Dijkstra, A*, BFS, K-shortest paths for route and network analysis
+  - Link Prediction: Preferential attachment, Jaccard, Adamic-Adar for network completion
+  - Centrality Analysis: Degree, Betweenness, Closeness, PageRank for importance ranking
+  - Community Detection: Louvain, Leiden, Label propagation for clustering analysis
+  - Connectivity Analysis: Components, bridges, density for network robustness
+  - Unified provenance tracking system with GraphBuilderWithProvenance and AlgorithmTrackerWithProvenance
+  - Complete execution tracking with metadata, timestamps, and reproducibility IDs
+  - Comprehensive test coverage with 5 test suites and 40+ test methods
+  - Professional documentation overhaul for all modules and reference documentation
+  - Enterprise-ready functionality with error handling and NetworkX compatibility
+  - Performance optimizations with sparse matrix operations and batch processing
+  - Full backward compatibility maintained with gradual migration support
+
+- **Improved Security Configuration with Dependabot**:
+  - Configured bi-weekly security updates with manual review by @KaifAhmad1
+  - Implemented automated security scans (Monday & Thursday at 7 AM IST) with Bandit, Safety, Semgrep
+  - Added security-critical package grouping (cryptography, requests, urllib3, certifi, pyopenssl)
+  - Enterprise-grade security with audit trail, compliance features, and zero auto-merge
+  - Optimized IST timezone scheduling (Security scans: 7 AM IST, PRs: 9 AM IST)
+  - Aligned with new Dependabot features: open-source proxy support, smart dependency grouping for Snowflake/Arrow/benchmark features, private registry support, semantic commit prefixes, and latest GitHub security best practices
+
+- **ResourceScheduler Deadlock Fix and Performance Improvements** (PR #299, #301 by @d4ndr4d3, @KaifAhmad1):
+  - Fixed critical deadlock in ResourceScheduler by replacing `threading.Lock()` with `threading.RLock()`
+  - Resolved nested lock acquisition issue in `allocate_resources()` → `allocate_cpu/memory/gpu()` calls
+  - Added allocation validation with `ValidationError` when no resources can be allocated
+  - Improved performance by moving progress tracking updates outside lock scope
+  - Implemented comprehensive resource cleanup on allocation failures to prevent leaks
+  - Added complete regression test suite (6 tests) for deadlock prevention and edge cases
+  - Improved error handling and documentation for better operator visibility
+  - Zero breaking changes, maintains thread safety and backward compatibility
+
+## [0.2.7] - 2026-02-09
+
+### Added / Changed
+
+- **Snowflake Connector for Data Ingestion** (PR #276 by @Sameer6305):
+  - Native Snowflake connector with multi-authentication (password, OAuth, key-pair, SSO)
+  - Table and query ingestion with pagination, schema introspection, batch processing
+  - SQL injection prevention via identifier escaping, OAuth token validation
+  - Progress tracking integration, context manager support, document export
+  - 24 comprehensive unit tests with mocking, complete documentation and examples
+  - Added as optional dependency `db-snowflake` with snowflake-connector-python>=3.0.0
+
+- **Apache Arrow Export Support** (PR #273 by @Sameer6305):
+  - Added Apache Arrow exporter with explicit schemas, entity/relationship export, compression support
+  - Integrated with export module and method registry, Pandas/DuckDB compatible
+  - 20 unit tests + 1 integration test, complete documentation with examples
+
+- **Comprehensive Benchmark Suite with Regression CLI** (PR #289 by @ZohaibHassan16, @KaifAhmad1):
+  - 137+ benchmarks across all 10 Semantica modules (Input, Core, Storage, Context, QA, Ontology, etc.)
+  - Environment-agnostic design with robust mocking system for CI/CD compatibility
+  - Statistical regression detection using Z-score analysis with configurable thresholds
+  - Automated performance auditing via GitHub Actions workflow
+  - Comprehensive documentation suite (benchmarks.md, architecture guides, usage examples)
+  - Zero breaking changes, production-ready with ultra-fast text processing (>10,000 ops/s)
+  - Added benchmark runner CLI: `python benchmarks/benchmark_runner.py`
+
+## [0.2.6] - 2026-02-03
+
+### Added / Changed
+
+- **W3C PROV-O Compliant Provenance Tracking** (#254, #246):
+  - Comprehensive provenance tracking system with W3C PROV-O compliance across all 17 Semantica modules
+  - **Core Module**: `ProvenanceManager`, W3C PROV-O schemas, storage backends (InMemory, SQLite), SHA-256 integrity verification
+  - **Module Integrations**: Semantic Extract, LLMs (Groq, OpenAI, HuggingFace, LiteLLM), Pipeline, Context, Ingest, Embeddings, Graph/Vector/Triplet stores, Reasoning, Conflicts, Deduplication, Export, Parse, Normalize, Ontology, Visualization
+  - **Features**: Complete lineage tracking (Document → Chunk → Entity → Relationship → Graph), LLM tracking (tokens, costs, latency), source tracking, bridge axioms for domain transformations
+  - **Compliance Infrastructure**: W3C PROV-O, FDA 21 CFR Part 11, SOX, HIPAA, TNFD
+  - **Testing**: 237 tests covering core functionality, all 17 module integrations, edge cases, backward compatibility
+  - **Design**: Opt-in with `provenance=False` by default, zero breaking changes, no new dependencies
+  - Contributed by @KaifAhmad1
+
+- **Enhanced Change Management Module** (#248, #243):
+  - Enterprise-grade version control for knowledge graphs and ontologies with persistent storage and audit trails
+  - **Core Classes**: `TemporalVersionManager` (KG versioning), `OntologyVersionManager` (ontology versioning), `ChangeLogEntry` (metadata)
+  - **Storage**: SQLite (persistent) and in-memory backends with thread-safe operations
+  - **Features**: SHA-256 checksums, detailed entity/relationship diffs, structural ontology comparison, email validation
+  - **Compliance Infrastructure**: HIPAA, SOX, FDA 21 CFR Part 11 with immutable audit trails
+  - **Testing**: 104 tests (100% pass) - unit, integration, compliance, performance, edge cases
+  - **Performance**: 17.6ms for 10k entities, 510+ ops/sec concurrent, handles 5k+ entity graphs
+  - **Migration**: Backward compatible, simplified class names, zero external dependencies
+  - Contributed by @KaifAhmad1
+
+- CSV Ingestion Enhancements (PR #244 by @saloni0318)
+  - Auto-detect CSV encoding (chardet) and delimiter (csv.Sniffer)
+  - Tolerant decoding and malformed-row handling (`on_bad_lines='warn'`)
+  - Optional chunked reading for large files; metadata tracks detected values
+  - Expanded unit tests covering delimiters, quoted/multiline fields, header overrides, chunks, and NaN preservation
+
+- Tests: Comprehensive units for TextNormalizer (PR #242 by @ZohaibHassan16)
+  - Added focused test coverage for TextNormalizer behavior across inputs
+
+- Tests: Register integration mark and tidy ingest test warnings (PR #241 by @KaifAhmad1)
+  - Introduced integration test marker and reduced noisy warnings in ingest tests
+
+- **Ingest Unit Tests** (#239, #232):
+  - Comprehensive unit tests for ingestion modules (file, web, and feed ingestors)
+  - **Coverage**: File scanning (local/cloud S3/GCS/Azure), web ingestion (URL/sitemap/robots.txt), RSS/Atom feed parsing
+  - **Testing**: 998 lines of test code with mocked external dependencies for fast, isolated execution
+  - **Results**: file_ingestor (86%), web_ingestor (86%), feed_ingestor (80%) coverage
+  - Covers happy paths, edge cases, and error handling
+  - Contributed by @Mohammed2372
+
+### Fixed
+
+- **Temperature Compatibility Fix** (#256, #252):
+  - Fixed hardcoded `temperature=0.3` that broke compatibility with models requiring specific temperature values (e.g., gpt-5-mini)
+  - Added `_add_if_set` helper method to `BaseProvider` that only passes parameters when explicitly set
+  - When `temperature=None`, parameter is omitted allowing APIs to use model defaults
+  - Updated all 5 providers: OpenAI, Groq, Gemini, Ollama, DeepSeek
+  - Reduced code by ~85 lines with cleaner parameter handling
+  - Comprehensive test coverage added (10 temperature tests, all passing)
+  - Backward compatible - no breaking changes
+  - Contributed by @F0rt1s and @IGES-Institut
+
+- **JenaStore Empty Graph Bug** (#257, #258):
+  - Fixed `ProcessingError: Graph not initialized` when operating on empty (but initialized) graphs
+  - Replaced implicit `if not self.graph:` checks with explicit `if self.graph is None:` validation in 5 methods (`add_triplets`, `get_triplets`, `delete_triplet`, `execute_sparql`, `serialize`)
+  - Properly distinguishes `None` (uninitialized) from empty graphs (initialized with 0 triplets)
+  - Unblocks benchmarking suite, fresh deployments, and testing workflows
+  - Contributed by @ZohaibHassan16
+
+## [0.2.5] - 2026-01-27
+
+### Added
+- **Pinecone Vector Store Support**:
+    - Implemented native Pinecone support (`PineconeStore`) with full CRUD capabilities.
+    - Added support for serverless and pod-based indexes, namespaces, and metadata filtering.
+    - Integrated with `VectorStore` unified interface and registry.
+    - (Closes #219, Resolves #220)
+- **Configurable LLM Retry Logic**:
+    - Exposed `max_retries` parameter in `NERExtractor`, `RelationExtractor`, `TripletExtractor` and low-level extraction methods (`extract_entities_llm`, `extract_relations_llm`, `extract_triplets_llm`).
+    - Defaults to 3 retries to prevent infinite loops during JSON validation failures or API timeouts.
+    - Propagated retry configuration through chunked processing helpers to ensure consistent behavior for long documents.
+    - Updated `03_Earnings_Call_Analysis.ipynb` to use `max_retries=3` by default.
+
+### Added
+- **Bring Your Own Model (BYOM) Support**:
+    - Enabled full support for custom Hugging Face models in `NERExtractor`, `RelationExtractor`, and `TripletExtractor`.
+    - Added support for custom tokenizers in `HuggingFaceModelLoader` to handle models with non-standard tokenization requirements.
+    - Implemented robust fallback logic for model selection: runtime options (`extract(model=...)`) now correctly override configuration defaults.
+- **Enhanced NER Implementation**:
+    - Added configurable aggregation strategies (`simple`, `first`, `average`, `max`) to `extract_entities_huggingface` for better sub-word token handling.
+    - Implemented robust IOB/BILOU parsing to reconstruct entities from raw model outputs when structured output is unavailable.
+    - Added confidence scoring for aggregated entities.
+- **Relation Extraction Improvements**:
+    - Implemented standard entity marker technique (wrapping subject/object with `<subj>`, `<obj>` tags) in `extract_relations_huggingface` for compatibility with sequence classification models.
+    - Added structured output parsing to convert raw model predictions into validated `Relation` objects.
+- **Triplet Extraction Completion**:
+    - Added specialized parsing for Seq2Seq models (e.g., REBEL) in `extract_triplets_huggingface` to generate structured triplets directly from text.
+    - Implemented post-processing logic to clean and validate generated triplets.
+
+### Fixed
+- **LLM Extraction Stability**:
+    - Fixed infinite retry loops in `BaseProvider` by strictly enforcing `max_retries` limit during structured output generation.
+    - Resolved stuck execution in earnings call analysis notebooks when using smaller models (e.g., Llama 3 8B) that frequently produce invalid JSON.
+- **Model Parameter Precedence**:
+    - Fixed issue where configuration defaults took precedence over runtime arguments in Hugging Face extractors. Runtime options now correctly override config values.
+- **Import Handling**:
+    - Fixed circular import issues in test suites by implementing robust mocking strategies.
+
+## [0.2.4] - 2026-01-22
+
+### Added
+- **Ontology Ingestion Module**:
+    - Implemented `OntologyIngestor` in `semantica.ingest` for parsing RDF/OWL files (Turtle, RDF/XML, JSON-LD, N3) into standardized `OntologyData` objects.
+    - Added `ingest_ontology` convenience function and integrated it into the unified `ingest(source_type="ontology")` interface.
+    - Added recursive directory scanning support for batch ontology ingestion.
+    - Exposed ingestion tools in `semantica.ontology` for better discoverability.
+    - Added `OntologyData` dataclass for consistent metadata handling (source path, format, timestamps).
+- **Documentation**:
+    - **Ontology Usage Guide**: Updated `ontology_usage.md` with comprehensive examples for single-file and directory ingestion.
+    - **API Reference**: Updated `ontology.md` with `OntologyIngestor` class documentation and method details.
+- **Tests**:
+    - **Comprehensive Test Suite**: Added `tests/ingest/test_ontology_ingestor.py` covering all supported formats, error handling, and unified interface integration.
+    - **Demo Script**: Added `examples/demo_ontology_ingest.py` for end-to-end usage demonstration.
+
+## [0.2.3] - 2026-01-20
+
+### Fixed
+- **LLM Relation Extraction Parsing**:
+    - Fixed relation extraction returning zero relations despite successful API calls to Groq and other providers
+    - Normalized typed responses from instructor/OpenAI/Groq to consistent dict format before parsing
+    - Added structured JSON fallback when typed generation yields zero relations to avoid silent empty outputs
+    - Removed acceptance of extra kwargs (`max_tokens`, `max_entities_prompt`) from relation extraction internals
+    - Filtered kwargs passed to provider LLM calls to only `temperature` and `verbose`
+- **API Parameter Handling**:
+    - Limited kwargs forwarded in chunked extraction helper to prevent parameter leakage
+    - Ensured minimal, safe parameters are passed to provider calls
+- **Pipeline Circular Import (Issues #192, #193)**:
+    - Fixed circular import between `pipeline_builder` and `pipeline_validator` triggered during `semantica.pipeline` import
+    - Lazy-loaded `PipelineValidator` inside `PipelineBuilder.__init__` and guarded type hints with `TYPE_CHECKING`
+    - Ensured `from semantica.deduplication import DuplicateDetector` no longer fails even when pipeline module is imported
+- **JupyterLab Progress Output (Issue #181)**:
+    - Added `SEMANTICA_DISABLE_JUPYTER_PROGRESS` environment variable to disable rich Jupyter/Colab progress tables
+    - When enabled, progress falls back to console-style output, preventing infinite scrolling and JupyterLab out-of-memory errors
+
+### Added
+- **Comprehensive Test Suite**:
+-    - Added unit tests (`tests/test_relations_llm.py`) with mocked LLM provider covering both typed and structured response paths
+-    - Added integration tests (`tests/integration/test_relations_groq.py`) for real Groq API calls with environment variable API key
+-    - Tests validate relation extraction completion and result parsing across different response formats
+- **Amazon Neptune Dev Environment**:
+-    - Added CloudFormation template (`cookbook/introduction/neptune-setup.yaml`) to provision a dev Neptune cluster with public endpoint and IAM auth enabled
+-    - Documented deployment, cost estimates, and IAM User vs IAM Role best practices in `cookbook/introduction/21_Amazon_Neptune_Store.ipynb`
+-    - Added `cfn-lint` to `.pre-commit-config.yaml` for validating CloudFormation templates while excluding `neptune-setup.yaml` from generic YAML linters
+- **Vector Store High-Performance Ingestion**:
+-    - Added `VectorStore.add_documents` for high-throughput ingestion with automatic embedding generation, batching, and parallel processing
+-    - Added `VectorStore.embed_batch` helper for generating embeddings for lists of texts without immediately storing them
+-    - Enabled default parallel ingestion in `VectorStore` with `max_workers=6` for common workloads
+-    - Added dedicated documentation page `docs/vector_store_usage.md` describing high-performance vector store usage and configuration
+-    - Added `tests/vector_store/test_vector_store_parallel.py` covering parallel vs sequential performance, error handling, and edge cases for `add_documents` and `embed_batch`
+
+### Changed
+- **Relation Extraction API**:
+-    - Simplified parameter interface by removing unused kwargs that were previously ignored
+-    - Improved error handling and verbose logging for debugging relation extraction issues
+-    - Enhanced robustness of post-response parsing across different LLM providers
+- **Vector Store Defaults and Examples**:
+-    - Standardized `VectorStore` default concurrency to `max_workers=6` for parallel ingestion
+-    - Updated vector store reference documentation and usage guides to rely on implicit defaults instead of requiring manual `max_workers` configuration in examples
+
+
+## [0.2.2] - 2026-01-15
+
+### Added
+- **Parallel Extraction Engine**:
+    - Implemented high-throughput parallel batch processing across all core extractors (`NERExtractor`, `RelationExtractor`, `TripletExtractor`, `EventDetector`, `SemanticNetworkExtractor`) using `concurrent.futures.ThreadPoolExecutor`.
+    - Added `max_workers` configuration parameter (default: 1) to all extractor `extract()` methods, allowing users to tune concurrency based on available CPU cores or API rate limits.
+    - **Parallel Chunking**: Implemented parallel processing for large document chunking in `_extract_entities_chunked` and `_extract_relations_chunked`, significantly reducing latency for long-form text analysis.
+    - **Thread-Safe Progress Tracking**: Enhanced `ProgressTracker` to handle concurrent updates from multiple threads without race conditions during batch processing.
+- **Semantic Extract Performance & Regression**:
+    - Added edge-case regression suite covering max worker defaults, LLM prompt entity filtering, and extractor reuse.
+    - Added a runnable real-use-case benchmark script for batch latency across `NERExtractor`, `RelationExtractor`, `TripletExtractor`, `EventDetector`, `SemanticAnalyzer`, and `SemanticNetworkExtractor`.
+    - Added Groq LLM smoke tests that exercise LLM-based entities/relations/triplets when `GROQ_API_KEY` is available via environment configuration.
+
+### Security
+- **Credential Sanitization**:
+    - Removed hardcoded API keys from 8 cookbook notebooks to prevent secret leakage.
+    - Enforced environment variable usage for `GROQ_API_KEY` across all examples.
+- **Secure Caching**:
+    - Updated `ExtractionCache` to exclude sensitive parameters (e.g., `api_key`, `token`, `password`) from cache key generation, preventing secret leakage and enabling safe cache sharing.
+    - Upgraded cache key hashing algorithm from MD5 to **SHA-256** for enhanced collision resistance and security.
+
+### Changed
+- **Gemini SDK Migration**:
+    - Migrated `GeminiProvider` to use the new `google-genai` SDK (v0.1.0+) to address deprecation warnings.
+    - Implemented graceful fallback to `google.generativeai` for backward compatibility.
+- **Dependency Resolution**:
+    - Pinned `opentelemetry-api` and `opentelemetry-sdk` to `1.37.0` to resolve pip conflicts.
+    - Updated `protobuf` and `grpcio` constraints for better stability.
+- **Entity Filtering Scope**:
+    - Removed entity filtering from non-LLM extraction flows to avoid accuracy regressions.
+    - Applied entity downselection only to LLM relation prompt construction, while matching returned entities against the full original entity list.
+- **Batch Concurrency Defaults**:
+    - Standardized `max_workers` defaulting across `semantic_extract` and tuned for low-latency: ML-backed methods default to single-worker, while pattern/regex/rules/LLM/huggingface methods use a higher parallelism default capped by CPU.
+    - Raised the global `optimization.max_workers` default to 8 for better throughput on batch workloads.
+
+### Performance
+- **Bottleneck Optimization (GitHub Issue #186)**:
+    - **Resolved Bottleneck #1 (Sequential Processing)**: Replaced sequential `for` loops with parallel execution for both document-level batches and intra-document chunks.
+    - **Performance Gains**: Achieved **~1.89x speedup** in real-world extraction scenarios (tested with Groq `llama-3.3-70b-versatile` on standard datasets).
+    - **Initialization Optimization**: Refactored test suite to use class-level `setUpClass` for LLM provider initialization, eliminating redundant API client creation overhead.
+- **Low-Latency Entity Matching**:
+    - Avoided heavyweight embedding stack imports on common matches by improving fast matching heuristics and short-circuiting before embedding similarity.
+    - Optimized entity matching to prioritize exact/substring/word-boundary matches and only fall back to embedding similarity when needed, reducing CPU overhead in LLM relation/triplet mapping.
+
+
 ## [0.2.1] - 2026-01-12
 
 ### Fixed
@@ -16,6 +901,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - Fixed `AttributeError` in provider integration by ensuring consistent parameter passing via `**kwargs`.
 - **Constraint Relaxations**:
     - Removed hardcoded `max_length` constraints from `Entity`, `Relation`, and `Triplet` classes to support long-form semantic extraction (e.g., long descriptions or names).
+- Fixed orchestrator lazy property initialization and configuration normalization logic in `Orchestrator`.
+- Resolved `AssertionError` in orchestrator tests by aligning test mocks with production component usage.
+- Fixed dependency compatibility issues by pinning `protobuf>=5.29.1,<7.0` and `grpcio>=1.71.2`.
+- Added missing dependencies `GitPython` and `chardet` to `pyproject.toml`.
+- Verified and aligned `FileObject.text` property usage in GraphRAG notebooks for consistent content decoding.
 
 ### Changed
 - **Chunking Defaults**:
@@ -218,4 +1108,3 @@ When breaking changes are introduced, migration guides will be provided in the r
 ---
 
 For detailed release notes, see [GitHub Releases](https://github.com/Hawksight-AI/semantica/releases).
-

CONTRIBUTING.md

@@ -1,306 +1,266 @@
 # Contributing to Semantica
 
-Thank you for your interest in contributing to Semantica! This document provides guidelines and instructions for contributing to the project.
+Thank you for your interest in contributing! Every contribution, no matter how small, is valuable. 🎉
 
-## Table of Contents
+⭐ **Give us a Star** • 🍴 **[Fork Semantica](https://github.com/Hawksight-AI/semantica/fork)** • 💬 **Join our [Discord](https://discord.gg/sV34vps5hH)**
 
-- [Code of Conduct](#code-of-conduct)
-- [Getting Started](#getting-started)
-- [Development Setup](#development-setup)
-- [Code Style Guidelines](#code-style-guidelines)
-- [Testing Requirements](#testing-requirements)
-- [Commit Message Conventions](#commit-message-conventions)
-- [Pull Request Process](#pull-request-process)
-- [Documentation Standards](#documentation-standards)
-- [Types of Contributions](#types-of-contributions)
-- [Getting Help](#getting-help)
+> **New to contributing?** Start with a [`good first issue`](https://github.com/Hawksight-AI/semantica/labels/good%20first%20issue) or join our [Discord](https://discord.gg/sV34vps5hH) community.
 
-## Code of Conduct
+---
 
-This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.
+## 🚀 Quick Start
 
-## Getting Started
+1. Find a [`good first issue`](https://github.com/Hawksight-AI/semantica/labels/good%20first%20issue)
+2. [Fork Semantica](https://github.com/Hawksight-AI/semantica/fork) & clone the repository
+3. Make your changes
+4. Submit a pull request!
 
-1. **Fork the repository** on GitHub
-2. **Clone your fork** locally:
-   ```bash
-   git clone https://github.com/your-username/semantica.git
-   cd semantica
-   ```
-3. **Add the upstream remote**:
-   ```bash
-   git remote add upstream https://github.com/Hawksight-AI/semantica.git
-   ```
+**Need help?** Join [Discord](https://discord.gg/sV34vps5hH) or [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
 
-## Development Setup
+---
 
-### Prerequisites
+## 🎯 Ways to Contribute
 
-- Python 3.8 or higher (3.9+ recommended)
-- pip package manager
-- Git
+### 💻 Code
 
-### Installation
+**What you can do:**
+- Fix bugs
+- Add new features
+- Improve code quality (add type hints, docstrings, improve error messages)
+- Optimize performance
 
-1. **Create a virtual environment** (recommended):
-   ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   ```
+**Where:** `semantica/` directory
 
-2. **Install the project in editable mode with dev dependencies**:
-   ```bash
-   pip install -e ".[dev]"
-   ```
+**Good first issues:** Add docstrings, type hints, or improve error messages
 
-3. **Install pre-commit hooks**:
-   ```bash
-   pre-commit install
-   ```
+---
 
-### Verify Installation
+### 📝 Documentation
+
+**What you can do:**
+- Fix typos and grammar errors
+- Improve clarity and readability
+- Add code examples and tutorials
+- Create new cookbook notebooks
+- Improve API documentation (docstrings)
+- Create troubleshooting guides
+- Update installation instructions
+- Add missing documentation
+
+**Where:** `README.md`, `docs/`, `cookbook/`, docstrings in code
+
+**Good first issues:** Fix typos, add examples, create cookbook tutorials, improve docstrings
+
+**Documentation formatting:**
+- Use clear, concise language
+- Include code examples where helpful
+- Follow markdown best practices
+- Use proper headings hierarchy
+- Add links to related sections
+- Include screenshots for UI-related docs
+
+---
+
+### 🧪 Testing
+
+**What you can do:**
+- Add unit tests
+- Improve test coverage
+- Add integration tests
+
+**Where:** `tests/` directory
+
+**Good first issues:** Add tests for specific functions or classes
+
+---
+
+### 🐛 Bug Reports
+
+**What:** Report bugs you find
+
+**How:** Use the [bug report template](https://github.com/Hawksight-AI/semantica/issues/new?template=bug_report.md)
+
+**Include:** Description, steps to reproduce, expected vs actual behavior, environment details
+
+---
+
+### 💡 Feature Requests
+
+**What:** Suggest new features or improvements
+
+**How:** Use the [feature request template](https://github.com/Hawksight-AI/semantica/issues/new?template=feature_request.md)
+
+**Include:** Problem statement, proposed solution, use cases
+
+---
+
+### 🎨 Cookbook & Examples
+
+**What:** Create tutorials and examples
+
+**Where:** `cookbook/` directory
+
+**Examples:** Create new notebooks, add examples, improve existing tutorials
+
+---
+
+### 💬 Community Support
+
+**What:** Help others in the community
+
+**Where:** [Discord](https://discord.gg/sV34vps5hH), [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)
+
+**Examples:** Answer questions, review PRs, share your projects
+
+---
+
+### 🎓 Educational Content
+
+**What:** Create educational materials
+
+**Examples:** Blog posts, video tutorials, talks, workshops, case studies
+
+---
+
+### 🔧 Other Contributions
+
+- **Design & Graphics:** Logos, diagrams, visualizations
+- **Tools & Integrations:** CLI tools, integrations with other frameworks
+- **Infrastructure:** CI/CD improvements, Docker optimization
+- **Security:** Report security vulnerabilities (privately)
+
+---
+
+## 📋 Getting Started
+
+### 1. Fork & Clone
+
+First, [fork Semantica](https://github.com/Hawksight-AI/semantica/fork) on GitHub, then:
 
 ```bash
-python -c "import semantica; print(semantica.__version__)"
-pytest --version
-black --version
+git clone https://github.com/your-username/semantica.git
+cd semantica
+git remote add upstream https://github.com/Hawksight-AI/semantica.git
 ```
 
-## Code Style Guidelines
-
-We use several tools to maintain code quality and consistency:
-
-### Formatting
-
-- **Black**: Code formatting (line length: 88)
-  ```bash
-  black semantica/
-  ```
-
-- **isort**: Import sorting
-  ```bash
-  isort semantica/
-  ```
-
-### Linting
-
-- **flake8**: Style guide enforcement
-  ```bash
-  flake8 semantica/
-  ```
-
-- **mypy**: Static type checking
-  ```bash
-  mypy semantica/
-  ```
-
-### Running All Checks
+### 2. Set Up Environment
 
 ```bash
-# Format code
-black semantica/ tests/
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
 
-# Sort imports
-isort semantica/ tests/
+# Install dev dependencies
+pip install -e ".[dev]"
 
-# Lint
-flake8 semantica/ tests/
-
-# Type check
-mypy semantica/
+# Install pre-commit hooks (optional)
+pre-commit install
 ```
 
-Or use pre-commit hooks (automatically runs on commit):
-```bash
-pre-commit run --all-files
-```
-
-## Testing Requirements
-
-### Running Tests
+### 3. Create Branch
 
 ```bash
-# Run all tests
-pytest
-
-# Run with coverage
-pytest --cov=semantica --cov-report=html
-
-# Run specific test file
-pytest tests/test_specific.py
-
-# Run with verbose output
-pytest -v
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/bug-description
 ```
 
-### Test Coverage
+### 4. Make Changes
 
-- Minimum coverage: **80%**
-- Critical modules: **90%+**
-- Coverage reports are generated in `htmlcov/`
+- Follow code style (see below)
+- Add tests for new features
+- Update documentation
 
-### Writing Tests
+### 5. Run Checks
 
-- Follow pytest conventions
-- Use descriptive test names
-- Include docstrings for complex tests
-- Test both success and failure cases
-- Use fixtures for common setup
-
-Example:
-```python
-def test_entity_extraction():
-    """Test basic entity extraction functionality."""
-    from semantica.semantic_extract import NamedEntityRecognizer
-    
-    ner = NamedEntityRecognizer()
-    entities = ner.extract("Apple Inc. was founded by Steve Jobs.")
-    
-    assert len(entities) > 0
-    assert any(e.text == "Apple Inc." for e in entities)
+```bash
+pytest                          # Run tests
+black semantica/ tests/        # Format code
+isort semantica/ tests/         # Sort imports
+flake8 semantica/ tests/        # Lint
 ```
 
-## Commit Message Conventions
+Or use pre-commit hooks: `pre-commit run --all-files`
 
-We follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
+### 6. Commit & Push
 
-### Format
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
+```bash
+git commit -m "feat(module): add new feature"
+git push origin feature/your-feature-name
 ```
 
-### Types
+Then create a pull request on GitHub!
 
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation changes
-- `style`: Code style changes (formatting, etc.)
-- `refactor`: Code refactoring
-- `test`: Adding or updating tests
-- `chore`: Maintenance tasks
-- `perf`: Performance improvements
-- `ci`: CI/CD changes
+---
 
-### Examples
+## 📐 Code Style
+
+We use automated tools:
+
+| Tool     | Purpose                    | Command                    |
+|----------|----------------------------|----------------------------|
+| **Black** | Code formatting            | `black semantica/ tests/` |
+| **isort** | Import sorting             | `isort semantica/ tests/` |
+| **flake8** | Style enforcement          | `flake8 semantica/ tests/` |
+| **mypy** | Type checking              | `mypy semantica/`          |
+
+**Run all:** `black semantica/ tests/ && isort semantica/ tests/ && flake8 semantica/ tests/ && mypy semantica/`
+
+---
+
+## 🧪 Testing
+
+```bash
+pytest                          # Run all tests
+pytest --cov=semantica         # With coverage
+pytest tests/test_file.py      # Specific file
+```
+
+**Coverage goal:** 80% minimum, 90%+ for critical modules
+
+---
+
+## 📝 Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
 
 ```
 feat(kg): add temporal graph support
-
-Add support for temporal knowledge graphs with version tracking
-and time-based queries.
-
-Closes #123
+fix(parse): handle empty PDF files
+docs(readme): add installation guide
+test(extract): add unit tests
 ```
 
-```
-fix(parse): handle empty PDF files gracefully
+**Types:** `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `style`, `chore`
 
-Previously, empty PDF files would cause a crash. Now they return
-an empty document with appropriate warnings.
+---
 
-Fixes #456
-```
+## ✅ PR Checklist
 
-## Pull Request Process
-
-### Before Submitting
-
-1. **Update your fork**:
-   ```bash
-   git fetch upstream
-   git checkout main
-   git merge upstream/main
-   ```
-
-2. **Create a feature branch**:
-   ```bash
-   git checkout -b feature/your-feature-name
-   # or
-   git checkout -b fix/bug-description
-   ```
-
-3. **Make your changes** and commit following our conventions
-
-4. **Run all checks**:
-   ```bash
-   pytest
-   black semantica/ tests/
-   isort semantica/ tests/
-   flake8 semantica/ tests/
-   mypy semantica/
-   ```
-
-5. **Push to your fork**:
-   ```bash
-   git push origin feature/your-feature-name
-   ```
-
-### PR Checklist
+Before submitting:
 
 - [ ] Code follows style guidelines
 - [ ] Tests pass locally
-- [ ] New tests added for new features
+- [ ] New tests added (if applicable)
 - [ ] Documentation updated
 - [ ] Commit messages follow conventions
 - [ ] No merge conflicts
-- [ ] PR description is clear and complete
 
-### PR Description Template
+---
 
-```markdown
-## Description
-Brief description of changes
+## 📖 Documentation Standards
 
-## Type of Change
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Breaking change
-- [ ] Documentation update
+### Code Documentation (Docstrings)
 
-## Related Issues
-Closes #123
-Related to #456
+**Format:** Use Google-style docstrings
 
-## Testing
-- [ ] Tests pass locally
-- [ ] Added new tests
-- [ ] Updated existing tests
-
-## Checklist
-- [ ] Code follows style guidelines
-- [ ] Self-review completed
-- [ ] Comments added for complex code
-- [ ] Documentation updated
-- [ ] No new warnings generated
-```
-
-## Documentation Standards
-
-### Code Documentation
-
-- Use Google-style docstrings
-- Include type hints
-- Document all public functions and classes
-- Include examples for complex functions
-
-Example:
 ```python
-def extract_entities(
-    text: str,
-    model: str = "transformer",
-    confidence_threshold: float = 0.7
-) -> List[Entity]:
+def extract_entities(text: str, model: str = "transformer") -> List[Entity]:
     """Extract named entities from text.
     
     Args:
         text: Input text to process
         model: NER model to use (default: "transformer")
-        confidence_threshold: Minimum confidence score (default: 0.7)
     
     Returns:
         List of extracted Entity objects
@@ -309,92 +269,98 @@ def extract_entities(
         ValueError: If text is empty or model is invalid
     
     Example:
-        >>> ner = NamedEntityRecognizer()
+        >>> from semantica.semantic_extract import NERExtractor
+        >>> ner = NERExtractor(method="ml", model="en_core_web_sm")
         >>> entities = ner.extract("Apple Inc. was founded in 1976.")
         >>> len(entities)
         2
     """
-    ...
 ```
 
-### Documentation Files
+### Markdown Documentation Formatting
 
-- Update relevant documentation in `docs/`
-- Add examples to cookbook if applicable
-- Update API reference if adding new public APIs
-- Keep README.md up to date
+**General Guidelines:**
+- Use clear headings (H1 for title, H2 for main sections, H3 for subsections)
+- Keep paragraphs short and focused
+- Use bullet points for lists
+- Add code blocks with syntax highlighting
+- Include links to related documentation
 
-## Types of Contributions
+**Code Blocks:**
+- Use triple backticks with language identifier: ` ```python `, ` ```bash `
+- Include comments in code examples
+- Show expected output when helpful
 
-### 💻 Code Contributions
+**Examples:**
 
-- **Bug Fixes**: Resolving issues reported in the issue tracker.
-- **New Features**: Implementing new capabilities (please discuss via an issue first!).
-- **Refactoring**: Improving code structure and maintainability without changing behavior.
-- **Algorithm Optimization**: Improving the efficiency of graph algorithms and vector search.
+```markdown
+## Section Title
 
-#### ⚡ Performance and Latency
-We deeply value efficiency. Contributions that make Semantica faster and lighter are highly appreciated!
+Brief introduction paragraph.
 
-- **Latency Reduction**: Optimize critical paths and RAG pipeline response times.
-- **Memory Optimization**: Reduce graph/vector processing memory footprint.
-- **Throughput**: Improve operations per second (bulk ingestion, parallel queries).
-- **Benchmarks**: Add performance benchmarks to track regressions.
-- **Async/Concurrency**: Enhance asynchronous execution and concurrency.
+### Subsection
 
-### 📚 Documentation Contributions
+- Bullet point 1
+- Bullet point 2
 
-- Fix typos and grammar
-- Improve clarity
-- Add examples
-- Create tutorials
-- Translate documentation
+**Code example:**
 
-### Testing Contributions
+```python
+from semantica import SomeClass
 
-- Add test coverage
-- Improve test quality
-- Add integration tests
-- Performance benchmarks
+instance = SomeClass()
+result = instance.method()
+```
 
-### Other Contributions
+**Note:** Additional context or warnings.
+```
 
-- Answer questions in discussions
-- Help with issues
-- Review pull requests
-- Share use cases
-- Report bugs
-- Suggest features
+**Best Practices:**
+- Start with an overview/introduction
+- Use consistent terminology
+- Include "See also" links
+- Add examples for complex concepts
+- Keep formatting consistent across docs
 
-## Getting Help
+---
 
-### Communication Channels
+## 🆘 Getting Help
 
-- **GitHub Discussions**: General questions and discussions
-- **GitHub Issues**: Bug reports and feature requests
-- **Discord**: Real-time chat and community support
+- 💬 [Discord](https://discord.gg/sV34vps5hH) - Real-time chat
+- 💭 [GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions) - Q&A
+- 🐛 [GitHub Issues](https://github.com/Hawksight-AI/semantica/issues) - Bug reports
 
-### Before Asking for Help
+**Before asking:** Check existing documentation, search issues/discussions, review cookbook examples
 
-1. Check existing documentation
-2. Search GitHub issues and discussions
-3. Review code examples in cookbook
-4. Check FAQ in documentation
+---
 
-### Asking Good Questions
+## 🏆 Recognition
 
-- Provide context and environment details
-- Include code examples
-- Show what you've tried
-- Include error messages and logs
-- Be specific about what you need
-
-## Recognition
-
-Contributors are recognized in:
+All contributors are recognized in:
 - [CONTRIBUTORS.md](CONTRIBUTORS.md)
 - GitHub contributors page
-- Release notes for significant contributions
+- Release notes
 
-Thank you for contributing to Semantica! 🎉
+We follow the [all-contributors](https://allcontributors.org) specification!
 
+---
+
+## 📜 Code of Conduct
+
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). Be respectful and inclusive.
+
+---
+
+## 📚 Resources
+
+- [README.md](README.md) - Project overview
+- [Cookbook](cookbook/) - Tutorials and examples
+- [Documentation](docs/) - Comprehensive guides
+
+---
+
+**Thank you for contributing!** 🚀
+
+Every contribution matters - whether it's a single line of code, a typo fix, a helpful answer, or a bug report. We appreciate you! 🙏
+
+⭐ **Give us a Star** • 🍴 **[Fork Semantica](https://github.com/Hawksight-AI/semantica/fork)** • 💬 **Join our [Discord](https://discord.gg/sV34vps5hH)**

CONTRIBUTORS.md

@@ -4,44 +4,31 @@ Thank you to all the people who have contributed to Semantica! 🎉
 
 This project follows the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!
 
-## How to Contribute
+⭐ **Give us a Star** • 🍴 **Fork us** • 💬 **Join our [Discord](https://discord.gg/sV34vps5hH)**
 
-We welcome contributions of all kinds! Whether you're:
-- Writing code
-- Improving documentation
-- Reporting bugs
-- Suggesting features
-- Answering questions
-- Reviewing pull requests
-- Sharing use cases
-- Creating examples
-
-All contributions are valuable and appreciated!
+---
 
 ## Contribution Types
 
+We recognize all types of contributions:
+
 - 💻 **Code**: Writing code, fixing bugs, implementing features
 - 📝 **Documentation**: Writing docs, tutorials, examples
+- 🧪 **Testing**: Writing tests, improving test coverage
 - 🐛 **Bug Reports**: Finding and reporting bugs
 - 💡 **Ideas**: Suggesting new features or improvements
 - 🎨 **Design**: UI/UX improvements, graphics, branding
-- 📖 **Examples**: Creating code examples and tutorials
-- 🔍 **Testing**: Writing tests, improving test coverage
-- 💬 **Answering Questions**: Helping others in discussions
-- 📢 **Talks**: Giving talks, presentations, workshops
-- 🌍 **Translation**: Translating documentation
+- 🎨 **Cookbook**: Creating tutorials and examples
+- 💬 **Community**: Answering questions, reviewing PRs
+- 🎓 **Education**: Blog posts, video tutorials, talks, workshops
 - 🔧 **Tools**: Creating tools, scripts, integrations
 - 📦 **Packaging**: Improving build, release, distribution
 - ⚠️ **Security**: Reporting security vulnerabilities
-- 🎓 **Education**: Teaching, mentoring, tutorials
-- 📹 **Video**: Creating video content, tutorials
-- 🎵 **Audio**: Podcasts, audio content
-- 📸 **Photography**: Screenshots, images
-- 🔬 **Research**: Research, analysis, studies
-- 💰 **Financial**: Sponsoring, funding
 - 🏗️ **Infrastructure**: CI/CD, hosting, infrastructure
 - 🚇 **Maintenance**: Maintenance, triage, project management
 
+---
+
 ## Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START -->
@@ -50,48 +37,78 @@ All contributions are valuable and appreciated!
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
+---
+
 ## Recognition
 
-### Top Contributors
+All contributors are recognized in:
 
-Contributors are recognized based on their contributions to the project. Recognition includes:
+- This contributors list
+- [GitHub contributors page](https://github.com/Hawksight-AI/semantica/graphs/contributors)
+- Release notes for significant contributions
+- Community appreciation
 
-- Listing in this file
-- GitHub contributor statistics
-- Special mentions in release notes
-- Featured showcases for significant contributions
-
-### Hall of Fame
-
-Special recognition for exceptional contributions:
-
-- **Coming soon** - We'll feature outstanding contributors here!
+---
 
 ## How to Add Yourself
 
-If you've contributed to Semantica and want to be added to this list:
+### Automatic Recognition
 
-1. **Automatic**: If you've made a commit, you'll appear in [GitHub's contributors graph](https://github.com/Hawksight-AI/semantica/graphs/contributors)
-2. **Manual**: Open a PR adding yourself to this file, or use the [@all-contributors bot](https://allcontributors.org/docs/en/bot/usage)
+If you've made a commit, you'll automatically appear in [GitHub's contributors graph](https://github.com/Hawksight-AI/semantica/graphs/contributors).
 
-Example:
-```markdown
-- [Your Name](https://github.com/yourusername) - 💻 📝 🐛
-```
+### Using All-Contributors Bot
 
-## All Contributors Bot
-
-We use the [all-contributors](https://allcontributors.org) bot to automatically recognize contributors. To add a contributor, comment on an issue or PR:
+Comment on any issue or PR with:
 
 ```
 @all-contributors please add @username for code, docs, bug
 ```
 
-## Thank You!
+**Examples:**
 
-Every contribution, no matter how small, helps make Semantica better. Thank you for being part of our community!
+```
+@all-contributors please add @johndoe for code
+@all-contributors please add @janedoe for docs, bug
+@all-contributors please add @devuser for code, test, maintenance
+```
+
+### Manual Addition
+
+Open a PR adding yourself to this file:
+
+```markdown
+- [Your Name](https://github.com/yourusername) - 💻 📝 🐛
+```
 
 ---
 
-**Want to contribute?** Check out our [Contributing Guide](CONTRIBUTING.md) to get started!
+## Contribution Type Codes
 
+When using the all-contributors bot, use these codes:
+
+- `code` - Code contributions
+- `doc` - Documentation
+- `test` - Testing
+- `bug` - Bug reports
+- `ideas` - Feature requests/ideas
+- `design` - Design work
+- `example` - Cookbook/examples
+- `question` - Answering questions
+- `talk` - Talks/presentations
+- `tool` - Tools/integrations
+- `packaging` - Packaging/distribution
+- `security` - Security reports
+- `infra` - Infrastructure
+- `maintenance` - Maintenance
+
+See [all-contributors specification](https://allcontributors.org/docs/en/emoji-key) for complete list.
+
+---
+
+## Thank You!
+
+Every contribution, no matter how small, helps make Semantica better. Thank you for being part of our community! 🙏
+
+**Want to contribute?** 
+
+⭐ Give us a Star • 🍴 [Fork us](https://github.com/Hawksight-AI/semantica/fork) • Check out our [Contributing Guide](CONTRIBUTING.md) to get started!

RELEASE.md

@@ -1,56 +0,0 @@
-# Release Process for Semantica
-
-This document outlines the steps to release a new version of the Semantica framework.
-
-## 1. Versioning Policy
-
-Semantica follows [Semantic Versioning (SemVer)](https://semver.org/).
-- **MAJOR** version for incompatible API changes.
-- **MINOR** version for functionality added in a backwards compatible manner.
-- **PATCH** version for backwards compatible bug fixes.
-
-## 2. Pre-release Checklist
-
-Before releasing, ensure:
-- [ ] All tests pass: `pytest`
-- [ ] Documentation is up to date in `docs/` and `MkDocs` config.
-- [ ] `CHANGELOG.md` is updated with the latest changes.
-- [ ] Version is updated in:
-  - `semantica/__init__.py`
-  - `pyproject.toml`
-  - `docs/citation.md` (BibTeX entry)
-
-## 3. Release Steps
-
-### Automated Release (Recommended)
-
-The project uses GitHub Actions for automated releases to PyPI.
-
-1. **Tag the commit**: Create a new git tag for the version (e.g., `v0.2.1`).
-   ```bash
-   git tag -a v0.2.1 -m "Release v0.2.1"
-   git push origin v0.2.1
-   ```
-2. **GitHub Action**: The `Release` workflow will automatically trigger, build the package, create a GitHub Release, and publish to PyPI using Trusted Publishing.
-
-### Manual Release
-
-If you need to release manually:
-
-1. **Build the package**:
-   ```bash
-   python -m build
-   ```
-2. **Verify the build**:
-   ```bash
-   twine check dist/*
-   ```
-3. **Upload to PyPI**:
-   ```bash
-   twine upload dist/*
-   ```
-
-## 4. Post-release
-
-- Verify the new version is available on [PyPI](https://pypi.org/project/semantica/).
-- Check the [GitHub Releases](https://github.com/your-org/semantica/releases) page for the new release notes.

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.

RELEASE_NOTES_v0.2.0.md

@@ -1,95 +0,0 @@
-# Semantica v0.2.0 Release Notes
-
-We are excited to announce the release of Semantica v0.2.0! This release brings major enhancements to graph database support, document parsing, extraction robustness, and provenance tracking.
-
-## 🚀 Highlights
-
-### Amazon Neptune Support
-- **Native Integration**: Added `AmazonNeptuneStore` for full integration with Amazon Neptune via Bolt and OpenCypher.
-- **Enterprise Security**: Implemented `NeptuneAuthTokenManager` for AWS IAM SigV4 signing with automatic token refresh.
-- **Resilience**: Added robust connection handling with retry logic and backoff for transient errors.
-
-### Docling Integration
-- **High-Fidelity Parsing**: New `DoclingParser` in `semantica.parse` leverages the Docling library for superior document understanding.
-- **Multi-Format Support**: Parse PDF, DOCX, PPTX, XLSX, HTML, and images with state-of-the-art table extraction.
-
-### Robust Extraction Fallbacks
-- **No More Empty Results**: Implemented a "ML/LLM -> Pattern -> Last Resort" fallback chain across all extractors.
-- **Last Resort Strategies**:
-  - **NER**: Identifies capitalized words as generic entities when models fail.
-  - **Relations**: Infers weak connections between adjacent entities.
-
-### Provenance & Tracking
-- **Traceability**: Added `batch_index` and `document_id` metadata to all extracted elements (entities, relations, triplets).
-- **Transparency**: Added count tracking to batch processing logs.
-
-## 📋 Changelog
-
-### Added
-- **Amazon Neptune Support**:
-    - Added `AmazonNeptuneStore` providing Amazon Neptune graph database integration via Bolt protocol and OpenCypher.
-    - Implemented `NeptuneAuthTokenManager` extending Neo4j AuthManager for AWS IAM SigV4 signing with automatic token refresh.
-    - Added robust connection handling: retry logic with backoff for transient errors (signature expired, connection closed) and driver recreation.
-    - Added `graph-amazon-neptune` optional dependency group (boto3, neo4j).
-    - Comprehensive test suite covering all GraphStore interface methods.
-- **Docling Integration**:
-    - Added `DoclingParser` in `semantica.parse` for high-fidelity document parsing using the Docling library.
-    - Supports multi-format parsing (PDF, DOCX, PPTX, XLSX, HTML, images) with superior table extraction and structure understanding.
-    - Implemented as a standalone parser supporting local execution, OCR, and multiple export formats (Markdown, HTML, JSON).
-- **Robust Extraction Fallbacks**:
-    - Implemented comprehensive fallback chains ("ML/LLM" -> "Pattern" -> "Last Resort") across `NERExtractor`, `RelationExtractor`, and `TripletExtractor` to prevent empty result lists.
-    - Added "Last Resort" pattern matching in `NERExtractor` to identify capitalized words as generic entities when all other methods fail.
-    - Added "Last Resort" adjacency-based relation extraction in `RelationExtractor` to create weak connections between adjacent entities if no relations are found.
-    - Added fallback logic in `TripletExtractor` to convert relations to triplets or use rule-based extraction if standard methods fail.
-- **Provenance & Tracking**:
-    - Added count tracking to batch processing logs in `NERExtractor`, `RelationExtractor`, and `TripletExtractor`.
-    - Added `batch_index` and `document_id` to the metadata of all extracted entities, relations, triplets, semantic roles, and clusters for better traceability.
-- **Semantic Extract Improvements**:
-    - Introduced `auto-chunking` for long text processing in LLM extraction methods (`extract_entities_llm`, `extract_relations_llm`, `extract_triplets_llm`).
-    - Added `silent_fail` parameter to LLM extraction methods for configurable error handling.
-    - Implemented robust JSON parsing and automatic retry logic (3 attempts with exponential backoff) in `BaseProvider` for all LLM providers.
-    - Enhanced `GroqProvider` with better diagnostics and connectivity testing.
-    - Added comprehensive entity, relation, and triplet deduplication for chunked extraction.
-    - Added `semantica/semantic_extract/schemas.py` with canonical Pydantic models for consistent structured output.
-- **Testing**:
-    - Added comprehensive robustness test suite `tests/semantic_extract/test_robustness_fallback.py` for validating extraction fallbacks and metadata propagation.
-    - Added comprehensive unit test suite `tests/embeddings/test_model_switching.py` for verifying dynamic model transitions and dimension updates.
-    - Added end-to-end integration test suite for Knowledge Graph pipeline validation (GraphBuilder -> EntityResolver -> GraphAnalyzer).
-- **Other**:
-    - Added missing dependencies `GitPython` and `chardet` to `pyproject.toml`.
-    - Robustified ID extraction across `CentralityCalculator`, `CommunityDetector`, and `ConnectivityAnalyzer` to handle various entity formats.
-    - Improved `Entity` class hashability and equality logic in `utils/types.py`.
-
-### Changed
-- **Deduplication & Conflict Logic**:
-    - Removed internal deduplication logic from `NERExtractor`, `RelationExtractor`, and `TripletExtractor`.
-    - Removed consistency/conflict checking from `ExtractionValidator` to defer to dedicated `semantica/conflicts` module.
-    - Removed `_deduplicate_*` methods from `semantica/semantic_extract/methods.py`.
-- **Batch Processing & Consistency**:
-    - Standardized batch processing across all extractors (`NERExtractor`, `RelationExtractor`, `TripletExtractor`, `SemanticNetworkExtractor`, `EventDetector`, `SemanticAnalyzer`, `CoreferenceResolver`) using a unified `extract`/`analyze`/`resolve` method pattern with progress tracking.
-    - Added provenance metadata (`batch_index`, `document_id`) to `SemanticNetwork` nodes/edges, `Event` objects, `SemanticRole` results, `CoreferenceChain` mentions, and `SemanticCluster` (tracking source `document_ids`).
-    - Updated `SemanticClusterer.cluster` and `SemanticAnalyzer.cluster_semantically` to accept list of dictionaries (with `content` and `id` keys) for better document tracking during clustering.
-    - Removed legacy `check_triplet_consistency` from `TripletExtractor`.
-    - Removed `validate_consistency` and `_check_consistency` from `ExtractionValidator`.
-- **Weighted Scoring**:
-    - Clarified weighted confidence scoring (50% Method Confidence + 50% Type Similarity) in comments.
-    - Explicitly labeled "Type Similarity" as "user-provided" in code comments to remove ambiguity.
-- **Refactoring**:
-    - Fixed orchestrator lazy property initialization and configuration normalization logic in `Orchestrator`.
-    - Verified and aligned `FileObject.text` property usage in GraphRAG notebooks for consistent content decoding.
-
-### Fixed
-- **Critical Fixes**:
-    - Resolved `NameError` in `extraction_validator.py` by adding missing `Union` import.
-    - Resolved issues where extractors would return empty lists for valid input text when primary extraction methods failed.
-    - Fixed metadata initialization issue in batch processing where `batch_index` and `document_id` were occasionally missing from extracted items.
-    - Ensured `LLMExtraction` methods (`enhance_entities`, `enhance_relations`) return original input instead of failing or returning empty results when LLM providers are unavailable.
-- **Component Fixes**:
-    - Fixed model switching bug in `TextEmbedder` where internal state was not cleared, preventing dynamic updates between `fastembed` and `sentence_transformers` (#160).
-    - Implemented model-intrinsic embedding dimension detection in `TextEmbedder` to ensure consistency between models and vector databases.
-    - Updated `set_model` to properly refresh configuration and dimensions during model switches.
-    - Fixed `TypeError: unhashable type: 'Entity'` in `GraphAnalyzer` when processing graphs with raw `Entity` objects or dictionaries in relationships (#159).
-    - Resolved `AssertionError` in orchestrator tests by aligning test mocks with production component usage.
-    - Fixed dependency compatibility issues by pinning `protobuf==4.25.3` and `grpcio==1.67.1`.
-    - Fixed a bug in `TripletExtractor` where the `validate_triplets` method was shadowed by an internal attribute.
-    - Fixed incorrect `TextSplitter` import path in the `semantic_extract.methods` module.

SECURITY.md

@@ -6,6 +6,8 @@ We actively support the following versions of Semantica with security updates:
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.2.3   | :white_check_mark: |
+| 0.2.2   | :white_check_mark: |
 | 0.2.1   | :white_check_mark: |
 | 0.2.0   | :white_check_mark: |
 | 0.1.1   | :white_check_mark: |

SUPPORT.md

@@ -27,7 +27,7 @@ Start with our comprehensive documentation:
 
 **Best for**: Real-time chat and quick questions
 
-- [Join Discord](https://discord.gg/pMHguUzG)
+- [Join Discord](https://discord.gg/sV34vps5hH)
 
 #### GitHub Issues
 

benchmarks/.gitignore

@@ -0,0 +1,75 @@
+--- Python Standards ---
+
+pycache/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+--- Virtual Environments ---
+
+.env
+.venv
+venv/
+ENV/
+
+--- Benchmarks & Results ---
+
+Ignore all individual benchmark runs to avoid repository bloat
+
+benchmarks/results/run_*.json
+
+Ignore the .pytest_cache which can get quite large
+
+.pytest_cache/
+
+Ignore any temporary files created by benchmarks
+
+benchmarks/input_layer/*.txt
+
+--- IMPORTANT: Keep the Baseline ---
+
+We want to track the 'gold standard' performance in Git
+
+!benchmarks/results/baseline.json
+
+--- IDEs & Editors ---
+
+.idea/
+.vscode/
+*.swp
+*.swo
+.project
+.pydevproject
+.settings/
+
+--- Jupyter Notebooks ---
+
+.ipynb_checkpoints
+
+--- OS Specific ---
+
+.DS_Store
+Thumbs.db
+
+--- Project Specific ---
+
+logs/
+*.log
+semantica.log

benchmarks/benchmark_results.md

@@ -0,0 +1,343 @@
+# Semantica Benchmark Suite Results
+
+## Executive Summary
+
+**Test Date**: February 7, 2026  
+**Total Benchmarks**: 138 passed, 1 skipped  
+**Test Duration**: 38 minutes 35 seconds  
+**Environment**: Windows 10, Intel i5-1135G7 @ 2.40GHz, Python 3.11.9  
+
+## Performance Overview
+
+| Module | Tests | Performance Grade | Status |
+|--------|-------|------------------|---------|
+| Input Layer | 6 | 🟢 Excellent | All passed |
+| Core Processing | 5 | 🟢 Excellent | All passed |
+| Context Memory | 2 | 🟢 Excellent | All passed |
+| Storage | 4 | 🟢 Excellent | All passed |
+| Ontology | 4 | 🟢 Excellent | All passed |
+| Export | 4 | 🟢 Excellent | All passed |
+| Visualization | 3 | 🟢 Excellent | All passed |
+| Quality Assurance | 2 | 🟢 Excellent | All passed |
+| Output Orchestration | 2 | 🟢 Excellent | All passed |
+| Context | 3 | 🟢 Excellent | All passed |
+
+---
+
+## 📊 Detailed Benchmark Results
+
+### 🔄 Input Layer Benchmarks
+
+**Purpose**: Test document parsing, data ingestion, and text processing performance
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_json_parsing_throughput[1000]` | 27,365.2 | 36.54 | 35.62 | 40.13 | 0.99 | ✅ |
+| `test_json_parsing_throughput[5000]` | 5,541.6 | 180.45 | 165.73 | 194.32 | 11.42 | ✅ |
+| `test_csv_parsing_throughput[1000]` | 18,127.9 | 55.16 | 52.41 | 61.87 | 3.33 | ✅ |
+| `test_html_scraping_speed[100]` | 2,437.8 | 410.20 | 346.30 | 6,736.50 | 89.27 | ✅ |
+| `test_pdf_extraction_overhead[10]` | 9.36 | 106.84 | 11.63 | 91.87 | 62.48 | ✅ |
+| `test_python_ast_parsing` | 3,142.6 | 318.21 | 291.96 | 347.90 | 35.67 | ✅ |
+
+**Key Insights**:
+- JSON parsing scales linearly (5K items processed in 180ms)
+- HTML scraping shows high variance due to complexity
+- PDF extraction optimized for batch processing
+- AST parsing maintains sub-millisecond performance per operation
+
+---
+
+### ⚙️ Core Processing Benchmarks
+
+**Purpose**: Test NER extraction, semantic analysis, and text processing algorithms
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_ner_ml_wrapper_overhead` | 2,480.3 | 403.18 | - | - | - | ✅ |
+| `test_ner_pattern_speed` | 1,440.1 | 694.42 | - | - | - | ✅ |
+| `test_ner_batch_throughput` | 2.33 | 429.70 | - | - | - | ✅ |
+| `test_similarity_calculation` | 3,142.6 | 318.21 | - | - | - | ✅ |
+| `test_clustering_algorithm` | 39.1 | 25,558.38 | 6,113.80 | 42,058.84 | 42,058.84 | ✅ |
+| `test_ner_ml_real_performance` | - | - | - | - | - | ⏭️ Skipped |
+
+**Key Insights**:
+- Pattern-based NER significantly outperforms ML approaches
+- Semantic clustering is computationally intensive (25s mean time)
+- Real spaCy ML test skipped due to mocked environment
+- Batch processing provides good throughput
+
+---
+
+### 🧠 Context Memory Benchmarks
+
+**Purpose**: Test graph operations, memory storage, and retrieval logic
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_bfs_traversal_depth[1]` | 469.48 | 2.13 | 1.42 | 2.04 | 1.86 | ✅ |
+| `test_bfs_traversal_depth[2]` | 419.46 | 2.38 | 2.04 | 2.38 | 0.89 | ✅ |
+| `test_memory_storage_overhead` | 9.36 | 106.84 | 11.63 | 91.87 | 62.48 | ✅ |
+| `test_short_term_pruning` | 9.23 | 108.36 | 91.87 | 108.36 | 20.76 | ✅ |
+| `test_linking_operations` | 2,869.0 | 348.55 | 313.28 | 346.30 | 39.45 | ✅ |
+| `test_retrieval_logic[False]` | 2,437.8 | 410.20 | 347.90 | 410.20 | 89.27 | ✅ |
+| `test_retrieval_logic[True]` | 39.13 | 25,558.38 | 6,113.80 | 42,058.84 | 42,058.84 | ✅ |
+
+**Key Insights**:
+- BFS traversal scales linearly with graph depth
+- Memory storage optimized for batch operations
+- Retrieval pipeline maintains sub-millisecond performance for simple cases
+- Complex retrieval (with context) significantly increases processing time
+
+---
+
+### 💾 Storage Layer Benchmarks
+
+**Purpose**: Test vector stores, triplet storage, and graph database operations
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_binary_raw_throughput` | 5.83 | 171.52 | 162.04 | 178.50 | 7.56 | ✅ |
+| `test_numpy_compression_speed[1000]` | 2.47 | 404.81 | 387.07 | 393.72 | 11.55 | ✅ |
+| `test_numpy_compression_speed[10000]` | 0.25 | 3,972.74 | 3,867.34 | 3,983.95 | 61.69 | ✅ |
+| `test_json_vector_overhead` | 0.66 | 1,504.93 | 1,471.47 | 1,443.15 | 29.39 | ✅ |
+| `test_triplet_conversion_overhead` | 87.71 | 11.40 | 5.51 | 157.91 | 21.54 | ✅ |
+| `test_bulk_loader_logic` | 2.03 | 492.98 | 304.90 | 40,477.30 | 2,084.37 | ✅ |
+
+**Key Insights**:
+- Binary vector storage is 8x faster than JSON serialization
+- Triplet conversion is highly optimized (11ms mean)
+- Bulk loading shows high variance due to retry logic
+- Vector compression scales linearly with data size
+
+---
+
+### 🏗️ Ontology Benchmarks
+
+**Purpose**: Test ontology inference, serialization, and namespace management
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_property_inference_scaling[size0]` | 1,440.1 | 694.42 | 637.90 | - | 65.09 | ✅ |
+| `test_owl_xml_generation` | 516.92 | 1.93 | 1.02 | 1.93 | 1.42 | ✅ |
+| `test_rdf_serialization_formats[turtle]` | 457.77 | 2.18 | 1.90 | 2.18 | 0.48 | ✅ |
+| `test_rdf_serialization_formats[rdfxml]` | 357.26 | 2.80 | 2.23 | 2.80 | 0.79 | ✅ |
+| `test_owl_serialization_formats[xml]` | 85.55 | 11.69 | 8.51 | 11.69 | 5.73 | ✅ |
+| `test_owl_serialization_formats[turtle]` | 61.10 | 16.37 | 12.28 | 16.37 | 6.84 | ✅ |
+
+**Key Insights**:
+- RDF Turtle format is 2x faster than RDF/XML
+- OWL serialization efficient for large ontologies
+- Property inference is computationally intensive
+- XML formats show higher overhead than Turtle
+
+---
+
+### 📤 Export Benchmarks
+
+**Purpose**: Test data export and serialization performance
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_json_parsing_throughput[1000]` | 27,365.2 | 36.54 | 35.62 | 40.13 | 0.99 | ✅ |
+| `test_csv_entity_export` | 18,127.9 | 55.16 | 52.41 | 61.87 | 3.33 | ✅ |
+| `test_json_parsing_throughput[5000]` | 5,541.6 | 180.45 | 165.73 | 194.32 | 11.42 | ✅ |
+| `test_yaml_serialization_overhead` | 2.33 | 429.70 | 357.29 | 429.70 | 68.83 | ✅ |
+| `test_graph_conversion_overhead[graphml]` | 62.16 | 16.09 | 10.74 | 16.09 | 16.84 | ✅ |
+| `test_graph_conversion_overhead[gexf]` | 55.43 | 18.04 | 15.80 | 18.04 | 1.82 | ✅ |
+
+**Key Insights**:
+- JSON export maintains excellent performance across data sizes
+- YAML serialization is slower but feature-rich
+- GraphML format is slightly faster than GEXF
+- Export performance scales linearly with data size
+
+---
+
+### 📈 Visualization Benchmarks
+
+**Purpose**: Test graph visualization, analytics, and dashboard performance
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_network_evolution_frames` | 0.21 | 4,871.40 | 3,958.10 | 4,871.40 | 931.20 | ✅ |
+| `test_temporal_dashboard_assembly` | 0.11 | 9,209.90 | 3,327.40 | 9,209.90 | 5,644.20 | ✅ |
+| `test_graph_conversion_overhead[graphml]` | 62.16 | 16.09 | 10.74 | 16.09 | 16.84 | ✅ |
+| `test_graph_conversion_overhead[gexf]` | 55.43 | 18.04 | 15.80 | 18.04 | 1.82 | ✅ |
+
+**Key Insights**:
+- Complex visualizations are computationally expensive
+- Dashboard assembly suitable for periodic updates (not real-time)
+- Graph conversion is highly optimized
+- Network evolution requires significant processing time
+
+---
+
+### 🔍 Quality Assurance Benchmarks
+
+**Purpose**: Test deduplication and conflict resolution algorithms
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_deduplication_algorithm` | 2.33 | 429.70 | 357.29 | 429.70 | 68.83 | ✅ |
+| `test_conflict_resolution` | 1,440.1 | 694.42 | 637.90 | - | 65.09 | ✅ |
+
+**Key Insights**:
+- Deduplication algorithms are efficient for batch processing
+- Conflict resolution maintains good performance
+- Both algorithms scale linearly with data size
+
+---
+
+### 🎯 Output Orchestration Benchmarks
+
+**Purpose**: Test pipeline execution and parallelism performance
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_execution_pipeline_overhead` | 2,437.8 | 410.20 | 347.90 | 410.20 | 89.27 | ✅ |
+| `test_parallelism_scaling` | 39.13 | 25,558.38 | 6,113.80 | 42,058.84 | 42,058.84 | ✅ |
+
+**Key Insights**:
+- Pipeline execution maintains good performance
+- Parallelism scaling shows high variance due to threading overhead
+- Suitable for batch processing rather than real-time
+
+---
+
+### 🔗 Context Benchmarks
+
+**Purpose**: Test graph operations and linking performance
+
+| Benchmark | Operations/sec | Mean Time (ms) | Min Time (ms) | Max Time (ms) | StdDev | Status |
+|-----------|----------------|----------------|---------------|---------------|---------|---------|
+| `test_graph_ops_performance` | 2,869.0 | 348.55 | 313.28 | 346.30 | 39.45 | ✅ |
+| `test_linking_operations` | 2,869.0 | 348.55 | 313.28 | 346.30 | 39.45 | ✅ |
+| `test_memory_storage_overhead` | 9.36 | 106.84 | 11.63 | 91.87 | 62.48 | ✅ |
+
+**Key Insights**:
+- Graph operations are highly optimized
+- Linking operations maintain consistent performance
+- Memory storage suitable for batch operations
+
+---
+
+## 🎯 Performance Analysis
+
+### Top Performers (>10,000 ops/sec)
+1. **JSON Parsing (1K)**: 27,365.2 ops/sec
+2. **JSON Export (1K)**: 27,365.2 ops/sec
+3. **HTML Scraping**: 2,437.8 ops/sec
+4. **Similarity Calculation**: 3,142.6 ops/sec
+5. **AST Parsing**: 3,142.6 ops/sec
+
+### Performance Optimizations Needed
+1. **Network Evolution**: 0.21 ops/sec (4.87s mean)
+2. **Dashboard Assembly**: 0.11 ops/sec (9.21s mean)
+3. **Semantic Clustering**: 39.13 ops/sec (25.56s mean)
+4. **Vector JSON Export**: 0.66 ops/sec (1.50s mean)
+
+### Memory Efficiency
+- **Binary vs JSON**: 8x performance improvement with binary vector storage
+- **Batch Processing**: All algorithms show linear scaling
+- **Mock Environment**: Zero memory overhead from heavy dependencies
+
+---
+
+## 📋 Regression Detection
+
+**Baseline Status**: ✅ New baseline established  
+**Regression Threshold**: 15% change with Z-score > 2.0  
+**Current Status**: ✅ No regressions detected  
+**Monitoring**: Active with 10% threshold for CI/CD
+
+---
+
+## 🖥️ Environment Specifications
+
+### Hardware Configuration
+- **CPU**: Intel i5-1135G7 @ 2.40GHz (8 cores, 16 threads)
+- **Memory**: 16GB DDR4
+- **Storage**: NVMe SSD
+- **Architecture**: x64
+
+### Software Stack
+- **OS**: Windows 10 Pro (Build 19044)
+- **Python**: 3.11.9 (64-bit)
+- **Benchmark Framework**: pytest-benchmark 5.2.3
+- **Mock Environment**: Full heavy library mocking
+
+### Test Configuration
+- **Total Test Files**: 50
+- **Total Benchmarks**: 138
+- **Test Duration**: 38m 35s
+- **Success Rate**: 99.3% (138/139)
+
+---
+
+## 🚀 Production Recommendations
+
+### High Performance Operations
+1. **Use JSON for data exchange** - 27K+ ops/sec
+2. **Binary vector storage** - 8x faster than JSON
+3. **Pattern-based NER** - Significantly faster than ML
+4. **Batch processing** - Linear scaling confirmed
+
+### Optimization Opportunities
+1. **Semantic clustering** - Algorithm optimization needed
+2. **Visualization dashboards** - Implement caching
+3. **YAML serialization** - Consider alternative libraries
+4. **Parallel execution** - Threading overhead analysis
+
+### CI/CD Integration
+- ✅ Environment-agnostic design
+- ✅ Statistical regression detection
+- ✅ Automated performance monitoring
+- ✅ Zero false positive rate
+
+---
+
+## 📊 Test Coverage Matrix
+
+| Module | Coverage Areas | Test Count | Performance |
+|--------|----------------|------------|-------------|
+| **Input Layer** | JSON, CSV, HTML, PDF, AST parsing | 6 | 🟢 Excellent |
+| **Core Processing** | NER, similarity, clustering | 5 | 🟢 Excellent |
+| **Context Memory** | Graph ops, memory, retrieval | 2 | 🟢 Excellent |
+| **Storage** | Vectors, triplets, graphs | 4 | 🟢 Excellent |
+| **Ontology** | Inference, serialization | 4 | 🟢 Excellent |
+| **Export** | JSON, CSV, YAML, Graph formats | 4 | 🟢 Excellent |
+| **Visualization** | Networks, dashboards, analytics | 3 | 🟢 Excellent |
+| **Quality Assurance** | Deduplication, conflicts | 2 | 🟢 Excellent |
+| **Output Orchestration** | Pipelines, parallelism | 2 | 🟢 Excellent |
+| **Context** | Graph operations, linking | 3 | 🟢 Excellent |
+
+---
+
+## 🏆 Conclusion
+
+The Semantica benchmark suite demonstrates **exceptional performance** across all modules:
+
+### ✅ Achievements
+- **138/138 benchmarks passed** (99.3% success rate)
+- **Sub-millisecond performance** for core operations
+- **Linear scalability** confirmed for batch processing
+- **Production-ready** performance characteristics
+- **Zero breaking changes** from benchmark addition
+
+### 🎯 Key Performance Metrics
+- **Ultra-fast text processing**: >10,000 ops/sec
+- **Efficient storage operations**: Binary format 8x faster
+- **Optimized graph algorithms**: Sub-millisecond traversal
+- **Scalable export formats**: Linear performance scaling
+
+### 🚀 Production Readiness
+- **Environment-agnostic**: Works in CI/CD and local
+- **Regression detection**: Statistical analysis active
+- **Comprehensive coverage**: All 10 modules tested
+- **Performance monitoring**: Automated baseline tracking
+
+The benchmark suite successfully provides a robust foundation for continuous performance monitoring and optimization of the Semantica framework.
+
+---
+
+*Results generated on February 7, 2026 • Semantica Benchmark Suite v1.0 • Test Environment: Windows 10, Python 3.11.9*

benchmarks/benchmarks.md

@@ -0,0 +1,72 @@
+# Semantica Performance Benchmark Suite
+
+This document outlines the architecture, directory structure, and usage of the performance benchmarking suite for the Semantica Agentic RAG framework.
+
+## Architecture
+
+The suite is organized into modular layers mirroring the library's internal structure, which allows for isolated performance testing of specific components.
+
+### High-Level Design Principles
+
+- **Isolation:** Use of mocks to ensure benchmarks measure algorithm logic.
+
+- **Virtualization:** A custom `conftest.py` virtualization layer allows tests to run without heavy local dependencies.
+
+- **Pedantic Measurement:** High-iteration counts and statistical rounds to filter out system noise.
+
+## Directory Structure
+
+Based on the current production environment, the suite is organized as follows:
+
+|                       |                                                                    |
+| --------------------- | ------------------------------------------------------------------ |
+| Folder                | Description                                                        |
+| context/              | Low-level graph operations and memory storage logic.               |
+| context_memory/       | Agent-level memory management and GraphRAG retrieval patterns.     |
+| core_processing/      | Throughput tests for NER, extraction, and graph building.          |
+| export/               | Serialization benchmarks for JSON, CSV, RDF, and GraphML.          |
+| infrastructure/       | Support scripts, including the regression comparison engine.       |
+| input_layer/          | Ingestion, parsing, and splitting performance.                     |
+| normalize/            | Text cleaning, encoding handling, and date normalization.          |
+| ontology/             | Inference, serialization, and namespace management overhead.       |
+| output_orchestration/ | Parallelism and execution pipeline management.                     |
+| quality_assurance/    | Deduplication and conflict resolution strategies.                  |
+| results/              | Storage for benchmark JSON outputs and performance baselines.      |
+| storage/              | Latency tests for Vector stores (FAISS) and Triplet stores (Jena). |
+| visualization/        | Computational cost of layout algorithms and chart rendering.       |
+
+## Usage
+
+### Running the Suite
+
+To run the full suite and generate a new results file:
+
+```bash
+python benchmarks/benchmark_runner.py
+```
+
+### Strict Mode (CI/CD)
+
+The suite is designed to integrate with automated pipelines. Using the --strict flag will cause the runner to return a non-zero exit code if a performance regression greater than 15% is detected.
+
+```bash
+python benchmarks/benchmark_runner.py --strict
+```
+
+
+
+### Performance Comparison
+
+The comparison engine (infrastructure/compare.py) uses Z-scores to distinguish between actual performance regressions and environmental noise.
+
+- Regression: Change > 15% AND Z-score > 2.0.
+
+- Noise: Change > 15% but Z-score < 2.0.
+
+### Updating Baseline
+
+When a performance change is intentional (e.g., a more complex but necessary algorithm is added), update the "gold standard" baseline:
+
+```bash
+cp benchmarks/results/run_latest.json benchmarks/results/baseline.json
+```

benchmarks/benchmarks_runner.py

@@ -0,0 +1,84 @@
+import argparse
+import os
+import subprocess
+import sys
+from datetime import datetime
+
+
+def run_benchmarks():
+    """
+    Master Runner for Semantica Benchmarks.
+    """
+    parser = argparse.ArgumentParser(description="Run Semantica Benchmarks")
+    parser.add_argument(
+        "--strict", action="store_true", help="Fail script if performance regresses"
+    )
+    args = parser.parse_args()
+
+    print("Starting Semantica Benchmark Suite...")
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H_%M_%S")
+    os.makedirs("benchmarks/results", exist_ok=True)
+
+    current_json = f"benchmarks/results/run_{timestamp}.json"
+    baseline_json = "benchmarks/results/baseline.json"
+
+    # Run Benchmarks
+    cmd = [
+        sys.executable,
+        "-m",
+        "pytest",
+        "benchmarks/",
+        "-p",
+        "no:typeguard",
+        "-p",
+        "no:langsmith",
+        "--benchmark-only",
+        f"--benchmark-json={current_json}",
+        "--benchmark-columns=min,mean,stddev,ops",
+        "--benchmark-sort=mean",
+    ]
+
+    print(f"Executing benchmarks... (saving to {current_json})")
+    result = subprocess.run(cmd)
+
+    if result.returncode != 0:
+        print("Benchmarks failed to execute (runtime errors).")
+        sys.exit(result.returncode)
+
+    print("Benchmarks completed execution.")
+
+    # Compare against Baseline
+    if os.path.exists(baseline_json):
+        print(f"Comparing against Baseline ({baseline_json})...")
+
+        if os.path.exists("benchmarks/infrastructure/compare.py"):
+            compare_cmd = [
+                sys.executable,
+                "benchmarks/infrastructure/compare.py",
+                baseline_json,
+                current_json,
+            ]
+
+            compare_result = subprocess.run(compare_cmd)
+
+            if compare_result.returncode != 0:
+                print("\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!")
+                print("   PERFORMANCE REGRESSION DETECTED")
+                print("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n")
+                if args.strict:
+                    sys.exit(1)
+            else:
+                print("Performance is within acceptable limits.")
+        else:
+            print(
+                "Comparison script not found (benchmarks/infrastructure/compare.py). Skipping comparison."
+            )
+    else:
+        print("No baseline found. This run effectively sets the new baseline.")
+
+    print(f"\n[Action] To update baseline: cp {current_json} {baseline_json}")
+
+
+if __name__ == "__main__":
+    run_benchmarks()

benchmarks/conftest.py

@@ -0,0 +1,355 @@
+import importlib.abc
+import importlib.machinery
+import os
+import sys
+import tempfile
+import uuid
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+# Import interception
+
+HEAVY_LIBS = {
+    "pdfplumber",
+    "docx",
+    "pptx",
+    "openpyxl",
+    "pandas",
+    "PIL",
+    "PIL.Image",
+    "PIL.ImageDraw",
+    "lxml",
+    "pytesseract",
+    "networkx",
+    "chardet",
+    "langdetect",
+    "neo4j",
+    "weaviate",
+    "qdrant_client",
+    "sentence_transformers",
+    "transformers",
+    "fastembed",
+    "spacy",
+    "thinc",
+    "torch",
+    "matplotlib",
+    "umap",
+    "pynndescent",
+    "fireworks",
+    "fireworks.client",
+    "docling",
+    "docling.document_converter",
+    "docling.backend",
+    "docling_core",
+    "docling_core.types",
+    "instructor",
+    "instructor.processing",
+    "instructor.core",
+    "instructor.providers",
+    "instructor.providers.fireworks",
+    "pyarrow",
+    "arrow",
+    "pa",
+}
+
+
+class MockMeta(type):
+    """Metaclass that only claims RobustMocks as instances."""
+
+    def __instancecheck__(cls, instance):
+        return hasattr(instance, "_is_robust_mock")
+
+    def __subclasscheck__(cls, subclass):
+        return True
+
+
+def create_mock_class(full_name: str):
+    return MockMeta(
+        full_name.split(".")[-1],
+        (object,),
+        {
+            "__module__": ".".join(full_name.split(".")[:-1]),
+            "__doc__": f"Mocked class {full_name}",
+            "__getattr__": lambda self, attr: RobustMock(f"{full_name}.{attr}"),
+            "__call__": lambda self, *args, **kwargs: RobustMock(full_name),
+            "__init__": lambda self, *args, **kwargs: None,
+            "__repr__": lambda self: f"<MockClass {full_name}>",
+        },
+    )
+
+
+class RobustMock:
+    def __init__(self, name: str = "mock"):
+        self.__name__ = name
+        self.__version__ = "9.9.9"
+        self._is_robust_mock = True
+        self.__path__ = []
+        self.__file__ = "mock_file.py"
+        self.__all__ = []
+
+    def __getattr__(self, name):
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        full_name = f"{self.__name__}.{name}"
+        
+        # Special handling for common PIL patterns
+        if self.__name__.endswith("Image") and name == "Image":
+            return create_mock_class(full_name)
+        elif self.__name__.endswith("ImageDraw") and name == "ImageDraw":
+            return create_mock_class(full_name)
+        # Special handling for pyarrow patterns
+        elif self.__name__ in ["pa", "pyarrow", "arrow"] and name in ["schema", "Table", "Dataset", "array", "RecordBatch"]:
+            return create_mock_class(full_name)
+        # Capital names are classes
+        elif name and name[0].isupper():
+            return create_mock_class(full_name)
+        return RobustMock(full_name)
+
+    def __call__(self, *args, **kwargs):
+        return RobustMock(self.__name__)
+
+    def __iter__(self):
+        return iter([])
+
+    def __getitem__(self, item):
+        return RobustMock(f"{self.__name__}[{item}]")
+
+    def __len__(self):
+        return 0
+
+    def __bool__(self):
+        return True
+
+    def __hash__(self):
+        return id(self)
+
+    def __repr__(self):
+        return f"<RobustMock {self.__name__}>"
+
+
+class MockLoader(importlib.abc.Loader):
+    def create_module(self, spec):
+        mock_module = RobustMock(spec.name)
+        mock_module.__spec__ = spec
+        mock_module.__loader__ = self
+        mock_module.__package__ = spec.parent
+        return mock_module
+
+    def exec_module(self, module):
+        pass
+
+
+class MockFinder(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path, target=None):
+        # Check for exact matches first
+        if fullname in HEAVY_LIBS:
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+        
+        # Check for prefix matches (e.g., PIL.Image, PIL.ImageDraw)
+        for lib in HEAVY_LIBS:
+            if fullname.startswith(lib + "."):
+                return importlib.machinery.ModuleSpec(fullname, MockLoader())
+        
+        # Special handling for PIL submodules
+        if fullname.startswith("PIL."):
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+            
+        # Special handling for fireworks
+        if fullname.startswith("fireworks."):
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+            
+        # Special handling for docling
+        if fullname.startswith("docling"):
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+            
+        # Special handling for instructor
+        if fullname.startswith("instructor"):
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+            
+        # Special handling for pyarrow
+        if fullname.startswith("pyarrow") or fullname.startswith("arrow"):
+            return importlib.machinery.ModuleSpec(fullname, MockLoader())
+            
+        return None
+
+
+if os.getenv("BENCHMARK_REAL_LIBS") != "1":
+    if not any(isinstance(f, MockFinder) for f in sys.meta_path):
+        sys.meta_path.insert(0, MockFinder())
+    
+    # Special handling for 'pa' alias that's commonly used for pyarrow
+    if "pa" not in sys.modules:
+        sys.modules["pa"] = RobustMock("pa")
+    
+    # Pre-emptively create a mock arrow_exporter module to prevent import errors
+    # This must happen BEFORE any semantica.export imports
+    import types
+    mock_arrow_module = types.ModuleType('semantica.export.arrow_exporter')
+    
+    # Create a mock ArrowExporter class with proper interface
+    class MockArrowExporter:
+        def __init__(self, *args, **kwargs):
+            pass
+        def __getattr__(self, name):
+            return lambda *args, **kwargs: f"Mock ArrowExporter.{name}"
+    
+    mock_arrow_module.ArrowExporter = MockArrowExporter
+    mock_arrow_module.ENTITY_SCHEMA = RobustMock("ENTITY_SCHEMA")
+    mock_arrow_module.RELATIONSHIP_SCHEMA = RobustMock("RELATIONSHIP_SCHEMA") 
+    mock_arrow_module.METADATA_SCHEMA = RobustMock("METADATA_SCHEMA")
+    mock_arrow_module.pa = RobustMock("pa")
+    
+    # Inject the mock module into sys.modules
+    sys.modules["semantica.export.arrow_exporter"] = mock_arrow_module
+
+# Infrastructure and Data Fixtures
+
+
+class NullTracker:
+    def start_tracking(self, *args, **kwargs):
+        return "dummy_id"
+
+    def update_tracking(self, *args, **kwargs):
+        pass
+
+    def stop_tracking(self, *args, **kwargs):
+        pass
+
+    def register_pipeline_modules(self, *args, **kwargs):
+        pass
+
+    def clear_pipeline_context(self, *args, **kwargs):
+        pass
+
+    def update_progress(self, *args, **kwargs):
+        pass
+
+    def update_progress_batch(self, *args, **kwargs):
+        pass
+
+    @property
+    def enabled(self):
+        return False
+
+    @enabled.setter
+    def enabled(self, value):
+        pass
+
+
+@pytest.fixture(autouse=True)
+def kill_io_overhead():
+    tracker = NullTracker()
+    with patch("semantica.utils.logging.get_logger"), patch(
+        "semantica.utils.progress_tracker.get_progress_tracker", return_value=tracker
+    ):
+        # Patch the export module to handle missing ArrowExporter
+        try:
+            from benchmarks.export.arrow_exporter import ArrowExporter, ENTITY_SCHEMA, RELATIONSHIP_SCHEMA, METADATA_SCHEMA
+            mock_arrow_module = RobustMock("semantica.export.arrow_exporter")
+            mock_arrow_module.ArrowExporter = ArrowExporter
+            mock_arrow_module.ENTITY_SCHEMA = ENTITY_SCHEMA
+            mock_arrow_module.RELATIONSHIP_SCHEMA = RELATIONSHIP_SCHEMA
+            mock_arrow_module.METADATA_SCHEMA = METADATA_SCHEMA
+        except ImportError:
+            mock_arrow_module = RobustMock("semantica.export.arrow_exporter")
+        
+        with patch.dict('sys.modules', {
+            'semantica.export.arrow_exporter': mock_arrow_module
+        }):
+            patches = []
+            for mod_name, module in list(sys.modules.items()):
+                if mod_name.startswith("semantica.") and hasattr(
+                    module, "get_progress_tracker"
+                ):
+                    p = patch.object(module, "get_progress_tracker", return_value=tracker)
+                    patches.append(p)
+            for p in patches:
+                p.start()
+            yield
+            for p in patches:
+                p.stop()
+
+
+class MockVectorStore:
+    def __init__(self, dim=384):
+        self.dim = dim
+
+    def embed(self, text: str):
+        return np.random.rand(self.dim).astype(np.float32)
+
+    def store_vectors(self, vectors, metadata):
+        pass
+
+    def search(self, query, limit=5):
+        return [
+            {"id": str(uuid.uuid4()), "score": 0.9, "content": "test", "metadata": {}}
+            for _ in range(limit)
+        ]
+
+
+@pytest.fixture
+def mock_vector_store():
+    return MockVectorStore()
+
+
+@pytest.fixture
+def generate_graph_data():
+    BASE_NS = "http://semantica.example.org/resource/"
+    PRED_NS = "http://semantica.example.org/predicate/"
+
+    def _gen(n_nodes: int = 100, avg_degree: int = 4):
+        nodes = [
+            {
+                "id": f"{BASE_NS}node/{i}",
+                "type": "Entity",
+                "properties": {"label": f"Node {i}"},
+            }
+            for i in range(n_nodes)
+        ]
+        edges = [
+            {
+                "source_id": f"{BASE_NS}node/{i}",
+                "target_id": f"{BASE_NS}node/{(i+1)%n_nodes}",
+                "type": f"{PRED_NS}conn",
+                "properties": {"w": 1.0},
+            }
+            for i in range(n_nodes)
+        ]
+        return nodes, edges
+
+    return _gen
+
+
+@pytest.fixture
+def populated_context_graph(generate_graph_data):
+    from semantica.context.context_graph import ContextGraph
+
+    def _create(n_nodes=1000):
+        g = ContextGraph()
+        nodes, edges = generate_graph_data(n_nodes)
+        g.add_nodes(nodes)
+        g.add_edges(edges)
+        return g
+
+    return _create
+
+
+@pytest.fixture
+def sample_text_file():
+    lines = ["Line " + str(i) for i in range(1000)]
+    content = "\n".join(lines)
+    with tempfile.NamedTemporaryFile(
+        mode="w+", delete=False, suffix=".txt", encoding="utf-8"
+    ) as tmp:
+        tmp.write(content)
+        tmp_path = tmp.name
+    yield tmp_path
+    if os.path.exists(tmp_path):
+        os.remove(tmp_path)
+
+
+@pytest.fixture
+def long_text_string():
+    return "benchmark " * 5000

benchmarks/context/conftest.py

@@ -0,0 +1,23 @@
+import pytest
+
+from semantica.context.agent_memory import AgentMemory
+from semantica.context.context_retriever import ContextRetriever
+
+
+@pytest.fixture
+def retriever_setup(mock_vector_store, populated_context_graph):
+    """
+    Sets up a fully configured retriever
+    """
+    kg = populated_context_graph(n_nodes=1000)
+
+    memory = AgentMemory(vector_store=mock_vector_store, knowledge_graph=kg)
+
+    retriever = ContextRetriever(
+        memory_store=memory,
+        knowledge_graph=kg,
+        vector_store=mock_vector_store,
+        hybrid_alpha=0.5,
+    )
+
+    return retriever

benchmarks/context/test_graph_ops.py

@@ -0,0 +1,47 @@
+import pytest
+
+from semantica.context.context_graph import ContextGraph
+
+
+@pytest.mark.benchmark(group="graph_traversal")
+@pytest.mark.parametrize("hops", [1, 2])
+def test_bfs_traversal_depth(benchmark, populated_context_graph, hops):
+    """Benchmarks the BFS neighbor retrieval at differnet depths."""
+    graph = populated_context_graph(n_nodes=2000)
+    start_node = list(graph.nodes.keys())[0]
+
+    def run():
+        return graph.get_neighbors(start_node, hops=hops)
+
+    benchmark.pedantic(run, iterations=5, rounds=10)
+
+
+@pytest.mark.benchmark(group="graph_construction")
+@pytest.mark.parametrize("size", [1000])
+def test_graph_ingestion_speed(benchmark, generate_graph_data, size):
+    """
+    Benchmarks the speed of adding nodes and edges to the
+    in-memory structure.
+    """
+
+    nodes, edges = generate_graph_data(n_nodes=size)
+
+    def run():
+        graph = ContextGraph()
+        graph.add_nodes(nodes)
+        graph.add_edges(edges)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="graph_query")
+def test_graph_keyword_search(benchmark, populated_context_graph):
+    """
+    Benchmarks the linear scan keyword search over graph nodes.
+    """
+    graph = populated_context_graph(n_nodes=2000)
+
+    def run():
+        return graph.query("Node content 500")
+
+    benchmark.pedantic(run, iterations=5, rounds=10)

benchmarks/context/test_linking.py

@@ -0,0 +1,32 @@
+import pytest
+
+from semantica.context.context_graph import ContextGraph
+from semantica.context.entity_linker import EntityLinker
+
+
+@pytest.mark.benchmark(group="entity_linkiing")
+@pytest.mark.parametrize("num_entities_in_graph", [100, 1000])
+def test_entity_linking_complexity(benchmark, num_entities_in_graph):
+    """
+    Benchmarks finding links for extracted entities
+    against the existing graph.
+    """
+
+    graph = ContextGraph()
+    nodes = [
+        {"id": f"e_{i}", "type": "Entity", "properties": {"content": f"Entity {i}"}}
+        for i in range(num_entities_in_graph)
+    ]
+    graph.add_nodes(nodes)
+
+    graph_dict = graph.to_dict()
+
+    linker = EntityLinker(knowledge_graph=graph_dict, similarity_threshold=0.7)
+
+    # Simulate extraction
+    extracted_entities = [{"text": f"Entity {i}", "type": "Entity"} for i in range(5)]
+
+    def run():
+        return linker.link("dummy text", entities=extracted_entities)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/context/test_memory_storage.py

@@ -0,0 +1,40 @@
+import pytest
+
+from semantica.context.agent_memory import AgentMemory
+
+
+@pytest.mark.benchmark(group="memory_io")
+def test_memory_storage_overhead(benchmark, mock_vector_store):
+    """
+    Benchmarks storing a memory item.
+    """
+    memory = AgentMemory(vector_store=mock_vector_store)
+    content = "This is nothing burger for benchmarking this memory thingy."
+    metadata = {"type": "conversation", "user": "u_1"}
+
+    def run():
+        return memory.store(content, metadata=metadata)
+
+    benchmark.pedantic(run, iterations=10, rounds=10)
+
+
+@pytest.mark.benchmark(group="memory_io")
+def test_short_term_pruning(benchmark, mock_vector_store):
+    """
+    Benchmarks the pruning logic when short-term memory
+    limit is hit.
+    """
+
+    def setup_overfilled_memory():
+        memory = AgentMemory(vector_store=mock_vector_store, short_term_limit=50)
+        # Pre-fill
+        for i in range(55):
+            memory.store(f"filler memory {i}")
+        return (memory,), {}
+
+    def run_prune(mem_instance):
+        mem_instance.store("Trigger Pruning")
+
+    benchmark.pedantic(
+        target=run_prune, setup=setup_overfilled_memory, iterations=1, rounds=20
+    )

benchmarks/context/test_retrieval_logic.py

@@ -0,0 +1,42 @@
+import pytest
+
+from semantica.context.agent_memory import AgentMemory
+from semantica.context.context_retriever import ContextRetriever, RetrievedContext
+
+
+@pytest.mark.benchmark(group="rag_logic")
+def test_hybrid_ranking_overhead(benchmark, retriever_setup):
+    """
+    Benchmarks the CPU cost of the 'rank_and_merge' logic.
+    """
+
+    query = "test_query"
+
+    # Dummy results to sim inputs
+    raw_results = [
+        RetrievedContext(content=f"Vec {i}", score=0.9 - i * 0.01, source="vector:x")
+        for i in range(10)
+    ] + [
+        RetrievedContext(content=f"Graph {i}", score=0.8 - i * 0.01, source="graph:y")
+        for i in range(10)
+    ]
+
+    def run():
+        return retriever_setup._rank_and_merge(raw_results, query)
+
+    benchmark.pedantic(run, iterations=10, rounds=20)
+
+
+@pytest.mark.benchmark(group="rag_logic")
+@pytest.mark.parametrize("use_graph", [True, False])
+def test_full_retrieval_pipeline(benchmark, retriever_setup, use_graph):
+    """
+    Benchmarks the orchestration of the retrieve() method.
+    """
+
+    def run():
+        return retriever_setup.retrieve(
+            "Node content", max_results=10, use_graph_expansion=use_graph, max_hops=1
+        )
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/context_memory/test_agentic.py

@@ -0,0 +1,86 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.context.agent_context import AgentContext
+from semantica.context.context_retriever import RetrievedContext
+
+# Fixtures
+
+
+@pytest.fixture
+def mock_agent_context():
+    """
+    Creates an AgentContext with mocked internals.
+    """
+    vector_store = MagicMock()
+    knowledge_graph = MagicMock()
+
+    with patch("semantica.context.agent_context.AgentMemory") as MockMemory, patch(
+        "semantica.context.agent_context.ContextRetriever"
+    ) as MockRetriever:
+
+        ctx = AgentContext(vector_store=vector_store, knowledge_graph=knowledge_graph)
+
+        # Internal mocks
+
+        ctx._memory = MockMemory.return_value
+        ctx._retriever = MockRetriever.return_value
+
+        return ctx
+
+
+# Benchmarks
+
+
+def test_router_overhead(benchmark, mock_agent_context):
+    """
+    Benchmarks the logic that decides between Vector vs Graph retrieval.
+    """
+
+    mock_agent_context._retriever.retrieve.return_value = []
+
+    def op():
+        return mock_agent_context.retrieve("test query", use_graph=None)
+
+    benchmark.pedantic(op, iterations=50, rounds=20)
+
+
+def test_result_conversion_throughput(benchmark, mock_agent_context):
+    """
+    Benchmarks converting internal RetrievedContext objects to Dicts.
+    """
+
+    fake_results = [
+        RetrievedContext(
+            content=f"Result {i}",
+            score=0.9,
+            source="graph:node_1",
+            metadata={"type": "fact"},
+            related_entities=[{"id": "e1", "name": "Entity"}],
+            related_relationships=[{"source": "e1", "target": "e2"}],
+        )
+        for i in range(100)
+    ]
+    mock_agent_context._retriever.retrieve.return_value = fake_results
+
+    def op():
+        return mock_agent_context.retrieve("test", use_graph=True)
+
+    benchmark.pedantic(op, iterations=20, rounds=10)
+
+
+def test_store_orchestration_overhead(benchmark, mock_agent_context):
+    """
+    Benchmarks the 'store' method's logic for routing documents.
+    """
+    docs = [{"content": f"Doc {i}", "metadata": {"id": i}} for i in range(50)]
+
+    # Mock the internal storage to return immediately
+    mock_agent_context._memory.store.return_value = "mem_id"
+    mock_agent_context._build_graph_from_documents = MagicMock(return_value={})
+
+    def op():
+        return mock_agent_context.store(docs, extract_entities=False)
+
+    benchmark.pedantic(op, iterations=10, rounds=10)

benchmarks/context_memory/test_graphrag.py

@@ -0,0 +1,244 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+from semantica.context.agent_context import AgentContext
+from semantica.context.agent_memory import AgentMemory
+from semantica.context.context_graph import ContextGraph
+from semantica.context.context_retriever import ContextRetriever, RetrievedContext
+from semantica.context.entity_linker import EntityLinker
+
+# Infra
+
+
+class NullTracker:
+    """
+    Stateless dummy tracker.
+    """
+
+    def start_tracking(self, *args, **kwargs):
+        return "dummy_id"
+
+    def update_tracking(self, *args, **kwargs):
+        pass
+
+    def stop_tracking(self, *args, **kwargs):
+        pass
+
+    def register_pipeline_modules(self, *args, **kwargs):
+        pass
+
+    def clear_pipeline_context(self, *args, **kwargs):
+        pass
+
+    def update_progress(self, *args, **kwargs):
+        pass
+
+    @property
+    def enabled(self):
+        return False
+
+    @enabled.setter
+    def enabled(self, value):
+        pass
+
+
+# ~~ MOCK STORES ~~
+
+
+class MockVectorStore:
+    """
+    A feather VectorStore sim that does no math.
+    We want to measure the MANAGER overhead.
+    """
+
+    def __init__(self):
+        self.vectors = {}
+        self.dim = 384
+
+    def embed(self, text):
+        return np.random.rand(self.dim).tolist()
+
+    def add(self, items):
+        for item in items:
+            self.vectors[item.memory_id] = item
+
+    def search(self, query, limit=5):
+        class MockResult:
+            def __init__(self, i):
+                self.id = f"mem_{i}"
+                self.content = f"Content for result {i} matching {query[:10]}"
+                self.score = 0.9 - (i * 0.05)
+                self.metadata = {"type": "test"}
+
+        return [MockResult(i) for i in range(limit)]
+
+
+def create_dense_graph(node_count):
+    """
+    Creates a ContextGraph with 'Small World' Topology.
+    Used to stress-test BFS traversal scaling.
+    """
+    graph = ContextGraph()
+
+    graph.progress_tracker = NullTracker()
+
+    # Create nodes
+    nodes = [
+        {
+            "id": f"node_{i}",
+            "type": "concept",
+            "properties": {"content": f"Concept {i}"},
+        }
+        for i in range(node_count)
+    ]
+    graph.add_nodes(nodes)
+
+    # Create Edges (Chain + Hub + Random)
+    edges = []
+    for i in range(node_count):
+        # Chain
+        if i < node_count - 1:
+            edges.append(
+                {"source_id": f"node_{i}", "target_id": f"node_{i+1}", "type": "next"}
+            )
+        # Hub
+        if i > 0:
+            edges.append(
+                {"source_id": "node_0", "target_id": f"node_{i}", "type": "hub_link"}
+            )
+        # Rando
+        if i % 5 == 0 and i + 5 < node_count:
+            edges.append(
+                {
+                    "source_id": f"node_{i}",
+                    "target_id": f"node_{i+5}",
+                    "type": "cross_link",
+                }
+            )
+
+    graph.add_edges(edges)
+    return graph
+
+
+def create_populated_memory(item_count):
+    """Creates an AgentMemory populated with N items."""
+    vs = MockVectorStore()
+    memory = AgentMemory(vector_store=vs)
+    memory.progress_tracker = NullTracker()
+
+    for i in range(item_count):
+        mem_id = f"setup_mem_{i}"
+        from datetime import datetime
+
+        from semantica.context.agent_memory import MemoryItem
+
+        memory.memory_items[mem_id] = MemoryItem(
+            content=f"History item {i}",
+            timestamp=datetime.now(),
+            memory_id=mem_id,
+            metadata={"type": "chat"},
+        )
+        memory.memory_index.append(mem_id)
+
+    return memory
+
+
+# ~~ BENCHMARKS ~~
+
+
+@pytest.mark.parametrize("graph_size", [100, 1000])
+@pytest.mark.parametrize("hops", [1, 2])
+def test_graph_traversal_scaling(benchmark, graph_size, hops):
+    """
+    Measures 'Hop Explosion' effect.
+    Retrieving multi-hop neighbors on a dense graph.
+    """
+    graph = create_dense_graph(graph_size)
+
+    def op():
+        # Start from'Hub' node which's celebrity, meaning
+        # connected to everyone
+        return graph.get_neighbors("node_0", hops=hops)
+
+    benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+@pytest.mark.parametrize("memory_count", [100, 1000])
+def test_retriever_ranking_throughput(benchmark, memory_count):
+    """
+    Measures CPU cost of merging and ranking results.
+    """
+    retriever = ContextRetriever(
+        vector_store=MockVectorStore(),
+        memory_store=create_populated_memory(10),
+        knowledge_graph=None,
+        hybrid_alpha=0.5,
+    )
+    retriever.progress_tracker = NullTracker()
+
+    results = []
+    for i in range(memory_count):
+        results.append(
+            RetrievedContext(
+                content=f"Vector Item {i}",
+                score=np.random.random(),
+                source=f"vector:{i}",
+            )
+        )
+        results.append(
+            RetrievedContext(
+                content=f"Graph Item {i}",
+                score=np.random.random(),
+                source=f"graph:{i}",
+                metadata={"node_id": f"node_{i}"},
+            )
+        )
+
+    def op():
+        return retriever._rank_and_merge(results, "query context")
+
+    benchmark.pedantic(op, iterations=5, rounds=10)
+
+
+@pytest.mark.parametrize("registry_size", [100, 1000])
+def test_entity_linking_speed(benchmark, registry_size):
+    """
+    Measures O(N) linear scan speed in `find_similar_entities`.
+    """
+    linker = EntityLinker()
+    linker.progress_tracker = NullTracker()
+
+    mock_kg = {"entities": []}
+    for i in range(registry_size):
+        mock_kg["entities"].append(
+            {"id": f"ent_{i}", "text": f"Entity Number {i}", "type": "TEST"}
+        )
+    linker.knowledge_graph = mock_kg
+
+    input_text = "I am looking for Entity Number 50 in the database."
+
+    def op():
+        return linker.find_similar_entities(input_text, threshold=0.1)
+
+    benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+@pytest.mark.parametrize("batch_size", [1, 10, 50])
+def test_agent_store_throughput(benchmark, batch_size):
+    """
+    'store' pipeline test.
+    """
+    vs = MockVectorStore()
+    context = AgentContext(vector_store=vs)
+    context._memory.progress_tracker = NullTracker()
+
+    inputs = [f"Memory item {i} for storage test" for i in range(batch_size)]
+
+    def op():
+        return context.batch_store(inputs)
+
+    benchmark.pedantic(op, iterations=5, rounds=5)

benchmarks/core_processing/conftest.py

@@ -0,0 +1,44 @@
+import pytest
+
+
+# Data factories
+@pytest.fixture
+def node_batch():
+    """Generates 1000 nodes for graph"""
+    return [
+        {
+            "id": f"node_{i}",
+            "type": "Concept",
+            "properties": {"name": f"Concept {i}", "weight": i / 1000},
+        }
+        for i in range(1000)
+    ]
+
+
+@pytest.fixture
+def edge_batch():
+    """Generates 1000 edges connection to the nodes."""
+    return [
+        {
+            "source_id": f"node_{i}",
+            "target_id": f"node_{i + 1}",
+            "type": "related to",
+            "weight": 0.5,
+        }
+        for i in range(999)
+    ]
+
+
+@pytest.fixture
+def conversation_data():
+    """Simulates a large conversation log"""
+    entities = [{"text": f"Entity_{i}", "type": "topic"} for i in range(50)]
+
+    return [
+        {
+            "id": "conv_1",
+            "content": "This is a conversation about banking.",
+            "entities": entities,
+            "relationships": [],
+        }
+    ]

benchmarks/core_processing/test_extraction.py

@@ -0,0 +1,153 @@
+from unittest.mock import patch
+
+import pytest
+
+from semantica.semantic_extract.ner_extractor import Entity, NERExtractor
+from semantica.semantic_extract.semantic_analyzer import SemanticAnalyzer
+
+
+# Fixtures
+@pytest.fixture
+def document_batch():
+    base = "The quick brown fox jumps over the lazy dog."
+    docs = [
+        f"{base} Variation {i}. Apple Inc released a product in 2024."
+        for i in range(50)
+    ]
+    return docs
+
+
+# Fast wrapper-only benchmark (always runs)
+def test_ner_ml_wrapper_overhead(benchmark, long_text_string):
+    extractor = NERExtractor(method="ml", model="en_core_web_sm")
+
+    entity_text = "Semantica"
+    phrase = f"{entity_text} is a knowledge graph framework. "
+    medium_text = phrase * 5
+
+    expected_entities = []
+    phrase_len = len(phrase)
+    for i in range(5):
+        start = i * phrase_len
+        end = start + len(entity_text)
+        ent = Entity(
+            text=entity_text,
+            label="ORG",
+            start_char=start,
+            end_char=end,
+            confidence=0.98,
+            metadata={"lemma": entity_text},
+        )
+        expected_entities.append(ent)
+
+    def custom_ml_extraction(text: str, **method_options):
+        min_confidence = method_options.get("min_confidence", 0.5)
+        entity_types = method_options.get("entity_types")
+        filtered = []
+        for ent in expected_entities:
+            if entity_types and ent.label not in entity_types:
+                continue
+            if ent.confidence >= min_confidence:
+                filtered.append(ent)
+        return filtered
+
+    with patch(
+        "semantica.semantic_extract.methods.get_entity_method"
+    ) as mock_get_method:
+        mock_get_method.side_effect = lambda name: (
+            custom_ml_extraction if name == "ml" else (lambda t, **o: [])
+        )
+
+        def op():
+            return extractor.extract_entities(text=medium_text)
+
+        result = benchmark.pedantic(op, rounds=20, iterations=5)
+
+    assert len(result) == 5
+    assert all(e.text == "Semantica" for e in result)
+    assert all(e.label == "ORG" for e in result)
+    assert all(e.confidence == 0.98 for e in result)
+    assert all(medium_text[e.start_char : e.end_char] == e.text for e in result)
+
+
+# Real spaCy benchmark
+@pytest.mark.benchmark(group="ner_real_ml")
+def test_ner_ml_real_performance(benchmark, long_text_string):
+    """
+    Full spaCy inference + wrapper overhead.
+    Only runs when real spaCy is loaded (BENCHMARK_REAL_LIBS=1).
+    """
+    extractor = NERExtractor(method="ml", model="en_core_web_sm")
+
+    if (
+        extractor.nlp is None
+        or not hasattr(extractor.nlp, "pipe_names")
+        or "ner" not in extractor.nlp.pipe_names
+    ):
+        pytest.skip(
+            "Real spaCy NER pipeline not available — skipping production benchmark"
+        )
+
+    medium_text = long_text_string[:10000]
+
+    medium_text += " Apple Inc. was founded by Steve Jobs and Steve Wozniak in Cupertino, California on April 1, 1976. Microsoft is a competitor."
+
+    def op():
+        return extractor.extract_entities(text=medium_text)
+
+    result = benchmark.pedantic(op, rounds=6, iterations=2)
+
+    assert len(result) >= 6
+    assert any("Apple" in e.text and e.label == "ORG" for e in result)
+    assert any(e.label == "PERSON" for e in result)
+    assert any(e.label in {"GPE", "LOC"} for e in result)
+    assert any(e.label == "DATE" for e in result)
+    assert any("Microsoft" in e.text and e.label == "ORG" for e in result)
+
+
+def test_ner_pattern_speed(benchmark, long_text_string):
+    extractor = NERExtractor(method="pattern")
+    medium_text = long_text_string[:50000]
+    text_with_entities = medium_text + " Apple Inc. was founded in 1976. "
+
+    def op():
+        return extractor.extract_entities(text=text_with_entities)
+
+    result = benchmark.pedantic(op, rounds=20, iterations=5)
+    assert len(result) > 0
+    assert result[0].label in ["ORG", "DATE", "UNKNOWN"]
+
+
+def test_ner_batch_throughput(benchmark, document_batch):
+    extractor = NERExtractor(method="pattern")
+
+    def run_batch():
+        return extractor.extract_entities_batch(document_batch, max_workers=2)
+
+    result = benchmark.pedantic(run_batch, rounds=10, iterations=5)
+    assert len(result) == len(document_batch)
+    assert len(result[0]) > 0
+
+
+def test_similarity_calculation(benchmark):
+    analyzer = SemanticAnalyzer()
+    text1 = "The quick brown fox jumps over the lazy dog" * 10
+    text2 = "The slow brown fox jumped over the sleeping dog" * 10
+
+    def op():
+        return analyzer.calculate_similarity(text1, text2, method="jaccard")
+
+    result = benchmark.pedantic(op, rounds=100, iterations=100)
+    assert 0.0 <= result <= 1.0
+
+
+def test_clustering_algorithm(benchmark, document_batch):
+    analyzer = SemanticAnalyzer()
+    options = {"similarity_threshold": 0.1}
+
+    def op():
+        return analyzer.cluster_semantically(texts=document_batch, **options)
+
+    result = benchmark.pedantic(op, rounds=10, iterations=5)
+    assert len(result) > 0
+    assert result[0].texts

benchmarks/core_processing/test_graph_building.py

@@ -0,0 +1,56 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from semantica.context.context_graph import ContextGraph
+
+
+def test_bulk_node_insertion(benchmark, node_batch):
+    """
+    Benchmarks the overhead of adding nodes to in-memory graph.
+
+    """
+
+    def setup_graph():
+        return (ContextGraph(),), {}
+
+    def run(graph_instance):
+        graph_instance.add_nodes(node_batch)
+
+    benchmark.pedantic(target=run, setup=setup_graph, rounds=50, iterations=1)
+
+
+def test_bulk_edge_insertion(benchmark, node_batch, edge_batch):
+    """
+    Benchmarks adding edges.
+    """
+
+    def setup_graph_with_nodes():
+        g = ContextGraph()
+        g.add_nodes(node_batch)
+        return (g,), {}
+
+    def run(graph_instance):
+        graph_instance.add_edges(edge_batch)
+
+    benchmark.pedantic(
+        target=run, setup=setup_graph_with_nodes, rounds=50, iterations=1
+    )
+
+
+def test_conversation_to_graph_conversion(benchmark, conversation_data):
+    """
+    Benchmarks parsing conversation dicts into graph structures.
+    """
+
+    def setup_clean_builder():
+        g = ContextGraph()
+        g.entity_linker = MagicMock()
+        return (g,), {}
+
+    def run(graph_instance):
+        return graph_instance.build_from_conversations(
+            conversation_data, link_entities=False
+        )
+
+    benchmark.pedantic(target=run, setup=setup_clean_builder, rounds=20, iterations=1)

benchmarks/export/arrow_exporter.py

@@ -0,0 +1,69 @@
+"""
+Mock Arrow Exporter for Benchmark Testing
+
+This module provides a mock implementation of the ArrowExporter to prevent
+import errors during benchmark testing when PyArrow is not available in the CI environment.
+"""
+
+# Mock PyArrow import for CI compatibility
+try:
+    import pyarrow as pa
+except ImportError:
+    # Create a mock pa module for CI environment
+    import types
+    pa = types.ModuleType('pa')
+    
+    def mock_schema(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    def mock_table(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    def mock_array(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    pa.schema = mock_schema
+    pa.Table = mock_table
+    pa.array = mock_array
+    pa.RecordBatch = mock_table
+
+# Mock schema definitions
+ENTITY_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+RELATIONSHIP_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+METADATA_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+
+class ArrowExporter:
+    """
+    Mock Arrow Exporter class for benchmark testing.
+    
+    This is a lightweight implementation that provides the same interface
+    as the real ArrowExporter but doesn't require PyArrow to be installed.
+    """
+    
+    def __init__(self, config=None):
+        self.config = config
+        self._tables = {}
+    
+    def export_entities(self, entities, output_path):
+        """Mock export entities method."""
+        return f"Mock exported {len(entities)} entities to {output_path}"
+    
+    def export_relationships(self, relationships, output_path):
+        """Mock export relationships method."""
+        return f"Mock exported {len(relationships)} relationships to {output_path}"
+    
+    def export_knowledge_graph(self, entities, relationships, output_path):
+        """Mock export knowledge graph method."""
+        return f"Mock exported knowledge graph to {output_path}"
+    
+    def to_arrow_table(self, data):
+        """Mock conversion to Arrow table."""
+        return f"Mock Arrow table with {len(data)} rows"
+    
+    def save_to_file(self, table, path):
+        """Mock save to file method."""
+        return f"Mock saved table to {path}"
+    
+    def batch_export(self, data_list, output_dir):
+        """Mock batch export method."""
+        return f"Mock batch exported {len(data_list)} items to {output_dir}"

benchmarks/export/conftest.py

@@ -0,0 +1,81 @@
+import random
+import uuid
+from typing import Any, Dict, List
+
+import numpy as np
+import pytest
+
+# Data Generators
+
+
+@pytest.fixture
+def generate_entities():
+    def _gen(count: int) -> List[Dict[str, Any]]:
+        entities = []
+        for i in range(count):
+            entities.append(
+                {
+                    "id": f"e_{i}",
+                    "text": f"Entity Number {i}",
+                    "type": random.choice(
+                        ["person", "Organization", "Location", "Event"]
+                    ),
+                    "confidence": random.uniform(0.7, 1.0),
+                    "metadata": {"source": "doc_1.txt", "page": 1},
+                }
+            )
+
+        return entities
+
+    return _gen
+
+
+@pytest.fixture
+def generate_knowledge_graph(generate_entities):
+    def _gen(entity_count: int, rel_density: float = 1.5) -> Dict[str, Any]:
+        entities = generate_entities(entity_count)
+        relationships = []
+        rel_count = int(entity_count * rel_density)
+
+        for i in range(rel_count):
+            src = random.choice(entities)
+            tgt = random.choice(entities)
+            relationships.append(
+                {
+                    "id": f"r_{i}",
+                    "source_id": src["id"],
+                    "target_id": tgt["id"],
+                    "type": " RELATED_TO",
+                    "confidence": 0.9,
+                    "metadata": {"extractor": "v1"},
+                }
+            )
+
+        return {
+            "entities": entities,
+            "relationships": relationships,
+            "metadata": {"generated_at": "2026-02-05"},
+        }
+
+    return _gen
+
+
+@pytest.fixture
+def generate_vectors():
+    def _gen(count: int, dim: int = 384) -> List[Dict[str, Any]]:
+        matrix = np.random.rand(count, dim).astype(np.float32)
+
+        data = []
+
+        for i in range(count):
+            data.append(
+                {
+                    "id": f"vec_{i}",
+                    "vector": matrix[i].tolist(),
+                    "text": f"Text {i}",
+                    "metadata": {"model": "bert"},
+                }
+            )
+        return data
+
+    return _gen

benchmarks/export/test_core_formats.py

@@ -0,0 +1,42 @@
+import pytest
+
+from semantica.export.csv_exporter import CSVExporter
+from semantica.export.json_exporter import JSONExporter
+from semantica.export.yaml_exporter import SemanticNetworkYAMLExporter
+
+
+@pytest.mark.benchmark(group="structured_export")
+@pytest.mark.parametrize("size", [1000, 5000])
+def test_json_parsing_throughput(benchmark, tmp_path, generate_knowledge_graph, size):
+    kg = generate_knowledge_graph(size)
+    exporter = JSONExporter(indent=None)
+    output_file = tmp_path / "output.json"
+
+    def run():
+        exporter.export(kg, output_file)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="structured_export")
+def test_csv_entity_export(benchmark, tmp_path, generate_entities):
+    entities = generate_entities(5000)
+    exporter = CSVExporter()
+    output_file = tmp_path / "entities.csv"
+
+    def run():
+        exporter.export_entities(entities, output_file)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="structured_export")
+def test_yaml_serialization_overhead(benchmark, tmp_path, generate_knowledge_graph):
+    kg = generate_knowledge_graph(500)
+    exporter = SemanticNetworkYAMLExporter()
+    output_file = tmp_path / "output.yaml"
+
+    def run():
+        exporter.export(kg, output_file)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/export/test_graph_export.py

@@ -0,0 +1,22 @@
+import pytest
+
+from semantica.export.graph_exporter import GraphExporter
+
+
+@pytest.mark.benchmark(group="vis_export")
+@pytest.mark.parametrize("format", ["graphml", "gexf"])
+def test_graph_conversion_overhead(
+    benchmark, tmp_path, generate_knowledge_graph, format
+):
+    """
+    Measures the cost of converting internal KG structure to XML-based graph formats.
+    Includes dictionary traversal and XML string building.
+    """
+    kg = generate_knowledge_graph(2000)
+    exporter = GraphExporter(format=format)
+    output_file = tmp_path / f"graph.{format}"
+
+    def run():
+        exporter.export_knowledge_graph(kg, output_file)
+
+    benchmark(run)

benchmarks/export/test_semantic_export.py

@@ -0,0 +1,45 @@
+import pytest
+
+from semantica.export.lpg_exporter import LPGExporter
+from semantica.export.owl_exporter import OWLExporter
+from semantica.export.rdf_exporter import RDFExporter
+
+
+@pytest.mark.benchmark(group="semantic_serialization")
+@pytest.mark.parametrize("format", ["turtle", "rdfxml"])
+def test_rdf_serialization_formats(benchmark, generate_knowledge_graph, format):
+    kg = generate_knowledge_graph(1000)
+    exporter = RDFExporter()
+    rdf_data = exporter.serializer.convert_kg_to_rdf(kg)
+
+    def run():
+        return exporter.export_to_rdf(rdf_data, format=format)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="graph_db_export")
+def test_lpg_cypher_generation(benchmark, generate_knowledge_graph):
+    kg = generate_knowledge_graph(2000)
+    exporter = LPGExporter(batch_size=1000, include_indexes=False)
+
+    def run():
+        return exporter._generate_cypher_queries(kg)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="semantic_serialization")
+def test_owl_xml_generation(benchmark, tmp_path):
+    ontology = {
+        "name": "BenchmarkOntology",
+        "classes": [{"name": f"Class{i}"} for i in range(500)],
+        "object_properties": [{"name": f"Prop{i}"} for i in range(200)],
+    }
+    exporter = OWLExporter()
+    output_file = tmp_path / "ontology.xml"
+
+    def run():
+        exporter.export(ontology, output_file, format="owl-xml")
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/export/test_vector_export.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pytest
+
+from semantica.export.vector_exporter import VectorExporter
+
+
+@pytest.mark.benchmark(group="vector_io")
+@pytest.mark.parametrize("count", [1000, 10000])
+def test_numpy_compression_speed(benchmark, tmp_path, generate_vectors, count):
+    """
+    Measures cost of np.savez_compressed.
+    """
+    vectors = generate_vectors(count)
+    exporter = VectorExporter(format="numpy")
+    output_file = tmp_path / "vectors.npz"
+
+    def run():
+        exporter.export(vectors, output_file)
+
+    benchmark(run)
+
+
+@pytest.mark.benchmark(group="vector_io")
+def test_json_vector_overhead(benchmark, tmp_path, generate_vectors):
+    """
+    Benchmarks JSON export for vectors.
+    """
+
+    vectors = generate_vectors(2000)
+    exporter = VectorExporter(format="json")
+    output_file = tmp_path / "vectors.json"
+
+    def run():
+        exporter.export(vectors, output_file)
+
+    benchmark(run)
+
+
+@pytest.mark.benchmark(group="vector_io")
+def test_binary_raw_throughput(benchmark, tmp_path, generate_vectors):
+    """
+    Measures raw binary dump speed (no compression, no metadata).
+    """
+    vectors = generate_vectors(10000)
+    exporter = VectorExporter(format="binary")
+    output_file = tmp_path / "vectors.bin"
+
+    def run():
+        exporter.export(vectors, output_file)
+
+    benchmark(run)

benchmarks/infrastructure/compare.py

@@ -0,0 +1,102 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+def load_results(filepath: str) -> Dict[str, Any]:
+    with open(filepath, "r") as f:
+        return json.load(f)
+
+
+def calc_z_score(current_mean, base_mean, base_stddev):
+    """
+    Z-Score indicates how many standard deviations
+    away current run is from baseline
+    """
+
+    if base_stddev == 0:
+        return 0 if current_mean == base_mean else 100.0
+
+    return (current_mean - base_mean) / base_stddev
+
+
+def compare_benchmarks(
+    baseline: Dict[str, Any], current: Dict[str, Any], threshold_pct: float = 10.0
+):
+    """
+    Uses Mean for % change and Z-score for noise detection.
+    """
+
+    # colors for terminal
+    RED = "\033[91m"
+    GREEN = "\033[92m"
+    YELLOW = "\033[93m"
+    RESET = "\033[0m"
+
+    header = f"{'Benchmark':<60} | {'CHANGE %':<12} | {'SIGMA (Z)':<10} | {'STATUS'}"
+    print(header)
+    print("=" * len(header))
+
+    baseline_map = {b["name"]: b for b in baseline["benchmarks"]}
+    current_map = {b["name"]: b for b in current["benchmarks"]}
+
+    regressions = []
+
+    for name, curr in current_map.items():
+        base = baseline_map.get(name)
+        if not base:
+            print(f"{name:<60} | {'NEW':<12} | {'N/A':<10} | NEW")
+            continue
+
+        m1 = base["stats"]["mean"]
+        s1 = base["stats"]["stddev"]
+        m2 = curr["stats"]["mean"]
+
+        if m1 == 0:
+            delta_pct = 0.0
+        else:
+            delta_pct = ((m2 - m1) / m1) * 100
+
+        z_score = calc_z_score(m2, m1, s1)
+
+        status = f"{GREEN} OK{RESET}"
+
+        if delta_pct > threshold_pct:
+            if abs(z_score) > 2.0:
+                status = f"{RED} REGRESSION{RESET}"
+                regressions.append(name)
+            else:
+                status = f"{YELLOW} NOISE{RESET}"
+        elif delta_pct < -threshold_pct and abs(z_score) > 2.0:
+            status = f"{GREEN} IMPROVED{RESET}"
+
+        print(f"{name:<60} | {delta_pct:>+10.2f}% | {z_score:>9.2f} | {status}")
+
+    if regressions:
+        print(
+            f"\n{RED}FAILURE: Performance regression detected in {len(regressions)} tests.{RESET}"
+        )
+        return True
+    print(f"\n{GREEN}SUCCESS: No significant regressions.{RESET}")
+    return False
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("baseline", help="Gold standard JSON")
+    parser.add_argument("current", help="NEW RUN JSON")
+    parser.add_argument(
+        "--threshold", type=float, default=10.0, help="FAIL if slower by %"
+    )
+    args = parser.parse_args()
+
+    try:
+        failed = compare_benchmarks(
+            load_results(args.baseline), load_results(args.current), args.threshold
+        )
+        sys.exit(1 if failed else 0)
+    except FileNotFoundError as e:
+        print(f"Error loading files: {e}")
+        sys.exit(0)

benchmarks/input_layer/test_ingestion.py

@@ -0,0 +1,22 @@
+import pytest
+
+from semantica.ingest.file_ingestor import FileIngestor
+
+
+def test_ingest_file_performance(benchmark, sample_text_file):
+    """
+    Benchmarks the speed of the ingest_file method
+
+    Metrics:
+    - Time to open, read, validate and wrap a ~~10 KB text file.
+    """
+
+    ingestor = FileIngestor()
+    result = benchmark(
+        ingestor.ingest_file, file_path=sample_text_file, read_content=True
+    )
+
+    assert result is not None
+    assert result.size > 0
+    assert result.name.endswith(".txt")
+    assert "Line 0" in result.text

benchmarks/input_layer/test_parsing.py

@@ -0,0 +1,188 @@
+import csv
+import io
+import json
+import time
+from typing import Any, Dict, List
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.parse.code_parser import CodeParser
+from semantica.parse.csv_parser import CSVParser
+from semantica.parse.document_parser import DocumentParser
+from semantica.parse.html_parser import HTMLParser
+from semantica.parse.json_parser import JSONParser
+
+# Data gens
+
+
+def generate_json_string(item_count: int) -> str:
+    data = [
+        {
+            "id": i,
+            "name": f"Item:{i}",
+            "tags": ["tag1", "tag2", "tag3"],
+            "metadata": {"active": True, "score": 0.95},
+        }
+        for i in range(item_count)
+    ]
+    return json.dumps(data)
+
+
+def generate_csv_string(row_count: int) -> str:
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["id", "name", "description", "value", "date"])
+    for i in range(row_count):
+        writer.writerow([i, f"Item {i}", "Description text here", 100.50, "2024-01-01"])
+    return output.getvalue()
+
+
+def generate_html_string(element_count: int) -> str:
+    lis = "".join(
+        [f'<li><a href="/item/{i}">Link {i}</a></li>' for i in range(element_count)]
+    )
+    return f"""
+    <html>
+        <head><title>Benchmark Page</title></head>
+        <body>
+            <div id="content">
+                <h1>Header</h1>
+                <p>Some intro text.</p>
+                <ul>{lis}</ul>
+            </div>
+        </body>
+    </html>
+    """
+
+
+# lib mocks
+
+
+class MockPDFPage:
+    def __init__(self, page_num):
+        self.width = 600
+        self.height = 800
+        self.page_number = page_num
+
+    def extract_text(self):
+        return f"This is text content for page {self.page_number}. " * 50
+
+    def extract_tables(self):
+        return [[["Header1", "Header2"], ["Row1", "Value1"]]]
+
+    @property
+    def images(self):
+        return [{"x0": 10, "y0": 10, "width": 100, "height": 100}]
+
+
+class MockPDF:
+    def __init__(self, page_count):
+        self.pages = [MockPDFPage(i) for i in range(page_count)]
+        self.metadata = {"Title": "Benchmark PDF", "Author": "Noone"}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass
+
+
+@pytest.fixture
+def mock_pdfplumber():
+    with patch("pdfplumber.open") as mock_open:
+        yield mock_open
+
+
+# Benchmarks
+
+
+@pytest.mark.parametrize("size", [1000, 10000])
+def test_json_parsing_throughput(benchmark, size):
+    parser = JSONParser()
+    json_str = generate_json_string(size)
+
+    with patch("pathlib.Path.exists", return_value=False):
+
+        def op():
+            return parser.parse(json_str)
+
+        benchmark.pedantic(op, iterations=5, rounds=10)
+
+
+@pytest.mark.parametrize("rows", [1000, 10000])
+def test_csv_parsing_throughput(benchmark, rows):
+    """
+    Measures CSV parsing throughput.
+    """
+    parser = CSVParser()
+    csv_content = generate_csv_string(rows)
+
+    with patch(
+        "builtins.open", side_effect=lambda *args, **kwargs: io.StringIO(csv_content)
+    ):
+        with patch("pathlib.Path.exists", return_value=True):
+
+            def op():
+                return parser.parse("dummy.csv")
+
+            benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+@pytest.mark.parametrize("elements", [100, 1000])
+def test_html_scraping_speed(benchmark, elements):
+    parser = HTMLParser()
+    html_content = generate_html_string(elements)
+
+    with patch("pathlib.Path.exists", return_value=False):
+
+        def op():
+            return parser.parse(html_content, extract_links=True)
+
+        benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+@pytest.mark.parametrize("pages", [10, 50])
+def test_pdf_extraction_overhead(benchmark, mock_pdfplumber, pages):
+    parser = DocumentParser()
+
+    mock_pdf = MockPDF(pages)
+    mock_pdfplumber.return_value = mock_pdf
+
+    with patch("pathlib.Path.exists", return_value=True), patch(
+        "pathlib.Path.suffix", new_callable=MagicMock(return_value=".pdf")
+    ):
+
+        def op():
+            return parser.parse_document("dummy.pdf", extract_images=True)
+
+        benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+def test_python_ast_parsing(benchmark):
+    """
+    Measures performance of Python AST analysis.
+    """
+    parser = CodeParser()
+
+    code_lines = []
+    for i in range(200):
+        code_lines.append(f"import module_{i}")
+        code_lines.append(f"def function_{i}(arg):")
+        code_lines.append(f"    '''Docstring for function {i}'''")
+        code_lines.append(f"    return arg + {i}")
+        code_lines.append(f"class Class_{i}:")
+        code_lines.append(f"    pass")
+
+    code_content = "\n".join(code_lines)
+
+    with patch(
+        "builtins.open", side_effect=lambda *args, **kwargs: io.StringIO(code_content)
+    ), patch("pathlib.Path.exists", return_value=True), patch(
+        "pathlib.Path.suffix", new_callable=MagicMock(return_value=".py")
+    ):
+
+        def op():
+            return parser.parse_code("dummy.py")
+
+        benchmark.pedantic(op, iterations=5, rounds=5)

benchmarks/input_layer/test_splitting.py

@@ -0,0 +1,27 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+try:
+    from semantica.split.sliding_window_chunker import SlidingWindowChunker
+    from semantica.split.splitter import TextSplitter
+except ImportError as e:
+    pytest.skip(
+        f"Skipping splitting test due to missing dependencies ({e})",
+        allow_module_level=True,
+    )
+
+
+def test_sliding_window(benchmark, long_text_string):
+    """
+    Benchmarks the speed of SlidingWindowChunker in 'Fixed Size' mode
+    """
+
+    chunker = SlidingWindowChunker(chunk_size=500, overlap=50)
+
+    if hasattr(chunker, "progress_tracker"):
+        chunker.progress_tracker = MagicMock()
+
+    result = benchmark(chunker.chunk, text=long_text_string, preserve_boundaries=False)
+
+    assert len(result) > 0

benchmarks/mock_arrow_exporter.py

@@ -0,0 +1,69 @@
+"""
+Mock Arrow Exporter for Benchmark Testing
+
+This module provides a mock implementation of the ArrowExporter to prevent
+import errors during benchmark testing when PyArrow is not available in the CI environment.
+"""
+
+# Mock PyArrow import for CI compatibility
+try:
+    import pyarrow as pa
+except ImportError:
+    # Create a mock pa module for CI environment
+    import types
+    pa = types.ModuleType('pa')
+    
+    def mock_schema(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    def mock_table(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    def mock_array(*args, **kwargs):
+        return types.SimpleNamespace()
+    
+    pa.schema = mock_schema
+    pa.Table = mock_table
+    pa.array = mock_array
+    pa.RecordBatch = mock_table
+
+# Mock schema definitions
+ENTITY_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+RELATIONSHIP_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+METADATA_SCHEMA = pa.schema([]) if hasattr(pa, 'schema') else None
+
+class ArrowExporter:
+    """
+    Mock Arrow Exporter class for benchmark testing.
+    
+    This is a lightweight implementation that provides the same interface
+    as the real ArrowExporter but doesn't require PyArrow to be installed.
+    """
+    
+    def __init__(self, config=None):
+        self.config = config
+        self._tables = {}
+    
+    def export_entities(self, entities, output_path):
+        """Mock export entities method."""
+        return f"Mock exported {len(entities)} entities to {output_path}"
+    
+    def export_relationships(self, relationships, output_path):
+        """Mock export relationships method."""
+        return f"Mock exported {len(relationships)} relationships to {output_path}"
+    
+    def export_knowledge_graph(self, entities, relationships, output_path):
+        """Mock export knowledge graph method."""
+        return f"Mock exported knowledge graph to {output_path}"
+    
+    def to_arrow_table(self, data):
+        """Mock conversion to Arrow table."""
+        return f"Mock Arrow table with {len(data)} rows"
+    
+    def save_to_file(self, table, path):
+        """Mock save to file method."""
+        return f"Mock saved table to {path}"
+    
+    def batch_export(self, data_list, output_dir):
+        """Mock batch export method."""
+        return f"Mock batch exported {len(data_list)} items to {output_dir}"

benchmarks/normalize/conftest.py

@@ -0,0 +1,62 @@
+import random
+import string
+from typing import Any, Dict, List
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# Data gen
+
+
+@pytest.fixture
+def generate_text_data():
+    """Generates various types of text data."""
+
+    def _gen(type="clean", length=100):
+        if type == "clean":
+            return "".join(random.choices(string.ascii_letters + " ", k=length))
+        elif type == "html":
+            tags = ["<div>", "<p>", "<span>", "<a>", "<b>", "<i>"]
+            content = "".join(random.choices(string.ascii_letters + " ", k=length))
+            return f"{random.choice(tags)}{content}{random.choice(tags).replace('<', '</')}"
+        elif type == "unicode":
+            chars = string.ascii_letters + "éàèùâêîôûçñ"
+            return "".join(random.choices(chars, k=length))
+        elif type == "dirty":
+            chars = string.ascii_letters + " \t\n\r"
+            return "".join(random.choices(chars, k=length))
+
+    return _gen
+
+
+@pytest.fixture
+def generate_dataset():
+    """Generates dataset for data cleaner."""
+
+    def _gen(rows=100, duplicate_rate=0.0):
+        base_rows = []
+        unique_count = int(rows * (1 - duplicate_rate))
+
+        for i in range(unique_count):
+            base_rows.append(
+                {
+                    "id": i,
+                    "name": f"Entity_{i}",
+                    "email": f"user{i}@yahoo.com",
+                    "value": random.random() * 100,
+                    "category": random.choice(["A", "B", "C"]),
+                }
+            )
+
+        final_dataset = base_rows.copy()
+        while len(final_dataset) < rows:
+            source = random.choice(base_rows)
+            dup = source.copy()
+            if random.random() > 0.5:
+                dup["value"] = source["value"] + 0.001
+            final_dataset.append(dup)
+
+        random.shuffle(final_dataset)
+        return final_dataset
+
+    return _gen

benchmarks/normalize/test_data_cleaner.py

@@ -0,0 +1,38 @@
+import pytest
+
+from semantica.normalize.data_cleaner import DataCleaner
+
+
+@pytest.mark.parametrize("rows", [100, 500])
+def test_duplication_detection_scaling(benchmark, generate_dataset, rows):
+    """
+    Benchmarks duplicate detection scaling.
+    """
+
+    cleaner = DataCleaner()
+    dataset = generate_dataset(rows=rows, duplicate_rate=0.2)
+
+    def run():
+        return cleaner.detect_duplicates(dataset, key_fields=["name", "email"])
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+def test_missing_value_imputation(benchmark, generate_dataset):
+    """
+    Benchmarks statistical imputation.
+    """
+    cleaner = DataCleaner()
+
+    def setup_broken_dataset():
+        dataset = generate_dataset(rows=5000)
+        for row in dataset:
+            if row["id"] % 5 == 0:
+                row["value"] = None
+
+        return (dataset,), {}
+
+    def run(data):
+        return cleaner.handle_missing_values(data, strategy="impute", method="mean")
+
+    benchmark.pedantic(target=run, setup=setup_broken_dataset, iterations=1, rounds=10)

benchmarks/normalize/test_heavy_libs.py

@@ -0,0 +1,31 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.normalize.encoding_handler import EncodingHandler
+from semantica.normalize.language_detector import LanguageDetector
+
+
+def test_language_detection_throughput(benchmark, generate_text_data):
+    """Benchmarks langdetect intergration."""
+    detector = LanguageDetector()
+    texts = [generate_text_data("clean", 200) for _ in range(50)]
+
+    def run():
+        return detector.detect_batch(texts)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+def test_encoding_detection(benchmark):
+    """Benchmarks chardet integration via EncodingHandler."""
+    handler = EncodingHandler()
+    data = (
+        b"Wowzaaa a simple string for encoding decoding , oh encoding detection just."
+        * 100
+    )
+
+    def run():
+        return handler.detect(data)
+
+    benchmark.pedantic(run, iterations=5, rounds=10)

benchmarks/normalize/test_parsers.py

@@ -0,0 +1,25 @@
+import pytest
+
+from semantica.normalize.date_normalizer import DateNormalizer
+from semantica.normalize.number_normalizer import NumberNormalizer
+
+
+@pytest.mark.parametrize("date_str", ["2026-02-03", "Ferbuary 2nd, 2026", "9 days ago"])
+def test_data_parsing_variations(benchmark, date_str):
+    """Compare speed of different date formats."""
+    normalizer = DateNormalizer()
+    benchmark.pedantic(
+        lambda: normalizer.normalize_date(date_str), iterations=10, rounds=20
+    )
+
+
+def test_number_normalization(benchmark):
+    """Benchmarks number parsing with currency and unit stripping."""
+    normalizer = NumberNormalizer()
+    raw_inputs = ["$1,234.56", "1.5k", "50%", "1,000,000"] * 100
+
+    def run():
+        for n in raw_inputs:
+            normalizer.normalize_number(n)
+
+    benchmark.pedantic(run, iterations=5, rounds=20)

benchmarks/normalize/test_text_processing.py

@@ -0,0 +1,42 @@
+import pytest
+
+from semantica.normalize.text_cleaner import TextCleaner
+from semantica.normalize.text_normalizer import TextNormalizer
+
+
+def test_html_removal_reg_vs_bs4(benchmark, generate_text_data):
+    """
+    Compare regex vs BeautifulSoup.
+    """
+    cleaner = TextCleaner()
+    html_content = generate_text_data("html", 10_000)
+
+    def run():
+        return cleaner.remove_html(html_content, preserve_structure=False)
+
+    benchmark.pedantic(run, rounds=50, iterations=10)
+
+
+def test_unicode_normalization_throughput(benchmark, generate_text_data):
+    """
+    Benchmarks unicode NFC normalization speed.
+    """
+    normalizer = TextNormalizer()
+    text = generate_text_data("unicode", 50_000)
+
+    def run():
+        return normalizer.normalize_text(text, unicode_form="NFC")
+
+    benchmark.pedantic(run, iterations=5, rounds=10)
+
+
+def test_whitespace_normalization(benchmark, generate_text_data):
+    """Benchmarks whitespace regex replacement."""
+    normalizer = TextNormalizer()
+    text = generate_text_data("dirty", 50_000)
+
+    benchmark.pedantic(
+        lambda: normalizer.normalize_text(text, unicode_form="NFC"),
+        iterations=5,
+        rounds=10,
+    )

benchmarks/ontology/conftest.py

@@ -0,0 +1,85 @@
+import random
+import string
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# Data generators
+
+
+def _random_str(length=8):
+    return "".join(random.choices(string.ascii_letters, k=length))
+
+
+@pytest.fixture
+def generate_ontology_data():
+    """
+    Generates a synthetic dataset of entities and relationships
+    designed to triger class and property inference class.
+    """
+
+    def _generate(entity_count: int, relationship_density: float = 1.5):
+
+        num_classes = max(5, entity_count // 50)
+        class_names = [f"Class_{_random_str(4)}" for _ in range(num_classes)]
+
+        entities = []
+
+        for i in range(entity_count):
+            cls = random.choice(class_names)
+
+            props = {
+                f"prop_{_random_str(3)}": random.choice([10, "text", 1.5, True])
+                for _ in range(random.randint(1, 5))
+            }
+
+            entity = {
+                "id": f"e_{i}",
+                "type": cls,
+                "name": f"Entity_{i}",
+                "confidence": 0.95,
+                **props,
+            }
+
+            entities.append(entity)
+
+        relationships = []
+        rel_count = int(entity_count * relationship_density)
+        rel_types = ["relatedTo", "hasPart", "worksFor", "contains", "memberOf"]
+
+        for _ in range(rel_count):
+            src = random.choice(entities)
+            tgt = random.choice(entities)
+            rel = {
+                "source": src["name"],
+                "target": tgt["name"],
+                "type": random.choice(rel_types),
+                "source_type": src["type"],
+                "target_type": tgt["type"],
+                "confidence": 0.8,
+            }
+            relationships.append(rel)
+
+        return {"entities": entities, "relationships": relationships}
+
+    return _generate
+
+
+@pytest.fixture
+def large_ontology_definition(generate_ontology_data):
+    """Pre-calculates a structured ontology
+    definition dictionary.
+    """
+    from semantica.ontology.ontology_generator import OntologyGenerator
+
+    data = generate_ontology_data(entity_count=1000)
+
+    # Mocking validation in 6-step pipeline to speed up setup
+
+    with patch(
+        "semantica.ontology.ontology_validator.OntologyValidator.validate"
+    ) as mock_val:
+        mock_val.return_value.valid = True
+        gen = OntologyGenerator()
+
+        return gen.generate_ontology(data, validate=False)

benchmarks/ontology/test_inference.py

@@ -0,0 +1,70 @@
+import pytest
+
+from semantica.ontology.class_inferrer import ClassInferrer
+from semantica.ontology.property_generator import PropertyGenerator
+
+
+@pytest.mark.benchmark(group="class_Inference")
+@pytest.mark.parametrize("entity_count", [1000, 5000])
+def test_class_inference_scaling(benchmark, generate_ontology_data, entity_count):
+    """
+    Benchmarks grouping and threshold logic in ClassInferrer.
+    """
+
+    data = generate_ontology_data(entity_count=entity_count)
+    inferrer = ClassInferrer(min_occurrences=2)
+
+    def run():
+        return inferrer.infer_classes(data["entities"])
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="property_inference")
+@pytest.mark.parametrize("size", [(1000, 1500)])
+def test_property_inference_scaling(benchmark, generate_ontology_data, size):
+    """
+    Benchmarks: PropertyGenerator
+    """
+
+    e_count, _ = size
+    data = generate_ontology_data(entity_count=e_count)
+
+    inferrer = ClassInferrer()
+    classes = inferrer.infer_classes(data["entities"])
+
+    prop_gen = PropertyGenerator()
+
+    def run():
+        return prop_gen.infer_properties(
+            entities=data["entities"],
+            relationships=data["relationships"],
+            classes=classes,
+        )
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+def test_hierarchy_circular_detection(benchmark):
+    """
+    Benchmarks the DFS cycle detection in ClassInferrer.
+    """
+
+    inferrer = ClassInferrer()
+
+    # Create a deep chain A -> B -> C ... -> Z
+
+    chain_length = 200
+    classes = []
+
+    for i in range(chain_length):
+        cls = {
+            "name": f"Class_{i}",
+            "subClassOf": f"Class_{i+1}" if i < chain_length - 1 else None,
+        }
+        classes.append(cls)
+
+    def run():
+        return inferrer.validate_classes(classes)
+
+    benchmark.pedantic(run, iterations=1, rounds=10)

benchmarks/ontology/test_ontology_pipeline.py

@@ -0,0 +1,46 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.ontology.ontology_generator import OntologyGenerator
+
+
+@pytest.mark.benchmark(group="full_pipeline")
+@pytest.mark.parametrize("entity_count", [1000])
+def test_e2e_ontology_generation(benchmark, generate_ontology_data, entity_count):
+    """
+    Benchmarks complete 6-stage pipeline
+    """
+
+    data = generate_ontology_data(entity_count)
+    generator = OntologyGenerator()
+
+    with patch(
+        "semantica.ontology.ontology_validator.OntologyValidator.validate"
+    ) as mock_val:
+        mock_val.return_value.valid = True
+
+        def run():
+            return generator.generate_ontology(data, validate=True)
+
+        benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+def test_associative_class_creation(benchmark):
+    """
+    Benchmarks the creation of complex N-ary relationships.
+    """
+    from semantica.ontology.associative_class import AssociativeClassBuilder
+
+    builder = AssociativeClassBuilder()
+
+    def run():
+        for i in range(50):
+            builder.create_position_class(
+                person_class=f"Person_{i}",
+                organization_class=f"Org_{i}",
+                role_class=f"Role_{i}",
+                name=f"Position_{i}",
+            )
+
+    benchmark.pedantic(run, iterations=1, rounds=10)

benchmarks/ontology/test_reuse.py

@@ -0,0 +1,43 @@
+import pytest
+
+from semantica.ontology.namespace_manager import NamespaceManager
+from semantica.ontology.reuse_manager import ReuseManager
+
+
+def test_namespace_iri_generation(benchmark):
+    """
+    High-throughput test for IRI Generation.
+    """
+    manager = NamespaceManager(base_uri="https://semantica.dev/bench/")
+    names = [f"EntityName_{i}" for i in range(1000)]
+
+    def run():
+        for name in names:
+            manager.generate_class_iri(name)
+
+    benchmark.pedantic(run, iterations=1, rounds=20)
+
+
+def test_ontology_merging(benchmark, large_ontology_definition):
+    """
+    Benchmarks merging two large entities together.
+    """
+    manager = ReuseManager()
+    target = large_ontology_definition.copy()
+    source = large_ontology_definition.copy()
+
+    new_classes = []
+
+    for c in source["classes"]:
+        base_id = c.get("uri") or c.get("name") or "UnkownEntity"
+        new_c = c.copy()
+        new_c["uri"] = f"{base_id}_merged"
+        new_classes.append(new_c)
+
+    source["classes"] = new_classes
+
+    def run():
+        t_copy = target.copy()
+        return manager.merge_ontology_data(t_copy, source, overwrite=False)
+
+    benchmark.pedantic(run, iterations=1, rounds=10)

benchmarks/ontology/test_serialization.py

@@ -0,0 +1,33 @@
+import pytest
+
+from semantica.ontology.owl_generator import OWLGenerator
+
+
+@pytest.mark.benchmark(group="serialization")
+@pytest.mark.parametrize("format", ["turtle", "xml"])
+def test_owl_serialization_formats(benchmark, large_ontology_definition, format):
+    """Benchmarks the cost of serializing the ontology
+    to different string formats.
+    """
+    generator = OWLGenerator()
+
+    def run():
+        return generator.generate_owl(large_ontology_definition, format=format)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+def test_rdflib_graph_construction(benchmark, large_ontology_definition):
+    """
+    Benchmarks the creation of rdflib.Graph object.
+    """
+    generator = OWLGenerator()
+
+    def run():
+        if hasattr(generator, "_generate_with_rdflib"):
+            return generator._generate_with_rdflib(
+                large_ontology_definition, format="turtle"
+            )
+        return generator.generate_owl(large_ontology_definition)
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/output_orchestration/test_execution_pipeline.py

@@ -0,0 +1,98 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.pipeline.execution_engine import ExecutionEngine
+from semantica.pipeline.pipeline_builder import PipelineBuilder, StepStatus
+from semantica.pipeline.resource_scheduler import ResourceScheduler
+
+
+# ~~ Fixtures
+@pytest.fixture(autouse=True)
+def kill_hardware_checks():
+    with patch.object(ResourceScheduler, "_initialize_resources", return_value=None):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def kill_logging():
+    with patch("semantica.utils.logging.get_logger"):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def kill_tracker():
+    mock_tracker = MagicMock()
+    mock_tracker.enabled = False
+    with patch(
+        "semantica.pipeline.execution_engine.get_progress_tracker",
+        return_value=mock_tracker,
+    ):
+        yield
+
+
+def create_pipeline(size):
+    """Helper to generate pipelines of random size."""
+    builder = PipelineBuilder()
+    builder.progress_tracker = MagicMock()
+    builder.progress_tracker.enabled = False
+    handler = lambda x, **k: x
+
+    builder.add_step("start", "dummy", handler=handler)
+    for i in range(1, size):
+        builder.add_step(f"step_{i}", "dummy", handler=handler)
+        builder.connect_steps("start" if i == 1 else f"step_{i-1}", f"step_{i}")
+
+    return builder.build(f"bench_pipe_{size}")
+
+
+# ~~ Benchmarks ~~
+
+
+@pytest.mark.parametrize("step_count", [10, 100, 500])
+def test_pipeline_construction_scaling(benchmark, step_count):
+    """
+    Verifies if construction time scales linearly.
+    """
+
+    def op():
+        builder = PipelineBuilder()
+        builder.progress_tracker = MagicMock()
+        for i in range(step_count):
+            builder.add_step(f"s{i}", "t")
+        return builder.build()
+
+    benchmark.pedantic(op, iterations=5, rounds=5)
+
+
+@pytest.mark.parametrize("step_count", [10, 100])
+def test_execution_overhead_scaling(benchmark, step_count):
+    """
+    Measures per-step overhead as it gets more complex
+    """
+    engine = ExecutionEngine()
+    pipeline = create_pipeline(step_count)
+
+    def setup_run():
+        for step in pipeline.steps:
+            step.status = StepStatus.PENDING
+            step.result = None
+        return (pipeline,), {"data": {"val": 1}}
+
+    def op(pipeline, data):
+        return engine.execute_pipeline(pipeline, data=data)
+
+    benchmark.pedantic(op, setup=setup_run, iterations=1, rounds=10)
+
+
+@pytest.mark.parametrize("step_count", [10, 100, 1000])
+def test_topological_sort_scaling(benchmark, step_count):
+    """
+    Stress test for dependency graph algorithm.
+    """
+    engine = ExecutionEngine()
+    pipeline = create_pipeline(step_count)
+
+    benchmark.pedantic(
+        lambda: engine._topological_sort(pipeline.steps), iterations=20, rounds=10
+    )

benchmarks/output_orchestration/test_parallelism.py

@@ -0,0 +1,91 @@
+import time
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.pipeline.parallelism_manager import ParallelismManager, Task
+from semantica.pipeline.resource_scheduler import ResourceScheduler
+
+
+# ~~ Fixtures ~~
+@pytest.fixture(autouse=True)
+def kill_hardware_checks():
+    with patch.object(ResourceScheduler, "_initialize_resources", return_value=None):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def kill_logging():
+    with patch("semantica.utils.logging.get_logger"):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def kill_tracker():
+    mock_tracker = MagicMock()
+    mock_tracker.enabled = False
+    with patch(
+        "semantica.pipeline.parallelism_manager.get_progress_tracker",
+        return_value=mock_tracker,
+    ):
+        yield
+
+
+def blocking_task(duration):
+    """Simulates a task that waits for I/O (like a DB query or API call)."""
+    time.sleep(duration)
+    return True
+
+
+@pytest.fixture
+def thread_manager():
+    return ParallelismManager(max_workers=4, use_processes=False)
+
+
+@pytest.fixture
+def process_manager():
+    return ParallelismManager(max_workers=4, use_processes=True)
+
+
+# ~~ BENCHMARKS ~~
+
+
+def test_parallel_vs_serial_io(benchmark, thread_manager):
+    """
+    Runs 4 tasks that sleep for 0.1s.
+    """
+    tasks = [
+        Task(task_id=f"t{i}", handler=blocking_task, args=(0.1,)) for i in range(4)
+    ]
+
+    def op():
+        return thread_manager.execute_parallel(tasks)
+
+    benchmark.pedantic(op, iterations=1, rounds=5)
+
+
+def test_thread_pool_overhead(benchmark, thread_manager):
+    """
+    Measures the raw cost of spinning up threads for zero-work tasks.
+    """
+    # No-op handler
+    noop = lambda: None
+    tasks = [Task(task_id=f"t{i}", handler=noop) for i in range(100)]
+
+    def op():
+        return thread_manager.execute_parallel(tasks)
+
+    benchmark.pedantic(op, iterations=5, rounds=10)
+
+
+def test_process_pool_overhead(benchmark, process_manager):
+    """
+    Measures overhead of ProcessPoolExecutor
+    """
+    noop = lambda: None
+    tasks = [Task(task_id=f"t{i}", handler=noop) for i in range(10)]
+
+    def op():
+        return process_manager.execute_parallel(tasks)
+
+    benchmark.pedantic(op, iterations=1, rounds=5)

benchmarks/quality_assurance/test_conflicts.py

@@ -0,0 +1,84 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.deduplication.merge_strategy import MergeStrategy, MergeStrategyManager
+
+# Fixtures
+
+
+@pytest.fixture
+def conflict_manager():
+    """Returns a MergeStrategyManager with default settings."""
+    return MergeStrategyManager()
+
+
+@pytest.fixture
+def conflicting_entities_batch():
+    """
+    Generates a list of 100 entities that are all 'duplicates' of each other
+    but have conflicting property values. This forces the resolution logic to run hard.
+    """
+    entities = []
+    for i in range(100):
+        entities.append(
+            {
+                "id": "e_1",
+                "name": f"Entity Name {i}",
+                "type": "Person",
+                "confidence": 0.5 + (i * 0.005),
+                "properties": {
+                    "age": 20 + i,
+                    "email": f"user{i}@example.com",
+                    "status": "active" if i % 2 == 0 else "inactive",
+                },
+                "relationships": [
+                    {"source": "e_1", "target": f"other_{i}", "type": "knows"}
+                ],
+            }
+        )
+    return entities
+
+
+# Benchmarks
+
+
+def test_strategy_keep_highest_confidence(
+    benchmark, conflict_manager, conflicting_entities_batch
+):
+    """
+    Benchmarks 'KEEP_HIGHEST_CONFIDENCE'.
+    """
+
+    def op():
+        return conflict_manager.merge_entities(
+            conflicting_entities_batch, strategy=MergeStrategy.KEEP_HIGHEST_CONFIDENCE
+        )
+
+    benchmark.pedantic(op, iterations=10, rounds=10)
+
+
+def test_strategy_merge_all(benchmark, conflict_manager, conflicting_entities_batch):
+    """
+    Benchmarks 'MERGE_ALL'.
+    """
+
+    def op():
+        return conflict_manager.merge_entities(
+            conflicting_entities_batch, strategy=MergeStrategy.MERGE_ALL
+        )
+
+    benchmark.pedantic(op, iterations=10, rounds=10)
+
+
+def test_property_resolution_overhead(benchmark, conflict_manager):
+    """
+    Micro-benchmark for the inner _resolve_property_conflict logic.
+    """
+
+    def op():
+        return conflict_manager._resolve_property_conflict(
+            "age", 25, 30, MergeStrategy.KEEP_MOST_COMPLETE
+        )
+
+    benchmark.pedantic(op, iterations=1000, rounds=20)

benchmarks/quality_assurance/test_deduplication.py

@@ -0,0 +1,338 @@
+import random
+import string
+import time
+from typing import Any, Dict, List
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+from semantica.deduplication.cluster_builder import ClusterBuilder
+from semantica.deduplication.duplicate_detector import DuplicateDetector
+from semantica.deduplication.entity_merger import EntityMerger
+from semantica.deduplication.similarity_calculator import SimilarityCalculator
+
+# Infra
+
+
+class NullTracker:
+    """
+    Discards all data to prevent memory leaks
+    """
+
+    def start_tracking(self, *args, **kwargs):
+        return "dummy_id"
+
+    def update_tracking(self, *args, **kwargs):
+        pass
+
+    def stop_tracking(self, *args, **kwargs):
+        pass
+
+    def register_pipeline_modules(self, *args, **kwargs):
+        pass
+
+    def clear_pipeline_context(self, *args, **kwargs):
+        pass
+
+    def update_progress(self, *args, **kwargs):
+        pass
+
+    @property
+    def enabled(self):
+        return False
+
+    @enabled.setter
+    def enabled(self, value):
+        pass
+
+
+@pytest.fixture(autouse=True)
+def kill_io_overhead():
+    """
+    Replaces ProgressTracker with NullTracker globally.
+    """
+    with patch("semantica.utils.logging.get_logger"), patch(
+        "semantica.utils.progress_tracker.get_progress_tracker"
+    ) as mock_getter:
+
+        mock_getter.return_value = NullTracker()
+
+        with patch(
+            "semantica.deduplication.similarity_calculator.get_progress_tracker",
+            return_value=NullTracker(),
+        ), patch(
+            "semantica.deduplication.duplicate_detector.get_progress_tracker",
+            return_value=NullTracker(),
+        ), patch(
+            "semantica.deduplication.cluster_builder.get_progress_tracker",
+            return_value=NullTracker(),
+        ):
+            yield
+
+
+# Sim data
+
+
+def generate_entity_cluster(base_name: str, size: int) -> List[Dict[str, Any]]:
+    """
+    Generates a cluster of similar entities based on a seed name.
+    Example: "Apple" -> ["Apple Inc", "Apple Corp", etc.]
+    """
+
+    entities = []
+    suffixes = ["Inc", "Corp", "Ltd", "Gmbh", "LLC", "Group", "Systems"]
+
+    for i in range(size):
+        if random.random() < 0.8:
+            name = f"{base_name} {random.choice(suffixes)}"
+        else:
+            # Generating a typo for our calc to work on
+            chars = list(base_name)
+            if len(chars) > 2:
+                idx = random.randint(0, len(chars) - 2)
+                chars[idx], chars[idx + 1] = chars[idx + 1], chars[idx]
+            name = "".join(chars)
+
+        entities.append(
+            {
+                "id": f"{base_name.lower()}_{i}",
+                "name": name,
+                "type": "Organization",
+                "properties": {
+                    "location": "USA" if i % 2 == 0 else "California",
+                    "sector": "Tech",
+                    "employee_count": 100 + i,
+                },
+            }
+        )
+
+    return entities
+
+
+def generate_relationship_dataset(size: int) -> List[Dict[str, Any]]:
+    """
+    Generates a dataset of graph relationships/triplets.
+    Includes exact matches, synonym predicates, and dirty literal strings.
+    """
+    relationships = []
+    predicates = ["works_for", "employed_by", "is_employee_of", "has_employer"]
+    
+    for i in range(size):
+        # Base relationship
+        rel = {
+            "subject": f"Person_{i % 50}",
+            "predicate": random.choice(predicates),
+            "object": f"Company_{i % 10}"
+        }
+        relationships.append(rel)
+        
+        # Inject semantic duplicates (dirty literals / synonym predicates)
+        if random.random() < 0.4:
+            dirty_rel = {
+                "subject": f"Person_{i % 50}",
+                "predicate": random.choice(predicates),
+                "object": f"  Company_{i % 10} Inc.  " 
+            }
+            relationships.append(dirty_rel)
+            
+    return relationships
+
+
+def generate_dataset(
+    num_clusters: int, items_per_cluster: int, worst_case_blocking: bool = False
+):
+    """
+    Generates a full dataset
+
+    Args:
+      worst_case_blocking: If True, all names start with 'A' to defeat
+                           first-char blocking strategy in SimilarityCalculator.
+
+    """
+    dataset = []
+    for i in range(num_clusters):
+        if worst_case_blocking:
+            # All starts with 'A'
+            base_name = f"A_Company_{i}"
+        else:
+            start_char = random.choice(string.ascii_uppercase)
+            base_name = f"{start_char}_company_{i}"
+
+        cluster = generate_entity_cluster(base_name, items_per_cluster)
+        dataset.extend(cluster)
+
+    return dataset
+
+
+# ~~ Benchmarks ~~
+
+
+@pytest.mark.parametrize("method", ["levenshtein", "jaro_winkler"])
+def test_string_metric_speed(benchmark, method):
+    """
+    Measures the speed of string comparison algos.
+    """
+
+    calc = SimilarityCalculator()
+    s1 = "International Business Machines Corporation"
+    s2 = "International Business Machine Corp."
+
+    benchmark.pedantic(
+        lambda: calc.calculate_string_similarity(s1, s2, method=method),
+        iterations=1000,
+        rounds=100,
+    )
+
+
+def test_full_similarity_calculation(benchmark):
+    """
+    Measures weighted multi-factor calculation overhead.
+    (String + Property + Relationship + Weights).
+    """
+
+    calc = SimilarityCalculator(
+        string_weight=0.5, property_weight=0.3, relationship_weight=0.2
+    )
+
+    e1 = {
+        "name": "Acme Corp",
+        "properties": {"loc": "NY", "id": "123"},
+        "relationships": [{"target": "t1"}, {"target": "t2"}],
+    }
+
+    e2 = {
+        "name": "Acme Inc",
+        "properties": {"loc": "NY", "id": "123"},
+        "relationships": [{"target": "t1"}, {"target": "t2"}],
+    }
+
+    benchmark.pedantic(
+        lambda: calc.calculate_similarity(e1, e2), iterations=1000, rounds=50
+    )
+
+
+@pytest.mark.parametrize("dataset_size", [100, 500])
+def test_duplicate_detection_scaling_opt(benchmark, dataset_size):
+    """
+    Tests duplication on a 'Distributed' dataset (Best Case)
+    Now utilizing V2 Candidate Generation to ensure no regressions.
+    """
+    data = generate_dataset(
+        num_clusters=dataset_size // 10, items_per_cluster=10, worst_case_blocking=False
+    )
+    
+    detector = DuplicateDetector(
+        similarity_threshold=0.8,
+        similarity={
+            "candidate_strategy": "blocking_v2", 
+            "max_candidates_per_entity": 50,
+            "prefilter_enabled": True,
+            "score_breakdown_enabled": True,
+            "prefilter_thresholds": {
+                "min_length_ratio": 0.4,
+                "require_shared_token": True
+            }
+        }
+    )
+
+    benchmark.pedantic(lambda: detector.detect_duplicates(data), iterations=1, rounds=5)
+
+
+@pytest.mark.parametrize("dataset_size", [100, 500])
+def test_duplicate_detection_worst_Case(benchmark, dataset_size):
+    """
+    Tests detection on a 'Clustered' dataset (Worst Case).
+    Now utilizing V2 Candidate Generation to cut the pair explosion.
+    """
+    data = generate_dataset(
+        num_clusters=dataset_size // 10, items_per_cluster=10, worst_case_blocking=True
+    )
+    
+    detector = DuplicateDetector(
+        similarity_threshold=0.8,
+        similarity={
+            "candidate_strategy": "blocking_v2", 
+            "max_candidates_per_entity": 50,
+            "prefilter_enabled": True,
+            "score_breakdown_enabled": True,
+            "prefilter_thresholds": {
+                "min_length_ratio": 0.4,
+                "require_shared_token": True
+            }
+        }
+    )
+
+    benchmark.pedantic(lambda: detector.detect_duplicates(data), iterations=1, rounds=5)
+
+
+def test_incremental_detection_speed(benchmark):
+    """
+    Measures performance of adding new data to existing index.
+    """
+
+    existing = generate_dataset(num_clusters=50, items_per_cluster=5)
+    new_data = generate_dataset(num_clusters=5, items_per_cluster=2)
+
+    detector = DuplicateDetector()
+
+    benchmark.pedantic(
+        lambda: detector.incremental_detect(new_data, existing), iterations=5, rounds=10
+    )
+
+
+@pytest.mark.parametrize("algo", ["graph", "hierarchical"])
+def test_clustering_strategy_performance(benchmark, algo):
+    """
+    Comapres Union-Fund (Graph) vs Hierarchical Clustering.
+    """
+
+    data = generate_dataset(num_clusters=20, items_per_cluster=10)
+
+    use_hierarchical = algo == "hierarchical"
+    builder = ClusterBuilder(use_hierarchical=use_hierarchical)
+
+    benchmark.pedantic(lambda: builder.build_clusters(data), iterations=1, rounds=5)
+
+
+def test_merge_entity_benchmark(benchmark):
+    """
+    Measures the cost of fusing entities / res conflicts.
+    """
+
+    group = generate_entity_cluster("MegaCorp", 50)
+    merger = EntityMerger()
+
+    benchmark.pedantic(
+        lambda: merger.merge_entity_group(group, strategy="keep_most_complete"),
+        iterations=10,
+        rounds=10,
+    )
+    
+
+@pytest.mark.parametrize("mode", ["legacy", "semantic_v2"])
+def test_relationship_dedup_speed(benchmark, mode):
+    """
+    Measures the speed of relationship/triplet deduplication.
+    Compares the O(N^2) legacy fallback vs the fast canonical hash path.
+    """
+    # Yields ~280 relationships (approx 39,000 comparisons in O(N^2))
+    relationships = generate_relationship_dataset(200) 
+    
+    detector = DuplicateDetector()
+    options = {
+        "threshold": 0.85,
+        "relationship_dedup_mode": mode,
+        "predicate_synonym_map": {
+            "works_for": "employed_by",
+            "is_employee_of": "employed_by",
+            "has_employer": "employed_by"
+        },
+        "literal_normalization_enabled": True
+    }
+
+    benchmark.pedantic(
+        lambda: detector.detect_relationship_duplicates(relationships, **options),
+        iterations=5,
+        rounds=10,
+    )

benchmarks/requirements.txt

@@ -0,0 +1,43 @@
+# Benchmark Tools
+
+pytest>=7.0.0
+pytest-benchmark>=4.0.0
+
+# Core Utils
+
+pydantic
+loguru
+chardet
+requests
+greenlet
+typing-extensions
+tqdm
+click
+rich
+
+numpy
+pandas
+networkx
+scikit-learn
+
+# Graph & Storage
+
+sqlalchemy
+rdflib
+neo4j
+redis
+
+# AI proc
+
+torch
+transformers
+sentence-transformers
+spacy
+beautifulsoup4
+lxml
+pypdf2
+python-docx
+openpyxl
+pillow
+feedparser
+GitPython

benchmarks/storage/test_embeddings.py

@@ -0,0 +1,180 @@
+from typing import Generator, List
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+
+from semantica.embeddings.embedding_generator import EmbeddingGenerator
+from semantica.embeddings.graph_embedding_manager import GraphEmbeddingManager
+from semantica.embeddings.pooling_strategies import PoolingStrategyFactory
+from semantica.embeddings.text_embedder import TextEmbedder
+
+
+# Infra Mocks
+@pytest.fixture(autouse=True)
+def kill_io_overhead():
+    """Silences logging and tracker globally."""
+    with patch("semantica.utils.logging.get_logger"), patch(
+        "semantica.utils.progress_tracker.get_progress_tracker"
+    ) as mock_tracker:
+
+        tracker = MagicMock()
+        tracker.enabled = False
+        tracker._start_tracking.return_value = "dummy_id"
+        mock_tracker.return_value = tracker
+
+        with patch(
+            "semantica.embeddings.text_embedder.get_progress_tracker",
+            return_value=tracker,
+        ):
+            yield
+
+
+# __ Model Mocks __
+
+
+class MockSentenceTransformer:
+    """
+    Simulates ST.encode without loading the fat model itself.
+    """
+
+    def __init__(self, dim=384):
+        self.dim = dim
+
+    def encode(
+        self, sentences: List[str], normalize_embeddings=True, **kwargs
+    ) -> np.ndarray:
+        count = len(sentences)
+        return np.random.rand(count, self.dim).astype(np.float32)
+
+    def get_sentence_embedding_dimension(self):
+        return self.dim
+
+
+class MockFastEmbed:
+    """
+    Simulates FastEmbed.embed generator behavior.
+    """
+
+    def __init__(self, dim=384):
+        self.dim = dim
+
+    def embed(self, documents: List[str]) -> Generator[np.ndarray, None, None]:
+        for _ in documents:
+            yield np.random.rand(self.dim).astype(np.float32)
+
+
+# ~~ Fixtures ~~
+@pytest.fixture
+def text_embedder_st():
+    """
+    Text embedder configured with SentenceTransformer
+    """
+    embedder = TextEmbedder(method="sentence_transformers", model_name="mock-bert")
+    embedder.model = MockSentenceTransformer()
+    embedder.progress_tracker = MagicMock()
+    embedder.progress_tracker.enabled = False
+
+    return embedder
+
+
+@pytest.fixture
+def text_embedder_fast():
+    """
+    Text Embedder cofnigures with Mock FastEmbed.
+    """
+
+    embedder = TextEmbedder(method="fastembed", model_name="mock-bge")
+    embedder.fastembed_model = MockFastEmbed()
+    embedder.progress_tracker = MagicMock()
+    embedder.progress_tracker.enabled = False
+    return embedder
+
+
+# ~~ Benchmarks
+
+
+@pytest.mark.parametrize("strategy", ["mean", "max", "cls", "attention"])
+def test_pooling_math_speed(benchmark, strategy):
+    """
+    Measures the raw NumPy speed of pooling strategies.
+    Scenario: Pooling a batch of 128 token embeddings.
+    """
+
+    embeddings = np.random.rand(128, 768).astype(np.float32)
+    pooler = PoolingStrategyFactory.create(strategy)
+
+    benchmark.pedantic(lambda: pooler.pool(embeddings), iterations=1000, rounds=100)
+
+
+def test_hierarchical_pooling_overhead(benchmark):
+    """
+    Measures the overhead of two-step hierarchical pooling.
+    """
+
+    embeddings = np.random.rand(1000, 768).astype(np.float32)
+    pooler = PoolingStrategyFactory.create("hierarchical", chunk_size=100)
+
+    benchmark.pedantic(lambda: pooler.pool(embeddings), iterations=500, rounds=50)
+
+
+def test_st_wrapper_overhead(benchmark, text_embedder_st):
+    """
+    Measures overhead of TextEmbedder wrapper around SentenceTransformers.
+    """
+
+    text = "This is a whatever we are doing here since idk"
+
+    benchmark.pedantic(
+        lambda: text_embedder_st.embed_text(text), iterations=1000, rounds=20
+    )
+
+
+def test_fastembed_generator_consumption(benchmark, text_embedder_fast):
+    """
+    Measures the cost of consuming the FastEmbed generator
+    and converting to Array.
+    """
+    texts = [f"Sentence {i}" for i in range(20)]
+
+    benchmark.pedantic(
+        lambda: text_embedder_fast.embed_batch(texts), iterations=100, rounds=20
+    )
+
+
+@pytest.mark.parametrize("batch_size", [10, 100, 1000])
+def test_batch_processing_pipeline(benchmark, batch_size, text_embedder_st):
+    """
+    Measures the full EmbeddingGenerator pipeline:
+    Input validation -> Type detection -> Batching -> Mock Model -> Error handling.
+    """
+
+    generator = EmbeddingGenerator()
+
+    generator.text_embedder = text_embedder_st
+    generator.progress_tracker = MagicMock()
+    generator.progress_tracker.enabled = False
+
+    data = [f"Item {i}" for i in range(batch_size)]
+
+    benchmark.pedantic(lambda: generator.process_batch(data), iterations=5, rounds=10)
+
+
+@pytest.mark.parametrize("count", [100, 1000])
+def test_graph_embedding_prep(benchmark, count, text_embedder_st):
+    """
+    Measures how fast we can reshape dict for GraphDBs
+    """
+    manager = GraphEmbeddingManager()
+    manager.embedding_generator.text_embedder = text_embedder_st
+
+    manager.embedding_generator.generate_embeddings = MagicMock(
+        return_value=np.random.rand(count, 384).astype(np.float32)
+    )
+
+    entities = [{"id": f"e{i}", "text": f"Entity{i}"} for i in range(count)]
+
+    def op():
+        return manager.prepare_for_graph_db(entities, backend="neo4j")
+
+    benchmark.pedantic(op, iterations=10, rounds=10)

benchmarks/storage/test_graph_store.py

@@ -0,0 +1,137 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.graph_store.graph_store import GraphStore
+
+
+@pytest.fixture
+def mock_neo4j_driver():
+    """
+    Creates a mock of of Neo4j Driver
+    Simulates: Driver -> Session -> Transaction -> Result -> Record
+    """
+
+    mock_result = MagicMock()
+    fake_props = {"name": "TestNode", "age": 30}
+
+    def get_item(key):
+        if key == "id":
+            return 12345
+        if key == "n":
+            return fake_props
+        if key == "count":
+            return 42
+        return None
+
+    mock_record = MagicMock()
+    mock_record.__getitem__.side_effect = get_item
+    mock_record.keys.return_value = ["id", "n"]
+    mock_record.values.return_value = [12345, fake_props]
+
+    # dict conversion - essentially doing it because the db sometimes demands it
+    mock_record.items.return_value = [("id", 12345), ("n", fake_props)]
+
+    # ~~ Result Methods ~~
+    mock_result = MagicMock()
+    mock_result.single.return_value = mock_record
+    mock_result.__iter__.side_effect = lambda: iter([mock_record])
+
+    # ~~ Session ~~
+    mock_session = MagicMock()
+    mock_session.run.return_value = mock_result
+    mock_session.__enter__.return_value = mock_session
+    mock_session.__exit__.return_value = None
+
+    # ~~ Driver ~~
+    mock_driver = MagicMock()
+    mock_driver.session.return_value = mock_session
+    mock_driver.verify_connectivity.return_value = True
+
+    return mock_driver
+
+
+@pytest.fixture
+def graph_store(mock_neo4j_driver):
+    """
+    Returns a GraphsStore connected to mnock driver.
+    """
+
+    # ~~ Patch GraphDatbase ~~
+    with patch("semantica.graph_store.neo4j_store.GraphDatabase") as mockDB:
+        mockDB.driver.return_value = mock_neo4j_driver
+        store = GraphStore(
+            backend="neo4j", uri="bolt://mock:7687", user="mock", password="mock"
+        )
+        store.connect()
+
+        if hasattr(store, "progress_tracker"):
+            store.progress_tracker = MagicMock()
+
+        return store
+
+
+#    ~~ Benchmarks ~~
+
+
+def test_node_creation_overhead(benchmark, graph_store):
+    """
+    Benchamrks the full stack overhead for creating a single node.
+    Path: GraphStore -> NodeManager -> Neo4jStore, Driver
+    """
+
+    def op():
+        return graph_store.create_node(
+            labels=["Person"], properties={"name": "Alexander", "age": 17}
+        )
+
+    result = benchmark(op)
+    assert result["id"] == 12345
+
+
+def test_batch_node_creation_overhead(benchmark, graph_store):
+    """
+    Benchmarks the loop overhead in create_nodes (Batch).
+    Checks if it handles lists efficiently.
+    """
+
+    nodes = [{"labels": ["Person"], "properties": {"id": i}} for i in range(50)]
+
+    def op():
+        return graph_store.create_nodes(nodes)
+
+    result = benchmark(op)
+    assert len(result) == 50
+
+
+def test_query_construction_and_parsing(benchmark, graph_store):
+    """
+    Benchmarks every execution overhead.
+    Measures how fast `QueryEngine` parses result into a Python dict.
+    """
+
+    query = "MATCH ( n:Person) RETURN n LIMIT 1"
+
+    def op():
+        return graph_store.execute_query(query)
+
+    result = benchmark(op)
+    assert result["success"] is True
+    assert len(result["records"]) > 0
+
+
+def test_analytics_shortest_path_overhead(benchmark, graph_store):
+    """
+    Benchmarks the wrapper overhead for graph analytics.
+    """
+
+    def op():
+        return graph_store.shortest_path(
+            start_node_id=1, end_node_id=2, rel_type="KNOWS"
+        )
+
+    try:
+        benchmark(op)
+    except Exception:
+        # v pass as we are only trying to benchmark the function overhead call mainly
+        pass

benchmarks/storage/test_triplet_storage.py

@@ -0,0 +1,146 @@
+import time
+from dataclasses import dataclass
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from semantica.triplet_store.bulk_loader import BulkLoader
+from semantica.triplet_store.jena_store import JenaStore
+from semantica.triplet_store.triplet_store import TripletStore
+
+# ~~ Mocking ~~
+# We basically define a facile Triplet class for creating ds devoid of fat AI models
+
+
+@dataclass
+class SimpleTriplet:
+    subject: str
+    predicate: str
+    object: str
+    confidence: float = 1.0
+
+
+# ~~ Fixtures ~~
+@pytest.fixture
+def triplet_batch():
+    """Generates 1000 triplets."""
+    return [
+        SimpleTriplet(
+            subject=f"http://gandhara.org/entity/{i}",
+            predicate="http://gandhara.org/relation/knows",
+            object=f"http://example.org/entity/{i+1}",
+        )
+        for i in range(1000)
+    ]
+
+
+@pytest.fixture
+def large_knowledge_graph_dict():
+    """
+    Generates a large dict (1000 ent) to test parsing
+    logic in `TripletStore.store()`
+    """
+    entities = [
+        {
+            "id": f"ent_{i}",
+            "type": "Person",
+            "properties": {"name": f"Person {i}", "age": 60},
+        }
+        for i in range(1000)
+    ]
+    relationships = [
+        {"source": f"ent_{i}", "target": f"ent_{i+1}", "type": "KNOWS"}
+        for i in range(999)
+    ]
+
+    return {"entities": entities, "relationships": relationships}
+
+
+@pytest.fixture
+def in_memory_store():
+    """Returns a real JenaStore using RDFLib (In-Mmeory)."""
+
+    store = JenaStore(endpoint=None)
+    if store.graph is None:
+        pytest.fail("JenaStore failed to initialize rdflib graph.")
+    if hasattr(store, "progress_tracker"):
+        store.progress_tracker = MagicMock()
+
+    return store
+
+
+# ~~ Benchmarks ~~
+
+
+def test_rdflib_insert_throughput(benchmark, in_memory_store, triplet_batch):
+    """
+    Benchmarks raw Write Speed to in-memory RDF graph.
+    Is our baseline
+    """
+
+    def op():
+        in_memory_store.add_triplets(triplet_batch)
+
+    benchmark(op)
+
+    assert len(in_memory_store.graph) >= 1000
+
+
+def test_triplet_conversion_overhead(benchmark, large_knowledge_graph_dict):
+    """
+    Benchmarks the `store()` method in TripletStore.
+    This tests Python logic that converts a Dict -> Triplet objects.
+    """
+
+    with patch("semantica.triplet_store.blazegraph_store.BlazegraphStore") as mockBE:
+        mock_instance = mockBE.return_value
+        mock_instance.add_triplets.return_value = {"success": True}
+
+        manager = TripletStore(backend="blazegraph")
+        if hasattr(manager, "progress_tracker"):
+            manager.progress_tracker = MagicMock()
+
+        def op():
+            manager.store(
+                knowledge_graph=large_knowledge_graph_dict,
+                ontology={"classes": [], "properties": []},
+            )
+
+        benchmark(op)
+
+
+def test_bulk_loader_logic(benchmark, triplet_batch):
+    """
+    Benchmarks teh BulkLoader class.
+    Measures the overhead of batching, retries and progress tracking.
+    """
+
+    loader = BulkLoader(batch_size=100)
+    if hasattr(loader, "progress_tracker"):
+        loader.progress_tracker = MagicMock()
+
+    mock_store = MagicMock()
+    mock_store.add_triplets.return_value = {"success": True}
+
+    def op():
+        return loader.load_triplets(triplet_batch, mock_store)
+
+    result = benchmark(op)
+    assert result.total_batches == 10
+
+
+def test_sparql_query_performance(benchmark, in_memory_store, triplet_batch):
+    """
+    Benchamrks SPARQL query execution speed on 1000 items.
+    """
+
+    in_memory_store.add_triplets(triplet_batch)
+
+    query = "SELECT ?s ?o WHERE { ?s <http://gandhara.org/relation/knows> ?o } LIMIT 50"
+
+    def op():
+        return in_memory_store.execute_sparql(query)
+
+    result = benchmark(op)
+    assert result["success"] is True
+    assert len(result["bindings"]) == 50

benchmarks/storage/test_vector_storage.py

@@ -0,0 +1,94 @@
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+
+from semantica.vector_store.faiss_store import FAISSStore
+from semantica.vector_store.vector_store import VectorStore
+
+# Fixtures
+
+
+@pytest.fixture
+def vector_dim():
+    return 768
+
+
+@pytest.fixture
+def random_vectors(vector_dim):
+    """Generates a batch of 10,000 rando vectors."""
+    count = 10000
+    vectors = np.random.rand(count, vector_dim).astype(np.float32)
+    return vectors
+
+
+@pytest.fixture
+def populated_store(random_vectors, vector_dim):
+    """
+    Returns a FAISS store bred with data.
+    """
+
+    store = FAISSStore(dimension=vector_dim)
+    if hasattr(store, "progress_tracker"):
+        store.progress_tracker = MagicMock()
+    store.create_index(index_type="flat")
+    store.add_vectors(random_vectors)
+    return store
+
+
+# Benchmarks
+
+
+def test_faiss_insert_throughput(benchmark, random_vectors, vector_dim):
+    """
+    Benchmarks raw Write speed to FAISS
+    """
+    store = FAISSStore(dimension=vector_dim)
+    if hasattr(store, "progress_tracker"):
+        store.progress_tracker = MagicMock()
+    store.create_index(index_type="flat")
+
+    def insert_op():
+        store.add_vectors(random_vectors)
+
+    benchmark(insert_op)
+
+    assert len(store.index.vector_ids) >= 10000
+
+
+def test_faiss_search_latency(benchmark, populated_store, vector_dim):
+    """
+    Benchmarks Read/Search speed
+    """
+
+    query = np.random.rand(1, vector_dim).astype(np.float32)
+    results = benchmark(populated_store.search_similar, query_vector=query, k=10)
+    assert len(results) == 10
+
+
+def test_vector_storage_manager_overhead(benchmark, random_vectors, vector_dim):
+    """
+    Benchmarks the overhead of the VectorStore class
+    """
+    with patch(
+        "semantica.vector_store.vector_store.EmbeddingGenerator"
+    ) as MockEmbedder:
+        manager = VectorStore(backend="faiss", dimension=vector_dim)
+        if hasattr(manager, "progress_tracker"):
+            manager.progress_tracker = MagicMock()
+
+        def store_op():
+            manager.store_vectors(random_vectors)
+
+        benchmark(store_op)
+
+        # Check vectors were stored - handle both in-memory and backend stores
+        if hasattr(manager, 'vectors'):
+            # In-memory backend
+            assert len(manager.vectors) >= 10000
+        elif hasattr(manager, '_backend_store') and hasattr(manager._backend_store, 'vector_ids'):
+            # Backend store (like FAISS)
+            assert len(manager._backend_store.vector_ids) >= 10000
+        else:
+            # For other backends, just ensure no errors occurred
+            pass

benchmarks/visualization/conftest.py

@@ -0,0 +1,80 @@
+import random
+from typing import Any, Dict, List
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+
+
+# Data Generators
+@pytest.fixture
+def generate_embeddings():
+    """Generates synthetic high-dim embeddings."""
+
+    def _gen(n_samples: int, n_features: int = 768):
+        return np.random.rand(n_samples, n_features).astype(np.float32)
+
+    return _gen
+
+
+@pytest.fixture
+def generate_knowledge_graph():
+    """Generates synthetic Knowledge Graph dictionary."""
+
+    def _gen(n_nodes: int, density: float = 0.05):
+        entities = [
+            {
+                "id": f"e_{i}",
+                "label": f"Entity_{i}",
+                "type": random.choice(["Person", "Organization", "Location", "Event"]),
+                "metadata": {"score": random.random()},
+            }
+            for i in range(n_nodes)
+        ]
+
+        relationships = []
+        n_edges = int(n_nodes * (n_nodes - 1) * density)
+        # Capping edges for safety
+        n_edges = min(n_edges, n_nodes * 5)
+
+        for i in range(n_edges):
+            src = random.randint(0, n_nodes - 1)
+            tgt = random.randint(0, n_nodes - 1)
+
+            if src != tgt:
+                relationships.append(
+                    {
+                        "source": f"e_{src}",
+                        "target": f"e_{tgt}",
+                        "type": "related_to",
+                        "metadata": {"weight": random.random()},
+                    }
+                )
+
+        return {"entities": entities, "relationships": relationships}
+
+    return _gen
+
+
+@pytest.fixture
+def generate_temporal_data(generate_knowledge_graph):
+    """Generates synthetic temporal graph snapshots."""
+
+    def _gen(n_snapshots: int, n_nodes: int):
+        timestamps_map = {}
+        base_kg = generate_knowledge_graph(n_nodes)
+        entities = base_kg["entities"]
+
+        all_years = list(range(2020, 2020 + n_snapshots))
+        for ent in entities:
+            start = random.randint(0, len(all_years) - 2)
+            duration = random.randint(1, len(all_years) - start)
+            timestamps_map[ent["id"]] = all_years[start : start + duration]
+
+        return {
+            "entities": entities,
+            "relationships": base_kg["relationships"],
+            "timestamps": timestamps_map,
+        }
+
+    return _gen

benchmarks/visualization/test_analytics_viz.py

@@ -0,0 +1,26 @@
+import random
+
+import pytest
+
+from semantica.visualization.analytics_visualizer import AnalyticsVisualizer
+
+
+@pytest.mark.benchmark(group="analytics_charts")
+def test_centrality_ranking_sort_and_render(benchmark):
+    """
+    Benchmarks sorting a large centrality dictionary
+    and rendering the Top N bar chart.
+    """
+    viz = AnalyticsVisualizer()
+
+    # Generate 5000 node scores
+    centrality_data = {
+        "centrality": {f"node_{i}": random.random() for i in range(5000)}
+    }
+
+    def run():
+        return viz.visualize_centrality_rankings(
+            centrality_data, centrality_type="degree", top_n=50, output="interactive"
+        )
+
+    benchmark.pedantic(run, iterations=1, rounds=10)

benchmarks/visualization/test_embedding_viz.py

@@ -0,0 +1,45 @@
+import numpy as np
+import pytest
+
+from semantica.visualization.embedding_visualizer import EmbeddingVisualizer
+
+
+@pytest.mark.benchmark(group="embedding_projection")
+@pytest.mark.parametrize("method", ["pca", "tsne"])
+@pytest.mark.parametrize("n_samples", [500])
+def test_projection_calculation_overhead(
+    benchmark, generate_embeddings, method, n_samples
+):
+    """
+    Measures the combined cost of:
+    1. Dimensionality Reduction (Math)
+    2. Plotly Trace Construction (Object creation)
+    """
+
+    viz = EmbeddingVisualizer()
+    embeddings = generate_embeddings(n_samples=n_samples, n_features=128)
+    labels = [f"Label {i}" for i in range(n_samples)]
+
+    def run():
+        return viz.visualize_2d_projection(
+            embeddings, labels=labels, method=method, output="interactive"
+        )
+
+    rounds = 5 if method == "tsne" else 10
+    benchmark.pedantic(run, iterations=1, rounds=rounds)
+
+
+@pytest.mark.benchmark(group="embedding_heatmap")
+def test_similarity_heatmap_generation(benchmark, generate_embeddings):
+    """
+    Benchmarks O(N^2) similarity matrix calculation
+    and heatmap renderin.
+    """
+
+    viz = EmbeddingVisualizer()
+    embeddings = generate_embeddings(n_samples=500, n_features=64)
+
+    def run():
+        return viz.visualize_similarity_heatmap(embeddings, output="interactive")
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/visualization/test_kg_viz.py

@@ -0,0 +1,33 @@
+import pytest
+
+from semantica.visualization.kg_visualizer import KGVisualizer
+
+
+@pytest.mark.benchmark(group="graph_layouyt")
+@pytest.mark.parametrize("layout", ["circular", "force"])
+@pytest.mark.parametrize("size", [100])
+def test_network_layout_performance(benchmark, generate_knowledge_graph, layout, size):
+    """
+    Compares layout algorithm.
+    """
+    viz = KGVisualizer(layout=layout, force_layout_iterations=50)
+    graph = generate_knowledge_graph(n_nodes=size)
+
+    def run():
+        return viz.visualize_network(graph, output="interactive")
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="graph_structure")
+def test_matrix_view_rendering(benchmark, generate_knowledge_graph):
+    """
+    Benchmarks the creation of an adjacent/relationship matrix.
+    """
+    viz = KGVisualizer()
+    graph = generate_knowledge_graph(n_nodes=500)
+
+    def run():
+        return viz.visualize_relationship_matrix(graph, output="interactive")
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

benchmarks/visualization/test_temporal_viz.py

@@ -0,0 +1,39 @@
+import pytest
+
+from semantica.visualization.temporal_visualizer import TemporalVisualizer
+
+
+@pytest.mark.benchmark(group="temporal_animation")
+def test_network_evolution_frames(benchmark, generate_temporal_data):
+    """
+    Measures the cost of generating animation frames for Plotly.
+    """
+
+    temporal_data = generate_temporal_data(n_snapshots=5, n_nodes=100)
+    viz = TemporalVisualizer()
+
+    def run():
+        return viz.visualize_network_evolution(temporal_data, output="interactive")
+
+    benchmark.pedantic(run, iterations=1, rounds=5)
+
+
+@pytest.mark.benchmark(group="temporal_dashboard")
+def test_temporal_dashboard_assembly(benchmark, generate_temporal_data):
+    """
+    Benchmarks the creation of a multi-subplot dashboard.
+    """
+    temporal_data = generate_temporal_data(n_snapshots=20, n_nodes=200)
+    viz = TemporalVisualizer()
+
+    metrics = {
+        "Accuracy": [0.5 + i * 0.02 for i in range(20)],
+        "Loss": [1.0 - i * 0.04 for i in range(20)],
+    }
+
+    def run():
+        return viz.visualize_temporal_dashboard(
+            temporal_data, metrics=metrics, output="interactive"
+        )
+
+    benchmark.pedantic(run, iterations=1, rounds=5)

cookbook/advanced/snowflake_ingestion_examples.py

@@ -0,0 +1,411 @@
+"""
+Snowflake Ingestion Examples
+
+This module provides comprehensive examples of using the Snowflake ingestor.
+"""
+
+import os
+from datetime import datetime, timedelta
+
+from semantica.ingest import SnowflakeIngestor
+from semantica.utils.logging import get_logger
+
+logger = get_logger("snowflake_examples")
+
+
+def example_basic_ingestion():
+    """Example: Basic table ingestion."""
+    print("\n=== Example 1: Basic Table Ingestion ===\n")
+
+    # Initialize ingestor with password authentication
+    ingestor = SnowflakeIngestor(
+        account=os.getenv("SNOWFLAKE_ACCOUNT"),
+        user=os.getenv("SNOWFLAKE_USER"),
+        password=os.getenv("SNOWFLAKE_PASSWORD"),
+        warehouse="COMPUTE_WH",
+        database="SAMPLE_DB",
+        schema="PUBLIC",
+    )
+
+    # Ingest a table
+    data = ingestor.ingest_table("CUSTOMERS", limit=10)
+
+    print(f"Retrieved {data.row_count} rows")
+    print(f"Columns: {data.columns}")
+    print(f"\nFirst row:")
+    print(data.data[0])
+
+    ingestor.close()
+
+
+def example_query_execution():
+    """Example: Execute custom SQL queries."""
+    print("\n=== Example 2: Query Execution ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Execute aggregation query
+    query = """
+        SELECT 
+            COUNTRY,
+            COUNT(*) AS CUSTOMER_COUNT,
+            SUM(TOTAL_PURCHASES) AS TOTAL_REVENUE
+        FROM CUSTOMERS
+        GROUP BY COUNTRY
+        ORDER BY TOTAL_REVENUE DESC
+        LIMIT 10
+    """
+
+    data = ingestor.ingest_query(query)
+
+    print(f"Top 10 countries by revenue:")
+    for row in data.data:
+        print(
+            f"  {row['COUNTRY']}: {row['CUSTOMER_COUNT']} customers, "
+            f"${row['TOTAL_REVENUE']:,.2f} revenue"
+        )
+
+    ingestor.close()
+
+
+def example_parameterized_query():
+    """Example: Parameterized queries."""
+    print("\n=== Example 3: Parameterized Queries ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Calculate date range
+    end_date = datetime.now()
+    start_date = end_date - timedelta(days=30)
+
+    # Execute parameterized query
+    query = """
+        SELECT 
+            ORDER_ID,
+            CUSTOMER_ID,
+            PRODUCT_NAME,
+            AMOUNT,
+            ORDER_DATE
+        FROM ORDERS
+        WHERE ORDER_DATE BETWEEN %(start_date)s AND %(end_date)s
+          AND AMOUNT > %(min_amount)s
+        ORDER BY ORDER_DATE DESC
+    """
+
+    data = ingestor.ingest_query(
+        query,
+        params={
+            "start_date": start_date.strftime("%Y-%m-%d"),
+            "end_date": end_date.strftime("%Y-%m-%d"),
+            "min_amount": 100.0,
+        },
+    )
+
+    print(f"Found {data.row_count} orders in the last 30 days over $100")
+
+    ingestor.close()
+
+
+def example_schema_introspection():
+    """Example: Table schema introspection."""
+    print("\n=== Example 4: Schema Introspection ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Get table schema
+    schema = ingestor.get_table_schema("CUSTOMERS")
+
+    print("Table schema for CUSTOMERS:")
+    print(f"Primary keys: {schema['primary_keys']}\n")
+
+    print("Columns:")
+    for col in schema["columns"]:
+        nullable = "NULL" if col["nullable"] else "NOT NULL"
+        default = f" DEFAULT {col['default']}" if col["default"] else ""
+        print(f"  {col['name']}: {col['type']} {nullable}{default}")
+
+    ingestor.close()
+
+
+def example_list_tables():
+    """Example: List all tables in a schema."""
+    print("\n=== Example 5: List Tables ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # List tables in current schema
+    tables = ingestor.list_tables()
+
+    print(f"Found {len(tables)} tables:")
+    for table in tables:
+        print(f"  - {table}")
+
+    ingestor.close()
+
+
+def example_pagination():
+    """Example: Paginate large result sets."""
+    print("\n=== Example 6: Pagination ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    PAGE_SIZE = 100
+    total_rows = 0
+
+    # Paginate through large table
+    page = 0
+    while True:
+        data = ingestor.ingest_table(
+            "LARGE_TABLE", limit=PAGE_SIZE, offset=page * PAGE_SIZE
+        )
+
+        if data.row_count == 0:
+            break
+
+        total_rows += data.row_count
+        print(f"Page {page + 1}: {data.row_count} rows")
+
+        # Process page
+        process_page(data)
+
+        page += 1
+
+    print(f"\nTotal rows processed: {total_rows}")
+
+    ingestor.close()
+
+
+def example_batch_processing():
+    """Example: Batch processing with fetchmany."""
+    print("\n=== Example 7: Batch Processing ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Execute query with batching
+    data = ingestor.ingest_query(
+        "SELECT * FROM LARGE_TABLE WHERE STATUS = 'ACTIVE'", batch_size=1000
+    )
+
+    print(f"Retrieved {data.row_count} rows in batches of 1000")
+
+    ingestor.close()
+
+
+def example_export_documents():
+    """Example: Export to Semantica document format."""
+    print("\n=== Example 8: Export as Documents ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Ingest product data
+    data = ingestor.ingest_table("PRODUCTS", limit=10)
+
+    # Convert to documents
+    documents = ingestor.export_as_documents(
+        data, id_field="PRODUCT_ID", text_fields=["PRODUCT_NAME", "DESCRIPTION"]
+    )
+
+    print(f"Exported {len(documents)} documents")
+    print("\nFirst document:")
+    print(f"  ID: {documents[0]['id']}")
+    print(f"  Text: {documents[0]['text'][:100]}...")
+    print(f"  Metadata: {documents[0]['metadata']}")
+
+    ingestor.close()
+
+
+def example_key_pair_auth():
+    """Example: Key-pair authentication."""
+    print("\n=== Example 9: Key-Pair Authentication ===\n")
+
+    ingestor = SnowflakeIngestor(
+        account=os.getenv("SNOWFLAKE_ACCOUNT"),
+        user=os.getenv("SNOWFLAKE_USER"),
+        private_key_path=os.getenv("SNOWFLAKE_PRIVATE_KEY_PATH"),
+        warehouse="COMPUTE_WH",
+    )
+
+    data = ingestor.ingest_table("CUSTOMERS", limit=5)
+    print(f"Successfully authenticated and retrieved {data.row_count} rows")
+
+    ingestor.close()
+
+
+def example_context_manager():
+    """Example: Using context manager."""
+    print("\n=== Example 10: Context Manager ===\n")
+
+    with SnowflakeIngestor() as ingestor:
+        data = ingestor.ingest_table("CUSTOMERS", limit=5)
+        print(f"Retrieved {data.row_count} rows")
+
+    # Connection automatically closed
+    print("Connection closed automatically")
+
+
+def example_multi_schema():
+    """Example: Multi-schema ingestion."""
+    print("\n=== Example 11: Multi-Schema Ingestion ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Ingest from different schemas
+    prod_customers = ingestor.ingest_table(
+        "CUSTOMERS", database="PROD_DB", schema="PUBLIC", limit=10
+    )
+
+    staging_customers = ingestor.ingest_table(
+        "CUSTOMERS", database="STAGING_DB", schema="PUBLIC", limit=10
+    )
+
+    print(f"Production customers: {prod_customers.row_count}")
+    print(f"Staging customers: {staging_customers.row_count}")
+
+    ingestor.close()
+
+
+def example_error_handling():
+    """Example: Error handling."""
+    print("\n=== Example 12: Error Handling ===\n")
+
+    from semantica.utils.exceptions import ProcessingError, ValidationError
+
+    try:
+        # Try to connect with invalid credentials
+        ingestor = SnowflakeIngestor(
+            account="invalid_account", user="invalid_user", password="invalid_password"
+        )
+
+        data = ingestor.ingest_table("CUSTOMERS")
+
+    except ValidationError as e:
+        print(f"Validation error: {e}")
+
+    except ProcessingError as e:
+        print(f"Processing error: {e}")
+
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+
+
+def example_incremental_load():
+    """Example: Incremental data loading."""
+    print("\n=== Example 13: Incremental Loading ===\n")
+
+    ingestor = SnowflakeIngestor()
+
+    # Get last load timestamp (from your metadata store)
+    last_load = get_last_load_timestamp()  # Your function
+
+    # Query only new/updated records
+    query = """
+        SELECT *
+        FROM CUSTOMERS
+        WHERE UPDATED_AT > %(last_load)s
+        ORDER BY UPDATED_AT ASC
+    """
+
+    data = ingestor.ingest_query(query, params={"last_load": last_load})
+
+    print(f"Loaded {data.row_count} new/updated records since {last_load}")
+
+    # Update last load timestamp
+    if data.row_count > 0:
+        update_last_load_timestamp(datetime.now())
+
+    ingestor.close()
+
+
+def example_etl_pipeline():
+    """Example: Full ETL pipeline."""
+    print("\n=== Example 14: ETL Pipeline ===\n")
+
+    # Extract
+    ingestor = SnowflakeIngestor()
+
+    sales_query = """
+        SELECT 
+            s.ORDER_ID,
+            s.CUSTOMER_ID,
+            c.CUSTOMER_NAME,
+            s.PRODUCT_ID,
+            p.PRODUCT_NAME,
+            s.AMOUNT,
+            s.ORDER_DATE
+        FROM SALES s
+        JOIN CUSTOMERS c ON s.CUSTOMER_ID = c.ID
+        JOIN PRODUCTS p ON s.PRODUCT_ID = p.ID
+        WHERE s.ORDER_DATE >= CURRENT_DATE - 7
+    """
+
+    data = ingestor.ingest_query(sales_query)
+    print(f"Extracted {data.row_count} sales records")
+
+    # Transform
+    documents = ingestor.export_as_documents(
+        data, id_field="ORDER_ID", text_fields=["CUSTOMER_NAME", "PRODUCT_NAME"]
+    )
+    print(f"Transformed to {len(documents)} documents")
+
+    # Load (into Semantica)
+    from semantica.pipeline import Pipeline
+
+    pipeline = Pipeline()
+
+    for doc in documents:
+        pipeline.process_document(doc)
+
+    print("Loaded documents into Semantica pipeline")
+
+    ingestor.close()
+
+
+# Utility functions for examples
+def process_page(data):
+    """Process a page of data."""
+    # Your processing logic here
+    pass
+
+
+def get_last_load_timestamp():
+    """Get the last load timestamp from metadata store."""
+    # Your implementation here
+    return (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def update_last_load_timestamp(timestamp):
+    """Update the last load timestamp in metadata store."""
+    # Your implementation here
+    pass
+
+
+def main():
+    """Run all examples."""
+    examples = [
+        example_basic_ingestion,
+        example_query_execution,
+        example_parameterized_query,
+        example_schema_introspection,
+        example_list_tables,
+        example_export_documents,
+        example_context_manager,
+        example_error_handling,
+    ]
+
+    for example_func in examples:
+        try:
+            example_func()
+        except Exception as e:
+            logger.error(f"Example {example_func.__name__} failed: {e}")
+
+
+if __name__ == "__main__":
+    # Set up environment variables
+    # export SNOWFLAKE_ACCOUNT=your_account
+    # export SNOWFLAKE_USER=your_user
+    # export SNOWFLAKE_PASSWORD=your_password
+    # export SNOWFLAKE_WAREHOUSE=COMPUTE_WH
+    # export SNOWFLAKE_DATABASE=SAMPLE_DB
+    # export SNOWFLAKE_SCHEMA=PUBLIC
+
+    main()

cookbook/integrations/agno_decision_intelligence.ipynb

@@ -0,0 +1,534 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Agno × Semantica: Decision Intelligence Agent\n",
+    "\n",
+    "This notebook shows how to wire Semantica's **Decision Intelligence** stack into an Agno agent so it can:\n",
+    "\n",
+    "- Record every decision it makes with full reasoning provenance\n",
+    "- Search historical precedents before acting\n",
+    "- Validate decisions against policy rules\n",
+    "- Trace causal chains across decisions\n",
+    "- Accumulate institutional knowledge that survives across sessions\n",
+    "\n",
+    "**Domain used:** Financial loan underwriting (easily adapted to healthcare, legal, HR, etc.)\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Architecture\n",
+    "\n",
+    "```\n",
+    "Agno Agent\n",
+    "  ├── memory=AgnoContextStore       ← graph-backed persistent memory\n",
+    "  └── tools=[AgnoDecisionKit]       ← decision tools the LLM can call\n",
+    "          │\n",
+    "          ├── record_decision       ← Semantica AgentContext.record_decision()\n",
+    "          ├── find_precedents       ← Semantica AgentContext.find_precedents_advanced()\n",
+    "          ├── trace_causal_chain    ← Semantica ContextGraph.trace_decision_causality()\n",
+    "          ├── analyze_impact        ← Semantica AgentContext.analyze_decision_influence()\n",
+    "          ├── check_policy          ← Semantica PolicyEngine\n",
+    "          └── get_decision_summary  ← Semantica AgentContext.get_context_insights()\n",
+    "```\n",
+    "\n",
+    "## Install\n",
+    "\n",
+    "```bash\n",
+    "pip install semantica[agno]\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "setup-section",
+   "metadata": {},
+   "source": [
+    "## 1. Setup — Semantica Backends\n",
+    "\n",
+    "We build the Semantica components first.  These are **independent of Agno** — you can swap backends without touching agent code."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys, os\n",
+    "sys.path.insert(0, os.path.abspath(\"../../\"))\n",
+    "\n",
+    "# ── Semantica core (not Agno-specific) ──────────────────────────────────────\n",
+    "from semantica.context import AgentContext, ContextGraph\n",
+    "from semantica.context import PolicyEngine, DecisionQuery, CausalChainAnalyzer\n",
+    "from semantica.vector_store import VectorStore\n",
+    "\n",
+    "# ── Agno integration layer ───────────────────────────────────────────────────\n",
+    "from integrations.agno import AgnoContextStore, AgnoDecisionKit, AGNO_AVAILABLE\n",
+    "\n",
+    "print(f\"Semantica imports OK\")\n",
+    "print(f\"Agno installed: {AGNO_AVAILABLE}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "semantica-backends",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Vector store (FAISS, no external service needed) ────────────────────────\n",
+    "vector_store = VectorStore(backend=\"faiss\", dimension=768)\n",
+    "print(\"VectorStore ready (FAISS)\")\n",
+    "\n",
+    "# ── In-memory context graph with full analytics ──────────────────────────────\n",
+    "knowledge_graph = ContextGraph(\n",
+    "    advanced_analytics=True,\n",
+    "    # Switch to neo4j for production:\n",
+    "    # backend=\"neo4j\", uri=\"bolt://localhost:7687\"\n",
+    ")\n",
+    "print(\"ContextGraph ready (in-memory)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "seed-section",
+   "metadata": {},
+   "source": [
+    "## 2. Seed Historical Decisions\n",
+    "\n",
+    "Before the agent runs, we pre-load historical decisions using **native Semantica APIs** so the precedent database is warm.\n",
+    "\n",
+    "In production you would ingest from a database or a prior session's graph export."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "seed-decisions",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Build a pure-Semantica AgentContext for seeding historical data\n",
+    "seed_context = AgentContext(\n",
+    "    vector_store=vector_store,\n",
+    "    knowledge_graph=knowledge_graph,\n",
+    "    decision_tracking=True,\n",
+    ")\n",
+    "\n",
+    "historical_loans = [\n",
+    "    dict(\n",
+    "        category=\"loan_approval\",\n",
+    "        scenario=\"Applicant: credit score 740, income $95k, DTI 28%, down payment 20%\",\n",
+    "        reasoning=\"Strong credit history, debt load well below 35% threshold, adequate down payment\",\n",
+    "        outcome=\"approved\",\n",
+    "        confidence=0.96,\n",
+    "    ),\n",
+    "    dict(\n",
+    "        category=\"loan_approval\",\n",
+    "        scenario=\"Applicant: credit score 620, income $45k, DTI 42%, down payment 5%\",\n",
+    "        reasoning=\"Credit score below 650 floor, DTI exceeds 40% maximum, insufficient down payment\",\n",
+    "        outcome=\"rejected\",\n",
+    "        confidence=0.97,\n",
+    "    ),\n",
+    "    dict(\n",
+    "        category=\"loan_approval\",\n",
+    "        scenario=\"Applicant: credit score 700, income $72k, DTI 33%, down payment 15%\",\n",
+    "        reasoning=\"Adequate credit, moderate DTI within range, down payment slightly below ideal\",\n",
+    "        outcome=\"approved_with_conditions\",\n",
+    "        confidence=0.82,\n",
+    "    ),\n",
+    "    dict(\n",
+    "        category=\"loan_approval\",\n",
+    "        scenario=\"Applicant: credit score 780, income $130k, DTI 22%, down payment 30%\",\n",
+    "        reasoning=\"Excellent credit, low debt load, strong down payment — low-risk profile\",\n",
+    "        outcome=\"approved\",\n",
+    "        confidence=0.99,\n",
+    "    ),\n",
+    "    dict(\n",
+    "        category=\"loan_approval\",\n",
+    "        scenario=\"Applicant: credit score 660, income $58k, DTI 38%, down payment 10%\",\n",
+    "        reasoning=\"Borderline credit, high DTI, minimal down payment — escalated to senior review\",\n",
+    "        outcome=\"escalated\",\n",
+    "        confidence=0.70,\n",
+    "    ),\n",
+    "]\n",
+    "\n",
+    "for loan in historical_loans:\n",
+    "    did = seed_context.record_decision(**loan)\n",
+    "    print(f\"  Seeded [{loan['outcome']:25s}] → {did}\")\n",
+    "\n",
+    "print(f\"\\n{len(historical_loans)} historical decisions loaded into Semantica KG\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "policy-section",
+   "metadata": {},
+   "source": [
+    "## 3. Define Policy Rules with Semantica\n",
+    "\n",
+    "We use `PolicyEngine` directly — no Agno involvement here.  The `AgnoDecisionKit.check_policy` tool will call this engine during the agent's reasoning loop."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "policy",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "LENDING_POLICY_RULES = [\n",
+    "    \"credit_score >= 650\",\n",
+    "    \"dti <= 40\",\n",
+    "    \"down_payment_pct >= 10\",\n",
+    "    \"confidence >= 0.70\",\n",
+    "]\n",
+    "\n",
+    "# Verify directly with Semantica's PolicyEngine before wiring to Agno\n",
+    "policy_engine = PolicyEngine(graph_store=knowledge_graph)\n",
+    "\n",
+    "test_application = {\"credit_score\": 720, \"dti\": 31, \"down_payment_pct\": 18, \"confidence\": 0.88}\n",
+    "\n",
+    "try:\n",
+    "    result = policy_engine.check_compliance(test_application, LENDING_POLICY_RULES)\n",
+    "    print(f\"Policy check result: compliant={getattr(result, 'compliant', 'N/A')}\")\n",
+    "    print(f\"Violations: {getattr(result, 'violations', [])}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"PolicyEngine fallback (expected without full rule engine): {e}\")\n",
+    "\n",
+    "print(\"\\nPolicy rules defined:\", LENDING_POLICY_RULES)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "agent-section",
+   "metadata": {},
+   "source": [
+    "## 4. Build the Agno Decision-Intelligence Agent\n",
+    "\n",
+    "Now we wire everything into Agno using the integration classes.\n",
+    "\n",
+    "- `AgnoContextStore` gives the agent **persistent graph-backed memory**\n",
+    "- `AgnoDecisionKit` exposes **6 decision tools** the LLM can invoke during reasoning"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-agent",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── AgnoContextStore: wraps AgentContext as Agno MemoryDb ────────────────────\n",
+    "store = AgnoContextStore(\n",
+    "    vector_store=vector_store,       # Same store — shares seeded decisions\n",
+    "    knowledge_graph=knowledge_graph, # Same graph — shares seeded decisions\n",
+    "    decision_tracking=True,\n",
+    "    graph_expansion=True,\n",
+    "    session_id=\"loan_underwriter_v1\",\n",
+    ")\n",
+    "print(\"AgnoContextStore ready\")\n",
+    "\n",
+    "# ── AgnoDecisionKit: exposes Semantica decision tools to Agno's LLM ──────────\n",
+    "decision_kit = AgnoDecisionKit(\n",
+    "    context=store.context,    # Reuse same AgentContext — shared decision history\n",
+    "    max_precedents=5,\n",
+    "    causal_depth=3,\n",
+    "    enable_policy_check=True,\n",
+    ")\n",
+    "print(f\"AgnoDecisionKit ready — {len(decision_kit._tools)} tools registered\")\n",
+    "print(\"  Tools:\", [fn.__name__ for fn in decision_kit._tools])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "wire-agent",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if AGNO_AVAILABLE:\n",
+    "    from agno.agent import Agent\n",
+    "    from agno.memory import AgentMemory\n",
+    "    from agno.models.openai import OpenAIChat  # or any Agno-supported model\n",
+    "\n",
+    "    agent = Agent(\n",
+    "        name=\"LoanUnderwriter\",\n",
+    "        model=OpenAIChat(id=\"gpt-4o\"),\n",
+    "        memory=AgentMemory(db=store),\n",
+    "        tools=[decision_kit],\n",
+    "        show_tool_calls=True,\n",
+    "        description=(\n",
+    "            \"You are a senior loan underwriter. Before approving or rejecting any application:\"\n",
+    "            \" (1) find_precedents for similar past cases,\"\n",
+    "            \" (2) check_policy compliance,\"\n",
+    "            \" (3) record_decision with full reasoning.\"\n",
+    "            \" Always cite precedents and policy rule results in your explanation.\"\n",
+    "        ),\n",
+    "    )\n",
+    "    print(\"Agno Agent assembled and ready\")\n",
+    "else:\n",
+    "    print(\"Agno not installed — demonstrating tool calls directly below\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "demo-section",
+   "metadata": {},
+   "source": [
+    "## 5. Demonstrate Decision Tools\n",
+    "\n",
+    "We call the decision tools **directly** so the notebook is fully runnable without an OpenAI key.  When Agno is wired, the LLM orchestrates these same calls automatically."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-find-precedents",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "\n",
+    "# ── 5a. Find Precedents ───────────────────────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TOOL: find_precedents\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "new_application_scenario = (\n",
+    "    \"Applicant: credit score 715, income $82k, DTI 30%, down payment 18%\"\n",
+    ")\n",
+    "\n",
+    "precedents_json = decision_kit.find_precedents(\n",
+    "    scenario=new_application_scenario,\n",
+    "    category=\"loan_approval\",\n",
+    "    limit=3,\n",
+    ")\n",
+    "precedents = json.loads(precedents_json)\n",
+    "print(f\"Found {precedents['count']} similar past decisions:\")\n",
+    "for p in precedents['precedents']:\n",
+    "    print(f\"  [{p.get('outcome','?'):25s}] confidence={p.get('confidence',0):.2f}\")\n",
+    "    print(f\"    {p.get('scenario','')[:80]}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-policy",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── 5b. Check Policy ─────────────────────────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TOOL: check_policy\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "decision_data = json.dumps({\n",
+    "    \"credit_score\": 715,\n",
+    "    \"dti\": 30,\n",
+    "    \"down_payment_pct\": 18,\n",
+    "    \"confidence\": 0.88,\n",
+    "    \"outcome\": \"approved\",\n",
+    "})\n",
+    "\n",
+    "policy_json = decision_kit.check_policy(\n",
+    "    decision_data=decision_data,\n",
+    "    policy_rules=json.dumps(LENDING_POLICY_RULES),\n",
+    ")\n",
+    "policy_result = json.loads(policy_json)\n",
+    "print(f\"Compliant: {policy_result.get('compliant')}\")\n",
+    "print(f\"Violations: {policy_result.get('violations', [])}\")\n",
+    "print(f\"Warnings:   {policy_result.get('warnings', [])}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-record",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── 5c. Record Decision ──────────────────────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TOOL: record_decision\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "record_json = decision_kit.record_decision(\n",
+    "    category=\"loan_approval\",\n",
+    "    scenario=new_application_scenario,\n",
+    "    reasoning=(\n",
+    "        \"3 similar precedents found — 2 approved, 1 escalated. \"\n",
+    "        \"Credit score 715 exceeds 650 floor. DTI 30% well within 40% limit. \"\n",
+    "        \"Down payment 18% above 10% minimum. All policy rules satisfied.\"\n",
+    "    ),\n",
+    "    outcome=\"approved\",\n",
+    "    confidence=0.91,\n",
+    "    entities=\"loan_applicant, credit_bureau, lending_policy_v2\",\n",
+    ")\n",
+    "record_result = json.loads(record_json)\n",
+    "decision_id = record_result['decision_id']\n",
+    "print(f\"Decision recorded: {decision_id}\")\n",
+    "print(f\"Status: {record_result['status']}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-impact",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── 5d. Analyze Impact ───────────────────────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TOOL: analyze_impact\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "impact_json = decision_kit.analyze_impact(decision_id=decision_id)\n",
+    "impact = json.loads(impact_json)\n",
+    "print(\"Impact analysis:\")\n",
+    "for k, v in impact.items():\n",
+    "    if k != \"decision_id\":\n",
+    "        print(f\"  {k}: {v}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-summary",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── 5e. Decision Summary ─────────────────────────────────────────────────────\n",
+    "print(\"=\" * 60)\n",
+    "print(\"TOOL: get_decision_summary\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "summary_json = decision_kit.get_decision_summary(category=\"loan_approval\")\n",
+    "summary = json.loads(summary_json)\n",
+    "print(\"Decision history summary:\")\n",
+    "for k, v in summary.items():\n",
+    "    if k not in (\"category_filter\",):\n",
+    "        print(f\"  {k}: {v}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "agno-run-section",
+   "metadata": {},
+   "source": [
+    "## 6. Run the Full Agno Agent (requires API key)\n",
+    "\n",
+    "When `AGNO_AVAILABLE=True` and an OpenAI key is set, the LLM orchestrates all the tool calls automatically."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "run-agent",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "NEW_CASE = (\n",
+    "    \"New mortgage application received:\\n\"\n",
+    "    \"  Credit score: 715, Annual income: $82,000\\n\"\n",
+    "    \"  Debt-to-income: 30%, Down payment: 18%\\n\"\n",
+    "    \"  Loan amount: $320,000 for a primary residence in Austin TX\\n\"\n",
+    "    \"Should we approve this application?\"\n",
+    ")\n",
+    "\n",
+    "if AGNO_AVAILABLE:\n",
+    "    agent.print_response(NEW_CASE)\n",
+    "else:\n",
+    "    print(\"[Agno not installed — skipping live agent run]\")\n",
+    "    print()\n",
+    "    print(\"Expected agent reasoning flow:\")\n",
+    "    print(\"  1. find_precedents('credit score 715, DTI 30%, down payment 18%')\")\n",
+    "    print(\"     → 2 approved, 1 escalated among similar cases\")\n",
+    "    print(\"  2. check_policy(credit_score=715, dti=30, down_payment_pct=18)\")\n",
+    "    print(\"     → compliant=True, violations=[]\")\n",
+    "    print(\"  3. record_decision(outcome='approved', confidence=0.91)\")\n",
+    "    print(\"     → decision_id recorded in Semantica KG\")\n",
+    "    print()\n",
+    "    print(\"  Recommendation: APPROVE — 3 precedents + full policy compliance\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "analytics-section",
+   "metadata": {},
+   "source": [
+    "## 7. Post-Session Analytics with Semantica\n",
+    "\n",
+    "After the agent session, use **native Semantica APIs** for reporting and causal analysis — no Agno required."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "analytics",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Query decision history directly from Semantica\n",
+    "insights = store.context.get_context_insights()\n",
+    "print(\"Session Insights (Semantica native):\")\n",
+    "if isinstance(insights, dict):\n",
+    "    for k, v in insights.items():\n",
+    "        print(f\"  {k}: {v}\")\n",
+    "else:\n",
+    "    print(f\"  {insights}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "precedents-direct",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Precedent search directly via Semantica's AgentContext\n",
+    "# (same data, no Agno in the loop)\n",
+    "precedents = store.context.find_precedents_advanced(\n",
+    "    scenario=\"borderline mortgage application\",\n",
+    "    category=\"loan_approval\",\n",
+    ")\n",
+    "print(f\"\\nPrecedent search via Semantica directly → {len(precedents or [])} results\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "summary-section",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| What | How |\n",
+    "|---|---|\n",
+    "| Persistent decision history | `AgnoContextStore` wrapping `AgentContext` + FAISS |\n",
+    "| Tool calls for decision intelligence | `AgnoDecisionKit` (record, find, trace, check, summarise) |\n",
+    "| Historical seeding | Native `AgentContext.record_decision()` — no Agno needed |\n",
+    "| Policy rules | Native `PolicyEngine` — no Agno needed |\n",
+    "| Post-session analytics | Native `AgentContext.get_context_insights()` — no Agno needed |\n",
+    "\n",
+    "The Agno integration is a **thin wrapper** — Semantica's full API remains directly accessible whenever you need finer control."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/integrations/agno_graphrag_context.ipynb

@@ -0,0 +1,615 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Agno × Semantica: GraphRAG Context Agent\n",
+    "\n",
+    "This notebook demonstrates how to give an Agno agent a **relational knowledge graph** instead of a flat document store.  The agent retrieves answers via **multi-hop graph traversal** — finding connections that pure vector search misses.\n",
+    "\n",
+    "**Domain:** Regulatory compliance (Basel IV / DORA) — documents are ingested, entities & relations extracted, then the agent answers questions by hopping through the graph.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Architecture\n",
+    "\n",
+    "```\n",
+    "Agno Agent\n",
+    "  ├── knowledge=AgnoKnowledgeGraph       ← GraphRAG knowledge base\n",
+    "  └── tools=[AgnoKGToolkit]              ← live graph building/query tools\n",
+    "          │\n",
+    "          │   Backed by Semantica:\n",
+    "          ├── NERExtractor               ← named entity recognition\n",
+    "          ├── RelationExtractor          ← relation extraction\n",
+    "          ├── GraphBuilder               ← builds ContextGraph from extractions\n",
+    "          ├── ContextGraph               ← in-memory graph with analytics\n",
+    "          └── Reasoner                   ← rule-based inference\n",
+    "```\n",
+    "\n",
+    "## Install\n",
+    "\n",
+    "```bash\n",
+    "pip install semantica[agno]\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "imports-section",
+   "metadata": {},
+   "source": [
+    "## 1. Imports — Semantica Core + Agno Integration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys, os, json\n",
+    "sys.path.insert(0, os.path.abspath(\"../../\"))\n",
+    "\n",
+    "# ── Semantica core — used directly for pipeline setup ───────────────────────\n",
+    "from semantica.kg import GraphBuilder\n",
+    "from semantica.context import ContextGraph\n",
+    "from semantica.semantic_extract import NERExtractor, RelationExtractor, TripletExtractor\n",
+    "from semantica.reasoning import Reasoner\n",
+    "from semantica.vector_store import VectorStore\n",
+    "\n",
+    "# ── Agno integration layer ───────────────────────────────────────────────────\n",
+    "from integrations.agno import AgnoKnowledgeGraph, AgnoKGToolkit, AGNO_AVAILABLE\n",
+    "\n",
+    "print(\"Semantica imports OK\")\n",
+    "print(f\"Agno installed: {AGNO_AVAILABLE}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "pipeline-section",
+   "metadata": {},
+   "source": [
+    "## 2. Build the Semantica Extraction Pipeline\n",
+    "\n",
+    "The extraction pipeline (NER → relation extraction → graph build) is pure Semantica.  We construct each component explicitly so we can also use them for analysis outside Agno."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-pipeline",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# NER — identifies organisations, regulations, dates, amounts, roles\n",
+    "ner = NERExtractor()\n",
+    "\n",
+    "# Relation extractor — finds typed edges between entities\n",
+    "rel_extractor = RelationExtractor(confidence_threshold=0.60)\n",
+    "\n",
+    "# Knowledge graph builder\n",
+    "graph_builder = GraphBuilder(merge_entities=True, temporal_support=True)\n",
+    "\n",
+    "# In-memory context graph (swap to neo4j/falkordb for persistence)\n",
+    "context_graph = ContextGraph(advanced_analytics=True)\n",
+    "\n",
+    "# Reasoner for rule inference over the graph\n",
+    "reasoner = Reasoner()\n",
+    "\n",
+    "print(\"Semantica extraction pipeline assembled\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ingest-raw-section",
+   "metadata": {},
+   "source": [
+    "## 3. Direct Semantica Extraction (Before Agno)\n",
+    "\n",
+    "We first demonstrate extraction using **raw Semantica APIs** so you can see exactly what goes into the graph.\n",
+    "This is the same pipeline `AgnoKnowledgeGraph.load()` runs internally."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "raw-documents",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Regulatory documents (representative snippets)\n",
+    "REGULATORY_DOCS = [\n",
+    "    {\n",
+    "        \"title\": \"Basel IV — Capital Requirements\",\n",
+    "        \"text\": (\n",
+    "            \"Basel IV introduces a revised standardised approach for credit risk, \"\n",
+    "            \"replacing internal model floors. Banks must maintain a minimum CET1 ratio \"\n",
+    "            \"of 4.5% and a total capital ratio of 8%. The BCBS finalised these requirements \"\n",
+    "            \"in December 2017 with a phased implementation starting January 2022. \"\n",
+    "            \"National regulators including the EBA and FCA are responsible for local \"\n",
+    "            \"transposition. Risk-weighted assets under Basel IV are calculated using \"\n",
+    "            \"the Output Floor, capping RWA reductions at 72.5%.\"\n",
+    "        ),\n",
+    "    },\n",
+    "    {\n",
+    "        \"title\": \"DORA — Digital Operational Resilience Act\",\n",
+    "        \"text\": (\n",
+    "            \"DORA (Regulation EU 2022/2554) applies to financial entities and ICT \"\n",
+    "            \"third-party service providers operating in the EU. It mandates ICT risk \"\n",
+    "            \"management frameworks, incident classification, and annual operational \"\n",
+    "            \"resilience testing. Supervised entities must report major ICT incidents to \"\n",
+    "            \"the European Supervisory Authorities (ESAs) within 4 hours of classification. \"\n",
+    "            \"Critical ICT providers are subject to direct oversight by the Joint Oversight \"\n",
+    "            \"Network led by ESMA, EBA, and EIOPA. DORA became applicable on 17 January 2025.\"\n",
+    "        ),\n",
+    "    },\n",
+    "    {\n",
+    "        \"title\": \"AML — Anti-Money Laundering Directive VI\",\n",
+    "        \"text\": (\n",
+    "            \"AMLD6 strengthens the EU's anti-money laundering framework by extending \"\n",
+    "            \"criminal liability to 22 predicate offences including cybercrime and \"\n",
+    "            \"environmental crime. Financial institutions must apply Customer Due Diligence \"\n",
+    "            \"(CDD) at onboarding and Enhanced Due Diligence (EDD) for high-risk customers. \"\n",
+    "            \"Suspicious Activity Reports (SARs) are filed with the national Financial \"\n",
+    "            \"Intelligence Unit (FIU). Non-compliance carries penalties up to 10% of \"\n",
+    "            \"annual global turnover. AMLD6 was transposed into UK law via MLCO 2020.\"\n",
+    "        ),\n",
+    "    },\n",
+    "]\n",
+    "\n",
+    "print(f\"Documents to ingest: {len(REGULATORY_DOCS)}\")\n",
+    "for doc in REGULATORY_DOCS:\n",
+    "    print(f\"  • {doc['title']}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "run-ner",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Run NER directly with Semantica ─────────────────────────────────────────\n",
+    "all_entities = []\n",
+    "for doc in REGULATORY_DOCS:\n",
+    "    entities = ner.extract_entities(doc['text']) or []\n",
+    "    all_entities.extend(entities)\n",
+    "    print(f\"[{doc['title']}] → {len(entities)} entities\")\n",
+    "    for e in entities[:4]:\n",
+    "        print(f\"    {getattr(e,'name','?'):30s}  type={getattr(e,'type','?')}  conf={getattr(e,'confidence',0):.2f}\")\n",
+    "\n",
+    "print(f\"\\nTotal entities extracted: {len(all_entities)}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "run-rel",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Run relation extraction directly with Semantica ──────────────────────────\n",
+    "all_relations = []\n",
+    "for doc in REGULATORY_DOCS:\n",
+    "    relations = rel_extractor.extract_relations(doc['text']) or []\n",
+    "    all_relations.extend(relations)\n",
+    "    print(f\"[{doc['title']}] → {len(relations)} relations\")\n",
+    "    for r in relations[:3]:\n",
+    "        src  = getattr(r, 'source', '?')\n",
+    "        rtype = getattr(r, 'type', getattr(r, 'relation', '?'))\n",
+    "        tgt  = getattr(r, 'target', '?')\n",
+    "        conf = getattr(r, 'confidence', 0)\n",
+    "        print(f\"    {src!s:20s} --[{rtype}]--> {tgt!s:20s}  conf={conf:.2f}\")\n",
+    "\n",
+    "print(f\"\\nTotal relations extracted: {len(all_relations)}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "agno-kg-section",
+   "metadata": {},
+   "source": [
+    "## 4. Build AgnoKnowledgeGraph\n",
+    "\n",
+    "`AgnoKnowledgeGraph` wraps the extraction pipeline and implements Agno's `AgentKnowledge` protocol.  It runs the same NER + relation extract + graph build pipeline internally — here we pass our pre-built components so the same instances are used."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-agno-kg",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "kg = AgnoKnowledgeGraph(\n",
+    "    graph_builder=graph_builder,\n",
+    "    ner_extractor=ner,\n",
+    "    relation_extractor=rel_extractor,\n",
+    "    context_graph=context_graph,\n",
+    "    num_documents=5,\n",
+    ")\n",
+    "\n",
+    "# Ingest all documents through the integration wrapper\n",
+    "kg.load(texts=[doc['text'] for doc in REGULATORY_DOCS])\n",
+    "\n",
+    "print(f\"AgnoKnowledgeGraph: {len(kg._docs)} documents indexed\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "graphrag-section",
+   "metadata": {},
+   "source": [
+    "## 5. GraphRAG Search\n",
+    "\n",
+    "The `search()` method implements **multi-hop GraphRAG**:\n",
+    "1. Vector similarity over stored document texts\n",
+    "2. Entity lookup in the context graph\n",
+    "3. Graph hop expansion for entity neighbourhood\n",
+    "4. Context injection into the returned documents"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "graphrag-search",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "queries = [\n",
+    "    \"What is the minimum CET1 ratio required under Basel IV?\",\n",
+    "    \"Which authorities supervise critical ICT providers under DORA?\",\n",
+    "    \"What are the reporting timelines for major ICT incidents?\",\n",
+    "    \"How does AMLD6 handle customer due diligence?\",\n",
+    "]\n",
+    "\n",
+    "for query in queries:\n",
+    "    print(f\"\\nQ: {query}\")\n",
+    "    results = kg.search(query, num_documents=2)\n",
+    "    print(f\"   Retrieved {len(results)} document(s)\")\n",
+    "    for i, doc in enumerate(results, 1):\n",
+    "        content = getattr(doc, 'content', str(doc))\n",
+    "        print(f\"   [{i}] {content[:120]}...\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "entity-context",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get graph context for a specific entity\n",
+    "entity_contexts = [\"BCBS\", \"EBA\", \"DORA\", \"Basel IV\"]\n",
+    "for entity in entity_contexts:\n",
+    "    ctx = kg.get_graph_context(entity)\n",
+    "    print(f\"\\nGraph context for '{entity}':\")\n",
+    "    print(ctx if ctx else \"  (no graph nodes found — depends on NER extraction quality)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "toolkit-section",
+   "metadata": {},
+   "source": [
+    "## 6. AgnoKGToolkit — Live Graph Building\n",
+    "\n",
+    "The `AgnoKGToolkit` exposes 7 tools the LLM can call to **actively modify and query the graph** during reasoning."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-toolkit",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "toolkit = AgnoKGToolkit(\n",
+    "    ner_extractor=ner,\n",
+    "    relation_extractor=rel_extractor,\n",
+    "    reasoner=reasoner,\n",
+    "    context=context_graph,  # share same graph as knowledge base\n",
+    ")\n",
+    "\n",
+    "print(f\"AgnoKGToolkit: {len(toolkit._tools)} tools\")\n",
+    "print(\"  Tools:\", [fn.__name__ for fn in toolkit._tools])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-extract-entities",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: extract_entities\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: extract_entities\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "new_text = (\n",
+    "    \"The PRA published a consultation paper requiring UK banks to \"\n",
+    "    \"implement DORA-equivalent resilience testing by Q3 2025, \"\n",
+    "    \"with Barclays and HSBC named as systemic institutions.\"\n",
+    ")\n",
+    "entities_json = toolkit.extract_entities(new_text)\n",
+    "entities_result = json.loads(entities_json)\n",
+    "print(f\"Found {entities_result['count']} entities:\")\n",
+    "for e in entities_result['entities']:\n",
+    "    print(f\"  {e['name']:30s}  type={e['type']:15s}  conf={e['confidence']:.2f}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-extract-relations",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: extract_relations\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: extract_relations\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "relations_json = toolkit.extract_relations(new_text)\n",
+    "relations_result = json.loads(relations_json)\n",
+    "print(f\"Found {relations_result['count']} relations:\")\n",
+    "for r in relations_result['relations']:\n",
+    "    print(f\"  {r['source']:20s} --[{r['relation']}]--> {r['target']:20s}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-add-graph",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: add_to_graph\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: add_to_graph\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "add_result = json.loads(toolkit.add_to_graph(\n",
+    "    entities=json.dumps([\n",
+    "        {\"name\": \"PRA\", \"type\": \"REGULATOR\"},\n",
+    "        {\"name\": \"Barclays\", \"type\": \"BANK\"},\n",
+    "        {\"name\": \"HSBC\", \"type\": \"BANK\"},\n",
+    "    ]),\n",
+    "    relations=json.dumps([\n",
+    "        {\"source\": \"PRA\", \"relation\": \"SUPERVISES\", \"target\": \"Barclays\"},\n",
+    "        {\"source\": \"PRA\", \"relation\": \"SUPERVISES\", \"target\": \"HSBC\"},\n",
+    "        {\"source\": \"Barclays\", \"relation\": \"SUBJECT_TO\", \"target\": \"DORA\"},\n",
+    "        {\"source\": \"HSBC\", \"relation\": \"SUBJECT_TO\", \"target\": \"DORA\"},\n",
+    "    ]),\n",
+    "))\n",
+    "print(f\"Added: {add_result['nodes_added']} nodes, {add_result['edges_added']} edges\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-query-graph",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: query_graph\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: query_graph\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "query_result = json.loads(toolkit.query_graph(\"PRA\"))\n",
+    "print(f\"Keyword query 'PRA' → {query_result['count']} node(s):\")\n",
+    "for node in query_result['results']:\n",
+    "    print(f\"  label={node.get('label')}  type={node.get('type')}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-find-related",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: find_related\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: find_related\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "related_result = json.loads(toolkit.find_related(\"Barclays\", hops=2))\n",
+    "print(f\"Related to 'Barclays' (2 hops): {related_result['count']} entity/entities\")\n",
+    "for name in related_result['related']:\n",
+    "    print(f\"  → {name}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-infer",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: infer_facts — Semantica's Reasoner derives new facts from graph state\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: infer_facts\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "# Rules: regulatory compliance inference\n",
+    "inference_rules = json.dumps([\n",
+    "    \"IF BANK(?x) THEN FinancialEntity(?x)\",\n",
+    "    \"IF REGULATOR(?x) THEN SupervisoryAuthority(?x)\",\n",
+    "    \"IF FinancialEntity(?x) THEN ComplianceSubject(?x)\",\n",
+    "])\n",
+    "\n",
+    "infer_result = json.loads(toolkit.infer_facts(rules=inference_rules))\n",
+    "print(f\"Inferred {infer_result['count']} new fact(s):\")\n",
+    "for fact in infer_result['inferred_facts'][:8]:\n",
+    "    print(f\"  {fact}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "demo-export",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# TOOL: export_subgraph — export knowledge for downstream systems\n",
+    "print(\"=\" * 55)\n",
+    "print(\"TOOL: export_subgraph (JSON-LD)\")\n",
+    "print(\"=\" * 55)\n",
+    "\n",
+    "export_result = json.loads(toolkit.export_subgraph(entity=\"DORA\", format=\"json-ld\"))\n",
+    "print(f\"Exported as format='{export_result['format']}'\")\n",
+    "if 'data' in export_result:\n",
+    "    preview = str(export_result['data'])[:300]\n",
+    "    print(f\"Preview: {preview}...\")\n",
+    "elif 'nodes' in export_result:\n",
+    "    print(f\"Graph nodes exported: {len(export_result['nodes'])}\")\n",
+    "    for node in export_result['nodes'][:5]:\n",
+    "        print(f\"  {node}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "agno-run-section",
+   "metadata": {},
+   "source": [
+    "## 7. Run the Full Agno GraphRAG Agent (requires API key)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "agno-agent",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if AGNO_AVAILABLE:\n",
+    "    from agno.agent import Agent\n",
+    "    from agno.models.openai import OpenAIChat\n",
+    "\n",
+    "    compliance_agent = Agent(\n",
+    "        name=\"ComplianceAnalyst\",\n",
+    "        model=OpenAIChat(id=\"gpt-4o\"),\n",
+    "        knowledge=kg,\n",
+    "        search_knowledge=True,\n",
+    "        tools=[toolkit],\n",
+    "        show_tool_calls=True,\n",
+    "        description=(\n",
+    "            \"You are a regulatory compliance analyst. Use the knowledge graph \"\n",
+    "            \"to answer questions about Basel IV, DORA, and AML regulations. \"\n",
+    "            \"When answering, use find_related and query_graph to discover \"\n",
+    "            \"connections between regulators, rules, and institutions.\"\n",
+    "        ),\n",
+    "    )\n",
+    "\n",
+    "    compliance_agent.print_response(\n",
+    "        \"Which supervisory authorities are responsible for overseeing DORA compliance \"\n",
+    "        \"for UK banks, and how does this relate to Basel IV capital requirements?\"\n",
+    "    )\n",
+    "else:\n",
+    "    print(\"[Agno not installed — skipping live agent run]\")\n",
+    "    print()\n",
+    "    print(\"Expected reasoning flow:\")\n",
+    "    print(\"  search_knowledge('DORA supervisory authorities UK banks')\")\n",
+    "    print(\"    → retrieves DORA doc with graph expansion\")\n",
+    "    print(\"  query_graph('PRA') → finds PRA node\")\n",
+    "    print(\"  find_related('PRA', hops=2) → PRA → SUPERVISES → Barclays, HSBC\")\n",
+    "    print(\"  find_related('Basel IV', hops=1) → capital ratio requirements\")\n",
+    "    print(\"  Answer: PRA supervises UK banks under DORA; Basel IV CET1 requirement is 4.5%\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "semantica-analysis",
+   "metadata": {},
+   "source": [
+    "## 8. Post-Session Graph Analysis with Semantica\n",
+    "\n",
+    "After the agent session, use Semantica's graph analytics directly to explore the accumulated knowledge."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "graph-analytics",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Use Semantica's GraphAnalyzer directly on the same ContextGraph\n",
+    "from semantica.kg import GraphAnalyzer, CentralityCalculator, PathFinder\n",
+    "\n",
+    "try:\n",
+    "    analyzer = GraphAnalyzer()\n",
+    "    analysis = analyzer.analyze_graph(context_graph)\n",
+    "    print(\"Graph analysis (Semantica native):\")\n",
+    "    if isinstance(analysis, dict):\n",
+    "        for k, v in list(analysis.items())[:8]:\n",
+    "            print(f\"  {k}: {v}\")\n",
+    "    else:\n",
+    "        print(f\"  {analysis}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"GraphAnalyzer: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "centrality",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Centrality — which entities are most connected / influential?\n",
+    "try:\n",
+    "    centrality = CentralityCalculator()\n",
+    "    scores = centrality.calculate_degree_centrality(context_graph)\n",
+    "    print(\"Degree centrality (most connected entities):\")\n",
+    "    if isinstance(scores, dict):\n",
+    "        top = sorted(scores.items(), key=lambda x: x[1], reverse=True)[:5]\n",
+    "        for entity, score in top:\n",
+    "            print(f\"  {entity:30s} {score:.4f}\")\n",
+    "    else:\n",
+    "        print(f\"  {scores}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"CentralityCalculator: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "summary-section",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Component | Role | Library |\n",
+    "|---|---|---|\n",
+    "| `NERExtractor` | Extract regulatory entities from text | Semantica |\n",
+    "| `RelationExtractor` | Extract typed edges between entities | Semantica |\n",
+    "| `GraphBuilder` | Build `ContextGraph` from extractions | Semantica |\n",
+    "| `Reasoner` | Infer new facts from graph state | Semantica |\n",
+    "| `AgnoKnowledgeGraph` | GraphRAG `AgentKnowledge` interface | Agno integration |\n",
+    "| `AgnoKGToolkit` | 7 live graph tools for the Agno LLM | Agno integration |\n",
+    "| `GraphAnalyzer` / `CentralityCalculator` | Post-session analytics | Semantica |\n",
+    "\n",
+    "The Agno integration wraps Semantica components — the full Semantica API is available for pre/post-processing and analytics independently of the agent."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/integrations/agno_multi_agent_shared_context.ipynb

@@ -0,0 +1,676 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Agno × Semantica: Multi-Agent Shared Context\n",
+    "\n",
+    "This notebook shows how an Agno **Team** of specialist agents can share a single `ContextGraph` so they:\n",
+    "\n",
+    "- Never make contradictory decisions\n",
+    "- Reuse each other's extracted knowledge without coupling implementations\n",
+    "- Maintain a full causal audit trail across all agents\n",
+    "\n",
+    "**Scenario:** A product strategy team with three specialist agents:\n",
+    "\n",
+    "| Agent | Role | Tools |\n",
+    "|---|---|---|\n",
+    "| `Researcher` | Extracts competitive intelligence from text | `AgnoKGToolkit` |\n",
+    "| `Analyst` | Evaluates opportunities and records decisions | `AgnoDecisionKit` |\n",
+    "| `Strategist` | Synthesises both into a recommendation | both |\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Architecture\n",
+    "\n",
+    "```\n",
+    "AgnoSharedContext (single ContextGraph + VectorStore)\n",
+    "   │\n",
+    "   ├── bind_agent(\"researcher\")  → AgnoContextStore (role-scoped)\n",
+    "   ├── bind_agent(\"analyst\")     → AgnoContextStore (role-scoped)\n",
+    "   └── bind_agent(\"strategist\")  → AgnoContextStore (role-scoped)\n",
+    "\n",
+    "Agno Team\n",
+    "   ├── Researcher  memory=researcher_store  tools=[AgnoKGToolkit(context=shared)]\n",
+    "   ├── Analyst     memory=analyst_store     tools=[AgnoDecisionKit(context=shared)]\n",
+    "   └── Strategist  memory=strategist_store  tools=[AgnoKGToolkit, AgnoDecisionKit]\n",
+    "```\n",
+    "\n",
+    "## Install\n",
+    "\n",
+    "```bash\n",
+    "pip install semantica[agno]\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "imports-section",
+   "metadata": {},
+   "source": [
+    "## 1. Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys, os, json\n",
+    "sys.path.insert(0, os.path.abspath(\"../../\"))\n",
+    "\n",
+    "# ── Semantica core ───────────────────────────────────────────────────────────\n",
+    "from semantica.context import ContextGraph, AgentContext, CausalChainAnalyzer\n",
+    "from semantica.vector_store import VectorStore\n",
+    "from semantica.semantic_extract import NERExtractor, RelationExtractor\n",
+    "from semantica.reasoning import Reasoner\n",
+    "from semantica.kg import GraphBuilder, GraphAnalyzer, CentralityCalculator\n",
+    "\n",
+    "# ── Agno integration ─────────────────────────────────────────────────────────\n",
+    "from integrations.agno import (\n",
+    "    AgnoSharedContext,\n",
+    "    AgnoDecisionKit,\n",
+    "    AgnoKGToolkit,\n",
+    "    AGNO_AVAILABLE,\n",
+    ")\n",
+    "\n",
+    "print(\"Semantica imports OK\")\n",
+    "print(f\"Agno installed: {AGNO_AVAILABLE}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "shared-context-section",
+   "metadata": {},
+   "source": [
+    "## 2. Build the Shared Semantica Backend\n",
+    "\n",
+    "A single `VectorStore` and `ContextGraph` underpin the entire team.  All agents read and write to the same store — role scoping is applied automatically by `AgnoSharedContext`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-shared",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Single shared backends ───────────────────────────────────────────────────\n",
+    "shared_vector_store = VectorStore(backend=\"faiss\", dimension=768)\n",
+    "shared_graph = ContextGraph(advanced_analytics=True)\n",
+    "\n",
+    "print(\"Shared VectorStore (FAISS) ready\")\n",
+    "print(\"Shared ContextGraph ready\")\n",
+    "\n",
+    "# ── AgnoSharedContext: the team coordinator ───────────────────────────────────\n",
+    "shared = AgnoSharedContext(\n",
+    "    vector_store=shared_vector_store,\n",
+    "    knowledge_graph=shared_graph,\n",
+    "    decision_tracking=True,\n",
+    "    session_id=\"product_strategy_team_q1_2026\",\n",
+    ")\n",
+    "print(f\"\\nAgnoSharedContext ready — session: {shared.session_id}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bind-section",
+   "metadata": {},
+   "source": [
+    "## 3. Bind Agent Roles\n",
+    "\n",
+    "Each agent gets a **role-scoped** `AgnoContextStore` via `bind_agent()`.  All agents share the same underlying graph, but their writes are tagged with their role for filtering."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bind-agents",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Bind each agent role — idempotent, can be called multiple times safely\n",
+    "researcher_store  = shared.bind_agent(\"researcher\")\n",
+    "analyst_store     = shared.bind_agent(\"analyst\")\n",
+    "strategist_store  = shared.bind_agent(\"strategist\")\n",
+    "\n",
+    "print(\"Agent roles bound:\")\n",
+    "for role in shared.bound_roles:\n",
+    "    store = shared.bind_agent(role)\n",
+    "    print(f\"  {role:15s} → session={store.session_id}\")\n",
+    "\n",
+    "# Verify all roles see the same underlying knowledge_graph\n",
+    "assert researcher_store._ctx is analyst_store._ctx\n",
+    "print(\"\\nAll agents share the same AgentContext ✓\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "seed-section",
+   "metadata": {},
+   "source": [
+    "## 4. Pre-Load Competitive Intelligence\n",
+    "\n",
+    "Using **native Semantica APIs**, we load a competitive landscape into the shared graph.  This represents knowledge the team has accumulated from prior research sessions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "seed-intel",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Competitive intelligence documents\n",
+    "COMPETITIVE_INTEL = [\n",
+    "    {\n",
+    "        \"source\": \"market_research_q4_2025\",\n",
+    "        \"text\": (\n",
+    "            \"Competitor Alpha launched a new SaaS analytics platform in Q4 2025. \"\n",
+    "            \"The product targets mid-market enterprises with annual revenue between \"\n",
+    "            \"$50M–$500M and has attracted 200 paying customers within 3 months. \"\n",
+    "            \"Pricing is $2,000/seat/year with volume discounts at 50+ seats. \"\n",
+    "            \"Alpha raised a $80M Series C led by Sequoia Capital in November 2025.\"\n",
+    "        ),\n",
+    "    },\n",
+    "    {\n",
+    "        \"source\": \"customer_interviews_q4_2025\",\n",
+    "        \"text\": (\n",
+    "            \"Customer interviews reveal strong demand for AI-powered anomaly detection \"\n",
+    "            \"in financial reporting workflows. 78% of CFOs surveyed cite 'time to insight' \"\n",
+    "            \"as the top pain point — currently averaging 14 days per reporting cycle. \"\n",
+    "            \"Competitor Alpha scores poorly on integration depth (NPS: 24) while \"\n",
+    "            \"our legacy product scores 41. Customers value our data governance features \"\n",
+    "            \"but want a modern UI and sub-second query times.\"\n",
+    "        ),\n",
+    "    },\n",
+    "    {\n",
+    "        \"source\": \"technology_scan_q4_2025\",\n",
+    "        \"text\": (\n",
+    "            \"Emerging technologies for consideration: LLM-native analytics interfaces \"\n",
+    "            \"reduce time-to-insight by 60% in pilot studies (Stanford HAI, 2025). \"\n",
+    "            \"Graph-based anomaly detection outperforms time-series approaches for \"\n",
+    "            \"multi-entity financial fraud by 34% (ACM SIGMOD 2025). \"\n",
+    "            \"Vector database adoption in enterprise analytics grew 120% YoY. \"\n",
+    "            \"Apache Arrow and DuckDB emerging as standards for in-process OLAP.\"\n",
+    "        ),\n",
+    "    },\n",
+    "]\n",
+    "\n",
+    "# Use Semantica NER + RelationExtractor directly for rich extraction\n",
+    "ner = NERExtractor()\n",
+    "rel_extractor = RelationExtractor(confidence_threshold=0.55)\n",
+    "graph_builder = GraphBuilder(merge_entities=True)\n",
+    "\n",
+    "for doc in COMPETITIVE_INTEL:\n",
+    "    text = doc['text']\n",
+    "    entities = ner.extract_entities(text) or []\n",
+    "    relations = rel_extractor.extract_relations(text) or []\n",
+    "    print(f\"[{doc['source']}]\")\n",
+    "    print(f\"  Entities: {len(entities)}, Relations: {len(relations)}\")\n",
+    "    # Store into shared context for all agents to access\n",
+    "    shared._context.store(text, conversation_id=doc['source'])\n",
+    "\n",
+    "print(\"\\nCompetitive intelligence loaded into shared context\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "tools-section",
+   "metadata": {},
+   "source": [
+    "## 5. Build Agent-Specific Tools\n",
+    "\n",
+    "Each toolkit is pointed at the **shared context** so tool calls across agents modify and read the same graph."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "build-tools",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Researcher's KG toolkit — builds knowledge from raw text\n",
+    "researcher_kg_kit = AgnoKGToolkit(\n",
+    "    ner_extractor=ner,\n",
+    "    relation_extractor=rel_extractor,\n",
+    "    reasoner=Reasoner(),\n",
+    "    context=shared.knowledge_graph,   # shared graph\n",
+    ")\n",
+    "\n",
+    "# Analyst's decision kit — records evaluations and finds precedents\n",
+    "analyst_decision_kit = AgnoDecisionKit(\n",
+    "    context=shared._context,           # shared AgentContext\n",
+    "    max_precedents=5,\n",
+    "    causal_depth=3,\n",
+    "    enable_policy_check=True,\n",
+    ")\n",
+    "\n",
+    "# Strategist gets both\n",
+    "strategist_kg_kit = AgnoKGToolkit(\n",
+    "    ner_extractor=ner,\n",
+    "    relation_extractor=rel_extractor,\n",
+    "    reasoner=Reasoner(),\n",
+    "    context=shared.knowledge_graph,\n",
+    ")\n",
+    "strategist_decision_kit = AgnoDecisionKit(\n",
+    "    context=shared._context,\n",
+    "    max_precedents=5,\n",
+    ")\n",
+    "\n",
+    "print(f\"Researcher toolkit:  {len(researcher_kg_kit._tools)} tools\")\n",
+    "print(f\"Analyst toolkit:     {len(analyst_decision_kit._tools)} tools\")\n",
+    "print(f\"Strategist toolkits: {len(strategist_kg_kit._tools)} + {len(strategist_decision_kit._tools)} tools\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "simulate-section",
+   "metadata": {},
+   "source": [
+    "## 6. Simulate Agent Collaboration\n",
+    "\n",
+    "We simulate the agents' reasoning steps directly, showing how shared context propagates knowledge between roles."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "researcher-turn",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"=\" * 65)\n",
+    "print(\"RESEARCHER AGENT TURN\")\n",
+    "print(\"=\" * 65)\n",
+    "\n",
+    "# Researcher extracts entities from new competitive intel\n",
+    "new_intel = (\n",
+    "    \"Competitor Beta just closed a strategic partnership with Microsoft Azure, \"\n",
+    "    \"integrating their anomaly detection engine natively into Azure Synapse Analytics. \"\n",
+    "    \"This gives Beta access to Microsoft's 300,000+ enterprise customer base. \"\n",
+    "    \"Beta's CEO Sarah Chen announced the deal at Gartner Data & Analytics Summit.\"\n",
+    ")\n",
+    "\n",
+    "# Step 1: Extract entities\n",
+    "entities_result = json.loads(researcher_kg_kit.extract_entities(new_intel))\n",
+    "print(f\"\\n[researcher] extracted {entities_result['count']} entities:\")\n",
+    "for e in entities_result['entities']:\n",
+    "    print(f\"  {e['name']:30s}  type={e['type']}\")\n",
+    "\n",
+    "# Step 2: Extract relations\n",
+    "relations_result = json.loads(researcher_kg_kit.extract_relations(new_intel))\n",
+    "print(f\"\\n[researcher] extracted {relations_result['count']} relations\")\n",
+    "\n",
+    "# Step 3: Add to shared graph — now visible to ALL agents\n",
+    "add_result = json.loads(researcher_kg_kit.add_to_graph(\n",
+    "    entities=json.dumps([\n",
+    "        {\"name\": \"Competitor Beta\", \"type\": \"COMPANY\"},\n",
+    "        {\"name\": \"Microsoft Azure\", \"type\": \"COMPANY\"},\n",
+    "        {\"name\": \"Azure Synapse Analytics\", \"type\": \"PRODUCT\"},\n",
+    "        {\"name\": \"Sarah Chen\", \"type\": \"PERSON\"},\n",
+    "        {\"name\": \"Gartner Data & Analytics Summit\", \"type\": \"EVENT\"},\n",
+    "    ]),\n",
+    "    relations=json.dumps([\n",
+    "        {\"source\": \"Competitor Beta\", \"relation\": \"PARTNERSHIP_WITH\", \"target\": \"Microsoft Azure\"},\n",
+    "        {\"source\": \"Competitor Beta\", \"relation\": \"INTEGRATES_WITH\", \"target\": \"Azure Synapse Analytics\"},\n",
+    "        {\"source\": \"Sarah Chen\", \"relation\": \"CEO_OF\", \"target\": \"Competitor Beta\"},\n",
+    "    ]),\n",
+    "))\n",
+    "print(f\"\\n[researcher] added {add_result['nodes_added']} nodes, {add_result['edges_added']} edges to SHARED graph\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "analyst-turn",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"=\" * 65)\n",
+    "print(\"ANALYST AGENT TURN (sees researcher's graph additions)\")\n",
+    "print(\"=\" * 65)\n",
+    "\n",
+    "# Analyst queries the graph the researcher just populated\n",
+    "competitor_query = json.loads(analyst_decision_kit.find_precedents(\n",
+    "    scenario=\"competitor partnership with cloud hyperscaler threatens market position\",\n",
+    "    limit=3,\n",
+    "))\n",
+    "print(f\"\\n[analyst] find_precedents → {competitor_query['count']} similar past strategic responses found\")\n",
+    "\n",
+    "# Analyst records a strategic evaluation decision\n",
+    "eval_json = analyst_decision_kit.record_decision(\n",
+    "    category=\"strategic_response\",\n",
+    "    scenario=(\n",
+    "        \"Competitor Beta + Microsoft Azure partnership gives Beta access to \"\n",
+    "        \"300k enterprise customers via Azure Synapse native integration\"\n",
+    "    ),\n",
+    "    reasoning=(\n",
+    "        \"Threat level: HIGH. Beta's Azure native integration removes our \"\n",
+    "        \"integration advantage. Existing NPS lead (41 vs 24) remains but \"\n",
+    "        \"distribution disadvantage is critical. Recommend accelerated cloud-native \"\n",
+    "        \"partnership evaluation, specifically AWS Marketplace + Snowflake Native App.\"\n",
+    "    ),\n",
+    "    outcome=\"escalate_to_strategy\",\n",
+    "    confidence=0.85,\n",
+    "    entities=\"Competitor Beta, Microsoft Azure, AWS Marketplace, Snowflake\",\n",
+    ")\n",
+    "eval_result = json.loads(eval_json)\n",
+    "analyst_decision_id = eval_result['decision_id']\n",
+    "print(f\"\\n[analyst] recorded evaluation → decision_id: {analyst_decision_id}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "strategist-turn",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"=\" * 65)\n",
+    "print(\"STRATEGIST AGENT TURN (sees both researcher + analyst work)\")\n",
+    "print(\"=\" * 65)\n",
+    "\n",
+    "# Strategist queries the graph for the full competitive picture\n",
+    "related = json.loads(strategist_kg_kit.find_related(\"Competitor Beta\", hops=2))\n",
+    "print(f\"\\n[strategist] 'Competitor Beta' 2-hop neighbourhood: {related['count']} entity/entities\")\n",
+    "for entity in related['related']:\n",
+    "    print(f\"  → {entity}\")\n",
+    "\n",
+    "# Strategist traces what the analyst decided\n",
+    "causal = json.loads(strategist_decision_kit.trace_causal_chain(analyst_decision_id, depth=3))\n",
+    "print(f\"\\n[strategist] causal chain for analyst decision: {causal}\")\n",
+    "\n",
+    "# Strategist records the final strategic recommendation\n",
+    "strategy_json = strategist_decision_kit.record_decision(\n",
+    "    category=\"product_strategy\",\n",
+    "    scenario=\"Q1 2026 product strategy: respond to Beta+Azure threat\",\n",
+    "    reasoning=(\n",
+    "        \"Based on researcher's KG (Beta+Azure integration, 300k customer reach) \"\n",
+    "        \"and analyst's evaluation (threat level HIGH, escalated decision). \"\n",
+    "        \"Strategy: (1) Accelerate AWS Marketplace listing by Q2 2026. \"\n",
+    "        \"(2) Launch Snowflake Native App by Q3 2026. \"\n",
+    "        \"(3) Invest $2M in UI modernisation to widen NPS lead. \"\n",
+    "        \"(4) Fast-track LLM-native analytics interface (60% time-to-insight improvement per HAI study). \"\n",
+    "        \"Existing NPS advantage (41 vs 24) provides 18-month window before Beta catches up.\"\n",
+    "    ),\n",
+    "    outcome=\"approved\",\n",
+    "    confidence=0.88,\n",
+    "    entities=\"AWS Marketplace, Snowflake, LLM Analytics, Q2 2026, Q3 2026\",\n",
+    ")\n",
+    "strategy_result = json.loads(strategy_json)\n",
+    "print(f\"\\n[strategist] final recommendation recorded → {strategy_result['decision_id']}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "shared-pool-section",
+   "metadata": {},
+   "source": [
+    "## 7. Verify Shared Memory Pool\n",
+    "\n",
+    "Memories written by one agent are readable by all others."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "verify-shared",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from integrations.agno.context_store import _MemoryRow as MemoryRow\n",
+    "\n",
+    "# Researcher writes a memory\n",
+    "researcher_row = MemoryRow(\n",
+    "    memory=\"Beta + Azure partnership announced at Gartner Summit — threat level HIGH\",\n",
+    "    user_id=\"researcher\",\n",
+    ")\n",
+    "researcher_store.upsert_memory(researcher_row)\n",
+    "\n",
+    "# Analyst writes a memory\n",
+    "analyst_row = MemoryRow(\n",
+    "    memory=\"NPS advantage (41 vs 24) gives 18-month window — accelerate cloud partnerships\",\n",
+    "    user_id=\"analyst\",\n",
+    ")\n",
+    "analyst_store.upsert_memory(analyst_row)\n",
+    "\n",
+    "# Strategist reads ALL memories from both agents\n",
+    "strategist_memories = strategist_store.read_memories()\n",
+    "\n",
+    "print(f\"Strategist sees {len(strategist_memories)} shared memory item(s):\")\n",
+    "for m in strategist_memories:\n",
+    "    uid = getattr(m, 'user_id', '?')\n",
+    "    text = getattr(m, 'memory', str(m))\n",
+    "    print(f\"  [{uid:12s}] {text[:80]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "agno-team-section",
+   "metadata": {},
+   "source": [
+    "## 8. Wire into Agno Team (requires API key)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "agno-team",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "if AGNO_AVAILABLE:\n",
+    "    from agno.agent import Agent\n",
+    "    from agno.team import Team\n",
+    "    from agno.memory import AgentMemory\n",
+    "    from agno.models.openai import OpenAIChat\n",
+    "\n",
+    "    researcher_agent = Agent(\n",
+    "        name=\"Researcher\",\n",
+    "        model=OpenAIChat(id=\"gpt-4o\"),\n",
+    "        memory=AgentMemory(db=researcher_store),\n",
+    "        tools=[researcher_kg_kit],\n",
+    "        show_tool_calls=True,\n",
+    "        description=(\n",
+    "            \"You are a competitive intelligence researcher. \"\n",
+    "            \"Use extract_entities, extract_relations, and add_to_graph \"\n",
+    "            \"to build a structured knowledge graph from market intelligence. \"\n",
+    "            \"Always add discoveries to the shared graph.\"\n",
+    "        ),\n",
+    "    )\n",
+    "\n",
+    "    analyst_agent = Agent(\n",
+    "        name=\"Analyst\",\n",
+    "        model=OpenAIChat(id=\"gpt-4o\"),\n",
+    "        memory=AgentMemory(db=analyst_store),\n",
+    "        tools=[analyst_decision_kit],\n",
+    "        show_tool_calls=True,\n",
+    "        description=(\n",
+    "            \"You are a strategic analyst. Use find_precedents to check historical \"\n",
+    "            \"responses to similar threats, then record_decision with your evaluation. \"\n",
+    "            \"Always check if a similar situation was handled before acting.\"\n",
+    "        ),\n",
+    "    )\n",
+    "\n",
+    "    strategist_agent = Agent(\n",
+    "        name=\"Strategist\",\n",
+    "        model=OpenAIChat(id=\"gpt-4o\"),\n",
+    "        memory=AgentMemory(db=strategist_store),\n",
+    "        tools=[strategist_kg_kit, strategist_decision_kit],\n",
+    "        show_tool_calls=True,\n",
+    "        description=(\n",
+    "            \"You are the Chief Strategy Officer. Synthesise the researcher's knowledge \"\n",
+    "            \"graph and the analyst's decision record into a concrete product strategy. \"\n",
+    "            \"Use find_related to explore the competitive graph, then record_decision \"\n",
+    "            \"with the final approved strategy.\"\n",
+    "        ),\n",
+    "    )\n",
+    "\n",
+    "    strategy_team = Team(\n",
+    "        name=\"Product Strategy Team\",\n",
+    "        agents=[researcher_agent, analyst_agent, strategist_agent],\n",
+    "        mode=\"coordinate\",\n",
+    "    )\n",
+    "\n",
+    "    strategy_team.print_response(\n",
+    "        \"Competitor Beta just announced a native Azure integration. \"\n",
+    "        \"Analyse the competitive landscape and recommend our Q1 2026 product strategy.\"\n",
+    "    )\n",
+    "else:\n",
+    "    print(\"[Agno not installed — skipping live team run]\")\n",
+    "    print()\n",
+    "    print(\"Expected team coordination flow:\")\n",
+    "    print(\"  1. Researcher: extract_entities + add_to_graph (Beta+Azure)\")\n",
+    "    print(\"  2. Analyst: find_precedents + record_decision (threat=HIGH, escalate)\")\n",
+    "    print(\"  3. Strategist: find_related + trace_causal_chain + record_decision (final strategy)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "post-session-section",
+   "metadata": {},
+   "source": [
+    "## 9. Post-Session Analysis with Semantica\n",
+    "\n",
+    "After the team session, use **native Semantica APIs** for cross-agent audit, analytics, and causal chain review."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cross-agent-insights",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Team-level insights from AgnoSharedContext\n",
+    "insights = shared.get_shared_insights()\n",
+    "print(\"Team session insights:\")\n",
+    "if isinstance(insights, dict):\n",
+    "    for k, v in insights.items():\n",
+    "        print(f\"  {k}: {v}\")\n",
+    "else:\n",
+    "    print(f\"  {insights}\")\n",
+    "\n",
+    "print(f\"\\nBound agent roles: {shared.bound_roles}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "precedent-search",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Find all cross-agent strategic decisions\n",
+    "all_strategic = shared.find_precedents(\n",
+    "    scenario=\"cloud partnership competitive response\",\n",
+    "    category=\"strategic_response\",\n",
+    ")\n",
+    "print(f\"Cross-agent strategic precedents: {len(all_strategic or [])}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "graph-analytics",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Graph analytics on the shared knowledge graph (Semantica native)\n",
+    "try:\n",
+    "    analyzer = GraphAnalyzer()\n",
+    "    analysis = analyzer.analyze_graph(shared.knowledge_graph)\n",
+    "    print(\"Shared knowledge graph analysis:\")\n",
+    "    if isinstance(analysis, dict):\n",
+    "        for k, v in list(analysis.items())[:6]:\n",
+    "            print(f\"  {k}: {v}\")\n",
+    "    else:\n",
+    "        print(f\"  {analysis}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"GraphAnalyzer: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "centrality-analysis",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Which entities are most central in the competitive intelligence graph?\n",
+    "try:\n",
+    "    centrality = CentralityCalculator()\n",
+    "    scores = centrality.calculate_degree_centrality(shared.knowledge_graph)\n",
+    "    print(\"Most central entities in shared graph:\")\n",
+    "    if isinstance(scores, dict):\n",
+    "        top = sorted(scores.items(), key=lambda x: x[1], reverse=True)[:5]\n",
+    "        for entity, score in top:\n",
+    "            print(f\"  {entity:35s} centrality={score:.4f}\")\n",
+    "    else:\n",
+    "        print(f\"  {scores}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"CentralityCalculator: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "causal-analysis",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Direct Semantica causal chain analysis (no Agno needed)\n",
+    "try:\n",
+    "    causal_analyzer = CausalChainAnalyzer(graph_store=shared.knowledge_graph)\n",
+    "    # Query all decisions made during this session\n",
+    "    decisions = shared.knowledge_graph.find_precedents(category=\"product_strategy\", limit=10)\n",
+    "    print(f\"Product strategy decisions in shared graph: {len(decisions or [])}\")\n",
+    "    for d in (decisions or [])[:3]:\n",
+    "        scenario = d.get('scenario', '') if isinstance(d, dict) else str(d)\n",
+    "        outcome = d.get('outcome', '') if isinstance(d, dict) else ''\n",
+    "        print(f\"  [{outcome:20s}] {scenario[:70]}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"CausalChainAnalyzer: {e}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "summary-section",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Pattern | Implementation |\n",
+    "|---|---|\n",
+    "| Single shared knowledge graph | `AgnoSharedContext(vector_store, knowledge_graph)` |\n",
+    "| Role-scoped memory | `shared.bind_agent(\"researcher\")` → `_AgentScopedStore` |\n",
+    "| Cross-agent memory visibility | All stores read from `shared._shared_memories` |\n",
+    "| KG tool sharing | `AgnoKGToolkit(context=shared.knowledge_graph)` |\n",
+    "| Decision tool sharing | `AgnoDecisionKit(context=shared._context)` |\n",
+    "| Thread-safe binding | `AgnoSharedContext._lock` (RLock) |\n",
+    "| Post-session analytics | `GraphAnalyzer`, `CentralityCalculator`, `CausalChainAnalyzer` — all Semantica native |\n",
+    "\n",
+    "**Key design rule:** Every agent writes to the **same underlying graph** via different role-scoped stores.  The Agno integration is a thin routing layer — Semantica's full power is available at any point directly."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/introduction/15_Export.ipynb

@@ -178,6 +178,13 @@
     "rdf_exporter.export(kg, \"output.ttl\", format=\"turtle\")"
    ]
   },
+  {
+   "cell_type": "code",
+   "source": "# TTL alias: format=\"ttl\" is equivalent to format=\"turtle\"\nrdf_data = {\n    \"entities\": [\n        {\"id\": \"e1\", \"text\": \"Apple Inc.\", \"type\": \"ORG\", \"confidence\": 0.95},\n        {\"id\": \"e2\", \"text\": \"Steve Jobs\", \"type\": \"PERSON\", \"confidence\": 0.97},\n    ],\n    \"relationships\": [\n        {\"source_id\": \"e2\", \"target_id\": \"e1\", \"type\": \"founded_by\", \"confidence\": 0.91},\n    ],\n}\n\nrdf_exporter.export(rdf_data, \"output.ttl\", format=\"ttl\")\n\nresult = rdf_exporter.validate_rdf(rdf_data)\nprint(f\"Valid: {result['overall_valid']}\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

cookbook/introduction/21_Amazon_Neptune_Store.ipynb

@@ -25,6 +25,57 @@
     "- AWS credentials configured (boto3, environment variables, or IAM role)\n",
     "- Network access to your Neptune cluster (VPC, security groups)\n",
     "\n",
+    "#### Quick Setup with CloudFormation\n",
+    "\n",
+    "If you don't have a Neptune cluster, use the provided CloudFormation template to create one with a public endpoint and IAM authentication:\n",
+    "\n",
+    "```bash\n",
+    "# Deploy the Neptune stack (takes ~15-20 minutes)\n",
+    "aws cloudformation create-stack \\\n",
+    "  --stack-name semantica-neptune \\\n",
+    "  --template-body file://neptune-setup.yaml \\\n",
+    "  --capabilities CAPABILITY_NAMED_IAM\n",
+    "\n",
+    "# Wait for stack creation to complete\n",
+    "aws cloudformation wait stack-create-complete --stack-name semantica-neptune\n",
+    "\n",
+    "# Get the outputs (endpoint, port, credentials)\n",
+    "aws cloudformation describe-stacks --stack-name semantica-neptune \\\n",
+    "  --query 'Stacks[0].Outputs' --output table\n",
+    "```\n",
+    "\n",
+    "The template creates:\n",
+    "- VPC with public subnets and Internet Gateway\n",
+    "- Neptune cluster (`db.t3.medium`) with IAM authentication enabled\n",
+    "- IAM user with least-privilege access for OpenCypher queries\n",
+    "- Security group allowing Bolt protocol (port 8182) access\n",
+    "\n",
+    "> ⚠️ **Security Note**: This template creates an IAM User with static access keys for simplicity in demo/test environments. For production use, we recommend IAM Roles (EC2 instance roles, ECS task roles, Lambda execution roles) which provide temporary credentials that are automatically rotated. The secret access key in the Cloudformation outputs is provided in plaintext to simplify initial setup - in production, use AWS Secrets Manager.\n",
+    "\n",
+    "**Outputs:**\n",
+    "- `NeptuneEndpoint` - Cluster hostname (use as `NEPTUNE_ENDPOINT`)\n",
+    "- `NeptunePort` - 8182 (use as `NEPTUNE_PORT`)\n",
+    "- `AwsAccessKeyId` - IAM user access key (use as `AWS_ACCESS_KEY_ID`)\n",
+    "- `AwsSecretAccessKey` - IAM user secret key in **plaintext** (use as `AWS_SECRET_ACCESS_KEY`)\n",
+    "- `AwsRegion` - Deployment region (use as `AWS_REGION`)\n",
+    "\n",
+    "**Cleanup:**\n",
+    "```bash\n",
+    "aws cloudformation delete-stack --stack-name semantica-neptune\n",
+    "```\n",
+    "\n",
+    "**Estimated Monthly Cost (approximately 100-105 USD/month at 100% utilization):**\n",
+    "\n",
+    "| Resource | Cost (USD) |\n",
+    "| --- | --- |\n",
+    "| Neptune db.t3.medium instance | ~96/month (0.132/hr) |\n",
+    "| Storage (10 GB) | ~1/month |\n",
+    "| I/O requests | ~1-5/month |\n",
+    "| Public IPv4 address | ~3.60/month (0.005/hr) |\n",
+    "| VPC, subnets, route tables, Internet Gateway, IAM | No Additional Charge |\n",
+    "\n",
+    "> **Free Tier**: New Neptune users get 30 days free (750 hours of db.t3.medium, 10M I/Os, 1 GB storage). Delete the stack when not in use to avoid charges.\n",
+    "\n",
     "---"
    ]
   },
@@ -70,14 +121,21 @@
     "import os\n",
     "\n",
     "# Neptune cluster configuration - REPLACE WITH YOUR VALUES\n",
+    "# (Get these from CloudFormation stack outputs)\n",
     "os.environ[\"NEPTUNE_ENDPOINT\"] = \"your-cluster.us-east-1.neptune.amazonaws.com\"\n",
     "os.environ[\"NEPTUNE_PORT\"] = \"8182\"\n",
     "os.environ[\"AWS_REGION\"] = \"us-east-1\"\n",
     "\n",
-    "# AWS credentials (if using IAM Auth and not relying on IAM role or ~/.aws/credentials)\n",
-    "# os.environ[\"AWS_ACCESS_KEY_ID\"] = \"your-access-key-id\"\n",
-    "# os.environ[\"AWS_SECRET_ACCESS_KEY\"] = \"your-secret-access-key\"\n",
-    "# os.environ[\"AWS_SESSION_TOKEN\"] = \"your-session-token\"\n",
+    "# AWS credentials for IAM Authentication\n",
+    "# Option 1: IAM User (static credentials from CloudFormation template)\n",
+    "# os.environ[\"AWS_ACCESS_KEY_ID\"] = \"AKIA...\"  # From AwsAccessKeyId output\n",
+    "# os.environ[\"AWS_SECRET_ACCESS_KEY\"] = \"...\"  # From AwsSecretAccessKey output\n",
+    "# Note: No AWS_SESSION_TOKEN needed for IAM users\n",
+    "\n",
+    "# Option 2: IAM Role / Temporary credentials (e.g., STS AssumeRole, EC2 instance role)\n",
+    "# os.environ[\"AWS_ACCESS_KEY_ID\"] = \"ASIA...\"  # Temporary access key\n",
+    "# os.environ[\"AWS_SECRET_ACCESS_KEY\"] = \"...\"  # Temporary secret key\n",
+    "# os.environ[\"AWS_SESSION_TOKEN\"] = \"...\"      # REQUIRED for temporary credentials\n",
     "\n",
     "print(f\"Neptune Endpoint: {os.environ.get('NEPTUNE_ENDPOINT')}\")\n",
     "print(f\"AWS Region: {os.environ.get('AWS_REGION')}\")"

cookbook/introduction/neptune-setup.yaml

@@ -0,0 +1,228 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: >
+  Amazon Neptune cluster with public endpoint, IAM authentication, and least-privilege
+  IAM user for Semantica cookbook. Uses db.t3.medium (most cost-effective Neptune instance type).
+
+Parameters:
+  EnvironmentName:
+    Type: String
+    Default: semantica-neptune
+    Description: Environment name prefix for resource naming
+
+Resources:
+  # =============================================================================
+  # VPC & NETWORKING
+  # =============================================================================
+
+  VPC:
+    Type: AWS::EC2::VPC
+    Properties:
+      CidrBlock: 10.0.0.0/16
+      EnableDnsHostnames: true
+      EnableDnsSupport: true
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-vpc
+
+  InternetGateway:
+    Type: AWS::EC2::InternetGateway
+    Properties:
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-igw
+
+  InternetGatewayAttachment:
+    Type: AWS::EC2::VPCGatewayAttachment
+    Properties:
+      InternetGatewayId: !Ref InternetGateway
+      VpcId: !Ref VPC
+
+  PublicSubnet1:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref VPC
+      AvailabilityZone: !Select [0, !GetAZs '']
+      CidrBlock: 10.0.1.0/24
+      MapPublicIpOnLaunch: true
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-public-subnet-1
+
+  PublicSubnet2:
+    Type: AWS::EC2::Subnet
+    Properties:
+      VpcId: !Ref VPC
+      AvailabilityZone: !Select [1, !GetAZs '']
+      CidrBlock: 10.0.2.0/24
+      MapPublicIpOnLaunch: true
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-public-subnet-2
+
+  PublicRouteTable:
+    Type: AWS::EC2::RouteTable
+    Properties:
+      VpcId: !Ref VPC
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-public-rt
+
+  DefaultPublicRoute:
+    Type: AWS::EC2::Route
+    DependsOn: InternetGatewayAttachment
+    Properties:
+      RouteTableId: !Ref PublicRouteTable
+      DestinationCidrBlock: 0.0.0.0/0
+      GatewayId: !Ref InternetGateway
+
+  PublicSubnet1RouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      RouteTableId: !Ref PublicRouteTable
+      SubnetId: !Ref PublicSubnet1
+
+  PublicSubnet2RouteTableAssociation:
+    Type: AWS::EC2::SubnetRouteTableAssociation
+    Properties:
+      RouteTableId: !Ref PublicRouteTable
+      SubnetId: !Ref PublicSubnet2
+
+  # =============================================================================
+  # SECURITY GROUP
+  # =============================================================================
+
+  NeptuneSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupName: !Sub ${EnvironmentName}-neptune-sg
+      GroupDescription: Security group for Neptune cluster - allows Bolt protocol access
+      VpcId: !Ref VPC
+      SecurityGroupIngress:
+        - IpProtocol: tcp
+          FromPort: 8182
+          ToPort: 8182
+          CidrIp: 0.0.0.0/0
+          Description: Allow Bolt protocol access from anywhere
+      SecurityGroupEgress:
+        - IpProtocol: -1
+          CidrIp: 0.0.0.0/0
+          Description: Allow all outbound traffic
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-neptune-sg
+
+  # =============================================================================
+  # NEPTUNE CLUSTER
+  # =============================================================================
+
+  NeptuneSubnetGroup:
+    Type: AWS::Neptune::DBSubnetGroup
+    Properties:
+      DBSubnetGroupDescription: Subnet group for Neptune cluster
+      DBSubnetGroupName: !Sub ${EnvironmentName}-subnet-group
+      SubnetIds:
+        - !Ref PublicSubnet1
+        - !Ref PublicSubnet2
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-subnet-group
+
+  NeptuneCluster:
+    Type: AWS::Neptune::DBCluster
+    Properties:
+      DBClusterIdentifier: !Sub ${EnvironmentName}-cluster
+      DBSubnetGroupName: !Ref NeptuneSubnetGroup
+      VpcSecurityGroupIds:
+        - !Ref NeptuneSecurityGroup
+      EngineVersion: '1.4.6.3'
+      IamAuthEnabled: true
+      StorageEncrypted: true
+      DeletionProtection: false
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-cluster
+
+  NeptuneInstance:
+    Type: AWS::Neptune::DBInstance
+    Properties:
+      DBInstanceIdentifier: !Sub ${EnvironmentName}-instance
+      DBInstanceClass: db.t3.medium
+      DBClusterIdentifier: !Ref NeptuneCluster
+      PubliclyAccessible: true
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-instance
+
+  # =============================================================================
+  # IAM USER WITH LEAST PRIVILEGES
+  # =============================================================================
+
+  NeptuneUser:
+    Type: AWS::IAM::User
+    Properties:
+      UserName: !Sub ${EnvironmentName}-user
+      Tags:
+        - Key: Name
+          Value: !Sub ${EnvironmentName}-user
+
+  NeptuneUserPolicy:
+    Type: AWS::IAM::Policy
+    Properties:
+      PolicyName: !Sub ${EnvironmentName}-neptune-access
+      Users:
+        - !Ref NeptuneUser
+      PolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Sid: NeptuneDataAccess
+            Effect: Allow
+            Action:
+              - neptune-db:connect
+              - neptune-db:ReadDataViaQuery
+              - neptune-db:WriteDataViaQuery
+              - neptune-db:DeleteDataViaQuery
+            Resource: !Sub
+              - arn:aws:neptune-db:${AWS::Region}:${AWS::AccountId}:${ClusterResourceId}/*
+              - ClusterResourceId: !GetAtt NeptuneCluster.ClusterResourceId
+
+  NeptuneUserAccessKey:
+    Type: AWS::IAM::AccessKey
+    Properties:
+      UserName: !Ref NeptuneUser
+
+# =============================================================================
+# OUTPUTS
+# =============================================================================
+
+Outputs:
+  NeptuneEndpoint:
+    Description: Neptune cluster endpoint (hostname only) - use as NEPTUNE_ENDPOINT
+    Value: !GetAtt NeptuneCluster.Endpoint
+
+  NeptunePort:
+    Description: Neptune cluster port - use as NEPTUNE_PORT
+    Value: !GetAtt NeptuneCluster.Port
+
+  AwsAccessKeyId:
+    Description: Access key ID for the Neptune IAM user - use as AWS_ACCESS_KEY_ID
+    Value: !Ref NeptuneUserAccessKey
+
+  AwsSecretAccessKey:
+    Description: Secret access key for the Neptune IAM user - use as AWS_SECRET_ACCESS_KEY
+    Value: !GetAtt NeptuneUserAccessKey.SecretAccessKey
+
+  AwsRegion:
+    Description: AWS region where Neptune is deployed - use as AWS_REGION
+    Value: !Ref AWS::Region
+
+  NeptuneClusterResourceId:
+    Description: Neptune cluster resource ID (for IAM policy reference)
+    Value: !GetAtt NeptuneCluster.ClusterResourceId
+
+  VpcId:
+    Description: VPC ID
+    Value: !Ref VPC
+
+  SecurityGroupId:
+    Description: Neptune security group ID
+    Value: !Ref NeptuneSecurityGroup

cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb

@@ -110,7 +110,7 @@
    "source": [
     "# Set up API keys\n",
     "# Note: In production, use environment variables: export GROQ_API_KEY=\"your-key\"\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"Your Groq API\")\n"
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n"
    ]
   },
   {

cookbook/use_cases/advanced_rag/02_RAG_vs_GraphRAG_Comparison.ipynb

@@ -30,7 +30,7 @@
     "# Environment Setup\n",
     "import os\n",
     "\n",
-    "os.environ['GROQ_API_KEY'] = os.getenv('GROQ_API_KEY', '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')\n",
+    "os.environ['GROQ_API_KEY'] = os.getenv('GROQ_API_KEY', '')\n",
     "\n",
     "# Install Semantica and all required dependencies\n",
     "%pip install -qU semantica networkx matplotlib plotly pandas faiss-cpu beautifulsoup4 groq sentence-transformers\n"
@@ -84,7 +84,7 @@
    "source": [
     "# Set up API keys\n",
     "# Note: In production, use environment variables: export GROQ_API_KEY=\"your-key\"\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"your-groq-api-key-here\")\n",
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n",
     "\n",
     "print(\"API keys configured.\")\n"
    ]

cookbook/use_cases/biomedical/01_Drug_Discovery_Pipeline.ipynb

@@ -109,7 +109,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n"
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n"
    ]
   },
   {

cookbook/use_cases/biomedical/02_Genomic_Variant_Analysis.ipynb

@@ -85,7 +85,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n"
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n"
    ]
   },
   {

cookbook/use_cases/blockchain/01_DeFi_Protocol_Intelligence.ipynb

@@ -81,7 +81,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n",
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n",
     "\n",
     "# Configuration constants\n",
     "EMBEDDING_DIMENSION = 384\n",

cookbook/use_cases/capability_gap_defense/data/military_capability_gap_instances.ttl

@@ -0,0 +1,86 @@
+@prefix mcg: <https://example.org/mcg#> .
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<https://example.org/mcg/instance-data> a owl:Ontology ;
+    rdfs:label "Military Capability Gap Analysis Instance Data" ;
+    owl:imports <https://example.org/mcg> .
+
+# Scenario and threat
+mcg:Scenario_FutureA2AD_2028 a mcg:Scenario ;
+    rdfs:label "Future A2/AD Escalation 2028" ;
+    mcg:hasThreat mcg:Threat_LowAltitudeSwarm .
+
+mcg:Threat_LowAltitudeSwarm a mcg:Threat ;
+    rdfs:label "Low-Altitude Swarm Threat" ;
+    mcg:relatedToIntelligenceReport mcg:IntelReport_RAND_RRA733_1 .
+
+# Mission thread and events
+mcg:MissionThread_ForceProtection a mcg:MissionThread ;
+    rdfs:label "Force Protection under Swarm Pressure" ;
+    mcg:missionPriority "high" ;
+    mcg:includesEvent mcg:Event_SwarmIncursion_001 ;
+    mcg:requiresCapability mcg:Capability_LowAltitudeDetection ;
+    mcg:revealsGap mcg:Gap_LowAltitudeDetectionCoverage .
+
+mcg:Scenario_FutureA2AD_2028 mcg:hasMissionThread mcg:MissionThread_ForceProtection .
+
+mcg:Event_SwarmIncursion_001 a mcg:OperationalEvent ;
+    rdfs:label "Swarm Incursion Event 001" ;
+    mcg:eventTime "2028-04-12T05:15:00Z"^^xsd:dateTime ;
+    mcg:stressesSystem mcg:System_GroundRadarLayer ;
+    mcg:relatedToWargameObservation mcg:WargameObs_ValleyIngress .
+
+# Systems and capabilities
+mcg:System_GroundRadarLayer a mcg:System ;
+    rdfs:label "Ground Radar Layer" ;
+    mcg:coveragePercent "42.0"^^xsd:decimal ;
+    mcg:relatedToAssetRecord mcg:AssetRecord_RadarFleet_2028Q1 .
+
+mcg:Capability_LowAltitudeDetection a mcg:Capability ;
+    rdfs:label "Low Altitude Detection Capability" ;
+    mcg:requiredCoveragePercent "75.0"^^xsd:decimal ;
+    mcg:providedBy mcg:System_GroundRadarLayer .
+
+# Gap and outcome
+mcg:Gap_LowAltitudeDetectionCoverage a mcg:CapabilityGap ;
+    rdfs:label "Insufficient Low-Altitude Detection Coverage" ;
+    mcg:gapInCapability mcg:Capability_LowAltitudeDetection ;
+    mcg:gapSeverity "critical" ;
+    mcg:increasesRiskOf mcg:Outcome_MissionRiskIncrease ;
+    mcg:triggersDecision mcg:Decision_CapGap_001 .
+
+mcg:Outcome_MissionRiskIncrease a mcg:Outcome ;
+    rdfs:label "Increased Mission Risk and Response Delay" .
+
+# Decision and recommendation
+mcg:Decision_CapGap_001 a mcg:Decision ;
+    rdfs:label "Capability Gap Decision 001" ;
+    mcg:confidenceScore "0.93"^^xsd:decimal ;
+    mcg:hasRecommendation mcg:Recommendation_MultiLayerSensorFusion ;
+    mcg:supportedByEvidence mcg:Evidence_E001 ;
+    mcg:wasAssessedBy mcg:AnalystCell_A1 .
+
+mcg:Recommendation_MultiLayerSensorFusion a mcg:Recommendation ;
+    mcg:recommendationText "Integrate layered sensing (ground radar, passive RF, EO/IR) and update mission doctrine for low-altitude swarm defense." .
+
+# Evidence and provenance
+mcg:Evidence_E001 a mcg:Evidence ;
+    mcg:evidenceQuote "Operational analysis indicates persistent low-altitude sensing shortfalls in contested terrain." ;
+    mcg:derivedFromDocument mcg:IntelReport_RAND_RRA733_1 .
+
+mcg:IntelReport_RAND_RRA733_1 a mcg:IntelligenceReport, prov:Entity ;
+    rdfs:label "RAND RRA733-1 Competing Without Fighting (2022)" .
+
+mcg:WargameObs_ValleyIngress a mcg:WargameObservation, prov:Entity ;
+    rdfs:label "Wargame Observation: Valley Ingress Routes" .
+
+mcg:AssetRecord_RadarFleet_2028Q1 a mcg:AssetInventoryRecord, prov:Entity ;
+    rdfs:label "Asset Inventory: Radar Fleet 2028 Q1" .
+
+mcg:AnalystCell_A1 a prov:Agent ;
+    rdfs:label "Joint Capability Assessment Cell A1" .
+

cookbook/use_cases/capability_gap_defense/data/military_capability_gap_ontology.ttl

@@ -0,0 +1,143 @@
+@prefix mcg: <https://example.org/mcg#> .
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix d3f: <http://d3fend.mitre.org/ontologies/d3fend.owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<https://example.org/mcg> a owl:Ontology ;
+    rdfs:label "Military Capability Gap Analysis Ontology" ;
+    rdfs:comment "Ontology for end-to-end military capability gap analysis with context graphs, multi-hop reasoning, and provenance." ;
+    owl:imports <http://www.w3.org/ns/prov> .
+
+# Classes
+mcg:Scenario a owl:Class .
+mcg:MissionThread a owl:Class .
+mcg:OperationalEvent a owl:Class .
+mcg:System a owl:Class .
+mcg:Capability a owl:Class .
+mcg:CapabilityGap a owl:Class .
+mcg:Outcome a owl:Class .
+mcg:Decision a owl:Class .
+mcg:Recommendation a owl:Class .
+mcg:Evidence a owl:Class .
+mcg:Threat a owl:Class .
+mcg:DoctrineDocument a owl:Class ;
+    rdfs:subClassOf prov:Entity .
+mcg:WargameObservation a owl:Class ;
+    rdfs:subClassOf prov:Entity .
+mcg:AssetInventoryRecord a owl:Class ;
+    rdfs:subClassOf prov:Entity .
+mcg:IntelligenceReport a owl:Class ;
+    rdfs:subClassOf prov:Entity .
+
+# Optional alignment points
+mcg:Sensor a owl:Class ;
+    rdfs:subClassOf mcg:System, d3f:D3FEND .
+
+# Object properties (context chain)
+mcg:hasMissionThread a owl:ObjectProperty ;
+    rdfs:domain mcg:Scenario ;
+    rdfs:range mcg:MissionThread .
+
+mcg:includesEvent a owl:ObjectProperty ;
+    rdfs:domain mcg:MissionThread ;
+    rdfs:range mcg:OperationalEvent .
+
+mcg:stressesSystem a owl:ObjectProperty ;
+    rdfs:domain mcg:OperationalEvent ;
+    rdfs:range mcg:System .
+
+mcg:requiresCapability a owl:ObjectProperty ;
+    rdfs:domain mcg:MissionThread ;
+    rdfs:range mcg:Capability .
+
+mcg:providedBy a owl:ObjectProperty ;
+    rdfs:domain mcg:Capability ;
+    rdfs:range mcg:System .
+
+mcg:revealsGap a owl:ObjectProperty ;
+    rdfs:domain mcg:MissionThread ;
+    rdfs:range mcg:CapabilityGap .
+
+mcg:gapInCapability a owl:ObjectProperty ;
+    rdfs:domain mcg:CapabilityGap ;
+    rdfs:range mcg:Capability .
+
+mcg:increasesRiskOf a owl:ObjectProperty ;
+    rdfs:domain mcg:CapabilityGap ;
+    rdfs:range mcg:Outcome .
+
+mcg:triggersDecision a owl:ObjectProperty ;
+    rdfs:domain mcg:CapabilityGap ;
+    rdfs:range mcg:Decision .
+
+mcg:hasRecommendation a owl:ObjectProperty ;
+    rdfs:domain mcg:Decision ;
+    rdfs:range mcg:Recommendation .
+
+mcg:supportedByEvidence a owl:ObjectProperty ;
+    rdfs:domain mcg:Decision ;
+    rdfs:range mcg:Evidence .
+
+mcg:hasThreat a owl:ObjectProperty ;
+    rdfs:domain mcg:Scenario ;
+    rdfs:range mcg:Threat .
+
+mcg:relatedToAssetRecord a owl:ObjectProperty ;
+    rdfs:domain mcg:System ;
+    rdfs:range mcg:AssetInventoryRecord .
+
+mcg:relatedToWargameObservation a owl:ObjectProperty ;
+    rdfs:domain mcg:OperationalEvent ;
+    rdfs:range mcg:WargameObservation .
+
+mcg:relatedToIntelligenceReport a owl:ObjectProperty ;
+    rdfs:domain mcg:Threat ;
+    rdfs:range mcg:IntelligenceReport .
+
+# Provenance properties
+mcg:derivedFromDocument a owl:ObjectProperty ;
+    rdfs:subPropertyOf prov:wasDerivedFrom ;
+    rdfs:domain mcg:Evidence ;
+    rdfs:range prov:Entity .
+
+mcg:wasAssessedBy a owl:ObjectProperty ;
+    rdfs:subPropertyOf prov:wasAssociatedWith ;
+    rdfs:domain mcg:Decision ;
+    rdfs:range prov:Agent .
+
+# Data properties
+mcg:coveragePercent a owl:DatatypeProperty ;
+    rdfs:domain mcg:System ;
+    rdfs:range xsd:decimal .
+
+mcg:requiredCoveragePercent a owl:DatatypeProperty ;
+    rdfs:domain mcg:Capability ;
+    rdfs:range xsd:decimal .
+
+mcg:gapSeverity a owl:DatatypeProperty ;
+    rdfs:domain mcg:CapabilityGap ;
+    rdfs:range xsd:string .
+
+mcg:confidenceScore a owl:DatatypeProperty ;
+    rdfs:domain mcg:Decision ;
+    rdfs:range xsd:decimal .
+
+mcg:missionPriority a owl:DatatypeProperty ;
+    rdfs:domain mcg:MissionThread ;
+    rdfs:range xsd:string .
+
+mcg:eventTime a owl:DatatypeProperty ;
+    rdfs:domain mcg:OperationalEvent ;
+    rdfs:range xsd:dateTime .
+
+mcg:recommendationText a owl:DatatypeProperty ;
+    rdfs:domain mcg:Recommendation ;
+    rdfs:range xsd:string .
+
+mcg:evidenceQuote a owl:DatatypeProperty ;
+    rdfs:domain mcg:Evidence ;
+    rdfs:range xsd:string .
+

cookbook/use_cases/capability_gap_defense/data/us_navy_it_strategic_plan_fy2023.pdf

@@ -0,0 +1 @@
+<html><head><title>Request Rejected </title></head><body>Sorry, the requested URL was rejected. Please consult with your administrator..<br><br>Your support ID is: <9627954236696643144><br><br><a href='javascript:history.back();'>[Go Back]</body></html>

cookbook/use_cases/finance/02_Fraud_Detection.ipynb

@@ -98,7 +98,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n",
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n",
     "\n",
     "# Configuration constants\n",
     "EMBEDDING_DIMENSION = 384\n",

cookbook/use_cases/finance/03_Earnings_Call_Analysis.ipynb

@@ -35,14 +35,14 @@
     "## End-to-End Workflow\n",
     "\n",
     "**Workflow:**  \n",
-    "Dual PDF Input → Docling Parsing → Normalization & Chunking → Entity, Relation & Triplet Extraction → Conflict Resolution & Deduplication → Knowledge Graph Construction → Amazon Neptune → GraphRAG → Agent Memory & Context → Strategic Q&A\n",
+    "Dual PDF Input → Docling Parsing → Normalization & Chunking → Entity, Relation Extraction → Conflict Resolution & Deduplication → Knowledge Graph Construction → Amazon Neptune → GraphRAG → Agent Memory & Context → Strategic Q&A\n",
     "\n",
     "---\n",
     "\n",
     "## Pipeline Capabilities\n",
     "\n",
     "- High-fidelity PDF parsing (text, tables, structure)  \n",
-    "- Semantic extraction of entities, relationships, and triplets  \n",
+    "- Semantic extraction of entities, and relationships\n",
     "- Conflict detection and resolution with confidence awareness  \n",
     "- Entity deduplication and canonicalization  \n",
     "- Knowledge graph construction and validation  \n",
@@ -280,7 +280,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "from semantica.semantic_extract import NERExtractor\n",
     "\n",
     "ner = NERExtractor(\n",
@@ -289,27 +288,22 @@
     "    llm_model=\"llama-3.1-8b-instant\",\n",
     "    temperature=0.0,\n",
     "    api_key=GROQ_API_KEY,\n",
+    "    max_retries=3,\n",
     ")\n",
     "\n",
-    "ENTITY_TYPES = [\n",
-    "    \"ORGANIZATION\", \"ORG\", \"PERSON\", \"MONEY\", \"CURRENCY\",\n",
-    "    \"PERCENT\", \"PERCENTAGE\", \"DATE\", \"TIME\", \"PRODUCT\",\n",
-    "    \"LOCATION\", \"GPE\", \"EVENT\", \"QUANTITY\", \"CARDINAL\",\n",
+    "ENTITY_TYPES = [\"ORGANIZATION\", \"PERSON\", \"MONEY\", \"PERCENT\", \"DATE\", \"EVENT\"]\n",
+    "\n",
+    "all_entities = [\n",
+    "    e\n",
+    "    for c in chunks\n",
+    "    for e in ner.extract_entities(\n",
+    "        get_chunk_text(c),\n",
+    "        entity_types=ENTITY_TYPES,\n",
+    "    )\n",
+    "    if get_chunk_text(c).strip()\n",
     "]\n",
     "\n",
-    "all_entities = []\n",
-    "\n",
-    "for chunk in chunks:\n",
-    "    text = get_chunk_text(chunk)\n",
-    "    if text.strip():\n",
-    "        all_entities += ner.extract_entities(text, entity_types=ENTITY_TYPES)\n",
-    "\n",
-    "print(\"Entity extraction completed\")\n",
-    "print(\"Total entities extracted:\", len(all_entities))\n",
-    "\n",
-    "print(\"\\nSample entities\")\n",
-    "for e in all_entities[:10]:\n",
-    "    print(f\"{e.label}: {e.text}\")"
+    "print(\"Entities:\", len(all_entities))"
    ]
   },
   {
@@ -378,109 +372,104 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from concurrent.futures import ThreadPoolExecutor, TimeoutError\n",
     "from semantica.semantic_extract import RelationExtractor\n",
     "\n",
+    "MAX_ENTITIES = 30\n",
+    "CHUNK_TIMEOUT = 60\n",
+    "\n",
     "relation_extractor = RelationExtractor(\n",
     "    method=\"llm\",\n",
-    "    confidence_threshold=0.5,\n",
+    "    confidence_threshold=0.6,\n",
     "    relation_types=[\n",
-    "        \"HAS_REVENUE\", \"HAS_EPS\", \"HAS_MARGIN\", \"HAS_PROFIT\", \"HAS_GROWTH\",\n",
-    "        \"PROVIDES_GUIDANCE\", \"STATES\", \"ANNOUNCES\", \"REPORTS\", \"EXPECTS\",\n",
-    "        \"OPERATES_IN\", \"LOCATED_IN\", \"PARTNERS_WITH\", \"SERVES\",\n",
-    "        \"COMPARED_TO\", \"INCREASED_BY\", \"DECREASED_BY\", \"CHANGED_BY\",\n",
-    "        \"DURING\", \"IN_QUARTER\", \"FOR_PERIOD\",\n",
-    "        \"RELATED_TO\", \"PART_OF\", \"AFFECTS\",\n",
+    "        \"HAS_REVENUE\",\n",
+    "        \"HAS_GROWTH\",\n",
+    "        \"REPORTS\",\n",
+    "        \"PROVIDES_GUIDANCE\",\n",
+    "        \"IN_QUARTER\",\n",
+    "        \"FOR_PERIOD\",\n",
+    "        \"RELATED_TO\",\n",
     "    ],\n",
-    "    api_key=GROQ_API_KEY,\n",
-    ")\n",
-    "\n",
-    "def get_chunk_text(chunk):\n",
-    "    return getattr(chunk, \"content\", getattr(chunk, \"text\", \"\")) or \"\"\n",
-    "\n",
-    "relationships = []\n",
-    "\n",
-    "for chunk in chunks:\n",
-    "    text = get_chunk_text(chunk)\n",
-    "\n",
-    "    relations = relation_extractor.extract_relations(\n",
-    "        text,\n",
-    "        entities=all_entities,\n",
-    "        provider=\"groq\",\n",
-    "        llm_model=\"llama-3.1-8b-instant\",\n",
-    "        temperature=0.0,\n",
-    "    )\n",
-    "\n",
-    "    relationships += relations\n",
-    "\n",
-    "print(\"Relationship extraction completed\")\n",
-    "print(\"Total chunks:\", len(chunks))\n",
-    "print(\"Total relationships extracted:\", len(relationships))\n",
-    "\n",
-    "if relationships:\n",
-    "    r = relationships[0]\n",
-    "    print(\"Sample relationship:\")\n",
-    "    print(f\"{r.subject.text} → {r.predicate} → {r.object.text}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Step 6: Extract RDF Triplets\n",
-    "\n",
-    "Extract RDF triplets (subject-predicate-object) using TripletExtractor with Groq LLM.\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from semantica.semantic_extract import TripletExtractor\n",
-    "\n",
-    "triplet_extractor = TripletExtractor(\n",
-    "    method=\"llm\",\n",
-    "    include_temporal=True,\n",
-    "    include_provenance=True,\n",
     "    provider=\"groq\",\n",
     "    llm_model=\"llama-3.1-8b-instant\",\n",
-    "    temperature=0.0,\n",
     "    api_key=GROQ_API_KEY,\n",
+    "    temperature=0.0,\n",
+    "    verbose=False,\n",
     ")\n",
     "\n",
-    "def get_chunk_text(chunk):\n",
-    "    return getattr(chunk, \"content\", getattr(chunk, \"text\", \"\")) or \"\"\n",
     "\n",
-    "triplets = []\n",
+    "def filter_entities(text, entities):\n",
+    "    t = text.lower()\n",
+    "    return [e for e in entities if e.text.lower() in t]\n",
     "\n",
-    "for chunk in chunks:\n",
-    "    text = get_chunk_text(chunk)\n",
     "\n",
-    "    triplets += triplet_extractor.extract_triplets(\n",
-    "        text,\n",
-    "        entities=all_entities,\n",
-    "        relations=relationships if relationships else None,\n",
+    "def process_chunk(idx, chunk, total):\n",
+    "    text = get_chunk_text(chunk).strip()\n",
+    "\n",
+    "    remaining = total - (idx + 1)\n",
+    "\n",
+    "    if not text:\n",
+    "        print(f\"Chunk {idx+1}/{total} | remaining {remaining} | skipped (empty)\")\n",
+    "        return []\n",
+    "\n",
+    "    chunk_entities = filter_entities(text, all_entities)[:MAX_ENTITIES]\n",
+    "\n",
+    "    if len(chunk_entities) < 2:\n",
+    "        print(\n",
+    "            f\"Chunk {idx+1}/{total} | remaining {remaining} | \"\n",
+    "            f\"skipped (entities={len(chunk_entities)})\"\n",
+    "        )\n",
+    "        return []\n",
+    "\n",
+    "    print(\n",
+    "        f\"Chunk {idx+1}/{total} | remaining {remaining} | \"\n",
+    "        f\"entities={len(chunk_entities)}\"\n",
     "    )\n",
     "\n",
-    "if hasattr(triplet_extractor, \"validate_triplets\"):\n",
-    "    triplets = triplet_extractor.validate_triplets(triplets)\n",
+    "    return relation_extractor.extract_relations(\n",
+    "        text=text,\n",
+    "        entities=chunk_entities,\n",
+    "        verbose=False,\n",
+    "    )\n",
     "\n",
-    "print(\"Triplet extraction completed\")\n",
-    "print(\"Total chunks:\", len(chunks))\n",
-    "print(\"Total RDF triplets:\", len(triplets))\n",
     "\n",
-    "if triplets:\n",
-    "    t = triplets[0]\n",
-    "    print(\"Sample triplet:\")\n",
-    "    print(f\"{t.subject} → {t.predicate} → {t.object}\")\n"
+    "relationships = []\n",
+    "total_chunks = len(chunks)\n",
+    "\n",
+    "with ThreadPoolExecutor(max_workers=1) as executor:\n",
+    "    for i, c in enumerate(chunks):\n",
+    "        future = executor.submit(process_chunk, i, c, total_chunks)\n",
+    "\n",
+    "        try:\n",
+    "            rels = future.result(timeout=CHUNK_TIMEOUT)\n",
+    "            relationships.extend(rels)\n",
+    "            print(f\"  relations={len(rels)}\")\n",
+    "\n",
+    "        except TimeoutError:\n",
+    "            remaining = total_chunks - (i + 1)\n",
+    "            print(\n",
+    "                f\"Chunk {i+1}/{total_chunks} | remaining {remaining} | timed out\"\n",
+    "            )\n",
+    "\n",
+    "        except Exception as e:\n",
+    "            remaining = total_chunks - (i + 1)\n",
+    "            print(\n",
+    "                f\"Chunk {i+1}/{total_chunks} | remaining {remaining} | failed: {e}\"\n",
+    "            )\n",
+    "\n",
+    "print(f\"Done {total_chunks}/{total_chunks}\")\n",
+    "print(f\"Total relationships: {len(relationships)}\")\n",
+    "\n",
+    "if relationships:\n",
+    "    for r in relationships[:10]:\n",
+    "        print(f\"{r.subject.text} → {r.predicate} → {r.object.text}\")\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 7: Detect Conflicts\n",
+    "## Step 6: Detect Conflicts\n",
     "\n",
     "Detect conflicts in extracted entities and relationships using ConflictDetector.\n"
    ]
@@ -494,46 +483,76 @@
     "from semantica.conflicts import SourceTracker, SourceReference, ConflictDetector\n",
     "\n",
     "source_tracker = SourceTracker()\n",
+    "\n",
     "conflict_detector = ConflictDetector(\n",
     "    source_tracker=source_tracker,\n",
     "    similarity_threshold=0.8,\n",
     "    confidence_threshold=0.7,\n",
     ")\n",
     "\n",
-    "for entity in all_entities:\n",
-    "    entity_id = getattr(entity, \"id\", None) or getattr(entity, \"text\", \"\")\n",
-    "    entity_text = getattr(entity, \"text\", \"\")\n",
-    "    entity_label = getattr(entity, \"label\", \"UNKNOWN\")\n",
+    "entities = all_entities\n",
+    "extracted_relationships = relationships\n",
     "\n",
+    "for e in entities:\n",
+    "    entity_id = getattr(e, \"id\", None) or e.text\n",
     "    source_tracker.track_property_source(\n",
-    "        entity_id,\n",
-    "        \"name\",\n",
-    "        entity_text,\n",
-    "        # FIXED: Changed 'source' to 'document' to match SourceReference signature\n",
+    "        entity_id=entity_id,\n",
+    "        property_name=\"name\",\n",
+    "        value=e.text,\n",
     "        source=SourceReference(\n",
-    "            document=\"earnings_call\",  # Was incorrect: source=\"earnings_call\"\n",
+    "            document=\"earnings_call\",\n",
     "            timestamp=\"2024-Q1\",\n",
-    "            metadata={\"entity_type\": entity_label},\n",
+    "            metadata={\"entity_type\": getattr(e, \"label\", \"UNKNOWN\")},\n",
     "        ),\n",
     "    )\n",
     "\n",
-    "value_conflicts = conflict_detector.detect_value_conflicts(\n",
-    "    [{\"id\": getattr(e, \"id\", \"\"), \"name\": getattr(e, \"text\", \"\")} for e in all_entities],\n",
+    "entity_records = [\n",
+    "    {\n",
+    "        \"id\": getattr(e, \"id\", None) or e.text,\n",
+    "        \"name\": e.text,\n",
+    "    }\n",
+    "    for e in entities\n",
+    "]\n",
+    "\n",
+    "entity_value_conflicts = conflict_detector.detect_value_conflicts(\n",
+    "    entity_records,\n",
     "    property_name=\"name\",\n",
     ")\n",
     "\n",
-    "relationship_conflicts = conflict_detector.detect_relationship_conflicts(relationships)\n",
+    "normalized_relationships = [\n",
+    "    {\n",
+    "        \"id\": getattr(r, \"id\", None),\n",
+    "        \"source_id\": getattr(r.subject, \"id\", None) or r.subject.text,\n",
+    "        \"target_id\": getattr(r.object, \"id\", None) or r.object.text,\n",
+    "        \"type\": r.predicate,\n",
+    "        \"confidence\": getattr(r, \"confidence\", 1.0),\n",
+    "        \"metadata\": {},\n",
+    "    }\n",
+    "    for r in extracted_relationships\n",
+    "]\n",
+    "\n",
+    "relationship_conflicts = conflict_detector.detect_relationship_conflicts(\n",
+    "    normalized_relationships\n",
+    ")\n",
     "\n",
     "print(\"Conflict detection completed\")\n",
-    "print(\"Value conflicts:\", len(value_conflicts))\n",
-    "print(\"Relationship conflicts:\", len(relationship_conflicts))"
+    "print(\"Entity value conflicts:\", len(entity_value_conflicts))\n",
+    "print(\"Relationship conflicts:\", len(relationship_conflicts))\n",
+    "\n",
+    "if entity_value_conflicts:\n",
+    "    print(\"\\nSample entity conflict:\")\n",
+    "    print(entity_value_conflicts[0])\n",
+    "\n",
+    "if relationship_conflicts:\n",
+    "    print(\"\\nSample relationship conflict:\")\n",
+    "    print(relationship_conflicts[0])"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 8: Resolve Conflicts\n",
+    "## Step 7: Resolve Conflicts\n",
     "\n",
     "Resolve detected conflicts using ConflictResolver with voting strategy.\n"
    ]
@@ -551,27 +570,43 @@
     "    source_tracker=source_tracker,\n",
     ")\n",
     "\n",
-    "resolved_conflicts = []\n",
+    "resolved_entity_value_conflicts = []\n",
+    "resolved_relationship_conflicts = []\n",
     "\n",
-    "for conflict in value_conflicts:\n",
-    "    resolved_conflicts.append(\n",
-    "        conflict_resolver.resolve_conflict(conflict, strategy=\"voting\")\n",
+    "for conflict in entity_value_conflicts:\n",
+    "    resolved_entity_value_conflicts.append(\n",
+    "        conflict_resolver.resolve_conflict(\n",
+    "            conflict,\n",
+    "            strategy=\"voting\",\n",
+    "        )\n",
     "    )\n",
     "\n",
     "for conflict in relationship_conflicts:\n",
-    "    resolved_conflicts.append(\n",
-    "        conflict_resolver.resolve_conflict(conflict, strategy=\"voting\")\n",
+    "    resolved_relationship_conflicts.append(\n",
+    "        conflict_resolver.resolve_conflict(\n",
+    "            conflict,\n",
+    "            strategy=\"voting\",\n",
+    "        )\n",
     "    )\n",
     "\n",
     "print(\"Conflict resolution completed\")\n",
-    "print(\"Total conflicts resolved:\", len(resolved_conflicts))\n"
+    "print(\"Entity value conflicts resolved:\", len(resolved_entity_value_conflicts))\n",
+    "print(\"Relationship conflicts resolved:\", len(resolved_relationship_conflicts))\n",
+    "\n",
+    "if resolved_entity_value_conflicts:\n",
+    "    print(\"\\nSample resolved entity conflict:\")\n",
+    "    print(resolved_entity_value_conflicts[0])\n",
+    "\n",
+    "if resolved_relationship_conflicts:\n",
+    "    print(\"\\nSample resolved relationship conflict:\")\n",
+    "    print(resolved_relationship_conflicts[0])"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 9: Deduplicate Entities\n",
+    "## Step 8: Deduplicate Entities\n",
     "\n",
     "Detect and merge duplicate entities using DuplicateDetector and EntityMerger.\n"
    ]
@@ -583,45 +618,87 @@
    "outputs": [],
    "source": [
     "from semantica.deduplication import DuplicateDetector, EntityMerger\n",
+    "import time\n",
     "\n",
-    "duplicate_detector = DuplicateDetector(\n",
-    "    similarity_threshold=0.8,\n",
-    "    confidence_threshold=0.7,\n",
+    "start_time = time.time()\n",
+    "\n",
+    "raw = []\n",
+    "for i, e in enumerate(entities):\n",
+    "    raw.append({\n",
+    "        \"id\": getattr(e, \"id\", None) or f\"entity_{i}_{getattr(e, 'text', str(e))}\",\n",
+    "        \"name\": (getattr(e, \"text\", getattr(e, \"name\", \"\")) or \"\").strip(),\n",
+    "        \"type\": getattr(e, \"label\", \"UNKNOWN\"),\n",
+    "        \"confidence\": float(getattr(e, \"confidence\", 1.0) or 1.0),\n",
+    "        \"metadata\": getattr(e, \"metadata\", {}),\n",
+    "    })\n",
+    "\n",
+    "filtered = [r for r in raw if r[\"name\"] and len(r[\"name\"]) >= 3]\n",
+    "\n",
+    "collapsed = {}\n",
+    "for ent in filtered:\n",
+    "    key = (ent[\"type\"], ent[\"name\"].lower())\n",
+    "    best = collapsed.get(key)\n",
+    "    if best is None or ent[\"confidence\"] > best[\"confidence\"]:\n",
+    "        collapsed[key] = ent\n",
+    "\n",
+    "entity_dicts = list(collapsed.values())\n",
+    "\n",
+    "detector = DuplicateDetector(\n",
+    "    similarity_threshold=0.96,\n",
+    "    confidence_threshold=0.92,\n",
+    "    use_clustering=True,\n",
     ")\n",
     "\n",
-    "entity_dicts = [\n",
-    "    {\n",
-    "        \"id\": getattr(e, \"id\", \"\"),\n",
-    "        \"name\": getattr(e, \"text\", \"\"),\n",
-    "        \"type\": getattr(e, \"label\", \"UNKNOWN\"),\n",
-    "        \"confidence\": getattr(e, \"confidence\", 1.0),\n",
-    "        \"metadata\": getattr(e, \"metadata\", {}),\n",
-    "    }\n",
-    "    for e in resolved_entities\n",
-    "]\n",
+    "detector.detect_duplicate_groups(entity_dicts)\n",
     "\n",
-    "duplicates = duplicate_detector.detect_duplicates(entity_dicts)\n",
+    "merger = EntityMerger(\n",
+    "    preserve_provenance=True,\n",
+    "    detector={\n",
+    "        \"similarity_threshold\": 0.96,\n",
+    "        \"confidence_threshold\": 0.92,\n",
+    "        \"use_clustering\": True,\n",
+    "    },\n",
+    "    strategy={\"default_strategy\": \"keep_most_complete\"},\n",
+    ")\n",
     "\n",
-    "entity_merger = EntityMerger(preserve_provenance=True)\n",
-    "\n",
-    "merge_operations = entity_merger.merge_duplicates(\n",
-    "    entity_dicts,\n",
+    "merge_operations = merger.merge_duplicates(\n",
+    "    entities=entity_dicts,\n",
     "    strategy=\"keep_most_complete\",\n",
     ")\n",
     "\n",
-    "merged_entities = [op.merged_entity for op in merge_operations]\n",
+    "deduplicated_entities = [op.merged_entity for op in merge_operations] or entity_dicts\n",
     "\n",
-    "print(\"Entity deduplication completed\")\n",
-    "print(\"Original entities:\", len(entity_dicts))\n",
-    "print(\"Merged entities:\", len(merged_entities))\n",
-    "print(\"Duplicates removed:\", len(entity_dicts) - len(merged_entities))\n"
+    "entity_id_mapping = {}\n",
+    "for op in merge_operations:\n",
+    "    mid = op.merged_entity[\"id\"]\n",
+    "    for sid in op.source_ids:\n",
+    "        entity_id_mapping[sid] = mid\n",
+    "\n",
+    "deduplicated_relationships = []\n",
+    "for rel in normalized_relationships:\n",
+    "    s = entity_id_mapping.get(rel[\"source_id\"], rel[\"source_id\"])\n",
+    "    t = entity_id_mapping.get(rel[\"target_id\"], rel[\"target_id\"])\n",
+    "    if s != t:\n",
+    "        r = rel.copy()\n",
+    "        r[\"source_id\"], r[\"target_id\"] = s, t\n",
+    "        deduplicated_relationships.append(r)\n",
+    "\n",
+    "print({\n",
+    "    \"time_seconds\": round(time.time() - start_time, 2),\n",
+    "    \"entities_in\": len(raw),\n",
+    "    \"entities_after_filter\": len(filtered),\n",
+    "    \"entities_after_exact\": len(entity_dicts),\n",
+    "    \"entities_out\": len(deduplicated_entities),\n",
+    "    \"duplicates_removed\": len(entity_dicts) - len(deduplicated_entities),\n",
+    "    \"relationships_updated\": len(deduplicated_relationships),\n",
+    "})"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 10: Build Knowledge Graph\n",
+    "## Step 9: Build Knowledge Graph\n",
     "\n",
     "Build knowledge graph from cleaned entities, relationships, and triplets using GraphBuilder.\n"
    ]
@@ -634,28 +711,17 @@
    "source": [
     "from semantica.kg import GraphBuilder\n",
     "\n",
+    "# Deduplication is already done; avoid additional entity resolution/merging\n",
     "graph_builder = GraphBuilder(\n",
-    "    merge_entities=True,\n",
-    "    entity_resolution_strategy=\"fuzzy\",\n",
+    "    merge_entities=False,\n",
+    "    entity_resolution_strategy=\"none\",\n",
     ")\n",
     "\n",
-    "triplet_relationships = [\n",
-    "    {\n",
-    "        \"source\": t.subject,\n",
-    "        \"predicate\": t.predicate,\n",
-    "        \"target\": t.object,\n",
-    "        \"confidence\": t.confidence,\n",
-    "        \"metadata\": t.metadata,\n",
-    "    }\n",
-    "    for t in validated_triplets\n",
-    "]\n",
-    "\n",
-    "final_relationships = resolved_relationships + triplet_relationships\n",
+    "final_relationships = deduplicated_relationships\n",
     "\n",
     "kg_data = {\n",
-    "    \"entities\": merged_entities,\n",
+    "    \"entities\": deduplicated_entities,\n",
     "    \"relationships\": final_relationships,\n",
-    "    \"triplets\": validated_triplets,\n",
     "    \"metadata\": {\n",
     "        \"source\": \"earnings_call_transcript\",\n",
     "        \"extraction_method\": \"Groq LLM\",\n",
@@ -664,19 +730,19 @@
     "\n",
     "knowledge_graph = graph_builder.build(\n",
     "    sources=[kg_data],\n",
-    "    merge_entities=True,\n",
+    "    merge_entities=False,\n",
     ")\n",
     "\n",
-    "print(\"Knowledge graph build completed\")\n",
+    "print(\"Knowledge graph build completed (no additional merging)\")\n",
     "print(\"Final entities:\", len(knowledge_graph.get(\"entities\", [])))\n",
-    "print(\"Final relationships:\", len(knowledge_graph.get(\"relationships\", [])))\n"
+    "print(\"Final relationships:\", len(knowledge_graph.get(\"relationships\", [])))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 11: Analyze Knowledge Graph\n",
+    "## Step 10: Analyze Knowledge Graph\n",
     "\n",
     "This step evaluates the structure and quality of the knowledge graph.\n",
     "\n",
@@ -714,19 +780,17 @@
     "connectivity = graph_analyzer.analyze_connectivity(knowledge_graph)\n",
     "metrics = graph_analyzer.compute_metrics(knowledge_graph)\n",
     "\n",
-    "top_entities = centrality.get(\"rankings\", [])[:5]\n",
     "num_communities = len(communities.get(\"communities\", []))\n",
     "\n",
     "print(\"Graph analysis completed\")\n",
-    "print(\"Communities:\", num_communities)\n",
-    "print(\"Top entities:\", len(top_entities))\n"
+    "print(\"Communities:\", num_communities)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 12: Persist Knowledge Graph in Amazon Neptune\n",
+    "## Step 11: Persist Knowledge Graph in Amazon Neptune\n",
     "\n",
     "After cleaning, conflict resolution, and deduplication, the final step is to\n",
     "persist the **canonical knowledge graph** into a production graph database.\n",
@@ -841,7 +905,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 13: Context Retrieval\n",
+    "## Step 12: Context Retrieval\n",
     "\n",
     "Set up hybrid retrieval (vector + graph) using ContextRetriever for GraphRAG queries.\n"
    ]
@@ -852,31 +916,62 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import time\n",
     "from semantica.vector_store import VectorStore\n",
     "from semantica.context import ContextRetriever\n",
     "\n",
-    "vector_store = VectorStore(backend=\"faiss\")\n",
+    "if 'chunks' not in locals() or not chunks:\n",
+    "    raise ValueError(\"Chunks not found. Please run Step 3 first.\")\n",
     "\n",
-    "vector_store.add(\n",
-    "    texts=[parsed_doc[\"full_text\"]],\n",
-    "    metadata=[{\"source\": \"earnings_call\", \"type\": \"transcript\"}],\n",
+    "# Extract text content safely\n",
+    "chunk_texts = [getattr(c, \"content\", getattr(c, \"text\", \"\")) for c in chunks]\n",
+    "chunk_metadatas = [\n",
+    "    {\n",
+    "        \"source\": \"earnings_call\", \n",
+    "        \"type\": \"transcript\", \n",
+    "        \"chunk_index\": i,\n",
+    "        **(getattr(c, \"metadata\", {}) or {})\n",
+    "    }\n",
+    "    for i, c in enumerate(chunks)\n",
+    "]\n",
+    "\n",
+    "# Initialize Vector Store (Optimized for Speed)\n",
+    "# dimension=384 matches the default fast model (BAAI/bge-small-en-v1.5)\n",
+    "vector_store = VectorStore(\n",
+    "    backend=\"faiss\", \n",
+    "    dimension=384,  \n",
+    "    max_workers=16\n",
     ")\n",
     "\n",
+    "print(f\"Storing {len(chunks)} chunks with high-performance settings...\")\n",
+    "start_time = time.time()\n",
+    "\n",
+    "# Store in large batches with parallel processing\n",
+    "vector_ids = vector_store.add_documents(\n",
+    "    documents=chunk_texts,\n",
+    "    metadata=chunk_metadatas,\n",
+    "    batch_size=128,\n",
+    "    parallel=True\n",
+    ")\n",
+    "\n",
+    "print(f\"✅ Stored in {time.time() - start_time:.2f}s\")\n",
+    "\n",
+    "# Initialize Hybrid Retriever\n",
     "context_retriever = ContextRetriever(\n",
-    "    knowledge_graph=knowledge_graph,\n",
+    "    knowledge_graph=knowledge_graph, # Assumes knowledge_graph exists\n",
     "    vector_store=vector_store,\n",
     "    hybrid_alpha=0.6,\n",
     "    use_graph_expansion=True,\n",
     "    max_expansion_hops=2,\n",
     ")\n",
     "\n",
+    "# Test Retrieval\n",
     "queries = [\n",
     "    \"What was the company's revenue guidance?\",\n",
     "    \"What were the key financial metrics discussed?\",\n",
     "]\n",
     "\n",
     "retrieved_contexts = []\n",
-    "\n",
     "for query in queries:\n",
     "    results = context_retriever.retrieve(\n",
     "        query=query,\n",
@@ -886,15 +981,14 @@
     "    retrieved_contexts.append(results)\n",
     "\n",
     "print(\"Hybrid GraphRAG configured\")\n",
-    "print(\"Queries processed:\", len(queries))\n",
-    "print(\"Sample results:\", len(retrieved_contexts[0]) if retrieved_contexts else 0)\n"
+    "print(\"Sample results:\", len(retrieved_contexts[0]) if retrieved_contexts else 0)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 14: Agent Memory (Long-Term Context)\n",
+    "## Step 13: Agent Memory (Long-Term Context)\n",
     "\n",
     "This step enables long-term memory for agents by storing important facts,\n",
     "metrics, and entities extracted from the knowledge graph.\n",
@@ -930,10 +1024,13 @@
     "    retention_days=30,\n",
     ")\n",
     "\n",
+    "entity_count = len(knowledge_graph.get(\"entities\", []))\n",
+    "relationship_count = len(knowledge_graph.get(\"relationships\", []))\n",
+    "\n",
     "memory_contents = [\n",
     "    f\"Earnings call transcript: {parsed_doc['metadata'].get('title', 'Earnings Call')}\",\n",
-    "    f\"Financial metrics extracted: {sum(len(v) for v in financial_metrics.values())}\",\n",
-    "    f\"Key entities identified: {len(merged_entities)}\",\n",
+    "    f\"Graph entities: {entity_count}\",\n",
+    "    f\"Graph relationships: {relationship_count}\",\n",
     "]\n",
     "\n",
     "memory_ids = []\n",
@@ -958,14 +1055,14 @@
     "print(\"Agent memory configured\")\n",
     "print(\"Memories stored:\", len(memory_ids))\n",
     "print(\"Total memories:\", memory_stats.get(\"total_memories\", 0))\n",
-    "print(\"Retrieved memories:\", len(financial_memories))\n"
+    "print(\"Retrieved memories:\", len(financial_memories))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 15: Agent Context\n",
+    "## Step 14: Agent Context\n",
     "\n",
     "**AgentContext** provides a unified context layer that combines **vector-based RAG**\n",
     "with **graph-based GraphRAG** for grounded and explainable retrieval.\n",
@@ -1009,7 +1106,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -1037,7 +1134,7 @@
     ")\n",
     "\n",
     "memory_id = agent_context.store(\n",
-    "    content=parsed_doc[\"full_text\"][:1000],\n",
+    "    content=chunks,\n",
     "    metadata={\"source\": \"earnings_call\", \"date\": \"2024-Q1\"},\n",
     "    extract_entities=True,\n",
     "    extract_relationships=True,\n",
@@ -1063,7 +1160,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 16: Answer Generation\n",
+    "## Step 15: Answer Generation\n",
     "\n",
     "Generate answers to financial questions using Groq LLM with retrieved context and knowledge graph.\n"
    ]
@@ -1081,32 +1178,71 @@
     "\n",
     "generated_answers = []\n",
     "\n",
+    "print(\"--- Generating Enhanced Answers ---\\n\")\n",
+    "\n",
+    "def format_context(retrieved_contexts):\n",
+    "    \"\"\"Formats retrieved context with graph information.\"\"\"\n",
+    "    formatted_parts = []\n",
+    "    \n",
+    "    for i, ctx in enumerate(retrieved_contexts):\n",
+    "        content = getattr(ctx, \"content\", \"\")\n",
+    "        source = getattr(ctx, \"source\", \"unknown\")\n",
+    "        \n",
+    "        # Format related entities from the graph\n",
+    "        related_entities = getattr(ctx, \"related_entities\", [])\n",
+    "        entities_str = \", \".join([\n",
+    "            f\"{e.get('name', 'Unknown')} ({e.get('type', 'Entity')})\" \n",
+    "            for e in related_entities[:5]  # Limit to top 5 per chunk\n",
+    "        ])\n",
+    "        \n",
+    "        # Format related relationships\n",
+    "        related_rels = getattr(ctx, \"related_relationships\", [])\n",
+    "        rels_str = \"; \".join([\n",
+    "            f\"{r.get('source', '')} -> {r.get('type', '')} -> {r.get('target', '')}\"\n",
+    "            for r in related_rels[:3]  # Limit to top 3 per chunk\n",
+    "        ])\n",
+    "        \n",
+    "        part = f\"Source {i+1} ({source}):\\n{content}\\n\"\n",
+    "        if entities_str:\n",
+    "            part += f\"Related Entities: {entities_str}\\n\"\n",
+    "        if rels_str:\n",
+    "            part += f\"Graph Connections: {rels_str}\\n\"\n",
+    "            \n",
+    "        formatted_parts.append(part)\n",
+    "        \n",
+    "    return \"\\n---\\n\".join(formatted_parts)\n",
+    "\n",
     "for question in financial_questions:\n",
+    "    print(f\"Question: {question}\")\n",
+    "    \n",
+    "    # Retrieve with graph expansion enabled and higher limits\n",
     "    retrieved_contexts = context_retriever.retrieve(\n",
     "        query=question,\n",
-    "        max_results=3,\n",
+    "        max_results=10,          # Increased from 3\n",
     "        min_relevance_score=0.2,\n",
+    "        use_graph_expansion=True, # Explicitly enable graph expansion\n",
+    "        max_hops=2               # Traverse up to 2 hops in the graph\n",
     "    )\n",
     "\n",
-    "    context_text = \"\\n\\n\".join(\n",
-    "        ctx.get(\"content\", ctx.get(\"text\", \"\"))\n",
-    "        for ctx in retrieved_contexts\n",
-    "    )[:1000]\n",
+    "    # Use the rich formatter\n",
+    "    context_text = format_context(retrieved_contexts)\n",
     "\n",
-    "    entity_names = [\n",
-    "        entity.get(\"name\", \"\")\n",
-    "        for entity in knowledge_graph.get(\"entities\", [])[:5]\n",
+    "    # Get global key entities (optional, but good for high-level context)\n",
+    "    global_entities = [\n",
+    "        f\"{e.get('name', '')} ({e.get('type', '')})\"\n",
+    "        for e in knowledge_graph.get(\"entities\", [])[:10]\n",
     "    ]\n",
-    "    entities_text = \", \".join(entity_names) or \"N/A\"\n",
+    "    global_entities_text = \", \".join(global_entities)\n",
     "\n",
     "    prompt = f\"\"\"\n",
-    "Answer the question using only the context below.\n",
+    "Answer the question comprehensively using the provided context.\n",
+    "The context includes text chunks and knowledge graph connections (entities and relationships).\n",
     "If the answer is not present, say so.\n",
     "\n",
     "Context:\n",
     "{context_text}\n",
     "\n",
-    "Key entities: {entities_text}\n",
+    "Global Key Entities: {global_entities_text}\n",
     "\n",
     "Question:\n",
     "{question}\n",
@@ -1117,23 +1253,25 @@
     "    try:\n",
     "        answer = groq_llm.generate(\n",
     "            prompt,\n",
-    "            temperature=0.7,\n",
-    "            max_tokens=400,\n",
+    "            temperature=0.3, # Lower temperature for more factual answers\n",
+    "            max_tokens=1000, # Allow longer answers\n",
     "        )\n",
     "    except Exception as error:\n",
     "        answer = f\"Answer generation failed: {error}\"\n",
     "\n",
     "    generated_answers.append(answer)\n",
+    "    print(f\"Answer: {answer}\\n\")\n",
+    "    print(\"-\" * 50 + \"\\n\")\n",
     "\n",
     "print(\"Answer generation completed\")\n",
-    "print(\"Questions answered:\", len(generated_answers))\n"
+    "print(\"Questions answered:\", len(generated_answers))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Step 17: Export Results\n",
+    "## Step 16: Export Results\n",
     "\n",
     "Export knowledge graph and analysis results to JSON and RDF formats.\n"
    ]
@@ -1145,29 +1283,44 @@
    "outputs": [],
    "source": [
     "from semantica.export import JSONExporter, RDFExporter\n",
+    "import json\n",
     "\n",
+    "# Initialize exporters\n",
     "json_exporter = JSONExporter()\n",
     "rdf_exporter = RDFExporter()\n",
     "\n",
-    "kg_json = json_exporter.export(knowledge_graph, format=\"json\")\n",
-    "kg_rdf = rdf_exporter.export_to_rdf(knowledge_graph, format=\"turtle\")\n",
+    "# Define output file paths\n",
+    "json_output_path = \"knowledge_graph.json\"\n",
+    "rdf_output_path = \"knowledge_graph.ttl\"\n",
     "\n",
+    "# Export to files (required by the API)\n",
+    "json_exporter.export(knowledge_graph, file_path=json_output_path, format=\"json\")\n",
+    "\n",
+    "# FIXED: Use .export() instead of .export_to_rdf() to write to disk\n",
+    "rdf_exporter.export(knowledge_graph, file_path=rdf_output_path, format=\"turtle\")\n",
+    "\n",
+    "# Load the RDF file content to check its size\n",
+    "with open(rdf_output_path, \"r\", encoding=\"utf-8\") as f:\n",
+    "    kg_rdf_content = f.read()\n",
+    "\n",
+    "# Create analysis summary\n",
     "analysis_summary = {\n",
     "    \"entities\": len(knowledge_graph.get(\"entities\", [])),\n",
     "    \"relationships\": len(knowledge_graph.get(\"relationships\", [])),\n",
-    "    \"triplets\": len(triplets),\n",
-    "    \"conflicts_resolved\": len(resolved_conflicts),\n",
-    "    \"merged_entities\": len(merged_entities),\n",
-    "    \"communities\": num_communities,\n",
+    "    \"entity_conflicts_resolved\": len(locals().get(\"resolved_entity_value_conflicts\", [])),\n",
+    "    \"relationship_conflicts_resolved\": len(locals().get(\"resolved_relationship_conflicts\", [])),\n",
+    "    \"deduplicated_entities\": len(locals().get(\"deduplicated_entities\", [])),\n",
+    "    \"communities\": locals().get(\"num_communities\", 0),\n",
     "    \"questions_answered\": len(generated_answers),\n",
-    "    \"llm_model\": groq_llm.model,\n",
+    "    \"llm_model\": getattr(groq_llm, \"model\", \"unknown\"),\n",
     "}\n",
     "\n",
     "print(\"Export completed\")\n",
     "print(\"KG JSON entities:\", analysis_summary[\"entities\"])\n",
-    "print(\"KG RDF size (chars):\", len(kg_rdf))\n",
+    "print(\"KG RDF size (chars):\", len(kg_rdf_content))\n",
     "print(\"Questions answered:\", analysis_summary[\"questions_answered\"])\n",
-    "print(\"LLM model:\", analysis_summary[\"llm_model\"])\n"
+    "print(\"LLM model:\", analysis_summary[\"llm_model\"])\n",
+    "print(\"Conflicts resolved:\", analysis_summary[\"entity_conflicts_resolved\"] + analysis_summary[\"relationship_conflicts_resolved\"])"
    ]
   }
  ],

cookbook/use_cases/intelligence/02_Intelligence_Analysis_Orchestrator_Worker.ipynb

@@ -83,7 +83,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n",
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n",
     "\n",
     "# Configuration constants\n",
     "EMBEDDING_DIMENSION = 384\n",

cookbook/use_cases/renewable_energy/01_Energy_Market_Analysis.ipynb

@@ -80,7 +80,7 @@
    "source": [
     "import os\n",
     "\n",
-    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"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\")\n",
+    "os.environ[\"GROQ_API_KEY\"] = os.getenv(\"GROQ_API_KEY\", \"\")\n",
     "\n",
     "# Configuration constants\n",
     "EMBEDDING_DIMENSION = 384\n",

docs/CodeExamples.md

@@ -1018,7 +1018,7 @@ knowledge_graph.apply_resolutions(resolved_data)
 
 ### 💬 Community Support
 
-- **💬 [Discord Community](https://discord.gg/semantica)** - Real-time chat and support
+- **💬 [Discord Community](https://discord.gg/sV34vps5hH)** - Real-time chat and support
 - **🐙 [GitHub Discussions](https://github.com/semantica/semantica/discussions)** - Community Q&A
 - **📧 [Mailing List](https://groups.google.com/g/semantica)** - Announcements and updates
 - **🐦 [Twitter](https://twitter.com/semantica)** - Latest news and tips
@@ -1051,6 +1051,6 @@ This project is licensed under the MIT License - see the [LICENSE](https://githu
 
 **🚀 Ready to transform your data into intelligent knowledge?**
 
-[Get Started Now](https://semantica.readthedocs.io/quickstart/) • [View Examples](https://github.com/semantica/examples) • [Join Community](https://discord.gg/semantica)
+[Get Started Now](https://semantica.readthedocs.io/quickstart/) • [View Examples](https://github.com/semantica/examples) • [Join Community](https://discord.gg/sV34vps5hH)
 
 </div>