[FEATURE] Named Graph Support

[KaifAhmad1]

Enable multiple graph partitions (dev/staging/prod, tenants, trust tiers) inside a single RDF store using SPARQL named graphs.

---

Code Locations and Test Suites

• Core implementation belongs in:
  • semantica/triplet_store/ (SPARQL + RDF operations).
  • semantica/graph_store/ (backend‑specific behavior).
  • semantica/change_management/ (version and environment metadata).
• Tests for named graphs should extend the existing suites:
  • tests/triplet_store/
  • tests/graph_store/
  • tests/change_management/
• No new folders are needed; everything lives under semantica/ and tests/.

---

Capabilities Provided by This Feature

• Represents logical datasets and tiers as named graphs (graph URIs) instead of separate databases.
• Lets queries and validations target specific graphs or combinations of graphs.
• Integrates with change management and versioning to track lineage, environments, and trust levels.

---

Deployment and Architecture Impact

• Enables multi‑environment setups (dev/staging/prod) in one store.
• Supports multi‑tenant and multi‑tier architectures without extra databases.
• Improves data lineage and trust modeling using standard SPARQL concepts.
• Critical for enterprise‑scale deployments where isolation and governance matter.

---

Existing Infrastructure

Semantica already includes the core plumbing required for named graphs:

• Triplet store and SPARQL
  • semantica/triplet_store/triplet_store.py
    • Backend‑agnostic triple operations.
  • semantica/triplet_store/query_engine.py
    • SPARQL execution with optimization and caching.
  • semantica/triplet_store/config.py
    • Central configuration for RDF backends.
• Graph store
  • semantica/graph_store/*.py
    • Integrations with individual graph databases and a registry.
• Change management
  • semantica/change_management/version_storage.py
  • semantica/change_management/ontology_version_manager.py
• Documentation and tests
  • docs/reference/triplet_store.md
  • docs/reference/graph_store.md
  • docs/reference/change_management.md
  • tests/triplet_store/test_triplet_store.py
  • tests/graph_store/test_graph_store.py
  • tests/change_management/test_version_storage.py

---

Changes Required in Existing Modules

Named graph support should be implemented on top of the existing modules:

• Config for graph URIs
  • In semantica/triplet_store/config.py:
    • Add configuration fields such as default_graph_uri and environment‑specific named graph URIs.
• Graph‑aware TripletStore operations
  • In semantica/triplet_store/triplet_store.py:
    • Extend read/write APIs with an optional graph: Optional[str] parameter.
    • Forward this to backends that support named graphs, and ignore safely where unsupported.
• SPARQL support for named graphs
  • In semantica/triplet_store/query_engine.py:
    • Allow execute_query and related helpers to accept graph / graphs arguments.
    • When provided, add appropriate FROM and FROM NAMED clauses.
• Graph store routing
  • In semantica/graph_store backends:
    • Map logical graph URIs to underlying database constructs (labels, schemas, DBs) where possible.
• Versioning and lineage integration
  • In semantica/change_management/version_storage.py and ontology_version_manager.py:
    • Associate snapshot/version identifiers with the graph URIs they live in.
• Documentation and tests
  • Extend the docs and tests listed above with scenarios for:
    • Writing to and reading from specific named graphs.
    • Ensuring isolation between graphs while preserving backward‑compatible defaults.

---

Implementation Notes and Steps

1. Introduce graph identifiers in configuration

   • In triplet_store/config.py:
     • Add configuration fields for:
       • default_graph_uri
       • named graph URIs for environments or tenants (e.g. graphs.dev, graphs.staging).

2. Extend TripletStore APIs with optional graph parameter

   • In triplet_store/triplet_store.py:
     • For write/read methods, add an optional graph: Optional[str] parameter.
     • Forward this to backend implementations that support named graphs.
     • For backends that do not support named graphs, safely ignore the parameter while keeping behavior unchanged.

3. Update QueryEngine for named graphs

   • In triplet_store/query_engine.py:
     • Allow execute_query to accept graph / graphs options.
     • When provided, add appropriate FROM and FROM NAMED clauses to SPARQL queries.

4. Graph store integration

   • In graph_store backend implementations:
     • Where backend supports graph namespaces (e.g. Neo4j labels, AGE schemas), map from graph URIs to native constructs.
     • Ensure APIs can route operations to a specific logical graph when requested.

5. Change management and lineage

   • In change_management/version_storage.py and ontology_version_manager.py:
     • Link version IDs and tiers to the named graph URIs they live in.
     • This enables version‑aware queries and rollbacks per graph.

6. Documentation

   • Update docs/reference/triplet_store.md and graph_store.md:
     • Include examples for:
       • Writing data into a named graph.
       • Querying one or more named graphs.
   • Extend docs/reference/change_management.md with a short section on:
     • “Named Graphs for Environments and Versions”.

---

Acceptance Criteria

• Core TripletStore and QueryEngine APIs accept optional graph identifiers.
• At least one supported backend correctly isolates data per named graph.
• Change management can associate versions with specific graph URIs.
• Tests prove:
  • Data written to graph A does not appear in graph B unless explicitly queried.
  • Default behavior remains unchanged for existing code that does not pass graph parameters.
• Documentation clearly explains how to configure and use named graphs in Semantica.