[FEATURE] SPARQL CONSTRUCT Templates

[KaifAhmad1]

Define reusable SPARQL CONSTRUCT templates to generate inferred or transformed knowledge graphs using Semantica’s existing query and pipeline engines.

---

Repository Map

• Core logic for this feature lives in:
  • semantica/triplet_store/ (SPARQL execution and graph writes).
  • semantica/pipeline/ (template registration and pipeline steps).
• Tests should be added to existing folders:
  • tests/triplet_store/
  • tests/pipeline/
• All changes stay within semantica/ and tests/; no new top‑level modules.

---

What the Templates Enable

• Lets users define named SPARQL CONSTRUCT templates with parameters.
• Executes templates through the existing SPARQL query engine.
• Writes results into existing graph or triplet stores (including named graphs).
• Integrates with the pipeline engine so templates can run on schedules or as part of larger workflows.

---

Why This Belongs in Semantica

• Automates reasoning and enrichment pipelines.
• Encodes business rules as declarative graph transformations.
• Reduces copy‑paste SPARQL in notebooks, scripts, or one‑off jobs.
• Strengthens Semantica’s positioning as a decision‑intelligence platform, not just storage.

---

Capabilities Already Implemented

Existing capabilities we will reuse for templates:

• SPARQL and triplet store
  • semantica/triplet_store/query_engine.py
    • General SPARQL execution, optimization, and caching.
  • semantica/triplet_store/triplet_store.py
    • Backend‑agnostic triple operations and graph writes.
  • semantica/triplet_store/config.py
    • Configuration for SPARQL/triplet backends.
• Pipeline and orchestration
  • semantica/pipeline/pipeline_builder.py
  • semantica/pipeline/execution_engine.py
  • semantica/pipeline/pipeline_templates.py
  • semantica/pipeline/pipeline_validator.py
• Docs and tests
  • docs/reference/triplet_store.md
  • docs/reference/pipeline.md
  • tests/triplet_store/test_triplet_store.py
  • tests/pipeline/test_pipeline.py
  • tests/pipeline/test_pipeline_comprehensive.py

---

Additional Functionality to Build

SPARQL CONSTRUCT templates should sit on top of the existing modules:

• Template configuration model
  • In semantica/pipeline/pipeline_templates.py:
    • Define a template object (name, description, construct_query, parameters).
• Parameter substitution and safety
  • In semantica/triplet_store/query_engine.py:
    • Implement render_construct_template(template, params) with strict typing and escaping.
• Template execution
  • In semantica/triplet_store/query_engine.py:
    • Implement execute_construct_template(template, params, store_backend, target_graph=None) using existing execution and triplet_store APIs.
• Pipeline step integration
  • In semantica/pipeline/pipeline_builder.py and execution_engine.py:
    • Add a construct_template step type that:
      • Resolves the template.
      • Executes it via the new helper.
      • Writes to the target graph.
• Validation
  • In semantica/pipeline/pipeline_validator.py:
    • Validate references to templates and parameter schemas.
• Documentation and tests
  • Extend docs and tests listed above with:
    • Concrete examples of templates.
    • An end‑to‑end pipeline test that uses a template.

---

How to Implement This Feature

1. Template configuration model

   • In pipeline/pipeline_templates.py:
     • Define a configuration schema or dataclass for:
       • name, description
       • construct_query: SPARQL CONSTRUCT string with parameter placeholders
       • parameters: list of parameter descriptors (name, type, default).
     • Store instances using the same mechanism used for other pipeline templates.

2. Parameter substitution and safety

   • In triplet_store/query_engine.py:
     • Implement a helper, e.g. render_construct_template(template, params).
     • Ensure:
       • Only well‑typed parameters are substituted.
       • URIs and literals are escaped or validated to prevent injection issues.

3. Template execution

   • In query_engine.py:
     • Add a method execute_construct_template(template, params, store_backend, target_graph=None).
     • Logic:
       • Render the query using the helper.
       • Execute it on the backend via existing SPARQL execution.
       • Write results into target_graph using triplet_store.TripletStore APIs.

4. Pipeline step type

   • In pipeline/pipeline_builder.py and execution_engine.py:
     • Add a new step kind, for example type="construct_template".
     • Step configuration should reference:
       • template name
       • parameter values
       • target graph or dataset
     • Execution should call execute_construct_template and log metrics.

5. Validation

   • In pipeline/pipeline_validator.py:
     • Validate that:
       • Referenced templates exist.
       • Required parameters are provided and of correct type.

6. Documentation

   • In docs/reference/triplet_store.md and docs/reference/pipeline.md:
     • Add a “SPARQL CONSTRUCT Templates” section with:
       • Example template definition.
       • Example pipeline configuration.
       • How to run templates ad‑hoc vs scheduled.

---

Completion Checklist

• Contributors can define templates in configuration (Python or YAML) that:
  • Are discoverable by the pipeline engine.
  • Run via QueryEngine and TripletStore.
• At least one end‑to‑end test shows:
  • Construct template → pipeline step → target graph populated.
• Documentation clearly explains how to create and use SPARQL CONSTRUCT templates in Semantica.